agent-templates 0.1.0 → 0.2.0

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/agents/reviewer.md

@@ -1,33 +1,33 @@
----
-name: reviewer
-description: Reviewer stage of the three-agent pattern. Independent judge in a FRESH context — never the Builder's session, deliberately a different model tier from the Builder so the two do not share blind spots. Clears the work or bounces it back with findings.
-model: claude-fable-5
-effort: max
-tools: Read, Glob, Grep, Bash
----
-
-<!-- Model/effort pinned per pattern three-agent-architect-builder-reviewer, as of 2026-07-17.
-     Do not change them here first — update the pattern entry in agent-templates, then sync. -->
-
-You are the **Reviewer** — the last quality gate before merge, independent of the Builder.
-
-Context rule: you must be running in a **fresh context**. Your input is only: the ticket, the plan (`docs/plans/<ticket-id>.md`), and the Builder's diff (branch or PR ref). If you have been handed the Builder's conversation or its self-assessment, stop and report the pattern violation instead of reviewing.
-
-Review the diff against the ticket and the plan, in priority order:
-
-1. **Edge cases** — inputs and states the happy path ignores.
-2. **Concurrency** — races, ordering assumptions, shared-state mutation.
-3. **Security-sensitive paths** — authz checks, input validation, secrets handling, injection.
-4. **Plan conformance** — undeclared deviations from the plan are findings.
-
-Method:
-
-- Run the FULL suite yourself via Bash — unit, integration, and E2E where present, not only the tests the diff touches. Never trust reported results.
-- Be adversarial: try to refute the claim that the ticket is done. Default to BOUNCE when uncertain.
-
-Verdict (exactly one):
-
-- **CLEAR** — with a short note of what was checked.
-- **BOUNCE** — with numbered findings: `file:line` · concrete failure scenario · severity. Findings go back to the Builder.
-
-Never: fix the code yourself; approve out of politeness; re-clear without new commits to review.
+---
+name: reviewer
+description: Reviewer stage of the three-agent pattern. Independent judge in a FRESH context — never the Builder's session, deliberately a different model tier from the Builder so the two do not share blind spots. Clears the work or bounces it back with findings.
+model: claude-fable-5
+effort: max
+tools: Read, Glob, Grep, Bash
+---
+
+<!-- Model/effort pinned per pattern three-agent-architect-builder-reviewer, as of 2026-07-17.
+     Do not change them here first — update the pattern entry in agent-templates, then sync. -->
+
+You are the **Reviewer** — the last quality gate before merge, independent of the Builder.
+
+Context rule: you must be running in a **fresh context**. Your input is only: the ticket, the plan (`docs/plans/<ticket-id>.md`), and the Builder's diff (branch or PR ref). If you have been handed the Builder's conversation or its self-assessment, stop and report the pattern violation instead of reviewing.
+
+Review the diff against the ticket and the plan, in priority order:
+
+1. **Edge cases** — inputs and states the happy path ignores.
+2. **Concurrency** — races, ordering assumptions, shared-state mutation.
+3. **Security-sensitive paths** — authz checks, input validation, secrets handling, injection.
+4. **Plan conformance** — undeclared deviations from the plan are findings.
+
+Method:
+
+- Run the FULL suite yourself via Bash — unit, integration, and E2E where present, not only the tests the diff touches. Never trust reported results.
+- Be adversarial: try to refute the claim that the ticket is done. Default to BOUNCE when uncertain.
+
+Verdict (exactly one):
+
+- **CLEAR** — with a short note of what was checked.
+- **BOUNCE** — with numbered findings: `file:line` · concrete failure scenario · severity. Findings go back to the Builder.
+
+Never: fix the code yourself; approve out of politeness; re-clear without new commits to review.

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/agents/triage.md

@@ -1,31 +1,31 @@
----
-name: triage
-description: Nightly triage stage. Classifies an open tracker issue as fixable / invalid / needs-human; for fixable ones synthesizes a cold-startable pipeline ticket file from the issue. Never fixes code, never touches the tracker.
-model: claude-sonnet-5
-effort: xhigh
-tools: Read, Glob, Grep, Bash, Write
----
-
-<!-- Model/effort: profile inherited from the Architect row of the pattern README §3 —
-     classification + ticket synthesis is planning-shaped work; no separate benchmark
-     basis. [team-policy], as of 2026-07-17. Update via the pattern entry, then sync. -->
-
-You are the **Triage** stage of the nightly issue sweep.
-
-Input: one tracker issue (number, title, body, labels).
-
-Classify it as exactly one of:
-
-- **fixable** — a real defect or small task the pipeline can complete autonomously: a clear symptom or goal, bounded scope, and you can trace it to specific code by exploring now.
-- **invalid** — not a real issue: works as intended, duplicate, or out of scope. State why, with evidence (file refs, the behavior you verified).
-- **needs-human** — real, but not autonomous-safe: needs product judgment, a hard-to-reverse choice, is too large for one overnight ticket, or you cannot locate the code.
-
-For **fixable** only: write a ticket file at `docs/prd/99-nightly/tickets/ISS-<number>-<slug>.md` following `templates/ticket.template.md` (`id: ISS-<number>`, `module: 99-nightly`, honest `size`). Inline everything the pipeline needs — quote the relevant issue text, name the files you traced — per the cold-start rule. The acceptance checklist must be classified, mechanical wherever possible, and MUST turn the reported symptom into a test.
-
-Rules:
-
-- Read the code to verify claims before classifying — never classify from the issue text alone.
-- Never modify code. Never close, label, or comment on issues — tracker writes belong to the report step.
-- When torn between fixable and needs-human, choose **needs-human**: a wrong autonomous fix at night is worse than a skipped issue.
-
-Return: `classification`, `reason` (with evidence), and `ticketPath` (fixable only).
+---
+name: triage
+description: Nightly triage stage. Classifies an open tracker issue as fixable / invalid / needs-human; for fixable ones synthesizes a cold-startable pipeline ticket file from the issue. Never fixes code, never touches the tracker.
+model: claude-sonnet-5
+effort: xhigh
+tools: Read, Glob, Grep, Bash, Write
+---
+
+<!-- Model/effort: profile inherited from the Architect row of the pattern README §3 —
+     classification + ticket synthesis is planning-shaped work; no separate benchmark
+     basis. [team-policy], as of 2026-07-17. Update via the pattern entry, then sync. -->
+
+You are the **Triage** stage of the nightly issue sweep.
+
+Input: one tracker issue (number, title, body, labels).
+
+Classify it as exactly one of:
+
+- **fixable** — a real defect or small task the pipeline can complete autonomously: a clear symptom or goal, bounded scope, and you can trace it to specific code by exploring now.
+- **invalid** — not a real issue: works as intended, duplicate, or out of scope. State why, with evidence (file refs, the behavior you verified).
+- **needs-human** — real, but not autonomous-safe: needs product judgment, a hard-to-reverse choice, is too large for one overnight ticket, or you cannot locate the code.
+
+For **fixable** only: write a ticket file at `docs/prd/99-nightly/tickets/ISS-<number>-<slug>.md` following `templates/ticket.template.md` (`id: ISS-<number>`, `module: 99-nightly`, honest `size`). Inline everything the pipeline needs — quote the relevant issue text, name the files you traced — per the cold-start rule. The acceptance checklist must be classified, mechanical wherever possible, and MUST turn the reported symptom into a test.
+
+Rules:
+
+- Read the code to verify claims before classifying — never classify from the issue text alone.
+- Never modify code. Never close, label, or comment on issues — tracker writes belong to the report step.
+- When torn between fixable and needs-human, choose **needs-human**: a wrong autonomous fix at night is worse than a skipped issue.
+
+Return: `classification`, `reason` (with evidence), and `ticketPath` (fixable only).

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/commands/breakdown-prd.md

@@ -1,18 +1,18 @@
----
-description: Decompose docs/PRD.md into sub-PRDs + template-compliant tickets (three-agent pattern, pre-Gate-1 planning)
-argument-hint: [focus notes, e.g. module-count hint or what to defer]
----
-
-Launch the **architect** subagent to decompose the master PRD. Optional focus notes from the human: `$ARGUMENTS`
-
-Input: `docs/PRD.md` (hard requirement — STOP with a clear message if absent) plus any existing `docs/adr/` entries.
-
-Output (planning artifacts only — the architect writes no production code):
-
-1. `docs/prd/breakdown-plan.md` — the module split, cut on **file-ownership boundaries** (disjoint file-scopes are what make parallel lanes safe later; shared contracts/schemas go into a foundation module built first), the global file-scope allocation table, and the ticket dependency DAG (mirrors each ticket's `blocked_by`/`blocks`).
-2. Per module `NN-<name>`: `docs/prd/NN-<name>/README.md` — the sub-PRD: problem, scope/non-goals, decisions (each with a basis), rejected alternatives, open questions (each with an owner), work-breakdown table (ticket · size · lane · file-scope · depends-on), acceptance, changelog.
-3. `docs/prd/NN-<name>/tickets/<ID>-<slug>.md` — every ticket follows `templates/ticket.template.md` **fully**: traceability header, "Why `<agent>`" basis, `lane`/`blocked_by`/`blocks` frontmatter, per-item Non-goal owners, file-scope + does-not-touch + serial-safety, code-level deliverables, classified acceptance (tag vocabulary from this repo's CLAUDE.md), test plan, feedback obligation. Every ticket must be cold-startable.
-
-When the architect returns: present the breakdown summary (modules, ticket count, DAG, open questions) and **STOP**. This output is the input to Gate 1 — the human's review plus `/start-milestone` is the sign-off. Never begin implementation from this command.
-
-Hard rule: this stage runs in the **architect** subagent, never inline in this session. If the subagent cannot be launched or fails, report that and stop — do not absorb its role.
+---
+description: Decompose docs/PRD.md into sub-PRDs + template-compliant tickets (three-agent pattern, pre-Gate-1 planning)
+argument-hint: [focus notes, e.g. module-count hint or what to defer]
+---
+
+Launch the **architect** subagent to decompose the master PRD. Optional focus notes from the human: `$ARGUMENTS`
+
+Input: `docs/PRD.md` (hard requirement — STOP with a clear message if absent) plus any existing `docs/adr/` entries.
+
+Output (planning artifacts only — the architect writes no production code):
+
+1. `docs/prd/breakdown-plan.md` — the module split, cut on **file-ownership boundaries** (disjoint file-scopes are what make parallel lanes safe later; shared contracts/schemas go into a foundation module built first), the global file-scope allocation table, and the ticket dependency DAG (mirrors each ticket's `blocked_by`/`blocks`).
+2. Per module `NN-<name>`: `docs/prd/NN-<name>/README.md` — the sub-PRD: problem, scope/non-goals, decisions (each with a basis), rejected alternatives, open questions (each with an owner), work-breakdown table (ticket · size · lane · file-scope · depends-on), acceptance, changelog.
+3. `docs/prd/NN-<name>/tickets/<ID>-<slug>.md` — every ticket follows `templates/ticket.template.md` **fully**: traceability header, "Why `<agent>`" basis, `lane`/`blocked_by`/`blocks` frontmatter, per-item Non-goal owners, file-scope + does-not-touch + serial-safety, code-level deliverables, classified acceptance (tag vocabulary from this repo's CLAUDE.md), test plan, feedback obligation. Every ticket must be cold-startable.
+
+When the architect returns: present the breakdown summary (modules, ticket count, DAG, open questions) and **STOP**. This output is the input to Gate 1 — the human's review plus `/start-milestone` is the sign-off. Never begin implementation from this command.
+
+Hard rule: this stage runs in the **architect** subagent, never inline in this session. If the subagent cannot be launched or fails, report that and stop — do not absorb its role.

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/commands/nightly-issues.md

@@ -1,14 +1,14 @@
----
-description: Nightly issue sweep — triage open issues, auto-fix the fixable ones through the three-agent pipeline, post the morning report (designed for headless `claude -p "/nightly-issues"`)
-argument-hint: [max-issues]
----
-
-Arguments: `$ARGUMENTS` — optional first argument caps how many issues to process tonight (default 5).
-
-Execute in order:
-
-1. **Collect.** List open issues with the platform CLI (`gh issue list --state open --json number,title,body,labels,createdAt,url` / glab equivalent). Exclude issues labeled `nightly:escalated`, `triage:invalid`, or `needs-human`, and any issue titled `Nightly report ...`. For each remaining issue set `isNew` = created within the last 24 hours. Compute `reportDate` = today's local date (YYYY-MM-DD).
-2. **Launch the sweep.** Call the **Workflow** tool with `name: "nightly-issues"` and `args: { issues, maxIssues, defaultBranch, platform, reportDate }`. This command's instruction is your authorization to use the Workflow tool. The workflow triages (read-only), runs fixable issues through the run-milestone pipeline autonomously, and posts all tracker writes in one report step.
-3. **Final output** (this is the headless run's stdout): the report issue URL, then one line per processed issue — `#N · <classification or pipeline status> · <one-line reason>` — plus how many eligible issues were left for the next night.
-
-Operator notes: scheduling, permissions, and the morning-email mechanics are documented in the scaffold's INSTALL.md § Nightly sweep. You are an observer while the workflow runs — no stage work, no file edits, no tracker writes outside the workflow.
+---
+description: Nightly issue sweep — triage open issues, auto-fix the fixable ones through the three-agent pipeline, post the morning report (designed for headless `claude -p "/nightly-issues"`)
+argument-hint: [max-issues]
+---
+
+Arguments: `$ARGUMENTS` — optional first argument caps how many issues to process tonight (default 5).
+
+Execute in order:
+
+1. **Collect.** List open issues with the platform CLI (`gh issue list --state open --json number,title,body,labels,createdAt,url` / glab equivalent). Exclude issues labeled `nightly:escalated`, `triage:invalid`, or `needs-human`, and any issue titled `Nightly report ...`. For each remaining issue set `isNew` = created within the last 24 hours. Compute `reportDate` = today's local date (YYYY-MM-DD).
+2. **Launch the sweep.** Call the **Workflow** tool with `name: "nightly-issues"` and `args: { issues, maxIssues, defaultBranch, platform, reportDate }`. This command's instruction is your authorization to use the Workflow tool. The workflow triages (read-only), runs fixable issues through the run-milestone pipeline autonomously, and posts all tracker writes in one report step.
+3. **Final output** (this is the headless run's stdout): the report issue URL, then one line per processed issue — `#N · <classification or pipeline status> · <one-line reason>` — plus how many eligible issues were left for the next night.
+
+Operator notes: scheduling, permissions, and the morning-email mechanics are documented in the scaffold's INSTALL.md § Nightly sweep. You are an observer while the workflow runs — no stage work, no file edits, no tracker writes outside the workflow.

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/commands/review-ticket.md

@@ -1,14 +1,14 @@
----
-description: Run the Reviewer stage on a built ticket (three-agent pattern) — requires a fresh context
-argument-hint: <ticket-id> [branch-or-PR-ref]
----
-
-Arguments: `$ARGUMENTS` — the first is the ticket id (TICKET below); the optional second is the diff reference (branch or PR; default: the ticket's `ticket/<id>` branch).
-
-Contamination check first: if this session contains the Builder's implementation conversation for TICKET, STOP and tell the user to run `/review-ticket` from a fresh session. (A reviewer subagent launched from a session that only orchestrated — passing artifacts, never transcripts — is acceptable: Mode A in the scaffold's INSTALL.md.)
-
-Launch the **reviewer** subagent for TICKET. Give it ONLY: the ticket path, the plan path (`docs/plans/<ticket-id>.md`), and the diff reference. Never include the Builder's transcript or self-assessment.
-
-Relay the verdict verbatim — CLEAR, or BOUNCE with its numbered findings. On BOUNCE, findings go back to the Builder; after 2 bounce cycles, escalate to a human instead of looping.
-
-Hard rule: this stage runs in the **reviewer** subagent, never inline in this session. If the subagent cannot be launched or fails, report that and stop — do not absorb its role. After a merge, `/verify-delivery` still runs — a CLEAR verdict does not close the ticket by itself.
+---
+description: Run the Reviewer stage on a built ticket (three-agent pattern) — requires a fresh context
+argument-hint: <ticket-id> [branch-or-PR-ref]
+---
+
+Arguments: `$ARGUMENTS` — the first is the ticket id (TICKET below); the optional second is the diff reference (branch or PR; default: the ticket's `ticket/<id>` branch).
+
+Contamination check first: if this session contains the Builder's implementation conversation for TICKET, STOP and tell the user to run `/review-ticket` from a fresh session. (A reviewer subagent launched from a session that only orchestrated — passing artifacts, never transcripts — is acceptable: Mode A in the scaffold's INSTALL.md.)
+
+Launch the **reviewer** subagent for TICKET. Give it ONLY: the ticket path, the plan path (`docs/plans/<ticket-id>.md`), and the diff reference. Never include the Builder's transcript or self-assessment.
+
+Relay the verdict verbatim — CLEAR, or BOUNCE with its numbered findings. On BOUNCE, findings go back to the Builder; after 2 bounce cycles, escalate to a human instead of looping.
+
+Hard rule: this stage runs in the **reviewer** subagent, never inline in this session. If the subagent cannot be launched or fails, report that and stop — do not absorb its role. After a merge, `/verify-delivery` still runs — a CLEAR verdict does not close the ticket by itself.

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/commands/start-all.md

@@ -0,0 +1,17 @@
+---
+description: Whole-PRD Gate 1 — compute the module DAG, publish every module's tickets, run all modules through the pipeline in dependency order (three-agent pattern)
+argument-hint: [supervised|autonomous]
+---
+
+Arguments: `$ARGUMENTS` — optional mode override (else the repo's declared Operating mode in CLAUDE.md).
+
+Typing this command is the human Gate 1 sign-off **for the whole PRD** — every module, in dependency order. Prefer `/start-milestone` per module when you still want module-boundary checkpoints. Execute in order:
+
+1. **Compute the plan.** Run `node .claude/scripts/milestone-dag.mjs` and show its output (module order, per-module dependencies). STOP on any error — a dangling `blocked_by` or a cycle is a spec defect for the Architect/human, not something to patch here.
+2. **Publish all tickets.** For each module in DAG order: `node .claude/scripts/publish-tickets.mjs docs/prd/<module>` (dry-run, then `--create`; STOP on `error` entries). Then, per module, **filter out tickets whose issues are already closed** (closed = delivered by an earlier run — this makes `/start-all` re-runs resume: fully-closed modules pass an empty ticket list and are marked already-complete).
+3. **Launch the driver.** Call the **Workflow** tool with `name: "start-all"` and `args: { modules: [{name, dependsOn, tickets}] in DAG order, mode, defaultBranch, platform }`. This command's instruction is your authorization to use the Workflow tool. Failure policy is enforced in the workflow: failed modules block their dependents; independent branches continue in `autonomous`; anything short of a CLEAR stops everything in `supervised`.
+4. **Relay the final report verbatim** — per module: `completed` / `already-complete` / `paused-for-merge` (supervised: tell the human to merge, then re-run this command) / `failed` (with the failing ticket + stage) / `skipped-dependency` / `not-started`. Escalations inside a module carry through from run-milestone unchanged.
+
+While the workflow runs you are an observer. Do not do stage work in parallel, do not "help" a slow stage, do not edit files.
+
+Hard rule: DAG computation and publishing are script steps; module sequencing is the workflow's job. Never absorb either role by improvising order or tracker writes yourself.

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/commands/start-milestone.md

@@ -1,15 +1,15 @@
----
-description: Gate 1 start signal — publish the module's tickets as tracker issues, then run the milestone pipeline (three-agent pattern)
-argument-hint: <module dir, e.g. docs/prd/01-foo> [supervised|autonomous]
----
-
-Arguments: `$ARGUMENTS` — the first is the module directory (MODULE below); the optional second overrides the repo's declared Operating mode (CLAUDE.md).
-
-Typing this command **is** the human Gate 1 sign-off: the sub-PRD and tickets are final, and tracker issue **creation** is authorized by this sign-off. Execute in order:
-
-1. **Verify Gate 1 inputs.** `MODULE/README.md` (the sub-PRD) exists and `MODULE/tickets/*.md` is non-empty; every ticket has the required frontmatter (see `templates/ticket.template.md`). Anything missing → STOP and list exactly what is missing. Do not fix it yourself — that is Architect-stage work.
-2. **Publish tickets as tracker issues.** Run `node .claude/scripts/publish-tickets.mjs MODULE` (dry-run) and show the mapping. If the summary contains `error` entries → STOP and report them. Otherwise re-run with `--create` (idempotent — the `[<id>]` title prefix dedupes, so re-running is safe), and again STOP on any `error` entries.
-3. **Launch the pipeline.** Parse the final `PUBLISH-SUMMARY-JSON` line into `tickets: [{id, path, issue}]`. **Filter out tickets whose issue is already closed** (check via `gh`/`glab` — closed means delivered by an earlier run; this filter is what makes re-runs after supervised pauses or crashes safe). Determine the Operating mode, then call the **Workflow** tool with `name: "run-milestone"` and `args: { tickets, mode, defaultBranch, platform }`. This command's instruction is your authorization to use the Workflow tool.
-4. **Relay the final report verbatim** — per ticket: `delivered` · `awaiting-human-merge` · `escalated` (stage `review`, `reviewer-failed`, or `bounce-fix-build`) · `failed` · `delivery-incomplete`, plus `notStarted` when the run stopped early. Escalated and failed items go to the human; do not fix them inline (the write guard will hold you to that). In `supervised` mode the run stops after each CLEAR verdict — tell the human to merge, then re-run this command to continue.
-
-While the workflow runs you are an observer. Do not do stage work in parallel, do not "help" a slow stage, do not edit files.
+---
+description: Gate 1 start signal — publish the module's tickets as tracker issues, then run the milestone pipeline (three-agent pattern)
+argument-hint: <module dir, e.g. docs/prd/01-foo> [supervised|autonomous]
+---
+
+Arguments: `$ARGUMENTS` — the first is the module directory (MODULE below); the optional second overrides the repo's declared Operating mode (CLAUDE.md).
+
+Typing this command **is** the human Gate 1 sign-off: the sub-PRD and tickets are final, and tracker issue **creation** is authorized by this sign-off. Execute in order:
+
+1. **Verify Gate 1 inputs.** `MODULE/README.md` (the sub-PRD) exists and `MODULE/tickets/*.md` is non-empty; every ticket has the required frontmatter (see `templates/ticket.template.md`). Anything missing → STOP and list exactly what is missing. Do not fix it yourself — that is Architect-stage work.
+2. **Publish tickets as tracker issues.** Run `node .claude/scripts/publish-tickets.mjs MODULE` (dry-run) and show the mapping. If the summary contains `error` entries → STOP and report them. Otherwise re-run with `--create` (idempotent — the `[<id>]` title prefix dedupes, so re-running is safe), and again STOP on any `error` entries.
+3. **Launch the pipeline.** Parse the final `PUBLISH-SUMMARY-JSON` line into `tickets: [{id, path, issue}]`. **Filter out tickets whose issue is already closed** (check via `gh`/`glab` — closed means delivered by an earlier run; this filter is what makes re-runs after supervised pauses or crashes safe). Determine the Operating mode, then call the **Workflow** tool with `name: "run-milestone"` and `args: { tickets, mode, defaultBranch, platform }`. This command's instruction is your authorization to use the Workflow tool.
+4. **Relay the final report verbatim** — per ticket: `delivered` · `awaiting-human-merge` · `escalated` (stage `review`, `reviewer-failed`, or `bounce-fix-build`) · `failed` · `delivery-incomplete`, plus `notStarted` when the run stopped early. Escalated and failed items go to the human; do not fix them inline (the write guard will hold you to that). In `supervised` mode the run stops after each CLEAR verdict — tell the human to merge, then re-run this command to continue.
+
+While the workflow runs you are an observer. Do not do stage work in parallel, do not "help" a slow stage, do not edit files.

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/commands/verify-delivery.md

@@ -1,20 +1,20 @@
----
-description: Post-merge Definition-of-Done check for a ticket (three-agent pattern) — verifies delivery instead of assuming it
-argument-hint: <ticket-id>
----
-
-Verify — do not assume — that ticket $ARGUMENTS is actually delivered. Check every item yourself this session and print a pass/fail table:
-
-1. **Plan** exists at `docs/plans/$ARGUMENTS.md`.
-2. **Reviewer verdict** is CLEAR, attached to the MR/PR.
-3. **Tests green on the merged default branch** — run the suite yourself this session; never accept reported results.
-4. **MR/PR merged** into the **default branch** (not a side branch).
-5. **Tracker issue closed** — check via `glab issue view` / `gh issue view`. Auto-close via `Closes #N` fires only under specific conditions (GitLab: default-branch merge with the closing pattern in the MR description) — never trust it blindly; this exact gap has shipped before (MRs merged, issues left open).
-6. **Writeback** — any Deviations noted by the Builder are reflected back into the ticket/sub-PRD.
-
-Report every failed item plainly. If the MR is merged but the issue is still open, the repair is the exact close command (`glab issue close <N>` / `gh issue close <N>`) — behavior depends on the repo's declared operating mode (CLAUDE.md, "Operating mode"):
-
-- `supervised`: show the command and run it only after explicit human OK.
-- `autonomous`: run the repair, report what was repaired, and escalate to a human only if the repair fails or the gap is not mechanically repairable.
-
-Never mark an item passed that you did not check this session.
+---
+description: Post-merge Definition-of-Done check for a ticket (three-agent pattern) — verifies delivery instead of assuming it
+argument-hint: <ticket-id>
+---
+
+Verify — do not assume — that ticket $ARGUMENTS is actually delivered. Check every item yourself this session and print a pass/fail table:
+
+1. **Plan** exists at `docs/plans/$ARGUMENTS.md`.
+2. **Reviewer verdict** is CLEAR, attached to the MR/PR.
+3. **Tests green on the merged default branch** — run the suite yourself this session; never accept reported results.
+4. **MR/PR merged** into the **default branch** (not a side branch).
+5. **Tracker issue closed** — check via `glab issue view` / `gh issue view`. Auto-close via `Closes #N` fires only under specific conditions (GitLab: default-branch merge with the closing pattern in the MR description) — never trust it blindly; this exact gap has shipped before (MRs merged, issues left open).
+6. **Writeback** — any Deviations noted by the Builder are reflected back into the ticket/sub-PRD.
+
+Report every failed item plainly. If the MR is merged but the issue is still open, the repair is the exact close command (`glab issue close <N>` / `gh issue close <N>`) — behavior depends on the repo's declared operating mode (CLAUDE.md, "Operating mode"):
+
+- `supervised`: show the command and run it only after explicit human OK.
+- `autonomous`: run the repair, report what was repaired, and escalate to a human only if the repair fails or the gap is not mechanically repairable.
+
+Never mark an item passed that you did not check this session.

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/hooks/guard-main-session-writes.mjs

@@ -1,53 +1,53 @@
-#!/usr/bin/env node
-// Three-agent pattern guard: the ORCHESTRATOR (main session) never writes.
-//
-// PreToolUse hook on Edit|Write|MultiEdit|NotebookEdit (wired in .claude/settings.json).
-// Per https://code.claude.com/docs/en/hooks.md (verified 2026-07-17): hooks fire for
-// subagent tool calls too, and the input carries `agent_id`/`agent_type` ONLY when the
-// call comes from a subagent — their absence identifies the main session.
-//
-// Behavior:
-//   - subagent call (architect writes the plan, builder writes code) -> no objection
-//   - main-session call -> deny, with the dispatch instruction fed back to the model
-//   - override switch for a human-approved out-of-pipeline edit: create the file
-//     .claude/allow-main-writes (and delete it afterwards to re-arm the guard)
-//
-// Only the main session is constrained here; each subagent is governed by its own
-// tools/disallowedTools frontmatter (e.g. the reviewer has no Write/Edit at all).
-
-import { existsSync } from "node:fs";
-
-const chunks = [];
-for await (const chunk of process.stdin) chunks.push(chunk);
-
-let input = {};
-try {
-  input = JSON.parse(Buffer.concat(chunks).toString("utf8"));
-} catch {
-  process.exit(0); // unparsable input: stay out of the way rather than block blindly
-}
-
-const isSubagent = typeof input.agent_id === "string" && input.agent_id.length > 0;
-const overrideSwitch = new URL("../allow-main-writes", import.meta.url);
-
-if (isSubagent || existsSync(overrideSwitch)) {
-  process.exit(0); // no objection; normal permission flow applies
-}
-
-const target =
-  input.tool_input?.file_path ?? input.tool_input?.notebook_path ?? "(unknown target)";
-
-console.log(
-  JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: "PreToolUse",
-      permissionDecision: "deny",
-      permissionDecisionReason:
-        `Three-agent pattern: the main session orchestrates only and never writes ` +
-        `(blocked ${input.tool_name} on ${target}). Dispatch the work to its stage instead: ` +
-        `/plan-ticket (architect) or /build-ticket (builder). For a human-approved ` +
-        `out-of-pipeline edit, create .claude/allow-main-writes and retry — then delete it.`,
-    },
-  })
-);
-process.exit(0);
+#!/usr/bin/env node
+// Three-agent pattern guard: the ORCHESTRATOR (main session) never writes.
+//
+// PreToolUse hook on Edit|Write|MultiEdit|NotebookEdit (wired in .claude/settings.json).
+// Per https://code.claude.com/docs/en/hooks.md (verified 2026-07-17): hooks fire for
+// subagent tool calls too, and the input carries `agent_id`/`agent_type` ONLY when the
+// call comes from a subagent — their absence identifies the main session.
+//
+// Behavior:
+//   - subagent call (architect writes the plan, builder writes code) -> no objection
+//   - main-session call -> deny, with the dispatch instruction fed back to the model
+//   - override switch for a human-approved out-of-pipeline edit: create the file
+//     .claude/allow-main-writes (and delete it afterwards to re-arm the guard)
+//
+// Only the main session is constrained here; each subagent is governed by its own
+// tools/disallowedTools frontmatter (e.g. the reviewer has no Write/Edit at all).
+
+import { existsSync } from "node:fs";
+
+const chunks = [];
+for await (const chunk of process.stdin) chunks.push(chunk);
+
+let input = {};
+try {
+  input = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+} catch {
+  process.exit(0); // unparsable input: stay out of the way rather than block blindly
+}
+
+const isSubagent = typeof input.agent_id === "string" && input.agent_id.length > 0;
+const overrideSwitch = new URL("../allow-main-writes", import.meta.url);
+
+if (isSubagent || existsSync(overrideSwitch)) {
+  process.exit(0); // no objection; normal permission flow applies
+}
+
+const target =
+  input.tool_input?.file_path ?? input.tool_input?.notebook_path ?? "(unknown target)";
+
+console.log(
+  JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason:
+        `Three-agent pattern: the main session orchestrates only and never writes ` +
+        `(blocked ${input.tool_name} on ${target}). Dispatch the work to its stage instead: ` +
+        `/plan-ticket (architect) or /build-ticket (builder). For a human-approved ` +
+        `out-of-pipeline edit, create .claude/allow-main-writes and retry — then delete it.`,
+    },
+  })
+);
+process.exit(0);

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/scripts/milestone-dag.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+// milestone-dag.mjs — deterministic module-DAG computation for /start-all.
+// Ground truth is ticket frontmatter (`blocked_by`), never prose: module A depends on
+// module B when any ticket in A is blocked_by a ticket living in B.
+//
+// Usage: node .claude/scripts/milestone-dag.mjs [prd-root]     (default: docs/prd)
+// Output: human-readable plan + a final machine-readable line:
+//   DAG-JSON: {"order":[...],"modules":{"<name>":{"tickets":[ids],"dependsOn":[names]}}}
+// Exit 1 on: missing root, a blocked_by referencing an unknown ticket id (zero-silence:
+// a dangling dependency is a spec error, not a warning), or a dependency cycle.
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+const root = process.argv[2] || 'docs/prd'
+if (!existsSync(root)) {
+  console.error(`no such prd root: ${root}`)
+  process.exit(1)
+}
+
+const fmOf = (text) => (text.replace(/^/, '').match(/^---\r?\n([\s\S]*?)\r?\n---/) || [])[1] || ''
+const field = (fm, name) => ((fm.match(new RegExp(`^${name}\\s*:\\s*(.+)$`, 'm')) || [])[1] || '').trim()
+const listField = (fm, name) =>
+  field(fm, name)
+    .replace(/^\[/, '')
+    .replace(/\]$/, '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean)
+
+const modules = {} // name -> { tickets: [{id, blockedBy}], dependsOn:Set }
+const ticketModule = {} // ticket id -> module name
+const errors = []
+
+for (const d of readdirSync(root, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort()) {
+  const tdir = join(root, d, 'tickets')
+  let ok = false
+  try { ok = statSync(tdir).isDirectory() } catch {}
+  if (!ok) continue
+  const tickets = []
+  for (const f of readdirSync(tdir).filter((n) => n.endsWith('.md')).sort()) {
+    const fm = fmOf(readFileSync(join(tdir, f), 'utf8'))
+    const id = field(fm, 'id')
+    if (!id) { errors.push(`${join(tdir, f)}: missing frontmatter id`); continue }
+    if (ticketModule[id]) { errors.push(`duplicate ticket id ${id} (${ticketModule[id]} and ${d})`); continue }
+    ticketModule[id] = d
+    tickets.push({ id, blockedBy: listField(fm, 'blocked_by') })
+  }
+  if (tickets.length) modules[d] = { tickets, dependsOn: new Set() }
+}
+
+if (!Object.keys(modules).length) {
+  console.error(`no modules with tickets under ${root}`)
+  process.exit(1)
+}
+
+for (const [name, mod] of Object.entries(modules)) {
+  for (const t of mod.tickets) {
+    for (const dep of t.blockedBy) {
+      const owner = ticketModule[dep]
+      if (!owner) { errors.push(`${name}/${t.id}: blocked_by references unknown ticket '${dep}'`); continue }
+      if (owner !== name) mod.dependsOn.add(owner)
+    }
+  }
+}
+
+if (errors.length) {
+  for (const e of errors) console.error(`x ${e}`)
+  process.exit(1)
+}
+
+// Kahn topological sort; deterministic tiebreak by module name (numeric prefixes sort naturally)
+const order = []
+const remaining = new Set(Object.keys(modules))
+while (remaining.size) {
+  const ready = [...remaining].filter((m) => [...modules[m].dependsOn].every((d) => !remaining.has(d))).sort()
+  if (!ready.length) {
+    console.error(`x dependency cycle among: ${[...remaining].sort().join(', ')}`)
+    process.exit(1)
+  }
+  const next = ready[0]
+  order.push(next)
+  remaining.delete(next)
+}
+
+for (const m of order) {
+  const deps = [...modules[m].dependsOn].sort()
+  console.log(`${m}  (${modules[m].tickets.length} ticket(s))${deps.length ? '  <- depends on: ' + deps.join(', ') : ''}`)
+}
+const json = {
+  order,
+  modules: Object.fromEntries(order.map((m) => [m, { tickets: modules[m].tickets.map((t) => t.id), dependsOn: [...modules[m].dependsOn].sort() }])),
+}
+console.log('DAG-JSON: ' + JSON.stringify(json))