create-issflow 1.2.1 → 1.5.0

package/template/.claude/commands/sprint.md

@@ -0,0 +1,238 @@
+---
+description: The Scrum sprint layer — group PLAN phases into time-/scope-boxed sprints and run the full ceremony set (planning → standups → review/demo → retrospective → close) with burndown + velocity. AUTO-facilitated: the orchestrator runs every ceremony itself and drives the sprint end-to-end without stopping, pausing only at the real hard-stops. The layer between PLAN (backlog) and PHASE (build loop).
+argument-hint: [run|plan|standup|review|retro|close|status] [sprint number · "dry-run"]
+---
+
+Caveman ULTRA mode. You are the ORCHESTRATOR / SCRUM MASTER. You FACILITATE the
+ceremonies and ROUTE build work to subagents — you do NOT implement or debug yourself.
+
+Subcommand: $ARGUMENTS  (default: `status`)
+
+DRY-RUN: if `$ARGUMENTS` contains `dry-run`/`--dry-run`, do the full analysis but
+EXECUTE NOTHING — print the ACTION PLAN (which phases the sprint would commit,
+ceremonies it would run, points/capacity) and STOP. No sprint file is written, no
+phase runs. (METHODOLOGY → Dry-run.)
+
+Hierarchy: **PLAN (product backlog) → SPRINT (committed slice of phases) → PHASE
+(the build loop)**. A sprint groups consecutive PLAN phases behind ONE sprint goal
+and ships ONE deployable increment. Phases still run via `/phase` exactly as before
+— the sprint layer wraps them with planning, standups, a review, and a retro.
+
+**AUTONOMY (read first).** Sprint planning only SLICES the already-approved
+`docs/PLAN.md` — the requirements gate already happened at `/overview` plan approval —
+so the ceremonies are AUTO-safe and the orchestrator runs them WITHOUT stopping.
+- **AUTO (default):** `/sprint run` drives the whole sprint hands-off — plan → loop
+  `/phase` → standup tick after each phase → review → retro → close → roll forward →
+  start the next sprint. Decisions (points, scope-fit, accept/carry) are made from the
+  PLAN + velocity, logged, and the run continues. Pause ONLY for a methodology
+  hard-stop (deploy/irreversible/outbound, security-sensitive change, contradictory
+  spec, or debug budget spent with no independent slice left).
+- **GUIDED:** each ceremony presents its result and waits for you before the next.
+The PLAN-approval, commercial (`/propose`, `/change-request`), and release
+(`/release`, `/uat`, prod promote) gates are SEPARATE and stay interactive in both
+modes — the sprint layer never auto-passes them.
+
+Artifacts: `docs/sprints/sprint-<n>.md` (one per sprint — goal, committed phases,
+burndown, standups, review, retro) and `docs/sprints/VELOCITY.md` (the rolling
+velocity table). Create `docs/sprints/` if absent. STATE.md carries the active sprint.
+
+=====================================================================
+## ROUTER
+
+- `run`     → §RUN  (AUTO end-to-end driver — the default way to use this)
+- `plan`    → §1 PLANNING
+- `standup` → §2 STANDUP
+- `review`  → §3 REVIEW
+- `retro`   → §4 RETRO
+- `close`   → §5 CLOSE
+- `status`  → §STATUS  (default when no subcommand)
+
+=====================================================================
+## §1 — SPRINT PLANNING  (ceremony)
+
+Pre: `docs/PLAN.md` exists AND its `> Approval:` header reads `approved …` (the
+PLAN-APPROVAL gate, hard rule 13). Still `PENDING` / missing → STOP, route to the
+`/overview` plan-approval gate. A sprint only SLICES an already-signed-off plan.
+
+a. **Estimate (one-time, lazy).** Every pending PLAN phase needs a points estimate
+   (Fibonacci `1 2 3 5 8`, relative effort from the phase `slice` + `acceptance`
+   size; a phase that feels `>8` is too big — note it for `/replan` to split). If the
+   planner already wrote `[N pts]` tags, reuse them; otherwise assign now and write
+   them back into PLAN.md next to each phase header.
+
+b. **Capacity.** Read `docs/sprints/VELOCITY.md`.
+   - Have history → capacity = rolling-average completed velocity (last ≤3 sprints).
+   - First sprint (no history) → capacity = `flow-config.json` `sprint.defaultCapacity`
+     (fallback 8 pts).
+
+c. **Commit.** Walk the PLAN in dependency order, pull pending phases into this sprint
+   until the next phase would exceed capacity. Don't split a phase across a sprint
+   boundary; respect dependencies (never commit a phase whose dependency is in a later
+   sprint). Keep one coherent theme → that becomes the **sprint goal** (one line: the
+   user-visible increment this sprint ships). Optionally mark 1 phase `stretch`.
+
+d. **Write** `docs/sprints/sprint-<n>.md` from the template below; set
+   `status: active`; seed the burndown tick 0 = total committed points. Group the
+   committed phases under a `## Sprint <n>` header in PLAN.md if not already grouped.
+   Update STATE.md: `sprint: <n> (active)`.
+
+AUTO: auto-commit the computed backlog, log the goal + points + capacity, continue.
+GUIDED: present goal + committed phases + points, wait for confirm.
+
+=====================================================================
+## §2 — STANDUP  (auto-tick — fires once per phase close inside an active sprint)
+
+The AI dev loop has no calendar days, so the "daily" standup is rebound to a
+**per-phase-close tick** — the natural cadence of progress. After each `/phase` CLOSE
+while a sprint is active (the `/phase` command fires this; `/sprint run` fires it
+inline; or run `/sprint standup` by hand):
+
+1. Append a standup line to the active sprint doc:
+   `- tick <k> (Phase <p> <done|blocked>): done <what>; next <phase/none>; blockers <none|ref>`
+2. Update the **burndown**: append a row `tick <k> | Phase <p> <state> | <remaining pts>`
+   where remaining = committed points minus points of phases now `done`. Re-render the
+   ASCII sparkline.
+3. Surface blockers immediately if any (a blocked phase is the standup's whole point).
+   AUTO: the blocker is already parked per the circuit breaker — just record it here
+   and keep the burndown honest. GUIDED: relay it.
+
+Keep it ONE line per tick. No prose. The burndown is the signal.
+
+=====================================================================
+## §3 — SPRINT REVIEW / DEMO  (ceremony — at sprint boundary)
+
+Run when every committed phase is `done` or `blocked` (sprint timebox reached).
+
+a. **Demo.** Summarise the shipped increment: for each accepted phase, the
+   user-visible behaviour now working (pull from the phase `slice` + `docs/ENDPOINTS.md`).
+   This is the "done = demoable" check — a phase that can't be demoed isn't done.
+
+b. **Boundary audits.** Run the whole-product audits ONCE for the increment (cheaper
+   here than per-phase, broader than the inline gates):
+   `/ui-audit` (if UI shipped) · `/qa-audit` · `/security-audit`. Fold the scores in.
+   Open BLOCKER/HIGH/CRITICAL → route to FIX (`debugger`/`implementer`), re-audit.
+   (Security findings remain an autonomy hard-stop.)
+
+c. **Accept / carry.** Mark each phase `accepted` (demoed + audits clean) or
+   `carried` (not done / failed audit → rolls to the next sprint at §5).
+
+d. Write the `## Review` block into the sprint doc (demo bullets, audit scores,
+   accepted vs carried).
+
+=====================================================================
+## §4 — RETROSPECTIVE  (ceremony — after review)
+
+Inspect-and-adapt on the PROCESS, not the product. Write the `## Retro` block:
+
+- **went well** — what to keep (2–4 bullets).
+- **didn't** — friction, repeated debugging, churned tests, estimate misses.
+- **actions** — each a CONCRETE, routed change, not a wish. Route every action to a
+  durable home so it actually happens:
+  - a recurring bug/root-cause pattern → it's already in `docs/ISSUES.md`; note the ref.
+  - a workflow/structure change → `/log-decision` (`docs/DESIGN_LOG.md`).
+  - an ops/incident lesson → `/runbook`.
+  - a plan correction (re-estimate, split, reorder) → `/replan`.
+  - a durable, cross-project lesson → flag for `/store-wisdom`.
+- **estimate accuracy** — committed vs completed points; note phases that blew their
+  estimate so the next sprint's poker is calibrated.
+
+AUTO: auto-apply the routed actions (log/replan) and continue. GUIDED: list actions,
+confirm before applying.
+
+=====================================================================
+## §5 — SPRINT CLOSE
+
+a. **Velocity.** completed = sum of `accepted` phase points. Append a row to
+   `docs/sprints/VELOCITY.md`:
+   `| <n> | <committed> | <completed> | <goal met? yes/no> |` and recompute the rolling
+   average (last ≤3 sprints).
+b. **Carry forward.** Each `carried`/`blocked` phase stays pending in PLAN.md — the
+   next `/sprint plan` re-commits it first (carried work has priority). Don't lose it.
+c. Set the sprint doc `status: done`; stamp the close date. HISTORY line:
+   `sprint <n> closed — <completed>/<committed> pts, goal <met|missed> (<date>)`.
+d. Update STATE.md: clear the active sprint (or set the next one if `/sprint run`
+   continues).
+
+=====================================================================
+## §RUN — AUTO END-TO-END DRIVER  (the headline: "do all the process automatically")
+
+`/sprint run [n]` drives one full sprint — or, if you keep going, every remaining
+sprint until the PLAN is exhausted — with NO human stop except a hard-stop:
+
+```
+loop while pending phases remain in PLAN.md:
+  1. §1 PLANNING            → commit the next sprint from PLAN + velocity
+  2. for each committed phase, in dependency order:
+       run /phase <p>       → the full build loop (its own gates + circuit breaker)
+       §2 STANDUP tick      → append standup + update burndown
+       phase BLOCKED (circuit breaker parked it) → record, keep going to the next
+         INDEPENDENT phase; if none remain, end the sprint early (timebox)
+  3. §3 REVIEW              → demo + boundary audits (fix blockers, re-audit)
+  4. §4 RETRO               → routed actions, applied
+  5. §5 CLOSE              → velocity + carry-forward + HISTORY
+  6. /synthesize → suggest /clear  (token reset at the sprint boundary, like a phase)
+  AUTO: start the next sprint automatically.  GUIDED: stop, report, wait.
+HARD-STOP at any point: deploy/irreversible/outbound action, security-sensitive
+change, contradictory spec, or debug budget spent with no independent slice left →
+pause, surface the consolidated report, hand to the human.
+```
+
+When the last PLAN phase is `accepted`, the build is sprint-complete → recommend
+`/release` (the pre-production pipeline) as the next step. Do NOT auto-promote to prod
+— that is a separate, human-signed hard-stop.
+
+=====================================================================
+## §STATUS
+
+Read STATE.md + the active `docs/sprints/sprint-<n>.md` + VELOCITY.md and print:
+sprint number + goal, status, the burndown sparkline, committed vs done points,
+the current/next phase, any open blockers, and rolling velocity. One screen. No edits.
+
+=====================================================================
+## SPRINT DOC TEMPLATE  (`docs/sprints/sprint-<n>.md`)
+
+```
+# Sprint <n> — <short name>
+goal: <one line — the user-visible increment this sprint ships>
+status: active            # planning | active | review | done
+capacity: <cap> pts  (basis: velocity avg | default)
+
+## Committed
+- Phase <p>: <name>  [<pts> pts]  [status: pending|done|blocked|accepted|carried]
+- ...
+## Stretch
+- Phase <q>: <name>  [<pts> pts]   # optional, pulled in only if capacity frees up
+
+## Burndown
+tick | event                  | remaining pts
+0    | sprint start           | <total>
+1    | Phase <p> done         | <rem>
+...
+<ascii sparkline of remaining pts, e.g.  8 ▆▅▃▂ 0>
+
+## Standups
+- tick 1 (Phase <p> done): done <what>; next Phase <q>; blockers none
+- ...
+
+## Review (<date>)
+- demo: <increment shipped — user-visible behaviour now working>
+- audits: ui <score|n/a> · qa <score> · security <score> · code <clean|issues>
+- accepted: <phases>   carried: <phases or —>
+
+## Retro (<date>)
+- went well: ...
+- didn't: ...
+- actions: <each routed → ISSUES | DESIGN_LOG | RUNBOOK | replan | store-wisdom>
+- estimates: committed <c> pts / completed <d> pts — <misses noted>
+```
+
+## VELOCITY TEMPLATE  (`docs/sprints/VELOCITY.md`)
+
+```
+# Velocity
+| sprint | committed | completed | goal met? |
+|--------|-----------|-----------|-----------|
+| 1      | <c>       | <d>       | yes/no    |
+
+rolling avg (last ≤3): <v> pts/sprint
+```

package/template/.claude/commands/uat.md

@@ -0,0 +1,36 @@
+---
+description: Manual UAT cycle — generate an all-case test-scenario document for human testers, hand it off, capture their pasted results, and drive the defect loop until every scenario passes. Used inside /release; the human-in-the-loop acceptance gate.
+argument-hint: [optional: feature scope, or "failed" to re-issue only failures]
+---
+
+Caveman ULTRA mode. You are the ORCHESTRATOR.
+
+UAT is a HUMAN gate: real testers run the product and report results. Your job is to
+make that easy — produce a clear scenario sheet, capture results, and loop on defects.
+
+## STEP 1 — BUILD SCENARIOS
+From `docs/OVERVIEW.md` (flows) + `docs/PLAN.md` (acceptance) + `docs/ENDPOINTS.md`,
+write `docs/UAT-<date>.md` covering ALL cases a tester should run:
+```
+## UAT — <project>   (<date>, build <ref>)
+| # | scenario | preconditions | steps | expected | Result (PASS/FAIL) | Notes |
+|---|----------|---------------|-------|----------|--------------------|-------|
+| 1 | …        | …             | …     | …        |                    |       |
+```
+Cover: every happy path, every acceptance criterion, edge / negative cases, each user
+role, and each critical flow. Group by feature, number them, leave Result + Notes
+blank for the tester. Keep steps concrete enough to follow without you.
+
+## STEP 2 — HAND OFF
+Show me the scenario sheet, ready to run. Tell me to execute it (or pass it to QA /
+the client), then **paste the results back** here. WAIT — do not assume results.
+
+## STEP 3 — CAPTURE RESULTS
+Take the pasted results, fill PASS/FAIL + notes into `docs/UAT-<date>.md`, and
+summarise: **X / Y passed**, list the failures with their scenario IDs.
+
+## STEP 4 — DEFECT LOOP
+For each FAIL: log to `docs/ISSUES.md` (repro = the scenario steps), fix
+(`implementer` / `debugger`, debug cap 3), re-run the automated tests for that area,
+then re-issue **only the failed scenarios** to me for re-test. Loop until 100% PASS.
+On all-green, hand back to `/release` for sign-off.

package/template/.claude/commands/unstuck.md

@@ -15,7 +15,7 @@ Steps:
 
 - [ ] open - stuck after 3 attempts
 - symptom: <…>
-- attempts that FAILED: <hypothesis 1>, <2>, <3>
+- failed attempts: <hypothesis 1>, <2>, <3>
 
 ```
 Reference the existing debug-<slug>.md.

package/template/.claude/hooks/context-guard.js

@@ -2,7 +2,11 @@
 'use strict';
 // PreToolUse context watchdog (iStartSoftFlow). Two tiers, one hook:
 //   warnPct  -> non-blocking nudge (additionalContext) once per climb into the band
-//   gatePct  -> HARD block of NEW build work (Edit/Write-to-source/feature Task)
+//   gatePct  -> HARD block of NEW build work (Edit/Write to SOURCE files)
+// Delegation (Task) is the prescribed escape — a subagent runs in its OWN context
+// and returns a terse summary, so it SHRINKS orchestrator context, never grows it.
+// Blocking it would force the orchestrator to build inline (worse). So Task is
+// never gated; only direct source mutations by the orchestrator are.
 // Reads REAL token usage from the transcript. Fail-OPEN: any error -> allow,
 // never wedge the tool loop on a hook bug.
 const path = require('path');
@@ -34,7 +38,7 @@ function run(evt) {
   const tool = evt.tool_name || '';
   const ti = evt.tool_input || {};
   const band = u.pct >= gate ? 'gate' : u.pct >= warn ? 'warn' : 'ok';
-  const BLOCKABLE = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit', 'Task']);
+  const BLOCKABLE = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
 
   // HARD GATE — block new build mutations; reason is fed to the model.
   if (band === 'gate' && BLOCKABLE.has(tool) && !isEscape(tool, ti)) {
@@ -67,15 +71,12 @@ function run(evt) {
   return silent();
 }
 
-// Checkpoint/logging writes + the synthesizer ritual are never blocked, so the
-// model always has an escape path out of the gate.
+// Checkpoint/logging writes (docs/**, STATE/ISSUES/snapshots) are never blocked,
+// so the model always has an escape path out of the gate. (Task delegation is not
+// in BLOCKABLE at all — see the header note — so it needs no escape carve-out.)
 function isEscape(tool, ti) {
-  if (tool === 'Edit' || tool === 'Write' || tool === 'MultiEdit' || tool === 'NotebookEdit') {
-    const fp = ti.file_path || ti.path || ti.notebook_path || '';
-    return /(^|\/)docs\//.test(fp) || /STATE\.md|ISSUES\.md|\.snapshots\//.test(fp);
-  }
-  if (tool === 'Task') return (ti.subagent_type || '').toLowerCase() === 'synthesizer';
-  return false;
+  const fp = ti.file_path || ti.path || ti.notebook_path || '';
+  return /(^|\/)docs\//.test(fp) || /STATE\.md|ISSUES\.md|\.snapshots\//.test(fp);
 }
 
 const fmt = (n) => (n >= 1000 ? Math.round(n / 1000) + 'k' : String(n));

package/template/.claude/hooks/session-start.js

@@ -39,6 +39,21 @@ if (state !== null) {
   emit('');
 }
 
+// 2b. active sprint (sprint layer) — surface goal + burndown if one is active
+const sprintMatch = (state || '').match(/^\s*sprint:\s*(\d+)\s*\(active\)/m);
+if (sprintMatch) {
+  const sf = read(`docs/sprints/sprint-${sprintMatch[1]}.md`);
+  if (sf !== null) {
+    emit(`## Sprint ${sprintMatch[1]} (active)`);
+    const goal = (sf.match(/goal:\s*(.+)/i) || [])[1];
+    if (goal) emit('goal: ' + goal.trim());
+    const burn = sf.split('\n').find((l) => /burndown|remaining|pts? left|[▁▂▃▄▅▆▇█]/i.test(l));
+    if (burn) emit('burndown: ' + burn.trim());
+    emit(`see docs/sprints/sprint-${sprintMatch[1]}.md for the full sprint.`);
+    emit('');
+  }
+}
+
 // 3. issue log — inject only OPEN issues (resolved ones stay in the file for
 //    grep, but are NOT re-paid in tokens every session). Capped.
 const issues = read('docs/ISSUES.md');
@@ -65,7 +80,7 @@ if (issues !== null) {
 // 3b. research index
 const idx = read('docs/research/INDEX.md');
 if (idx !== null) {
-  const rows = idx.split('\n').filter((l) => /^[0-9]/.test(l));
+  const rows = idx.split('\n').filter((l) => /^\|\s*\d{4}-\d{2}-\d{2}/.test(l));
   emit(`## research/INDEX.md (${rows.length} prior investigations)`);
   emit('grep this before any new research or debugging.');
   for (const l of rows.slice(-15)) emit('  ' + l);
@@ -120,6 +135,8 @@ emit('- AUTO mode (default) governs the DEV loop: follow the plan — decide + l
 emit('  continue, do NOT stop to ask. (Planning / grill still asks — that part is fine.)');
 emit('  Hard-stops only: security / irreversible-or-outbound actions / contradictory spec.');
 emit('- caveman ULTRA mode is active.');
+emit('- PLAN-APPROVAL gate (rule 13): no /phase or /sprint while STATE `plan:` reads');
+emit('  PENDING — the plan needs a human sign-off via /overview first.');
 emit('- before debugging ANY error: grep ISSUES.md AND research/INDEX.md first.');
 emit('- debug attempts: WARN at 2; cap 3. AUTO: log + park the slice + continue (batched');
 emit('  report at the phase boundary). GUIDED: stop and ask you.');

package/template/.claude/istartsoft-flow/METHODOLOGY.md

@@ -59,6 +59,37 @@ non-TDD before SCAFFOLD fires.
 
 -----
 
+## Sprint layer (the Scrum wrapper — optional)
+
+Between the PLAN (the product backlog) and the PHASE (the build loop) sits an
+optional **sprint layer** (`/sprint`): consecutive PLAN phases are grouped behind ONE
+sprint goal and ship ONE deployable increment, wrapped in the full Scrum ceremony set.
+The hierarchy is **PLAN (backlog) → SPRINT (committed slice) → PHASE (loop)**. Phases
+run unchanged inside a sprint; the layer only adds cadence + inspect-and-adapt around them.
+
+Scrum maps onto the kit with no new vocabulary to learn:
+
+| Scrum | iStartSoftFlow |
+|-------|----------------|
+| Product Backlog | `docs/PLAN.md` (all phases) |
+| Sprint Backlog | `docs/sprints/sprint-<n>.md` (committed phases + goal) |
+| Scrum Master / Dev Team | the orchestrator (facilitates) / the subagent fleet (builds) |
+| Sprint Planning | `/sprint plan` — slice the approved PLAN into a capacity-bounded sprint |
+| Daily Scrum | `/sprint standup` — rebound to a **per-phase-close tick** (the AI loop has no calendar days) |
+| Sprint Review / demo | `/sprint review` — demo the increment + run the boundary audits |
+| Retrospective | `/sprint retro` — routed, concrete process actions |
+| Increment · Burndown · Velocity | the deployable slice · remaining-points table · completed pts/sprint |
+
+**AUTO-facilitated.** Sprint planning only SLICES an ALREADY-APPROVED plan (the
+requirements gate happened at `/overview` plan approval), so the ceremonies are
+AUTO-safe: `/sprint run` drives a whole sprint — or every remaining sprint — hands-off
+(plan → loop `/phase` → standup tick → review → retro → close → next sprint), pausing
+only at a methodology hard-stop. The PLAN-approval, commercial, and release gates are
+SEPARATE and stay interactive (see Autonomy). The layer is opt-in: skip it and drive
+phases directly off the PLAN exactly as before.
+
+-----
+
 ## Project lifecycle (real-world delivery)
 
 The loop above is the BUILD engine. Around it runs a full client-delivery lifecycle
@@ -68,20 +99,31 @@ from idea to closeout:
 1. **Discover** — idea → requirements, captured by `/overview` (the double-grill).
 2. **PRD** — crystallised requirements in `docs/PRD.md` (or your BMAD/iSSM stories).
 3. **Stack & architecture** — decided in `/overview` design-research → `OVERVIEW.md`.
-4. **Plan** — `/overview`'s `planner` → `docs/PLAN.md` (the vertical-slice phases).
-   The plan exists before the proposal, because the proposal estimates *these* phases.
+4. **Plan** — `/overview`'s `planner` → `docs/PLAN.md` (the vertical-slice phases),
+   then the **PLAN-APPROVAL gate** (rule 13): build cannot start until a human signs the
+   plan off and the approval is recorded. The plan exists before the proposal, because
+   the proposal estimates *these* phases.
 5. **Proposal & estimate (OPTIONAL — depends on the job)** — for client / quoted
    work, `/propose` reads OVERVIEW + PLAN → `docs/PROPOSAL.md` + a rendered
    `docs/proposal.html`: scope, phase breakdown, effort + cost estimate, timeline,
    assumptions, with a **client sign-off gate** before build. Internal / personal
    projects skip straight from plan to build.
-6. **Build** — the loop, one phase at a time (`/phase`, AUTO dev loop).
+6. **Build** — the loop, one phase at a time (`/phase`, AUTO dev loop). Each phase's
+   tests (unit + integration + e2e) are automated and MUST pass before the next phase.
+   Optionally wrap the phases in the **sprint layer** (`/sprint`): group them into
+   capacity-bounded sprints, each shipping one demoable increment with planning →
+   standups → review → retro. `/sprint run` drives this end-to-end (see Sprint layer).
 7. **Change mid-flight** — `/change-request`: impact analysis + re-estimate + a logged
    change order (`docs/CHANGES.md`) + sign-off, then `/replan`. Scope and cost never
    change silently.
-8. **Deploy** — in the final phase.
-9. **Closeout** — `/synthesize` (final pass) → a project summary: what was built, key
-   decisions, every change order, and the final cost vs the original estimate.
+8. **Release** — `/release`: full regression (functional/integration/e2e) → auto
+   audits (UI / QA / security / code) → smoke → **manual UAT** (`/uat`, scenario sheet
+   + captured results) → defect loop → **sign-off** (`docs/SIGNOFF-…`) → promote to
+   production (a human-signed hard-stop).
+9. **Go-live & support** — after-go-live hypercare; new scope routes through
+   `/change-request`. The project is live; the loop continues.
+10. **Closeout** — `/synthesize` → a project summary: what was built, key decisions,
+    every change order, and the final cost vs the original estimate.
 
 **Logging is continuous and total.** Every stage writes to a durable artifact:
 requirements (PRD / OVERVIEW), commercial (PROPOSAL / CHANGES), execution
@@ -89,9 +131,9 @@ requirements (PRD / OVERVIEW), commercial (PROPOSAL / CHANGES), execution
 Nothing important lives only in chat — it is on disk, so the project can always be
 reconstructed and summarised.
 
-**Commercial gates are always interactive** (both modes): the proposal sign-off and
-every change-order approval pause for the human. AUTO governs the *dev loop between*
-those gates, never the money decisions.
+**Approval gates are always interactive** (both modes): the **PLAN-APPROVAL** gate
+(rule 13), the proposal sign-off, and every change-order approval pause for the human.
+AUTO governs the *dev loop between* those gates, never the plan or the money decisions.
 
 -----
 
@@ -105,6 +147,7 @@ front-end. They compose — BMAD plans, iStartSoftFlow builds — with no duplic
 | Analyst / PM / Architect / PO agents | → | `/overview` grill + `researcher` + `planner` |
 | PRD + Architecture | → | `docs/OVERVIEW.md` (+ `docs/PRD.md`) |
 | sharded epics / story files | → | `docs/PLAN.md` phases (1 story ≈ 1 phase) |
+| epics / sprint grouping | → | the **sprint layer** (`/sprint`) — phases grouped behind one sprint goal |
 | SM "story with embedded context" | → | the phase **context package** (rationale + architecture + impl notes + qa focus + sharp acceptance) |
 | Dev → QA | → | `implementer` → `test-author` + the phase gates (TDD · UX · security · code-standards) |
 
@@ -148,8 +191,9 @@ can. Escalation is at most two hops.
   phases it is dispatched BEFORE logic exists (RED-first), so blindness is
   structural, not honor-system. Writes a MOCK suite + a REAL API suite.
 - **e2e-runner** — writes/runs functional browser E2E (your declared E2E runner,
-  e.g. Playwright) BLIND. Reads only the acceptance spec + `docs/ENDPOINTS.md`,
-  never the implementation.
+  e.g. Playwright) BLIND. Reads the acceptance spec, `docs/OVERVIEW.md` (stack),
+  `docs/ENDPOINTS.md`, and the E2E runner config — never the implementation. Writes
+  a trace to `docs/research/e2e-<phase-slug>.md`; returns a terse summary.
 - **debugger** — debugs in an ISOLATED context. Writes a trace to
   `docs/research/debug-<slug>.md`; returns a summary.
 - **synthesizer** — compresses `docs/STATE.md` / `docs/ISSUES.md`, prunes
@@ -171,7 +215,12 @@ Named procedures, each with a canonical body in `.claude/commands/<name>.md`.
   a logged change order (`CHANGES.md`) + sign-off, then `replan`.
 - **phase [n]** — run one phase end-to-end with the circuit breaker. Chooses the
   TDD or non-TDD order at RESEARCH. CLOSE runs the regression guard + ENDPOINTS
-  coverage gate.
+  coverage gate. When a sprint is active, CLOSE also fires a `/sprint standup` tick.
+- **sprint [run|plan|standup|review|retro|close|status] [n]** — the Scrum wrapper
+  around the build loop: slice the approved PLAN into a capacity-bounded sprint, run
+  the ceremonies (planning → standups → review/demo + boundary audits → retro → close)
+  with burndown + velocity. `/sprint run` drives a whole sprint (or every remaining
+  one) AUTO end-to-end. Opt-in; phases run unchanged inside it.
 - **quick [change]** — small, obvious, non-phase change; no agent chain. Stays
   non-TDD. Runs the mock regression corpus after the change.
 - **ui-audit** — whole-product UI audit against the `ux-design` cookbook (a11y /
@@ -183,12 +232,20 @@ Named procedures, each with a canonical body in `.claude/commands/<name>.md`.
 - **security-audit** — whole-product SECURITY audit against the `security` cookbook
   (OWASP/ASVS/WSTG/secrets/SCA/SAST/supply-chain); scored report. On-demand; a
   precondition for the pre-deploy pentest. Distinct from the per-phase rule-11 gate.
+- **release** — the pre-production pipeline (run after all build phases): full
+  regression → auto audits → smoke → UAT handoff → defect loop → sign-off → promote
+  to production → go-live support. The automated SDLC backbone.
+- **uat** — manual UAT cycle: generate an all-case scenario sheet for human testers,
+  capture their results, drive the defect loop to 100% pass. Used inside `release`.
 - **unstuck** — deep re-research after a circuit breaker (auto-run once in AUTO on
   first stuck; human-triggered in GUIDED).
 - **synthesize** — compress STATE.md, dedup ISSUES.md, prune snapshots. Run
   before a context reset.
 - **replan** — revise `PLAN.md` (add/cut/split/merge/reorder pending phases) and
-  reconcile the regression corpus in step.
+  reconcile the regression corpus in step. Reshaping unbuilt scope reverts the plan
+  to `PENDING` and re-runs the PLAN-APPROVAL gate (rule 13).
+- **runbook** — capture an operational / incident scenario in `docs/RUNBOOK.md` so
+  prod-debug knowledge isn't re-derived under pressure.
 - **log-issue** — append an error to `ISSUES.md` with root cause + failed attempts.
 - **log-decision** — record an architectural change in `docs/DESIGN_LOG.md`.
 - **store-wisdom** — promote resolved issues + research to the shared KB.
@@ -205,13 +262,22 @@ inject context, the model performs them itself.
 
 At the start of every session, before any other work, surface:
 1. git state (branch, uncommitted count, last 3 commits).
-2. `docs/STATE.md` — the current position. READ THIS FIRST.
+2. `docs/STATE.md` — the current position. READ THIS FIRST. If a sprint is active,
+   surface its goal + burndown from `docs/sprints/sprint-<n>.md`.
 3. open items in `docs/ISSUES.md`.
 4. `docs/research/INDEX.md` (research map) + infra/auth status.
 5. shared KB: pull latest + load `docs/.kb-snapshot.md` if `.claude/kb-config.json`
    exists.
 6. a one-line reminder of the hard rules below.
 
+### SPRINT-STANDUP (auto — at phase close inside an active sprint)
+
+When a sprint is active, every `/phase` CLOSE fires one standup tick: append a
+one-line entry to the active `docs/sprints/sprint-<n>.md` (done / next / blockers)
+and update the burndown (remaining points + the sparkline). The "daily" Scrum is
+rebound to per-phase-close because the AI dev loop has no calendar days — the phase
+boundary is the real unit of progress. Blockers surface immediately. See `/sprint`.
+
 ### COMPRESS (before a context compaction)
 
 Snapshot the live position to `docs/.snapshots/` so a post-compact session can
@@ -223,7 +289,8 @@ The cheapest token is the one never loaded. The kit is built to minimise context
 
 - **Phase boundary is the primary reset.** `/synthesize -> /clear` ends every
   phase so the next one starts with a small, fresh context instead of carrying
-  the whole history forward.
+  the whole history forward. The **sprint boundary** (`/sprint close`) is a second,
+  coarser reset — synthesize + clear there too before the next sprint plans.
 - **Lazy, not always-on.** This methodology + the skills load on demand; only the
   SessionStart hook output is paid every session, and it injects just the live
   STATE + *open* issues (resolved ones stay on disk for grep, not re-paid in tokens).
@@ -243,8 +310,8 @@ The cheapest token is the one never loaded. The kit is built to minimise context
 The kit runs in one of two modes, declared in `docs/OVERVIEW.md` (default: **AUTO**):
 
 **Planning always asks; development doesn't.** Asking is cheap and decisive while
-*planning* — so `/overview` (the double-grill) and plan approval stay interactive in
-both modes. AUTO governs only the **development loop** (implement → test → debug →
+*planning* — so `/overview` (the double-grill) and the **PLAN-APPROVAL gate** (rule 13,
+a recorded sign-off) stay interactive in both modes. AUTO governs only the **development loop** (implement → test → debug →
 close): there, interruptions are expensive, so it follows the plan instead of asking.
 
 - **AUTO (default) — during DEVELOPMENT, follow the plan, don't interrupt.** Once a
@@ -284,7 +351,19 @@ development run that follows the spec and logs every problem so it never recurs.
 
 -----
 
-## Hard rules (1–12)
+## Dry-run (preview — change nothing)
+
+Pass `dry-run` (or `--dry-run`) to ANY command and it does the full analysis but
+EXECUTES NOTHING: it prints the ACTION PLAN — files it would create/change · agents
+it would dispatch · tests/gates it would run · the deploy target · cost / scope /
+risk impact — then STOPS. Nothing is written, run, committed, or deployed. A safe
+preview to see the blast radius first. Most useful before side-effecting commands:
+`/phase` · `/release` · `/change-request` · `/sprint` · `/propose` · `/quick`.
+Mirrors the installer's `--dry-run`. (In a dry-run, even AUTO never acts — it only reports.)
+
+-----
+
+## Hard rules (1–13)
 
 1. Before debugging ANY error: grep `docs/ISSUES.md` AND `docs/research/INDEX.md`.
    The SESSION-OPEN ritual surfaces ISSUES.md — there is no excuse to miss it.
@@ -338,6 +417,16 @@ development run that follows the spec and logs every problem so it never recurs.
     (the language's standard tool), names follow the language's OWN idiom, and the
     code conforms to the declared architecture (Feature-Based by default) — checked
     at CLOSE. Lint/format errors or idiom violations BLOCK the close. (`code-standards`.)
+13. **PLAN-APPROVAL gate.** No phase / sprint / build work starts until `docs/PLAN.md`
+    carries a human approval. `/overview` ends by presenting the plan and STOPPING for
+    sign-off; on approval the gate is RECORDED in three places — the PLAN.md
+    `> Approval:` header (`approved <date> v<n>`), `plan:` in `docs/STATE.md`, and a
+    `plan v<n> approved` line in `docs/HISTORY.md`. `/phase` and `/sprint` REFUSE to
+    start while that header still reads `PENDING`. Interactive in BOTH modes: AUTO
+    governs the dev loop that runs AFTER approval, never the approval itself — it is
+    the planning twin of the commercial sign-off gate (`/propose`). A `/replan` that
+    adds or reshapes UNBUILT scope reverts the affected plan to `PENDING` and
+    re-surfaces it for confirmation before those phases run.
 
 -----
 
@@ -381,18 +470,35 @@ the KB. The kit works normally without a KB.
   commands render into `docs/`.
 - `docs/CHANGES.md` — change-order log (append-only): each scope change with its
   impact, effort/cost delta, new total, and approval status. The commercial audit trail.
+- `docs/UAT-<date>.md` — UAT scenario sheet (all cases) + captured tester results
+  (PASS/FAIL + notes). Drives the release defect loop.
+- `docs/SIGNOFF-<date>.md` — release sign-off: scope delivered, test/audit/UAT
+  summary, known limitations, approver — the gate to promote to production.
+- `docs/ui-audit-<date>.md` · `docs/qa-audit-<date>.md` · `docs/security-audit-<date>.md`
+  — scored whole-product audit reports (from the `*-audit` commands).
 - `docs/STATE.md` — current position. Small. Rewritten, not appended.
 - `docs/ISSUES.md` — error log. Deduped by synthesizer.
-- `docs/PLAN.md` — the phase plan. The last phase has the deploy task.
-- `docs/HISTORY.md` — one line per finished phase.
+- `docs/PLAN.md` — the phase plan (the product backlog). Carries an `> Approval:`
+  header — `PENDING` until the rule-13 PLAN-APPROVAL gate stamps `approved <date> v<n>`;
+  no phase runs while it reads `PENDING`. The last phase has the deploy task. Phases may
+  carry a `[N pts]` estimate and be grouped under `## Sprint` headers when the sprint
+  layer is used.
+- `docs/sprints/sprint-<n>.md` — one per sprint (sprint layer): goal, committed phases
+  + points, burndown, standup log, review (demo + audit scores), retro. Maintained by
+  `/sprint`.
+- `docs/sprints/VELOCITY.md` — rolling velocity table (committed vs completed pts per
+  sprint). Drives the next sprint's capacity.
+- `docs/HISTORY.md` — one line per finished phase (and per closed sprint).
 - `docs/DESIGN_LOG.md` — kit architectural rationale (§5.x decision log).
 - `docs/OVERVIEW.md` — project scope. Written after the double-grill in `overview`.
   E2E target.
 - `docs/ENDPOINTS.md` — API/service endpoint catalogue. Maintained by implementer
   each phase. Drives the CLOSE coverage gate.
+- `docs/RUNBOOK.md` — operational / incident runbook (grep-able): per-scenario
+  symptoms, diagnosis, and recovery steps. Maintained by `/runbook`.
 - `docs/research/` — full research + debug files. `INDEX.md` is the searchable map.
   `design-<slug>.md` (design research), `<slug>.md` (impl research),
-  `debug-<slug>.md` (debugger traces).
+  `debug-<slug>.md` (debugger traces), `e2e-<slug>.md` (e2e-runner traces).
 - `docs/.snapshots/` — pre-compact recovery markers (auto-pruned, gitignored).
   Holds no secrets.
 - your E2E stack — runner config + any ephemeral test services (e.g. `e2e/`,