create-issflow 1.2.0 → 1.4.0

package/README.md

@@ -25,9 +25,9 @@ Flags:
 The portable kit (every tool) in `<project>/.claude/`:
 
 - `agents/` — planner · researcher · implementer · test-author · debugger · e2e-runner · synthesizer
-- `commands/` — `/overview` `/propose` `/phase` `/ui-audit` `/qa-audit` `/security-audit` `/change-request` `/replan` `/quick` `/synthesize` `/store-wisdom` `/log-issue` `/log-decision` `/unstuck`
-- `skills/` — caveman · grill-me · karpathy-guidelines · ux-design
-- `hooks/` — session-start · pre-compact · subagent-stop
+- `commands/` — `/overview` `/propose` `/phase` `/sprint` `/ui-audit` `/qa-audit` `/security-audit` `/release` `/uat` `/change-request` `/replan` `/quick` `/synthesize` `/runbook` `/store-wisdom` `/log-issue` `/log-decision` `/unstuck`
+- `skills/` — caveman · grill-me · karpathy-guidelines · ux-design · security · code-standards
+- `hooks/` — session-start · context-guard · pre-compact · subagent-stop
 - `istartsoft-flow/METHODOLOGY.md` — the full methodology (single source of truth)
 
 Plus a root `AGENTS.md` (the open standard) and the per-tool adapter:

package/bin/cli.js

@@ -107,8 +107,21 @@ function copyTemplateCommands(destDir) {
 // ---- adapters (keep the methodology single-source — these POINT at it) ------
 
 function adapterClaude() {
+  // Claude Code auto-loads CLAUDE.md only — NOT AGENTS.md. Without a CLAUDE.md
+  // the methodology never enters context on its own (the SessionStart hook still
+  // injects the per-session summary, but the full single-source doc would not
+  // load). A one-line `@AGENTS.md` import gives Claude Code the full baseline
+  // while keeping ONE source of truth — no rule is restated here (anti-drift).
+  const c0 = conflicts;
+  writeFile('CLAUDE.md', claudeMd());
+  if (conflicts > c0) warnings.push('claude: you already keep a CLAUDE.md — ours was written as CLAUDE.md.issflow-new. Add a line `@AGENTS.md` to your CLAUDE.md so the methodology auto-loads.');
+  // Context-budget watchdog config (consumed by .claude/hooks/context-guard.js).
+  // Shipped default window:0 = auto-detect; flow-config.json lives at .claude root,
+  // outside build.js's copied DIRS, so the installer writes it here.
+  writeFile('.claude/flow-config.json', flowConfig());
   const HOOKS = {
     SessionStart: [{ matcher: 'startup|clear|compact', hooks: [{ type: 'command', command: 'node .claude/hooks/session-start.js' }] }],
+    PreToolUse:   [{ matcher: '*',                     hooks: [{ type: 'command', command: 'node .claude/hooks/context-guard.js' }] }],
     PreCompact:   [{ matcher: 'auto|manual',           hooks: [{ type: 'command', command: 'node .claude/hooks/pre-compact.js' }] }],
     SubagentStop: [{ hooks: [{ type: 'command', command: 'node .claude/hooks/subagent-stop.js' }] }],
   };
@@ -176,7 +189,7 @@ function adapterAider() {
 const ADAPTERS = { claude: adapterClaude, codex: adapterCodex, cursor: adapterCursor, gemini: adapterGemini, aider: adapterAider };
 
 const NEXT_STEPS = {
-  claude: 'Open Claude Code — the SessionStart hook fires automatically. Run /overview to bootstrap.',
+  claude: 'Open Claude Code — CLAUDE.md (@AGENTS.md) loads the methodology and the SessionStart hook fires automatically. Run /overview to bootstrap.',
   codex:  'Open Codex CLI — it reads AGENTS.md. Start by running the /overview procedure (.claude/commands/overview.md).',
   cursor: 'Open Cursor — the rule applies automatically. Run the /overview command to bootstrap.',
   gemini: 'Open Gemini CLI — it reads GEMINI.md. Run the SESSION-OPEN ritual, then the overview procedure.',
@@ -198,9 +211,9 @@ function agentsMd() {
     '## Roles — `.claude/agents/`', '',
     'planner · researcher · implementer · test-author · debugger · e2e-runner · synthesizer', '',
     '## Procedures — `.claude/commands/` (run as `/name`)', '',
-    '/overview · /propose · /phase · /ui-audit · /qa-audit · /security-audit ·',
-    '/change-request · /replan · /quick · /synthesize · /store-wisdom · /log-issue ·',
-    '/log-decision · /unstuck', '',
+    '/overview · /propose · /phase · /sprint · /ui-audit · /qa-audit · /security-audit · /release ·',
+    '/uat · /change-request · /replan · /quick · /synthesize · /runbook · /store-wisdom ·',
+    '/log-issue · /log-decision · /unstuck', '',
     '## Skills — `.claude/skills/` (loaded on demand)', '',
     'caveman · grill-me · karpathy-guidelines · ux-design · security (Secure SDLC) · code-standards', '',
     '## Autonomy', '',
@@ -217,7 +230,8 @@ function agentsMd() {
     'change · 9 UI conforms to the `ux-design` cookbook + wireframe frame · 10 no-rationalization ·',
     '11 Secure SDLC: threat-model → secure coding → SAST/SCA/secrets each phase → pentest',
     'gate + security review before deploy (`security` skill) · 12 code-standards gate:',
-    'lint/format clean + naming per language idiom + declared architecture (`code-standards`).', '',
+    'lint/format clean + naming per language idiom + declared architecture (`code-standards`) ·',
+    '13 PLAN-APPROVAL gate: no phase/sprint starts until `docs/PLAN.md` is human-approved.', '',
     '## Your stack', '',
     'Declare your stack (language, framework, infra, auth, test + E2E runner,',
     'planning source) once in `docs/OVERVIEW.md`. Every rule references *your declared',
@@ -225,6 +239,40 @@ function agentsMd() {
   ].join('\n');
 }
 
+function claudeMd() {
+  return [
+    '# CLAUDE.md — iStartSoftFlow (Claude Code entry)', '',
+    '@AGENTS.md', '',
+    'The import above is the single source of truth — it points to',
+    '`.claude/istartsoft-flow/METHODOLOGY.md` (read on demand). Do NOT restate any',
+    'rule here; this file only wires Claude-native mechanisms (anti-drift invariant).', '',
+    '## Claude-native wiring (automatic — see `.claude/settings.json`)', '',
+    '- **SessionStart** hook injects git state + `docs/STATE.md` + open `docs/ISSUES.md`',
+    '  + the rule summary each session — read those first.',
+    '- **PreCompact** + **SubagentStop** hooks run their rituals automatically.',
+    '- Commands in `.claude/commands/` run as `/name`; agents in `.claude/agents/` are',
+    '  native subagents.', '',
+  ].join('\n');
+}
+
+function flowConfig() {
+  return JSON.stringify({
+    context: {
+      window: 0,
+      warnPct: 60,
+      gatePct: 78,
+      _note: 'Context-budget watchdog (.claude/hooks/context-guard.js, PreToolUse hook). '
+        + 'window 0 = auto-detect from the model id (200000 for standard models). '
+        + 'Some 1M-context models report their id WITHOUT a [1m] tag, so auto-detect '
+        + 'assumes 200000 and may false-gate around 156k — if you run a 1M model, set '
+        + 'window:1000000 here by hand. warnPct = soft non-blocking nudge; gatePct = hard '
+        + 'block on NEW build work (Edit/Write-to-source/feature Task). Checkpoint paths '
+        + '(docs/**, STATE/ISSUES/snapshots), the synthesizer subagent, and all Bash are '
+        + 'never blocked.',
+    },
+  }, null, 2) + '\n';
+}
+
 // ---- main -------------------------------------------------------------------
 
 function main() {
@@ -243,6 +291,13 @@ function main() {
     writeFile(rel, fs.readFileSync(src, 'utf8'));
   }
 
+  // 1b. integrity: confirm the methodology resolved on disk (load-bearing sentinel).
+  const methPath = path.join(CWD, '.claude', 'istartsoft-flow', 'METHODOLOGY.md');
+  const SENTINEL = 'ISTARTSOFTFLOW-AGENTS-SENTINEL-v2.0';
+  if (!DRY && (!fs.existsSync(methPath) || !fs.readFileSync(methPath, 'utf8').includes(SENTINEL))) {
+    warnings.push(`integrity: ${SENTINEL} not found in installed METHODOLOGY.md — the kit may be incomplete; re-run create-issflow (or npm run build from source).`);
+  }
+
   // 2. AGENTS.md — the open-standard entry point.
   writeFile('AGENTS.md', agentsMd());
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-issflow",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Scaffold the iStartSoftFlow AI-coding workflow into a project. Stack-agnostic, tool-agnostic (Claude Code, Codex, Cursor, Gemini, Aider), non-destructive.",
   "bin": {
     "create-issflow": "bin/cli.js"

package/template/.claude/agents/e2e-runner.md

@@ -1,5 +1,6 @@
 ---
 name: e2e-runner
+description: Writes and runs functional browser E2E (your declared E2E runner, e.g. Playwright) BLIND — reads only the acceptance spec + docs/ENDPOINTS.md, never the implementation. Writes a trace to docs/research/e2e-<phase-slug>.md; returns a terse summary.
 tools: Read, Grep, Glob, Write, Bash
 model: opus
 ---

package/template/.claude/agents/planner.md

@@ -43,6 +43,12 @@ window. If a phase feels big, split it.
   money, or PII), add a `security:` note: threat-model it (STRIDE) and fold abuse
   cases into the acceptance criteria as negative cases; set the ASVS level (default
   L2). This is the design stage of the Secure SDLC (`security` skill).
+- SPRINT-READY (so the optional `/sprint` layer needs no rework): give every phase a
+  relative effort estimate `[N pts]` (Fibonacci 1/2/3/5/8) in its header, and group
+  consecutive phases under `## Sprint <n>: <name>  [goal: <one-line increment>]`
+  headers — each sprint a coherent, demoable theme of a few phases. If you cannot
+  size a sprint yet, still tag the points; `/sprint plan` will do the grouping from
+  the points + capacity. A phase that feels `>8 pts` is too big — split it.
 
 LAST PHASE RULE — the final code phase (the highest-numbered phase you write)
 MUST contain a deployment task block:
@@ -61,11 +67,19 @@ docs/PLAN.md format:
 
 # Plan: <project>
 <!-- infra: managed (Phase 0 N/A) | self-managed (Phase 0 below) -->
+> Approval: PENDING  (hard rule 13 — PLAN-APPROVAL gate; no phase/sprint runs until a human signs this off via the `/overview` gate)
+
+Keep the header VALUE a single leading token — `PENDING` here, later
+`approved <date> v<n>` — so the gate readers (`/phase`, `/sprint`) match the first
+token unambiguously. Do not put prose containing the word `approved` after a
+`PENDING` value, or a substring check could false-pass the gate.
 
 ## Phase 0: infra setup  [status: pending]   ← omit entirely if infra is managed
 
 
-## Phase 1: <name>  [status: pending]
+## Sprint 1: <name>  [goal: <one-line user-visible increment>]   ← sprint headers optional; group a few phases
+
+## Phase 1: <name>  [5 pts]  [status: pending]
 
 - slice: <what works end-to-end after this phase>
 - rationale: <why this slice, why now — the user / business value (from the PRD)>
@@ -90,4 +104,5 @@ docs/PLAN.md format:
 
 ```
 Order phases by dependency. Phase 0 first IF infra is self-managed; otherwise
-start at Phase 1. Stop. Do not implement.
+start at Phase 1. Always write the `> Approval: PENDING` header — the plan is unapproved
+until the `/overview` PLAN-APPROVAL gate stamps it (hard rule 13). Stop. Do not implement.

package/template/.claude/agents/synthesizer.md

@@ -21,6 +21,9 @@ Do NOT touch docs/ENDPOINTS.md — owned by implementer.
    - what was just completed (1-3 bullets)
    - the immediate next action
    - any open blocker
+   PRESERVE verbatim (never blank on rewrite): the `plan:` line (the PLAN-APPROVAL
+   sign-off record, hard rule 13) and the `sprint:` line (active-sprint marker) if
+   present — load-bearing gate/standup state, not transient progress.
    Target: under 25 lines.
 
 2. ISSUES.md — dedup + compress:

package/template/.claude/agents/test-author.md

@@ -31,8 +31,12 @@ peek at, your blindness is STRUCTURAL, not honor-system.
 
 ## TWO SUITES — write BOTH
 
-1. MOCK suite — fast, no external dependency. Mocks ONLY the external boundary.
-   No mocks on the external boundary. Code/API-level — not browser E2E.
+1. MOCK suite — fast, no external dependency. Mocks ONLY the external boundary
+   (the network / 3rd-party seam). Code/API-level — not browser E2E.
+2. REAL API suite — the SAME tests with no mocks, hitting the real external
+   boundary. The phase gate runs against THIS suite (rules 5–6); a green mock
+   suite alone can never close a phase. Mock vs real is a fixture/env FLAG on the
+   same test (see Test placement), not a duplicated file.
 
 ## Test placement (regression layout)
 

package/template/.claude/commands/change-request.md

@@ -44,7 +44,10 @@ gate — always interactive).
 - **Approved** -> set CR status `approved`; bump PROPOSAL.md to a new version (vN+1)
   with the delta folded in; re-render `docs/proposal.html` from it (same template +
   language); then dispatch `/replan` to apply the phase changes to PLAN.md (done
-  phases stay frozen). Update STATE.md.
+  phases stay frozen). Update STATE.md. NOTE: `/replan` reverts PLAN.md to
+  `> Approval: PENDING` and re-runs the PLAN-APPROVAL gate (hard rule 13) — the
+  commercial CR sign-off is SEPARATE from the plan sign-off, so `/phase` and
+  `/sprint` stay blocked until you also re-approve the revised plan.
 - **Rejected** -> set CR status `rejected`; PLAN + PROPOSAL unchanged.
 
 ## STEP 6 — RECORD

package/template/.claude/commands/overview.md

@@ -75,6 +75,20 @@ Store the round-1 answers as working context — do NOT write OVERVIEW.md yet.
 
 ---
 
+### Foundations sign-off (confirm BEFORE planning)
+
+5b. Before the `planner` runs, present the FOUNDATIONS for explicit human confirmation
+— the whole plan is built on these, so lock them first. Show a concise summary and
+STOP for sign-off (planning always asks, both modes):
+- **Tech stack** — language · framework · infra · auth · datastore · test + E2E runner
+- **Architecture** — the pattern (Feature-Based by default) + the folder layout
+- **UX direction** — design system / tokens + the wireframe baseline (the frame)
+- **Data & integrations** — core data model + external services + their limits
+- **Conventions** — naming idiom (`code-standards`) + autonomy mode (AUTO / GUIDED)
+- **Estimation config** — unit · rate card · currency · contingency (if quoting)
+On any "change X" → revise OVERVIEW.md and re-confirm. Only a signed-off foundation
+proceeds to the planner. (This is the planning confirmation gate.)
+
 ### Plan
 
 6. Hand OVERVIEW.md + design-research findings to the `planner` subagent.
@@ -89,6 +103,7 @@ Store the round-1 answers as working context — do NOT write OVERVIEW.md yet.
 # STATE
 
 phase: 0 (pending)
+plan: PENDING
 completed: project bootstrapped — design research done, double grill done
 blocker: none
 
@@ -97,17 +112,31 @@ blocker: none
 
 9. Create empty docs/HISTORY.md.
 
-
-11. Create docs/ENDPOINTS.md:
+10. Create docs/ENDPOINTS.md:
  ```
  # Endpoints — <project name>
  > Maintained by implementer. Updated each phase.
  > Base URL: (populated after deployment phase)
  ```
 
-Then stop and show me PLAN.md for approval before any phase starts. Planning ends
-with a human sign-off in both modes; AUTO only governs the development loop that
-runs AFTER the plan is approved.
+---
+
+### PLAN-APPROVAL gate (hard rule 13 — always interactive, both modes)
+
+11. The plan is the contract the whole AUTO dev loop builds against, so it ends with a
+    human sign-off — the planning twin of the `/propose` commercial gate.
+
+    - SHOW me PLAN.md (and note any open risks the planner flagged). **STOP for approval.**
+    - On **approval**: record the sign-off in three places —
+      1. stamp the PLAN.md header `> Approval: approved <YYYY-MM-DD> v1`;
+      2. set `plan: approved <YYYY-MM-DD>` in docs/STATE.md;
+      3. append `<YYYY-MM-DD> plan v1 approved` to docs/HISTORY.md (date-first, to
+         match the other HISTORY lines).
+      Only now may `/phase` / `/sprint` run.
+    - On **rejection / change**: revise (re-run the `planner`, or `/replan`), bump the
+      version, and re-show. The header stays `PENDING` until I approve.
+
+    AUTO governs the development loop that runs AFTER this gate, never the gate itself.
 
 Optional next step (client / quoted work only): run `/propose` to turn this
 OVERVIEW + PLAN into a proposal + estimate for sign-off before building. Internal or

package/template/.claude/commands/phase.md

@@ -14,12 +14,17 @@ Target phase: $ARGUMENTS  (default: the phase marked pending in docs/PLAN.md)
 
 ## 0. PRE-FLIGHT
 
-a. INFRA CHECK (phases > 0): Read the declared infra in docs/OVERVIEW.md.
+a. PLAN-APPROVAL CHECK (hard rule 13): Read the docs/PLAN.md `> Approval:` header.
+   Still `PENDING` (or no header) -> STOP. The plan is not signed off; no phase may
+   start. Route me to the `/overview` PLAN-APPROVAL gate (or `/replan` then re-approve).
+   Approved -> continue.
+
+b. INFRA CHECK (phases > 0): Read the declared infra in docs/OVERVIEW.md.
    - Managed infra -> confirm it is reachable; no provisioning step is needed.
    - Self-managed infra -> confirm Phase 0 (infra) ran and is healthy.
    Surface infra + auth status before any work. Blocked infra -> STOP.
 
-b. PHASE STATE CHECK: Read docs/STATE.md and docs/PLAN.md.
+c. PHASE STATE CHECK: Read docs/STATE.md and docs/PLAN.md.
    - No phase in progress, requested is next pending -> START at step 1.
    - Same phase in-progress -> RESUME from STATE.md "next action".
    - Different phase in-progress -> STOP. Tell me which phase is open.
@@ -27,7 +32,7 @@ b. PHASE STATE CHECK: Read docs/STATE.md and docs/PLAN.md.
      phase in PLAN order. GUIDED: STOP, warn, proceed only if I confirm.
    - Phase not in PLAN.md -> STOP. Suggest /overview or /replan.
 
-c. FINAL PHASE CHECK: Read docs/PLAN.md. Is this the last phase (no further
+d. FINAL PHASE CHECK: Read docs/PLAN.md. Is this the last phase (no further
    pending phases after this one)? Record this as IS_FINAL_PHASE=true/false.
 
 
@@ -181,6 +186,12 @@ SECURITY GATE (rule 11 — Secure SDLC build stage):
 
 Mark phase `done` in docs/PLAN.md.
 
+SPRINT STANDUP (if a sprint is active — STATE.md shows `sprint: <n> (active)`):
+fire the `/sprint standup` tick — append the one-line standup to
+docs/sprints/sprint-<n>.md and update the burndown (rule: SPRINT-STANDUP ritual).
+If all the sprint's committed phases are now done/blocked, recommend `/sprint review`
+(or, under `/sprint run`, the driver proceeds to review automatically).
+
 ARCHITECTURE SELF-CHECK: did this phase add/remove/rename an agent, hook, or
 command, or change a workflow rule? YES -> run `/log-decision`. NO -> state why not.
 
@@ -221,10 +232,12 @@ After each step, update docs/STATE.md:
 ```
 
 phase: <n> (in progress)
+plan: approved <date>          ← carry forward; never drop the rule-13 sign-off record
 tdd: <true|false>
 completed: <steps done so far>
 next: <exact next step>
 blocker: <none or open issue>
 
 ```
-Keep STATE.md small — overwrite, do not append.
+Keep STATE.md small — overwrite, do not append. Preserve the `plan:` line on every
+overwrite (the PLAN-APPROVAL record, hard rule 13); do not blank it.

package/template/.claude/commands/propose.md

@@ -13,6 +13,12 @@ A proposal is a commercial gate: always interactive (both AUTO and GUIDED).
 Read `docs/OVERVIEW.md` (scope, stack, success criteria) and `docs/PRD.md` if
 present (else the PRD in your BMAD/iSSM). No OVERVIEW -> run `/overview` first.
 
+PLAN-APPROVAL CHECK (hard rule 13): the proposal prices the *approved* phases, so
+the plan is signed off first (lifecycle: plan → proposal). If `docs/PLAN.md` exists
+and its `> Approval:` header still reads `PENDING` (or is missing), STOP and route me
+to the `/overview` PLAN-APPROVAL gate before quoting — pricing an unapproved plan
+re-prices on every revision.
+
 ## STEP 1 — SCOPE
 List the deliverables (features / epics) from OVERVIEW / PRD. Mark each
 **in-scope** or **out-of-scope** explicitly — naming out-of-scope items now is what
@@ -57,12 +63,13 @@ change-orders re-price against.
 ## Sign-off     — approved by: ___  date: ___  version: v1
 ```
 2. RENDER a client-facing `docs/proposal.html` from `.claude/templates/proposal.html`:
-   copy it, replace every `{{PLACEHOLDER}}`, and LOCALISE all labels + content to the
-   declared language (natural Thai for Thai projects; keep tech terms in English).
-   Fill `{{COMPANY}}` / `{{LOGO}}` from the ISSUING company's brand declared in
-   OVERVIEW (or ask once) — the template is white-label, never hardcode the kit's
-   name. It is print-ready (Save as PDF). Keep PROPOSAL.md and proposal.html in sync —
-   the markdown is the source, the HTML is the deliverable you send the client.
+   copy it, replace every `{{PLACEHOLDER}}`, and fill the CONTENT in the declared
+   language (the section labels are already bilingual TH / EN). It must fit ONE A4
+   page — be terse (≈ 3–6 phase rows, ≈ 4 assumptions, short scope items); trim before
+   it spills to a second page. Fill `{{COMPANY}}` / `{{COMPANY_TAGLINE}}` / `{{LOGO}}`
+   from the ISSUING company's brand declared in OVERVIEW (or ask once) — white-label,
+   never hardcode the kit's name. Print-ready (Ctrl/Cmd-P → A4 → Save as PDF). Keep
+   PROPOSAL.md (source) and proposal.html (deliverable) in sync.
 
 ## STEP 6 — SIGN-OFF GATE
 Show me the proposal. **STOP for approval** (commercial gate — always interactive).

package/template/.claude/commands/quick.md

@@ -14,7 +14,7 @@ Use `/quick` when ALL hold:
 - not mid-phase
 
 If any fail -> STOP, tell me, recommend `/phase`.
-(Hard rule 11: never route phase-worthy work through `/quick` to dodge the RED gate.)
+(Hard rule 10: never route phase-worthy work through `/quick` to dodge the RED gate.)
 
 Steps:
 1. grep docs/ISSUES.md for anything related.

package/template/.claude/commands/release.md

@@ -0,0 +1,51 @@
+---
+description: Pre-production release pipeline — after all build phases, run the full automated gauntlet (full regression: functional / integration / e2e · all audits: UI / QA / security / code · smoke test), then hand off to manual UAT, drive the defect loop to green, produce a sign-off document, and promote to production. The automated SDLC backbone; production deploy is a human-signed hard-stop.
+argument-hint: [optional: target env]
+---
+
+Caveman ULTRA mode. You are the ORCHESTRATOR.
+
+Run this AFTER every build `/phase` is done (the candidate is on staging/preview).
+AUTO runs all AUTOMATED stages without stopping; it STOPS only at the human gates —
+UAT execution, sign-off, and the production promote (security/irreversible hard-stops).
+Record progress in STATE.md so a resumed session continues mid-pipeline.
+
+## STAGE 1 — FULL REGRESSION (auto)
+Run the whole REAL corpus end-to-end: **functional + integration + e2e**
+(`scripts/regression.sh --real`, then the declared E2E runner via `e2e-runner`).
+Any red → `debugger` (cap 3) → fix → re-run. Must be 100% green to proceed.
+
+## STAGE 2 — AUTO AUDITS (auto)
+Run every whole-product audit and fold results together:
+- `/ui-audit` · `/qa-audit` · `/security-audit`
+- **code cleaning**: lint + format (the language's standard tool) must be clean
+- **code optimization**: a pass for dead code, obvious N+1 / perf, bundle bloat
+Collect every BLOCKER / HIGH / CRITICAL. Open blocker → fix → re-audit. (Security
+fixes surface for sign-off — security is an autonomy hard-stop.)
+
+## STAGE 3 — SMOKE TEST (auto)
+Deploy the candidate to staging/preview; run the **smoke suite**: app boots, health
+endpoint 200, the critical happy paths load, no console/server errors. Fail → STOP, fix.
+
+## STAGE 4 — UAT HANDOFF (human)
+Dispatch `/uat`: generate the all-case scenario document, hand it to the testers, and
+WAIT. Capture their pasted results into `docs/UAT-<date>.md`. (UAT is a human gate.)
+
+## STAGE 5 — UAT DEFECT LOOP
+For each issue/bug reported: log to `docs/ISSUES.md` (repro from the scenario), fix
+(`implementer`/`debugger`), re-run STAGE 1–3 for the touched area, then resubmit ONLY
+the failed scenarios via `/uat`. Loop until ALL scenarios PASS.
+
+## STAGE 6 — SIGN-OFF (human)
+Produce `docs/SIGNOFF-<date>.md`: scope delivered · test + audit results summary · UAT
+pass confirmation · known limitations · the approver/date line. **STOP for human
+sign-off** — a release gate, always interactive in both modes.
+
+## STAGE 7 — PROMOTE TO PRODUCTION (hard-stop)
+On a SIGNED sign-off only: deploy to production, smoke-test prod (health 200), update
+`docs/ENDPOINTS.md` base URL, tag the release. HISTORY line: `released v<n> (<date>)`.
+
+## STAGE 8 — GO-LIVE & SUPPORT
+Enter after-go-live support (hypercare): watch for incidents, keep the issue log live.
+New scope → `/change-request` (impact + re-price + sign-off). The project is live; the
+loop continues through change requests.

package/template/.claude/commands/replan.md

@@ -58,8 +58,13 @@ commercial impact (split/merge/reorder, a discovered technical re-slice).
    reconciled corpus still passes against live services. A failure -> surface it
    and stop before approval.
 
-6. SHOW ME the revised phase list + the regression-corpus changes, and STOP for
-   approval.
+6. PLAN-APPROVAL gate (hard rule 13). A re-plan reshapes UNBUILT scope, so it reverts
+   the plan to unapproved: set the PLAN.md `> Approval:` header back to `PENDING`, SHOW
+   ME the revised phase list + the regression-corpus changes, and STOP for approval.
+   On approval: re-stamp the header `approved <date> v<n+1>`, update STATE.md `plan:`,
+   and append `<date> plan v<n+1> approved (replan)` to docs/HISTORY.md (date-first,
+   matching the other HISTORY lines). `/phase` and `/sprint` stay blocked until this
+   re-stamp.
 
 7. ARCHITECTURE SELF-CHECK: re-planning is not normally a kit-architecture
    change. Only run /log-decision if the workflow itself changed (rare).

package/template/.claude/commands/runbook.md

@@ -0,0 +1,38 @@
+---
+description: Capture an operational/incident scenario in docs/RUNBOOK.md — one grep-able markdown so prod-debug knowledge isn't re-derived under pressure.
+argument-hint: [scenario, or "from the incident we just solved"]
+---
+
+Caveman ULTRA mode.
+
+Distill an operational scenario into docs/RUNBOOK.md. Scenario: $ARGUMENTS
+
+This is the runbook pattern Anthropic's Security + Data-Infra teams converged on
+independently: consolidate stack traces, dashboard signals, and the exact
+remediation commands into ONE searchable file so the next incident is a lookup,
+not a re-investigation.
+
+If $ARGUMENTS says "from the incident we just solved" (or similar), distill the
+debugging session in context — symptom, the REAL root cause, the commands that
+fixed it — instead of asking the user to re-type it.
+
+Append an entry to docs/RUNBOOK.md (create the file if missing). Canonical format:
+```
+
+### <scenario title — searchable, literal symptom keywords>
+
+- trigger: <what you observe first — alert, error string, dashboard signal>
+- diagnose: <steps/commands to confirm the real root cause>
+- remediate: <the exact commands/actions that fix it>
+- verify: <how to confirm recovery — what "healthy" looks like>
+- refs: <dashboard URLs, docs, related docs/ISSUES.md titles>
+
+```
+Rules:
+- title carries literal symptom keywords -> grep finds it mid-incident.
+- remediate must be runnable as-is; no "investigate further".
+- mark any step that is irreversible / PROD-writing with ⚠ so it's never run blind.
+- cross-link the matching docs/ISSUES.md entry instead of duplicating root-cause prose.
+- newest scenario at the TOP.
+
+Confirm the entry back in 2 lines.