create-anpunkit 2.0.0

package/template/README.md

@@ -0,0 +1,283 @@
+# anpunkit — AI-coding system development workflow
+
+A reusable, self-navigating workflow for **Claude Code and Cursor**. Install with
+one `npx` command, or clone it directly into your project.
+
+## Why
+
+Codifies a `design-research -> grill -> plan -> implement -> test -> deploy` loop
+with vertical-slice phases, blind testing, agent orchestration, automatic context
+hygiene, and Azure infrastructure as a first-class Phase 0 — so the workflow runs
+itself instead of being hand-steered every session.
+
+## The core idea
+
+Mandatory steps live in **hooks** (deterministic, cannot be skipped).
+Thinking steps live in **subagents + skills** (the model reasons).
+Putting "read the issue log" in a hook is why it stops getting skipped.
+
+## Install
+
+**End users — `npx` (recommended):**
+```bash
+cd my-project
+npx create-anpunkit            # non-destructive: never clobbers your files
+# then open Claude Code or Cursor — the session-start hook fires automatically
+/overview                      # bootstrap the project (includes Phase 0 infra)
+```
+Useful flags: `--dry-run` (print the plan, write nothing), `--force` (overwrite
+user-modified kit files), `--kb-path <dir>` / `--kb-remote <url>` / `--no-kb`.
+
+Upgrading an existing anpunkit project? Re-run `npx create-anpunkit`. It refreshes
+kit-owned files, preserves anything you modified as `<file>.anpunkit-new`, merges
+hook config into your existing `settings.json` / `.cursor/hooks.json`, and writes a
+timestamped `.anpunkit-backup-*/` first.
+
+**Kit developers — clone + `setup.sh`:**
+```bash
+git clone https://github.com/MetheeS/anpunkit.git my-project
+cd my-project && bash setup.sh
+```
+
+> `npx create-anpunkit` requires Node >= 18 and `bash` on PATH (Git Bash on
+> Windows). Claude Code already requires Node, so this adds no new dependency.
+
+## Commands
+
+|Command          |Does                                                                          |
+|-----------------|------------------------------------------------------------------------------|
+|`/overview`      |design-research → grill (×2) → OVERVIEW → PLAN (Phase 0 always first) → STATE |
+|`/infra`         |provision Azure infra: Bicep → what-if → review → apply → INFRA.md + .env.test|
+|`/phase [n]`     |run one phase: research → implement → blind test, with circuit breaker        |
+|`/quick [change]`|small obvious change, direct, no agent chain                                  |
+|`/unstuck`       |deep re-research after a circuit breaker (you trigger it)                     |
+|`/synthesize`    |compress STATE.md, dedup ISSUES.md, prune snapshots                           |
+|`/replan`        |revise PLAN.md when it drifts                                                 |
+|`/log-issue`     |append an error with root cause + failed attempts                             |
+|`/log-decision`  |record an architectural change in DESIGN_LOG.md                               |
+|`/store-wisdom`  |promote resolved issues + research findings to shared KB                      |
+
+## Subagents
+
+`researcher` (Haiku, two modes: design + impl) · `planner` (Opus) · `infra-provisioner` (Opus) ·
+`implementer` (Opus, SCAFFOLD/FILL modes) · `test-author` (Opus, blind, RED-first) · `debugger` (Opus, isolated) ·
+`e2e-runner` (Opus, blind, Playwright) · `synthesizer` (Haiku)
+
+The main session is the orchestrator — it routes, it does not implement.
+
+## The loop (v2.0: TDD-first + regression guard)
+
+Phases that add a public callable surface run test-first:
+`RESEARCH -> SCAFFOLD -> RED -> GREEN -> TEST -> FIX -> CLOSE`. The implementer
+writes interface stubs only; the `test-author` writes the suite blind against
+those stubs (it must collect cleanly and FAIL — the RED gate); the implementer
+then fills to green. Pure infra/config/doc phases keep the direct
+`RESEARCH -> IMPLEMENT -> TEST` order.
+
+Every phase CLOSE runs the accumulated **mock regression corpus**
+(`tests/regression/`, via `scripts/regression.sh`) and a hard ENDPOINTS coverage
+gate — so a contract built in an early phase cannot be silently broken later. The
+final phase additionally runs the full real corpus.
+
+Methodology lives in one place: the portable **`AGENTS.md`** at the repo root.
+`CLAUDE.md` is a thin `@AGENTS.md` shim with Claude-native wiring only.
+
+## Compatibility
+
+|Tool          |What you get                                                                                          |
+|--------------|------------------------------------------------------------------------------------------------------|
+|**Claude Code** (full, reference)|commands, all 3 lifecycle hooks **with context injection**, named subagents, shared KB, `@AGENTS.md` import|
+|**Cursor** (full)|generated commands (`.cursor/commands/`), lifecycle hooks (`.cursor/hooks.json`: sessionStart / preCompact / subagentStop), methodology via a `.cursor/rules/` pointer to `AGENTS.md`|
+|**Other tools**|read `AGENTS.md` if they support the open standard; no generated adapters; not claimed as supported in v2.0|
+
+One canonical command body in `commands.src/<name>.md` generates both tools' command sets at install.
+
+**Cursor — verified against cursor.com/docs (June 2026):**
+- **sessionStart context injection: works.** Cursor's `sessionStart` hook accepts an
+  `additional_context` JSON output field injected into the conversation's initial
+  context. Cursor expects JSON (Claude injects raw stdout), so the shipped wiring
+  runs the shared body through `cursor-session-start.sh`, a thin JSON-envelope
+  wrapper. The hook is fire-and-forget (non-blocking).
+- **Named subagents: work natively.** Cursor reads `.claude/agents/*.md` directly
+  (documented Claude-compatibility path), with `/name` invocation and
+  description-based delegation — one set of role files serves both tools.
+  Caveat: `model: haiku/opus` tiers are Claude-specific; Cursor falls back to
+  `inherit`/a compatible model.
+- **Hook path resolution: project hooks run from the project root** (not
+  `.cursor/`), so the shipped wiring uses `bash .claude/hooks/<script>.sh`. Cursor
+  sets `CLAUDE_PROJECT_DIR` as a compatibility alias, so the shared scripts run
+  unchanged.
+- **preCompact is observational** in Cursor (cannot modify compaction); the
+  snapshot side-effect still runs, which is all the COMPRESS ritual needs.
+
+> Note: Cursor can also load `.claude/settings.json` hooks directly ("Third-party
+> skills" toggle). anpunkit does not rely on this — it requires a manual settings
+> toggle (silent no-op if forgotten) and would double-fire hooks alongside
+> `.cursor/hooks.json`. The explicit native wiring is the supported path.
+
+Codex is **not** a target in v2.0 (its repo-committed command path is deprecated
+home-dir custom-prompts with a divergent UX).
+
+## How each problem is solved
+
+|Your problem                               |Fix in this kit                                                                              |
+|-------------------------------------------|---------------------------------------------------------------------------------------------|
+|Agents miss the issue log                  |SessionStart hook injects open ISSUES.md every session — not optional                        |
+|Manual navigation every session            |SessionStart hook injects STATE.md + git + active phase                                      |
+|Stuck on a bug too long                    |warn at attempt 2; first hard-stop at 3 STOPS and asks you; `/unstuck` for deep re-research  |
+|Context rot during debugging               |`researcher` + `debugger` write full output to `docs/research/`, return only a summary + path|
+|Want orchestration                         |8 scoped subagents; `/phase` is the orchestrator routing them                                |
+|Handoff / memory keeps growing             |`synthesizer` + PreCompact hook compress and dedup                                           |
+|Azure auth friction per session            |`scripts/auth-setup.sh` — one token check, once per session                                  |
+|Infra created ad-hoc mid-phase             |`infra-provisioner` + Phase 0 — provisioned once, reviewed before apply                      |
+|Planning without domain knowledge          |design-researcher runs before planning; double grill absorbs findings                        |
+|Deployment not in the plan                 |planner always puts deploy task in last phase                                                |
+|No endpoint summary at project end         |final-phase close shows usage endpoints from docs/ENDPOINTS.md                               |
+|Re-discovering same gotchas across projects|`/store-wisdom` promotes findings to shared KB; researcher checks KB before web              |
+
+## Files it manages
+
+- `docs/STATE.md` — current position, kept small (rewritten each phase)
+- `docs/ISSUES.md` — error log, deduped by synthesizer
+- `docs/PLAN.md` — vertical-slice phase plan (Phase 0 always first)
+- `docs/HISTORY.md` — one line per finished phase
+- `docs/OVERVIEW.md` — project scope, written after double-grill
+- `docs/INFRA.md` — Azure resource manifest + cost estimates (written by infra-provisioner)
+- `docs/ENDPOINTS.md` — API/service endpoint catalogue (maintained by implementer)
+- `docs/.snapshots/` — pre-compact recovery markers (auto-pruned, gitignored)
+- `infra/` — Bicep templates (generated by infra-provisioner, committed to git)
+
+## Shared Knowledge Base (optional)
+
+The kit can connect to a shared GitHub repo (`anpunkit-kb`) that accumulates
+resolved issues and research findings across all your projects. Once configured,
+the researcher checks the KB at the start of every session — so you stop
+re-discovering the same Azure/Databricks gotchas project after project.
+
+**Setup (one-time per machine):**
+
+```bash
+# 1. Create a GitHub repo: anpunkit-kb (empty)
+# 2. Clone it somewhere permanent on your machine
+git clone git@github.com:your-username/anpunkit-kb.git ~/anpunkit-kb
+
+# 3. During setup.sh, provide the path when prompted
+bash setup.sh
+```
+
+**Usage:**
+
+```
+/store-wisdom    # after a resolved bug or completed phase — promotes findings to KB
+```
+
+See `docs/KB_GUIDE.md` in the anpunkit-kb repo (created by first `/store-wisdom` run).
+
+## Daily flow
+
+```
+/overview                    once per project (design-research + double grill)
+/infra                       once per project (Phase 0) — after /overview
+scripts/auth-setup.sh        once per session (Azure projects)
+/phase 1   ->  /synthesize  ->  /clear
+/phase 2   ->  /synthesize  ->  /clear
+...
+# last phase -> shows usage endpoints automatically
+# bug won't die?  ->  /unstuck
+# plan drifted?   ->  /replan
+# learned something worth keeping?  ->  /store-wisdom
+```
+
+## Azure infrastructure (Phase 0)
+
+The kit treats Azure infra as **Phase 0** — provisioned once before any code
+phase starts, owned by the `infra-provisioner` subagent.
+
+### Phase 0 flow
+
+```
+/overview          # includes Phase 0 in PLAN.md automatically
+/infra             # generates Bicep -> what-if diff -> you review -> "go" -> apply
+                   # writes docs/INFRA.md (resource manifest + cost estimates)
+                   # writes .env.test (generated, never fill manually)
+/phase 1           # PRE-FLIGHT checks Phase 0 is done before starting
+```
+
+### Session startup (Azure projects)
+
+Run once per session before any Azure work:
+
+```bash
+scripts/auth-setup.sh
+```
+
+Checks your `az` token is fresh and the right subscription is active.
+Prompts `az login` only if stale. No credential storage — your account only.
+
+### What /infra does
+
+1. `infra-provisioner` reads `docs/OVERVIEW.md` for the system design
+1. Generates `infra/main.bicep` + per-service modules under `infra/modules/`
+1. Runs `az deployment what-if` — shows exactly what will be created
+1. **Stops and waits for your “go”** — nothing applied without your review
+1. Applies the deployment
+1. Writes `docs/INFRA.md` — resource IDs, endpoints, cost estimates (THB, SEA region)
+1. Generates `.env.test` from the manifest
+
+Re-run `/infra` any time infra drifts or a new resource is needed.
+Re-run `/infra regenerate-env` to refresh `.env.test` only.
+
+### Cost awareness
+
+`infra-provisioner` annotates every resource in `INFRA.md` with an estimated
+monthly cost. It uses production-appropriate SKUs by default — not artificially
+cheap dev tiers that need resizing before go-live.
+
+### E2E target
+
+`infra-provisioner` determines the E2E target from the system design:
+
+- **azure-deployed**: `E2E_STACK_EXTERNAL=1` — Playwright hits your deployed Azure app.
+- **local-docker**: Containers run the app, pointed at real Azure services.
+
+### Test data
+
+Seeding and cleanup are **deployment phase** concerns, not E2E concerns.
+`e2e-stack.sh` has no seed/cleanup commands.
+
+## End-to-end testing
+
+Three layers: unit/integration (mock suite), real API (`test-author`), and
+functional browser E2E (`e2e-runner`, Playwright).
+
+**Phase gate:** a frontend-touching phase closes only when the real API suite
+AND the browser E2E suite pass. Mock-green alone never closes a phase.
+
+**MSAL / Entra ID auth.** Browser E2E never drives the Microsoft login UI.
+`e2e/global-setup.ts` uses ROPC flow with a dedicated test account (MFA excluded
+via Conditional Access) to fetch a real token and inject it into the MSAL cache.
+
+**E2E setup (one-time per project):**
+
+1. Run `/infra` — it generates `.env.test` automatically.
+1. Provision the Entra test user + Conditional Access MFA exclusion.
+1. `npm i -D @playwright/test && npx playwright install chromium`
+
+## Windows / Git Bash
+
+The hooks are bash scripts. On Windows they run under **Git Bash**.
+
+- **Line endings.** The shipped `.gitattributes` pins all `.sh` files to LF.
+- **`bash` on PATH.** Verify in PowerShell: `bash --version`.
+
+Hook commands use a BARE `bash` prefix: `bash .claude/hooks/session-start.sh`.
+Never an explicit bash.exe path — that triggers a Claude Code argument-splitter bug.
+
+**Verifying hooks:** in a fresh session ask Claude:
+
+> What does my STATE.md say, and how many open issues are in ISSUES.md?
+
+A correct answer without reading any file = hooks working. No visible banner on
+newer Claude Code versions is normal — injection may be silent.
+
+(WSL users: the kit runs as-is — WSL is Linux.)

package/template/commands.src/infra.md

@@ -0,0 +1,62 @@
+---
+description: Provision or verify Azure infrastructure. Generates Bicep, shows what-if diff for your review, applies only after your approval, writes docs/INFRA.md and .env.test.
+argument-hint: [provision | verify | update <what changed> | regenerate-env]
+---
+
+Caveman ULTRA mode. You are the ORCHESTRATOR.
+
+Action: $ARGUMENTS (default: "provision" if INFRA.md missing, "verify" if present)
+
+---
+
+## PRE-FLIGHT
+
+1. Check `az account show` — if it fails, STOP.
+   Tell me: "Run `scripts/auth-setup.sh` first."
+
+2. Determine mode from $ARGUMENTS or default logic.
+
+---
+
+## PROVISION / UPDATE flow
+
+1. Dispatch `infra-provisioner` with the mode.
+
+2. It returns WHAT-IF READY. Show me:
+   - resource list with SKUs and costs
+   - total monthly cost estimate
+   - what-if detail file path
+   Then ask:
+   > "Review docs/research/infra-whatif-<timestamp>.md. Type 'go' to apply,
+   >  or describe changes to make first."
+   WAIT. Do not proceed until I say "go".
+
+3. On "go": pass APPROVED to `infra-provisioner`.
+
+4. On "make changes": dispatch UPDATE with feedback. Loop to step 2.
+
+5. On APPLIED: tell me INFRA.md ✓, .env.test ✓, and any manual steps remaining.
+
+---
+
+## VERIFY flow
+
+1. Check INFRA.md exists. If missing: tell me to run `/infra provision` first.
+2. Dispatch `infra-provisioner` VERIFY mode.
+3. Return drift report.
+
+---
+
+## REGENERATE-ENV flow
+
+1. Check INFRA.md exists.
+2. Dispatch `infra-provisioner` REGENERATE-ENV.
+3. Confirm .env.test rewritten.
+
+---
+
+## Notes
+
+- /infra never touches PLAN.md, STATE.md, ISSUES.md, or DESIGN_LOG.md.
+- Infra errors are AZURE UNAVAILABLE or CONFIG ERROR — do NOT route to debugger.
+- If UNDERSPEC: list missing decisions, ask me to fill them, re-dispatch.

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

@@ -0,0 +1,34 @@
+---
+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
+- infra changes -> INFRA.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/commands.src/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/commands.src/overview.md

@@ -0,0 +1,106 @@
+---
+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.
+   Cover: project purpose, success criteria, external services, Azure services
+   needed (type + sizing), region, deployment target (Azure or local for E2E),
+   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?
+   - Azure services: any sizing or SKU constraints relevant to the use case?
+   - 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
+   - "Azure services" section: every service with expected SKU
+   - Deployment target (azure-deployed or local-docker for E2E)
+   - 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
+next: run /infra to provision Azure infrastructure
+blocker: none
+
+```
+8. Create docs/ISSUES.md with header `# Issues` and `## Archived` section.
+
+9. Create empty docs/HISTORY.md.
+
+10. Create docs/INFRA.md from the template (populated by /infra).
+
+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.
+
+Remind me: "Run `/infra` next to provision the Azure environment (Phase 0)
+before starting Phase 1."