create-anpunkit 2.0.0

package/template/.cursor/commands/quick.md

@@ -0,0 +1,25 @@
+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/.cursor/commands/replan.md

@@ -0,0 +1,59 @@
+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:
+   - A new external service is mentioned (Stripe, Twilio, a new Azure service, etc.)
+   - 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/.cursor/commands/store-wisdom.md

@@ -0,0 +1,191 @@
+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>
+Domain: <inferred path, e.g. azure/auth.md or databricks/sdk.md>
+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
+   # anpunkit-kb — guide
+
+   This repo accumulates resolved issues and research findings from anpunkit projects.
+   Populated by `/store-wisdom`. Read by the anpunkit `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/.cursor/commands/synthesize.md

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

package/template/.cursor/commands/unstuck.md

@@ -0,0 +1,36 @@
+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/.cursor/hooks.json

@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [
+      { "command": "bash .claude/hooks/cursor-session-start.sh" }
+    ],
+    "preCompact": [
+      { "command": "bash .claude/hooks/pre-compact.sh" }
+    ],
+    "subagentStop": [
+      { "command": "bash .claude/hooks/subagent-stop.sh" }
+    ]
+  }
+}

package/template/.cursor/rules/anpunkit.md

@@ -0,0 +1,11 @@
+---
+description: anpunkit methodology — load on every session.
+alwaysApply: true
+---
+
+# anpunkit
+
+Methodology, roles, procedures, rituals, and hard rules live in `@AGENTS.md`
+at the repo root. Read it and follow it for all work in this repository.
+
+@AGENTS.md

package/template/.gitattributes

@@ -0,0 +1,12 @@
+# Shell scripts MUST stay LF, even on Windows.
+*.sh    text eol=lf
+*.bash  text eol=lf
+.claude/hooks/*  text eol=lf
+*.js    text eol=lf
+*.mjs   text eol=lf
+*.ts    text eol=lf
+*.json  text eol=lf
+*.md    text eol=lf
+*.ps1   text eol=crlf
+*.cmd   text eol=crlf
+*.bat   text eol=crlf

package/template/AGENTS.md

@@ -0,0 +1,216 @@
+# anpunkit — portable agent methodology (single source of truth)
+
+<!-- ANPUNKIT-AGENTS-SENTINEL-v2.0 -->
+> **SENTINEL.** The HTML comment above (`ANPUNKIT-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 anpunkit
+> 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.
+- **infra-provisioner** — generates Bicep, runs `az deployment what-if`, applies
+  only on human approval, writes `docs/INFRA.md` + `.env.test`.
+- **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
+  `docs/INFRA.md` for the target.
+- **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).
+- **infra** — provision/verify Azure infra: Bicep → what-if → human review → apply
+  → `INFRA.md` + `.env.test`.
+- **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).
+7. Service outage is not a bug — `SERVICE UNAVAILABLE` / `AZURE UNAVAILABLE` /
+   `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.
+10. Azure project? Run `scripts/auth-setup.sh` ONCE per session before any Azure
+    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`.
+- `docs/INFRA.md` — Azure infra manifest: resource IDs, endpoints, cost estimates,
+  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).
+- `infra/` — Bicep templates. Committed (IaC audit trail). `infra/params.json`
+  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).
+- `scripts/auth-setup.sh` — session Azure credential check. Run once per session.
+- `.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.md

@@ -0,0 +1,70 @@
+@AGENTS.md
+
+# CLAUDE.md — Claude Code native wiring (thin shim)
+
+> This file restates NO methodology. Every rule, role, procedure, and ritual
+> lives in `AGENTS.md`, imported above via the bare `@AGENTS.md` line (the first
+> non-comment line — `setup.sh` VERIFY checks it is bare, top-level, and
+> unfenced). This shim only maps the methodology onto Claude Code's native
+> mechanisms.
+
+## Subagent roster
+
+The roles defined in AGENTS.md map to these Claude Code subagent files:
+
+|Role              |Definition file                       |Model tier|
+|------------------|--------------------------------------|----------|
+|researcher        |`.claude/agents/researcher.md`        |haiku     |
+|planner           |`.claude/agents/planner.md`           |opus      |
+|infra-provisioner |`.claude/agents/infra-provisioner.md` |opus      |
+|implementer       |`.claude/agents/implementer.md`       |opus      |
+|test-author       |`.claude/agents/test-author.md`       |opus      |
+|e2e-runner        |`.claude/agents/e2e-runner.md`        |opus      |
+|debugger          |`.claude/agents/debugger.md`          |opus      |
+|synthesizer       |`.claude/agents/synthesizer.md`       |haiku     |
+
+## Hooks automate the AGENTS.md rituals
+
+On Claude Code, do NOT run the SESSION-OPEN or COMPRESS rituals by hand — the
+hooks (wired in `.claude/settings.json`) perform them:
+
+- **SessionStart** (`.claude/hooks/session-start.sh`) automates SESSION-OPEN:
+  auto session-open + KB pull + STATE/ISSUES/research/infra injection into context.
+- **PreCompact** (`.claude/hooks/pre-compact.sh`) automates COMPRESS: snapshots the
+  live position before compaction.
+- **SubagentStop** (`.claude/hooks/subagent-stop.sh`) writes a subagent trace.
+
+The same script bodies are wired for Cursor in `.cursor/hooks.json`; only the
+wiring differs (Cursor's sessionStart expects JSON output, so it runs the shared
+body through the `cursor-session-start.sh` envelope wrapper). Cursor also reads
+`.claude/agents/*.md` natively for subagents — one set of role files serves both
+tools.
+
+## /clear keeps hooks
+
+`/clear` does not drop hooks — the wiring lives in `settings.json`, not in
+context. After `/clear`, SessionStart fires again and re-injects state.
+
+## Skills resolution
+
+- `karpathy-guidelines` — kit-owned (`.claude/skills/karpathy-guidelines/`).
+- `caveman`, `grill-me` — global-authoritative if installed; the vendored copies
+  under `.claude/skills/` are a fallback only.
+
+## Platform notes
+
+- **Windows / Git Bash.** Hooks are bash scripts. Hook commands use a BARE `bash`
+  prefix (`bash .claude/hooks/session-start.sh`) — never an explicit `bash.exe`
+  path (triggers a Claude Code argument-splitter bug). `.gitattributes` pins all
+  `.sh` files to LF. WSL runs the kit as-is.
+- **Plan mode.** Run planning-heavy commands (`/overview`, `/replan`) from plan
+  mode (Shift+Tab).
+
+## Silent injection (Claude Code 2.1.x) + fresh-session test
+
+On Claude Code 2.1.x the SessionStart injection may be silent (no visible banner).
+That is normal. To verify hooks are live, in a fresh session ask:
+
+> What does my STATE.md say, and how many open issues are in ISSUES.md?
+
+A correct answer without Claude reading any file = hooks working.