@makerx/yoke 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MakerX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,28 @@
-# Temporary Holding Version
+# yoke
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Claude Code skills for MakerX AI-assisted delivery, and the CLI they call.
+
+## Principles
+
+- **User-invoked.** Skills run only when you type their slash command.
+- **Overridable.** A skill of your own with the same name wins.
+- **Lean.** Few skills, short prompts; the CLI enforces the rules.
+
+## Usage
+
+```bash
+npm i -g @makerx/yoke
+
+# then either
+yoke sync          # this repo's .claude/skills
+# or
+yoke sync --user   # ~/.claude/skills
+```
+
+## Skills
+
+- `/pr` raises a PR with a short What/Why/(How) description.
+
+## License
+
+[MIT](LICENSE)

package/dist/cli.js

@@ -0,0 +1,331 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { relative } from "path";
+import { Command } from "commander";
+
+// package.json
+var package_default = {
+  name: "@makerx/yoke",
+  version: "0.2.0",
+  description: "Lean, user-invoked Claude Code skills for MakerX AI-assisted delivery, plus the CLI they call.",
+  license: "MIT",
+  author: "MakerX",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/MakerXStudio/yoke.git"
+  },
+  bin: {
+    yoke: "./dist/cli.js"
+  },
+  files: [
+    "dist"
+  ],
+  type: "module",
+  publishConfig: {
+    access: "public"
+  },
+  scripts: {
+    build: "tsup",
+    test: "vitest run",
+    "test:ci": "vitest run --reporter=default --reporter=junit --outputFile=test-results.xml",
+    verify: "verifyx",
+    "verify:lint": "verifyx lint",
+    "verify:format": "verifyx format",
+    "verify:check-types": "verifyx check-types",
+    "verify:unused-code": "verifyx unused-code",
+    "verify:complexity": 'verifyx complexity "src/**/*.ts"',
+    "verify:comments": "verifyx comments",
+    "verify:github-actions": "verifyx github-actions",
+    prepublishOnly: "npm run build"
+  },
+  dependencies: {
+    commander: "^15.0.0"
+  },
+  devDependencies: {
+    "@makerx/verify": "^1.3.0",
+    "@types/node": "^24.0.0",
+    knip: "^6.42.1",
+    oxfmt: "^0.74.0",
+    oxlint: "^1.89.0",
+    "oxlint-tsgolint": "^7.0.2004",
+    tsup: "^9.0.0",
+    typescript: "^6.0.3",
+    vitest: "^5.0.5"
+  },
+  engines: {
+    node: ">=24"
+  }
+};
+
+// src/features/pr/guide.ts
+var raiseGuide = `
+Compose a short PR in the format below, get the user's approval in the terminal, push, then create it as a draft with \`yoke pr raise\`, which rejects a title or body that breaks the rules.
+
+Preconditions
+
+- Working tree clean, every change committed. If not, stop and say what is uncommitted.
+- Branch is not the default branch.
+- \`gh pr view\` reports no PR for the branch. If one exists, do not create another: propose edits to the existing title and body and apply them with \`gh pr edit\` after the same approval step.
+
+Body
+
+Use exactly these sections, in this order, with these headings. Never add a section and never rename one: no \`## Summary\`, no \`## Changes\`, no \`## Test plan\`.
+
+Closes #<issue number>
+
+## What
+
+<2\u20133 sentences>
+
+## Why
+
+<1\u20132 sentences>
+
+Then, only if earned: \`## How\` (1\u20132 sentences).
+
+Closes line. If the session or branch name gives an issue number, make it the first line, written \`Closes #123\` for a same-repo issue or \`Closes owner/repo#123\` for a cross-repo one. One \`Closes\` per issue. Nothing else goes above \`## What\`.
+
+One section, one question.
+
+  What  what is observably different for a user or caller. Never function, file or component names, or how it is built.
+  Why   the problem that made the change worth doing. Never mechanism.
+  How   a non-obvious decision the diff cannot explain: a trade-off, a workaround, a rejected obvious approach. Never a walkthrough of the diff or a restatement of What.
+
+Litmus for mechanism: a sentence with "by \u2026ing", "so that it can", "because the X uses", or the name of an internal component, function or file belongs in How, and probably does not belong at all.
+
+Brevity budget. Hard caps enforced by \`yoke pr raise\`: What 300 characters, Why 200, How 250, and 600 across all sections. Ceilings, not targets. Prefer deleting a sentence to shortening it.
+
+No per-file lists. Never list changes file by file; the diff already shows that.
+
+Register. Write like a commit message. Short declarative sentences, present tense, active voice. Cut "this change", "in order to", "it is worth noting", hedges and adverbs.
+
+  Wordy: This change introduces a confirmation step so that users are able to cancel before their results are reset.
+  Terse: Retake asks for confirmation before resetting results.
+
+Prose, not bullets. Bullets only for 3 or more genuinely parallel items, and never in What.
+
+Backticks around symbols, commands and flags.
+
+The title and body never mention Claude, AI assistance or attribution. No \`Co-Authored-By\` or "Generated with" anywhere.
+
+Title
+
+One line, at most 70 characters, conventional-commit prefix as the repo uses (\`fix(scope): \u2026\`, \`feat(scope): \u2026\`, \`chore: \u2026\`). Says what changed for the user, not what files moved.
+
+Approval
+
+Mandatory in every permission mode, including auto-accept and bypass. Write the full title and body verbatim in your visible reply. Then call \`AskUserQuestion\` with an approve option whose \`preview\` holds the complete title and body, plus a revise option. Approval covers the push as well as the create. On revise, redraft and ask again.
+
+Create
+
+git push -u origin HEAD
+yoke pr raise --title "<title>" --body "$(cat <<'EOF'
+<body>
+EOF
+)"
+
+Always a draft; the user marks it ready for review themselves. If \`yoke pr raise\` rejects the description, it names each rule that failed: fix those, show the revised description, and get approval again before rerunning. On success it prints the PR URL; report it.
+`;
+
+// src/features/pr/raise.ts
+import { execFileSync } from "child_process";
+
+// src/features/pr/validate.ts
+var limits = {
+  title: 70,
+  body: 600,
+  sections: { What: 300, Why: 200, How: 250 }
+};
+var sectionOrder = ["What", "Why", "How"];
+var requiredSections = ["What", "Why"];
+var perFileListThreshold = 2;
+var headingPattern = /^(#{1,6})\s+(.+?)\s*#*\s*$/;
+var fencePattern = /^\s*(```|~~~)/;
+var closesPattern = /^(closes|fixes|resolves)\s+\S*#\d+\s*$/i;
+var listItemPattern = /^\s*(?:[-*+]|\d+[.)])\s+(.*)$/;
+var fileExtensions = "ts|tsx|js|jsx|mjs|cjs|json|md|mdx|ya?ml|toml|css|scss|html|py|go|rs|cs|csproj|sln|java|kt|sh|ps1|sql|txt|lock|xml|svg";
+var filePathPattern = new RegExp(`(?:^|[\\s\`(])(?:[\\w.-]+/)*[\\w-][\\w.-]*\\.(?:${fileExtensions})(?=$|[\\s\`:,.)])`);
+function validateTitle(title) {
+  const trimmed = title.trim();
+  if (!trimmed) return [{ rule: "title-required", message: "Title is empty." }];
+  const violations = [];
+  if (/[\r\n]/.test(trimmed)) violations.push({ rule: "title-single-line", message: "Title must be a single line." });
+  if (trimmed.length > limits.title)
+    violations.push({ rule: "title-length", message: `Title is ${trimmed.length} characters; the cap is ${limits.title}.` });
+  return violations;
+}
+function parseBody(body) {
+  const preamble = [];
+  const sections = [];
+  let inFence = false;
+  for (const line of body.split(/\r?\n/)) {
+    if (fencePattern.test(line)) inFence = !inFence;
+    const heading = inFence ? null : headingPattern.exec(line);
+    if (heading?.[1] && heading[2]) {
+      sections.push({ name: heading[2], level: heading[1].length, content: "" });
+      continue;
+    }
+    const current = sections.at(-1);
+    if (current) current.content += `${line}
+`;
+    else preamble.push(line);
+  }
+  for (const section of sections) section.content = section.content.trim();
+  return { preamble: preamble.join("\n").trim(), sections };
+}
+function isKnownSection(section) {
+  return section.level === 2 && sectionOrder.includes(section.name);
+}
+function checkPreamble(preamble) {
+  const stray = preamble.split("\n").filter((line) => line.trim() && !closesPattern.test(line.trim()));
+  if (!stray.length) return [];
+  return [{ rule: "preamble", message: "Only `Closes #<issue>` lines may come before `## What`." }];
+}
+function checkStructure(sections) {
+  const violations = [];
+  for (const section of sections.filter((s) => !isKnownSection(s)))
+    violations.push({
+      rule: "unknown-section",
+      message: `Heading "${"#".repeat(section.level)} ${section.name}" is not allowed; use only ## What, ## Why and optionally ## How.`
+    });
+  const known = sections.filter(isKnownSection);
+  for (const name of requiredSections)
+    if (!known.find((s) => s.name === name)?.content)
+      violations.push({ rule: `${name.toLowerCase()}-required`, message: `Body needs a non-empty "## ${name}" section.` });
+  const names = known.map((s) => s.name);
+  const duplicates = [...new Set(names.filter((name, i) => names.indexOf(name) !== i))];
+  for (const name of duplicates) violations.push({ rule: "duplicate-section", message: `"## ${name}" appears more than once.` });
+  const indexes = names.map((name) => sectionOrder.indexOf(name));
+  if (!duplicates.length && indexes.some((index, i) => i > 0 && index < (indexes[i - 1] ?? 0)))
+    violations.push({ rule: "section-order", message: "Sections must be in the order What, Why, How." });
+  return violations;
+}
+function checkLengths(sections) {
+  const violations = [];
+  let total = 0;
+  for (const section of sections) {
+    total += section.content.length;
+    if (!isKnownSection(section)) continue;
+    const cap = limits.sections[section.name];
+    if (section.content.length > cap)
+      violations.push({
+        rule: "section-length",
+        message: `"## ${section.name}" is ${section.content.length} characters; the cap is ${cap}.`
+      });
+  }
+  if (total > limits.body)
+    violations.push({ rule: "body-length", message: `Body sections total ${total} characters; the cap is ${limits.body}.` });
+  return violations;
+}
+function checkPerFileList(body) {
+  const fileItems = body.split(/\r?\n/).map((line) => listItemPattern.exec(line)?.[1]).filter((item) => item !== void 0 && filePathPattern.test(item));
+  if (fileItems.length < perFileListThreshold) return [];
+  return [{ rule: "per-file-list", message: "Body lists changes per file; the diff already shows that. Describe the change instead." }];
+}
+function validateBody(body) {
+  const { preamble, sections } = parseBody(body);
+  return [...checkPreamble(preamble), ...checkStructure(sections), ...checkLengths(sections), ...checkPerFileList(body)];
+}
+function validatePr(title, body) {
+  return [...validateTitle(title), ...validateBody(body)];
+}
+
+// src/features/pr/raise.ts
+var PrValidationError = class extends Error {
+  constructor(violations) {
+    super(["PR description rejected:", ...violations.map((v) => `  \u2717 ${v.rule}: ${v.message}`)].join("\n"));
+    this.violations = violations;
+    this.name = "PrValidationError";
+  }
+  violations;
+};
+var runGh = (args) => execFileSync("gh", args, { encoding: "utf8", stdio: ["ignore", "pipe", "inherit"] });
+function raisePr({ title, body, base, draft }, run = runGh) {
+  const violations = validatePr(title, body);
+  if (violations.length) throw new PrValidationError(violations);
+  const args = ["pr", "create", "--title", title.trim(), "--body", body.trim()];
+  if (base) args.push("--base", base);
+  if (draft) args.push("--draft");
+  const output = run(args).trim().split("\n");
+  return output.at(-1) ?? "";
+}
+
+// src/features/sync/sync.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+// src/skill.ts
+var ownerMarker = 'owner: "@makerx/yoke"';
+function renderSkill({ name, description, body }) {
+  return [
+    "---",
+    `name: ${name}`,
+    `description: ${description}`,
+    "disable-model-invocation: true",
+    "metadata:",
+    `  ${ownerMarker}`,
+    "---",
+    "",
+    body.trim(),
+    ""
+  ].join("\n");
+}
+
+// src/features/pr/skill.ts
+var prSkill = {
+  name: "pr",
+  description: "Raise a PR with a concise What/Why/(How) description",
+  body: `
+Run \`yoke pr raise --help\` and follow it exactly. Do not use \`gh pr create\`.
+
+If \`yoke\` is not on PATH, stop and tell the user to run \`npm i -g @makerx/yoke\`.
+`
+};
+
+// src/features/sync/sync.ts
+var bundledSkills = [prSkill];
+function skillsRoot(user, cwd = process.cwd(), home = homedir()) {
+  return join(user ? home : cwd, ".claude", "skills");
+}
+function isOwnedByUser(skillFile) {
+  return existsSync(skillFile) && !readFileSync(skillFile, "utf8").includes(ownerMarker);
+}
+function syncSkills(destination, skills = bundledSkills) {
+  const result = { written: [], skipped: [] };
+  for (const skill of skills) {
+    const target = join(destination, skill.name);
+    const skillFile = join(target, "SKILL.md");
+    if (isOwnedByUser(skillFile)) {
+      result.skipped.push(target);
+      continue;
+    }
+    mkdirSync(target, { recursive: true });
+    writeFileSync(skillFile, renderSkill(skill));
+    result.written.push(skillFile);
+  }
+  return result;
+}
+
+// src/cli.ts
+var { version } = package_default;
+var program = new Command("yoke").description("Lean, user-invoked Claude Code skills and the CLI they call.").version(version);
+program.command("sync").description("Write yoke's skills into this repo's .claude/skills, or ~/.claude/skills with --user").option("--user", "write to ~/.claude/skills instead, for every repo").action((options) => {
+  const user = options.user ?? false;
+  const display = (path) => user ? path : relative(process.cwd(), path);
+  const { written, skipped } = syncSkills(skillsRoot(user));
+  for (const file of written) console.log(`wrote ${display(file)}`);
+  for (const dir of skipped) console.log(`skipped ${display(dir)} (your own skill; delete it to take yoke's)`);
+});
+var pr = program.command("pr").description("Pull request commands");
+pr.command("raise").description("Validate a PR title and body, then create the PR with gh").requiredOption("--title <title>", "single-line PR title").requiredOption("--body <body>", "PR body with ## What, ## Why and optionally ## How").option("--base <branch>", "base branch (defaults to the repo default)").option("--no-draft", "create a ready-for-review PR instead of a draft").addHelpText("after", raiseGuide).action((options) => {
+  try {
+    console.log(raisePr(options));
+  } catch (error) {
+    if (!(error instanceof PrValidationError)) throw error;
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+});
+program.parse();

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@makerx/yoke",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Lean, user-invoked Claude Code skills for MakerX AI-assisted delivery, plus the CLI they call.",
+  "license": "MIT",
+  "author": "MakerX",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MakerXStudio/yoke.git"
+  },
+  "bin": {
+    "yoke": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:ci": "vitest run --reporter=default --reporter=junit --outputFile=test-results.xml",
+    "verify": "verifyx",
+    "verify:lint": "verifyx lint",
+    "verify:format": "verifyx format",
+    "verify:check-types": "verifyx check-types",
+    "verify:unused-code": "verifyx unused-code",
+    "verify:complexity": "verifyx complexity \"src/**/*.ts\"",
+    "verify:comments": "verifyx comments",
+    "verify:github-actions": "verifyx github-actions",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "commander": "^15.0.0"
+  },
+  "devDependencies": {
+    "@makerx/verify": "^1.3.0",
+    "@types/node": "^24.0.0",
+    "knip": "^6.42.1",
+    "oxfmt": "^0.74.0",
+    "oxlint": "^1.89.0",
+    "oxlint-tsgolint": "^7.0.2004",
+    "tsup": "^9.0.0",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.5"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}