create-issflow 1.2.1 → 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

@@ -211,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 · /runbook · /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', '',
@@ -230,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',
@@ -290,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.1",
+  "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/sprint.md

@@ -0,0 +1,233 @@
+---
+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]
+---
+
+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`)
+
+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/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');
@@ -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) |
 
@@ -149,7 +192,8 @@ can. Escalation is at most two hops.
   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.
+  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,7 @@ development run that follows the spec and logs every problem so it never recurs.
 
 -----
 
-## Hard rules (1–12)
+## 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 +405,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 +458,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/`,

package/template/.claude/templates/proposal.html

@@ -1,126 +1,112 @@
 <!doctype html>
 <!--
-  Client-facing proposal template (rendered by /propose from docs/PROPOSAL.md).
-  HOW TO USE (agent): copy this file to docs/proposal.html and replace every
-  {{PLACEHOLDER}}. LOCALISE the labels + content to the project's declared
-  language (e.g. natural Thai) — keep technical terms in English where a Thai dev
-  team would. Light + print-friendly on purpose (Ctrl/Cmd-P → "Save as PDF").
-  Repeat the <tr> in the phases table per phase; repeat <li> lists as needed.
-
-  WHITE-LABEL: this template is brand-neutral. Fill {{COMPANY}} / {{LOGO}} with the
-  ISSUING company's brand (whoever is sending the proposal) — NOT the kit's. {{LOGO}}
-  is optional: replace with an <img src="…"> or a text wordmark, or delete it.
-  Icons: none by design (no emoji) — keep it clean and typographic.
+  Client-facing proposal — ONE A4 PAGE (rendered by /propose from docs/PROPOSAL.md).
+  HOW TO USE (agent): copy to docs/proposal.html, replace every {{PLACEHOLDER}}, and
+  keep it to a SINGLE A4 page — be terse (≈3–6 phases, ≈4 assumptions). Localise the
+  CONTENT to the project language; the section labels are bilingual (TH / EN) already.
+  WHITE-LABEL: fill {{COMPANY}} / {{LOGO}} with the ISSUING company's brand (not the
+  kit's). {{LOGO}} optional: an <img src="…">, an SVG, or delete to keep the monogram.
+  Print: Ctrl/Cmd-P → A4 → "Save as PDF" (fits one page).
 -->
 <html lang="{{LANG}}">
 <head>
 <meta charset="utf-8" />
-<meta name="viewport" content="width=device-width, initial-scale=1" />
 <title>{{TITLE}} — Proposal {{VERSION}}</title>
 <style>
-  :root{ --ink:#1a2230; --muted:#5b6878; --line:#e3e8f0; --accent:#5b4cf0;
-    --accent2:#0ea5b7; --bg:#fff; --soft:#f6f8fc;
-    --sans:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Noto Sans Thai",system-ui,sans-serif;
-    --mono:ui-monospace,Menlo,Consolas,monospace; }
+  @page { size: A4; margin: 0 }
+  :root{
+    --ink:#162033; --muted:#5d6a7d; --line:#dbe3ee; --soft:#f6f8fb;
+    --violet:#635bff; --green:#15803d;
+    --sans:"Inter","Noto Sans Thai",-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;
+    --mono:ui-monospace,Menlo,Consolas,monospace;
+  }
   *{box-sizing:border-box}
-  body{margin:0;background:var(--soft);color:var(--ink);font-family:var(--sans);line-height:1.6}
-  .sheet{max-width:880px;margin:24px auto;background:var(--bg);border:1px solid var(--line);
-    border-radius:14px;overflow:hidden}
-  .head{padding:34px 40px;border-bottom:3px solid var(--accent);
-    background:linear-gradient(120deg,#f3f1ff,#eafcff)}
-  .brand-row{display:flex;align-items:center;gap:10px;margin-bottom:14px;font-size:1rem}
-  .brand-row .logo{display:inline-flex;align-items:center}
-  .head .ey{font:600 .72rem/1 var(--mono);letter-spacing:.18em;text-transform:uppercase;color:var(--accent)}
-  .head h1{margin:.3em 0 .1em;font-size:1.9rem;letter-spacing:-.02em}
-  .head .meta{color:var(--muted);font-size:.9rem}
-  main{padding:14px 40px 40px}
-  section{padding:20px 0;border-bottom:1px solid var(--line)}
-  section:last-child{border:none}
-  h2{font-size:1.05rem;margin:0 0 .5em;display:flex;align-items:center;gap:9px}
-  h2::before{content:"";width:10px;height:10px;border-radius:3px;
-    background:linear-gradient(120deg,var(--accent),var(--accent2))}
-  table{width:100%;border-collapse:collapse;font-size:.92rem}
-  th,td{text-align:left;padding:10px 12px;border-bottom:1px solid var(--line)}
-  th{background:var(--soft);font-size:.74rem;text-transform:uppercase;letter-spacing:.04em;color:var(--muted)}
-  td.num,th.num{text-align:right;font-family:var(--mono)}
-  tfoot td{font-weight:700;border-top:2px solid var(--ink);border-bottom:none}
-  ul{margin:.2em 0;padding-left:1.2em} li{margin:.2em 0;color:var(--muted)}
-  .total{font-size:1.5rem;font-weight:800}
-  .total small{font-size:.8rem;color:var(--muted);font-weight:500}
-  .cols{display:flex;gap:32px;flex-wrap:wrap} .cols>div{flex:1;min-width:220px}
-  .sign{display:flex;gap:40px;flex-wrap:wrap;margin-top:10px}
-  .sign div{flex:1;min-width:220px} .line{border-bottom:1px solid var(--ink);height:34px;margin-top:18px}
-  .muted{color:var(--muted)} .pill{display:inline-block;font:600 .7rem/1 var(--mono);
-    padding:3px 8px;border-radius:6px;background:var(--soft);border:1px solid var(--line);color:var(--muted)}
-  footer{padding:18px 40px;color:var(--muted);font-size:.8rem;background:var(--soft)}
-  @media print{ body{background:#fff} .sheet{margin:0;border:none;border-radius:0;max-width:none}
-    .head{background:#fff} section{break-inside:avoid} }
+  body{margin:0;background:#e9edf3;color:var(--ink);font-family:var(--sans);font-size:10.5px;line-height:1.45}
+  .sheet{width:210mm;min-height:297mm;margin:10mm auto;background:#fff;padding:15mm 16mm;display:flex;flex-direction:column;gap:11px}
+  .lbl{color:var(--muted);font-size:8.5px;font-weight:800;letter-spacing:.06em;text-transform:uppercase;margin:0 0 3px}
+  .lbl em{font-style:normal;opacity:.6;font-weight:600}
+  h1{font-size:21px;margin:0;letter-spacing:-.3px;line-height:1.1}
+  .muted{color:var(--muted)} ul{margin:0;padding-left:15px} li{margin:1.5px 0}
+  hr{border:none;border-top:1px solid var(--line);margin:0}
+
+  /* header */
+  .head{display:flex;justify-content:space-between;align-items:flex-start;border-bottom:2px solid var(--ink);padding-bottom:11px}
+  .co{display:flex;align-items:center;gap:10px}
+  .logo{width:42px;height:42px;border-radius:9px;background:var(--ink);color:#fff;display:flex;align-items:center;justify-content:center;font-weight:800;font-size:13px;flex:0 0 auto;overflow:hidden}
+  .logo img{width:100%;height:100%;object-fit:contain}
+  .co .name{font-weight:800;font-size:15px;line-height:1.15}
+  .co .tag{color:var(--muted);font-size:9px}
+  .head .meta{text-align:right;font-size:9px;color:var(--muted)}
+  .head .meta .big{font:800 12px/1.2 var(--sans);letter-spacing:.12em;color:var(--violet)}
+  .pill{display:inline-block;border:1px solid var(--line);border-radius:999px;padding:2px 8px;font:800 8px/1 var(--mono);color:var(--muted);margin-top:4px}
+
+  .cols{display:flex;gap:18px} .cols>div{flex:1;min-width:0}
+  table{width:100%;border-collapse:collapse;font-size:10px}
+  th,td{text-align:left;padding:5px 7px;border-bottom:1px solid var(--line)}
+  th{background:var(--soft);font-size:8px;text-transform:uppercase;letter-spacing:.04em;color:var(--muted)}
+  td.n,th.n{text-align:right;font-family:var(--mono)}
+  tfoot td{font-weight:800;border-top:1.5px solid var(--ink);border-bottom:none}
+  .total{display:flex;align-items:baseline;justify-content:space-between;background:var(--soft);border-radius:9px;padding:9px 13px}
+  .total .amt{font-size:19px;font-weight:800} .total .amt small{font-size:9px;color:var(--muted);font-weight:600}
+
+  .sign{display:flex;gap:34px;margin-top:auto;padding-top:14px}
+  .sign>div{flex:1} .line{border-bottom:1px solid var(--ink);height:30px} .sign .lbl{margin-top:5px}
+  footer{border-top:1px solid var(--line);padding-top:8px;color:var(--muted);font-size:8.5px;display:flex;justify-content:space-between}
+  @media print{ body{background:#fff} .sheet{margin:0;min-height:auto;box-shadow:none} }
 </style>
 </head>
 <body>
 <div class="sheet">
+
   <div class="head">
-    <div class="brand-row"><span class="logo">{{LOGO}}</span><strong>{{COMPANY}}</strong></div>
-    <div class="ey">Proposal · {{VERSION}}</div>
+    <div class="co">
+      <span class="logo">{{LOGO}}</span>
+      <span><span class="name">{{COMPANY}}</span><br><span class="tag">{{COMPANY_TAGLINE}}</span></span>
+    </div>
+    <div class="meta">
+      <div class="big">PROPOSAL</div>
+      {{VERSION}} · {{DATE}}<br><span class="pill">{{STATUS}}</span>
+    </div>
+  </div>
+
+  <div>
+    <p class="lbl">ใบเสนอราคา <em>Prepared for</em></p>
     <h1>{{TITLE}}</h1>
-    <div class="meta">{{L_PREPARED_FOR}} {{CLIENT}} · {{DATE}} · <span class="pill">{{STATUS}}</span></div>
+    <p class="muted" style="margin:3px 0 0">{{CLIENT}} — {{SUMMARY}}</p>
   </div>
-  <main>
-    <section>
-      <h2>{{L_OVERVIEW}}</h2>
-      <p class="muted">{{SUMMARY}}</p>
-    </section>
 
-    <section>
-      <h2>{{L_SCOPE}}</h2>
-      <div class="cols">
-        <div><strong>{{L_IN_SCOPE}}</strong><ul>{{SCOPE_IN_ITEMS}}</ul></div>
-        <div><strong>{{L_OUT_SCOPE}}</strong><ul>{{SCOPE_OUT_ITEMS}}</ul></div>
-      </div>
-    </section>
+  <div class="cols">
+    <div><p class="lbl">ขอบเขตงาน <em>In scope</em></p><ul>{{SCOPE_IN_ITEMS}}</ul></div>
+    <div><p class="lbl">นอกขอบเขต <em>Out of scope</em></p><ul>{{SCOPE_OUT_ITEMS}}</ul></div>
+  </div>
+
+  <div>
+    <p class="lbl">เฟส &amp; ค่าใช้จ่าย <em>Phases &amp; cost</em></p>
+    <table>
+      <thead><tr><th>เฟส <em style="font-style:normal;opacity:.5">Phase</em></th><th>Complexity</th><th class="n">Effort</th><th class="n">Cost</th></tr></thead>
+      <tbody>{{PHASE_ROWS}}<!-- <tr><td>1. Auth</td><td>M</td><td class="n">2–3d</td><td class="n">฿16k–24k</td></tr> --></tbody>
+      <tfoot><tr><td colspan="2">รวม <em style="font-style:normal;opacity:.5">Total</em></td><td class="n">{{TOTAL_EFFORT}}</td><td class="n">{{TOTAL_COST}}</td></tr></tfoot>
+    </table>
+  </div>
 
-    <section>
-      <h2>{{L_PHASES}}</h2>
-      <table>
-        <thead><tr>
-          <th>{{L_PHASE}}</th><th>{{L_COMPLEXITY}}</th>
-          <th class="num">{{L_EFFORT}}</th><th class="num">{{L_COST}}</th>
-        </tr></thead>
-        <tbody>
-          {{PHASE_ROWS}}
-          <!-- e.g. <tr><td>1. Auth</td><td>M</td><td class="num">2–3d</td><td class="num">฿16,000–24,000</td></tr> -->
-        </tbody>
-        <tfoot><tr><td colspan="2">{{L_TOTAL}}</td><td class="num">{{TOTAL_EFFORT}}</td><td class="num">{{TOTAL_COST}}</td></tr></tfoot>
-      </table>
-      <p class="total" style="margin-top:14px">{{TOTAL_COST}} <small>{{CONTINGENCY_NOTE}}</small></p>
-    </section>
+  <div class="total">
+    <span><span class="lbl" style="margin:0">ราคารวม <em>Total</em></span><br><span class="muted" style="font-size:9px">{{TIMELINE}}</span></span>
+    <span class="amt">{{TOTAL_COST}} <small>{{CONTINGENCY_NOTE}}</small></span>
+  </div>
 
-    <section>
-      <h2>{{L_TIMELINE}}</h2>
-      <p class="muted">{{TIMELINE}}</p>
-    </section>
+  <div class="cols">
+    <div><p class="lbl">สมมุติฐาน <em>Assumptions</em></p><ul>{{ASSUMPTION_ITEMS}}</ul></div>
+    <div><p class="lbl">ข้อยกเว้น <em>Exclusions</em></p><ul>{{EXCLUSION_ITEMS}}</ul></div>
+  </div>
 
-    <section>
-      <div class="cols">
-        <div><h2>{{L_ASSUMPTIONS}}</h2><ul>{{ASSUMPTION_ITEMS}}</ul></div>
-        <div><h2>{{L_EXCLUSIONS}}</h2><ul>{{EXCLUSION_ITEMS}}</ul></div>
-      </div>
-    </section>
+  <div><p class="lbl">เงื่อนไขการชำระเงิน <em>Payment</em></p><p class="muted" style="margin:0">{{PAYMENT_ITEMS}}</p></div>
 
-    <section>
-      <h2>{{L_PAYMENT}}</h2>
-      <ul>{{PAYMENT_ITEMS}}</ul>
-    </section>
+  <div class="sign">
+    <div><div class="line"></div><p class="lbl">ลงนามลูกค้า <em>Client sign-off</em></p></div>
+    <div><div class="line"></div><p class="lbl">วันที่ <em>Date</em></p></div>
+  </div>
 
-    <section>
-      <h2>{{L_SIGNOFF}}</h2>
-      <div class="sign">
-        <div><div class="line"></div><div class="muted">{{L_CLIENT_SIGN}}</div></div>
-        <div><div class="line"></div><div class="muted">{{L_DATE}}</div></div>
-      </div>
-    </section>
-  </main>
-  <footer>{{FOOTER}}</footer>
+  <footer><span>{{COMPANY}} · {{FOOTER}}</span><span>{{VERSION}}</span></footer>
 </div>
 </body>
 </html>