Release feature-runner and pr-review

.claude/skills/implement-feature/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: implement-feature
+argument-hint: '[slug]'
+description: This skill should be used when the user asks to "implement a feature", "run the Feature Runner", "/implement-feature", "implement all issues for <slug>", or "drain the issue queue overnight". Automates the implementation side of the AI-development cycle for one Feature: creates an isolated worktree and branch, runs /tdd on every ready-for-agent issue in dependency order, and opens a PR when done.
+---
+
+# Implement Feature
+
+Automate the implementation side of the AI-development cycle for one Feature. Takes a slug, creates an isolated branch, runs `/tdd` on every `ready-for-agent` issue in dependency order, and marks each `resolved` on success.
+
+**Invocation:** `/implement-feature [slug]`
+
+## Quick start
+
+- **Named run** — `/implement-feature pr-review-doc-context-enrichment` — targets a specific Feature slug directly; creates a worktree, runs all `ready-for-agent` issues, opens a PR.
+- **Auto-select** — `/implement-feature` with no argument — scans `docs/issues/` and picks the first Feature alphabetically that has at least one `ready-for-agent` issue and no unprepped issues (`needs-triage`, `needs-info`, `needs-specs`). Picks up partial features after a failure fix automatically.
+- **Overnight loop** — `/loop /implement-feature` — drains the queue unattended; the runner emits `LOOP_COMPLETE` when no qualifying Feature remains, which terminates the loop.
+- **Safe to interrupt** — Ctrl+C during any issue leaves that issue at `ready-for-agent`; re-running resumes from the first unresolved issue. Note: a **/tdd failure** (as opposed to a Ctrl+C interrupt) sets the failing issue to `needs-info`, preventing auto-select from retrying until the developer intervenes.
+
+## Steps
+
+### 0. Resolve the slug
+
+**If a slug argument was provided**, use it directly and proceed to step 1.
+
+**If no argument was provided**, scan `docs/issues/` for qualifying features:
+
+1. Use the Bash tool to list immediate subdirectories of `docs/issues/`:
+
+```
+ls -d docs/issues/*/
+```
+
+2. For each subdirectory (potential feature slug), use the Bash tool to list its `NN-*.md` files and use the Read tool to check the `**Status:**` line of each one. A feature **qualifies** if:
+
+   - At least one `NN-*.md` file has status `ready-for-agent`, **and**
+   - Every `NN-*.md` file has a status in `{ready-for-agent, resolved, closed, rejected, ready-for-human}`.
+
+   Any file with status `needs-triage`, `needs-info`, `needs-specs`, or any unrecognised state **disqualifies the whole feature** — it is not fully prepped for autonomous execution. Features where every file is `resolved`, `closed`, or `rejected` (nothing left to run) are also skipped.
+
+3. Sort the qualifying slugs alphabetically and select the first one.
+
+4. **If no qualifying feature exists**, emit the **LOOP_COMPLETE signal** (see `references/runner-output-formats.md`) on its own line and exit cleanly (no error). Do not output anything after it.
+
+5. **If a qualifying feature was found**, set the slug to that feature's directory name and continue to step 1.
+
+### 1. Resolve the feature directory and assemble the static context bundle
+
+The slug argument maps directly to `docs/issues/<slug>/`. Use the Bash tool to confirm:
+
+1. The directory exists (e.g. `ls docs/issues/<slug>/`).
+2. It contains at least one `NN-*.md` file (e.g. `ls docs/issues/<slug>/[0-9]*.md`).
+3. At least one of those files has `**Status:** ready-for-agent` (use the Read tool on each file and inspect the `**Status:**` line).
+
+If any of these checks fails, stop and report the specific reason to the user. Do not create a worktree.
+
+**Read the PRD:** `docs/issues/<slug>/PRD.md`. Scan its content for references matching `apps/claude-code/<plugin>/` (any path that starts with that prefix). This determines the ADR scope:
+
+- **Plugin feature** — one or more `apps/claude-code/<plugin>/` references found → use that plugin's `apps/claude-code/<plugin>/CONTEXT.md` and `apps/claude-code/<plugin>/docs/adr/`. Do **not** also inject root ADRs.
+- **Repo/tooling feature** — no such references found → use root `CONTEXT.md` and root `docs/adr/`.
+
+Also extract the `title:` field from the PRD's YAML frontmatter (the value between the opening `---` and closing `---` at the top of the file). Retain it for use in step 7's PR title derivation.
+
+**Read the scoped CONTEXT.md** using the Read tool.
+
+**Read all ADR files** in the scoped ADR directory: list `*.md` files using the Bash tool, then read each one using the Read tool.
+
+**Get the last 5 git commits** using the Bash tool:
+
+```
+git log --oneline -5
+```
+
+These items (PRD content + title, CONTEXT.md, ADRs, recent commits) are static — gather them once before the issue loop begins.
+
+### 2. Create the worktree and branch
+
+First, check whether a worktree from a prior run already exists using the Bash tool:
+
+```
+ls .claude/worktrees/<slug>
+```
+
+- **Exists** — reuse it. The branch `feature/afk/<slug>` already contains the committed work from the previous run. Skip `git worktree add`.
+- **Does not exist** — create it using the Bash tool:
+
+```
+git worktree add .claude/worktrees/<slug> -b feature/afk/<slug> develop
+```
+
+The worktree lands at `.claude/worktrees/<slug>`. All subsequent implementation work happens inside that worktree.
+
+### 3. Collect issues, build the dependency graph, and derive execution order
+
+Use the Bash tool to list **all** `NN-*.md` files in `docs/issues/<slug>/` (including `resolved` and `closed` — they are needed for graph completeness):
+
+```
+ls docs/issues/<slug>/[0-9]*.md
+```
+
+Use the Read tool to read each file. For every file record:
+
+- Its **numeric prefix** (the `NN` integer from the filename).
+- Its **status** (`**Status:**` line).
+- Its **`## Blocked by`** list — the filenames or paths referenced there. `## Blocked by: None`, `## Blocked by: None — can start immediately`, or a missing `## Blocked by` section all mean no predecessors.
+
+**Missing-blocker check — halt before executing anything if violated:**
+
+For each `## Blocked by` reference, verify the referenced filename actually exists in `docs/issues/<slug>/`. If a referenced blocker file is missing (typo, renamed, deleted), halt immediately with the **missing blocker error** (see `references/runner-output-formats.md`), naming the issue and the unresolvable reference. Do not silently treat it as satisfied.
+
+**Conflict check — halt before executing anything if violated:**
+
+For each issue A that lists issue B in `## Blocked by`: if B's numeric prefix is greater than A's numeric prefix, the dependency contradicts numerical convention. Halt immediately with the **dependency conflict error** (see `references/runner-output-formats.md`), naming both issues.
+
+**Build the execution queue:**
+
+From the dependency graph, compute a topological order over all issues (using `## Blocked by` edges). Filter the topological sequence to only `ready-for-agent` issues — `resolved`, `closed`, and `rejected` issues are satisfied and act as satisfied dependency nodes, not as items to execute.
+
+**Unsatisfied dependency check — halt before executing anything if violated:**
+
+For each `ready-for-agent` issue in the execution queue, inspect its `## Blocked by` list. If any listed blocker has status `ready-for-human`, halt immediately with the **unsatisfied dependency error** (see `references/runner-output-formats.md`), naming both issues.
+
+This ordered list is the execution queue. Record M = number of items in the queue (frozen at this moment — do not recount mid-run).
+
+### 4. Implement each issue via `/tdd`
+
+For each issue file in queue order (N = 1, 2, … M), before invoking `/tdd`, emit the **progress line** (see `references/runner-output-formats.md`) substituting N, M, and the issue title (first `# Heading` line of the issue file).
+
+Invoke the sub-agent using the Agent tool with `subagent_type: general-purpose` — the only stock type with access to both the Skill tool (to load `/tdd`) and the Edit/Write tools (to write code). The issue's `## Acceptance criteria` replaces the interactive planning phase — pass it as the pre-approved plan so the agent skips confirmation and proceeds directly to implementation.
+
+Before constructing the prompt, use the Read tool to read all sibling issue files (`docs/issues/<slug>/[0-9]*.md` except the current issue) at their current state — this gives the sub-agent visibility into what is already resolved and what is still pending.
+
+Construct the prompt using the template in `references/tdd-prompt-template.md`, substituting all `<placeholder>` values at runtime. Pass the constructed prompt to the Agent tool. Wait for the agent to return before continuing.
+
+**On failure:** If the Agent call signals failure (throws, returns an error, or explicitly reports it could not complete the issue):
+
+1. Using the Edit tool, change the `**Status:** ready-for-agent` line to `**Status:** needs-info`. This prevents auto-select from picking up this Feature on subsequent loop iterations.
+
+2. Append the **failure note** (see `references/runner-output-formats.md`) to the issue file using the Edit tool, substituting `<slug>`.
+
+3. Stop the runner immediately. Do not execute any subsequent issues — they may depend on a foundation this issue was meant to lay.
+
+4. Report to the user: which issue failed, that the worktree is at `.claude/worktrees/<slug>` on branch `feature/afk/<slug>`, and that no subsequent issues were run.
+
+### 5. Mark each issue resolved
+
+After the Agent call for an issue returns **successfully**, update the issue file using the Edit tool: change the `**Status:** ready-for-agent` line to `**Status:** resolved`.
+
+### 6. Continue until queue is empty
+
+Repeat steps 4–5 for every issue in the queue. When the last issue is resolved, proceed to step 7.
+
+### 7. Open a pull request and clean up
+
+**Push the branch:**
+
+```
+git -C .claude/worktrees/<slug> push -u origin feature/afk/<slug>
+```
+
+**Derive the PR title** from the PRD's `title` frontmatter field (already read in step 1) and the slug:
+
+```
+feat(<slug>): <PRD title>
+```
+
+**List the resolved issues** — all `NN-*.md` files in `docs/issues/<slug>/` whose status is now `resolved` (every issue the runner just processed, in numerical order).
+
+**Open the PR** using the Bash tool. The exact `gh pr create` invocation with the heredoc-wrapped body lives in `references/runner-output-formats.md` under "PR body template" — use that form verbatim, substituting `<slug>`, `<PRD title>`, and the resolved-issue list before running it. Run from inside the worktree (`git -C .claude/worktrees/<slug>`) or pass `--repo` if needed. **Do not run the snippet without substitution** — angle-bracket placeholders are not valid shell.
+
+**Failure handling for steps 7a and 7b:** If `git push` or `gh pr create` fails (non-zero exit, network error, permission denied, branch protection, etc.):
+
+1. Stop immediately. Do **not** remove the worktree.
+2. Report to the user: which command failed, the error output, that the worktree is at `.claude/worktrees/<slug>` on branch `feature/afk/<slug>`, and that all issues are still `resolved` (the failure is post-implementation).
+3. Suggest re-running `git push` / `gh pr create` manually once the cause is resolved.
+
+**Remove the worktree** only after the PR is opened successfully (PR URL returned by `gh`):
+
+```
+git worktree remove .claude/worktrees/<slug>
+```
+
+Report the PR URL and the list of resolved issues to the user.
+
+## Supporting Documentation
+
+- **`references/runner-output-formats.md`** — verbatim strings for the progress line, dependency conflict error, unsatisfied dependency error, failure note, PR body template, and `LOOP_COMPLETE` signal.
+- **`references/tdd-prompt-template.md`** — the AFK prompt template passed to the Agent tool for each `/tdd` sub-agent invocation; substitute all `<placeholder>` values at runtime.
+- **`docs/agents/feature-runner.md`** — human-facing reference: lifecycle diagram, dependency-satisfaction matrix, ADR scope, historical cleanup convention. Maintained in parallel; consult for broader context, not for runtime instructions.

.claude/skills/implement-feature/references/runner-output-formats.md

@@ -0,0 +1,106 @@
+# Runner output formats
+
+Verbatim strings emitted or embedded by the Feature Runner. `SKILL.md` references this file by name rather than repeating these strings inline.
+
+---
+
+## Progress line
+
+Emitted to the user before each `/tdd` invocation.
+
+```
+Implementing issue N of M: <issue title>
+```
+
+---
+
+## Missing blocker error
+
+Emitted when a `## Blocked by` reference points to a filename that does not exist in `docs/issues/<slug>/`. The runner halts before executing any issue.
+
+```
+Feature Runner error: missing blocker reference.
+  Issue NN-<A> lists "<reference>" in ## Blocked by, but that file does not exist in docs/issues/<slug>/.
+  Check for a typo, a rename, or a deleted issue. Resolve the reference manually before re-running.
+```
+
+---
+
+## Dependency conflict error
+
+Emitted when a `## Blocked by` reference points to an issue with a higher numeric prefix than the issue being blocked. The runner halts before executing any issue.
+
+```
+Feature Runner error: dependency conflict detected.
+  Issue NN-<A> is blocked by NN-<B>, but NN-<B> has a higher number than NN-<A>.
+  This conflicts with the numerical ordering convention. Resolve the ordering manually before re-running.
+```
+
+---
+
+## Unsatisfied dependency error
+
+Emitted when a `ready-for-agent` issue in the execution queue has a `## Blocked by` dependency whose status is `ready-for-human`. The runner halts before executing any issue.
+
+```
+Feature Runner error: unsatisfied dependency.
+  Issue NN-<A> is blocked by NN-<B>, but NN-<B> has status ready-for-human.
+  Complete issue NN-<B> manually (or update its status) before re-running /implement-feature <slug>.
+```
+
+---
+
+## Failure note
+
+Appended to a failing issue file under `## Comments` when `/tdd` cannot complete an issue. The `**Status:**` line is also changed to `needs-info` (see SKILL.md step 4).
+
+```markdown
+## Comments
+
+> _This was generated by AI during triage._
+
+**Feature Runner failure** — `/tdd` could not complete this issue. Status has been set to `needs-info`.
+
+The worktree at `.claude/worktrees/<slug>` has been left in place for inspection. Once the issue is resolved manually, restore `**Status:** ready-for-agent` and re-run `/implement-feature <slug>` to resume. Alternatively, close or reject the issue if it should not be retried.
+```
+
+---
+
+## PR body template
+
+The body passed to `gh pr create` after all issues in a feature are resolved.
+
+```markdown
+## Feature
+
+`docs/issues/<slug>/PRD.md`
+
+## Resolved issues
+
+- `docs/issues/<slug>/NN-<name>.md`
+- ...
+
+🤖 Implemented by the Feature Runner via `/implement-feature <slug>`
+```
+
+Pass via a bash heredoc:
+
+```
+gh pr create \
+  --base develop \
+  --title "feat(<slug>): <PRD title>" \
+  --body "$(cat <<'EOF'
+<substituted body content>
+EOF
+)"
+```
+
+---
+
+## LOOP_COMPLETE signal
+
+Emitted on its own line when no qualifying feature exists during auto-selection. Must appear alone — nothing before or after it on the same line. This is the stop signal that `/loop /implement-feature` uses to terminate an overnight draining run.
+
+```
+LOOP_COMPLETE
+```

.claude/skills/implement-feature/references/tdd-prompt-template.md

@@ -0,0 +1,27 @@
+# /tdd AFK prompt template
+
+Passed to the Agent tool for each `/tdd` sub-agent invocation. All `<placeholder>` values are substituted at runtime before the prompt is sent.
+
+```
+You are running `/tdd` in AFK mode. The interactive planning phase is complete — do not ask for confirmation. Begin by invoking the `tdd` skill via the Skill tool to load its full procedural guidance (red→green→refactor, vertical-slice rule, deep-modules / interface-design / refactoring sub-references), then follow it using the acceptance criteria below as the pre-approved plan and proceed directly to the red→green→refactor loop.
+
+Working directory: .claude/worktrees/<slug>
+
+--- ISSUE ---
+<full content of the current issue file>
+
+--- PRD (parent context) ---
+<full content of the PRD file at docs/issues/{slug}/PRD.md>
+
+--- SIBLING ISSUES ---
+<full content of each sibling issue file, separated by the filename as a header>
+
+--- CONTEXT.md ---
+<full content of the scoped CONTEXT.md>
+
+--- ADRs ---
+<full content of each scoped ADR file, separated by the filename as a header>
+
+--- RECENT COMMITS (last 5) ---
+<output of git log --oneline -5>
+```

.claude/skills/new-plugin/references/package-json-template.md

@@ -12,7 +12,7 @@ Use this as the starting shape for a new plugin's `package.json`. Copy `packageM
   "license": "LGPL-3.0-or-later",
   "type": "module",
   "packageManager": "<copy from root package.json>",
-  "engines": { "node": ">=24", "pnpm": ">=10" },
+  "engines": { "node": ">=22", "pnpm": ">=10" },
   "scripts": {
     "test": "node --test",
     "typecheck": "tsc --noEmit --project tsconfig.json",
@@ -32,7 +32,7 @@ Use this as the starting shape for a new plugin's `package.json`. Copy `packageM
 }
 ```
 
-`node --test` with no path argument uses Node's built-in test file discovery. It exits 0 with zero tests in Node >=22 — safe here because this repo requires `node >=24`.
+`node --test` with no path argument uses Node's built-in test file discovery. It exits 0 with zero tests in Node >=22 — safe here because this repo requires `node >=22`.
 
 ## Command-only plugin (no scripts or tests)
 
@@ -46,7 +46,7 @@ Omit `test`, `typecheck`, and the `@types/node`/`@unic/tsconfig`/`typescript` de
   "license": "LGPL-3.0-or-later",
   "type": "module",
   "packageManager": "<copy from root package.json>",
-  "engines": { "node": ">=24", "pnpm": ">=10" },
+  "engines": { "node": ">=22", "pnpm": ">=10" },
   "scripts": {
     "bump": "unic-bump",
     "sync-version": "unic-sync-version",

.out-of-scope/plans-issues-sync.md

@@ -0,0 +1,11 @@
+# docs/plans/ ↔ docs/issues/ Sync Gap
+
+This project will not build a bridge between `docs/plans/` and `docs/issues/`.
+
+## Why this is out of scope
+
+`docs/plans/` is being discontinued. The sync gap between the two systems is a consequence of running them in parallel, not a problem worth solving on its own. Once `docs/plans/` is retired, `docs/issues/` becomes the sole source of truth and the gap disappears.
+
+## Prior requests
+
+- `docs/inbox/plans-issues-sync-gap.md` — "no bridge between docs/plans/ specs and docs/issues/ triage files" (2026-05-08)

.out-of-scope/plans-numbering-format.md

@@ -0,0 +1,11 @@
+# Plans Numbering Format
+
+This project will not migrate `docs/plans/` spec file numbering to a 4-digit prefix.
+
+## Why this is out of scope
+
+`docs/plans/` is being discontinued. Renaming all existing spec files to a 4-digit scheme (`0001-`, `0002-`, …) would be pure churn on infrastructure that is on its way out, with no functional benefit and a non-trivial risk of breaking tooling or references mid-transition.
+
+## Prior requests
+
+- `docs/inbox/migrate-plans-numbering-to-4-digits-prefix.md` — "Migrate plans numbering to 4-digits prefix" (2026-05-03)

.out-of-scope/plugin-scaffolding-workflow.md

@@ -0,0 +1,21 @@
+# Plugin Scaffolding Workflow
+
+This project will not research how to scaffold or create new plugins — the workflow is already established.
+
+## Why this is out of scope
+
+The approach has been proven in practice:
+
+1. If the work is a skill, start with `/write-a-skill`.
+2. For a full plugin, use `/plugin-dev:create-plugin` (Anthropic's guided end-to-end plugin creation workflow).
+3. For targeted component work, use the relevant sub-command:
+   - `/plugin-dev:hook-development`
+   - `/plugin-dev:skill-development`
+   - `/plugin-dev:plugin-settings`
+   - …and other `plugin-dev:*` variants.
+
+Further research into scaffolding approaches would duplicate work already done and encoded in these skills.
+
+## Prior requests
+
+- `docs/inbox/research-how-to-scaffold-or-create-new-plugins.md` — "Research how to scaffold or create new plugins" (2026-05-03)