@fernado03/zoo-flow 0.11.2 → 0.12.0

package/bin/zoo-flow.js

@@ -13,34 +13,34 @@ const claudeCodeTemplateRoot = path.join(packageRoot, "templates", "claude-code"
 
 const COMMAND_POLICY = {
   routed: {
-    "tweak": "code-tweaker",
-    "tdd": "code-tweaker",
-    "update-docs": "code-tweaker",
-    "commit-and-document": "code-tweaker",
-    "prototype": "code-tweaker",
-    "scaffold-context": "code-tweaker",
-    "verify": "code-tweaker",
-    "fix": "system-architect",
-    "feature": "system-architect",
-    "refactor": "system-architect",
-    "explore": "system-architect",
-    "triage": "system-architect",
-    "review": "system-architect"
+    "zoo-tweak": "code-tweaker",
+    "zoo-tdd": "code-tweaker",
+    "zoo-update-docs": "code-tweaker",
+    "zoo-commit-and-document": "code-tweaker",
+    "zoo-prototype": "code-tweaker",
+    "zoo-scaffold-context": "code-tweaker",
+    "zoo-verify": "code-tweaker",
+    "zoo-fix": "system-architect",
+    "zoo-feature": "system-architect",
+    "zoo-refactor": "system-architect",
+    "zoo-explore": "system-architect",
+    "zoo-triage": "system-architect",
+    "zoo-review": "system-architect"
   },
   helpers: {
-    "diagnose": "system-architect",
-    "grill-with-docs": "system-architect",
-    "improve-codebase-architecture": "system-architect",
-    "to-prd": "system-architect",
-    "to-issues": "system-architect",
-    "zoom-out": "system-architect",
-    "handoff": "system-architect",
-    "grill-me": "system-architect",
-    "write-a-skill": "code-tweaker",
-    "setup-matt-pocock-skills": "code-tweaker",
-    "teach": "code-tweaker"
+    "zoo-diagnose": "system-architect",
+    "zoo-grill-with-docs": "system-architect",
+    "zoo-improve-codebase-architecture": "system-architect",
+    "zoo-to-prd": "system-architect",
+    "zoo-to-issues": "system-architect",
+    "zoo-zoom-out": "system-architect",
+    "zoo-handoff": "system-architect",
+    "zoo-grill-me": "system-architect",
+    "zoo-write-a-skill": "code-tweaker",
+    "zoo-setup-matt-pocock-skills": "code-tweaker",
+    "zoo-teach": "code-tweaker"
   },
-  modelessUtilities: ["caveman"]
+  modelessUtilities: ["zoo-caveman"]
 };
 
 const ALLOWED_COMMAND_MODES = new Set(["system-architect", "code-tweaker", "custom-orchestrator"]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fernado03/zoo-flow",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "description": "Structured workflow templates for AI coding assistants",
   "type": "module",
   "bin": {

package/templates/claude-code/.claude/skills/engineering/commit-and-document/SKILL.md

@@ -30,7 +30,8 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 ## Complete
 
-Return completion with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - commit hash
 - files changed
 - documentation updated

package/templates/claude-code/.claude/skills/engineering/diagnose/SKILL.md

@@ -128,7 +128,8 @@ Write `<session-dir>/root-cause.md`:
 
 Write `<session-dir>/diagnosis.md` with full log (hypotheses, instrumentation results, timeline).
 
-Return completion with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - `<session-dir>/root-cause.md` path
 - root cause summary
 - fix applied

package/templates/claude-code/.claude/skills/engineering/explore/SKILL.md

@@ -43,7 +43,7 @@ Look for:
 
 ## 4. Report findings
 
-Return completion with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
 
 - modules/components identified
 - key dependencies and relationships

package/templates/claude-code/.claude/skills/engineering/feature/SKILL.md

@@ -50,7 +50,8 @@ Delegate to implementer profile via `Agent` tool. Implementer executes:
 
 ## 5. Verify and report
 
-Implementer returns completion with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - feature implemented
 - tests status (all passing)
 - recommended next command (typically `/verify` then `/review` then `/commit-and-document`)

package/templates/claude-code/.claude/skills/engineering/fix/SKILL.md

@@ -41,7 +41,8 @@ Delegate to implementer profile via `Agent` tool. Implementer executes:
 
 ## 4. Verify and report
 
-Implementer returns completion with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - root cause identified
 - fix implemented
 - regression test added

package/templates/claude-code/.claude/skills/engineering/grill-with-docs/SKILL.md

@@ -29,7 +29,8 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 ## Complete
 
-Return completion with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - documentation location
 - key findings and insights
 - recommended next command (typically `/feature` or `/refactor` if changes needed)

package/templates/claude-code/.claude/skills/engineering/improve-codebase-architecture/SKILL.md

@@ -33,7 +33,8 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 ## Complete
 
-Return completion with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - architecture proposal location
 - key improvements identified
 - recommended next command (typically `/refactor` to implement changes)

package/templates/claude-code/.claude/skills/engineering/prototype/SKILL.md

@@ -28,7 +28,8 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 ## Complete
 
-Return completion with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - prototype location
 - findings and insights
 - recommendations for next steps (proceed with design, explore alternative, or abandon)

package/templates/claude-code/.claude/skills/engineering/refactor/SKILL.md

@@ -42,7 +42,8 @@ Delegate to implementer profile via `Agent` tool. Implementer executes:
 
 ## 4. Verify and report
 
-Implementer returns completion with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - what was refactored
 - structural improvements achieved
 - tests status (all passing)

package/templates/claude-code/.claude/skills/engineering/review/SKILL.md

@@ -125,7 +125,8 @@ Write `<session-dir>/synthesis.md` with:
 - Prioritized findings by severity
 - Result line: `approve` / `approve with nits` / `changes requested` / `blocked`
 
-Return completion with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - `<session-dir>/synthesis.md` path
 - brief result line (approve / approve with nits / changes requested / blocked)
 - recommended next command

package/templates/claude-code/.claude/skills/engineering/scaffold-context/SKILL.md

@@ -38,7 +38,8 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 ## 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.
+
 - CONTEXT.md location
 - sections added/updated
 - recommended next command (typically `/explore` to deepen understanding, or `/feature`/`/refactor` to start work)

package/templates/claude-code/.claude/skills/engineering/setup-matt-pocock-skills/SKILL.md

@@ -42,7 +42,8 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 ## 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.
+
 - configuration files updated
 - conventions document location
 - recommended next command (typically `/verify` to ensure config is valid)

package/templates/claude-code/.claude/skills/engineering/tdd/SKILL.md

@@ -54,7 +54,8 @@ After green, suggest `/verify`, then `/review`, then `/commit-and-document` 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.
+
 - what was implemented (behaviours, interfaces)
 - tests written (count, pass/fail)
 - status (complete / blocked with reason)

package/templates/claude-code/.claude/skills/engineering/to-issues/SKILL.md

@@ -30,7 +30,8 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 ## Complete
 
-Return completion with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - issues directory location
 - issue count and summary
 - dependency graph

package/templates/claude-code/.claude/skills/engineering/to-prd/SKILL.md

@@ -33,7 +33,8 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 ## Complete
 
-Return completion with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - PRD location
 - summary of requirements
 - recommended next command (typically `/to-issues` to break down into tasks)

package/templates/claude-code/.claude/skills/engineering/triage/SKILL.md

@@ -30,7 +30,8 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 ## Complete
 
-Return completion with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - triage document location
 - prioritized list summary
 - recommended next command (typically `/fix` for bugs, `/feature` for features, or `/refactor` for tech debt)

package/templates/claude-code/.claude/skills/engineering/tweak/SKILL.md

@@ -19,7 +19,8 @@ Use for small known fixes.
 
 ## 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.
+
 - what was changed (file paths, line ranges)
 - status (complete / blocked with reason)
 - recommended next command

package/templates/claude-code/.claude/skills/engineering/update-docs/SKILL.md

@@ -27,7 +27,8 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 ## Complete
 
-Return completion with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - documentation files updated
 - summary of changes
 - recommended next command (typically `/verify` to ensure docs are accurate)

package/templates/claude-code/.claude/skills/engineering/verify/SKILL.md

@@ -32,7 +32,8 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 ## Complete
 
-Return completion with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - verification commands run
 - pass/fail status for each
 - recommended next command (typically `/review` if passed, or `/fix` if failed)

package/templates/claude-code/.claude/skills/engineering/zoom-out/SKILL.md

@@ -68,7 +68,8 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 ## Complete
 
-Return completion with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - `<session-dir>/synthesis.md` file path
 - high-level structure summary
 - recommended next command (typically `/explore` for deeper dive, or `/feature`/`/refactor` if changes needed)

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/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+