create-issflow 1.0.0

package/template/.claude/commands/log-decision.md

@@ -0,0 +1,33 @@
+---
+description: Record an architectural decision in docs/DESIGN_LOG.md. Use only when the kit's structure changes.
+argument-hint: [what changed]
+---
+
+Caveman ULTRA mode.
+
+Append an architectural decision to docs/DESIGN_LOG.md. Change: $ARGUMENTS
+
+WHEN this applies — the change is ARCHITECTURAL:
+- new / removed / renamed agent, hook, or command
+- changed workflow rule (escalation, phase gate, test layering)
+- design decision where alternatives were weighed
+
+WHEN it does NOT apply:
+- code changes, features, phase progress -> HISTORY.md
+- bugs + fixes -> ISSUES.md
+
+Steps:
+1. Read docs/DESIGN_LOG.md.
+2. Append a dated line to `## 0. Changelog`, newest first.
+3. If alternatives were weighed, ALSO append a full entry to §5:
+```
+
+### 5.x <decision title>
+
+Options: <a, b, c>. **Chosen: <x>.** <why it won.>
+
+```
+4. If agent/hook/command/file added or removed, update the file inventory (§6).
+5. NEVER rewrite or delete existing entries — append only.
+
+Confirm back in 2-3 lines: what was logged and where.

package/template/.claude/commands/log-issue.md

@@ -0,0 +1,28 @@
+---
+description: Log an error to docs/ISSUES.md with root cause + solution, in the canonical format.
+argument-hint: [short error description]
+---
+
+Caveman ULTRA mode.
+
+Append an entry to docs/ISSUES.md. Error: $ARGUMENTS
+
+Canonical format:
+```
+
+### <short error title — searchable, literal error keywords>
+
+- [x] open      (or “- [x] resolved”)
+- symptom: <what was observed>
+- root cause: <the REAL underlying cause>
+- solution: <exact fix, or “pending”>
+- failed attempts: <approaches that did NOT work>
+
+```
+Rules:
+- title must contain literal error keywords -> grep finds it.
+- root cause is the real cause, not "the line threw an error".
+- always fill "failed attempts" — stops repeated dead ends.
+- open issues go at the TOP; resolved below; archived oldest at bottom.
+
+Confirm the entry back in 2 lines.

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

@@ -0,0 +1,98 @@
+---
+description: Bootstrap a new project. Runs design-research, double grill, and planning. Run once per project.
+---
+
+Caveman ULTRA mode.
+
+Recommended: run from plan mode (Shift+Tab). Planning agents are read-only by
+tool grant; plan mode adds a read-only gate on the main session too. Optional.
+
+Goal: stand up a fresh project workspace with a well-grounded plan.
+
+---
+
+## Steps
+
+### Round 1 — Initial grill
+
+1. Run the `grill-me` skill to interrogate me. Goal: understand initial scope.
+   known constraints, unknowns.
+   Do not stop early. Do not write OVERVIEW.md yet.
+
+Store the round-1 answers as working context — do NOT write OVERVIEW.md yet.
+
+---
+
+### Design research
+
+2. Extract DESIGN TOPICS from the round-1 answers. These are things we need
+   to verify before planning:
+   - Each external service mentioned: what does it support at the relevant tier?
+     Quotas, rate limits, known gaps?
+   - Auth patterns: any MSAL/Entra constraints for this scenario?
+   - Any other architectural assumption in the round-1 answers worth verifying.
+
+3. Dispatch `researcher` in DESIGN mode with the DESIGN TOPICS list.
+   It returns a terse summary + file paths. Read the design-<slug>.md files
+   only if needed.
+
+---
+
+### Round 2 — Research-informed re-grill
+
+4. Run `grill-me` again — a second focused pass. Seed it with:
+   - The round-1 answers (already established — do not re-ask these)
+   - The design-research key findings and new questions raised
+
+   The re-grill asks whatever it needs to build complete understanding. It is
+   not limited to "gaps from research" — research context makes new questions
+   relevant even if it found no blockers. Do not re-ask what round 1 already
+   established clearly.
+
+---
+
+### Write OVERVIEW.md
+
+5. Write docs/OVERVIEW.md from the COMBINED output of round-1 + design-research
+   + round-2. Include:
+   - Project purpose and success criteria
+   - Scope and constraints (informed by research findings)
+   - External services with confirmed capabilities/limits
+   - Known risks / open questions (if any remain)
+
+   OVERVIEW.md is written HERE — after the re-grill, not before.
+
+---
+
+### Plan
+
+6. Hand OVERVIEW.md + design-research findings to the `planner` subagent.
+   PLAN.md MUST:
+   - Start with Phase 0 (infra setup) as the first entry (always).
+   - End with a final code phase that contains the deploy task block.
+
+7. Create docs/STATE.md:
+```
+
+# STATE
+
+phase: 0 (pending)
+completed: project bootstrapped — design research done, double grill done
+blocker: none
+
+```
+8. Create docs/ISSUES.md with header `# Issues` and `## Archived` section.
+
+9. Create empty docs/HISTORY.md.
+
+
+11. 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.
+
+before starting Phase 1."

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

@@ -0,0 +1,191 @@
+---
+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.

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

@@ -0,0 +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.

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

@@ -0,0 +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.

package/template/.claude/commands/store-wisdom.md

@@ -0,0 +1,194 @@
+---
+description: Promote resolved issues and research findings from this project to the shared istartsoft-flow-kb repo. Analyzes, proposes candidates for your review, then pushes approved entries.
+---
+
+Caveman ULTRA mode. You are the ORCHESTRATOR.
+
+Purpose: share what this project learned with all future projects.
+Only resolved issues and completed research qualify. Open issues do NOT.
+
+---
+
+## PRE-FLIGHT
+
+1. Read `.claude/kb-config.json`.
+   - Not found -> STOP. Tell me: "KB not configured. Run setup.sh to set up the
+     shared KB repo, then retry /store-wisdom."
+   - Found -> extract `kb_path` and `kb_remote`.
+
+2. Expand `kb_path` (resolve `~` to home directory).
+   Verify the path exists and is a git repo (`git -C <path> status`).
+   - Fails -> STOP. Tell me the path is broken and to re-run setup.sh.
+
+---
+
+## STEP 1 — PULL LATEST KB
+
+Run: `git -C <kb_path> pull --ff-only`
+
+- Success -> continue.
+- Conflict or diverged -> STOP. Tell me:
+  "KB has a conflict. Resolve manually in <kb_path>, then retry /store-wisdom."
+- Offline (no network) -> WARN me, ask: "KB pull failed (offline?). Continue
+  with local KB copy, or abort?" Wait for answer.
+
+---
+
+## STEP 2 — ANALYZE LOCAL PROJECT
+
+Scan this project for promotion candidates:
+
+### From docs/ISSUES.md — resolved issues only
+- Read all entries marked `- [x] resolved`.
+- Exclude: entries with no root cause filled in, entries without a solution.
+- For each qualifying entry, note: title, symptom, root cause, solution,
+  failed attempts.
+
+### From docs/research/ — completed research files
+- Read docs/research/INDEX.md. For each entry:
+  - Read the corresponding file.
+  - A research entry qualifies if: it documents an external service behavior,
+    API contract, SDK gotcha, architectural constraint, or cost finding that
+    would be useful in a different project.
+  - A research entry does NOT qualify if: it is a project-specific config
+    finding, a one-off trace with no generalizable conclusion, or a debug
+    trace (`debug-*.md`).
+- Note: research entries get a `created:` timestamp (today's date if not
+  already present in the file). Staleness is measured from this date.
+
+### Cross-check against KB
+- Read `<kb_path>/INDEX.md` (if it exists).
+- For each candidate: does a matching slug already exist in the KB?
+  - YES, fresh entry: skip (already in KB, not stale).
+  - YES, stale entry (marked [STALE] in the snapshot): flag as REWRITE candidate.
+  - NO: flag as NEW candidate.
+
+---
+
+## STEP 3 — PROPOSE CANDIDATES
+
+Present candidates one at a time. For each:
+```
+
+[N of M] <type: NEW | REWRITE> — <slug>
+Tags: <tag1, tag2, tag3>
+Action: <“new entry” | “replaces stale entry from YYYY-MM-DD”>
+
+## Preview:
+
+## [<slug>]
+
+## created: <YYYY-MM-DD>
+tags: <tags>
+symptom/context: <…>
+root-cause / finding: <…>
+fix / recommendation: <…>
+
+[APPROVE / EDIT / SKIP]
+
+```
+- APPROVE: add to approved list.
+- EDIT: ask me for the edit, apply it, re-show, wait for APPROVE or SKIP.
+- SKIP: discard this candidate.
+
+After all candidates: show me the summary:
+```
+
+Approved: <N> entries
+Skipped: <M> entries
+Domains to write: <list>
+New domain folders to create: <list or “none”>
+Proceed? [yes / abort]
+
+```
+Wait for "yes" before writing anything.
+
+---
+
+## STEP 4 — WRITE TO KB
+
+For each approved entry:
+
+1. Determine the domain file path: `<kb_path>/<domain>/<file>.md`
+   - If the directory does not exist: create it.
+   - If the file does not exist: create it with a `# <domain> — <file>` header.
+
+2. REWRITE candidates: find the existing `## [<slug>]` block in the file and
+   replace it entirely with the new entry.
+
+3. NEW candidates: append the entry to the end of the domain file.
+
+4. Update `<kb_path>/INDEX.md`:
+   - For NEW entries: append a line:
+     `YYYY-MM-DD | <domain>/<file> | <slug> | <one-sentence summary>`
+   - For REWRITE entries: update the existing line in-place (new date, same slug).
+
+5. If this is the first `/store-wisdom` run (no INDEX.md existed):
+   Also create `<kb_path>/KB_GUIDE.md` with the entry format reference:
+
+   ```markdown
+   # istartsoft-flow-kb — guide
+
+   This repo accumulates resolved issues and research findings from iStartSoftFlow projects.
+   Populated by `/store-wisdom`. Read by the iStartSoftFlow `researcher` agent at session start.
+
+   ## Entry format — issues
+   ## [slug]
+   created: YYYY-MM-DD
+   tags: tag1, tag2
+   symptom: what was observed
+   root-cause: the real underlying cause
+   fix: exact solution
+   failed-attempts: what did not work
+
+   ## Entry format — research
+   ## [slug]
+   created: YYYY-MM-DD
+   tags: tag1, tag2
+   symptom/context: what prompted the research
+   finding: what was discovered
+   recommendation: what to do
+
+   ## INDEX.md format
+   YYYY-MM-DD | domain/file | slug | one-sentence summary
+
+   ## Staleness
+   Research entries older than 6 months are flagged [STALE] at session load.
+   Stale entries are re-researched locally and rewritten via /store-wisdom.
+   Issue entries never go stale.
+```
+
+-----
+
+## STEP 5 — COMMIT AND PUSH
+
+Run from `<kb_path>`:
+
+```bash
+git add -A
+git commit -m "store-wisdom: <N> entries from <project-name> (<YYYY-MM-DD>)"
+git push
+```
+
+- Push success -> tell me:
+  
+  ```
+  KB updated.
+  - entries written: <N> (<list of slugs>)
+  - domains touched: <list>
+  - new domains created: <list or "none">
+  - pushed to: <kb_remote>
+  ```
+- Push fails -> tell me the push failed, show the git error.
+  The entries ARE written locally — tell me to push manually:
+  `git -C <kb_path> push`
+
+-----
+
+## NOTES
+
+- `/store-wisdom` never modifies docs/ISSUES.md or docs/research/ in this project.
+  It reads them; it does not change them.
+- If there are no qualifying candidates, tell me so and stop. Do not push an empty commit.
+- The KB is append-only except for REWRITE of stale research entries.
+  Issue entries are never deleted or overwritten — they are facts.

package/template/.claude/commands/synthesize.md

@@ -0,0 +1,26 @@
+---
+description: Compress handoff docs, dedup the issue log, prune snapshots. Run before /clear.
+---
+
+Caveman ULTRA mode.
+
+Trigger: end of a phase, or any time STATE.md / ISSUES.md feel bloated.
+
+Dispatch the `synthesizer` subagent.
+
+For a normal phase: it rewrites STATE.md, dedups ISSUES.md, prunes snapshots,
+appends to HISTORY.md.
+
+For the FINAL phase (no further pending phases): also pass the signal
+"FINAL PHASE" so the synthesizer runs the extended pass — updating OVERVIEW.md
+and README.md to reflect the completed project state.
+
+To determine if this is the final phase: read docs/PLAN.md. If no phases remain
+with status "pending" after the current one, it is the final phase.
+
+When synthesizer returns "safe to /clear: yes", tell me:
+- before/after line counts
+- whether the final-pass ran
+- that I can now run /clear (or proceed to the endpoint summary if final phase)
+
+If it returns anything unsafe, show me what and stop.