claude-code-superkit 0.0.0-stage → 1.5.3

package/packages/core/rules/coding-style.md

@@ -0,0 +1,68 @@
+---
+alwaysApply: true
+tokens: 755
+---
+
+# Coding Style
+
+Always-on discipline for every response that touches code: verify before you claim, change only what was asked, follow the style rules below.
+
+## Investigate Before Answering
+- Never speculate about code you have not opened
+- If a user references a file — READ it before answering
+- Do NOT invent API endpoints, package names, or function signatures
+- Do NOT assume a package exists — verify in package registry or node_modules/go.mod
+- If unsure whether something exists — grep for it first
+
+## Surgical Changes
+- Change ONLY what was requested — nothing more
+- A bug fix does NOT need surrounding code cleaned up
+- A new feature does NOT need existing code refactored
+- Do NOT "improve" code you're passing through
+- Do NOT add docstrings, comments, or type annotations to code you didn't change
+- If you see a real problem in unrelated code — mention it, don't fix it
+- Three similar lines of code is better than a premature abstraction
+
+## Search First
+- Check codebase for existing patterns before writing new code
+- Check packages before reimplementing
+- Name the precedent you follow (file:line) — or state explicitly that no precedent was found after searching
+
+## Solution Ladder (before writing new code)
+
+Stop at the first rung that holds:
+1. Doesn't need to exist (YAGNI)? — don't write it (anti-patterns below).
+2. Already in this codebase? — reuse it (Search First above).
+3. Stdlib covers it? — use stdlib; don't reimplement, don't add a dependency.
+4. Native platform feature covers it? — use it: `<input type="date">` over a picker lib, CSS over JS, a DB constraint over app-level checks.
+5. An installed dependency covers it? — use it. Never add a NEW dependency for what stdlib, the platform, or a few lines can do.
+
+Mark a deliberate simplification with a comment naming its ceiling and the upgrade trigger: `// simplified: global lock; per-account locks if throughput matters`.
+
+Minimal never means fragile: input validation at trust boundaries, error handling, security, and accessibility are never simplified away — and anything explicitly requested is never dropped.
+
+## YAGNI Anti-Patterns (canonical)
+- Abstraction with one implementation
+- Config option nobody sets
+- Scaffolding "for later"
+- Wrapper that adds nothing over what it wraps
+- Dead flag/parameter kept "just in case"
+
+## General
+- Use language-standard formatter
+- No magic numbers — named constants
+- No commented-out code
+- Early returns over nesting
+- Max ~50 lines per function
+- No global state — DI via constructors
+
+## Testing
+- Tests required for: new endpoints, bug fixes (regression test), business logic
+- Tests optional for: pure UI, config, docs
+- "should [behavior] when [condition]" naming
+
+## Parallel Execution
+- When reading multiple files — read them all in parallel (multiple Read calls in one message)
+- When searching for patterns — run multiple Grep calls in parallel
+- When dispatching independent agents — dispatch ALL simultaneously
+- Only sequence calls that depend on previous results

package/packages/core/rules/dev-workflow.md

@@ -0,0 +1,77 @@
+---
+alwaysApply: true
+tokens: 1145
+---
+
+# Auto Dev Workflow
+
+## Hard Rules
+
+1. Every task that creates or modifies code files MUST follow the /dev orchestration (`packages/core/commands/dev.md`, installed as the `/dev` command) — even when the user never typed `/dev`. This covers features, bug fixes of any size, refactors, migrations, bot changes, and integration work.
+2. Do NOT announce "I'm using the /dev workflow" — just follow the phases.
+3. NEVER commit with `[wip]` on `main` / `master` / `prod*` branches.
+4. `[quick:]` / `[no-dev:]` / `[trivial:]` require a reason of ≥ 15 characters; `[hotfix:]` requires a ticket ID or an explicit `no-ticket: <reason ≥15 chars>`.
+5. Override budget: at most 2 override tags per 30 minutes across the whole project. The third is blocked — run /dev instead or wait for the oldest override to age out.
+6. The commit gate hard-blocks `git commit` after 3 or more code-file edits in a session unless /dev ran or a valid override tag is present.
+
+## When NOT to use /dev
+
+| Task Type | Action |
+|-----------|--------|
+| Docs-only update | Direct edit |
+| Config / env change | Direct edit |
+| Question / explanation | Just answer |
+| Typo fix in non-code file | Direct edit |
+
+## Complexity → phases
+
+The /dev Skip Matrix in `packages/core/commands/dev.md` is the single source of truth. Complexity is decided in the /dev Understand phase and never changes mid-run:
+
+| Complexity | Signals | Skipped phases |
+|------------|---------|----------------|
+| **Simple** | 1 file, < 100 lines, existing pattern | Architect (2), Pseudocode (3), Contract (5), Validate Plan (6), Evaluate (8), Verify Goals (11), Critic (13) |
+| **Standard** | 2–5 files | Architect (2), Pseudocode (3), Critic (13) |
+| **Complex** | 6+ files, new subsystem, auth/payments/security | none — all 16 phases |
+
+The Review and Document phases run for every complexity class — never skip them; Document is where logic/API/architecture changes get their doc updates.
+
+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.
+
+## Enforcement (hard-block at commit)
+
+Three hooks enforce this rule technically:
+
+| Hook | Event | Behavior |
+|------|-------|----------|
+| `dev-edit-counter.sh` | `PostToolUse(Edit\|Write)` | Counts code-file edits per session. Tests, docs, memory, `.claude/`, and config files are ignored. |
+| `dev-marker-set.sh` | `UserPromptSubmit` + `PreToolUse(Skill)` | Records that /dev was invoked this session (word-boundary match — `/develop`, `/device`, `/devops` do NOT trigger). |
+| `dev-required-on-commit.sh` | `PreToolUse(Bash)` | Blocks `git commit` (incl. `git -C <path> commit`) when the edit count is ≥ 3 AND no /dev marker is set AND no override tag is present. |
+
+**Threshold:** 3 code-file edits — below that, committing without /dev is allowed. Counter and marker reset on every successful code commit (exempt commits leave the counter untouched), so each work-cycle starts fresh.
+
+**Exempt commits** (no /dev required even at counter ≥ 3):
+
+- Docs-only commits (no `.go` / `.ts` / `.tsx` / etc. files staged)
+- Test-only commits (`*_test.go`, `*.test.ts`, `*.spec.*`)
+- `presentation/` changes (see the frontend-3d package documentation)
+- `.claude/` and `memory/` changes
+
+**Override tags** — the tag must **open a line** of the commit message: either the very start of the subject line or on its own trailer line (`^\s*[tag…]`). A tag merely mentioned mid-sentence — or anywhere in the command outside the `-m` / `--message` payload — is **not** an override and does not bypass the gate. (This keeps the escape hatch intentional: a memory note that simply *describes* `[no-dev: …]` never triggers a bypass or a block.)
+
+| Tag | When to use | Rationale requirements |
+|-----|-------------|------------------------|
+| `[quick: <reason ≥15 chars>]` | Small fix, intentional skip | Reason required |
+| `[no-dev: <reason ≥15 chars>]` | /dev not applicable (pure infra / docs) | Reason required |
+| `[trivial: <reason ≥15 chars>]` | Cosmetic change (naming, formatting) | Reason required |
+| `[hotfix: #123 …]` or `[hotfix: ABC-123 …]` | Emergency fix tied to a ticket | Ticket ID mandatory |
+| `[hotfix: no-ticket: <reason ≥15 chars>]` | Emergency fix without a ticket | Explicit justification |
+| `[wip]` | Work-in-progress checkpoint | Feature branches only (Hard Rule 3) |
+
+**Anti-reset penalty** — override cycles are logged per session: ≥ 2 override cycles within 60 minutes lower the threshold from 3 to 2; ≥ 3 consecutive override cycles disable the override path entirely for the rest of the session (forced recovery via /dev).
+
+## Recap
+
+- Code change of any size → follow /dev phases, silently.
+- Skips come only from the Skip Matrix; Review and Document always run.
+- `[wip]` never lands on `main` / `master` / `prod*`.
+- Overrides are budgeted (2 per 30 min) and penalized when chained — /dev is always the cheaper path.

package/packages/core/rules/documentation.md

@@ -0,0 +1,106 @@
+---
+alwaysApply: true
+tokens: 1888
+---
+
+# Documentation Updates — MANDATORY
+
+## HARD RULE
+Code changes affecting logic, API, architecture, or behavior MUST include documentation updates **IN THE SAME RESPONSE** as the code. Code without updated docs = **INCOMPLETE TASK**. NEVER defer docs to "later" or "next commit".
+
+**Editing integrity.** Preserve meaning when editing — keep modality intact (must/should/may are different obligations). Preserve conditions, warnings, required actions. A cleaner sentence that changes obligations is wrong. No marketing vocabulary, no invented rationale in docs. *(Authoring principle from the golang-documentation skill.)*
+
+## 11-Point Pre-Commit Checklist
+
+Before EVERY `git commit`: if a Trigger matches any staged file, the Required Doc MUST also be staged. Multiple rows can match — satisfy all of them.
+
+| # | Trigger (staged files) | Required Doc |
+|---|------------------------|--------------|
+| 1 | `*/migrations/*.sql`, `*/db/migrate/*` | `docs/architecture/database-schema.md` AND `CLAUDE.md` (migration counter) |
+| 2 | `*/handlers/*.go`, `*/routes*.go`, `*/router*.go` | `docs/architecture/api-reference.md` OR `docs/openapi.yaml` |
+| 3 | `*/app/**`, `*/middleware*`, `*/jobs/**`, `*/workers/**`, `*/cmd/**` | `docs/architecture/backend-layers.md` |
+| 4 | `*/services/auth/**` | `docs/architecture/auth-and-sessions.md` |
+| 5 | Any other `*/services/<name>/**` | matching `docs/architecture/<service-doc>.md` — see example map below |
+| 6 | Frontend `src/**/*.ts`, `src/**/*.tsx` | `docs/architecture/frontend-state.md` |
+| 7 | ANY new non-test code file (`git diff --cached --diff-filter=A`) | relevant `docs/trees/tree-*.md` |
+| 8 | NEW dependency in `go.mod` / `package.json` | `README.md` Tech Stack section (or `CLAUDE.md`) |
+| 9 | `config.example.*`, `config.sample.*`, `.env.example` | `README.md` Configuration section |
+| 10 | Deploy/infra config changing runtime behavior (Dockerfile, compose, CI/CD) | `docs/architecture/deployment.md` |
+| 11 | New service directory or new `internal/` package | `README.md` Project Structure AND `CLAUDE.md` |
+
+The `doc-check-on-commit.sh` hook hard-blocks commits for most rows; rows it does not cover are equally mandatory under this rule.
+
+**README rule:** when dependencies or config shape change, README MUST reflect it. A `go.mod` listing samber/oops while README says "errors via fmt.Errorf" lies to every new developer.
+
+### Project-Specific Example Map — ADAPT TO YOUR PROJECT
+
+EXAMPLE rows from a production Telegram app — NOT generic. Replace paths and doc names with YOUR services, and keep this map in sync with the `case` statements in `doc-check-on-commit.sh` (the shipped hook hardcodes exactly these mappings — always edit the rule and the hook together).
+
+| Trigger (any depth) | Required Doc |
+|---------------------|--------------|
+| `*/services/media/**` | `docs/architecture/photo-pipeline.md` |
+| `*/services/moderation/**` | `docs/architecture/moderation-pipeline.md` |
+| `*/services/feed/**`, `*/services/antiabuse/**` | `docs/architecture/feed-and-antiabuse.md` |
+| `*/services/entitlements/**`, `*/services/store/**`, `*/services/payments/**` | `docs/architecture/entitlements-and-store.md` |
+| `*/services/notifications/**` | `docs/architecture/notification-system.md` |
+| `*/bot_moderator/**`, `*/bot_support/**`, `*/tgbots/**`, `*/bots/**` | `docs/architecture/bot-moderator.md` / `bot-support.md` |
+
+## When Docs Are NOT Needed
+
+- Pure refactors (no behavior change, same API contract)
+- Test-only changes (`*_test.go`, `*.test.ts`, `*.spec.ts`)
+- Typo fixes in non-doc files
+- Dependency patch/minor updates (NEW dependencies or major upgrades → row 8)
+
+**Config precedence rule:** a config change that alters runtime behavior or config shape other developers must know (example/sample config files, new config keys, deploy settings) → docs required per rows 9–10. Purely local/dev values (`.env` values, secrets, local overrides, editor settings) → exempt.
+
+## Enforcement (4 layers)
+
+| Layer | Mechanism | Type | When |
+|-------|-----------|------|------|
+| 1. **This rule** | loaded every session | Proactive | Always — primary mechanism |
+| 2. **PreToolUse hook** | `doc-check-on-commit.sh` | Hard block (exit 2) | Before every `git commit` — maps staged files to required docs, blocks if missing |
+| 3. **/dev Document phase** | `dev.md` phase gate | Phase gate | /dev cannot reach Report until docs are updated |
+| 4. **Stop hook** | prompt-type Stop hook inline in `settings.json` | Safety net | Session end — verifies docs updated when logic/API/architecture changed |
+
+Do NOT rely on layers 2–4 — update docs proactively with every code change (layer 1).
+
+### What CANNOT satisfy the doc requirement
+
+The hook excludes these paths from counting as "docs updated":
+
+- `docs/superpowers/plans/**`, `docs/superpowers/specs/**`, `docs/superpowers/research/**`
+- `memory/**`
+- `CHANGELOG.md`, `HISTORY.md`
+- `docs/active-plans-archive.md`
+
+These are meta-work: a plan describes intent; the architecture doc describes current system behavior. A contract change in `handlers/auth_handler.go` belongs in `docs/architecture/auth-and-sessions.md` — never "described in the plan file".
+
+## Plan Completion Gate
+
+When finishing an implementation plan (superpowers writing-plans / executing-plans):
+
+1. BEFORE marking the plan complete, run the 11-point checklist above; update any stale doc as the FINAL task.
+2. After a plan completes, `plan-completion-gate.sh` sets a marker: the next code commit MUST stage a `docs/architecture/*` file OR carry `[plan-docs-deferred: <plan-id>: <reason ≥15 chars>]` in the commit message.
+3. A plan is NOT complete until docs are updated.
+
+## Subagent Instructions
+
+When delegating via the Agent tool, list EVERY specific doc file — never say "update docs" generically:
+
+```
+After making code changes, update these documentation files:
+1. `docs/architecture/<specific-file>.md` — <what to update>
+2. `CLAUDE.md` — <specific section> (e.g., migration counter, Active Plans)
+3. `docs/trees/<specific-tree>.md` — regenerate if files were added/removed
+4. `docs/openapi.yaml` — add/update endpoint definitions
+```
+
+Subagents MUST NOT commit without doc updates. A subagent that cannot determine which docs to update asks the parent — it does not skip docs.
+
+## Recap — non-negotiables
+
+- Docs ship IN THE SAME RESPONSE as the code — code without docs = INCOMPLETE TASK.
+- Before every commit, walk the 11-point checklist; every matching row's doc must be staged.
+- Plans/specs/memory/CHANGELOG never satisfy the doc requirement — only architecture docs, trees, README, CLAUDE.md, openapi.yaml do.
+- A plan is NOT complete until the checklist passes.

package/packages/core/rules/frontend-aesthetics.md

@@ -0,0 +1,53 @@
+---
+alwaysApply: false
+applyWhenPaths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+  - "**/*.vue"
+  - "**/*.svelte"
+  - "**/*.css"
+  - "**/*.scss"
+tokens: 624
+---
+
+# Frontend Aesthetics
+
+Proactive anti-slop: apply DURING frontend code generation, not after review.
+Precedence: if the frontend-ui package rules are installed (`typography-guidelines.md`, `ui-anti-patterns.md`, etc. in `.claude/rules/`), follow those — this rule is the minimal fallback.
+
+## Hard Rules
+- Tokens first: every color, spacing value, and font size comes from a defined scale (see Design System Compliance).
+- NEVER default to Inter, Roboto, Arial, Helvetica, Open Sans, or bare system fonts — run the Typography procedure instead.
+- NEVER ship any pattern from the AI Pattern Red Flags list.
+
+## Typography — selection procedure
+1. Project already loads fonts (Tailwind/theme config, `@font-face`, `next/font`, `<link>` import)? → use that stack.
+2. No stack? → pick one characterful display face for headings + one workhorse body face, from fonts the project can actually load (self-hosted files or a provider it already uses); name both picks in your response.
+3. Nothing loadable and no user direction? → propose 2–3 named pairings and ask — do not silently fall back to defaults.
+
+Hierarchy: headings, body, and captions must differ in at least two of size / weight / family.
+
+## Color & Theme
+- Commit to one cohesive palette via CSS variables; dominant base + sharp accents beats a timid, evenly-distributed palette.
+- Draw from the project's design system tokens when available.
+
+## Motion & Animation
+- Concentrate on high-impact moments: one well-orchestrated page load with staggered reveals beats scattered micro-interactions.
+- Use the project's existing animation library (motion/react, framer-motion, CSS transitions); prefer CSS-only when it suffices.
+
+## Backgrounds & Depth
+- Create atmosphere: layer CSS gradients, geometric patterns, contextual effects — not solid white/gray defaults.
+
+## AI Pattern Red Flags (AVOID these)
+- Purple/blue gradient as default accent color
+- White cards on gray background with identical spacing everywhere
+- Generic hero section with stock imagery
+- Rounded corners on everything with no visual hierarchy
+- box-shadow on every interactive element
+- "Clean and modern" that actually means "bland and default"
+- Identical spacing/padding/gap values everywhere — no rhythm
+
+## Design System Compliance
+- If a design system exists (Tailwind config, theme file, tokens) — use it.
+- If none — establish consistent tokens (CSS variables) before building components.
+- Every color, spacing value, and font size comes from a defined scale.

package/packages/core/rules/git-workflow.md

@@ -0,0 +1,14 @@
+---
+alwaysApply: true
+tokens: 131
+---
+
+# Git Workflow
+
+- **Commits**: conventional format `type(scope): description`
+  - Types: feat, fix, docs, refactor, chore, test, perf. Anything else → chore
+  - Scope: the top-level module/package the change touches — derive it from this repo's structure (e.g. backend, frontend, cli)
+- **No --no-verify**: Fix pre-commit hook issues, don't skip them
+- **No force push to main**: Use PRs
+- **No git reset --hard**: Use stash or soft reset
+- **Branch naming**: `feature/description`, `fix/description`, `chore/description`

package/packages/core/rules/security.md

@@ -0,0 +1,29 @@
+---
+alwaysApply: false
+applyWhenPaths:
+  - "**/*.go"
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+  - "**/*.py"
+  - "**/*.rs"
+  - "**/*.java"
+  - "**/*.kt"
+  - "**/*.rb"
+  - "**/*.sql"
+  - ".github/workflows/**"
+  - "Dockerfile*"
+  - "docker-compose*"
+tokens: 152
+---
+
+# Security
+
+- SQL: parameterized queries ($1 for pgx, ? for MySQL; Python: %s placeholders passed as driver params — `execute(sql, params)` — never f-strings, .format(), or % interpolation)
+- XSS: no dangerouslySetInnerHTML without DOMPurify
+- Secrets: no hardcoded tokens/passwords/keys — use env vars
+- Auth: all API endpoints require auth middleware, except an enumerated public allowlist (health checks, auth entry points, signature-verified webhooks)
+- Input: validate at system boundaries
+- Files: validate MIME type and size server-side
+- CORS: explicit origin allowlist, no wildcards in production

package/packages/core/rules/superkit-integrity.md

@@ -0,0 +1,114 @@
+---
+alwaysApply: true
+tokens: 1383
+---
+
+# Superkit Integrity — Verify Before Commit (superkit repo only)
+
+## HARD RULE
+
+- Before EVERY `git commit` in this repo: run Steps 1–4 below with real commands. Never verify from memory.
+- ANY mismatch → fix it, THEN commit.
+- Before EVERY `gh release create`: additionally pass the 7-point Pre-Release Audit.
+- The hook `packages/core/hooks/superkit-counts-verify.sh` (PreToolUse on `git commit`/`git push`, exit 2 = block) auto-enforces most of Steps 1–2, but NOT Steps 3–4 (phase count, stale refs) — only this rule catches those.
+
+### Step 1 — Count Verification (30s)
+
+Fast path: `bash bin/superkit-counts-verify.sh` runs the hook's count/version checks manually (add `--check-remote` to also verify GitHub About). Exit 0 clears the hook-checked subset; the items the hook skips are listed below the table. Manual equivalent:
+
+```bash
+# Per-package counts (same globs the hook uses)
+CORE_AGENTS=$(ls packages/core/agents/*.md | wc -l)
+STACK_AGENTS=$(ls packages/stack-agents/*/*.md | wc -l)               # references/ not matched
+PKG_AGENTS=$(ls packages/{frontend-3d,frontend-ui,gan}/agents/*.md | wc -l)
+EXTRAS_AGENTS=$({ ls packages/extras/*.md; ls packages/extras/*/agent.md; } | wc -l)
+CORE_HOOKS=$(ls packages/core/hooks/*.sh packages/core/hooks/*.py | wc -l)
+STACK_HOOKS=$(ls packages/stack-hooks/*/*.sh | wc -l)
+PKG_HOOKS=$(ls packages/{frontend-3d,frontend-ui}/hooks/*.sh | wc -l)
+CORE_RULES=$(ls packages/core/rules/*.md | wc -l)
+STACK_RULES=$(ls packages/stack-rules/*/*.md | wc -l)
+PKG_RULES=$(ls packages/{frontend-3d,frontend-ui}/rules/*.md | wc -l)
+CORE_COMMANDS=$(ls packages/core/commands/*.md | wc -l)
+PKG_COMMANDS=$(ls packages/frontend-3d/commands/*.md | wc -l)
+SKILLS=$(find packages/{core,frontend-3d,frontend-ui,gan,extras} -name SKILL.md | wc -l)
+CODEX_SKILLS=$(find packages/codex/skills -name SKILL.md | wc -l)
+
+# Shipped totals — subtract superkit-internal files (never installed;
+# canonical list: packages/core/INTERNAL-FILES — the single source of truth
+# consumed by lib/installer.js, superkit-counts-verify.sh and superkit-update.sh)
+AGENTS=$((CORE_AGENTS + STACK_AGENTS + PKG_AGENTS + EXTRAS_AGENTS))   # 31+9+13+3 = 56
+HOOKS=$((CORE_HOOKS - 2 + STACK_HOOKS + PKG_HOOKS))                   # 26+9+7    = 42
+RULES=$((CORE_RULES - 1 + STACK_RULES + PKG_RULES))                   # 7+2+10    = 19
+COMMANDS=$((CORE_COMMANDS + PKG_COMMANDS))                            # 15+1      = 16
+                                                                      # SKILLS      = 22
+```
+
+Every computed number must equal what is documented in:
+
+| Where | Must match |
+|-------|------------|
+| `README.md` badge + "What's Inside" table | AGENTS, HOOKS, RULES, COMMANDS, SKILLS totals; CORE_AGENTS; "N skills" near Codex |
+| `CLAUDE.md` "Current Counts" table + Totals line | every per-package cell + all five totals |
+| `packages/codex/INSTALL.md` + `AGENTS.md` | CODEX_SKILLS ("N skills") |
+| GitHub About (`gh repo view --json description`) | all five counts; hook checks agents/commands/hooks/rules on `git push` |
+
+NOT hook-checked — compare yourself: SKILLS (=22) everywhere it appears (incl. GitHub About), plus CLAUDE.md cells beyond the hook's spot checks (it verifies only Core/Stack Agents, Core Commands, Codex Skills, Showcase Commands). Mismatch → update the docs (GitHub via `gh repo edit --description`) BEFORE committing.
+
+### Step 2 — Version Sync (10s)
+
+```bash
+VERSION_FILE=$(cat VERSION | tr -d '[:space:]')
+PKG_VERSION=$(node -p "require('./package.json').version")
+```
+
+VERSION MUST equal package.json version, and CHANGELOG.md MUST contain that version string (hook blocks both). Differ → fix BEFORE committing.
+
+### Step 3 — Phase Count Consistency (10s)
+
+`packages/core/commands/dev.md` frontmatter declares the /dev phase count (currently "16 phases (0–15)"). The SAME count must appear in:
+
+- `README.md` — Key Commands `/dev` row AND the `docs/dev-flow.svg` embed's `alt` text ("/dev — 16-phase development orchestrator…"). If the count ever changes, regenerate the SVG labels and `docs/dev-flow-variants/` too.
+- `CLAUDE.md` — Key Files table, dev.md row
+- `docs/guide/01-getting-started.md` — command table
+- `docs/guide/08-orchestration.md` — "The /dev Pipeline: N Phases" header
+- `packages/codex/AGENTS.md` — dev-orchestrator row
+- `packages/codex/skills/dev-orchestrator/SKILL.md` — frontmatter description
+
+### Step 4 — Stale Reference Scan (10s)
+
+Substitute `<PREV>` = the PREVIOUS phase count, then run:
+
+```bash
+grep -rn "<PREV>-phase" docs/ README.md CLAUDE.md packages/codex/ --include="*.md" \
+  | grep -v plans/ | grep -v CHANGELOG
+```
+
+Filled example after an 8→16 renumber: `grep -rn "8-phase" …`. Must return 0 lines. plans/ and CHANGELOG are historical — leave them; everything else uses the CURRENT count.
+
+## Pre-Release Audit — before EVERY `gh release create`
+
+All 7 must pass:
+
+1. Steps 1–4 above all pass.
+2. `git tag -l "vX.Y.Z"` — the release tag exists.
+3. `cat VERSION` matches the tag version.
+4. package.json version matches VERSION.
+5. `grep "## \[X.Y.Z\]" CHANGELOG.md` — the version section exists.
+6. README "What's New" references vX.Y.Z.
+7. `git status` — working tree clean, nothing uncommitted.
+
+ANY check fails → fix, re-commit, re-run, THEN release.
+
+## When to Skip Steps 1–4
+
+- Docs-only wording/typo changes touching no counts, versions, or phase references.
+- Plan/spec files under docs/superpowers/.
+- Test files.
+
+Unsure whether counts changed → run the steps (<1 minute total). This drift class shipped before (v1.3.5: 8 stale refs) — the checks are cheaper than the cleanup.
+
+## Recap
+
+- Never commit with a count/version mismatch — run Steps 1–4 first, fix before committing.
+- Never `gh release create` unless Steps 1–4 AND all 7 release checks pass.
+- Skip verification only for docs-only wording, docs/superpowers/ plans, and test files.