agent-templates 0.1.0 → 0.2.0

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

@@ -1,65 +1,65 @@
-# Installing the three-agent scaffold
-
-Source pattern: `agent-templates/patterns/three-agent-architect-builder-reviewer` — read its [README](../README.md) (especially the expiry trigger) before installing.
-
-## Quickstart
-
-From a checkout of the catalog: `node scripts/adopt.mjs three-agent-architect-builder-reviewer <target-dir>` performs steps 1–6 below mechanically (idempotent; `--platform gh|glab`), then prints the next steps. Full walkthrough incl. the bare-PRD.md scenario: the catalog's [ADOPTING.md](../../../ADOPTING.md). The manual steps:
-
-## Steps
-
-1. Copy `.claude/` from this scaffold into the target repo root. If the target already has `.claude/settings.json`, merge the `hooks.PreToolUse` entry instead of overwriting.
-2. Install the catalog's **universal templates** (shared by all patterns — source of truth is the catalog root, not this scaffold): `templates/ticket.template.md` → the target repo's `templates/`; the platform half of `templates/tracker/` → `.github/` (ISSUE_TEMPLATE/ + PULL_REQUEST_TEMPLATE.md) or `.gitlab/` (issue_templates/ + merge_request_templates/). Then fill the PR/MR template's **Constraint check** section with the target repo's CLAUDE.md non-negotiables. Hand-written issues and pipeline PRs now share one format that triage can convert and reviewers can verify.
-3. The write-guard hook needs Node.js ≥ 18 on PATH. It denies main-session Edit/Write with a dispatch instruction; subagent writes pass. Override switch for human-approved out-of-pipeline edits: create `.claude/allow-main-writes`, delete it afterwards — and add that path to `.gitignore`.
-4. The tracker steps (`publish-tickets.mjs`, the deliver stage, `/verify-delivery`, the nightly sweep) need the platform CLI installed and authenticated: `gh` (GitHub) or `glab` (GitLab). The publish script autodetects the platform from the origin remote; override with `--platform gh|glab` (test doubles / non-PATH binaries: `GH_BIN` / `GLAB_BIN` env overrides).
-5. Append the content of `claude-md-snippet.md` to the target repo's `CLAUDE.md`, and set the **Operating mode** line (`supervised` for a fresh adoption; `autonomous` is the target).
-6. Ensure the docs layout the pipeline assumes exists: `docs/PRD.md`, `docs/prd/<module>/README.md` (the sub-PRD — `/start-milestone` hard-requires it), `docs/prd/<module>/tickets/` (author tickets from `templates/ticket.template.md`), `docs/adr/`, and an empty `docs/plans/`.
-7. Check the pattern entry's expiry (README metadata table). If expired, re-verify the model/effort table against current official docs before adopting — do not copy an expired recommendation into a new project.
-
-## Usage modes
-
-- **Mode A — one orchestrator session (default):** run `/plan-ticket` → `/build-ticket` → `/review-ticket` → `/verify-delivery` from a single main session. Each stage executes in its own subagent, so stage contexts stay isolated. The orchestrator passes only artifacts between stages — ticket path, plan path, diff ref — never transcripts or agent self-assessments, and it never does stage work itself (see "Orchestrator discipline" in `claude-md-snippet.md`; role leakage is a recorded failure mode).
-- **Mode B — three human-run sessions:** open a fresh Claude Code session per stage. Strongest isolation; use when the orchestrator session itself has grown long or has seen implementation detail.
-- **Milestone mode (the target operating model):** `/start-milestone <module> [supervised|autonomous]` — Gate 1 in one action: verify inputs, publish tickets as issues, then run all tickets through `.claude/workflows/run-milestone.js`. Each stage still runs in its own subagent; ordering, the bounce cap, and merge policy are code, not prompts. The human returns at Gate 2 (smoke test) or on escalation.
-
-## Nightly sweep (unattended)
-
-- **Entry:** `claude -p "/nightly-issues"` — slash commands expand in headless `-p` mode. `[official]`
-- **Permissions:** pre-approve exactly what the pipeline needs in the target repo's `.claude/settings.json` (`permissions.allow`, e.g. `Bash(git:*)`, `Bash(gh:*)` or `Bash(glab:*)`, `Bash(node:*)`, `Bash(npm:*)`), then run with `--permission-mode dontAsk` — the documented CI recommendation: pre-approved tools run, everything else is auto-denied instead of blocking. Subagents run in `acceptEdits` mode (their file edits are auto-approved). Avoid `bypassPermissions` outside isolated containers (documented warning). `[official]`
-- **Scheduling (Windows, primary):** Task Scheduler — runs whenever the machine is on at the trigger time:
-
-  ```
-  schtasks /create /tn "nightly-issues" /sc daily /st 02:00 ^
-    /tr "cmd /c cd /d C:\path\to\repo && claude -p \"/nightly-issues\" --permission-mode dontAsk >> .claude\nightly.log 2>&1"
-  ```
-
-  macOS/Linux: launchd / cron equivalents.
-- **Why not Claude Code's native cron** (`/loop`, Cron tools): documented constraints — the session must stay open, recurring tasks expire after 7 days, and firings jitter up to 30 minutes — the wrong shape for "machine on, no session open". For no-local-machine automation the docs point to Routines (Anthropic infrastructure) or CI schedules. `[official]`
-- **Morning email:** watch the repo / enable tracker notifications. The sweep posts per-issue outcome comments, labels (`triage:invalid` = flagged invalid, never auto-closed · `nightly:escalated` = won't retry until a human clears it · `needs-human`), closes delivered issues, and files a `Nightly report YYYY-MM-DD` issue — the tracker's own notification email is the delivery mechanism, no SMTP to configure.
-
-## Config-key verification record
-
-`model:` and `effort:` in `.claude/agents/*.md`, and command frontmatter (`description`, `argument-hint`, `$ARGUMENTS`/`$N` substitution), verified against the official Claude Code docs on **2026-07-17**:
-
-- <https://code.claude.com/docs/en/sub-agents.md> — agent frontmatter keys incl. `model` (full IDs and aliases; omitted = inherit) and `effort` (`low`/`medium`/`high`/`xhigh`/`max`); omitted `tools` inherits all tools.
-- <https://code.claude.com/docs/en/skills.md> — command/skill frontmatter incl. `model`, `effort`, `argument-hint`; argument substitution via `$ARGUMENTS` and `$N` (0-based).
-- <https://code.claude.com/docs/en/model-config.md> — effort levels incl. `max`; note the `effortLevel` *setting* accepts `low`–`xhigh` only (`max` is session-only), while agent/command frontmatter `effort` accepts `max`.
-
-Hook mechanism (the main-session write guard), verified **2026-07-17**:
-
-- <https://code.claude.com/docs/en/hooks.md> — PreToolUse settings schema (regex `matcher`, `type: command`); hooks fire for subagent tool calls too; the hook input carries `agent_id`/`agent_type` **only** when the call comes from a subagent, so their absence identifies the main session; deny via stdout JSON `hookSpecificOutput.permissionDecision: "deny"` (the reason string is fed back to the model), or exit code 2.
-- <https://code.claude.com/docs/en/permissions.md> — `permissions.deny` rules apply to subagents as well (subagents inherit the parent's permission stack); **no documented main-session-only permission scope exists**, which is why the guard is a hook rather than a deny rule.
-
-Workflow tool + `ultracode` (for the milestone runner), verified **2026-07-17**:
-
-- <https://code.claude.com/docs/en/workflows> — the Workflow tool (deterministic multi-agent scripts: `export const meta`, `agent()` / `parallel()` / `pipeline()`) is publicly documented; `.claude/workflows/` is the documented project location for saved workflow scripts (also <https://code.claude.com/docs/en/claude-directory>).
-- <https://code.claude.com/docs/en/model-config> — "Ultracode is a Claude Code setting rather than a model effort level": it applies `xhigh` effort plus automatic workflow orchestration. Persistable effort levels are `low`–`xhigh`; `max` and `ultracode` are session-only.
-
-Headless + scheduling facts (for the nightly sweep), verified **2026-07-17**:
-
-- <https://code.claude.com/docs/en/headless.md> — `claude -p "<prompt>"`; slash commands expand in `-p`; `--output-format`, `--max-turns`.
-- <https://code.claude.com/docs/en/permission-modes.md> and <https://code.claude.com/docs/en/permissions.md> — `--permission-mode dontAsk` is the documented CI recommendation (pre-approved tools only, rest auto-denied); `acceptEdits`; `bypassPermissions` only for isolated environments; `--allowedTools`; settings `permissions.allow`; subagents run in `acceptEdits`.
-- <https://code.claude.com/docs/en/workflows.md> — workflows are available in headless `claude -p`.
-- <https://code.claude.com/docs/en/scheduled-tasks.md> and <https://code.claude.com/docs/en/routines.md> — native `/loop`/Cron tools require an open session, recurring tasks expire after 7 days, jitter up to 30 min; Routines run on Anthropic infrastructure.
-
-Re-verify these keys when Claude Code major-versions, or when this record is more than 6 months old.
+# Installing the three-agent scaffold
+
+Source pattern: `agent-templates/patterns/three-agent-architect-builder-reviewer` — read its [README](../README.md) (especially the expiry trigger) before installing.
+
+## Quickstart
+
+From a checkout of the catalog: `node scripts/adopt.mjs three-agent-architect-builder-reviewer <target-dir>` performs steps 1–6 below mechanically (idempotent; `--platform gh|glab`), then prints the next steps. Full walkthrough incl. the bare-PRD.md scenario: the catalog's [ADOPTING.md](../../../ADOPTING.md). The manual steps:
+
+## Steps
+
+1. Copy `.claude/` from this scaffold into the target repo root. If the target already has `.claude/settings.json`, merge the `hooks.PreToolUse` entry instead of overwriting.
+2. Install the catalog's **universal templates** (shared by all patterns — source of truth is the catalog root, not this scaffold): `templates/ticket.template.md` → the target repo's `templates/`; the platform half of `templates/tracker/` → `.github/` (ISSUE_TEMPLATE/ + PULL_REQUEST_TEMPLATE.md) or `.gitlab/` (issue_templates/ + merge_request_templates/). Then fill the PR/MR template's **Constraint check** section with the target repo's CLAUDE.md non-negotiables. Hand-written issues and pipeline PRs now share one format that triage can convert and reviewers can verify.
+3. The write-guard hook needs Node.js ≥ 18 on PATH. It denies main-session Edit/Write with a dispatch instruction; subagent writes pass. Override switch for human-approved out-of-pipeline edits: create `.claude/allow-main-writes`, delete it afterwards — and add that path to `.gitignore`.
+4. The tracker steps (`publish-tickets.mjs`, the deliver stage, `/verify-delivery`, the nightly sweep) need the platform CLI installed and authenticated: `gh` (GitHub) or `glab` (GitLab). The publish script autodetects the platform from the origin remote; override with `--platform gh|glab` (test doubles / non-PATH binaries: `GH_BIN` / `GLAB_BIN` env overrides).
+5. Append the content of `claude-md-snippet.md` to the target repo's `CLAUDE.md`, and set the **Operating mode** line (`supervised` for a fresh adoption; `autonomous` is the target).
+6. Ensure the docs layout the pipeline assumes exists: `docs/PRD.md`, `docs/prd/<module>/README.md` (the sub-PRD — `/start-milestone` hard-requires it), `docs/prd/<module>/tickets/` (author tickets from `templates/ticket.template.md`), `docs/adr/`, and an empty `docs/plans/`.
+7. Check the pattern entry's expiry (README metadata table). If expired, re-verify the model/effort table against current official docs before adopting — do not copy an expired recommendation into a new project.
+
+## Usage modes
+
+- **Mode A — one orchestrator session (default):** run `/plan-ticket` → `/build-ticket` → `/review-ticket` → `/verify-delivery` from a single main session. Each stage executes in its own subagent, so stage contexts stay isolated. The orchestrator passes only artifacts between stages — ticket path, plan path, diff ref — never transcripts or agent self-assessments, and it never does stage work itself (see "Orchestrator discipline" in `claude-md-snippet.md`; role leakage is a recorded failure mode).
+- **Mode B — three human-run sessions:** open a fresh Claude Code session per stage. Strongest isolation; use when the orchestrator session itself has grown long or has seen implementation detail.
+- **Milestone mode (the target operating model):** `/start-milestone <module> [supervised|autonomous]` — Gate 1 in one action: verify inputs, publish tickets as issues, then run all tickets through `.claude/workflows/run-milestone.js`. Each stage still runs in its own subagent; ordering, the bounce cap, and merge policy are code, not prompts. The human returns at Gate 2 (smoke test) or on escalation.
+
+## Nightly sweep (unattended)
+
+- **Entry:** `claude -p "/nightly-issues"` — slash commands expand in headless `-p` mode. `[official]`
+- **Permissions:** pre-approve exactly what the pipeline needs in the target repo's `.claude/settings.json` (`permissions.allow`, e.g. `Bash(git:*)`, `Bash(gh:*)` or `Bash(glab:*)`, `Bash(node:*)`, `Bash(npm:*)`), then run with `--permission-mode dontAsk` — the documented CI recommendation: pre-approved tools run, everything else is auto-denied instead of blocking. Subagents run in `acceptEdits` mode (their file edits are auto-approved). Avoid `bypassPermissions` outside isolated containers (documented warning). `[official]`
+- **Scheduling (Windows, primary):** Task Scheduler — runs whenever the machine is on at the trigger time:
+
+  ```
+  schtasks /create /tn "nightly-issues" /sc daily /st 02:00 ^
+    /tr "cmd /c cd /d C:\path\to\repo && claude -p \"/nightly-issues\" --permission-mode dontAsk >> .claude\nightly.log 2>&1"
+  ```
+
+  macOS/Linux: launchd / cron equivalents.
+- **Why not Claude Code's native cron** (`/loop`, Cron tools): documented constraints — the session must stay open, recurring tasks expire after 7 days, and firings jitter up to 30 minutes — the wrong shape for "machine on, no session open". For no-local-machine automation the docs point to Routines (Anthropic infrastructure) or CI schedules. `[official]`
+- **Morning email:** watch the repo / enable tracker notifications. The sweep posts per-issue outcome comments, labels (`triage:invalid` = flagged invalid, never auto-closed · `nightly:escalated` = won't retry until a human clears it · `needs-human`), closes delivered issues, and files a `Nightly report YYYY-MM-DD` issue — the tracker's own notification email is the delivery mechanism, no SMTP to configure.
+
+## Config-key verification record
+
+`model:` and `effort:` in `.claude/agents/*.md`, and command frontmatter (`description`, `argument-hint`, `$ARGUMENTS`/`$N` substitution), verified against the official Claude Code docs on **2026-07-17**:
+
+- <https://code.claude.com/docs/en/sub-agents.md> — agent frontmatter keys incl. `model` (full IDs and aliases; omitted = inherit) and `effort` (`low`/`medium`/`high`/`xhigh`/`max`); omitted `tools` inherits all tools.
+- <https://code.claude.com/docs/en/skills.md> — command/skill frontmatter incl. `model`, `effort`, `argument-hint`; argument substitution via `$ARGUMENTS` and `$N` (0-based).
+- <https://code.claude.com/docs/en/model-config.md> — effort levels incl. `max`; note the `effortLevel` *setting* accepts `low`–`xhigh` only (`max` is session-only), while agent/command frontmatter `effort` accepts `max`.
+
+Hook mechanism (the main-session write guard), verified **2026-07-17**:
+
+- <https://code.claude.com/docs/en/hooks.md> — PreToolUse settings schema (regex `matcher`, `type: command`); hooks fire for subagent tool calls too; the hook input carries `agent_id`/`agent_type` **only** when the call comes from a subagent, so their absence identifies the main session; deny via stdout JSON `hookSpecificOutput.permissionDecision: "deny"` (the reason string is fed back to the model), or exit code 2.
+- <https://code.claude.com/docs/en/permissions.md> — `permissions.deny` rules apply to subagents as well (subagents inherit the parent's permission stack); **no documented main-session-only permission scope exists**, which is why the guard is a hook rather than a deny rule.
+
+Workflow tool + `ultracode` (for the milestone runner), verified **2026-07-17**:
+
+- <https://code.claude.com/docs/en/workflows> — the Workflow tool (deterministic multi-agent scripts: `export const meta`, `agent()` / `parallel()` / `pipeline()`) is publicly documented; `.claude/workflows/` is the documented project location for saved workflow scripts (also <https://code.claude.com/docs/en/claude-directory>).
+- <https://code.claude.com/docs/en/model-config> — "Ultracode is a Claude Code setting rather than a model effort level": it applies `xhigh` effort plus automatic workflow orchestration. Persistable effort levels are `low`–`xhigh`; `max` and `ultracode` are session-only.
+
+Headless + scheduling facts (for the nightly sweep), verified **2026-07-17**:
+
+- <https://code.claude.com/docs/en/headless.md> — `claude -p "<prompt>"`; slash commands expand in `-p`; `--output-format`, `--max-turns`.
+- <https://code.claude.com/docs/en/permission-modes.md> and <https://code.claude.com/docs/en/permissions.md> — `--permission-mode dontAsk` is the documented CI recommendation (pre-approved tools only, rest auto-denied); `acceptEdits`; `bypassPermissions` only for isolated environments; `--allowedTools`; settings `permissions.allow`; subagents run in `acceptEdits`.
+- <https://code.claude.com/docs/en/workflows.md> — workflows are available in headless `claude -p`.
+- <https://code.claude.com/docs/en/scheduled-tasks.md> and <https://code.claude.com/docs/en/routines.md> — native `/loop`/Cron tools require an open session, recurring tasks expire after 7 days, jitter up to 30 min; Routines run on Anthropic infrastructure.
+
+Re-verify these keys when Claude Code major-versions, or when this record is more than 6 months old.

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

@@ -1,37 +1,38 @@
-<!-- Append this block to the target repo's CLAUDE.md.
-     Source pattern: agent-templates/patterns/three-agent-architect-builder-reviewer (as of 2026-07-17). -->
-
-## Delivery pipeline — three-agent Architect / Builder / Reviewer
-
-**Operating mode: `supervised`** <!-- switch to `autonomous` once the pattern holds on this repo -->
-
-- `supervised` — a human confirms each merge and each tracker close; issue **creation** is authorized by the `/start-milestone` sign-off itself. The milestone runner stops after each CLEAR verdict for the human merge — re-run `/start-milestone` to continue (closed issues are skipped). Use for a fresh adoption.
-- `autonomous` (target) — humans decide at exactly two gates: Gate 1, sign-off of master PRD → sub-PRDs → tickets before the pipeline starts; Gate 2, a smoke test of the delivered milestone. Between them the pipeline self-drives: merge on CLEAR, `/verify-delivery` repairs gaps (including closing the issue) automatically. A human is pulled in only on the exception path — 2 bounce cycles without convergence, a failed build, or an unrepairable verify-delivery item.
-
-Every non-trivial ticket flows through three stages; no agent judges its own work.
-
-- **`/breakdown-prd [notes]`** — pre-Gate-1: the Architect decomposes `docs/PRD.md` into a breakdown plan + sub-PRDs + template-compliant tickets (disjoint file-scopes, dependency DAG), then stops for human review.
-- **`/plan-ticket <ticket>`** — Architect (`claude-sonnet-5` @ `xhigh`) reads the ticket + codebase → implementation plan at `docs/plans/<ticket-id>.md`. Writes no production code.
-- **`/build-ticket <ticket>`** — Builder (`claude-opus-4-8` @ `xhigh`) implements the plan, runs tests until green, records deviations. Never merges or self-clears.
-- **`/review-ticket <ticket>`** — Reviewer (`claude-fable-5` @ `max`) in a **fresh context**, deliberately a different model tier from the Builder. Focus: edge cases, concurrency, security-sensitive paths. Verdict **CLEAR** or **BOUNCE**; merge requires CLEAR.
-- **`/verify-delivery <ticket>`** — post-merge Definition-of-Done check: plan on disk · tests green · CLEAR verdict · MR merged into the default branch · **tracker issue closed** · writeback done. Run after **every** merge; tracker auto-close side effects are never trusted blindly.
-- **`/start-milestone <module> [mode]`** — the Gate 1 start signal: verify sub-PRD + tickets, publish tickets as tracker issues (deterministic idempotent script — agents never hand-create issues), then run every ticket through the deterministic `run-milestone` workflow (stage order, bounce cap, merge policy enforced in code).
-- **`/nightly-issues [max]`** — unattended sweep (OS-scheduled, `claude -p`): triage open issues → auto-fix fixable ones through the pipeline → per-issue comments + labels + a `Nightly report <date>` issue for the morning read. Invalid issues are labeled `triage:invalid`, never auto-closed. Setup: scaffold INSTALL.md § Nightly sweep.
-
-Orchestrator discipline (hard rules for the main session):
-
-- The main session **orchestrates only**: it invokes the stage commands and relays artifacts (ticket path, plan path, diff ref). It never plans, implements, or reviews a ticket inline — that work belongs to the stage subagents, whatever the size of the change.
-- If a stage subagent fails or is unavailable, report the failure and stop. **Never absorb its role.**
-- This is **mechanically enforced**: a PreToolUse guard (`.claude/hooks/guard-main-session-writes.mjs`) denies Edit/Write in the main session; subagent calls pass. For a human-approved out-of-pipeline edit, create `.claude/allow-main-writes` (git-ignored) and delete it afterwards.
-- Known guard boundary: Bash is not covered. Bash in the main session is for orchestration only (git, tracker CLI, running commands) — never for writing files (`echo >`, `git apply`, heredocs). The guard stops reflexive edits, not determined bypasses; this rule covers the rest.
-- A ticket is done only when `/verify-delivery` passes all items — "the MR is merged" is not done (known failure: MRs merged with issues left open, observed 2026-07-17).
-
-Rules:
-
-- The Reviewer never runs in the Builder's session and never edits code; it receives only the ticket, the plan, and the diff ref — never transcripts.
-- Maximum 2 bounce cycles, then escalate to a human.
-- Trivial/mechanical changes may skip the pipeline only with an explicit human OK.
-- Ticket files are the issue-content source of truth. Issues are created only by `.claude/scripts/publish-tickets.mjs` (`[<id>]` title prefix = dedupe key); to change an issue body, edit the ticket file and republish. Issue state (close) moves via the deliver step / `/verify-delivery`, never by hand mid-pipeline.
-- Agents own the whole test pyramid: the Builder writes and runs unit + integration tests (and E2E where the ticket's acceptance calls for it); the Reviewer re-runs the full suite independently; the deliver step re-runs it on the merged default branch. The human tests exactly once — the Gate 2 smoke test after the PRD's tasks are all done.
-- **Pattern-level problems go upstream, not here.** If the pipeline itself misbehaves (a role boundary misfits, a model/effort pin looks stale, an orchestration bug), file an issue against the pattern catalog — `gh issue create --repo Ruihang2017/agent-templates` using its issue templates — so the catalog's own nightly sweep triages it. Project bugs stay in this repo's tracker.
-- Model/effort per role are pinned in `.claude/agents/*.md`. Change them by updating the pattern entry in agent-templates first (new as-of date + provenance entry), then syncing here — never by editing only this repo.
+<!-- Append this block to the target repo's CLAUDE.md.
+     Source pattern: agent-templates/patterns/three-agent-architect-builder-reviewer (as of 2026-07-17). -->
+
+## Delivery pipeline — three-agent Architect / Builder / Reviewer
+
+**Operating mode: `supervised`** <!-- switch to `autonomous` once the pattern holds on this repo -->
+
+- `supervised` — a human confirms each merge and each tracker close; issue **creation** is authorized by the `/start-milestone` sign-off itself. The milestone runner stops after each CLEAR verdict for the human merge — re-run `/start-milestone` to continue (closed issues are skipped). Use for a fresh adoption.
+- `autonomous` (target) — humans decide at exactly two gates: Gate 1, sign-off of master PRD → sub-PRDs → tickets before the pipeline starts; Gate 2, a smoke test of the delivered milestone. Between them the pipeline self-drives: merge on CLEAR, `/verify-delivery` repairs gaps (including closing the issue) automatically. A human is pulled in only on the exception path — 2 bounce cycles without convergence, a failed build, or an unrepairable verify-delivery item.
+
+Every non-trivial ticket flows through three stages; no agent judges its own work.
+
+- **`/breakdown-prd [notes]`** — pre-Gate-1: the Architect decomposes `docs/PRD.md` into a breakdown plan + sub-PRDs + template-compliant tickets (disjoint file-scopes, dependency DAG), then stops for human review.
+- **`/plan-ticket <ticket>`** — Architect (`claude-sonnet-5` @ `xhigh`) reads the ticket + codebase → implementation plan at `docs/plans/<ticket-id>.md`. Writes no production code.
+- **`/build-ticket <ticket>`** — Builder (`claude-opus-4-8` @ `xhigh`) implements the plan, runs tests until green, records deviations. Never merges or self-clears.
+- **`/review-ticket <ticket>`** — Reviewer (`claude-fable-5` @ `max`) in a **fresh context**, deliberately a different model tier from the Builder. Focus: edge cases, concurrency, security-sensitive paths. Verdict **CLEAR** or **BOUNCE**; merge requires CLEAR.
+- **`/verify-delivery <ticket>`** — post-merge Definition-of-Done check: plan on disk · tests green · CLEAR verdict · MR merged into the default branch · **tracker issue closed** · writeback done. Run after **every** merge; tracker auto-close side effects are never trusted blindly.
+- **`/start-milestone <module> [mode]`** — the Gate 1 start signal: verify sub-PRD + tickets, publish tickets as tracker issues (deterministic idempotent script — agents never hand-create issues), then run every ticket through the deterministic `run-milestone` workflow (stage order, bounce cap, merge policy enforced in code).
+- **`/start-all [mode]`** — Gate 1 for the **whole PRD**: compute the module DAG from ticket `blocked_by` frontmatter (`milestone-dag.mjs`, deterministic — cycles and dangling refs fail loudly), publish every module, then drive all modules through `run-milestone` in dependency order. Failed modules block their dependents; independent branches continue in `autonomous`; anything short of a CLEAR stops everything in `supervised`. Re-run to resume — fully-closed modules skip as already-complete.
+- **`/nightly-issues [max]`** — unattended sweep (OS-scheduled, `claude -p`): triage open issues → auto-fix fixable ones through the pipeline → per-issue comments + labels + a `Nightly report <date>` issue for the morning read. Invalid issues are labeled `triage:invalid`, never auto-closed. Setup: scaffold INSTALL.md § Nightly sweep.
+
+Orchestrator discipline (hard rules for the main session):
+
+- The main session **orchestrates only**: it invokes the stage commands and relays artifacts (ticket path, plan path, diff ref). It never plans, implements, or reviews a ticket inline — that work belongs to the stage subagents, whatever the size of the change.
+- If a stage subagent fails or is unavailable, report the failure and stop. **Never absorb its role.**
+- This is **mechanically enforced**: a PreToolUse guard (`.claude/hooks/guard-main-session-writes.mjs`) denies Edit/Write in the main session; subagent calls pass. For a human-approved out-of-pipeline edit, create `.claude/allow-main-writes` (git-ignored) and delete it afterwards.
+- Known guard boundary: Bash is not covered. Bash in the main session is for orchestration only (git, tracker CLI, running commands) — never for writing files (`echo >`, `git apply`, heredocs). The guard stops reflexive edits, not determined bypasses; this rule covers the rest.
+- A ticket is done only when `/verify-delivery` passes all items — "the MR is merged" is not done (known failure: MRs merged with issues left open, observed 2026-07-17).
+
+Rules:
+
+- The Reviewer never runs in the Builder's session and never edits code; it receives only the ticket, the plan, and the diff ref — never transcripts.
+- Maximum 2 bounce cycles, then escalate to a human.
+- Trivial/mechanical changes may skip the pipeline only with an explicit human OK.
+- Ticket files are the issue-content source of truth. Issues are created only by `.claude/scripts/publish-tickets.mjs` (`[<id>]` title prefix = dedupe key); to change an issue body, edit the ticket file and republish. Issue state (close) moves via the deliver step / `/verify-delivery`, never by hand mid-pipeline.
+- Agents own the whole test pyramid: the Builder writes and runs unit + integration tests (and E2E where the ticket's acceptance calls for it); the Reviewer re-runs the full suite independently; the deliver step re-runs it on the merged default branch. The human tests exactly once — the Gate 2 smoke test after the PRD's tasks are all done.
+- **Pattern-level problems go upstream, not here.** If the pipeline itself misbehaves (a role boundary misfits, a model/effort pin looks stale, an orchestration bug), file an issue against the pattern catalog — `gh issue create --repo Ruihang2017/agent-templates` using its issue templates — so the catalog's own nightly sweep triages it. Project bugs stay in this repo's tracker.
+- Model/effort per role are pinned in `.claude/agents/*.md`. Change them by updating the pattern entry in agent-templates first (new as-of date + provenance entry), then syncing here — never by editing only this repo.