create-anpunkit 2.2.0 → 2.3.0

package/template/README.md

@@ -1,14 +1,18 @@
 # 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.
+A reusable, self-navigating workflow for **Claude Code**. 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.
+with vertical-slice phases, blind testing, agent orchestration, and automatic
+context hygiene — so the workflow runs itself instead of being hand-steered every
+session. The invariant core (loop, gates, doc system, commands) is use-case
+agnostic; web/Azure practice ships as **preinstalled knowledge docs**
+(`knowledge/webapp.md`, `knowledge/azure.md`) that the researcher consults only
+when your declared project type calls for them. Works for web apps, desktop apps,
+scripts, and libraries alike.
 
 ## The core idea
 
@@ -22,20 +26,22 @@ Putting "read the issue log" in a hook is why it stops getting skipped.
 ```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)
+# then open Claude Code — the session-start hook fires automatically
+/overview                      # bootstrap the project (declares project type + flags)
 ```
-Useful flags: `--dry-run` (print the per-tool plan, write nothing), `--force`
-(overwrite user-modified kit files), `--tools <claude,cursor>` (install only the
-selected tools' files; interactive menu if omitted on a fresh TTY install),
-`--add-tool <name>` (lay down an additional tool's files into an existing
-project), `--kb-path <dir>` (your pre-cloned KB repo; remote auto-recorded from
-its origin) / `--no-kb`.
+Useful flags: `--dry-run` (print the plan, write nothing), `--force` (overwrite
+user-modified kit files), `--kb-path <dir>` (your pre-cloned KB repo; remote
+auto-recorded from its origin) / `--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.
+hook config into your existing `.claude/settings.json`, and writes a timestamped
+`.anpunkit-backup-*/` first.
+
+> **Upgrading from v2.2 (Cursor dropped):** v2.3 is Claude Code only. After
+> upgrading you may safely delete the now-orphaned `.cursor/`,
+> `.claude/hooks/cursor-session-start.sh`, and `.claude/anpunkit-tools.json` —
+> setup.sh no longer manages them.
 
 **Kit developers — clone + `setup.sh`:**
 ```bash
@@ -50,8 +56,8 @@ cd my-project && bash setup.sh
 
 |Command          |Does                                                                          |
 |-----------------|------------------------------------------------------------------------------|
-|`/overview`      |design-research → RESEARCH REVIEW → grill (×2, incl. data/state flow) → OVERVIEW + DATAFLOW → PLAN (Phase 0 first) → STATE|
-|`/infra`         |provision Azure infra: Bicep → what-if → review → apply → INFRA.md + .env.test → AUTH PROOF|
+|`/overview`      |design-research → RESEARCH REVIEW → grill (×2, incl. data/state flow) → OVERVIEW (+ project flags) + DATAFLOW → PLAN → STATE|
+|`/infra`         |provision infra (when `infra_needed`): IaC → what-if → review → apply → INFRA.md + .env.test → AUTH PROOF|
 |`/phase [n]`     |run one phase: research → SPEC fill → SPEC REVIEW → SCAFFOLD → RED → conformance → GREEN → boundary/E2E, with circuit breaker|
 |`/quick [change]`|small obvious change, direct, no agent chain                                  |
 |`/unstuck`       |deep re-research after a circuit breaker (you trigger it)                     |
@@ -70,7 +76,16 @@ cd my-project && bash setup.sh
 
 The main session is the orchestrator — it routes, it does not implement.
 
-## The loop (v2.2: spec-driven contract + upstream human gate + generated tests)
+## The loop (v2.3: adaptive to project type + spec-driven contract + upstream human gate)
+
+**Project flags (declared at `/overview`).** The grill asks your `project_type`
+(web app / desktop app / script / library / other) and what "shipped" means. From
+that it derives `infra_needed`, `e2e_kind` (browser / cli / http / library-api),
+`deploy_kind` (cloud-deploy / package-publish / install-run-verified / none), and
+which `knowledge_docs` to consult — all recorded in `docs/OVERVIEW.md`, never
+inferred mid-phase. Phase 0 (infra) exists only when `infra_needed`; the boundary
+run is selected by `e2e_kind`; the final phase completes `deploy_kind`.
+
 
 Phases that add a public callable surface run spec-first:
 `RESEARCH -> SPEC fill -> spec-staleness -> SPEC REVIEW -> SCAFFOLD -> RED -> spec-conformance -> GREEN -> boundary/E2E -> FIX -> CLOSE`.
@@ -115,37 +130,22 @@ Methodology lives in one place: the portable **`AGENTS.md`** at the repo root.
 
 |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).
+|**Claude Code** (the supported target)|commands, all 3 lifecycle hooks **with context injection**, named subagents, shared KB, `@AGENTS.md` import|
+|**Other tools**|read `AGENTS.md` if they support the open standard; no generated adapters, no support claim|
+
+The canonical command bodies live in `commands.src/<name>.md`, copied to
+`.claude/commands/` at install. **Cursor support was dropped in v2.3** (§5.69) —
+the maintenance cost exceeded demand. v2.3 is Claude Code only.
+
+## Compression
+
+Output compression is a kit-native, always-on facility (`.claude/ref/compression.md`),
+not a skill and never model-invoked. Two profiles: `user` (human-facing, keeps the
+Auto-Clarity exception for security warnings, irreversible-action confirmations,
+multi-step sequences, and clarification requests) and `internal` (agent↔agent,
+harder). `AGENTS.md` declares `user`; every subagent prompt points at `internal`.
+Exact-output artifacts (fixtures, spec rows, generated tests) are exempted by
+structural gates in the emitter prompts.
 
 ## How each problem is solved
 
@@ -157,10 +157,10 @@ home-dir custom-prompts with a divergent UX).
 |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                                                |
+|Cloud auth friction per session            |liveness ritual recorded in INFRA.md `## AUTH` (Azure: `knowledge/azure.md`) — one check per session|
+|Infra created ad-hoc mid-phase             |`infra-provisioner` + Phase 0 when `infra_needed` — provisioned once, reviewed before apply  |
+|Planning without domain knowledge          |design-researcher runs before planning; consults matching `knowledge/*.md`; double grill absorbs findings|
+|Deployment not in the plan                 |planner always puts the `deploy_kind` completion task in the 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              |
 
@@ -168,17 +168,19 @@ home-dir custom-prompts with a divergent UX).
 
 - `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/PLAN.md` — vertical-slice phase plan (Phase 0 first when `infra_needed`)
 - `docs/HISTORY.md` — one line per finished phase
 - `docs/OVERVIEW.md` — project scope, written after double-grill
 - `docs/DATAFLOW.md` — state-transition table per key object (grilled at /overview; drives CLOSE coverage gate)
 - `docs/spec-phase-<n>.md` — per-phase behavioral contract (skeleton at /overview, filled by spec-author; human-reviewed at SPEC REVIEW)
 - `fixtures/<case-id>-{input,expected,ui}.json` — shared by the spec row and the generated test harness (committed; part of the contract)
 - `tests/helpers/spec-assert.{py,ts}` — kit-versioned matcher-aware comparator (honors `<UUID>`, `<ISO8601>`, … tokens)
-- `docs/INFRA.md` — Azure resource manifest + cost estimates (written by infra-provisioner)
+- `docs/INFRA.md` — infra resource manifest + cost estimates (when `infra_needed`; 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)
+- `knowledge/webapp.md`, `knowledge/azure.md` — preinstalled matured practice + materializable templates
+- `.claude/ref/compression.md` — kit-native compression profiles (`user`, `internal`)
+- `infra/` — IaC templates (generated by infra-provisioner, committed to git)
 
 ## Shared Knowledge Base (optional)
 
@@ -216,8 +218,8 @@ See `docs/KB_GUIDE.md` in the anpunkit-kb repo (created by first `/store-wisdom`
 
 ```
 /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)
+/infra                       once per project (Phase 0) — only when infra_needed
+<INFRA.md AUTH command>      once per session (infra projects; Azure: scripts/auth-setup.sh)
 /phase 1   ->  /synthesize  ->  /clear
 /phase 2   ->  /synthesize  ->  /clear
 ...
@@ -227,83 +229,50 @@ scripts/auth-setup.sh        once per session (Azure projects)
 # learned something worth keeping?  ->  /store-wisdom
 ```
 
-## Azure infrastructure (Phase 0)
+## Use-case knowledge (infra, E2E, deploy)
+
+The invariant core ships nothing use-case specific. Matured web/Azure practice
+lives in **preinstalled knowledge docs** that the `researcher` consults at RESEARCH
+when your declared `project_type` matches (recorded in OVERVIEW `knowledge_docs`):
 
-The kit treats Azure infra as **Phase 0** — provisioned once before any code
-phase starts, owned by the `infra-provisioner` subagent.
+- **`knowledge/webapp.md`** — browser E2E practice (Playwright, closed assert
+  vocabulary, screenshot evidence) plus the E2E stack ritual and the
+  `playwright.config.ts` / `e2e/global-setup.ts` / `docker-compose.test.yml` /
+  `scripts/e2e-stack.sh` templates, materialized into your project on demand.
+- **`knowledge/azure.md`** — the once-per-session auth ritual (`scripts/auth-setup.sh`
+  template), Entra/MSAL ROPC + MFA-excluded test account practice, and the Bicep /
+  `az` provisioning patterns (Key Vault, THB cost annotations, SEA region default).
 
-### Phase 0 flow
+### Infra (Phase 0, when `infra_needed`)
+
+Application project types (web app, desktop app, service) set `infra_needed: true`;
+scripts and libraries set it false and skip Phase 0 entirely. When present, Phase 0
+is provisioned once before any code phase, owned by `infra-provisioner`:
 
 ```
-/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)
+/overview          # declares infra_needed; includes Phase 0 in PLAN.md when true
+/infra             # generates IaC -> what-if diff -> you review -> "go" -> apply
+                   # writes docs/INFRA.md (resource manifest + cost estimates + ## AUTH)
                    # writes .env.test (generated, never fill manually)
                    # runs AUTH PROOF (every credential proven reusable headlessly)
 /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
-1. Runs the **AUTH PROOF** — proves every credential (Entra/MSAL + datasources) is obtainable headlessly twice in a row
-
-Re-run `/infra` any time infra drifts or a new resource is needed.
-Re-run `/infra regenerate-env` to refresh `.env.test` only.
-Re-run `/infra auth-proof` to re-prove credentials on demand.
-
-### 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).
+Cloud specifics (Azure `az`/Bicep commands, region/cost conventions, the session
+auth ritual) live in `knowledge/azure.md`, consulted by `infra-provisioner`.
 
-**Phase gate:** a frontend-touching phase closes only when the real API suite
-AND the browser E2E suite pass with screenshot evidence. Mock-green alone never closes a phase.
+### Boundary testing (per `e2e_kind`)
 
-**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.
+The boundary run is selected by the phase's bound `e2e_kind`:
 
-**E2E setup (one-time per project):**
+- **browser** (frontend phases): `e2e-runner` emits Playwright from each `ui` case's
+  descriptor and captures a screenshot at every UI-existence assertion — on success
+  too — to a gitignored `docs/evidence/` dir. Stack ritual + templates:
+  `knowledge/webapp.md`.
+- **cli / http / library-api**: the phase's real-mode boundary suite runs against
+  the shipped outer surface, transcript captured as evidence.
 
-1. Run `/infra` — it generates `.env.test` automatically and runs the AUTH PROOF.
-1. Provision the Entra test user + Conditional Access MFA exclusion.
-1. `npm i -D @playwright/test && npx playwright install chromium`
+Mock-green alone never closes a phase.
 
 ## Windows / Git Bash
 

package/template/commands.src/infra.md

@@ -3,16 +3,20 @@ description: Provision or verify Azure infrastructure. Generates Bicep, shows wh
 argument-hint: [provision | verify | update <what changed> | regenerate-env | auth-proof]
 ---
 
-Caveman ULTRA mode. You are the ORCHESTRATOR.
+compression: user (.claude/ref/compression.md). You are the ORCHESTRATOR.
 
 Action: $ARGUMENTS (default: "provision" if INFRA.md missing, "verify" if present)
 
+Only meaningful when docs/OVERVIEW.md has `infra_needed: true`. If
+`infra_needed: false`, tell me this project has no infra phase and STOP.
+
 ---
 
 ## PRE-FLIGHT
 
-1. Check `az account show` — if it fails, STOP.
-   Tell me: "Run `scripts/auth-setup.sh` first."
+1. Confirm cloud CLI auth per the project's knowledge doc (Azure:
+   `knowledge/azure.md` ritual — `bash scripts/auth-setup.sh`; materialize it if
+   absent). If it fails, STOP and tell me the exact command to run.
 
 2. Determine mode from $ARGUMENTS or default logic.
 

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

@@ -3,7 +3,7 @@ description: Record an architectural decision in docs/DESIGN_LOG.md. Use only wh
 argument-hint: [what changed]
 ---
 
-Caveman ULTRA mode.
+compression: user (.claude/ref/compression.md).
 
 Append an architectural decision to docs/DESIGN_LOG.md. Change: $ARGUMENTS
 

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

@@ -3,7 +3,7 @@ description: Log an error to docs/ISSUES.md with root cause + solution, in the c
 argument-hint: [short error description]
 ---
 
-Caveman ULTRA mode.
+compression: user (.claude/ref/compression.md).
 
 Append an entry to docs/ISSUES.md. Error: $ARGUMENTS
 

package/template/commands.src/overview.md

@@ -2,7 +2,7 @@
 description: Bootstrap a new project. Runs design-research, research review, double grill (incl. data/state flow), datasource-understanding baseline, and planning. Run once per project.
 ---
 
-Caveman ULTRA mode.
+compression: user (.claude/ref/compression.md).
 
 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.
@@ -16,11 +16,17 @@ Goal: stand up a fresh project workspace with a well-grounded plan.
 ### 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. ALSO establish:
+   Cover: project purpose, success criteria, external services, cloud/infra
+   services needed (type + sizing, if any), region, known constraints, unknowns.
+   ALSO establish:
+   - **project_type**: web app / desktop app / script / library / other. This
+     drives the deterministic flag derivation (step 6) and knowledge-doc
+     selection.
    - **has_frontend**: is there a browser-facing UI? If yes, what is the frontend
      root path (e.g. `src/web/`, `app/`)? This drives the mandatory-E2E path match.
+   - **deploy meaning**: what does "done and shipped" mean for this project —
+     cloud deploy (where?), package publish (which registry?), verified
+     install/run instructions, or none (why)? This sets `deploy_kind`.
    Do not stop early. Do not write OVERVIEW.md yet.
 
 Store the round-1 answers as working context — do NOT write OVERVIEW.md yet.
@@ -86,11 +92,23 @@ Store the round-1 answers as working context — do NOT write OVERVIEW.md yet.
    - 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)
+   - Cloud/infra services section: every service with expected SKU (if any)
    - `has_frontend: true|false` and, if true, the frontend root path
    - Known risks / open questions (if any remain)
 
+   PROJECT FLAGS (hard rule 10 — declared once here, recorded verbatim, never
+   re-derived later):
+   - `project_type: web app|desktop app|script|library|other` (declared in round 1)
+   - `infra_needed: true|false` — derived: application types (web app, desktop
+     app, service) → true; script / library → false. Overridable here with a
+     stated reason.
+   - `e2e_kind: browser|cli|http|library-api` — derived: has_frontend → browser;
+     backend/API service → http; script → cli; library → library-api.
+   - `deploy_kind: cloud-deploy|package-publish|install-run-verified|none(<reason>)`
+     (from the round-1 "deploy meaning" answer).
+   - `knowledge_docs:` — derived list: web app or has_frontend → `knowledge/webapp.md`;
+     Azure services declared OR Azure cloud-deploy → `knowledge/azure.md`; else empty.
+
    OVERVIEW.md is written HERE — after the re-grill, not before.
 
 7. Write docs/DATAFLOW.md — a state-transition table per key object, driven by the
@@ -112,8 +130,10 @@ Store the round-1 answers as working context — do NOT write OVERVIEW.md yet.
 
 8. Hand OVERVIEW.md + DATAFLOW.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.
+   - Start with Phase 0 (infra setup) as the first entry IFF `infra_needed: true`;
+     when `infra_needed: false` there is no Phase 0 — Phase 1 is the first entry.
+   - End with a final code phase whose deploy task completes `deploy_kind`
+     (cloud deploy / package publish / verified install-run / none-with-reason).
    - For any phase whose `changes` touch the frontend root: include ≥1
      UI-existence acceptance criterion naming the specific user-visible
      interactive element the phase introduces (not "page renders 200").
@@ -138,15 +158,18 @@ Store the round-1 answers as working context — do NOT write OVERVIEW.md yet.
 
 phase: 0 (pending)
 completed: project bootstrapped — design research, research review, double grill (incl. data/state flow) done
-next: run /infra to provision Azure infrastructure
+next: <if infra_needed: "run /infra to provision infrastructure (Phase 0)"; else "run /phase 1">
 blocker: none
 
 ```
+   When `infra_needed: false`, set `phase: 1 (pending)` and the next line to
+   "run /phase 1".
 10. Create docs/ISSUES.md with header `# Issues` and `## Archived` section.
 
 11. Create empty docs/HISTORY.md.
 
-12. Create docs/INFRA.md from the template (populated by /infra).
+12. Create docs/INFRA.md from the template (populated by /infra). Skip when
+    `infra_needed: false`.
 
 13. Create docs/ENDPOINTS.md:
  ```
@@ -162,5 +185,7 @@ case NAMES (no values). I confirm the case-name set is COMPLETE here — these n
 are the up-front behavioral contract; values get filled + reviewed per phase at
 `/phase` SPEC REVIEW.
 
-Remind me: "Run `/infra` next to provision the Azure environment (Phase 0) and
-run the one-time AUTH PROOF before starting Phase 1."
+Remind me of the next step per `infra_needed`:
+- `infra_needed: true` → "Run `/infra` next to provision the environment (Phase 0)
+  and run the one-time AUTH PROOF before starting Phase 1."
+- `infra_needed: false` → "No infra phase — run `/phase 1` to start."

package/template/commands.src/phase.md

@@ -3,7 +3,7 @@ description: Run one phase end-to-end. TDD phases run SPEC fill -> SPEC REVIEW -
 argument-hint: [phase number]
 ---
 
-Caveman ULTRA mode. You are the ORCHESTRATOR. Route work to subagents —
+compression: user (.claude/ref/compression.md). You are the ORCHESTRATOR. Route work to subagents —
 you do NOT implement, fill specs, or debug yourself.
 
 Note: subagents cannot talk to the user. Only YOU can.
@@ -14,8 +14,9 @@ Target phase: $ARGUMENTS  (default: the phase marked pending in docs/PLAN.md)
 
 ## 0. PRE-FLIGHT
 
-a. INFRA CHECK (phases > 0):
-   - Read docs/INFRA.md. If Phase 0 not done -> STOP.
+a. INFRA CHECK (phases > 0): read docs/OVERVIEW.md `infra_needed`.
+   - `infra_needed: false` -> no Phase 0 exists; SKIP this check entirely.
+   - `infra_needed: true`: read docs/INFRA.md. If Phase 0 not done -> STOP.
      Tell me: "Phase 0 (infra) not complete. Run `/infra` first."
    - Exception: if $ARGUMENTS is "0", tell me to run `/infra` directly.
 
@@ -29,13 +30,14 @@ b. PHASE STATE CHECK: Read docs/STATE.md and docs/PLAN.md.
 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.
 
-d. AUTH LIVENESS GATE (hard rule 16): if this phase will run a boundary/E2E suite,
-   confirm every credential it needs is live NOW.
+d. AUTH LIVENESS GATE (hard rule 16): only if this phase touches a credentialed
+   external service and will run a boundary/E2E suite. Skip otherwise.
    - If INFRA.md has no `AUTH PROOF: PASS` marker -> STOP: "Auth never proven
      reusable. Run `/infra` first."
-   - Run `scripts/auth-setup.sh --check` (Entra token obtainable + not expired)
-     and, for each external system this phase touches (docs/DATAFLOW.md external
-     rows + docs/ENDPOINTS.md auth column), confirm its credential is obtainable
+   - Run the liveness command recorded in docs/INFRA.md `## AUTH` (Azure projects:
+     the ritual per `knowledge/azure.md`, i.e. `bash scripts/auth-setup.sh`) and,
+     for each external system this phase touches (docs/DATAFLOW.md external rows +
+     docs/ENDPOINTS.md auth column), confirm its credential is obtainable
      headlessly. Any failure -> boundary/E2E is BLOCKED; tell me what to run; the
      MOCK suite may still proceed.
 
@@ -45,6 +47,10 @@ e. FRONTEND TRIGGER (hard rule 13): read docs/OVERVIEW.md `has_frontend` + the
    This is a PATH MATCH, not a judgment call. Record FRONTEND_PHASE — it gates the
    `ui` boundary run + evidence at CLOSE.
 
+f. FLAG BASELINES: read docs/OVERVIEW.md `e2e_kind` + `deploy_kind`. These are the
+   project baselines; §1 binds this phase's effective E2E_KIND and (final phase)
+   confirms DEPLOY_KIND.
+
 ---
 
 ## 1. RESEARCH + TDD APPLICABILITY
@@ -75,6 +81,11 @@ Then classify the phase:
   to me, so I can override to non-TDD BEFORE SPEC fill fires. (Hard rule 11: never
   downgrade a TDD phase just to dodge the gates.)
 
+FLAG BINDING (hard rule 10): bind this phase's effective E2E_KIND — `browser` iff
+FRONTEND_PHASE, else the OVERVIEW `e2e_kind` baseline. If IS_FINAL_PHASE, restate
+`deploy_kind` and confirm the final phase's deploy task realizes it. STATE both
+bindings. Divergence from OVERVIEW is mine to resolve — never silently re-derived.
+
 =====================================================================
 ## TDD PATH  (TDD_PHASE=true)
 =====================================================================
@@ -160,11 +171,16 @@ fixtures + research + the generated test file paths (it MAY read the tests — f
 before logic, no overfit — but must NOT edit tests, spec, or fixtures). Fill to
 green against the spec. Budget 3, WARN@2, STUCK@3.
 
-Run the BOUNDARY suite (real HTTP/CLI/message; `TEST_MODE=real`). If FRONTEND_PHASE,
-`e2e-runner` runs its emitted `ui` specs — MANDATORY (hard rule 13) — reads INFRA.md
-target, runs `scripts/e2e-stack.sh up` / Playwright / `down`, and captures a
-screenshot at EACH UI-existence assertion regardless of pass/fail to
-docs/evidence/e2e-phase-<n>/, with a summary in docs/research/e2e-<slug>.md.
+Run the BOUNDARY suite (real HTTP/CLI/message; `TEST_MODE=real`) — the outer surface
+per this phase's bound E2E_KIND. Capture evidence (hard rule 13):
+- `browser` (FRONTEND_PHASE): dispatch `e2e-runner` to run its emitted `ui` specs —
+  MANDATORY — reads INFRA.md target, runs the stack ritual per `knowledge/webapp.md`
+  (`scripts/e2e-stack.sh up` / Playwright / `down`), captures a screenshot at EACH
+  UI-existence assertion regardless of pass/fail to docs/evidence/e2e-phase-<n>/,
+  with a summary in docs/research/e2e-<slug>.md.
+- `cli` / `http` / `library-api`: the real-mode boundary suite IS the outer run;
+  capture its transcript (invocation + result) to docs/evidence/e2e-phase-<n>/.
+  No separate emitter is dispatched.
 
 PHASE GATE (rule 5) -> go to §8/§9/§10 (see GATE below).
 
@@ -177,7 +193,8 @@ PHASE GATE (rule 5) -> go to §8/§9/§10 (see GATE below).
 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.
+realizes `deploy_kind` (deployed URL / published version / verified install-run)
+before proceeding.
 
 ## 3N. TEST (blind)
 
@@ -237,8 +254,11 @@ REGRESSION + COVERAGE GATES (before closing — all FAIL HARD, do not close):
   IS_FINAL_PHASE: any transition still PENDING -> FAIL HARD. (The case→test half is
   already enforced by `spec-conformance.sh` at §6 — every case-id is cited by a
   boundary test, which by placement lands in tests/regression/.)
-- EVIDENCE (FRONTEND_PHASE only, hard rule 13): docs/evidence/e2e-phase-<n>/ must
-  contain at least the per-UI-existence-assertion screenshots. Empty -> FAIL HARD.
+- EVIDENCE (hard rule 13): docs/evidence/e2e-phase-<n>/ must contain the boundary
+  run's evidence — per-UI-existence-assertion screenshots for `browser`, or the
+  captured boundary-run transcript for `cli`/`http`/`library-api`. Required whenever
+  this phase closes an E2E_KIND boundary (browser: FRONTEND_PHASE; others: the phase
+  ships/changes the outer surface). Empty when required -> FAIL HARD.
 - IF IS_FINAL_PHASE: additionally run `bash scripts/regression.sh --real` (full real
   corpus). A failure blocks close.
 
@@ -256,24 +276,28 @@ 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:
+  b. Surface a "READY TO USE" summary to me, shaped by `deploy_kind`:
      ```
      ✅ PROJECT COMPLETE
 
-     Deployed at: <base URL from docs/INFRA.md "Deployed base URL">
+     <deploy_kind line:
+       cloud-deploy         -> Deployed at: <base URL from docs/INFRA.md "Deployed base URL">
+       package-publish       -> Published: <package name> @ <version> to <registry>
+       install-run-verified  -> Verified install/run: <the exact commands, confirmed working>
+       none(<reason>)        -> Not shipped: <reason>>
 
-     ## Endpoints
-     <paste the full docs/ENDPOINTS.md table>
+     ## Interface
+     <web/http: paste the full docs/ENDPOINTS.md table; cli: the command surface;
+      library: the public API surface>
 
      ## Quick start
-     - Base URL: <URL>
-     - Auth: <Bearer token / API key / none — from ENDPOINTS.md>
-     - Health check: GET <base URL>/health
+     <how to use it, per deploy_kind — base URL + auth + health check for a service;
+      install + invoke for a CLI; import + call for a library>
 
      ## Docs
-     - Full endpoint catalogue: docs/ENDPOINTS.md
+     - Full interface catalogue: docs/ENDPOINTS.md
      - Object/state flow: docs/DATAFLOW.md
-     - Infrastructure: docs/INFRA.md
+     - Infrastructure: docs/INFRA.md (if infra_needed)
      - Project history: docs/HISTORY.md
      ```
   Tell me the project is complete and ready to use.
@@ -293,6 +317,7 @@ After each step, update docs/STATE.md:
 phase: <n> (in progress)
 tdd: <true|false>
 frontend_phase: <true|false>
+e2e_kind: <browser|cli|http|library-api — the bound value>
 completed: <steps done so far>
 next: <exact next step>
 blocker: <none or open issue>

package/template/commands.src/quick.md

@@ -3,7 +3,7 @@ description: Make a small, obvious change directly — no agent chain, no phase
 argument-hint: [what to change]
 ---
 
-Caveman ULTRA mode. Apply `karpathy-guidelines` skill.
+compression: user (.claude/ref/compression.md). Apply `karpathy-guidelines` skill.
 
 Purpose: skip the orchestration tax for a 5-line fix.
 

package/template/commands.src/replan.md

@@ -3,7 +3,7 @@ description: Revise docs/PLAN.md when it no longer matches reality — add, cut,
 argument-hint: [what changed about the plan]
 ---
 
-Caveman ULTRA mode.
+compression: user (.claude/ref/compression.md).
 
 Recommended: run from plan mode (Shift+Tab). Optional; the command stops for
 your approval regardless.

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

@@ -2,7 +2,7 @@
 description: Promote resolved issues and research findings from this project to the shared anpunkit-kb repo. Analyzes, proposes candidates for your review, then pushes approved entries.
 ---
 
-Caveman ULTRA mode. You are the ORCHESTRATOR.
+compression: user (.claude/ref/compression.md). 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.