claude-code-superkit 0.0.0-stage → 1.5.3

package/packages/core/skills/writing-agents/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: writing-agents
+description: How to write Claude Code agents — playbook skeleton, canonical severity/confidence enums, Evidence Gate, Output Contract, dispatch patterns
+tokens: 2453
+user-invocable: false
+---
+
+# Writing Claude Code Agents
+
+Meta-skill: the standard every kit agent follows. Agents are `.md` files in `.claude/agents/` — YAML frontmatter + markdown body. Reference implementations of this standard: `critic.md` and `code-reviewer.md` in the same directory.
+
+## Use when / Do not use
+
+- **Use when:** authoring a new agent, rewriting an existing one, or checking an agent file for kit compliance.
+- **Do not use for:** commands, hooks, rules, or skills — those have different formats.
+
+## Hard Rules
+
+1. `model: opus` — the kit is opus-only. NEVER emit sonnet or haiku.
+2. Canonical enums, exact spelling — Severity: CRITICAL / WARNING / SUGGESTION. Confidence: HIGH (≥80) / MEDIUM (60–79) / LOW (<60). LOW items route to Open Questions, never silently dropped.
+3. Every reviewer agent carries the Evidence Gate; every generator agent carries a "Done ONLY when" gate.
+4. Every agent ends with an exact fenced Output Contract plus one filled mini example — never "[standard format]", "[standard questions]", or "report in your usual format".
+5. Reference /dev phases by NAME ("the /dev Review phase", "the /dev Critic phase"), never by bare number.
+6. Grep patterns must be ripgrep-safe: literal text, alternation `a|b`, character classes — no lookaheads or lookbehinds.
+
+## Frontmatter
+
+```yaml
+---
+name: agent-name
+description: One line — what it reviews/creates AND when to dispatch it
+model: opus
+allowed-tools: Read, Grep, Glob, Bash
+---
+```
+
+- `description` — single line; dispatch matches on it, so include the trigger condition (e.g., "Review Dockerfiles for security — dispatch when Dockerfile or docker-compose files change").
+- `allowed-tools` — minimal set. Reviewers: `Read, Grep, Glob, Bash`. Generators add `Edit, Write`.
+- `tokens: N` — transparency signal, not a budget. Do not hand-count; regenerate with `node bin/inject-tokens.js` after editing.
+
+## Body Skeleton (every agent, this order)
+
+1. **Role** — 1–2 sentences.
+2. **Hard Rules** — ≤7 MUST/NEVER bullets at the TOP (weaker models lose constraints buried mid-file).
+3. **Phase 0 — Load Project Context** — kit convention, template below.
+4. **Process** — numbered phases, linear integers only (no 1.5/2.1); each phase: goal → tool-level actions → done-when.
+5. **Domain checklists / decision tables** — the expertise; keep depth, cut prose.
+6. **Output Contract** — exact fenced template + one filled mini example.
+7. **Recap** — 3–5 bullets restating the hard rules, as the last section.
+
+Precision rules: a list labeled "N-point" contains exactly N items; every decision fork lists all branches plus an explicit default — no "use judgment" or "as appropriate".
+
+### Phase 0 template
+
+```markdown
+## Phase 0 — Load Project Context
+Read if present, skip silently if absent: `CLAUDE.md` or `AGENTS.md`; relevant `docs/architecture/*.md`.
+Use it to: [one line — what this agent extracts]. Violations of DOCUMENTED conventions → report with HIGH confidence instead of MEDIUM.
+```
+
+## Authoring Workflow
+
+1. Define the role in one sentence and the dispatch condition — both go into `description`.
+2. Write frontmatter: `model: opus`, minimal `allowed-tools`.
+3. Write the body top-down in skeleton order: Hard Rules → Phase 0 → Process → checklists.
+4. Write the Output Contract and fill the mini example with realistic content — zero bracketed placeholders.
+5. Add the Evidence Gate (reviewer) or Done-gate (generator), then the Recap.
+6. Run `node bin/inject-tokens.js` to refresh `tokens:`.
+
+Done when: sections appear in skeleton order and `rg -n "standard format|usual format|standard questions"` on the file returns nothing.
+
+## Severity / Confidence (canonical)
+
+**Severity**
+- **CRITICAL** — data loss, security vulnerability, crash. Example: SQL injection, auth bypass.
+- **WARNING** — incorrect behavior under specific conditions. Example: missing error wrap, N+1 query.
+- **SUGGESTION** — style, readability. Safe to ignore.
+
+**Confidence**
+- **HIGH (≥80)** — bug visible in the code.
+- **MEDIUM (60–79)** — pattern-based; mark "needs verification".
+- **LOW (<60)** — route to Open Questions, never silently drop.
+
+Finding format:
+
+```
+[SEVERITY/CONFIDENCE] file:line — one-line description
+  Evidence: <what the code shows>
+  Fix: <concrete change>
+```
+
+**Do NOT inflate severity to seem thorough.** A review with 0 CRITICAL and 2 SUGGESTIONS is valid. If the code is clean, say so.
+
+## Evidence Gate (copy into every reviewer)
+
+```markdown
+## Evidence Gate
+Report a finding ONLY if all four hold:
+1. **Citation** — exact `file:line` you Read in this session, never from memory.
+2. **Failure mode** — a concrete input/path that triggers the problem (no "could be problematic").
+3. **Context** — you read the surrounding function/callers, not just the flagged line.
+4. **Severity** you can defend to a skeptic.
+If a referenced file/symbol cannot be found: output `NOT FOUND: <path>` — never invent its contents.
+A clean review (0 findings) is a valid result — do not manufacture findings.
+```
+
+## Done-gate (copy into every generator)
+
+```markdown
+## Done ONLY when
+- [ ] Every promised artifact exists on disk — verified with Read/ls, not from memory.
+- [ ] [compile/test command] ran; paste its real output in the report.
+- [ ] Report separates VERIFIED (tool output seen) from ASSUMED (not checked) — list both.
+Not all boxes checked → say what is missing; do not claim completion.
+```
+
+Multi-phase reviewers may also end with a "Done ONLY when" checklist of per-phase completion criteria — the pattern `critic.md` and `code-reviewer.md` use.
+
+## Dispatch Priority
+
+If a **stack-specific reviewer** exists (e.g., `go-reviewer` for `*.go`), it is dispatched **instead of** `code-reviewer` for matching files. `code-reviewer` covers files no specialist claims.
+
+## Checklist Design Tips
+
+- Each item names a concrete probe: a ripgrep-safe grep pattern or a file path to check.
+- Order by severity — critical checks first.
+- Include both positive checks (X must be present) and negative checks (Y must NOT be present).
+- 8–15 items is the sweet spot. More than 20 → split into two agents.
+
+## Example: Complete Minimal Agent
+
+Every section filled — this is the template to copy, not a sketch:
+
+````markdown
+---
+name: dockerfile-reviewer
+description: Review Dockerfiles for security and image hygiene — dispatch when Dockerfile or docker-compose files change
+model: opus
+allowed-tools: Read, Grep, Glob
+---
+
+# Dockerfile Reviewer
+
+Reviews Dockerfiles for security and build hygiene, producing evidence-gated findings.
+
+## Hard Rules
+1. Every finding passes the Evidence Gate: cite only `file:line` you Read this session; missing files → `NOT FOUND: <path>`.
+2. Severity CRITICAL/WARNING/SUGGESTION; Confidence HIGH (≥80) / MEDIUM (60–79) / LOW (<60); LOW → Open Questions.
+3. 0 findings is a valid result — never manufacture findings.
+
+## Phase 0 — Load Project Context
+Read if present, skip silently if absent: `CLAUDE.md` or `AGENTS.md`; `docs/architecture/deployment.md`.
+Use it to: learn base-image, registry, and deploy conventions. Violations of DOCUMENTED conventions → HIGH confidence instead of MEDIUM.
+
+## Evidence Gate
+Report a finding ONLY if all four hold:
+1. **Citation** — exact `file:line` you Read in this session, never from memory.
+2. **Failure mode** — a concrete input/path that triggers the problem (no "could be problematic").
+3. **Context** — you read the surrounding function/callers, not just the flagged line.
+4. **Severity** you can defend to a skeptic.
+If a referenced file/symbol cannot be found: output `NOT FOUND: <path>` — never invent its contents.
+A clean review (0 findings) is a valid result — do not manufacture findings.
+
+## Process
+1. **Locate** — Glob `**/Dockerfile*`, Read each hit. Done when: every file Read or reported `NOT FOUND`.
+2. **Checklist** — evaluate all 5 items below against every file. Done when: 5 items × files evaluated.
+3. **Report** — emit the Output Contract.
+
+## Checklist (5 items)
+1. **Root user** — grep `USER`; missing, or `USER root` as the last USER directive → CRITICAL.
+2. **Floating tag** — grep `:latest`; pin a specific version → WARNING.
+3. **Multi-stage** — count `FROM` lines; single-stage build shipping compilers in the final image → WARNING.
+4. **COPY vs ADD** — grep `ADD`; prefer COPY unless extracting an archive → SUGGESTION.
+5. **Health check** — grep `HEALTHCHECK`; absent for a long-running service → SUGGESTION.
+
+## Output Contract
+
+```
+## Dockerfile Review
+
+### Findings
+[SEVERITY/CONFIDENCE] file:line — one-line description
+  Evidence: <what the file shows>
+  Fix: <concrete change>
+
+### Open Questions
+- file:line — suspicion + what would confirm it (or "none")
+
+### Summary
+<N> CRITICAL, <N> WARNING, <N> SUGGESTION — <one-line verdict>
+```
+
+Mini example:
+
+```
+### Findings
+[CRITICAL/HIGH] deploy/Dockerfile:14 — container runs as root
+  Evidence: no USER directive after the final FROM stage
+  Fix: create a non-root user and add `USER app` before ENTRYPOINT
+
+### Open Questions
+- deploy/Dockerfile:3 — pinned digest may be stale; confirm the base-image update policy
+
+### Summary
+1 CRITICAL, 0 WARNING, 0 SUGGESTION — fix root user before merge.
+```
+
+## Recap — non-negotiables
+- Evidence Gate: cite only lines Read this session; `NOT FOUND: <path>` for missing files.
+- Canonical enums, exact spelling; LOW → Open Questions.
+- 0 findings is valid — never inflate.
+````
+
+## Recap — non-negotiables
+
+- `model: opus` only — never sonnet or haiku.
+- Severity CRITICAL/WARNING/SUGGESTION; Confidence HIGH ≥80 / MEDIUM 60–79 / LOW <60; LOW → Open Questions.
+- Reviewers carry the Evidence Gate; generators carry the Done-gate.
+- Output Contract is a fenced template with a filled mini example — placeholders like "[standard format]" are banned.
+- /dev phases by NAME; greps ripgrep-safe; `tokens:` via `node bin/inject-tokens.js`.

package/packages/core/skills/writing-commands/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: writing-commands
+description: How to write Claude Code slash commands — canonical skeleton, orchestrator pattern, agent dispatch, auto-detection
+tokens: 1771
+user-invocable: false
+---
+
+# Writing Claude Code Commands
+
+## Purpose
+
+Author `.claude/commands/*.md` files that a model executes reliably: fixed skeleton, per-step done-when conditions, every fork enumerated, and a final report gated on completion.
+
+## Use when / Do not use
+
+- **Use when**: creating a new slash command or restructuring an existing one.
+- **Do not use for**: agents (see `writing-agents`) or hooks (see `writing-hooks`) — commands are user-triggered workflows; agents are dispatched workers.
+
+## Hard Rules — for every command you write
+
+1. `$ARGUMENTS` appears EXACTLY once — at the step that parses it. Zero occurrences loses user input; two makes consumption ambiguous.
+2. Linear integer numbering for steps/phases (1, 2, 3…). Never insert fractional numbers (2.5) — renumber instead.
+3. Every step ends with a `Done when:` line stating a verifiable exit condition (file exists, command output seen, agent report received).
+4. The final report is emitted ONLY after every non-skipped step's done-when holds; anything missing is listed as "Not done" — never claimed complete.
+5. Every fork enumerates ALL branches plus an explicit else/default — no "as appropriate" or "use judgment".
+6. Destructive actions (git checkout/stash, file deletion, migrations) get a gate: record restore state BEFORE the action; a restore step ALWAYS runs after it, on success and on failure.
+7. `allowed-tools` lists only what the command needs (least privilege).
+
+## Command Skeleton (canonical)
+
+Frontmatter:
+
+```yaml
+---
+description: One-line description (shown in /help)
+argument-hint: <what-user-types>
+allowed-tools: Bash, Read, Edit, Write, Glob, Grep, Agent  # only what this command needs
+---
+```
+
+Body, in this order:
+
+1. **Title + Role** — 1–2 sentences: one primary purpose per command — what it does, when it stops early.
+2. **Hard Rules** — ≤7 MUST/NEVER bullets; include destructive-action gates where relevant.
+3. **Numbered Steps** — Step 1, Step 2, … each with concrete actions and `Done when:`. `$ARGUMENTS` sits in the parse step (`Arguments: $ARGUMENTS`).
+4. **Output template** — exact fenced template the report must follow, plus a "Done ONLY when" checklist for longer commands.
+5. **Recap** — 3–5 bullets restating the hard rules.
+
+Living references — read before writing a command: `test.md` (linear detect → scope → run → report shape) and `benchmark.md` (destructive-gate shape: record ref/stash BEFORE git switch, always-run restore epilogue) in the same commands directory. If absent, follow the skeleton above.
+
+Tiny commands (≤3 steps, no destructive actions) may omit Hard Rules and Recap; anything with destructive actions or 4+ steps includes both.
+
+## The Orchestrator Pattern
+
+Most powerful commands are **orchestrators** — they coordinate multiple agents through phases:
+
+```
+Phase 1: Understand  → read codebase, find patterns
+Phase 2: Plan        → output structured checklist
+Phase 3: Execute     → create/modify files
+Phase 4: Verify      → dispatch health-checker agent
+Phase 5: Test        → dispatch test-generator agent
+Phase 6: Review      → dispatch reviewer agents (parallel)
+Phase 7: Document    → dispatch docs-reviewer agent
+Phase 8: Report      → summary table
+```
+
+Not every command needs many phases — the full `/dev` runs 16, but simple commands (lint, test) may have 2-3 phases.
+
+### Phase discipline
+
+- Each phase declares a `Done when:` condition an executor can verify.
+- Conditional phases keep linear integer numbering; ALL skip conditions live in one skip table ("Phase 5 — skip when no test framework detected"). Never renumber fractionally.
+- The Report phase runs LAST and is gated: emit it only after every non-skipped phase's done-when holds. A failed or unran phase appears in the report under "Not done" — the command never claims completion it did not verify.
+
+## Dispatching Agents from Commands
+
+Use the `Agent` tool. Reference agents by their EXACT name — the `.claude/agents/` filename without `.md`.
+
+**Parallel dispatch** (independent agents — all Agent calls in one message):
+```
+Dispatch ALL triggered agents simultaneously:
+- go-reviewer (if .go files changed)
+- ts-reviewer (if .ts/.tsx files changed)
+- security-scanner (always)
+```
+
+**Sequential dispatch** (later steps depend on earlier results — every branch spelled out):
+```
+1. Dispatch health-checker.
+   - Passes → step 2.
+   - Fails → report the failing checks and STOP (default for any unclear result: STOP).
+2. Dispatch test-generator; run the generated tests.
+   - Pass → step 3.
+   - Fail → report the failures and STOP.
+3. Dispatch reviewer agents (parallel).
+```
+
+## Auto-Detection Pattern
+
+For multi-stack projects, detect the stack from project files:
+
+```
+Auto-detection:
+  go.mod exists?          → Go project
+  package.json + tsconfig → TypeScript project
+  pyproject.toml          → Python project
+  Cargo.toml              → Rust project
+```
+
+This lets commands work in any project without hardcoded paths. Multiple markers → treat as multi-stack: handle each detected stack, report each separately.
+
+## Input Parsing
+
+Parse `$ARGUMENTS` at its consumption step. List patterns in PRECEDENCE order — first match wins — and always end with an explicit else:
+
+```markdown
+## Step N — Parse Arguments
+
+Arguments: $ARGUMENTS
+
+Match in this order (first match wins):
+1. Empty → default behavior.
+2. Known keyword/flag (--fix, all, e2e, …) → that mode.
+3. PR#NNN → fetch the PR diff.
+4. Existing branch name (verify: `git rev-parse --verify <name>`) → use as base.
+5. Else → state how the input was interpreted in the report; never silently ignore it.
+```
+
+Keyword-before-branch ordering resolves inputs that match both.
+
+## Example: Minimal Command
+
+```markdown
+---
+description: Run project linters
+argument-hint: "[--fix]"
+allowed-tools: Bash, Glob
+---
+
+# Lint
+
+Auto-detect the project's linters and run them.
+
+## Step 1 — Parse Arguments
+
+Arguments: $ARGUMENTS
+
+- Empty → report-only mode.
+- Contains `--fix` → add auto-fix flags.
+- Else → run report-only mode; note the ignored tokens in the report.
+
+Done when: mode fixed.
+
+## Step 2 — Detect and Run
+
+1. `go.mod` exists → run `gofmt -l . && go vet ./...`
+2. `tsconfig.json` exists → run `npx tsc --noEmit && npx eslint .`
+3. Neither exists → report "No supported linter detected." and stop.
+
+Done when: every detected stack's linter ran and its real output was seen (or the no-linter case was reported).
+
+## Step 3 — Report
+
+List files with issues. If clean: "All files pass linting." — a clean result is valid.
+
+Done when: the report reflects the actual Step 2 output.
+```
+
+## Recap — non-negotiables
+
+- `$ARGUMENTS` exactly once, at the parse step; every step ends with `Done when:`.
+- Linear integer numbering; conditional phases in one skip table; final report only after every non-skipped step's done-when holds.
+- Every fork lists all branches plus an explicit else; unclear result defaults to STOP-and-report.
+- Destructive actions: record restore state before, always-run restore step after (see `benchmark.md`).
+- Least-privilege `allowed-tools`; agents referenced by exact filename-derived name.