@fernado03/zoo-flow 0.11.3 → 0.12.1

package/examples/feature-flow.md

@@ -0,0 +1,117 @@
+# Example: `/feature` flow
+
+The `/feature` chain is the longest one Zoo Flow ships. It exists
+specifically because the most expensive mistakes happen when an agent
+implements a feature it has not properly sharpened. The chain forces
+the slow steps before any code is written.
+
+## Setup
+
+- Active mode: `🪃 Custom Orchestrator`.
+- Example feature:
+
+  > "Add a dark mode toggle to the settings page."
+
+## Phase 1 — orchestrator routes
+
+Type:
+
+```
+/feature Add a dark mode toggle to the settings page.
+```
+
+The orchestrator delegates with `new_task` to `system-architect`.
+
+## Phase 2 — architect sharpens
+
+The architect runs `grill-with-docs` to sharpen the request. Expect:
+
+- Questions about target users and platforms.
+- Questions about existing theming infrastructure.
+- Questions about persistence (per-user, per-device, system-default).
+- Updates to relevant docs.
+
+**Hard stop**: the architect halts and asks:
+
+> Prototype, or skip to PRD?
+
+Answer one or the other. For this example:
+
+```
+Prototype.
+```
+
+## Phase 3 — prototype handoff (optional)
+
+Because you chose Prototype:
+
+1. Architect summarizes the prototype question, constraints, relevant
+   context, and the decision the prototype is meant to settle.
+2. Architect calls `switch_mode` to `code-tweaker` **in the same task
+   window**.
+3. Tweaker executes `/prototype` per the command protocol.
+4. Tweaker calls `switch_mode` back to `system-architect` with the
+   prototype result, run command or URL if any, and the decision needed.
+
+**Hard stop**: architect halts and asks for your verdict on the
+prototype.
+
+This is the phase that breaks most often if the architect skips the
+`switch_mode`. See
+[`docs/troubleshooting.md`](../docs/troubleshooting.md#prototype-running-in-the-wrong-mode).
+
+## Phase 4 — PRD
+
+The architect runs `to-prd`, summarizing the prior phases in three
+bullets and producing a PRD draft.
+
+**Hard stop**: "Ready to slice into issues?"
+
+Answer:
+
+```
+Yes.
+```
+
+## Phase 5 — slice into issues
+
+The architect runs `to-issues`, producing a list of well-scoped issues.
+
+**Hard stop**: wait for your approval of the issue list. Edit, drop,
+or merge issues here. Once approved, the chain continues.
+
+## Phase 6 — implement
+
+The architect summarizes the approved issues and `switch_mode`s to
+`code-tweaker`. The tweaker, for each issue:
+
+1. Runs `/tdd` per the command protocol.
+2. Implements the issue.
+3. After each issue ships, suggests `/commit-and-document`.
+
+The orchestrator does not auto-launch `/commit-and-document`. You run
+it explicitly when you want the commit.
+
+## Phase 7 — return
+
+When the chain completes (or hits a blocker), the active mode calls
+`attempt_completion`. The orchestrator summarizes and halts.
+
+## Pass criteria
+
+- [ ] Orchestrator delegated to `system-architect`.
+- [ ] Architect halted after sharpening, asked for Prototype or PRD.
+- [ ] If you picked Prototype, the architect used `switch_mode` to
+      hand off; the architect did not run the prototype itself.
+- [ ] Architect did not edit application source code at any point.
+- [ ] Architect halted before producing the PRD, after the PRD, and
+      after the issue list.
+- [ ] Tweaker ran `/tdd` per issue, not freeform implementation.
+- [ ] Tweaker did not commit without explicit approval.
+
+## Why this chain has so many stops
+
+Each hard stop is a place where the cheapest fix is "your input,
+right now". A wrong sharpening assumption is cheap to correct in
+phase 2, expensive after a PRD, and very expensive after an issue
+slice. The hard stops are not friction — they are the design.

package/examples/fix-flow.md

@@ -0,0 +1,139 @@
+# Example: `/fix` flow
+
+A worked example of the multi-phase `/fix` chain: orchestrator delegates
+to the architect, architect diagnoses, architect switches to the tweaker
+to implement, tweaker switches back, architect runs the post-mortem,
+tweaker prepares the commit. The whole flow has explicit HITL stops.
+
+## Setup
+
+- Active mode: `🪃 Custom Orchestrator`.
+- Workspace has a real bug to fix. For this example, assume:
+
+  > "The login button does nothing on the second click. First click
+  > works."
+
+## Phase 1 — orchestrator routes
+
+Type:
+
+```
+/fix The login button does nothing on the second click. First click works.
+```
+
+**Expected**
+
+Orchestrator looks up the routing matrix and delegates with `new_task`
+targeting `system-architect`. The delegated message includes the
+slash form, user context, proceed policy, command-protocol pointer,
+skills location, and the completion rule.
+
+## Phase 2 — architect diagnoses
+
+The new task window opens in `🏗️ System Architect`. The architect:
+
+1. Loads `/fix` per the command protocol.
+2. Runs the `diagnose` skill, phases 1–3.
+3. Produces a short list of hypotheses.
+4. **Halts** and asks you to pick one.
+
+**Expected message (paraphrased)**
+
+> Hypotheses:
+> 1. Click handler is wired once and never re-bound after a state change.
+> 2. The button enters a disabled state on first click and never resets.
+> 3. A queued network request is canceling the second click's handler.
+>
+> Which would you like to instrument? (1 / 2 / 3)
+
+You answer:
+
+```
+2
+```
+
+## Phase 3 — architect instruments
+
+The architect runs phase 4 of the `diagnose` skill on hypothesis 2.
+This phase may involve reading state-management code, adding a
+console-log or instrumentation suggestion (Markdown only — the architect
+cannot edit source), and producing a confirmed root cause.
+
+**Expected**
+
+> Root cause confirmed: `LoginButton` sets `disabled` on the first
+> click and the `onSuccess` handler does not reset it. The second
+> click is being absorbed by the disabled state.
+
+The architect summarizes the proposed fix and prepares to hand off.
+
+## Phase 4 — architect switches to tweaker
+
+The architect calls `switch_mode` to `code-tweaker` **inside the same
+task window** with a summary of:
+
+- The root cause.
+- The proposed fix (`onSuccess` resets `disabled`).
+- The files involved.
+- The tests to add or extend.
+
+The tweaker takes over without losing context.
+
+## Phase 5 — tweaker implements
+
+The tweaker:
+
+1. Edits the `LoginButton` component to reset `disabled` on success
+   and on error.
+2. Adds or extends tests covering the second-click case.
+3. Runs the test suite.
+4. Reports back.
+
+**HITL stop**: the tweaker does not commit. Per the git rule, it waits
+for your approval.
+
+## Phase 6 — back to architect for post-mortem
+
+The tweaker calls `switch_mode` back to `system-architect`. The
+architect runs phase 6 of `diagnose` (post-mortem):
+
+- What was the original assumption that masked the bug?
+- Is this an isolated mistake or a pattern?
+- If a pattern, would `/refactor` help?
+
+The architect produces a short post-mortem note in `docs/` or
+`.scratch/` (Markdown only) and either drops the matter there or
+suggests `/refactor`.
+
+## Phase 7 — tweaker prepares the commit
+
+The architect switches back to the tweaker. The tweaker suggests
+`/commit-and-document`. **The orchestrator does not auto-launch it.**
+That command runs only when you type it.
+
+## Phase 8 — return to orchestrator
+
+When the chain is complete (or blocked), the active mode calls
+`attempt_completion`. The orchestrator summarizes for you and halts.
+
+## Pass criteria
+
+- [ ] Orchestrator delegated to `system-architect`, not the tweaker.
+- [ ] Architect halted after phase 3 hypotheses, did not instrument
+      until you picked one.
+- [ ] Architect did not edit source code at any point.
+- [ ] Architect used `switch_mode` (same window) to hand off, not
+      `new_task`.
+- [ ] Tweaker did not run `git commit` or `git push` without your
+      explicit approval.
+- [ ] After return, orchestrator halted instead of auto-launching
+      `/commit-and-document`.
+
+## Common slips
+
+- Architect tries to edit source: see
+  [`docs/troubleshooting.md`](../docs/troubleshooting.md#architect-trying-to-edit-source).
+- Tweaker commits without approval: tighten the git rule in the
+  tweaker's `customInstructions`.
+- Orchestrator launches `/commit-and-document` automatically: see
+  [`docs/troubleshooting.md`](../docs/troubleshooting.md#slash-command-leakage-from-subtask-summaries).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fernado03/zoo-flow",
-  "version": "0.11.3",
+  "version": "0.12.1",
   "description": "Structured workflow templates for AI coding assistants",
   "type": "module",
   "bin": {
@@ -10,7 +10,10 @@
     "bin/",
     "templates/",
     "scripts/",
-    "tests/"
+    "tests/",
+    "docs/",
+    "examples/",
+    "LICENSE"
   ],
   "keywords": [
     "ai",

package/scripts/check-package-links.js

@@ -12,7 +12,7 @@ const packageJsonPath = path.join(packageRoot, "package.json");
 
 const failures = [];
 const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
-const files = Array.isArray(packageJson.files) ? packageJson.files : [];
+const files = Array.isArray(packageJson.files) ? packageJson.files.map((f) => f.replace(/\/$/, "")) : [];
 const forbidden = [".git", "node_modules", ".scratch", ".zoo-flow-backup", "*.tgz"];
 
 for (const entry of files) {

package/scripts/eval-routing.js

@@ -105,7 +105,7 @@ if (!fs.existsSync(casesPath)) {
         fail(lineNumber, "expected_command must start with /");
       } else {
         const commandName = record.expected_command.slice(1);
-        const commandPath = path.join(templateRoot, ".roo", "commands", `${commandName}.md`);
+        const commandPath = path.join(templateRoot, ".roo", "commands", `zoo-${commandName}.md`);
         if (!fs.existsSync(commandPath)) {
           fail(lineNumber, `missing command file for ${record.expected_command}`);
         } else {

package/scripts/score-quality.js

@@ -37,7 +37,7 @@ function check(condition, description, category) {
     const files = fs.readdirSync(commandsDir).filter((f) => f.endsWith(".md"));
     for (const file of files) {
       const text = fs.readFileSync(path.join(commandsDir, file), "utf8");
-      const isModeless = file === "caveman.md";
+      const isModeless = file === "zoo-caveman.md";
       r.total++;
       if (isModeless) {
         r.pass++; // modeless by design, not a failure
@@ -183,7 +183,7 @@ function check(condition, description, category) {
 (function () {
   const r = { pass: 0, total: 0 };
 
-  const verifyCmd = path.join(templateRoot, ".roo", "commands", "verify.md");
+  const verifyCmd = path.join(templateRoot, ".roo", "commands", "zoo-verify.md");
   r.total++;
   r.pass += check(fs.existsSync(verifyCmd), "verify command exists", "verification") ? 1 : 0;
 
@@ -209,7 +209,7 @@ function check(condition, description, category) {
 (function () {
   const r = { pass: 0, total: 0 };
 
-  const reviewCmd = path.join(templateRoot, ".roo", "commands", "review.md");
+  const reviewCmd = path.join(templateRoot, ".roo", "commands", "zoo-review.md");
   r.total++;
   r.pass += check(fs.existsSync(reviewCmd), "review command exists", "review_process") ? 1 : 0;
 

package/scripts/test-doctor.js

@@ -42,21 +42,21 @@ function mutate(root, mutation) {
   if (mutation === "missing-roomodes") {
     fs.rmSync(path.join(root, ".roomodes"));
   } else if (mutation === "missing-command") {
-    fs.rmSync(command("review.md"));
+    fs.rmSync(command("zoo-review.md"));
   } else if (mutation === "missing-skill") {
     fs.rmSync(skill("engineering", "tweak", "SKILL.md"));
   } else if (mutation === "bad-skill-wrapper") {
-    replaceInFile(command("caveman.md"), "Skill:", "Run skill:");
+    replaceInFile(command("zoo-caveman.md"), "Skill:", "Run skill:");
   } else if (mutation === "bad-mode-slug") {
-    replaceInFile(command("review.md"), "mode: system-architect", "mode: architect");
+    replaceInFile(command("zoo-review.md"), "mode: system-architect", "mode: architect");
   } else if (mutation === "bad-built-in-delegation") {
     fs.appendFileSync(path.join(root, ".roo", "rules-custom-orchestrator", "00-routing.md"), "\nUse new_task to architect for review.\n");
   } else if (mutation === "bad-zoo-path") {
     fs.appendFileSync(path.join(root, ".roo", "rules", "00-paths.md"), "\nBad path: .zoo/commands/example.md\n");
   } else if (mutation === "helper-missing-mode") {
-    replaceInFile(command("diagnose.md"), /^mode: system-architect\r?\n/m, "");
+    replaceInFile(command("zoo-diagnose.md"), /^mode: system-architect\r?\n/m, "");
   } else if (mutation === "helper-not-permitted") {
-    replaceInFile(path.join(root, ".roomodes"), "/diagnose, ", "");
+    replaceInFile(path.join(root, ".roomodes"), "/zoo-diagnose, ", "");
   } else {
     throw new Error(`Unknown mutation: ${mutation}`);
   }

package/templates/full/.roo/commands/{explore.md → zoo-explore.md}

@@ -1,18 +1,18 @@
----
-description: "Explore unfamiliar code before /feature, /refactor, or /fix. Produces written map."
-argument-hint: <feature or folder to map>
-mode: system-architect
----
-
-Explore unfamiliar code and produce a written map. Follow the skill exactly.
-
-Skill: `.roo/skills/engineering/zoom-out/SKILL.md`
-
-EXECUTION RULES:
-1. READ `.zoo-flow/CONTEXT.md`. If it does not exist, output one line before step 2: "No CONTEXT.md found. Run /scaffold-context to fill, or continue without." Do not invent content.
-2. OUTPUT MAP: Create markdown with sections: Domain language, Modules, Data flow, Seams/callers, ADRs, Open questions. Derive slug from the target area (e.g. "auth module" → `auth-module.md`). Write to `.scratch/explorations/<YYYY-MM-DD>/<slug>.md`.
-3. WRITE POINTER: Write the exact file path to `.scratch/LAST-EXPLORATION.md` so next commands can find it.
-4. NEXT STEPS: Suggest `/scaffold-context`, `/feature`, `/refactor`, or `/fix`. DO NOT auto-launch.
-5. COMPLETION: Call `attempt_completion` with the exact file path, status, and recommended next command. Do NOT use `ask_followup_question` or write results as plain text.
-
-$ARGUMENTS
+---
+description: "Explore unfamiliar code before /feature, /refactor, or /fix. Produces written map."
+argument-hint: <feature or folder to map>
+mode: system-architect
+---
+
+Explore unfamiliar code and produce a written map. Follow the skill exactly.
+
+Skill: `.roo/skills/engineering/zoom-out/SKILL.md`
+
+EXECUTION RULES:
+1. READ `.zoo-flow/CONTEXT.md`. If it does not exist, output one line before step 2: "No CONTEXT.md found. Run /scaffold-context to fill, or continue without." Do not invent content.
+2. OUTPUT MAP: Create markdown with sections: Domain language, Modules, Data flow, Seams/callers, ADRs, Open questions. Derive slug from the target area (e.g. "auth module" → `auth-module.md`). Write to `.scratch/explorations/<YYYY-MM-DD>/<slug>.md`.
+3. WRITE POINTER: Write the exact file path to `.scratch/LAST-EXPLORATION.md` so next commands can find it.
+4. NEXT STEPS: Suggest `/scaffold-context`, `/feature`, `/refactor`, or `/fix`. DO NOT auto-launch.
+5. COMPLETION: Call `attempt_completion` with the exact file path, status, and recommended next command. Do NOT use `ask_followup_question` or write results as plain text.
+
+$ARGUMENTS

package/templates/full/.roo/commands/{scaffold-context.md → zoo-scaffold-context.md}

@@ -1,16 +1,16 @@
----
-description: "Bootstrap .zoo-flow/CONTEXT.md (and 0-2 starter ADRs) for an existing project by scanning code for domain terms and cross-cutting decisions. Shows proposed entries inline and asks for confirm before writing. Use when starting Zoo Flow on a project with no CONTEXT.md, or to expand a thin one."
-argument-hint: <optional focus area, e.g. "auth", "billing", or empty for whole project>
-mode: code-tweaker
----
-
-Bootstrap .zoo-flow/CONTEXT.md for an existing project. Follow the skill exactly.
-
-Skill: `.roo/skills/engineering/scaffold-context/SKILL.md`
-
-EXECUTION RULES:
-1. APPLY the slot discovery rule from `.roo/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md` to find current CONTEXT.md, ADRs.
-2. IF `.zoo-flow/CONTEXT.md` exists and is non-empty, ASK: skip / merge (default) / replace. Skip = do nothing. Merge = add only new terms, never overwrite. Replace = full rewrite from scan.
-3. DO NOT auto-launch any follow-up commands.
-
-$ARGUMENTS
+---
+description: "Bootstrap .zoo-flow/CONTEXT.md (and 0-2 starter ADRs) for an existing project by scanning code for domain terms and cross-cutting decisions. Shows proposed entries inline and asks for confirm before writing. Use when starting Zoo Flow on a project with no CONTEXT.md, or to expand a thin one."
+argument-hint: <optional focus area, e.g. "auth", "billing", or empty for whole project>
+mode: code-tweaker
+---
+
+Bootstrap .zoo-flow/CONTEXT.md for an existing project. Follow the skill exactly.
+
+Skill: `.roo/skills/engineering/scaffold-context/SKILL.md`
+
+EXECUTION RULES:
+1. APPLY the slot discovery rule from `.roo/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md` to find current CONTEXT.md, ADRs.
+2. IF `.zoo-flow/CONTEXT.md` exists and is non-empty, ASK: skip / merge (default) / replace. Skip = do nothing. Merge = add only new terms, never overwrite. Replace = full rewrite from scan.
+3. DO NOT auto-launch any follow-up commands.
+
+$ARGUMENTS

package/templates/full/.roo/commands/{setup-matt-pocock-skills.md → zoo-setup-matt-pocock-skills.md}

@@ -1,8 +1,8 @@
----
-description: "Sets up an `## Agent skills` block in AGENTS.md/CLAUDE.md and `docs/agents/` so the engineering skills know this repo's issue tracker (GitHub or local markdown), triage label vocabulary, and domain doc layout. Run before first use of `to-issues`, `to-prd`, or `triage` — or if those skills appear to be missing issue tracker, triage label, or domain-doc configuration."
-mode: code-tweaker
----
-
+---
+description: "Sets up an `## Agent skills` block in AGENTS.md/CLAUDE.md and `docs/agents/` so the engineering skills know this repo's issue tracker (GitHub or local markdown), triage label vocabulary, and domain doc layout. Run before first use of `to-issues`, `to-prd`, or `triage` — or if those skills appear to be missing issue tracker, triage label, or domain-doc configuration."
+mode: code-tweaker
+---
+
 Skill: `.roo/skills/engineering/setup-matt-pocock-skills/SKILL.md`
-
-$ARGUMENTS
+
+$ARGUMENTS

package/templates/full/.roo/commands/{update-docs.md → zoo-update-docs.md}

@@ -1,22 +1,22 @@
----
-description: "Update repo documentation so it matches the current code."
-argument-hint: <doc or area to update>
-mode: code-tweaker
----
-
-Update repo documentation so it matches the current code. Surgical edits only — read existing docs first, verify claims against code, never rewrite wholesale unless the existing doc is unsalvageable. Follow the skill exactly.
-
-Skill: `.roo/skills/engineering/update-docs/SKILL.md`
-
-Find the target doc in `.zoo-flow/` or `docs/`. If it does not exist, ask once: "No <doc> found. Create a stub at .zoo-flow/<doc>? (yes / pick-existing / skip)".
-
-Do NOT use this for:
-
-- Domain glossary terms — use `/grill-with-docs`
-- ADRs — use `/grill-with-docs` or `/refactor`
-- Local commit journal entries — use `/commit-and-document`
-- Read-only understanding — use `/explore`
-
-If `$ARGUMENTS` is empty, ask once: "Which documentation file or area should I update?"
-
-$ARGUMENTS
+---
+description: "Update repo documentation so it matches the current code."
+argument-hint: <doc or area to update>
+mode: code-tweaker
+---
+
+Update repo documentation so it matches the current code. Surgical edits only — read existing docs first, verify claims against code, never rewrite wholesale unless the existing doc is unsalvageable. Follow the skill exactly.
+
+Skill: `.roo/skills/engineering/update-docs/SKILL.md`
+
+Find the target doc in `.zoo-flow/` or `docs/`. If it does not exist, ask once: "No <doc> found. Create a stub at .zoo-flow/<doc>? (yes / pick-existing / skip)".
+
+Do NOT use this for:
+
+- Domain glossary terms — use `/grill-with-docs`
+- ADRs — use `/grill-with-docs` or `/refactor`
+- Local commit journal entries — use `/commit-and-document`
+- Read-only understanding — use `/explore`
+
+If `$ARGUMENTS` is empty, ask once: "Which documentation file or area should I update?"
+
+$ARGUMENTS

package/templates/full/.roo/rules-custom-orchestrator/00-routing.md

@@ -44,25 +44,25 @@ Slash commands are internal routing labels unless the user explicitly typed one
 
 ## Routed commands
 
-| Workflow             | Command                | Mode             |
-| -------------------- | ---------------------- | ---------------- |
-| small implementation | `/tweak`               | code-tweaker     |
-| test-first           | `/tdd`                 | code-tweaker     |
-| documentation update | `/update-docs`         | code-tweaker     |
-| commit and journal   | `/commit-and-document` | code-tweaker     |
-| prototype            | `/prototype`           | code-tweaker     |
-| context scaffolding  | `/scaffold-context`    | code-tweaker     |
-| diagnosis            | `/fix`                 | system-architect |
-| feature planning     | `/feature`             | system-architect |
-| refactor planning    | `/refactor`            | system-architect |
-| exploration          | `/explore`             | system-architect |
-| issue triage         | `/triage`              | system-architect |
-| review               | `/review`              | system-architect |
-| verification         | `/verify`              | code-tweaker     |
+| Workflow             | Command                 | Mode             |
+| -------------------- | ----------------------- | ---------------- |
+| small implementation | `/zoo-tweak`            | code-tweaker     |
+| test-first           | `/zoo-tdd`              | code-tweaker     |
+| documentation update | `/zoo-update-docs`      | code-tweaker     |
+| commit and journal   | `/zoo-commit-and-document` | code-tweaker  |
+| prototype            | `/zoo-prototype`        | code-tweaker     |
+| context scaffolding  | `/zoo-scaffold-context` | code-tweaker     |
+| diagnosis            | `/zoo-fix`              | system-architect |
+| feature planning     | `/zoo-feature`          | system-architect |
+| refactor planning    | `/zoo-refactor`         | system-architect |
+| exploration          | `/zoo-explore`          | system-architect |
+| issue triage         | `/zoo-triage`           | system-architect |
+| review               | `/zoo-review`           | system-architect |
+| verification         | `/zoo-verify`           | code-tweaker     |
 
 ## Routing decision guide
 
-Read intent, not keywords. Top-down: 1. unknown code area or unclear next move → exploration; 2. broken behavior with unknown cause → diagnosis; 3. new capability needing design, PRD, issue slicing, or phase gates → feature planning; 4. working behavior but structure is the problem → refactor planning; 5. small known low-risk change → small implementation; 6. clear behavior and interface, user wants tests first → test-first; 7. throwaway design/state/UI uncertainty → prototype; 8. docs drift from code → documentation update; 9. finished work needs commit/journal → commit and journal; 10. issue creation, sorting, labels, or tracker workflow → issue triage; 11. diff, branch, PR, standards, architecture, or pre-commit inspection → review; 12. check if this passes, run tests for this change, verify the branch, or make sure nothing broke → verification.
+Read intent, not keywords. Top-down: 1. unknown code area or unclear next move → `/zoo-explore`; 2. broken behavior with unknown cause → `/zoo-fix`; 3. new capability needing design, PRD, issue slicing, or phase gates → `/zoo-feature`; 4. working behavior but structure is the problem → `/zoo-refactor`; 5. small known low-risk change → `/zoo-tweak`; 6. clear behavior and interface, user wants tests first → `/zoo-tdd`; 7. throwaway design/state/UI uncertainty → `/zoo-prototype`; 8. docs drift from code → `/zoo-update-docs`; 9. finished work needs commit/journal → `/zoo-commit-and-document`; 10. issue creation, sorting, labels, or tracker workflow → `/zoo-triage`; 11. diff, branch, PR, standards, architecture, or pre-commit inspection → `/zoo-review`; 12. check if this passes, run tests for this change, verify the branch, or make sure nothing broke → `/zoo-verify`.
 
 ## Routing weight
 
@@ -78,7 +78,7 @@ Diagnosis vs small implementation: unknown cause → diagnosis; known cause →
 
 ## Confidence and presentation
 
-Explicit slash command from user = approval; route as-is. Clear free-form request = recommend one plain-language workflow plus one safe alternative if useful. Genuine tie = offer numbered plain-language choices. Prefer lighter workflow when safe, but do not skip needed diagnosis, planning, or approval. Follow `.roo/rules/03-manual-reply-protocol.md`: no slash commands, mode names, or executable routing text in selectable options. Good free-form option: 1. Make the small implementation change; 2. Explore the area first. Bad free-form option: 1. `/tweak`; 2. `/explore`.
+Explicit slash command from user = approval; route as-is. Clear free-form request = recommend one plain-language workflow plus one safe alternative if useful. Genuine tie = offer numbered plain-language choices. Prefer lighter workflow when safe, but do not skip needed diagnosis, planning, or approval. Follow `.roo/rules/03-manual-reply-protocol.md`: no slash commands, mode names, or executable routing text in selectable options. Good free-form option: 1. Make the small implementation change; 2. Explore the area first. Bad free-form option: 1. `/zoo-tweak`; 2. `/zoo-explore`.
 
 ## Approval gate
 
@@ -94,8 +94,8 @@ For non-trivial work, suggest the next command chain only after the current comm
 
 Recommended chains:
 
-- test-first → verification → review → commit and journal
-- diagnosis → verification → review → commit and journal
-- refactor planning → verification → review → commit and journal
-- feature planning → verification → review → commit and journal
-- small implementation → verification or review when risk is R3+
+- `/zoo-tdd` → `/zoo-verify` → `/zoo-review` → `/zoo-commit-and-document`
+- `/zoo-fix` → `/zoo-verify` → `/zoo-review` → `/zoo-commit-and-document`
+- `/zoo-refactor` → `/zoo-verify` → `/zoo-review` → `/zoo-commit-and-document`
+- `/zoo-feature` → `/zoo-verify` → `/zoo-review` → `/zoo-commit-and-document`
+- `/zoo-tweak` → `/zoo-verify` or `/zoo-review` when risk is R3+