claude-code-superkit 0.0.0-stage → 1.5.3

package/packages/core/commands/benchmark.md

@@ -0,0 +1,130 @@
+---
+description: Run Go benchmarks with statistical analysis and optional comparison
+argument-hint: "[package] [--compare branch/commit]"
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# Go Benchmark Runner
+
+## Role
+
+Run Go benchmarks with memory stats and 6 repetitions; in `--compare` mode, benchmark two git refs and diff them with benchstat. Go-only command: on non-Go projects it exits at Step 1 with zero side effects.
+
+## Hard Rules
+
+1. No `go.mod` found → report "No Go project detected" and STOP.
+2. No `func Benchmark` functions found → report "No benchmark functions found" and STOP.
+3. Compare mode: record `ORIGINAL_REF` and `STASHED` (Step 4) BEFORE any `git checkout` or `git stash`. Never switch first.
+4. Once Step 4 switched refs, the Restore epilogue (Step 6) ALWAYS runs — after success, after a failed benchmark run, after a missing tool, after any error. Never finish with the repo on another ref or with changes still stashed.
+5. Never run destructive git commands (`reset --hard`, `clean -f`, checkout that overwrites uncommitted changes). Uncommitted changes are preserved only via `git stash push`.
+6. Use the exact `go test` command from Step 3; do not lower `-count` below 6 (statistical significance needs repetitions).
+
+## Step 1 — Detect Project
+
+1. Find `go.mod` (repo root, else `Glob **/go.mod`). Missing → Hard Rule 1.
+2. Find benchmarks: `grep -rn "func Benchmark" --include="*.go" .` Zero hits → Hard Rule 2.
+
+Done when: `go.mod` confirmed AND ≥1 benchmark function found (or the command stopped with the exact message).
+
+## Step 2 — Parse Arguments
+
+Arguments: $ARGUMENTS
+
+| Input | Result |
+|-------|--------|
+| (empty) | `PKG=./...` (all packages), MODE=single |
+| `<package>` | `PKG=<package>` (e.g. `./pkg/cache/...`), MODE=single |
+| `--compare <ref>` | MODE=compare against `<ref>`; PKG from remaining arg or `./...` |
+
+Done when: PKG and MODE are fixed.
+
+## Step 3 — Run Current Benchmarks
+
+```bash
+go test -bench=. -benchmem -count=6 -timeout=10m <PKG>
+```
+
+- MODE=single: parse output into the results table → go to Step 7.
+- MODE=compare: save raw output to `/tmp/bench-new.txt`. If this run FAILS, report the error and STOP here (nothing was switched yet, no restore needed).
+
+Done when: run finished; compare mode additionally has `/tmp/bench-new.txt` on disk.
+
+## Step 4 — Compare Setup (compare mode only; single mode skips Steps 4–6)
+
+1. Check benchstat: `command -v benchstat`. Missing → `go install golang.org/x/perf/cmd/benchstat@latest`, re-check. Still missing → set `FALLBACK=raw` and continue (Step 7 has a no-benchstat format).
+2. Record the return point: `ORIGINAL_REF=$(git rev-parse --abbrev-ref HEAD)`; if that prints `HEAD` (detached), use `ORIGINAL_REF=$(git rev-parse HEAD)`.
+3. `git status --porcelain` non-empty → `git stash push -u -m "benchmark-compare"`, set `STASHED=yes`; else `STASHED=no`.
+4. `git checkout <ref>`. If checkout fails → go straight to Step 6.
+
+Done when: benchstat status known, ORIGINAL_REF + STASHED recorded, repo on `<ref>`.
+
+## Step 5 — Benchmark the Old Ref (compare mode only)
+
+Run the exact Step 3 command again; save output to `/tmp/bench-old.txt`. If it fails, note the failure for the report and proceed to Step 6 anyway (Hard Rule 4).
+
+Done when: `/tmp/bench-old.txt` written, or the failure recorded.
+
+## Step 6 — Restore Epilogue (ALWAYS runs after Step 4 item 4, regardless of outcome)
+
+1. `git checkout <ORIGINAL_REF>`
+2. If `STASHED=yes`: `git stash pop`. On pop conflict: report the conflict, do NOT drop the stash — tell the user their changes remain in `git stash list`.
+3. Verify with `git status`: original ref active, working tree state back.
+
+Done when: repo is on ORIGINAL_REF and the stash is popped (or a pop conflict is explicitly reported).
+
+## Step 7 — Report
+
+Use exactly one of these templates.
+
+### Single Run
+
+```
+## Benchmark Results — <PKG>
+
+| Benchmark | ns/op | B/op | allocs/op |
+|-----------|-------|------|-----------|
+| BenchmarkGet-8 | 234 | 48 | 1 |
+| BenchmarkSet-8 | 567 | 128 | 3 |
+
+Ran 6 iterations per benchmark for statistical significance.
+```
+
+### Comparison (benchstat available)
+
+Run `benchstat /tmp/bench-old.txt /tmp/bench-new.txt`, then:
+
+```
+## Benchmark Comparison — current vs <ref>
+
+[benchstat output with p-values]
+
+Summary:
+- X benchmarks faster, Y slower, Z unchanged (at p < 0.05)
+```
+
+### Comparison (FALLBACK=raw, benchstat unavailable)
+
+Build the delta table yourself from the two `/tmp/bench-*.txt` files (per benchmark, average the 6 runs):
+
+```
+## Benchmark Comparison — current vs <ref> (raw; benchstat unavailable)
+
+| Benchmark | old ns/op | new ns/op | Δ% | old B/op | new B/op | old allocs/op | new allocs/op |
+|-----------|-----------|-----------|----|----------|----------|---------------|---------------|
+
+No statistical significance test applied — install benchstat for p-values:
+go install golang.org/x/perf/cmd/benchstat@latest
+```
+
+## Done ONLY when
+
+- [ ] Report emitted using one of the exact templates above.
+- [ ] Compare mode: `git status` confirms the repo is back on ORIGINAL_REF with the stash popped (or a pop conflict explicitly reported).
+- [ ] Every benchmark/checkout/tool failure that occurred is stated in the report, not silently swallowed.
+
+## Recap
+
+- No `go.mod` / no benchmarks → stop early with the exact message; zero side effects on non-Go projects.
+- Record ORIGINAL_REF + STASHED before any git switch; the Step 6 Restore epilogue always runs after a switch.
+- benchstat is checked (and installed) BEFORE use; raw delta table is the fallback.
+- Exact `go test -bench=. -benchmem -count=6 -timeout=10m` invocation; report only via the fenced templates.

package/packages/core/commands/commit.md

@@ -0,0 +1,148 @@
+---
+description: Conventional commit helper — analyze changes, detect secrets, create well-formatted commit
+argument-hint: "[optional commit message override]"
+allowed-tools: Bash, Read, Grep, Glob
+---
+
+# Conventional Commit Helper
+
+## Role
+
+Stage changes safely, draft a conventional-commit message (with optional trailers), scan the staged diff for secrets, then create one verified commit. This command commits only — it never pushes.
+
+## Hard Rules
+
+- Stage files explicitly by path. Never run `git add -A`, `git add .`, or `git add -u`.
+- Never stage anything on the never-stage denylist (Step 2).
+- Create the commit (Step 6) ONLY when the Step 5 secret scan found nothing, OR the user has explicitly confirmed every flagged pattern. An unconfirmed secret finding blocks the commit.
+- This command creates exactly one commit. Never `git push`.
+- Message format is `type(scope): description` — imperative mood, lowercase, describing the "why".
+- Always end the commit body with the `Co-Authored-By: Claude <noreply@anthropic.com>` trailer.
+
+## Steps
+
+### 1. Analyze Changes
+
+```bash
+git status
+git diff --stat
+git diff --cached --stat
+git log --oneline -5
+```
+
+Done when: you know which files changed, which are already staged, and the repo's recent commit-message style.
+
+### 2. Stage Files
+
+Stage only the files that belong to this change, one path at a time: `git add <path> <path> ...`. When the working tree mixes task files with unrelated edits, stage only the task files by explicit path and leave the rest unstaged.
+
+**Never** stage:
+- `.env` files (secrets)
+- `credentials.json`, `*.key`, `*.pem`, `*.p12`
+- `*.sqlite`, `*.db` (database files)
+- Large binary files (images, videos, archives)
+- `node_modules/`, `vendor/`, `__pycache__/`, `target/`
+
+Done when: every file intended for this commit is staged by explicit path, and re-checking `git diff --cached --stat` shows no denylist path staged.
+
+### 3. Draft Commit Message
+
+Analyze the diff to determine:
+- **Type**: `feat`, `fix`, `docs`, `refactor`, `chore`, `test`, `perf`, `style`, `build`, `ci`
+- **Scope**: component or directory name (e.g., `backend`, `frontend`, `auth`, `api`)
+- **Description**: concise "why" (not "what"), imperative mood, lowercase
+
+Format: `type(scope): description`
+
+Examples:
+- `feat(auth): add JWT refresh token rotation`
+- `fix(cache): prevent stale reads after invalidation`
+- `refactor(api): extract validation into middleware`
+- `docs(readme): update setup instructions for Docker`
+- `test(users): add edge cases for concurrent access`
+
+If `$ARGUMENTS` is provided and non-empty, use it as the commit message instead of auto-generating.
+
+Done when: you have a single subject line in `type(scope): description` form.
+
+### 4. Add Git Trailers (for non-trivial changes)
+
+For changes touching 3+ files or core logic, append structured trailers to the commit body. These provide traceability metadata.
+
+| Trailer | Values | When to use |
+|---------|--------|-------------|
+| `Confidence` | `HIGH` / `MEDIUM` / `LOW` | Always. How confident are you this change is correct? |
+| `Scope-risk` | `LOW` / `MEDIUM` / `HIGH` | When touching shared code. How likely to affect other components? |
+| `Not-tested` | free text | When something is NOT covered by tests. List what's untested. |
+
+Example commit with trailers:
+```
+feat(auth): add JWT refresh token rotation
+
+Implement automatic token refresh when access token expires.
+Refresh tokens are single-use with 7-day TTL.
+
+Confidence: HIGH
+Scope-risk: MEDIUM — touches auth middleware used by all endpoints
+Not-tested: concurrent refresh requests from multiple devices
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+**Skip trailers for:** typo fixes, docs-only changes, config changes, single-file edits < 20 lines.
+
+Done when: trailers are added, or the change matches a skip condition.
+
+### 5. Check for Secrets
+
+Scan the staged diff (`git diff --cached`) for potential secrets:
+- API keys: long alphanumeric strings (32+ chars) in string literals
+- Passwords: `password`, `secret`, `token`, `api_key` assignments with literal values
+- Private keys: `-----BEGIN` patterns
+- Connection strings with embedded credentials
+- Bot tokens: `[0-9]+:[A-Za-z0-9_-]{35}` (Telegram format)
+- AWS keys: `AKIA[A-Z0-9]{16}`
+
+If any pattern matches, **WARN**, list every suspicious file and match, and ask for confirmation. Do not advance to Step 6 until the user has explicitly confirmed each flagged pattern is safe.
+
+Done when: the scan found nothing, or the user has explicitly confirmed every flagged pattern.
+
+### 6. Create Commit
+
+Precondition: Step 5 found no secrets, or the user confirmed each flagged pattern. Do not run this step otherwise.
+
+```bash
+git commit -m "$(cat <<'EOF'
+type(scope): description
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+EOF
+)"
+```
+
+Done when: `git commit` exits 0 and prints a commit hash.
+
+### 7. Verify
+
+```bash
+git log --oneline -1
+git status
+```
+
+Done when: the new commit appears at the top of the log and you have counted any remaining unstaged files.
+
+## Output
+
+Report exactly:
+
+```
+Committed: <hash> <subject>
+Unstaged after commit: <count> file(s) — [list paths, or "none"]
+```
+
+## Recap — non-negotiables
+
+- Stage by explicit path only; never `git add -A` / `.` / `-u`, and never stage a denylist path.
+- No commit while an unconfirmed secret finding stands — Step 5 gates Step 6.
+- Message is `type(scope): description`, imperative and lowercase, ending with the `Co-Authored-By` trailer.
+- Commit only — never `git push`.

package/packages/core/commands/dev.md

@@ -0,0 +1,302 @@
+---
+description: Full-stack development orchestrator — always-on, 16 phases (0–15): read-docs → understand → architect → pseudocode → plan → contract → validate → implement → evaluate → verify → test → goals → review → critic → document → report
+argument-hint: <task-description>
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent
+---
+
+# Development Orchestrator
+
+Run the full development cycle for the task below as 16 numbered phases. You are the orchestrator: you execute phases yourself and dispatch specialist agents at the gates.
+
+## Task
+
+$ARGUMENTS
+
+## Hard Rules
+
+1. Execute phases in order 0 → 15. Skip a phase ONLY when the Skip Matrix says so for the task's complexity class.
+2. A phase is complete only when its **Done when** condition holds. If a phase produces errors, fix them before advancing.
+3. Consume gate verdicts exactly as produced: plan-checker → PASS/REVISE/BLOCK · evaluator → PROCEED/ITERATE/ESCALATE · goal-verifier → PASS/NEEDS-ATTENTION/NEEDS-REMEDIATION · critic → APPROVE/CONCERN/BLOCK.
+4. On any failed gate or retry, escalate effort to `max` for the next attempt and say you are doing so — never silently re-run at the same effort.
+5. Never claim completion while compilation or tests fail. The Phase 15 report is emitted only after every non-skipped phase has run.
+6. If the task is ambiguous, ask the user before Phase 7 (Implement) — not after.
+7. Always read existing patterns before writing new code — search first, reuse the closest implementation as reference.
+
+## Phase Overview & Skip Matrix
+
+Complexity (Simple / Standard / Complex) is decided in Phase 1 and never changes mid-run.
+
+| # | Phase | Simple | Standard | Complex | Gate agent |
+|---|-------|:------:|:--------:|:-------:|-----------|
+| 0 | Read Docs | ✓ | ✓ | ✓ | — |
+| 1 | Understand | ✓ | ✓ | ✓ | — |
+| 2 | Architect | — | — | ✓ | architect |
+| 3 | Pseudocode | — | — | ✓ | — |
+| 4 | Plan | ✓ | ✓ | ✓ | — |
+| 5 | Contract | — | ✓ | ✓ | — |
+| 6 | Validate Plan | — | ✓ | ✓ | plan-checker |
+| 7 | Implement | ✓ | ✓ | ✓ | — |
+| 8 | Evaluate | — | ✓ (max 2 passes) | ✓ (max 3 passes) | evaluator |
+| 9 | Verify | ✓ | ✓ | ✓ | health-checker |
+| 10 | Test | ✓ | ✓ | ✓ | test-generator |
+| 11 | Verify Goals | — | ✓ | ✓ | goal-verifier |
+| 12 | Review | ✓ | ✓ | ✓ | reviewers (parallel) |
+| 13 | Critic | — | — | ✓ | critic |
+| 14 | Document | ✓ | ✓ | ✓ | docs-reviewer |
+| 15 | Report | ✓ | ✓ | ✓ | — |
+
+## Phase 0 — Read Docs
+
+Read `docs/architecture/` files relevant to the task scope:
+- Backend task → `backend-layers.md`, `api-reference.md`, `database-schema.md`
+- Frontend task → `frontend-state.md`
+- Auth task → `auth-and-sessions.md`
+- Full-stack → all available docs
+
+Missing docs are not an error — note what was absent and continue.
+**Done when:** relevant existing docs are read (or confirmed absent).
+
+## Phase 1 — Understand
+
+1. **Detect the stack** by scanning the repository root and subdirectories:
+
+   | Marker file | Stack |
+   |---|---|
+   | `go.mod` | Go backend |
+   | `package.json` + `tsconfig.json` | TypeScript (check for React, Vue, Svelte, etc.) |
+   | `pyproject.toml` / `setup.py` / `requirements.txt` | Python |
+   | `Cargo.toml` | Rust |
+   | `pom.xml` / `build.gradle` | Java/Kotlin |
+   | `docker-compose.yml` | Docker infrastructure |
+   | `migrations/` or `db/migrate/` | Database migrations |
+
+2. **Parse the task**: affected components (backend, frontend, infra, bots, docs); feature / enhancement / bug fix / refactor; inputs and expected outputs.
+
+3. **Assess complexity** — score each of 5 factors, majority column wins (ties → Standard):
+
+   | Factor | Simple | Standard | Complex |
+   |--------|--------|----------|---------|
+   | File count | 1 | 2–5 | 6+ |
+   | Line changes | < 100 | 100–500 | 500+ |
+   | Novelty | Existing pattern | New pattern in existing area | New subsystem |
+   | Risk | Internal, no data changes | API change, DB migration | Auth, payments, security |
+   | Ambiguity | Clear spec | Some unknowns | Exploratory/open-ended |
+
+4. **Search the codebase** for existing related patterns: grep domain terms, endpoint paths, function names; read files that will be modified; check routing files and API specs.
+
+5. **Identify the closest existing implementation** and read it — it is the reference pattern for Phase 7.
+
+**Done when:** stack detected, complexity class declared, reference pattern read.
+
+## Phase 2 — Architect (Complex only)
+
+Dispatch **architect**:
+```
+Design the architecture for this task:
+Task: [description]
+Current architecture: [from Phase 0 docs]
+Affected components: [from Phase 1]
+Propose 2-3 approaches with trade-offs.
+```
+Use the recommendation to shape Phase 4. If the chosen approach had real alternatives and lasting consequences (framework/data-model/protocol/security choice), append an ADR to `docs/adr/` from `docs-templates/adr-template.md` recording the rejected alternatives and why — skip for trivial or easily-reversible choices, and if `docs-templates/adr-template.md` is absent, skip silently rather than blocking on a missing template.
+**Done when:** one approach chosen, with a stated reason.
+
+## Phase 3 — Pseudocode (Complex only)
+
+Draft language-agnostic pseudocode for the core logic (algorithm, state machine, data pipeline): input/output contract, main control flow, error paths, data transformations. 30–50 lines maximum — longer means the task needs decomposition. No file paths, no framework syntax.
+
+Present to the user: "Here's the pseudocode for [core logic]. Does this match your expectations?"
+**Done when:** user approves (or explicitly waives) the pseudocode; it becomes the Phase 4 skeleton.
+
+## Phase 4 — Plan
+
+Produce a checklist plan organized by component — include only relevant sections:
+
+```
+## Implementation Plan
+### Database
+- [ ] Migration: NNNN_description
+### Backend
+- [ ] Repository/data layer: path
+- [ ] Service/business logic: path
+- [ ] DTOs/schemas: path
+- [ ] Handler/controller: path
+- [ ] Routes: path
+- [ ] Tests: path
+### Frontend
+- [ ] Types / API client / state / component: paths
+### Infrastructure
+- [ ] Docker/config changes
+### Documentation
+- [ ] API spec, architecture docs, README
+```
+
+**Done when:** every planned item names a concrete file path.
+
+## Phase 5 — Contract (Standard: 5–10 criteria · Complex: 10–20)
+
+Write testable acceptance criteria — the evaluator checks exactly these in Phase 8:
+
+```
+## Sprint Contract
+| # | Criterion | Test Method | Threshold | Priority |
+|---|-----------|-------------|-----------|----------|
+| 1 | [specific, testable outcome] | [grep / curl / test / read] | Score ≥ 7 | MUST |
+| 2 | ... | ... | ... | MUST/SHOULD |
+```
+
+Threshold uses the evaluator's 0–10 scale — default 7 unless a criterion warrants stricter. Good criteria are testable, specific ("returns 200 with user.id in JSON", not "endpoint works"), independent, and measurable. Never include subjective items ("code is clean") or unmeasurable ones ("performance is good").
+**Done when:** every criterion has a concrete test method.
+
+## Phase 6 — Validate Plan
+
+Dispatch **plan-checker** with the Phase 4 plan and Phase 5 contract.
+- **PASS** → Phase 7.
+- **REVISE** → fix the blocking issues, re-dispatch (max 2 iterations, then treat as BLOCK).
+- **BLOCK** → stop; present the issues to the user.
+**Done when:** verdict is PASS.
+
+## Phase 7 — Implement
+
+Execute the plan in dependency order; for each step, read the reference pattern first, then implement. Before writing any NEW code, walk the Solution Ladder (coding-style rule) and stop at the first rung that holds: not needed → reuse in codebase → stdlib → native platform feature → installed dependency; a new dependency is the last resort.
+
+1. **Migration** — next number in the project's migration directory; up + down files; parameterized DDL, `IF NOT EXISTS`, appropriate types.
+2. **Data layer** — follow the project's existing data-access patterns (Go: pgx/sqlx/gorm, nil-safe repos, `fmt.Errorf("Context.Method: %w", err)`; Python: SQLAlchemy/Django ORM; TypeScript: Prisma/TypeORM/Drizzle).
+3. **Business logic** — constructor DI via interfaces; Go: `context.Context` first param, domain errors; Python: type hints, async where applicable; TypeScript: strict types.
+4. **Transport** — follow existing handler patterns (chi, gin, echo, express, FastAPI, …); input validation at the boundary; errors mapped to proper status codes.
+5. **Routes** — register endpoints, apply auth/middleware.
+6. **Frontend** — read existing components first (animation library, styling, state); API client and types matching the backend contract.
+
+**Done when:** every Phase 4 checklist item is implemented (no placeholders/TODOs left).
+
+## Phase 8 — Evaluate
+
+Dispatch **evaluator** with the Sprint Contract, changed-file list, pass number, and — on pass 2+ — the previous evaluation report.
+- **PROCEED** → Phase 9.
+- **ITERATE** → escalate effort to `max` (Hard Rule 4), fix the critique, re-dispatch as pass N+1. If passes exceed the matrix budget (Standard 2 / Complex 3) → proceed with the warning "Evaluation budget exhausted after N passes. Remaining issues: [list]". If the score did not improve vs the previous pass → proceed with an escalation note.
+- **ESCALATE** → dispatch **architect** for design review, apply its recommendation, restart from Phase 7.
+**Done when:** verdict is PROCEED, or budget exhausted with an explicit warning.
+
+## Phase 9 — Verify
+
+Dispatch **health-checker** if available; otherwise run compilation checks directly:
+Go `go vet ./...` · TypeScript `npx tsc --noEmit` · Python `mypy`/`pyright`/`python -m py_compile` · Rust `cargo check`.
+**Done when:** compilation/static checks pass with zero errors.
+
+## Phase 10 — Test
+
+Dispatch **test-generator** if available — otherwise write the tests yourself — for new/changed backend code: happy path, validation errors, not-found/conflict, boundary values, edge cases — following project test patterns. Then run the project's test command yourself and fix failures.
+**Done when:** the test suite runs green (paste the actual final summary line).
+
+## Phase 11 — Verify Goals
+
+Dispatch **goal-verifier** with the Phase 4 goals and changed files. It checks 4 levels: EXISTS → SUBSTANTIVE → WIRED → DATA-FLOW.
+- **PASS** → Phase 12.
+- **NEEDS-ATTENTION** → fix the listed gaps in place, re-verify.
+- **NEEDS-REMEDIATION** → critical artifacts missing; return to Phase 7 (or Phase 4 if the plan itself was wrong).
+**Done when:** verdict is PASS.
+
+## Phase 12 — Review
+
+First, a 30-second inline self-pass on the diff: (a) no placeholders/TODOs/`unimplemented`, (b) types/signatures consistent with callers, (c) every acceptance criterion has a corresponding change. Fix the obvious now.
+
+Then dispatch reviewer agents **in parallel** — every row whose pattern matches changed files AND whose agent exists in `.claude/agents/`:
+
+| Changed files | Agent |
+|---|---|
+| `*.go` (not migrations, not tests) | **go-reviewer**, **security-scanner** |
+| `*.sql` migrations | **migration-reviewer**, **database-reviewer** |
+| Data-access files (`*_repo.go`, repositories) | **database-reviewer** |
+| `*.ts`, `*.tsx` | **ts-reviewer** |
+| `*.py` | **py-reviewer**, **security-scanner** |
+| `*.rs` | **rs-reviewer** |
+| Bot code | **bot-reviewer** |
+| UI components | **design-system-reviewer**, **ui-reviewer** |
+| OpenAPI/GraphQL spec changed | **api-contract-sync** |
+| Any changed code | **silent-failure-hunter**, **comment-rot-analyzer** |
+
+Pass each agent the changed-file list and task description. Each runs its own two-stage discipline (discover, then triage by Severity + Confidence).
+
+Go path, opt-in: if a gopls MCP server is registered, Go edits use `go_symbol_references` (blast radius) before touching a definition and `go_diagnostics` after — never assume the server is wired.
+
+Triage findings — route, don't drop:
+- CRITICAL or WARNING at HIGH/MEDIUM confidence → fix before proceeding.
+- LOW confidence / ambiguous → carry into the **Open Questions** section of the Phase 15 report.
+- A clean review (0 findings) is a valid result — do not pad it.
+
+**Done when:** all CRITICAL/WARNING findings fixed or explicitly deferred with reason.
+
+## Phase 13 — Critic (Complex only)
+
+Dispatch **critic** with all changed files, the original task, and the Phase 12 findings summary. It reviews from security, new-hire, and ops perspectives.
+- **APPROVE** → Phase 14.
+- **CONCERN** → address; proceed if explicitly non-blocking.
+- **BLOCK** → fix blocking issues, re-dispatch.
+**Done when:** verdict is APPROVE, or CONCERN with all concerns addressed/answered.
+
+## Phase 14 — Document
+
+Dispatch **docs-reviewer** to verify documentation completeness for the changed files. Also update directly:
+1. **API spec** (OpenAPI/GraphQL) if endpoints changed.
+2. **Architecture docs** if system behavior changed.
+3. **README** if setup, commands, or structure changed.
+**Done when:** docs-reviewer reports no MISSING items for this change.
+
+## Phase 15 — Report
+
+Emit only after all non-skipped phases completed:
+
+```
+## Development Report
+
+### Task
+[Original task description]
+
+### Phases Executed
+| # | Phase | Status | Notes |
+|---|-------|--------|-------|
+| 0 | Read Docs | ✅ | N docs read |
+| 1 | Understand | ✅ | [components], [complexity] |
+| 2 | Architect | ⏭/✅ | [skipped: not Complex / approach chosen] |
+| 3 | Pseudocode | ⏭/✅ | |
+| 4 | Plan | ✅ | N items |
+| 5 | Contract | ⏭/✅ | N criteria |
+| 6 | Validate Plan | ⏭/✅ | PASS after N iterations |
+| 7 | Implement | ✅ | N created, M modified |
+| 8 | Evaluate | ⏭/✅ | PROCEED at pass N |
+| 9 | Verify | ✅ | compilation clean |
+| 10 | Test | ✅ | X tests green |
+| 11 | Verify Goals | ⏭/✅ | PASS (4/4 levels) |
+| 12 | Review | ✅ | [agents]: N findings fixed |
+| 13 | Critic | ⏭/✅ | APPROVE |
+| 14 | Document | ✅ | [docs updated] |
+| 15 | Report | ✅ | this report |
+
+### Changes Made
+| File | Action | Description |
+|------|--------|-------------|
+
+### Open Questions (LOW-confidence review items — surfaced, not dropped)
+- file:line — suspicion + what would confirm it (omit section if none)
+
+### Metrics
+| Metric | Value |
+|--------|-------|
+| Complexity | Simple / Standard / Complex |
+| Agent dispatches | N (list) |
+| Evaluator passes | N (ITERATE → … → PROCEED) |
+| Sprint contract | X/Y criteria met |
+
+### Suggested Commit Message
+type(scope): description
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+## Recap — non-negotiables
+
+- Phases run in order; Skip Matrix is the only source of skips.
+- Gate verdicts consumed verbatim; failed gate → retry at `max` effort, say so.
+- No completion claims over failing builds/tests; report only after all non-skipped phases.
+- LOW-confidence findings go to Open Questions, never silently dropped.
+- Conventional commits: `feat|fix|docs|refactor|chore|test|perf(scope): description`.

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

@@ -0,0 +1,75 @@
+---
+description: "Initialize project documentation — redirects to /superkit-init for intelligent setup"
+argument-hint: "[--non-interactive]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent
+---
+
+# Initialize Project Documentation
+
+## Role
+Set up project documentation. Prefer `/superkit-init` (intelligent scan + auto-populated docs). Run the manual fallback ONLY when that command is not installed.
+
+## Hard Rules
+- If `/superkit-init` exists, redirect to it and stop — never also run the fallback.
+- Never overwrite an existing root `CLAUDE.md`; create it only when absent.
+- Never reference kit-source paths (`packages/...`); they do not exist in installed projects. Use the inline skeleton below.
+- Fallback touches only: `docs/architecture/`, `docs/trees/`, and `CLAUDE.md` (when absent).
+- Forward the caller's arguments to `/superkit-init` unchanged.
+
+## Steps
+
+1. **Detect the preferred command.** Glob `.claude/commands/superkit-init.md`.
+   - Found → do Step 2 (redirect).
+   - Not found → do Step 3 (fallback).
+   - Done-when: you have chosen redirect or fallback.
+
+2. **Redirect (preferred).** Invoke `/superkit-init`, forwarding the caller's arguments verbatim: $ARGUMENTS
+   Then stop — do NOT run Step 3.
+   - Done-when: `/superkit-init` finished and its report is shown.
+
+3. **Fallback scaffold** (only when Step 1 found no `superkit-init.md`):
+   1. `mkdir -p docs/architecture docs/trees`
+   2. Dispatch the `tree-generator` agent to populate `docs/trees/`. If the agent is unavailable, note it and skip.
+   3. Read the project root: if `CLAUDE.md` already exists, leave it unchanged. If absent, Write it from the skeleton below, keeping the `TODO:` markers for the user to fill in.
+   - Done-when: both dirs exist, trees generated (or skipped with a note), and a root `CLAUDE.md` exists.
+
+### Inline CLAUDE.md skeleton (used by fallback Step 3, only when no root CLAUDE.md exists)
+```markdown
+# YOUR_PROJECT_NAME
+> TODO: one-line project description.
+
+## Tech Stack
+TODO: backend / frontend / infra.
+
+## Structure
+TODO: top-level directory layout.
+
+## Key Commands
+TODO: build / test / lint / migrate / dev-server commands.
+
+## Conventions
+TODO: formatting, error handling, commit format, API style, env vars.
+
+## Architecture Reference
+| Doc | Description |
+|-----|-------------|
+| docs/architecture/*.md | TODO: fill in per generated template |
+| docs/trees/tree-monorepo.md | Project directory structure |
+```
+
+## Output
+```
+## Docs Init — <redirect | fallback>
+[redirect]  Forwarded to /superkit-init — see its report above.
+[fallback]
+  docs/architecture/       created
+  docs/trees/              <generated | skipped: tree-generator unavailable>
+  CLAUDE.md                <created from skeleton | unchanged (already existed)>
+Next: fill the TODO sections in CLAUDE.md and docs/architecture/*.
+```
+
+## Recap
+- `/superkit-init` present → redirect and stop; absent → fallback. Never both.
+- Fallback never overwrites an existing root `CLAUDE.md`.
+- No `packages/...` kit paths — use the inline skeleton.
+- Emit the report only after the chosen branch's Done-when holds.