@fernado03/zoo-flow 0.11.1 → 0.11.3

package/templates/claude-code/.claude/skills/misc/scaffold-exercises/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: scaffold-exercises
+description: Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. Use when user wants to scaffold exercises, create exercise stubs, or set up a new course section.
+---
+
+# Scaffold Exercises
+
+Goal: create exercise dirs passing `pnpm ai-hero-cli internal lint`, then commit.
+
+## Naming
+
+- Sections: `exercises/XX-section-name/`.
+- Exercises: `XX.YY-exercise-name/` inside section.
+- Lowercase dash-case.
+
+## Variants
+
+Each exercise needs ≥1: `problem/`, `solution/`, `explainer/`. Default stub: `explainer/` unless plan says otherwise.
+
+## Required files
+
+- Each variant folder: non-empty `readme.md`.
+- Minimal readme:
+
+```md
+# Exercise Title
+
+Description here
+```
+
+- If folder has code, `main.ts` >1 line required.
+- Readme-only stubs allowed.
+
+## Workflow
+
+1. Parse plan into sections/exercises/variants.
+2. Use `Bash` to `mkdir -p` dirs.
+3. Use `Write` to create readme stubs.
+4. Use `Bash` to run `pnpm ai-hero-cli internal lint`.
+5. Fix until pass.
+6. Use `Bash` to move/rename with `git mv`.
+7. Use `Bash` to commit with `git commit`.
+
+## Lint constraints
+
+- Exercise has subfolder.
+- At least one of `problem/`, `explainer/`, `explainer.1/` exists.
+- Primary readme exists and non-empty.
+- No `.gitkeep`.
+- No `speaker-notes.md`.
+- No broken links.
+- No `pnpm run exercise` in readmes.
+- `main.ts` required only when code present.

package/templates/claude-code/.claude/skills/misc/setup-pre-commit/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: setup-pre-commit
+description: Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing.
+---
+
+# Setup Pre-Commit Hooks
+
+Creates Husky pre-commit, lint-staged Prettier, optional typecheck/test.
+
+## Process
+
+1. Detect package manager: `package-lock.json`→npm; `pnpm-lock.yaml`→pnpm; `yarn.lock`→yarn; `bun.lockb`→bun; default npm.
+2. Use `Bash` to install dev deps, adapting package manager:
+
+```bash
+npm i -D husky lint-staged prettier
+```
+
+3. Use `Bash` to init Husky:
+
+```bash
+npx husky init
+```
+
+4. Use `Write` to write `.husky/pre-commit`, adapting package manager; omit missing scripts and tell user:
+
+```text
+npx lint-staged
+npm run typecheck
+npm run test
+```
+
+5. Use `Write` to create `.lintstagedrc`:
+
+```json
+{
+  "*": "prettier --ignore-unknown --write"
+}
+```
+
+6. Use `Write` to create `.prettierrc` only if no Prettier config:
+
+```json
+{
+  "useTabs": false,
+  "tabWidth": 2,
+  "printWidth": 80,
+  "singleQuote": false,
+  "trailingComma": "es5",
+  "semi": true,
+  "arrowParens": "always"
+}
+```
+
+7. Verify: executable `.husky/pre-commit`; `.lintstagedrc`; `prepare` script = `husky`; Prettier config; use `Bash` to run `npx lint-staged`.
+8. Use `Bash` to commit:
+
+```bash
+git commit -m "Add pre-commit hooks (husky + lint-staged + prettier)"
+```
+
+RULE: Wait for explicit user approval before commit if current mode requires HITL.

package/templates/claude-code/.claude/skills/personal/edit-article/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: edit-article
+description: Edit and improve articles by restructuring sections, improving clarity, and tightening prose. Use when user wants to edit, revise, or improve an article draft.
+---
+
+# Edit Article
+
+1. Use `Read` to divide article by headings.
+2. Identify main point per section.
+3. Reorder sections/content so dependencies flow first.
+4. Confirm section plan with user.
+5. Use `Edit` to rewrite each section for clarity/coherence/flow.
+6. Max 240 chars per paragraph.

package/templates/claude-code/.claude/skills/personal/obsidian-vault/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: obsidian-vault
+description: Search, create, and manage notes in the Obsidian vault with wikilinks and index notes. Use when user wants to find, create, or organize notes in Obsidian.
+---
+
+# Obsidian Vault
+
+## Vault path
+
+1. Use `$OBSIDIAN_VAULT_PATH`.
+2. If unset, STOP and ask absolute vault path.
+
+## Naming
+
+- Index notes aggregate related topics: `Ralph Wiggum Index.md`.
+- Title Case filenames.
+- No folders for org; use wikilinks/index notes.
+
+## Linking
+
+- Use `[[wikilinks]]`.
+- Add related/dependency links at bottom.
+- Index notes = wikilink lists.
+
+## Commands
+
+```bash
+find "/mnt/d/Obsidian Vault/AI Research/" -name "*.md" | grep -i "keyword"
+grep -rl "keyword" "/mnt/d/Obsidian Vault/AI Research/" --include="*.md"
+grep -rl "\\[\\[Note Title\\]\\]" "/mnt/d/Obsidian Vault/AI Research/"
+find "/mnt/d/Obsidian Vault/AI Research/" -name "*Index*"
+```
+
+## Create note
+
+1. Title Case filename.
+2. Use `Write` to write one learning unit.
+3. Add related wikilinks at bottom.
+4. If numbered sequence, use hierarchy.

package/templates/claude-code/.claude/skills/productivity/grill-me/SKILL.md

@@ -14,7 +14,8 @@ description: Interview the user about a plan or design until reaching shared und
 
 ## Complete
 
-Return a summary with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - decision tree branches resolved (count)
 - key decisions made (summary)
 - status (complete / blocked with reason)

package/templates/claude-code/.claude/skills/productivity/handoff/SKILL.md

@@ -15,6 +15,7 @@ argument-hint: "What will the next session be used for?"
 
 ## Complete
 
-Return a summary with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - handoff file path (OS temp dir)
 - status (complete / blocked with reason)

package/templates/claude-code/.claude/skills/productivity/teach/SKILL.md

@@ -109,7 +109,8 @@ The user will sometimes express preferences of how they want to be taught, or th
 
 When the user ends the teaching session or says "done" / "stop teaching":
 
-Return a summary with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - lessons created (count, paths)
 - mission status (created / updated)
 - learning records updated (count)

package/templates/claude-code/.claude/skills/productivity/write-a-skill/SKILL.md

@@ -53,7 +53,8 @@ Add when: deterministic op; repeated code; explicit error handling needed.
 
 ## Complete
 
-Return a summary with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - skill created (name, path)
 - files written (SKILL.md, references, scripts)
 - status (complete / blocked with reason)

package/templates/claude-code/CLAUDE.md

@@ -122,6 +122,29 @@ Agent(
 )
 ```
 
+### Agent Completion Protocol
+
+**Critical**: When delegating to an agent via the `Agent` tool, the agent must understand how to return its work:
+
+1. **Your final text message IS the return value** - The parent agent receives exactly what you write as your last message
+2. **Output the completion summary, then STOP** - Do not call any more tools after writing your completion
+3. **Be complete in your final message** - Include all required information (files changed, status, recommendations)
+
+Add this to your agent prompts:
+```
+COMPLETION PROTOCOL:
+Your final text message is your return value to the parent agent.
+When you finish, output a summary with:
+- What was done
+- Status: complete / blocked (with reason)
+- Files changed (if any)
+- Recommended next command (if any)
+
+Then STOP - do not call any more tools or take any more actions.
+```
+
+This is similar to how ultracode's Workflow tool handles subagent completion.
+
 ### Multi-Phase Commands
 
 Commands like `/fix`, `/feature`, and `/refactor` involve multiple phases:

package/docs/architecture.md

@@ -1,380 +0,0 @@
-# Architecture
-
-Zoo Flow ships three custom modes, a fixed routing matrix, a small set of
-always-on rules, and a directory layout for slash commands and on-demand
-skills. This document explains what each piece does and why it is shaped
-the way it is.
-
-## Components
-
-```
-templates/full/
-├── .roomodes                       # minimal: slug, groups, short pointers
-└── .roo/
-    ├── rules/                      # always-on, every mode, every turn
-    │   ├── 00-paths.md
-    │   ├── 01-command-protocol.md
-    │   ├── 02-three-failure-rule.md
-    │   ├── 03-manual-reply-protocol.md
-    │   ├── 04-context-economy.md
-    │   └── 05-mcp-awareness.md
-    ├── rules-custom-orchestrator/  # mode-scoped, orchestrator only
-    │   ├── 00-routing.md
-    │   └── 01-delegation-message.md
-    ├── rules-system-architect/     # mode-scoped, architect only
-    │   ├── 00-scope.md
-    │   ├── 01-feature-prototype.md
-    │   └── 02-completion.md
-    ├── rules-code-tweaker/         # mode-scoped, tweaker only
-    │   ├── 00-scope.md
-    │   └── 01-completion.md
-    ├── commands/                   # slash commands (the public API)
-    └── skills/                     # on-demand skills, loaded by commands
-        ├── engineering/
-        ├── productivity/
-        ├── misc/
-        ├── personal/
-        └── in-progress/
-```
-
-`.roomodes` is intentionally minimal. It declares each mode's slug,
-role, tool groups, and a short `customInstructions` block that points
-at the matching `.roo/rules-{modeSlug}/` folder. All detailed mode
-behavior lives in the rule files inside that folder. See
-[`mode-rules.md`](mode-rules.md) for the full layout rationale.
-
-> Zoo Flow uses the preferred `.roo/rules-{modeSlug}/` directory form
-> only. Legacy single-file fallbacks such as `.roorules-{modeSlug}` and
-> `.clinerules-{modeSlug}` are not used by this template.
-
-## Modes
-
-### `custom-orchestrator`
-
-Defined in `templates/full/.roomodes`. Tool groups: **none**. Detailed
-behavior lives in
-[`.roo/rules-custom-orchestrator/`](../templates/full/.roo/rules-custom-orchestrator/)
-(`00-routing.md`, `01-delegation-message.md`).
-
-The orchestrator cannot read, edit, run commands, or call MCP tools. It
-exists to do exactly four things:
-
-1. Read the user request.
-2. Map it to a command using the routing matrix in its
-   `customInstructions`.
-3. Either delegate via `new_task` (when the user supplied an explicit
-   slash command) or offer 1-2 numbered workflow choices and halt
-   (when they did not).
-4. Summarize the subtask result and halt again.
-
-It never uses `switch_mode`. If `new_task` is unavailable, it stops and
-reports — it does not try to do the work itself.
-
-### `system-architect`
-
-Tool groups: `command`, `mcp`, `read`, and a constrained `edit` that only
-matches Markdown files, `.scratch/`, and `docs/`. The `fileRegex` lives in
-`.roomodes`:
-
-```json
-{ "fileRegex": "(.*\\.md$|^\\.scratch/.*|^docs/.*)" }
-```
-
-Detailed behavior lives in
-[`.roo/rules-system-architect/`](../templates/full/.roo/rules-system-architect/)
-(`00-scope.md`, `01-feature-prototype.md`, `02-completion.md`).
-
-The architect plans, diagnoses, refactors, explores, and triages. It cannot
-edit application source code. When implementation is needed, it
-`switch_mode`s to `code-tweaker` inside the same task window.
-
-Hard stops are baked in:
-
-- 3-strike rule on diagnosis: after three failed attempts, halt and ask
-  the user.
-- HITL stop before testing a hypothesis, finalizing a plan, publishing
-  issues, or making any irreversible decision.
-- During `/feature`, never run a prototype directly. Summarize and
-  switch to the tweaker.
-
-### `code-tweaker`
-
-Tool groups: `read`, `edit`, `command`, `mcp`. Full repo access within the
-assigned command. Detailed behavior lives in
-[`.roo/rules-code-tweaker/`](../templates/full/.roo/rules-code-tweaker/)
-(`00-scope.md`, `01-completion.md`).
-
-The tweaker implements, runs tests, updates docs, builds prototypes, and
-prepares commits.
-
-Hard stops:
-
-- Auto-escalate to the architect on the **same task window** if the work
-  needs major architecture decisions or the same approach fails three times.
-- Git stop: never run `git commit` or `git push` without explicit user
-  approval. Pushes only happen when the user asks.
-- Complete the whole chain, not the current phase. `attempt_completion`
-  returns to the orchestrator only after the command's **final** phase.
-  If a later phase belongs to the architect (e.g. `/fix` post-mortem),
-  hand back with `switch_mode` instead of completing early.
-
-## Command protocol
-
-The protocol is in
-[`templates/full/.roo/rules/01-command-protocol.md`](../templates/full/.roo/rules/01-command-protocol.md).
-It is loaded on every turn for every mode.
-
-When a mode is assigned a slash command:
-
-1. **Normalize.** `/fix` becomes `fix`.
-2. **Prefer `run_slash_command`.** Pass the normalized name as `command`
-   and the full task context as `args`.
-3. **Fall back to the file.** If `run_slash_command` is unavailable,
-   disabled, or fails, read `templates/full/.roo/commands/{command}.md`
-   and execute its instructions.
-4. **Resolve skills via the file.** If the command references a skill,
-   read the exact `.roo/skills/...` path the command provides. Do not
-   compute paths from anywhere else.
-5. **Do not chain.** A command suggested inside a subtask summary is
-   *not* authorization to run that command. Only the human or the
-   orchestrator's routing may launch a new command.
-
-The protocol exists to make slash commands work the same way whether the
-host UI exposes a native command runner or only file reads.
-
-### Command types
-
-Zoo Flow supports two command types:
-
-1. **Skill-wrapper commands.** The command file declares a skill via a
-   line like:
-
-   ```md
-   Skill: `.roo/skills/engineering/tdd/SKILL.md`
-   ```
-
-   The worker loads and follows that skill.
-
-2. **Direct workflow commands.** The command file contains the
-   procedure directly (no `Skill:` line). The worker executes those
-   steps directly and must not invent a skill path.
-
-This prevents redundant loading and avoids hallucinated skill paths.
-
-## Path safety
-
-The path-safety contract is in
-[`templates/full/.roo/rules/00-paths.md`](../templates/full/.roo/rules/00-paths.md).
-Two rules:
-
-- Skills are at workspace-root paths under `.roo/skills/{bucket}/{skill}/SKILL.md`.
-- Commands are at workspace-root paths under `.roo/commands/{name}.md`.
-
-The forbidden form is anything under `.roo/rules/skills/...` or
-`.roo/rules/commands/...`. Modes that try to load skills relative to a
-`rules/` file have produced the most common failure in practice
-(`ENOENT: .roo/rules/skills/...`). The rule blocks it before it happens.
-
-## Slash commands
-
-Each command is a Markdown file with a YAML front matter and a body. The
-front matter declares the target mode and the argument hint:
-
-```markdown
----
-description: "Direct implementation mode for small, known fixes or UI updates."
-argument-hint: <what to change>
-mode: code-tweaker
----
-
-Skill: `.roo/skills/engineering/tweak/SKILL.md`
-
-$ARGUMENTS
-```
-
-The body is the actual instruction set. Some commands invoke a single
-skill (`/tweak`, `/prototype`). Others orchestrate a multi-phase chain
-across modes (`/fix`, `/feature`, `/refactor`).
-
-A command can:
-
-- Reference a skill by its exact `.roo/skills/...` path.
-- Spell out HITL stops between phases.
-- Direct a mode to `switch_mode` to another mode at a specific phase.
-- Substitute `$ARGUMENTS` with the user / delegated context.
-
-A command must not:
-
-- Compute skill paths dynamically.
-- Bypass the orchestrator when handing the human a choice.
-- Auto-launch a follow-up command from a subtask summary.
-
-### Core vs. helper commands
-
-The orchestrator's **routing matrix** intentionally only routes a small
-set of core workflow commands:
-
-- `/tweak`, `/tdd`, `/update-docs`, `/commit-and-document`, `/prototype`, `/verify`
-  → `code-tweaker`
-- `/fix`, `/feature`, `/refactor`, `/explore`, `/triage`, `/review`
-  → `system-architect`
-
-Every other command in `templates/full/.roo/commands/` is a **helper**.
-Helpers are real, working commands. They are run directly inside the
-appropriate mode rather than delegated by the orchestrator. This keeps
-the orchestrator's routing matrix small and predictable, while leaving
-the broader command library available when you want it.
-
-If a helper command starts being used often enough to deserve
-delegation, promote it to the routing matrix in `.roomodes` and add it
-to the routed table in [`README.md`](../README.md#commands).
-
-## Skills
-
-Skills live under `templates/full/.roo/skills/`. Each skill is a folder
-with a `SKILL.md` and any supporting files (templates, scripts, sub-docs).
-They are organized into buckets:
-
-- `engineering/` — code work.
-- `productivity/` — non-code workflow.
-- `misc/` — kept around but rarely used.
-- `personal/` — tied to a maintainer's setup, not promoted.
-- `in-progress/` — drafts, not ready to ship.
-
-Skills are loaded **only** through commands. There is no "skill autoloader"
-that pulls them on every turn. The orchestrator does not see skills at all;
-it only sees commands.
-
-The skills index lives in [`docs/skills-index.md`](skills-index.md).
-It is human-facing reference documentation, intentionally kept outside
-`.roo/rules/` because `.roo/rules/` is injected on every turn. Commands
-load skills directly from explicit `.roo/skills/.../SKILL.md` paths, so
-the index is not required for runtime execution.
-
-### Skill output placement
-
-Skills that produce throwaway working files share a single convention
-so cleanup is mechanical:
-
-- `.scratch/<command>-<slug>.md` — phase checklists for `/fix`,
-  `/feature`, `/refactor`; optional `/explore` save-targets under
-  `.scratch/explorations/<date>/`; local PRDs and issues from
-  `setup-matt-pocock-skills` (`.scratch/{feature-slug}/`).
-- `.scratch/prototypes/<slug>/` — logic, state, and data-model
-  prototypes from `/prototype` (`LOGIC.md` branch). UI prototypes stay
-  adjacent to the real page they mock up because they need the route,
-  data fetching, and auth.
-- `docs/journal/` — entries written by `/commit-and-document`.
-- In-place edits — `/tweak`, `/tdd`, `migrate-to-shoehorn`,
-  `update-docs`.
-
-`.scratch/` is on the architect's `fileRegex` allowlist, so it is a
-safe edit target for `system-architect` and a natural bulk-cleanup
-target for the user.
-
-## Three-folder contract
-
-Zoo Flow uses three distinct folders, each with a different lifetime
-and replacement policy. Keeping them separate is intentional:
-
-| Folder | Lifetime | Loaded every turn? | Replaced by `init`/`update`? | Gitignored? | Authored by |
-|---|---|---|---|---|---|
-| `.roo/` | Per release | ✅ (rules/) | ✅ (full replace) | No | Template |
-| `.scratch/` | Per chain | ❌ | ❌ | Convention | Worker |
-| `.zoo-flow/` | Per project | ❌ | ❌ (migrated) | ✅ (init appends) | User via /grill-with-docs |
-
-**Why three folders, not one.** Each row has a different replacement
-policy and a different authorship model. Collapsing them would force
-the host to grow exception mechanisms (don't auto-load, don't replace
-this subset, don't wipe user content) that defeat the point of having
-a single contract.
-
-**Why `.zoo-flow/` instead of root.** Root `CONTEXT.md` and root
-`docs/adr/` polluted every project with files only some projects
-needed. `.zoo-flow/` is hidden, gitignored by default, and houses only
-the universally-essential `CONTEXT.md` placeholder plus user-authored
-ADRs. The other slots (ARCHITECTURE.md, APP_MAP.md, FLOW.md) are
-created on demand and never pre-shipped. The full slot list and
-discovery rule live in
-[`grill-with-docs/CONTEXT-FORMAT.md`](../templates/full/.roo/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md).
-
-## Same-window `switch_mode`
-
-Used inside a single task window when one mode needs the other for a phase
-of the same workflow. Examples:
-
-- `/fix` going architect (diagnose) → tweaker (implement) → architect
-  (post-mortem).
-- `/feature` going architect (sharpen) → tweaker (prototype) → architect
-  (PRD).
-- `code-tweaker` auto-escalating after a 3-strike test failure.
-
-`switch_mode` preserves context. The receiving mode reads the same task
-window and continues. Use it for tight loops where the cost of losing
-context outweighs the benefit of a clean boundary.
-
-## Delegated `new_task`
-
-Used by the orchestrator only. The orchestrator does not implement
-anything; it hands work off to the architect or the tweaker via
-`new_task`. The delegated message must include:
-
-- The slash command, including the leading slash.
-- The user context.
-- A proceed policy. One of: `Proceed automatically after audit if
-  clean`, `Ask user before implementation`, or `Stop and report only`.
-- A reminder to follow `.roo/rules/01-command-protocol.md`.
-- A reminder that skills live under `.roo/skills/...`.
-- A completion rule: finish the **whole command chain**, then end with
-  `attempt_completion` containing summary, files inspected/changed,
-  commands/tests run, blockers, and a recommended next command. Mid-chain
-  mode handoffs use `switch_mode`, not `attempt_completion`.
-
-`new_task` opens a fresh subtask window. The boundary is the point.
-Mode-internal context, scratch work, and false starts stay in the
-subtask.
-
-## Proceed policy
-
-Zoo Flow delegated tasks include a proceed policy so workers know when
-to continue and when to ask the user.
-
-Policies:
-
-- `Proceed automatically after audit if clean`
-- `Ask user before implementation`
-- `Stop and report only`
-
-This prevents unnecessary questions during well-specified subtasks,
-while preserving approval gates for hypotheses, architecture decisions,
-commits, issue changes, and irreversible actions.
-
-## `attempt_completion`
-
-Used at the end of a delegated subtask. It is **not** an escape hatch.
-
-A delegated task is the **entire command chain** — every phase and every
-mode switch the command body defines — not the single phase a mode is
-currently running. A worker returns via `attempt_completion` only after
-the command's **final** phase. Mid-chain handoffs between modes use
-`switch_mode`.
-
-Specifically, the architect must not use `attempt_completion` to skip
-required implementation work — if the work belongs to the tweaker, the
-architect uses `switch_mode` first. Likewise the tweaker must not complete
-out from under a remaining architect phase (e.g. `/fix` post-mortem); it
-`switch_mode`s back. Before any `attempt_completion`, the worker re-checks
-the command body and confirms no later phase is assigned to another mode.
-The composite commands (`/fix`, `/feature`, `/refactor`) persist a phase
-checklist under `.scratch/` so this survives context growth and mode
-switches.
-
-`attempt_completion` returns to the orchestrator with a structured summary.
-The orchestrator then summarizes for the user and halts. It never
-auto-launches the next subtask, even if the summary suggests one.
-
-## Context economy
-
-Zoo Flow avoids unnecessary token use by asking agents to search or list before broad reads, use targeted line ranges when possible, and avoid re-reading unchanged files.
-
-Full-file reads are still allowed when correctness requires complete context.

package/docs/bloat-control.md

@@ -1,49 +0,0 @@
-# Bloat Control
-
-Zoo Flow must stay small, focused, and hard to break. Every addition
-of a command, doc, rule, or skill must clear a bloat gate.
-
-## Bloat gate
-
-Before adding any new:
-
-- **Command** (composite or routed)
-- **Documentation file** under `docs/`
-- **Global rule** under `.roo/rules/`
-- **Mode-specific rule** under `.roo/rules-{mode}/`
-- **Skill** that ships by default
-
-Answer these:
-
-1. **Is it needed by most projects?** If not, it should be a
-   context pack or a community skill, not a default.
-2. **Does it cross SA/CT boundaries?** If not, prefer a skill or
-   helper command over a composite.
-3. **Does it add a new check to doctor?** Every file addition should
-   also add a doctor validation for it.
-4. **Does it fit a token budget tier?** Every file has a budget
-   (see `docs/token-budget.md`). If it exceeds the tier, add an
-   exception with justification.
-5. **Does it require documentation?** Every command and every new
-   doc file needs README or docs/ coverage with a link that
-   `check-package-links.js` validates.
-
-## Guardrails
-
-- Do not create optional docs by default. `/scaffold-context` may
-  offer them, but they are never written without user confirmation.
-- Do not add composite commands unless they meet all criteria in
-  `docs/command-design.md`.
-- Do not weaken approval gates or auto-run `/verify`, `/review`, or
-  `/commit-and-document`.
-- Token budgets with explicit exceptions are enforced by
-  `scripts/token-budget.js`.
-
-## Anti-patterns
-
-- Adding a command "because it might be useful" — put it in a skill
-  or context pack.
-- Accepting doc bloat "because it clarifies things" — token budget
-  will catch it.
-- Creating optional docs as defaults — they are only offered through
-  `/scaffold-context` after user confirmation.