create-yss-spec 1.0.0

package/README.md

@@ -0,0 +1,41 @@
+# create-yss-spec
+
+用于初始化 `yss-spec-project-template` 模板实例仓库的 npm CLI。
+
+## 用法
+
+```bash
+npm create yss-spec@latest
+```
+
+也可以使用 `npx`：
+
+```bash
+npx create-yss-spec@latest
+```
+
+## 当前支持
+
+- 交互式收集 `projectName`、`businessDomain`、`targetDir`
+- `--team-size`
+- `--dry-run`
+- 非空目录默认拒绝，`--force` 覆盖
+- `--git-init`
+- `--issue-tracker github|gitlab`
+- `--include-example-docs`
+- `--no-example-docs`
+
+## 开发验证
+
+在仓库根目录执行：
+
+```bash
+npm test
+```
+
+发布前可检查打包结果：
+
+```bash
+cd packages/create-yss-spec
+npm pack --dry-run
+```

package/bin/create-yss-spec.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+const { runCli } = require("../src/cli");
+
+(async () => {
+  await runCli(process.argv.slice(2));
+})().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "create-yss-spec",
+  "version": "1.0.0",
+  "description": "Initialize a YSS spec project template repository",
+  "files": [
+    "bin",
+    "src",
+    "template",
+    "template.manifest.json"
+  ],
+  "bin": {
+    "create-yss-spec": "./bin/create-yss-spec.js"
+  },
+  "scripts": {
+    "prepack": "node ../../scripts/sync-cli-template.js"
+  }
+}

package/src/cli.js

@@ -0,0 +1,443 @@
+const fs = require("node:fs");
+const path = require("node:path");
+const readline = require("node:readline/promises");
+const { spawnSync } = require("node:child_process");
+
+const PACKAGE_ROOT = path.resolve(__dirname, "..");
+const BUNDLED_TEMPLATE_ROOT = path.join(PACKAGE_ROOT, "template");
+const REPO_TEMPLATE_ROOT = path.resolve(PACKAGE_ROOT, "../..");
+const REPO_MANIFEST_PATH = path.join(REPO_TEMPLATE_ROOT, "template.manifest.json");
+const BUNDLED_MANIFEST_PATH = path.join(PACKAGE_ROOT, "template.manifest.json");
+const IS_REPO_DEVELOPMENT =
+  fs.existsSync(path.join(REPO_TEMPLATE_ROOT, "AGENTS.md")) &&
+  fs.existsSync(REPO_MANIFEST_PATH);
+const TEMPLATE_ROOT = IS_REPO_DEVELOPMENT
+  ? REPO_TEMPLATE_ROOT
+  : BUNDLED_TEMPLATE_ROOT;
+const TEMPLATE_MANIFEST_PATH = IS_REPO_DEVELOPMENT
+  ? REPO_MANIFEST_PATH
+  : BUNDLED_MANIFEST_PATH;
+const TEMPLATE_MANIFEST = JSON.parse(
+  fs.readFileSync(TEMPLATE_MANIFEST_PATH, "utf8"),
+);
+const ROOT_EXCLUDED_ENTRIES = new Set(TEMPLATE_MANIFEST.excludeRootEntries);
+const ROOT_EXCLUDED_FILES = new Set(TEMPLATE_MANIFEST.excludeRootFiles);
+const EXCLUDED_RELATIVE_PATHS = new Set(TEMPLATE_MANIFEST.excludePaths);
+const RENDERED_RELATIVE_PATHS = new Set(TEMPLATE_MANIFEST.renderPaths);
+const EXAMPLE_DOC_PATHS = new Set(TEMPLATE_MANIFEST.exampleDocPaths);
+const REPO_TRACKED_STATE = IS_REPO_DEVELOPMENT
+  ? loadRepoTrackedState(REPO_TEMPLATE_ROOT)
+  : null;
+
+function loadRepoTrackedState(repoRoot) {
+  const result = spawnSync("git", ["ls-files"], {
+    cwd: repoRoot,
+    encoding: "utf8",
+  });
+
+  if (result.status !== 0) {
+    return null;
+  }
+
+  const files = new Set();
+  const directories = new Set();
+
+  for (const entry of result.stdout.split(/\r?\n/)) {
+    if (!entry) {
+      continue;
+    }
+
+    const normalizedEntry = entry.split(path.sep).join("/");
+    files.add(normalizedEntry);
+
+    const segments = normalizedEntry.split("/");
+    segments.pop();
+
+    let current = "";
+    for (const segment of segments) {
+      current = current ? `${current}/${segment}` : segment;
+      directories.add(current);
+    }
+  }
+
+  return {
+    files,
+    directories,
+  };
+}
+
+function parseArgs(argv) {
+  const options = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const current = argv[index];
+    const next = argv[index + 1];
+
+    if (current === "--project-name" && next) {
+      options.projectName = next;
+      index += 1;
+    } else if (current === "--business-domain" && next) {
+      options.businessDomain = next;
+      index += 1;
+    } else if (current === "--team-size" && next) {
+      options.teamSize = next;
+      index += 1;
+    } else if (current === "--target-dir" && next) {
+      options.targetDir = next;
+      index += 1;
+    } else if (current === "--issue-tracker" && next) {
+      options.issueTracker = next;
+      index += 1;
+    } else if (current === "--dry-run") {
+      options.dryRun = true;
+    } else if (current === "--force") {
+      options.force = true;
+    } else if (current === "--git-init") {
+      options.gitInit = true;
+    } else if (current === "--include-example-docs") {
+      options.includeExampleDocs = true;
+    } else if (current === "--no-example-docs") {
+      options.includeExampleDocs = false;
+    }
+  }
+
+  return options;
+}
+
+async function promptForMissingOptions(options) {
+  if (!process.stdin.isTTY) {
+    return promptFromBufferedInput(options);
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  try {
+    const projectName =
+      options.projectName || (await rl.question("项目名称: ")).trim();
+    const businessDomain =
+      options.businessDomain || (await rl.question("业务领域: ")).trim();
+    const teamSizeInput =
+      options.teamSize !== undefined
+        ? options.teamSize
+        : await rl.question("团队规模（可留空）: ");
+    const targetDir =
+      options.targetDir || (await rl.question("目标目录: ")).trim();
+
+    return {
+      projectName,
+      businessDomain,
+      teamSize: (teamSizeInput || "").trim() || "待补充",
+      targetDir,
+      issueTracker: options.issueTracker || "github",
+      dryRun: Boolean(options.dryRun),
+      force: Boolean(options.force),
+      gitInit: Boolean(options.gitInit),
+      includeExampleDocs:
+        options.includeExampleDocs === undefined
+          ? true
+          : Boolean(options.includeExampleDocs),
+    };
+  } finally {
+    rl.close();
+  }
+}
+
+async function promptFromBufferedInput(options) {
+  const chunks = [];
+
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+
+  const answers = Buffer.concat(chunks)
+    .toString("utf8")
+    .split(/\r?\n/);
+  let answerIndex = 0;
+  const ask = (label) => {
+    process.stdout.write(`${label}: `);
+    const value = answers[answerIndex] ?? "";
+    answerIndex += 1;
+    return value.trim();
+  };
+
+  const projectName = options.projectName || ask("项目名称");
+  const businessDomain = options.businessDomain || ask("业务领域");
+  const teamSizeInput =
+    options.teamSize !== undefined ? options.teamSize : ask("团队规模（可留空）");
+  const targetDir = options.targetDir || ask("目标目录");
+
+  return {
+    projectName,
+    businessDomain,
+    teamSize: teamSizeInput || "待补充",
+    targetDir,
+    issueTracker: options.issueTracker || "github",
+    dryRun: Boolean(options.dryRun),
+    force: Boolean(options.force),
+    gitInit: Boolean(options.gitInit),
+    includeExampleDocs:
+      options.includeExampleDocs === undefined
+        ? true
+        : Boolean(options.includeExampleDocs),
+  };
+}
+
+function assertRequiredOptions(options) {
+  if (!options.projectName) {
+    throw new Error("项目名称不能为空");
+  }
+
+  if (!options.businessDomain) {
+    throw new Error("业务领域不能为空");
+  }
+
+  if (!options.targetDir) {
+    throw new Error("目标目录不能为空");
+  }
+}
+
+function normalizeTargetDir(targetDir) {
+  return path.resolve(process.cwd(), targetDir);
+}
+
+function isInsideTemplateRoot(targetDir) {
+  const relativePath = path.relative(TEMPLATE_ROOT, targetDir);
+  return (
+    relativePath === "" ||
+    (!relativePath.startsWith("..") && !path.isAbsolute(relativePath))
+  );
+}
+
+function shouldExcludeRelativePath(relativePath) {
+  const normalizedPath = relativePath.split(path.sep).join("/");
+  return EXCLUDED_RELATIVE_PATHS.has(normalizedPath);
+}
+
+function shouldSkipRootEntry(entryName) {
+  return (
+    ROOT_EXCLUDED_ENTRIES.has(entryName) || ROOT_EXCLUDED_FILES.has(entryName)
+  );
+}
+
+function shouldSkipRepoDevelopmentPath(relativePath, isDirectory) {
+  if (!REPO_TRACKED_STATE) {
+    return false;
+  }
+
+  const normalizedPath = relativePath.split(path.sep).join("/");
+
+  if (isDirectory) {
+    return !REPO_TRACKED_STATE.directories.has(normalizedPath);
+  }
+
+  return !REPO_TRACKED_STATE.files.has(normalizedPath);
+}
+
+function renderTemplateFile(relativePath, content, variables) {
+  if (relativePath === "AGENTS.md") {
+    return content
+      .replace(/(\*\*项目名称：\*\*\s*)\[填写\]/, `$1${variables.projectName}`)
+      .replace(
+        /(\*\*业务领域：\*\*\s*)\[填写\]/,
+        `$1${variables.businessDomain}`,
+      )
+      .replace(/(\*\*团队规模：\*\*\s*)\[填写\]/, `$1${variables.teamSize}`);
+  }
+
+  if (relativePath === "README.md") {
+    return content
+      .replace(/^# YSS Spec Project Template/m, `# ${variables.projectName}`)
+      .replace(
+        /^> Matt Pocock Engineering Skills/m,
+        `> 默认 Issue Tracker：${variables.issueTracker}\n>\n> Matt Pocock Engineering Skills`,
+      );
+  }
+
+  return content;
+}
+
+function buildCopyPlan(sourceDir, targetDir, variables, relativeDir = "") {
+  const operations = [];
+  const entries = fs.readdirSync(sourceDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!relativeDir && shouldSkipRootEntry(entry.name)) {
+      continue;
+    }
+
+    const relativePath = relativeDir
+      ? path.posix.join(relativeDir, entry.name)
+      : entry.name;
+
+    if (shouldSkipRepoDevelopmentPath(relativePath, entry.isDirectory())) {
+      continue;
+    }
+
+    if (shouldExcludeRelativePath(relativePath)) {
+      continue;
+    }
+
+    if (!variables.includeExampleDocs && EXAMPLE_DOC_PATHS.has(relativePath)) {
+      continue;
+    }
+
+    const sourcePath = path.join(sourceDir, entry.name);
+    const targetPath = path.join(targetDir, entry.name);
+
+    if (entry.isDirectory()) {
+      operations.push({
+        type: "mkdir",
+        relativePath,
+        targetPath,
+      });
+      operations.push(
+        ...buildCopyPlan(sourcePath, targetPath, variables, relativePath),
+      );
+      continue;
+    }
+
+    if (!entry.isFile()) {
+      continue;
+    }
+
+    if (RENDERED_RELATIVE_PATHS.has(relativePath)) {
+      operations.push({
+        type: "render",
+        relativePath,
+        sourcePath,
+        targetPath,
+      });
+      continue;
+    }
+
+    operations.push({
+      type: "copy",
+      relativePath,
+      sourcePath,
+      targetPath,
+    });
+  }
+
+  return operations;
+}
+
+function printDryRun(operations, targetDir) {
+  console.log("dry-run 预览");
+  console.log(`输出目录：${targetDir}`);
+
+  for (const operation of operations) {
+    console.log(`${operation.type}: ${operation.relativePath}`);
+  }
+}
+
+function inspectTargetDir(targetDir, force) {
+  if (isInsideTemplateRoot(targetDir)) {
+    throw new Error("目标目录不能位于模板源仓库内部");
+  }
+
+  if (!fs.existsSync(targetDir)) {
+    return {
+      exists: false,
+      clearEntries: false,
+    };
+  }
+
+  const entries = fs.readdirSync(targetDir);
+  if (entries.length > 0 && !force) {
+    throw new Error("目标目录非空，当前主路径不支持覆盖已有内容");
+  }
+
+  return {
+    exists: true,
+    clearEntries: entries.length > 0 && force,
+  };
+}
+
+function prepareTargetDir(targetDir, targetState) {
+  if (!targetState.exists) {
+    fs.mkdirSync(targetDir, { recursive: true });
+    return;
+  }
+
+  if (!targetState.clearEntries) {
+    return;
+  }
+
+  for (const entry of fs.readdirSync(targetDir)) {
+    fs.rmSync(path.join(targetDir, entry), { recursive: true, force: true });
+  }
+}
+
+function executePlan(operations, variables) {
+  for (const operation of operations) {
+    if (operation.type === "mkdir") {
+      fs.mkdirSync(operation.targetPath, { recursive: true });
+      continue;
+    }
+
+    if (operation.type === "render") {
+      const renderedContent = renderTemplateFile(
+        operation.relativePath,
+        fs.readFileSync(operation.sourcePath, "utf8"),
+        variables,
+      );
+      fs.mkdirSync(path.dirname(operation.targetPath), { recursive: true });
+      fs.writeFileSync(operation.targetPath, renderedContent, "utf8");
+      continue;
+    }
+
+    fs.mkdirSync(path.dirname(operation.targetPath), { recursive: true });
+    fs.copyFileSync(operation.sourcePath, operation.targetPath);
+  }
+}
+
+function initializeGitRepository(targetDir) {
+  const result = spawnSync("git", ["init"], {
+    cwd: targetDir,
+    encoding: "utf8",
+  });
+
+  if (result.status !== 0) {
+    throw new Error(result.stderr.trim() || "git init 执行失败");
+  }
+}
+
+async function runCli(argv = []) {
+  const promptedOptions = await promptForMissingOptions(parseArgs(argv));
+  assertRequiredOptions(promptedOptions);
+
+  const targetDir = normalizeTargetDir(promptedOptions.targetDir);
+  const targetState = inspectTargetDir(targetDir, promptedOptions.force);
+
+  const operations = buildCopyPlan(TEMPLATE_ROOT, targetDir, promptedOptions);
+
+  if (promptedOptions.dryRun) {
+    printDryRun(operations, targetDir);
+    return;
+  }
+
+  prepareTargetDir(targetDir, targetState);
+  executePlan(operations, promptedOptions);
+
+  if (promptedOptions.gitInit) {
+    initializeGitRepository(targetDir);
+  }
+
+  console.log("初始化完成");
+  console.log(`输出目录：${targetDir}`);
+  console.log("下一步建议：");
+  console.log(`1. cd ${targetDir}`);
+  console.log(
+    promptedOptions.gitInit
+      ? "2. 运行 git status 检查初始化结果"
+      : "2. 如需版本管理，可执行 git init",
+  );
+  console.log("3. 检查 AGENTS.md、README 和 docs 目录是否符合预期");
+}
+
+module.exports = {
+  runCli,
+};

package/template/.agent/skills/ask-matt/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: ask-matt
+description: Ask which skill or flow fits your situation. A router over the skills in this repo.
+disable-model-invocation: true
+---
+
+# Ask Matt
+
+You don't remember every skill, so ask.
+
+A **flow** is a path through the skills. Most paths run along one **main flow**, and two **on-ramps** merge onto it. Everything else is standalone, or a vocabulary layer that runs underneath.
+
+## The main flow: idea → ship
+
+The route most work travels. You have an idea and want it built.
+
+1. **`/grill-with-docs`** — sharpen the idea by interview. Start here when you **have a codebase**: it's stateful, retaining what it learns in `CONTEXT.md` and ADRs. (No codebase? Use `/grill-me` — see Standalone. Both run the same `/grilling` primitive; `grill-with-docs` is the one that leaves a paper trail.)
+2. **Branch — can you settle every question in conversation?** If a question needs a runnable answer (state, business logic, a UI you have to see), detour through a prototype, bridged by **`/handoff`** in both directions (see Crossing sessions):
+   - **`/handoff`** out, then open a fresh session against that file,
+   - **`/prototype`** to answer the question with throwaway code,
+   - **`/handoff`** back what you learned, and reference it from the original idea thread.
+3. **Branch — is this a multi-session build?**
+   - **Yes** → **`/to-prd`** (turn the thread into a PRD) → **`/to-issues`** (split the PRD into independently-grabbable issues). Because the issues are independent, **clear context between each one**: start a fresh session per issue and kick off **`/implement`** by passing it the PRD and the single issue to work on.
+   - **No** → **`/implement`** right here, in the same context window.
+
+   Either way, **`/implement`** builds each issue by driving **`/tdd`** internally — one red-green slice at a time — then closes out by running **`/code-review`**, a two-axis review (Standards + Spec) of the diff, before committing. Reach for **`/tdd`** on its own when you just want to build a concrete behaviour test-first without a full spec, and **`/code-review`** on its own whenever you want to review a branch or PR against a fixed point.
+
+### Context hygiene
+
+Keep steps 1–3 in **one unbroken context window** — don't compact or clear until after `/to-issues` — so the grilling, PRD, and issues all build on the same thinking. Each `/implement` then starts fresh, working from the issue.
+
+The limit on this is the **[smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone)**: the window (~120k tokens on state-of-the-art models) within which the model still reasons sharply. If a session approaches it before `/to-issues`, don't push on degraded — `/handoff` and continue in a fresh thread.
+
+## On-ramps
+
+A starting situation that generates work, then merges onto the main flow.
+
+- **Bugs and requests piling up** → **`/triage`**. It moves issues through triage roles and produces agent-ready issues, which **`/implement`** later picks up.
+
+  Triage is only for issues **you didn't create** — bug reports, incoming feature requests, anything that arrives raw. Issues that `/to-issues` produced are already agent-ready, so **don't triage them**.
+
+- **Something's broken** → **`/diagnosing-bugs`**. For the hard ones: the bug that resists a first glance, the intermittent flake, the regression that crept in between two known-good states. It refuses to theorise until it has a **tight feedback loop** — one command that already goes red on *this* bug — then fixes with a regression test. Its post-mortem hands off to **`/improve-codebase-architecture`** when the real finding is that there's no good seam to lock the bug down.
+
+## Codebase health
+
+Not feature work — upkeep.
+
+- **`/improve-codebase-architecture`** — run whenever you have a spare moment to keep the codebase good for agents to operate in. It surfaces **deepening opportunities**; picking one _generates an idea_ you can take into the main flow at `/grill-with-docs`. It's the survey that finds the candidates; **`/codebase-design`** (below) is the bench you design the chosen one on.
+
+## Vocabulary underneath
+
+Two model-invoked references that run *beneath* the other skills — each the single source of truth for its vocabulary. Reach for them directly when the **words**, not the process, are the problem; or let the skills above pull them in.
+
+- **`/domain-modeling`** — sharpen the project's *domain* language: challenge a fuzzy term, resolve an overloaded word ("account" doing three jobs), record a hard-to-reverse decision as an ADR. It's the active discipline `/grill-with-docs` drives to keep `CONTEXT.md` a clean glossary.
+- **`/codebase-design`** — the deep-module vocabulary (module, interface, depth, seam, adapter, leverage, locality) for designing a module's *shape*: a lot of behaviour behind a small interface at a clean seam. `/tdd` and `/improve-codebase-architecture` both speak it.
+
+## Crossing sessions
+
+- **`/handoff`** — when a thread is full or you need to branch off (e.g. into a `/prototype` session), this compacts the conversation into a markdown file. You don't continue in place — you **open a new session and reference that file** to carry the context across. It's the bridge between context windows, in either direction. Use it when you want a **fresh session** but need the **current conversation preserved**.
+- **`/compact`** (built-in) — stay in the **same conversation**, letting the earlier turns be summarized. Use it at **intentional breaks between phases**, when you don't mind losing the verbatim history. Don't compact mid-phase — the agent can lose its way. `/handoff` forks; `/compact` continues.
+
+## Standalone
+
+Off the main flow entirely.
+
+- **`/grill-me`** — the same relentless interview as `/grill-with-docs`, but for when you have **no codebase**. Stateless: it saves nothing locally, builds no `CONTEXT.md`. Reach for it to sharpen any plan or design that doesn't live in a repo.
+- **`/prototype`** — a small, throwaway program that answers one design question: does this state model feel right, or what should this UI look like. Throwaway from day one — keep the answer, delete the code. It's the detour in step 2 of the main flow, but reach for it any time a design question is hard to settle on paper.
+- **`/research`** — delegate reading legwork to a **background agent**: it investigates a question against **primary sources**, then leaves a cited Markdown file in the repo. Keep working while it reads. The file it produces is something to take *into* the main flow at `/grill-with-docs` — research feeds the thinking, it doesn't replace it.
+- **`/teach`** — learn a concept over multiple sessions, using the current directory as a stateful workspace.
+- **`/writing-great-skills`** — reference for writing and editing skills well.
+
+## Precondition
+
+**`/setup-matt-pocock-skills`** — run before your first engineering flow to configure the issue tracker, triage labels, and doc layout the other skills assume. Custom issue trackers also work.

package/template/.agent/skills/code-review/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: code-review
+description: Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/PRD asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X".
+---
+
+Two-axis review of the diff between `HEAD` and a fixed point the user supplies:
+
+- **Standards** — does the code conform to this repo's documented coding standards?
+- **Spec** — does the code faithfully implement the originating issue / PRD / spec?
+
+Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings.
+
+The issue tracker should have been provided to you — run `/setup-matt-pocock-skills` if `docs/agents/issue-tracker.md` is missing.
+
+## Process
+
+### 1. Pin the fixed point
+
+Whatever the user said is the fixed point — a commit SHA, branch name, tag, `main`, `HEAD~5`, etc. If they didn't specify one, ask for it.
+
+Capture the diff command once: `git diff <fixed-point>...HEAD` (three-dot, so the comparison is against the merge-base). Also note the list of commits via `git log <fixed-point>..HEAD --oneline`.
+
+Before going further, confirm the fixed point resolves (`git rev-parse <fixed-point>`) and the diff is non-empty. A bad ref or empty diff should fail here — not inside two parallel sub-agents.
+
+### 2. Identify the spec source
+
+Look for the originating spec, in this order:
+
+1. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.) — fetch via the workflow in `docs/agents/issue-tracker.md`.
+2. A path the user passed as an argument.
+3. A PRD/spec file under `docs/`, `specs/`, or `.scratch/` matching the branch name or feature.
+4. If nothing is found, ask the user where the spec is. If they say there isn't one, the **Spec** sub-agent will skip and report "no spec available".
+
+### 3. Identify the standards sources
+
+Anything in the repo that documents how code should be written, such as `CODING_STANDARDS.md` or `CONTRIBUTING.md`.
+
+On top of whatever the repo documents, the Standards axis always carries the **smell baseline** below — a fixed set of Fowler code smells (_Refactoring_, ch.3) that applies even when a repo documents nothing. Two rules bind it:
+
+- **The repo overrides.** A documented repo standard always wins; where it endorses something the baseline would flag, suppress the smell.
+- **Always a judgement call.** Each smell is a labelled heuristic ("possible Feature Envy"), never a hard violation — and, like any standard here, skip anything tooling already enforces.
+
+Each smell reads *what it is* → *how to fix*; match it against the diff:
+
+- **Mysterious Name** — a function, variable, or type whose name doesn't reveal what it does or holds. → rename it; if no honest name comes, the design's murky.
+- **Duplicated Code** — the same logic shape appears in more than one hunk or file in the change. → extract the shared shape, call it from both.
+- **Feature Envy** — a method that reaches into another object's data more than its own. → move the method onto the data it envies.
+- **Data Clumps** — the same few fields or params keep travelling together (a type wanting to be born). → bundle them into one type, pass that.
+- **Primitive Obsession** — a primitive or string standing in for a domain concept that deserves its own type. → give the concept its own small type.
+- **Repeated Switches** — the same `switch`/`if`-cascade on the same type recurs across the change. → replace with polymorphism, or one map both sites share.
+- **Shotgun Surgery** — one logical change forces scattered edits across many files in the diff. → gather what changes together into one module.
+- **Divergent Change** — one file or module is edited for several unrelated reasons. → split so each module changes for one reason.
+- **Speculative Generality** — abstraction, parameters, or hooks added for needs the spec doesn't have. → delete it; inline back until a real need shows.
+- **Message Chains** — long `a.b().c().d()` navigation the caller shouldn't depend on. → hide the walk behind one method on the first object.
+- **Middle Man** — a class or function that mostly just delegates onward. → cut it, call the real target direct.
+- **Refused Bequest** — a subclass or implementer that ignores or overrides most of what it inherits. → drop the inheritance, use composition.
+
+### 4. Spawn both sub-agents in parallel
+
+Send a single message with two `Agent` tool calls. Use the `general-purpose` subagent for both.
+
+**Standards sub-agent prompt** — include:
+
+- The full diff command and commit list.
+- The list of standards-source files you found in step 3, **plus the smell baseline from step 3** pasted in full — the sub-agent has no other access to it.
+- The brief: "Report — per file/hunk where relevant — (a) every place the diff violates a documented standard: cite the standard (file + the rule); and (b) any baseline smell you spot: name it and quote the hunk. Distinguish hard violations from judgement calls — documented-standard breaches can be hard, but baseline smells are always judgement calls, and a documented repo standard overrides the baseline. Skip anything tooling enforces. Under 400 words."
+
+**Spec sub-agent prompt** — include:
+
+- The diff command and commit list.
+- The path or fetched contents of the spec.
+- The brief: "Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words."
+
+If the spec is missing, skip the Spec sub-agent and note this in the final report.
+
+### 5. Aggregate
+
+Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings — the two axes are deliberately separate (see _Why two axes_).
+
+End with a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any). Don't pick a single winner across axes — that's the reranking the separation exists to prevent.
+
+## Why two axes
+
+A change can pass one axis and fail the other:
+
+- Code that follows every standard but implements the wrong thing → **Standards pass, Spec fail.**
+- Code that does exactly what the issue asked but breaks the project's conventions → **Spec pass, Standards fail.**
+
+Reporting them separately stops one axis from masking the other.