claude-code-superkit 0.0.0-stage → 1.5.3

package/packages/core/commands/superkit-init.md

@@ -0,0 +1,274 @@
+---
+description: Intelligent project setup — scan codebase, generate filled documentation, configure rules with real paths
+argument-hint: "[--non-interactive]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent
+---
+
+# Superkit Init — Intelligent Project Setup
+
+## Role
+
+Scan the codebase, generate **filled** documentation (not empty templates), and configure superkit rules/hooks with real project paths. Replaces manual CLAUDE.md filling, architecture doc writing, and rule configuration.
+
+Parse $ARGUMENTS:
+- Empty (default) → **interactive**: pause at every checkpoint.
+- `--non-interactive` → skip all checkpoints and questions, generate everything automatically.
+
+## Hard Rules
+
+1. Detect by reading code. Do NOT ask the user what their stack is — the only permitted question is the Scaffold stack question (interactive mode, empty project).
+2. Generated docs describe what EXISTS in the code, not what should exist.
+3. ALL generated text is English, including TODO placeholders.
+4. Architecture doc filenames come ONLY from the canonical table in Step 2 — never invent name variants.
+5. When something cannot be determined from code, write `TODO: [specific question]` — never guess.
+6. Every generated file starts with the generation stamp (Step 2).
+7. Emit the final report ONLY after the Done-when gate in Step 5 passes.
+
+## Scaffold path (empty project)
+
+Step 1 declares Scaffold when NO language marker exists (no `go.mod`, `package.json`, `Cargo.toml`, `pyproject.toml`, `requirements.txt`). All steps still run in order; this matrix defines each step's behavior:
+
+| Step | Full project | Empty project (Scaffold) |
+|------|-------------|--------------------------|
+| 1 Scan | Full detection | Record "empty project". Interactive: ask "What stack will you use? [Go / TypeScript / Python / Rust / Other]". Non-interactive: stack = `TODO: define the stack` |
+| 2 Generate | Arch docs + trees + CLAUDE.md | Minimal CLAUDE.md only (project name, stack answer or the TODO above, empty structure). No arch docs, no trees |
+| 3 Configure rules | Real-path mapping | SKIP — no real paths exist yet; record "rules not configured (empty project)" for the report |
+| 4 Validate | All 3 checks | Single check: CLAUDE.md exists and starts with the generation stamp |
+| 5 Commit & report | Full report | `git add CLAUDE.md` only; use the Scaffold report variant |
+
+## Step 1 — Scan (project introspection)
+
+### Languages & frameworks
+
+| Marker | Detected As |
+|--------|-------------|
+| `go.mod` | Go. Read `go.mod` for framework: `chi`, `gin`, `echo`, `fiber` |
+| `package.json` + `tsconfig.json` | TypeScript. Read `package.json` for: react/vue/svelte/angular, vite/webpack/next |
+| `pyproject.toml` / `requirements.txt` | Python. Read for: fastapi/django/flask |
+| `Cargo.toml` | Rust. Read for: actix/axum/rocket |
+
+### Infrastructure
+
+| Check | How |
+|-------|-----|
+| Database | `docker-compose*.yml` → postgres/mysql/mongo. `.env` → `DB_*`, `DATABASE_URL` |
+| Cache | `docker-compose*.yml` → redis. Imports: `go-redis`, `ioredis`, `redis-py` |
+| Storage | `docker-compose*.yml` → minio/s3. Imports: `minio-go`, `@aws-sdk/client-s3` |
+| Auth | Grep for: `jwt`, `session`, `oauth`, `passport`, `auth middleware` |
+| CI/CD | `.github/workflows/`, `Dockerfile`, `docker-compose*.yml`, `.gitlab-ci.yml` |
+
+### Structure
+
+```bash
+# Detect monorepo vs single
+find . -maxdepth 3 -name "go.mod" -o -name "package.json" | grep -v node_modules | wc -l
+# If > 1 → monorepo
+
+# Detect components
+ls -d */ | head -20
+# Look for: backend/, frontend/, adminpanel/, bots/, workers/, services/, apps/
+
+# Scale
+find . -name "*.go" -o -name "*.ts" -o -name "*.py" -o -name "*.rs" | grep -v node_modules | grep -v vendor | wc -l
+```
+
+### Existing docs
+
+```bash
+test -f CLAUDE.md && echo "HAS_CLAUDE_MD"
+test -f AGENTS.md && echo "HAS_AGENTS_MD"
+test -d docs/architecture && echo "HAS_ARCH_DOCS" && ls docs/architecture/
+test -f backend/docs/openapi.yaml && echo "HAS_OPENAPI"
+```
+
+### Scan summary
+
+Summarize findings internally (do NOT save to file):
+```
+Stack: Go 1.23 (chi, pgx), TypeScript (React 19, Vite), PostgreSQL 16, Redis 7
+Structure: monorepo (backend/, frontend/, adminpanel/)
+Components: 3 (backend, frontend, adminpanel)
+Scale: ~450 files, 50 migrations, 67 endpoints
+Auth: JWT + Redis sessions
+Infra: Docker Compose, GitHub Actions
+Existing docs: CLAUDE.md (TODO-heavy), no architecture docs
+```
+
+**Done when:** internal summary produced, OR Scaffold declared per the matrix.
+
+## Step 2 — Generate documentation
+
+For EACH detected component, read actual code and generate **filled** docs. Minimize TODOs.
+
+Every generated file starts with:
+```markdown
+> Generated by `/superkit-init` on YYYY-MM-DD. Review and customize for your project.
+```
+
+### Architecture docs — canonical names
+
+Generate only docs matching detected components. These six filenames are canonical — each matches a shipped template in `docs-templates/architecture/` and is exactly what `/superkit-evolve` checks. Use them exactly (e.g. `api-reference.md`, not `backend-api-reference.md`; `frontend-state.md`, not `frontend-state-contracts.md`):
+
+| Condition | Generate | How |
+|-----------|----------|-----|
+| Backend detected | `docs/architecture/backend-layers.md` | Read cmd/, internal/, routes → describe layers, DI, error handling |
+| API routes found | `docs/architecture/api-reference.md` | Grep route registrations → list endpoints with method, path, auth |
+| Migrations dir exists | `docs/architecture/database-schema.md` | Read last 10 migrations → list tables, columns, constraints |
+| Auth code detected | `docs/architecture/auth-and-sessions.md` | Read auth service → describe token/session lifecycle |
+| Frontend detected | `docs/architecture/frontend-state.md` | Read src/ → routing, state, data fetching |
+| Docker/CI detected | `docs/architecture/deployment.md` | Read docker-compose, Dockerfile → describe how to run |
+
+For each doc:
+1. Read 3-5 key source files in the component.
+2. Write a structured doc describing what EXISTS (not what should exist).
+3. Unknown detail → `TODO: [specific question]`.
+
+### Decision records (optional — offer, never force)
+
+Ask the user whether to seed a `docs/adr/` namespace for architecture decision records (separate from the current-state architecture docs above; no filename collision). If they accept, create `docs/adr/` with a short `README.md` index — a one-line purpose plus a note to copy `docs-templates/adr-template.md` to `docs/adr/NNNN-<slug>.md` for any significant choice with real alternatives. If they decline, skip it silently.
+
+### Project trees
+
+```bash
+mkdir -p docs/trees
+```
+
+Generate with the `tree` command; if `tree` is unavailable, fall back to `find . -maxdepth 2 -type d -not -path '*/node_modules/*' -not -path '*/.git/*'`:
+- If monorepo: `tree-monorepo.md` (depth 2)
+- Per-component: `tree-{component}.md` (depth 3)
+
+### CLAUDE.md
+
+If CLAUDE.md doesn't exist or is the superkit TODO template, generate a filled version reading from:
+- README.md → project description
+- package.json / go.mod → tech stack with versions
+- Makefile / package.json scripts → key commands
+- Existing migrations → migration format and count
+- Generated arch docs → architecture reference table
+- .editorconfig / linter configs → conventions
+
+### Checkpoint (interactive mode only)
+
+```
+✅ Generated documentation:
+  docs/architecture/backend-layers.md (142 lines)
+  docs/architecture/database-schema.md (89 lines)
+  docs/architecture/frontend-state.md (67 lines)
+  docs/trees/tree-monorepo.md
+  docs/trees/tree-backend.md
+  docs/trees/tree-frontend.md
+  CLAUDE.md (95 lines, 2 TODOs remaining)
+
+Review before configuring rules? [continue / show <file> / edit <file>]
+```
+
+In `--non-interactive` mode: no checkpoint, proceed to Step 3.
+
+**Done when:** every doc from the condition table (or the Scaffold CLAUDE.md) is written to disk with the generation stamp.
+
+## Step 3 — Configure rules
+
+Adapt superkit rules to use **real project paths** (not generic patterns). Scaffold: skip per the matrix.
+
+### documentation.md rule
+
+Read `.claude/rules/documentation.md`. Update the trigger-to-doc mapping table with real paths detected in Step 1:
+
+```
+| # | Trigger (from Step 1 scan) | Required Doc | File Path |
+|---|----------------------------|-------------|-----------|
+| 1 | {actual migrations path}/*.sql | Database schema | docs/architecture/database-schema.md |
+| 2 | {actual handlers path}/*.go | API reference | docs/architecture/api-reference.md |
+...
+```
+
+### doc-check-on-commit.sh hook
+
+Update `.claude/scripts/hooks/doc-check-on-commit.sh` with project-specific path mappings for the smart blocker.
+
+### Checkpoint (interactive mode only)
+
+```
+✅ Configured rules with your project paths:
+  .claude/rules/documentation.md — N-row trigger mapping with real paths
+  .claude/scripts/hooks/doc-check-on-commit.sh — smart mapping for N categories
+
+Review? [continue / show rules]
+```
+
+In `--non-interactive` mode: no checkpoint.
+
+**Done when:** both files updated with detected paths (or Scaffold skip recorded).
+
+## Step 4 — Validate
+
+1. **Path check** — backticked literal paths in rules and CLAUDE.md must exist (portable — no `grep -P`):
+```bash
+grep -hoE '`[^` ]*/[^` ]*\.(go|ts|tsx|sql|py|rs|md)`' .claude/rules/documentation.md CLAUDE.md 2>/dev/null \
+  | tr -d '`' | sort -u | grep -v '\*' | while read -r p; do
+    [ -e "$p" ] || echo "BROKEN: $p"
+  done
+```
+Extracted strings that contain `*` are glob patterns: check each with the Glob tool; a pattern with zero matches → fix it or replace with a real path. Bare filenames without `/` are code spans — ignore them.
+
+2. **Cross-reference** — migration count in CLAUDE.md matches the actual file count in the migrations directory.
+
+3. **Consistency** — the CLAUDE.md architecture reference table lists every doc generated in Step 2.
+
+**Done when:** re-run after fixes prints zero `BROKEN` lines, all globs match, counts agree. Scaffold: CLAUDE.md exists with the generation stamp.
+
+## Step 5 — Commit & report
+
+```bash
+git add docs/ CLAUDE.md .claude/rules/ .claude/scripts/hooks/
+git commit -m "chore: initialize project documentation via superkit-init
+
+Generated:
+- docs/architecture/ (N files, filled from code analysis)
+- docs/trees/ (N files)
+- CLAUDE.md (populated with project details)
+- .claude/rules/ (configured with project-specific paths)
+
+Co-Authored-By: Claude <noreply@anthropic.com>"
+```
+
+Scaffold: `git add CLAUDE.md` and a message noting the minimal scaffold.
+
+### Done ONLY when
+
+- [ ] Every file named in the report exists on disk — verified with `ls`/Read this session, not from memory.
+- [ ] Step 4 passed on its final run (zero `BROKEN`, globs match; Scaffold: stamp check passed).
+- [ ] Commit exists — `git log --oneline -1` shows it.
+- [ ] `TODOs remaining: X` equals the real count: `grep -ro 'TODO:' CLAUDE.md docs/architecture/ 2>/dev/null | wc -l`.
+
+Any box unchecked → state what is missing and fix it; do not emit the report.
+
+## Output — final report
+
+```
+✅ superkit-init complete!
+
+Generated: N architecture docs, M tree files, CLAUDE.md
+Configured: documentation rule, doc-check hook
+TODOs remaining: X (areas that need manual input)
+
+Next: start coding! The /dev pipeline now has full project context.
+Run /superkit-evolve anytime to update docs as your project grows.
+```
+
+Scaffold variant — replace the middle and Next lines with:
+```
+Generated: CLAUDE.md (minimal — empty project)
+Configured: nothing — rules skipped, no real paths yet
+TODOs remaining: X
+
+Next: project is empty. Start with /dev <task>, then run /superkit-evolve once code exists.
+```
+
+## Recap — non-negotiables
+
+- Detect by reading code; the Scaffold stack question is the only question allowed.
+- Canonical doc filenames only (Step 2 table); all generated text in English.
+- Unknowns become `TODO: [specific question]` — never invented content.
+- Empty project → follow the Scaffold column for every step, including the skip of Step 3.
+- Final report only after every Done-ONLY-when box is checked.

package/packages/core/commands/test.md

@@ -0,0 +1,108 @@
+---
+description: Auto-detect and run project tests — supports Go, TypeScript, Python, Rust, and more
+argument-hint: "[backend|frontend|e2e|all] [--coverage]"
+allowed-tools: Bash
+---
+
+# Run Tests
+
+Auto-detect the project's test runner, execute the tests for the requested scope, and report the runner's real results.
+
+## Hard Rules
+
+- Report the runner's REAL output — paste the actual pass/fail/skip lines; never summarize from memory or invent counts.
+- Consume the argument exactly as `scope` + optional `--coverage`; when no scope is given, default to `backend`.
+- If the chosen scope has no matching markers (e.g. `backend` on a frontend-only repo), fall back to running all detected suites — never do nothing.
+- Detect commands only from the Step 1–2 tables; do not invent test commands or flags.
+- When a `Makefile` `test` target exists for the stack, prefer `make test`.
+- For scope `all`, run every detected suite sequentially and report each separately.
+- On failure, show the first 5 failure details for diagnosis — no more.
+
+## Step 1 — Detect Test Runner
+
+Scan the project root and subdirectories for stack markers:
+
+| Marker | Test Command | Stack |
+|--------|-------------|-------|
+| `go.mod` | `go test ./... -count=1` | Go |
+| `package.json` + vitest config | `npx vitest run` | Vitest |
+| `package.json` + jest config | `npx jest` | Jest |
+| `package.json` + playwright config | `npx playwright test` | Playwright (e2e) |
+| `cypress.config.{js,ts}` | `npx cypress run` | Cypress (e2e) |
+| `pyproject.toml` / `pytest.ini` / `conftest.py` | `pytest` | Python (pytest) |
+| `pyproject.toml` with `[tool.unittest]` | `python -m unittest discover` | Python (unittest) |
+| `tests/e2e/` dir + pytest | `pytest tests/e2e/` | Python E2E (selenium) |
+| `Cargo.toml` | `cargo test` | Rust |
+| `pom.xml` | `mvn test` | Java (Maven) |
+| `build.gradle` | `./gradlew test` | Java/Kotlin (Gradle) |
+| `Makefile` with `test` target | `make test` | Makefile |
+
+If a `Makefile` with a `test` target exists and the stack has one, prefer `make test` as it may include additional setup.
+
+**Done when:** every stack present in the repo is mapped to its exact test command (or to `make test`).
+
+## Step 2 — Determine Scope and Coverage
+
+Parse `$ARGUMENTS` into a `scope` token (`backend` | `frontend` | `e2e` | `all`; empty → `backend`) and an optional `--coverage` flag, then select commands:
+
+### backend (default)
+Run backend tests only:
+- **Go**: `go test ./... -count=1 -short` (`-short` skips integration tests that need external services)
+- **Python**: `pytest tests/` or `pytest`
+- **Rust**: `cargo test`
+- **Java**: `mvn test` / `./gradlew test`
+
+If the project is a monorepo, `cd` into the backend directory first (detect by `backend/`, `server/`, `api/`, or `src/` containing the go.mod/pyproject.toml).
+
+**Fallback:** if no backend markers are detected, run all detected suites instead (treat as scope `all`).
+
+### frontend
+Run frontend tests:
+- **Vitest**: `npx vitest run`
+- **Jest**: `npx jest`
+
+If the project is a monorepo, `cd` into the frontend directory first (detect by `frontend/`, `web/`, `client/`, or `app/` containing package.json).
+
+### e2e
+Run end-to-end tests:
+- **Playwright**: `npx playwright test`
+- **Cypress**: `npx cypress run`
+- **pytest + selenium**: `pytest tests/e2e/`
+
+### all
+Run every detected suite (backend + frontend + e2e) sequentially. Report results for each.
+
+### --coverage (append when the flag is present)
+- **Go**: `go test ./... -coverprofile=coverage.out` then `go tool cover -func=coverage.out | tail -1`
+- **Vitest/Jest**: append `--coverage`
+- **pytest**: append `--cov`
+- **Rust**: requires `cargo-tarpaulin` — `cargo tarpaulin`
+
+**Done when:** the exact command(s) to run are assembled, including any coverage flags, monorepo `cd`, and the `all` fallback if the scope had no markers.
+
+## Step 3 — Run and Report
+
+Execute the assembled command(s). Paste the runner's real output, then fill the template below. For scope `all`, repeat the per-stack block once per suite. If tests fail, show the first 5 failure details for diagnosis.
+
+```
+## Test Results
+
+### [Stack Name]
+- Command: `[exact command run]`
+- Result: X passed, Y failed, Z skipped
+- Duration: Ns
+- Coverage: XX% (if --coverage flag used)
+
+### Failures (if any)
+1. TestName — error message (file:line)
+2. ...
+```
+
+**Done when:** every selected command has been executed, its real output pasted, and the Test Results template filled for each suite.
+
+## Recap — non-negotiables
+
+- Paste the runner's REAL output; never fabricate counts or claim a pass you did not see.
+- Default scope is `backend`; if no backend markers exist, run all detected suites.
+- Use only the commands/flags in the Step 1–2 tables; prefer `make test` when a test target exists.
+- On failures, show the first 5 for diagnosis.

package/packages/core/commands/workflow.md

@@ -0,0 +1,150 @@
+---
+description: Run a predefined workflow template — bugfix, hotfix, spike, refactor, dep-upgrade, security-audit
+argument-hint: <template> [task-description]
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent
+---
+
+# Workflow Templates
+
+Run one of six opinionated workflow templates. Each template fixes an ordered list of phases and the agents to dispatch, so common task types follow the same proven path every time.
+
+## Target
+
+$ARGUMENTS
+
+## Hard Rules
+
+1. Run only the template named in Target. If Target names none, or the first word matches no template, do not guess — follow Step 3 or Step 4 and stop until the user answers.
+2. Execute a template's phases in listed order. A phase begins only after the previous phase's done-when condition holds.
+3. Report status after every phase, and emit the Workflow Report only when every executed phase has a status row.
+4. On a failed gate or retry, escalate effort to `max` for the next attempt and state that you are doing so — never silently re-run at the same effort.
+5. spike produces a report only (no code changes); hotfix applies the minimal fix (no refactoring, no improvements).
+6. When consuming security-scanner output, use its exact enums — Severity CRITICAL/WARNING/SUGGESTION, Confidence HIGH/MEDIUM/LOW.
+7. For tasks that fit no template, tell the user to use `/dev` instead of forcing a template.
+
+## Steps
+
+1. Read the template name from the first word of Target. Done when: the name equals one of the six templates below, or you route to Step 3/4.
+2. Read the task description from the rest of Target. Done when: the task text is captured (empty is allowed — spike and security-audit can run without a description).
+3. If Target names no template — list the six templates with their one-line summaries and ask the user to choose. Done when: the user names a template; do not proceed before then.
+4. If the first word matches no template — name the single closest template and ask the user to confirm before running it. Done when: the user confirms or picks another; do not proceed before then.
+5. Run the matched template's phases (see Templates) in order. At each dispatch point, dispatch the named agent; if that agent is absent from `.claude/agents/`, perform the phase inline and write "agent unavailable — ran inline" in that phase's Notes. Done when: every phase's done-when condition is met.
+6. After each phase, record its status row for the Workflow Report (see Output). Done when: Step 5's final phase done-when holds and every executed phase has a row — only then emit the report.
+
+## Templates
+
+### `bugfix` — Triage, fix, verify, test
+
+For bug reports and regressions.
+
+1. **Triage** — reproduce the bug as a failing test, identify root cause (dispatch **debug-observer**). Done when: a failing test that reproduces the bug exists (red) and one root cause is named.
+2. **Fix** — implement the fix following existing patterns. Done when: the fix is applied, the changed files compile, and the previously-failing test now passes (green).
+3. **Verify** — run compilation checks, ensure no regressions. Done when: build/typecheck passes with no new errors.
+4. **Test** — run the full suite and add any additional coverage the fix warrants. Done when: the full suite passes with no regressions.
+
+### `hotfix` — Fix, test, deploy-check
+
+For urgent production issues. Minimal process, maximum speed.
+
+1. **Fix** — implement the minimal fix (no refactoring, no improvements). Done when: the minimal change is applied and compiles.
+2. **Test** — run existing tests, add a regression test if quick. Done when: existing tests pass.
+3. **Deploy-check** — verify build succeeds, no breaking changes to API/DB. Done when: the build succeeds and no API/DB-breaking change is detected.
+
+### `spike` — Scope, research, summarize
+
+For exploration and investigation. No code changes — research only.
+
+1. **Scope** — define what we are investigating and its success criteria. Done when: the question and success criteria are written down.
+2. **Research** — explore the codebase, read docs, search for patterns, check dependencies. Done when: enough evidence is gathered to answer the scoped question.
+3. **Summarize** — structured findings with recommendations and next steps. Done when: the report contains findings, recommendations, and next steps. Spike produces a report, not code — use the findings to plan implementation separately.
+
+### `refactor` — Baseline, inventory, plan, migrate, verify
+
+For restructuring code without changing behavior.
+
+1. **Baseline** — confirm the affected tests exist and pass green before any change; if coverage is thin, write characterization tests first. Done when: the affected suite is green, or characterization tests were added and are green.
+2. **Inventory** — list all files/functions affected, map dependencies. Done when: the affected file/function list and dependency map are written.
+3. **Plan** — define the target structure, migration order, rollback strategy. Done when: target structure, leaf-first migration order, and rollback strategy are all stated.
+4. **Migrate** — execute changes in dependency order (leaf files first). Done when: every planned file is migrated leaf-first and compiles.
+5. **Verify** — compilation clean, all tests pass, no behavior changes (dispatch **health-checker**). Done when: build is clean, the full suite passes, and health-checker reports no behavior change.
+
+### `dep-upgrade` — Assess, upgrade, fix-breaking, verify
+
+For dependency updates and vulnerability fixes.
+
+1. **Assess** — dispatch **dependency-checker** for a full audit. Done when: dependency-checker has returned its audit.
+2. **Upgrade** — apply updates in safe order (patches first, then minors, then majors). Done when: the planned updates are applied in that order.
+3. **Fix-breaking** — resolve any breaking changes from major updates. Done when: no unresolved breaking-change compile or test errors remain.
+4. **Verify** — compilation clean, tests pass, no regressions (dispatch **health-checker**). Done when: build is clean, tests pass, and health-checker reports no regressions.
+
+### `security-audit` — Scan, triage, remediate, re-scan
+
+For security review and hardening.
+
+1. **Scan** — dispatch **security-scanner** for a full OWASP + config audit. Done when: security-scanner has returned its findings.
+2. **Triage** — prioritize findings by Severity and exploitability. Done when: every finding carries a Severity (CRITICAL/WARNING/SUGGESTION) and Confidence (HIGH/MEDIUM/LOW).
+3. **Remediate** — fix CRITICAL and WARNING findings (HIGH/MEDIUM confidence); list LOW-confidence items under Next Steps rather than fixing blind. Done when: no CRITICAL and no HIGH/MEDIUM-confidence WARNING remains unresolved (or each is explicitly recorded as accepted).
+4. **Re-scan** — dispatch **security-scanner** again to verify fixes and check for new issues. Done when: the re-scan confirms the remediated findings are gone and introduces no new CRITICAL or WARNING.
+
+## Output
+
+Emit exactly this structure. Status is one of `done` / `blocked` / `skipped`. The Result cell holds a short observable outcome (a count, a verdict, a named cause) — never a wall-clock estimate.
+
+```
+## Workflow Report: [template]
+
+### Task
+[Original task description]
+
+### Phases
+| Phase | Status | Result | Notes |
+|-------|--------|--------|-------|
+| [phase] | done/blocked/skipped | [observable outcome] | [notes] |
+
+### Changes Made
+| File | Action | Description |
+|------|--------|-------------|
+| path | Created/Modified | description |
+
+### Next Steps
+- [recommendations, LOW-confidence items, or "none"]
+```
+
+Filled example (bugfix):
+
+```
+## Workflow Report: bugfix
+
+### Task
+Nil-pointer panic in checkout when cart is empty
+
+### Phases
+| Phase | Status | Result | Notes |
+|-------|--------|--------|-------|
+| Triage | done | root cause: unchecked cart.Items[0]; failing repro test written (red) | debug-observer reproduced with empty cart |
+| Fix | done | guard added in checkout.go; repro test now passes (green) | followed existing early-return pattern |
+| Verify | done | build clean, 0 new errors | |
+| Test | done | full suite green, 214 pass | no further coverage needed |
+
+### Changes Made
+| File | Action | Description |
+|------|--------|-------------|
+| checkout.go | Modified | early return when cart is empty |
+| checkout_test.go | Modified | regression test for empty cart |
+
+### Next Steps
+- none
+```
+
+## Notes
+
+- Templates auto-detect the project stack (Go, TypeScript, Python, Rust) for their build/test commands.
+- Templates can be chained: e.g. `bugfix` a defect, then `dep-upgrade` the affected dependency.
+
+## Recap — non-negotiables
+
+- Run only the named template; on missing/unrecognized input, list templates or offer the closest match and stop.
+- Phases run in order — each starts only after the prior phase's done-when holds; report a status row per phase.
+- Escalate effort to `max` on a failed gate or retry and say so; never silently re-run at the same effort.
+- security-audit remediation targets CRITICAL and WARNING findings (HIGH/MEDIUM confidence) in security-scanner's exact enums.
+- Emit the Workflow Report only when every executed phase has a row.

package/packages/core/docs/guide/01-getting-started.md

@@ -0,0 +1,41 @@
+
+## Your First Commands
+
+After installation, here's what to try:
+
+### 1. Verify installation
+Open Claude Code in your project and try:
+```
+/review --full
+```
+This dispatches reviewer agents against your entire codebase. You should see a dispatch plan, then findings grouped by severity.
+
+### 2. Run a quick audit
+```
+/audit
+```
+Dispatches up to 4 parallel audit agents (frontend, backend, infra, security). Each produces a findings report.
+
+### 3. Check project health
+```
+/dev <describe your task>
+```
+The dev orchestrator runs 16 phases (understand → plan → implement → verify → test → review → document → report, plus plan-check, sprint-contract, goal-verify, and critic gates).
+
+### If Something Doesn't Work
+
+1. **settings.json invalid?** Run `jq empty .claude/settings.json` — no output means valid
+2. **Hooks not firing?** Run `chmod +x .claude/scripts/hooks/*.sh`
+3. **No agents found?** Check `ls .claude/agents/` — should have .md files
+4. **Need help?** See `TROUBLESHOOTING.md` in the superkit repo
+
+## Prerequisites
+
+| Tool | Required | Install |
+|------|----------|---------|
+| Claude Code CLI | Yes | `npm install -g @anthropic-ai/claude-code` |
+| git | Yes | System package manager |
+| jq | Yes | `brew install jq` (macOS) or `apt install jq` (Linux) |
+| Superpowers plugin | Recommended | Claude Code → `/plugins` → search "superpowers" |
+| GitHub CLI (gh) | Optional | `brew install gh` — needed for `--comment` in /review |
+| tree | Optional | `brew install tree` — nicer project tree generation |

package/packages/core/docs-templates/README.md

@@ -0,0 +1,33 @@
+# Architecture Doc Templates
+
+Copy relevant templates to your project's `docs/architecture/` directory and fill in the TODOs.
+
+## Which templates to use
+
+| Template | Use when your project has... |
+|----------|----------------------------|
+| `backend-layers.md` | Any backend (Go, Node, Python, Rust) |
+| `api-reference.md` | REST/GraphQL API endpoints |
+| `database-schema.md` | SQL database with migrations |
+| `auth-and-sessions.md` | Authentication system |
+| `frontend-state.md` | Frontend app (React, Vue, Svelte) |
+| `deployment.md` | Production deployment process |
+| `api-contracts.md` | External API integrations |
+| `data-flow.md` | Complex multi-step data flows |
+| `../adr-template.md` | A significant choice with real alternatives to record — copies to `docs/adr/NNNN-<slug>.md`, not `architecture/` |
+
+> **ADR template.** `adr-template.md` lives one level up (not in `architecture/`) because ADRs target a separate `docs/adr/` namespace. Use it only for decisions with real alternatives and lasting consequences (framework/library choice, data-model shape, protocol/API style, security model) — never for trivial or reversible choices. It records the WHY and the rejected alternatives, which the current-state architecture docs deliberately do not.
+
+## How to use
+
+1. Run `/docs-init` in Claude Code — auto-detects which templates apply
+2. Or manually: `cp packages/core/docs-templates/architecture/*.md docs/architecture/`
+3. Fill in the TODOs
+4. Delete templates that don't apply
+5. Add custom docs as your project grows
+
+## Tips
+
+- Start minimal — fill only what you know now, expand later
+- These docs are read by AI agents (Phase 0) — accurate docs = better reviews
+- The `docs-reviewer` agent will flag stale docs after code changes

package/packages/core/docs-templates/adr-template.md

@@ -0,0 +1,62 @@
+# ADR-NNNN: <decision title>
+
+> **When to write one.** Copy this file to `docs/adr/NNNN-<slug>.md` (zero-padded
+> sequence, e.g. `0007-postgres-over-mongo.md`) and fill it in. Write an ADR only
+> for decisions with **real alternatives and lasting consequences** — a framework
+> or library choice, a data-model shape, a protocol/API style, a security model.
+> Never write one for trivial or easily-reversible choices (formatting, naming, a
+> local helper's signature): an ADR for everything is ceremony that kills the
+> habit. The point of the record is the WHY and the rejected alternatives — the
+> context that stops a future session from re-litigating or silently violating
+> this decision.
+
+## Status
+
+`proposed` → `accepted` → `deprecated` | `superseded-by-NNNN`
+
+- **Status:** proposed
+- **Date:** YYYY-MM-DD
+
+Start at `proposed`; move to `accepted` once the decision is in effect. When a
+later ADR overrides this one, set the status here to `superseded-by-NNNN` and
+link the replacement so the trail stays intact.
+
+## Context
+
+<!-- The forces at play: the constraints, requirements, and trade-offs that make
+this a real decision. 3-6 lines. State the problem, not the solution. -->
+
+TODO: What situation forces a decision? What technical, product, or team
+constraints bound the choice? What is non-negotiable, and what is flexible?
+
+## Decision
+
+<!-- What was chosen. Active voice: "We use X." One clear statement, then the
+few reasons that made it win over the alternatives below. -->
+
+TODO: We <verb> <choice>, because <the decisive reasons>.
+
+## Alternatives Considered
+
+<!-- The whole point of the record. For each serious alternative, name it and
+say WHY it was rejected — that rejection rationale is what future readers need. -->
+
+### Alternative A — <name>
+- **What it was:** TODO: one line.
+- **Why rejected:** TODO: the specific reason it lost (cost, risk, complexity,
+  missing capability, team unfamiliarity, lock-in).
+
+### Alternative B — <name>
+- **What it was:** TODO: one line.
+- **Why rejected:** TODO: the specific reason it lost.
+
+<!-- Add a third only if a third option was genuinely on the table. -->
+
+## Consequences
+
+<!-- What this decision makes easier AND harder. Include the negative ones
+honestly — a decision with no downsides usually means one wasn't recorded. -->
+
+- **Easier:** TODO: what this unlocks or simplifies.
+- **Harder / accepted cost:** TODO: the downside you are knowingly taking on.
+- **Follow-ups:** TODO: any migration, guardrail, or revisit-trigger this implies.