create-issflow 1.0.0

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

@@ -0,0 +1,40 @@
+---
+description: Forced re-research after a circuit breaker. Stops flailing, re-routes to deep research with full memory of dead ends.
+---
+
+Caveman ULTRA mode.
+
+Trigger: I chose "re-research" at a circuit breaker (see /phase step 5).
+
+Steps:
+
+1. WRITE IT DOWN. Append to docs/ISSUES.md as OPEN:
+```
+
+### <error title>
+
+- [ ] open - stuck after 3 attempts
+- symptom: <…>
+- attempts that FAILED: <hypothesis 1>, <2>, <3>
+
+```
+Reference the existing debug-<slug>.md.
+
+2. RESET FRAME. The 3 failed hypotheses are probably all wrong. Discard them.
+
+3. DEEP RESEARCH. Dispatch `researcher` in IMPL mode WIDE:
+- Read existing debug-<slug>.md and ISSUES.md failed-attempts FIRST.
+- Re-read the actual error from scratch.
+- Check real external service contract / docs.
+- Look one layer below: config? env? version? data shape?
+- Return fresh HYPOTHESIS backed by NEW evidence.
+
+4. RE-PLAN if needed. Research shows phase design was wrong -> dispatch planner.
+
+5. RESUME. Hand fresh hypothesis to `debugger`. It reads the prior debug file
+(already knows what's ruled out). Budget = 3, NEW hypotheses only.
+
+6. This counts as the path chosen at the first breaker. If STUCK again ->
+/phase step 5 SECOND STUCK. Do not loop further.
+
+Report each step.

package/template/.claude/hooks/pre-compact.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# PreCompact hook. Fires before auto/manual /compact.
+set -euo pipefail
+cd "${CLAUDE_PROJECT_DIR:-.}"
+
+mkdir -p docs/.snapshots
+STAMP=$(date +%Y%m%d-%H%M%S)
+SNAP="docs/.snapshots/precompact-${STAMP}.md"
+
+{
+  echo "# Pre-compact snapshot ${STAMP}"
+  echo
+  echo "## Git"
+  git status --short 2>/dev/null || true
+  git diff --stat 2>/dev/null || true
+  echo
+  echo "## STATE.md at compact time"
+  [ -f docs/STATE.md ] && cat docs/STATE.md || echo "(no STATE.md)"
+} > "$SNAP"
+
+ls -1t docs/.snapshots/precompact-*.md 2>/dev/null | tail -n +6 | xargs -r rm -f
+
+echo "Context was compacted. Recovery snapshot saved at ${SNAP}."
+echo "STATE.md and ISSUES.md were re-injected by the SessionStart hook - trust those."
+exit 0

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

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+# SessionStart hook. stdout is injected into Claude's context every session.
+set -euo pipefail
+cd "${CLAUDE_PROJECT_DIR:-.}"
+
+emit () { printf '%s\n' "$1"; }
+
+emit "=== iStartSoftFlow AUTO-CONTEXT (injected by hook, NOT optional) ==="
+emit ""
+
+# 1. git state
+emit "## Git"
+emit "branch: $(git branch --show-current 2>/dev/null || echo n/a)"
+emit "uncommitted: $(git status --short 2>/dev/null | wc -l | tr -d ' ') file(s)"
+git log --oneline -3 2>/dev/null | sed 's/^/  /' || true
+emit ""
+
+# 2. active state
+if [ -f docs/STATE.md ]; then
+  emit "## STATE.md (current position - READ THIS FIRST)"
+  cat docs/STATE.md
+  emit ""
+else
+  emit "## STATE.md missing -> run /overview to bootstrap the project."
+  emit ""
+fi
+
+# 3. issue log
+if [ -f docs/ISSUES.md ]; then
+  OPEN=$(grep -c '^- \[ \]' docs/ISSUES.md 2>/dev/null || true)
+  OPEN=${OPEN:-0}
+  emit "## ISSUES.md (${OPEN} open) - check this before debugging anything"
+  awk '/^### / {p=1} p' docs/ISSUES.md 2>/dev/null | head -100
+  emit ""
+fi
+
+# 3b. research index
+if [ -f docs/research/INDEX.md ]; then
+  RCOUNT=$(grep -c '^[0-9]' docs/research/INDEX.md 2>/dev/null || true)
+  RCOUNT=${RCOUNT:-0}
+  emit "## research/INDEX.md (${RCOUNT} prior investigations)"
+  emit "grep this before any new research or debugging."
+  grep '^[0-9]' docs/research/INDEX.md 2>/dev/null | tail -15 | sed 's/^/  /' || true
+  emit ""
+fi
+
+
+# 3d. shared KB — pull latest + load snapshot
+KB_CONFIG=".claude/kb-config.json"
+if [ -f "$KB_CONFIG" ]; then
+  KB_PATH=$(python3 -c "import json; print(json.load(open('$KB_CONFIG')).get('kb_path',''))" 2>/dev/null || echo "")
+  KB_PATH_EXPANDED="${KB_PATH/#\~/$HOME}"
+
+  if [ -n "$KB_PATH_EXPANDED" ] && [ -d "$KB_PATH_EXPANDED" ]; then
+    emit "## Shared KB"
+
+    # Pull latest (fail silently — offline or no remote shouldn't break session start)
+    if git -C "$KB_PATH_EXPANDED" pull --ff-only --quiet 2>/dev/null; then
+      emit "KB pulled: OK"
+    else
+      emit "KB pull skipped (offline or conflict — using local copy)"
+    fi
+
+    # Load INDEX.md into session snapshot
+    KB_INDEX="${KB_PATH_EXPANDED}/INDEX.md"
+    SNAPSHOT="docs/.kb-snapshot.md"
+
+    if [ -f "$KB_INDEX" ]; then
+      TODAY=$(date +%Y-%m-%d)
+      CUTOFF=$(date -d "6 months ago" +%Y-%m-%d 2>/dev/null \
+               || python3 -c "from datetime import date, timedelta; print((date.today() - timedelta(days=180)).isoformat())" 2>/dev/null \
+               || echo "2000-01-01")
+
+      {
+        echo "# KB snapshot — loaded $(date +%Y-%m-%d)"
+        echo "# Stale = created date older than ${CUTOFF}"
+        echo ""
+        while IFS='|' read -r entry_date domain slug summary rest; do
+          entry_date=$(echo "$entry_date" | tr -d ' ')
+          # Mark stale if date field present and older than cutoff
+          if [ -n "$entry_date" ] && [[ "$entry_date" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ ]]; then
+            if [[ "$entry_date" < "$CUTOFF" ]]; then
+              echo "[STALE] ${entry_date} |${domain} |${slug} |${summary} |${rest}"
+            else
+              echo "${entry_date} |${domain} |${slug} |${summary} |${rest}"
+            fi
+          else
+            echo "${entry_date} |${domain} |${slug} |${summary} |${rest}"
+          fi
+        done < <(grep -v '^#' "$KB_INDEX" | grep -v '^$')
+      } > "$SNAPSHOT"
+
+      TOTAL=$(grep -c '|' "$SNAPSHOT" 2>/dev/null || echo 0)
+      STALE=$(grep -c '^\[STALE\]' "$SNAPSHOT" 2>/dev/null || echo 0)
+      emit "KB snapshot loaded: ${TOTAL} entries (${STALE} stale — researcher will re-research these)"
+      emit "Snapshot at docs/.kb-snapshot.md — researcher reads this before web search."
+    else
+      emit "KB INDEX.md not found at ${KB_PATH_EXPANDED} — run /store-wisdom to populate it."
+    fi
+    emit ""
+  else
+    emit "## Shared KB: configured but path not found (${KB_PATH})"
+    emit "Re-run setup.sh to fix the KB path."
+    emit ""
+  fi
+fi
+
+# 4. hard rule reminder
+emit "## RULES (enforced this session)"
+emit "- caveman ULTRA mode is active."
+emit "- before debugging ANY error: grep ISSUES.md AND research/INDEX.md first."
+emit "- debug attempts: WARN at 2; first hard-stop at 3 STOPS and asks you."
+emit "- end of every phase: run /synthesize, then /clear."
+emit "- small obvious change? use /quick, not /phase."
+if [ -f "$KB_CONFIG" ]; then
+  emit "- KB active: researcher checks docs/.kb-snapshot.md before web search."
+  emit "- learned something worth keeping? run /store-wisdom."
+fi
+emit "=== END AUTO-CONTEXT ==="
+exit 0

package/template/.claude/hooks/subagent-stop.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# SubagentStop hook.
+set -euo pipefail
+cd "${CLAUDE_PROJECT_DIR:-.}"
+
+mkdir -p docs/.snapshots
+LOG="docs/.snapshots/agent-trace.log"
+echo "$(date +%H:%M:%S) subagent finished" >> "$LOG"
+
+tail -n 50 "$LOG" > "$LOG.tmp" 2>/dev/null && mv "$LOG.tmp" "$LOG" || true
+exit 0

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

@@ -0,0 +1,214 @@
+# iStartSoftFlow — portable agent methodology (single source of truth)
+
+> **Adapted for Saku POS (from the open "anpunkit" workflow by MetheeS).**
+> Namespaced under `.claude/istartsoft-flow/` to coexist with the repo's own
+> `CLAUDE.md` / `AGENTS.md` (Saku project docs) — it does NOT replace them.
+> Cursor support and the Azure infra phase were removed: this repo is Claude-only
+> and infra is **managed (Vercel + Supabase)**, so **Phase 0 (infra) is N/A** —
+> phases begin at the first vertical slice. Planning source of truth stays in
+> **iSSM/BMAD** (PRD/architecture/stories); iStartSoftFlow is the execution loop on top.
+
+<!-- ISTARTSOFTFLOW-AGENTS-SENTINEL-v2.0 -->
+> **SENTINEL.** The HTML comment above (`ISTARTSOFTFLOW-AGENTS-SENTINEL-v2.0`) is a
+> load-bearing marker. `setup.sh` greps for it to confirm this file resolved on
+> disk and was not clobbered. Do not remove or rename it.
+
+> **What this file is.** The complete, tool-agnostic methodology for the iStartSoftFlow
+> workflow: the loop, the roles, the procedures, the rituals, and the hard rules.
+> This is the ONE place every rule lives. Claude Code, Cursor, and any tool that
+> reads the open `AGENTS.md` standard get the full methodology from here.
+
+> **Anti-drift invariant (load-bearing).** Every rule lives in exactly ONE place:
+> this file. `CLAUDE.md` restates NO rule — it only maps roles to Claude-native
+> files and says "native mechanism X performs ritual Y automatically." A rule and
+> its automation may never contradict. Duplication between files is an
+> architectural defect, not a convenience.
+
+Caveman ULTRA mode always on. Apply the `karpathy-guidelines` skill (engineering
+discipline) on every coding and debugging task.
+
+-----
+
+## The loop
+
+`design-research -> grill (×2) -> plan -> implement -> test -> deploy`, one
+VERTICAL SLICE per phase. Implement AND test a phase before the next. The last
+phase always includes deployment.
+
+A phase runs in one of two orders, chosen at RESEARCH time by the TDD
+APPLICABILITY check (see Procedures → `phase`):
+
+- **TDD phase** (`TDD_PHASE=true`):
+  `RESEARCH -> SCAFFOLD -> RED -> GREEN -> TEST(e2e) -> FIX -> CLOSE`
+- **Non-TDD phase** (pure infra / config / doc — `TDD_PHASE=false`):
+  `RESEARCH -> IMPLEMENT -> TEST -> FIX -> CLOSE`
+
+`TDD_PHASE` = "the phase adds or changes a public callable surface (an endpoint,
+exported function/class, CLI command, or message contract) that is assertable
+from the acceptance spec." Size is NOT the criterion. On ambiguity, default
+`TDD_PHASE=true` AND state the classification + reason so a human can override to
+non-TDD before SCAFFOLD fires.
+
+-----
+
+## Roles (fresh-context workers)
+
+Each role is a fresh-context worker. Where the host tool supports named subagents
+(Claude Code natively; Cursor reads the same `.claude/agents/` files via its
+Claude-compatibility path), each maps to a definition file. Where it does not, the role
+degrades to a bounded sub-task that dumps its noise to a file and returns only a
+terse summary + path. Workers cannot address the user — only the orchestrator
+can. Escalation is at most two hops.
+
+- **researcher** — two modes. DESIGN: domain/constraint research before planning
+  (service limits, API contracts, architectural constraints, cost surprises).
+  IMPL: per-phase codebase + service investigation. Checks the shared KB snapshot
+  first (step 0). Writes findings to `docs/research/`; returns terse summary + path.
+- **planner** — research → vertical-slice `docs/PLAN.md`. Phase 0 (infra) always
+  first; the last phase always contains the deploy task.
+- **implementer** — builds ONE phase. Two MODES for TDD phases (SCAFFOLD: stubs
+  only; FILL: logic to green) plus a legacy full-build mode for non-TDD phases.
+  Writes code, never tests. Maintains `docs/ENDPOINTS.md` each phase.
+- **test-author** — writes tests BLIND (never reads implementation logic). On TDD
+  phases it is dispatched BEFORE logic exists (RED-first), so blindness is
+  structural, not honor-system. Writes a MOCK suite + a REAL API suite.
+- **e2e-runner** — writes/runs functional browser E2E (Playwright) BLIND. Reads
+- **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
+  snapshots. On the final phase, also updates `README.md` + `docs/OVERVIEW.md`.
+
+The orchestrator ROUTES. It does not implement or debug.
+
+-----
+
+## Procedures (the slash-command set)
+
+Named procedures, each with a canonical body in `commands.src/<name>.md` and a
+generated copy per tool (`.claude/commands/`, `.cursor/commands/`).
+
+- **overview** — bootstrap a project: design-research → grill r1 → design-research
+  → re-grill r2 → `OVERVIEW.md` → planner → `PLAN.md` (Phase 0 always first).
+- **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.
+- **quick [change]** — small, obvious, non-phase change; no agent chain. Stays
+  non-TDD. Runs the mock regression corpus after the change.
+- **unstuck** — deep re-research after a circuit breaker (human-triggered).
+- **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.
+- **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.
+
+-----
+
+## Rituals (model-run fallback for hooks)
+
+Where the host tool can run lifecycle hooks (Claude Code, Cursor), these rituals
+are AUTOMATED by hook scripts and must NOT be run by hand. Where the tool cannot
+inject context, the model performs them itself.
+
+### SESSION-OPEN (start / clear / compact-resume)
+
+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.
+3. open items in `docs/ISSUES.md`.
+4. `docs/research/INDEX.md` (research map) + infra status + auth nudge.
+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.
+
+### COMPRESS (before a context compaction)
+
+Snapshot the live position to `docs/.snapshots/` so a post-compact session can
+recover: current phase, next action, open blocker.
+
+-----
+
+## Hard rules (1–11)
+
+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.
+2. Debug attempt cap = 3: WARN the user at attempt 2; the FIRST hard-stop at 3
+   STOPS and asks the user. No 4th in-place attempt.
+3. Every resolved error -> logged to `docs/ISSUES.md` with root cause + failed
+   attempts.
+4. End of phase -> synthesize -> context reset -> next phase.
+5. **PHASE GATE** = the current-phase REAL API suite passes AND (frontend phase)
+   the E2E suite passes AND the accumulated mock regression corpus stays green AND
+   every `docs/ENDPOINTS.md` entry has at least one test in `tests/regression/`.
+   The final phase additionally runs the full REAL regression corpus. A green
+   mock suite alone can never close a phase.
+6. Tests are written by `test-author`, which never sees the implementation logic
+   (unbiased). On TDD phases the suite is written before the logic (RED-first).
+   `STACK NOT READY` / `FLAKE` do not spend the debug budget. Only `LOGIC FAIL`
+   reaches the debugger.
+8. E2E auth = ROPC with a dedicated MFA-excluded test account. NEVER script the
+   Microsoft login UI.
+9. Architectural change (new/removed agent, hook, command, or a changed workflow
+   rule)? -> run `log-decision` before closing.
+    work. Never debug an auth error without checking this first.
+11. **No-rationalization (scoped).** Do not downgrade a TDD phase to non-TDD to
+    dodge the RED gate, and do not route phase-worthy work through `quick` to
+    dodge it. (Scoped deliberately to these two seams; this is not a broad
+    "never make excuses" rule.)
+
+-----
+
+## Shared KB (optional)
+
+If `.claude/kb-config.json` exists, the SESSION-OPEN ritual pulls the KB and loads
+a snapshot to `docs/.kb-snapshot.md`. The researcher checks the snapshot (step 0)
+before any web search. Run `store-wisdom` to promote resolved issues + research to
+the KB. The kit works normally without a KB.
+
+-----
+
+## File contract
+
+- `docs/STATE.md` — current position. Small. Rewritten, not appended.
+- `docs/ISSUES.md` — error log. Deduped by synthesizer.
+- `docs/PLAN.md` — the phase plan. Phase 0 (infra) always first; last phase has
+  the deploy task.
+- `docs/HISTORY.md` — one line per finished phase.
+- `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/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).
+- `docs/.snapshots/` — pre-compact recovery markers (auto-pruned, gitignored).
+  holds no secrets.
+- `e2e/`, `scripts/e2e-stack.sh`, `docker-compose.test.yml`, `playwright.config.ts`
+  — the E2E stack.
+- `tests/phase-<n>/` — phase-local test suites.
+- `tests/regression/` — cross-phase contract tests (the regression corpus). Run by
+  `scripts/regression.sh` (default mock; `--real` runs the real corpus).
+- `.claude/kb-config.json` — shared KB path + remote (optional, written by setup.sh).
+- `docs/.kb-snapshot.md` — KB INDEX loaded this session (auto-generated, gitignored).
+
+-----
+
+## Capability matrix (which tools get what)
+
+- **Claude Code — full (reference implementation).** Generated commands; all three
+  lifecycle hooks WITH context injection (SessionStart / PreCompact / SubagentStop);
+  named subagents (`.claude/agents/*.md`); `@AGENTS.md` import; shared KB.
+- **Cursor — full (verified against cursor.com/docs, 2026-06).** Generated
+  commands (`.cursor/commands/`); the three lifecycle hooks via `.cursor/hooks.json`
+  (sessionStart / preCompact / subagentStop) wired to the SAME shared hook scripts —
+  sessionStart injects context via a JSON-envelope wrapper
+  (`cursor-session-start.sh`); named subagents work natively because Cursor reads
+  `.claude/agents/*.md` directly (no duplication); methodology via a
+  `.cursor/rules/` pointer at this file. Known degradations: `model: haiku/opus`
+  tiers are Claude-specific (Cursor falls back to inherit/compatible), and Cursor's
+  preCompact is observational (the snapshot side-effect still runs; no context
+  modification).
+- **Everything else.** Reads this `AGENTS.md` if it supports the open standard.
+  No generated adapters. Not claimed as supported in v2.0.

package/template/.claude/skills/caveman/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: caveman
+description: >
+  Ultra-compressed communication mode. Cuts token usage ~75% by dropping
+  filler, articles, and pleasantries while keeping full technical accuracy.
+  Use when user says "caveman mode", "talk like caveman", "use caveman",
+  "less tokens", "be brief", or invokes /caveman.
+---
+
+Respond terse like smart caveman. All technical substance stay. Only fluff die.
+
+## Persistence
+
+ACTIVE EVERY RESPONSE once triggered. No revert after many turns. No filler drift. Still active if unsure. Off only when user says "stop caveman" or "normal mode".
+
+## Rules
+
+Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). Abbreviate common terms (DB/auth/config/req/res/fn/impl). Strip conjunctions. Use arrows for causality (X -> Y). One word when one word enough.
+
+Technical terms stay exact. Code blocks unchanged. Errors quoted exact.
+
+Pattern: `[thing] [action] [reason]. [next step].`
+
+Not: "Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by..."
+Yes: "Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"
+
+### Examples
+
+**"Why React component re-render?"**
+
+> Inline obj prop -> new ref -> re-render. `useMemo`.
+
+**"Explain database connection pooling."**
+
+> Pool = reuse DB conn. Skip handshake -> fast under load.
+
+## Auto-Clarity Exception
+
+Drop caveman temporarily for: security warnings, irreversible action confirmations, multi-step sequences where fragment order risks misread, user asks to clarify or repeats question. Resume caveman after.

package/template/.claude/skills/grill-me/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: grill-me
+description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree.
+---
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.

package/template/.claude/skills/karpathy-guidelines/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: karpathy-guidelines
+description: Coding and debugging discipline. Apply on every coding and debug task.
+---
+
+# karpathy-guidelines
+
+Apply on every coding + debug task. Caveman ULTRA mode.
+
+## Coding
+- Smallest change that works. No speculative abstraction. No "while I'm here".
+- Make it run, then make it right, then make it fast — in that order.
+- One concern per change. If the diff does two things, split it.
+- Read before write — understand the existing code path before editing.
+- Name things for what they are. Delete dead code, don't comment it out.
+- Prefer boring, obvious solutions over clever ones.
+
+## Debugging
+- Reproduce first.
+- One hypothesis at a time. State it before changing anything.
+- Change one variable, observe, conclude. No shotgun edits.
+- Read the actual error and stack — top to bottom — before theorizing.
+- When stuck: the bug is somewhere you're sure it isn't. Check assumptions.
+- 3 failed attempts -> stop poking, go research.
+
+## Honesty
+- Don't claim it works until you ran it.
+- "I don't know yet" is valid — say it instead of guessing.
+- A failing test is information. Don't edit the test to hide it.
+- Surface uncertainty to the orchestrator; don't paper over it.
+
+## Verification
+- Every change gets run. Lint/typecheck/smoke at minimum.
+- The real test is written blind by test-author — your own run is just sanity.