create-issflow 1.0.0 → 1.0.2

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

@@ -1,191 +1,202 @@
----
-description: Run one phase end-to-end. TDD phases run SCAFFOLD -> RED -> GREEN; non-TDD phases run IMPLEMENT -> TEST. Both with the debug circuit breaker and the regression guard at CLOSE.
-argument-hint: [phase number]
----
-
-Caveman ULTRA mode. You are the ORCHESTRATOR. Route work to subagents —
-you do NOT implement or debug yourself.
-
-Note: subagents cannot talk to the user. Only YOU can.
-
-Target phase: $ARGUMENTS  (default: the phase marked pending in docs/PLAN.md)
-
----
-
-## 0. PRE-FLIGHT
-
-a. INFRA CHECK (phases > 0):
-
-b. 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.
-   - Out of dependency order -> 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
-   pending phases after this one)? Record this as IS_FINAL_PHASE=true/false.
-
-
----
-
-## 1. RESEARCH + TDD APPLICABILITY
-
-Dispatch `researcher` in IMPL mode scoped to this phase.
-Returns terse summary + path. Read the file only if needed.
-Unknowns block the phase -> re-dispatch narrowed. No guessing.
-
-Then classify the phase:
-
-  `TDD_PHASE` = the phase adds or changes a PUBLIC CALLABLE SURFACE (endpoint,
-  exported function/class, CLI command, message contract) assertable from the
-  acceptance spec. Size is NOT the criterion.
-
-- Clear public surface -> `TDD_PHASE=true` -> run the TDD path (§2 → §3a → §3b).
-- Pure infra/config/doc, no public surface -> `TDD_PHASE=false` -> run the
-  non-TDD path (§2N → §3N).
-- AMBIGUOUS -> default `TDD_PHASE=true`, but STATE the classification + the reason
-  to me, so I can override to non-TDD BEFORE SCAFFOLD fires. (Hard rule 11: never
-  downgrade a TDD phase just to dodge the RED gate.)
-
-=====================================================================
-## TDD PATH  (TDD_PHASE=true)
-=====================================================================
-
-## 2. SCAFFOLD
-
-Dispatch `implementer` in SCAFFOLD mode: interface stubs only (signatures +
-types; bodies raise NotImplementedError / return 501); NO logic, NO tests.
-Returns the stub files + the interface surface.
-
-## 3a. RED
-
-Dispatch `test-author` to write the REAL API suite (+ mock) BLIND against the
-stubs + acceptance. Place contract/ENDPOINTS tests in `tests/regression/`,
-phase-local tests in `tests/phase-<n>/`. Run the suite.
-
-RED GATE = every acceptance test COLLECTS cleanly AND FAILS (assertion /
-NotImplemented).
-- Any test PASSES on stubs -> STOP (spec trivial or test wrong); show me.
-- Collection / import / syntax error -> stub mismatch; re-dispatch SCAFFOLD to
-  fix SIGNATURES (not logic); re-run.
-- UNDERSPEC -> STOP; ask me to sharpen the acceptance spec.
-
-## 3b. GREEN
-
-Dispatch `implementer` in FILL mode with the phase spec + research + the test
-file paths (it MAY read the tests — frozen before logic, no overfit — but must
-NOT edit them). Fill to green. Budget 3, WARN@2, STUCK@3.
-
-`scripts/e2e-stack.sh up` / Playwright / `down`).
-
-PHASE GATE (rule 5) -> go to §4/§5/§6 (see GATE below).
-
-=====================================================================
-## NON-TDD PATH  (TDD_PHASE=false)
-=====================================================================
-
-## 2N. IMPLEMENT
-
-Dispatch `implementer` (legacy mode) with phase spec + research summary.
-Returns STUCK -> go to ESCALATE.
-If IS_FINAL_PHASE: phase spec includes the deploy task; confirm the return
-includes "deployed URL" before proceeding.
-
-## 3N. TEST (blind)
-
-Dispatch `test-author`. It writes MOCK + REAL API suites from the acceptance
-spec — never reads the logic. (e2e-runner only if frontend.)
-
-=====================================================================
-
-## GATE (both paths)
-
-PHASE GATE = current-phase REAL API suite passes AND (if frontend) E2E passes AND
-the accumulated mock regression corpus stays green AND every docs/ENDPOINTS.md
-entry has a regression test (checked at CLOSE).
-- GATE PASS -> go to CLOSE.
-- GATE FAIL (LOGIC FAIL) -> go to FIX.
-
----
-
-## 4. FIX
-
-Dispatch `debugger` (isolated context) on the specific failure.
-- FIXED -> re-run TEST (and the regression corpus).
-- WARN (2 attempts failed) -> relay immediately, then let debugger finish attempt 3.
-- STUCK -> go to ESCALATE.
-
----
-
-## 5. ESCALATE — circuit breaker. Mode B.
-
-FIRST STUCK: STOP. Present to me: the problem, 3 failed hypotheses, the
-debugger's recommendation, the debug file path. Ask what to do. Wait. Options:
-  (a) "re-research" -> /unstuck
-  (b) hint -> re-dispatch debugger with hint, budget 3
-  (c) "skip" / "re-slice" -> mark blocked, dispatch planner
-
-SECOND STUCK: STOP completely. Full summary — every hypothesis, current state,
-what to try next. Hand control to me.
-
----
-
-## 6. CLOSE
-
-REGRESSION GATE (before closing — Feature 3):
-- Run `scripts/regression.sh` (mock corpus). A failure BLOCKS close -> route to FIX.
-- ENDPOINTS COVERAGE: every `docs/ENDPOINTS.md` entry MUST have >=1 test in
-  `tests/regression/`. Zero coverage -> FAIL HARD; do not close.
-- IF IS_FINAL_PHASE: additionally run `scripts/regression.sh --real` (full real
-  corpus). A failure blocks close.
-
-Mark phase `done` in docs/PLAN.md.
-
-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.
-
-IF IS_FINAL_PHASE — FINAL CLOSE sequence:
-
-  a. Run `/synthesize` — pass the signal that this is the final phase so the
-     synthesizer runs the extended pass (OVERVIEW.md + README.md update).
-
-  b. Read docs/ENDPOINTS.md. Surface a "READY TO USE" summary to me:
-     ```
-     ✅ PROJECT COMPLETE
-
-
-     ## Endpoints
-     <paste the full docs/ENDPOINTS.md table>
-
-     ## Quick start
-     - Base URL: <URL>
-     - Auth: <Bearer token / API key / none — from ENDPOINTS.md>
-     - Health check: GET <base URL>/health
-
-     ## Docs
-     - Full endpoint catalogue: docs/ENDPOINTS.md
-     - Project history: docs/HISTORY.md
-     ```
-  Tell me the project is complete and ready to use.
-
-ELSE (not final phase):
-
-  Run `/synthesize`.
-  Tell me phase done + the next phase. Recommend `/clear` then `/phase` next.
-
----
-
-## STATE CHECKPOINTING
-
-After each step, update docs/STATE.md:
-```
-
-phase: <n> (in progress)
-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.
+---
+description: Run one phase end-to-end. TDD phases run SCAFFOLD -> RED -> GREEN; non-TDD phases run IMPLEMENT -> TEST. Both with the debug circuit breaker and the regression guard at CLOSE.
+argument-hint: [phase number]
+---
+
+Caveman ULTRA mode. You are the ORCHESTRATOR. Route work to subagents —
+you do NOT implement or debug yourself.
+
+Note: subagents cannot talk to the user. Only YOU can.
+
+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.
+   - 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.
+   - 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.
+   - Out of dependency order -> 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
+   pending phases after this one)? Record this as IS_FINAL_PHASE=true/false.
+
+
+---
+
+## 1. RESEARCH + TDD APPLICABILITY
+
+Dispatch `researcher` in IMPL mode scoped to this phase.
+Returns terse summary + path. Read the file only if needed.
+Unknowns block the phase -> re-dispatch narrowed. No guessing.
+
+Then classify the phase:
+
+  `TDD_PHASE` = the phase adds or changes a PUBLIC CALLABLE SURFACE (endpoint,
+  exported function/class, CLI command, message contract) assertable from the
+  acceptance spec. Size is NOT the criterion.
+
+- Clear public surface -> `TDD_PHASE=true` -> run the TDD path (§2 → §3a → §3b).
+- Pure infra/config/doc, no public surface -> `TDD_PHASE=false` -> run the
+  non-TDD path (§2N → §3N).
+- AMBIGUOUS -> default `TDD_PHASE=true`, but STATE the classification + the reason
+  to me, so I can override to non-TDD BEFORE SCAFFOLD fires. (Hard rule 11: never
+  downgrade a TDD phase just to dodge the RED gate.)
+
+=====================================================================
+## TDD PATH  (TDD_PHASE=true)
+=====================================================================
+
+## 2. SCAFFOLD
+
+Dispatch `implementer` in SCAFFOLD mode: interface stubs only (signatures +
+types; bodies raise NotImplementedError / return 501); NO logic, NO tests.
+Returns the stub files + the interface surface.
+
+## 3a. RED
+
+Dispatch `test-author` to write the REAL API suite (+ mock) BLIND against the
+stubs + acceptance. Place contract/ENDPOINTS tests in `tests/regression/`,
+phase-local tests in `tests/phase-<n>/`. Run the suite.
+
+RED GATE = every acceptance test COLLECTS cleanly AND FAILS (assertion /
+NotImplemented).
+- Any test PASSES on stubs -> STOP (spec trivial or test wrong); show me.
+- Collection / import / syntax error -> stub mismatch; re-dispatch SCAFFOLD to
+  fix SIGNATURES (not logic); re-run.
+- UNDERSPEC -> STOP; ask me to sharpen the acceptance spec.
+
+## 3b. GREEN
+
+Dispatch `implementer` in FILL mode with the phase spec + research + the test
+file paths (it MAY read the tests — frozen before logic, no overfit — but must
+NOT edit them). Fill to green. Budget 3, WARN@2, STUCK@3.
+
+## 3c. TEST (e2e) — FRONTEND phases only
+
+If this phase ships UI: dispatch `e2e-runner` (BLIND) to write + run browser E2E
+for the slice using the declared E2E runner (it brings the test stack up/down
+itself). Then run the `ux-design` cookbook + wireframe check on the new UI
+(hard rule 9): the UI must match the wireframe frame and pass the cookbook
+(tokens, a11y/WCAG AA, states, breakpoints). A `ux-design` BLOCK is a GATE FAIL.
+Non-frontend phase -> skip §3c.
+
+PHASE GATE (rule 5) -> go to §4/§5/§6 (see GATE below).
+
+=====================================================================
+## NON-TDD PATH  (TDD_PHASE=false)
+=====================================================================
+
+## 2N. IMPLEMENT
+
+Dispatch `implementer` (legacy mode) with phase spec + research summary.
+Returns STUCK -> go to ESCALATE.
+If IS_FINAL_PHASE: phase spec includes the deploy task; confirm the return
+includes "deployed URL" before proceeding.
+
+## 3N. TEST (blind)
+
+Dispatch `test-author`. It writes MOCK + REAL API suites from the acceptance
+spec — never reads the logic. (e2e-runner only if frontend.)
+
+=====================================================================
+
+## GATE (both paths)
+
+PHASE GATE = current-phase REAL API suite passes AND (if frontend) E2E passes AND
+(if frontend) the `ux-design` cookbook + wireframe check passes AND the
+accumulated mock regression corpus stays green AND every docs/ENDPOINTS.md
+entry has a regression test (checked at CLOSE).
+- GATE PASS -> go to CLOSE.
+- GATE FAIL (LOGIC FAIL) -> go to FIX.
+
+---
+
+## 4. FIX
+
+Dispatch `debugger` (isolated context) on the specific failure.
+- FIXED -> re-run TEST (and the regression corpus).
+- WARN (2 attempts failed) -> relay immediately, then let debugger finish attempt 3.
+- STUCK -> go to ESCALATE.
+
+---
+
+## 5. ESCALATE — circuit breaker. Mode B.
+
+FIRST STUCK: STOP. Present to me: the problem, 3 failed hypotheses, the
+debugger's recommendation, the debug file path. Ask what to do. Wait. Options:
+  (a) "re-research" -> /unstuck
+  (b) hint -> re-dispatch debugger with hint, budget 3
+  (c) "skip" / "re-slice" -> mark blocked, dispatch planner
+
+SECOND STUCK: STOP completely. Full summary — every hypothesis, current state,
+what to try next. Hand control to me.
+
+---
+
+## 6. CLOSE
+
+REGRESSION GATE (before closing — Feature 3):
+- Run `scripts/regression.sh` (mock corpus). A failure BLOCKS close -> route to FIX.
+- ENDPOINTS COVERAGE: every `docs/ENDPOINTS.md` entry MUST have >=1 test in
+  `tests/regression/`. Zero coverage -> FAIL HARD; do not close.
+- IF IS_FINAL_PHASE: additionally run `scripts/regression.sh --real` (full real
+  corpus). A failure blocks close.
+
+Mark phase `done` in docs/PLAN.md.
+
+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.
+
+IF IS_FINAL_PHASE — FINAL CLOSE sequence:
+
+  a. Run `/synthesize` — pass the signal that this is the final phase so the
+     synthesizer runs the extended pass (OVERVIEW.md + README.md update).
+
+  b. Read docs/ENDPOINTS.md. Surface a "READY TO USE" summary to me:
+     ```
+     ✅ PROJECT COMPLETE
+
+
+     ## Endpoints
+     <paste the full docs/ENDPOINTS.md table>
+
+     ## Quick start
+     - Base URL: <URL>
+     - Auth: <Bearer token / API key / none — from ENDPOINTS.md>
+     - Health check: GET <base URL>/health
+
+     ## Docs
+     - Full endpoint catalogue: docs/ENDPOINTS.md
+     - Project history: docs/HISTORY.md
+     ```
+  Tell me the project is complete and ready to use.
+
+ELSE (not final phase):
+
+  Run `/synthesize`.
+  Tell me phase done + the next phase. Recommend `/clear` then `/phase` next.
+
+---
+
+## STATE CHECKPOINTING
+
+After each step, update docs/STATE.md:
+```
+
+phase: <n> (in progress)
+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.

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

@@ -1,30 +1,30 @@
----
-description: Make a small, obvious change directly — no agent chain, no phase overhead.
-argument-hint: [what to change]
----
-
-Caveman ULTRA mode. Apply `karpathy-guidelines` skill.
-
-Purpose: skip the orchestration tax for a 5-line fix.
-
-Use `/quick` when ALL hold:
-- change is small (under 30 lines) and obvious
-- no new vertical slice
-- no external service contract change
-- 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.)
-
-Steps:
-1. grep docs/ISSUES.md for anything related.
-2. Make the change. Smallest diff that works.
-3. Run it — lint/typecheck/smoke. Show me result.
-4. REGRESSION GUARD: run `scripts/regression.sh` (mock corpus). A break BLOCKS the
-   `/quick` — surface it to me and stop. No agent chain is added.
-5. Error you cannot fix in 2 tries -> STOP. Recommend `/phase`.
-6. Change revealed a bug -> `/log-issue`.
-7. ARCHITECTURE SELF-CHECK: touched an agent, hook, command, or workflow rule?
-   YES -> `/log-decision`.
-
-No STATE.md rewrite, no synthesize, no /clear needed.
+---
+description: Make a small, obvious change directly — no agent chain, no phase overhead.
+argument-hint: [what to change]
+---
+
+Caveman ULTRA mode. Apply `karpathy-guidelines` skill.
+
+Purpose: skip the orchestration tax for a 5-line fix.
+
+Use `/quick` when ALL hold:
+- change is small (under 30 lines) and obvious
+- no new vertical slice
+- no external service contract change
+- 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.)
+
+Steps:
+1. grep docs/ISSUES.md for anything related.
+2. Make the change. Smallest diff that works.
+3. Run it — lint/typecheck/smoke. Show me result.
+4. REGRESSION GUARD: run `scripts/regression.sh` (mock corpus). A break BLOCKS the
+   `/quick` — surface it to me and stop. No agent chain is added.
+5. Error you cannot fix in 2 tries -> STOP. Recommend `/phase`.
+6. Change revealed a bug -> `/log-issue`.
+7. ARCHITECTURE SELF-CHECK: touched an agent, hook, command, or workflow rule?
+   YES -> `/log-decision`.
+
+No STATE.md rewrite, no synthesize, no /clear needed.

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

@@ -1,63 +1,63 @@
----
-description: Revise docs/PLAN.md when it no longer matches reality — add, cut, split, merge, or reorder phases.
-argument-hint: [what changed about the plan]
----
-
-Caveman ULTRA mode.
-
-Recommended: run from plan mode (Shift+Tab). Optional; the command stops for
-your approval regardless.
-
-Use when PLAN.md no longer matches reality. Change: $ARGUMENTS
-
----
-
-## Steps
-
-1. PRE-FLIGHT. Read docs/STATE.md and docs/PLAN.md.
-   - Phase in progress -> tell me which. Ask: revise around it, or is it the
-     thing being changed? Do not silently rewrite a mid-execution phase.
-   - Done phases are FROZEN. /replan never edits or reorders done phases.
-   - Phase 0 (infra) is ALWAYS frozen once done.
-
-2. DESIGN RESEARCH CHECK. Scan $ARGUMENTS for signals that design research
-   is warranted before re-planning:
-   - The change involves architecture (a new integration pattern, auth change, etc.)
-   - A service tier or quota change is implied
-
-   If ANY of these signals are present: dispatch `researcher` in DESIGN mode
-   with the specific new service/pattern as the DESIGN TOPICS list. Show me the
-   key findings before proceeding to step 3.
-
-   If none: proceed directly to step 3 (impl-research may still be dispatched
-   in step 3 for non-trivial changes per the original logic).
-
-3. IMPL RESEARCH if needed. If the change is non-trivial but design research
-   was not needed, dispatch `researcher` in IMPL mode to ground the re-plan
-   in facts.
-
-4. RE-PLAN. Dispatch `planner` with the change + current PLAN.md. It must:
-   - Keep done phases untouched.
-   - Insert / cut / split / merge / reorder only PENDING phases.
-   - Place new phases in correct DEPENDENCY order.
-   - Keep every phase a vertical slice with its own acceptance spec.
-   - Ensure the LAST pending phase still contains the deploy task block.
-   - Renumber pending phases if needed; update STATE.md `phase:` pointer.
-
-5. RECONCILE THE REGRESSION CORPUS (scoped to `tests/regression/`):
-   - A CUT phase -> retire its regression tests.
-   - A MERGE -> consolidate the merged phases' regression tests.
-   - A REORDER -> keep the tests as-is (contracts are phase-independent).
-   Do NOT touch phase-local `tests/phase-<n>/` here beyond renumbering dirs.
-   After reconciling, run `scripts/regression.sh --real` to confirm the
-   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.
-
-7. ARCHITECTURE SELF-CHECK: re-planning is not normally a kit-architecture
-   change. Only run /log-decision if the workflow itself changed (rare).
-
-Report what changed: phases added / cut / split / reordered, and regression
-tests retired / consolidated.
+---
+description: Revise docs/PLAN.md when it no longer matches reality — add, cut, split, merge, or reorder phases.
+argument-hint: [what changed about the plan]
+---
+
+Caveman ULTRA mode.
+
+Recommended: run from plan mode (Shift+Tab). Optional; the command stops for
+your approval regardless.
+
+Use when PLAN.md no longer matches reality. Change: $ARGUMENTS
+
+---
+
+## Steps
+
+1. PRE-FLIGHT. Read docs/STATE.md and docs/PLAN.md.
+   - Phase in progress -> tell me which. Ask: revise around it, or is it the
+     thing being changed? Do not silently rewrite a mid-execution phase.
+   - Done phases are FROZEN. /replan never edits or reorders done phases.
+   - Phase 0 (infra), if present, is frozen once done.
+
+2. DESIGN RESEARCH CHECK. Scan $ARGUMENTS for signals that design research
+   is warranted before re-planning:
+   - The change involves architecture (a new integration pattern, auth change, etc.)
+   - A service tier or quota change is implied
+
+   If ANY of these signals are present: dispatch `researcher` in DESIGN mode
+   with the specific new service/pattern as the DESIGN TOPICS list. Show me the
+   key findings before proceeding to step 3.
+
+   If none: proceed directly to step 3 (impl-research may still be dispatched
+   in step 3 for non-trivial changes per the original logic).
+
+3. IMPL RESEARCH if needed. If the change is non-trivial but design research
+   was not needed, dispatch `researcher` in IMPL mode to ground the re-plan
+   in facts.
+
+4. RE-PLAN. Dispatch `planner` with the change + current PLAN.md. It must:
+   - Keep done phases untouched.
+   - Insert / cut / split / merge / reorder only PENDING phases.
+   - Place new phases in correct DEPENDENCY order.
+   - Keep every phase a vertical slice with its own acceptance spec.
+   - Ensure the LAST pending phase still contains the deploy task block.
+   - Renumber pending phases if needed; update STATE.md `phase:` pointer.
+
+5. RECONCILE THE REGRESSION CORPUS (scoped to `tests/regression/`):
+   - A CUT phase -> retire its regression tests.
+   - A MERGE -> consolidate the merged phases' regression tests.
+   - A REORDER -> keep the tests as-is (contracts are phase-independent).
+   Do NOT touch phase-local `tests/phase-<n>/` here beyond renumbering dirs.
+   After reconciling, run `scripts/regression.sh --real` to confirm the
+   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.
+
+7. ARCHITECTURE SELF-CHECK: re-planning is not normally a kit-architecture
+   change. Only run /log-decision if the workflow itself changed (rare).
+
+Report what changed: phases added / cut / split / reordered, and regression
+tests retired / consolidated.