@fernado03/zoo-flow 0.3.0 → 0.3.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fernado03/zoo-flow",
   "description": "Workflow control plane for Zoo Code.",
-  "version": "0.3.0",
+  "version": "0.3.4",
   "type": "module",
   "bin": {
     "zoo-flow": "bin/zoo-flow.js"

package/templates/full/.roo/commands/feature.md

@@ -4,6 +4,7 @@ argument-hint: <describe the feature>
 mode: system-architect
 ---
 EXECUTION RULES (Run sequentially. Wait for user between phases):
+0. TRACK: At start, write a phase checklist to `.scratch/feature-<slug>.md` (phases 1-5, each unchecked). Before any `switch_mode` or `attempt_completion`, update it. Do NOT `attempt_completion` while any phase is unchecked — `switch_mode` to the phase's owner instead.
 1. SHARPEN (Architect): Run skill `.roo/skills/engineering/grill-with-docs/SKILL.md`. Update docs.
    HARD STOP: Ask user to choose: Prototype OR skip to PRD.
 2. PROTOTYPE [Optional]: Follow `.roo/rules-system-architect/01-feature-prototype.md` for the architect→tweaker handoff.

package/templates/full/.roo/commands/fix.md

@@ -4,6 +4,7 @@ argument-hint: <describe the bug or error>
 mode: system-architect
 ---
 EXECUTION RULES:
+0. TRACK: At start, write a phase checklist to `.scratch/fix-<slug>.md` (phases 1-5, each unchecked). Before any `switch_mode` or `attempt_completion`, update it. Do NOT `attempt_completion` while any phase is unchecked — `switch_mode` to the phase's owner instead.
 1. DIAGNOSE (Architect): Run skill `.roo/skills/engineering/diagnose/SKILL.md`. Run phases 1-3.
    HARD STOP: Present hypotheses. Wait for user selection. Ignore internal AFK rules.
 2. INSTRUMENT (Architect): Run phase 4 on chosen hypothesis. Find root cause.

package/templates/full/.roo/commands/refactor.md

@@ -4,6 +4,7 @@ argument-hint: <area to refactor>
 mode: system-architect
 ---
 EXECUTION RULES:
+0. TRACK: At start, write a phase checklist to `.scratch/refactor-<slug>.md` (phases 1-3, each unchecked). Before any `switch_mode` or `attempt_completion`, update it. Do NOT `attempt_completion` while any phase is unchecked — `switch_mode` to the phase's owner instead.
 1. FIND (Architect): Run skill `.roo/skills/engineering/improve-codebase-architecture/SKILL.md`. List candidates.
    HARD STOP: Ask user which candidate to explore.
 2. GRILL (Architect): Run grilling loop. Update CONTEXT/ADRs inline.

package/templates/full/.roo/commands/triage.md

@@ -1,5 +1,6 @@
 ---
 description: "Triage issues through a state machine driven by triage roles. Use when user wants to create an issue, triage issues, review incoming bugs or feature requests, prepare issues for an AFK agent, or manage issue workflow."
+mode: system-architect
 ---
 
 Run skill: `.roo/skills/engineering/triage/SKILL.md`

package/templates/full/.roo/rules/05-mcp-awareness.md

@@ -0,0 +1,7 @@
+# MCP Awareness
+
+If MCP tools are available, prefer them when they match the task better than built-in tools.
+
+Do not assume specific MCP servers exist. Check what is available before attempting a call.
+
+If no MCP servers are configured, ignore this rule.

package/templates/full/.roo/rules/06-tool-parameter-safety.md

@@ -0,0 +1,16 @@
+# Tool Parameter Safety
+
+All required parameters must be present in every tool call. Never invoke a tool with missing or empty required fields.
+
+## On rejection
+
+After a missing-parameter or schema error:
+
+1. Do **not** retry unchanged — that counts toward the three-failure cap (`02-three-failure-rule.md`).
+2. Either supply the missing value in the next call, or surface the blocker to the user.
+
+## Write-tool guard (`write_to_file`, `apply_diff`, etc.)
+
+- Compose the full content **before** calling the tool.
+- If content exceeds ~150 lines, split: first `write_to_file` (initial chunk), then `append_to_file` for the rest.
+- If splitting is impractical, output the content in the response body and ask the user to confirm or save.

package/templates/full/.roo/rules-code-tweaker/01-completion.md

@@ -1,8 +1,17 @@
 # Code Tweaker Completion
 
-If created by `custom-orchestrator` via `new_task`, use `attempt_completion` when done or blocked.
+A delegated task is the **entire command chain**, including every phase and mode switch the command body defines — not the single phase you are currently running.
 
-Include:
+Choose your exit by where you are in that chain:
+
+- **More phases remain** (a later phase is assigned to `system-architect`, e.g. post-mortem, or control returns to it): use `switch_mode` back to `system-architect`. Never `attempt_completion` mid-chain.
+- **You are running the command's final phase** and it is complete or blocked: use `attempt_completion` to return to the orchestrator.
+
+If you entered this window via `switch_mode` (you are mid-chain, not the entry point) and any phase remains, you hand back with `switch_mode`. Only the command's final phase returns to the orchestrator.
+
+Before any `attempt_completion`, re-read the command body and confirm no later phase is assigned to another mode. If one is, `switch_mode` instead.
+
+`attempt_completion` must include:
 
 - what was done
 - files changed or inspected

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

@@ -4,13 +4,76 @@ The orchestrator is a router only.
 
 Do not inspect implementation files, edit files, run shell commands, or answer technical implementation questions directly.
 
-If the user gives a technical request without an explicit command, offer 1-2 numbered workflow choices and ask for a typed number.
-
-Delegate only with `new_task` to:
+Delegate only with `new_task` to these exact slugs:
 
 - `code-tweaker`
 - `system-architect`
 
-When delegating, choose the safest proceed policy from `01-delegation-message.md`.
+The planning/architecture mode slug is always `system-architect`. Never use `architect`.
 
 After a subtask returns, summarize and stop. Do not auto-launch another subtask.
+
+## Routed commands
+
+| Command                | Mode             | Routed when the user wants to…                                        |
+| ---------------------- | ---------------- | --------------------------------------------------------------------- |
+| `/tweak`               | code-tweaker     | Make a small, known, low-risk change. Cause is understood.            |
+| `/tdd`                 | code-tweaker     | Build a unit of behavior test-first, red-green-refactor.              |
+| `/update-docs`         | code-tweaker     | Align existing docs with current code.                                |
+| `/commit-and-document` | code-tweaker     | Stage, write a Conventional Commit, journal the change.               |
+| `/prototype`           | code-tweaker     | Throw away code to resolve a design uncertainty.                      |
+| `/fix`                 | system-architect | Resolve a bug whose cause is unknown. Diagnose → fix → post-mortem.   |
+| `/feature`             | system-architect | Add new capability needing planning. Sharpen → PRD → slice → build.   |
+| `/refactor`            | system-architect | Improve working code's structure without changing behavior.          |
+| `/explore`             | system-architect | Map unfamiliar code before deciding what to do.                       |
+| `/triage`              | system-architect | Create, sort, or prepare issues in a tracker.                         |
+
+## Routing decision guide
+
+Read the request for intent, not keywords. Work top-down:
+
+1. **Unfamiliar territory?** User is unsure where the code lives, how it works, or what the right move is → `/explore` first. It produces a written map and recommends the next command.
+2. **Something is broken and the cause is unknown?** Error, crash, regression, "it used to work", flaky, slow → `/fix`. The diagnosis loop lives inside it.
+3. **New capability that needs planning?** Net-new behavior, multiple unknowns, or design questions → `/feature`.
+4. **Working code, structure is the problem?** "Clean up", "decouple", "this is getting hard to change", no behavior change intended → `/refactor`.
+5. **Small and well-understood?** Cause known, scope tight, no design questions → `/tweak`.
+6. **Test-first unit of behavior, cause/interface clear?** → `/tdd`.
+7. **Design uncertainty worth throwing code at?** → `/prototype`.
+8. **Docs drifted from code?** → `/update-docs`.
+9. **Ready to record finished work?** → `/commit-and-document`.
+10. **Issue/tracker management?** → `/triage`.
+
+## Disambiguation
+
+These pairs overlap. Choose by the distinguishing signal, not surface wording.
+
+- `/fix` vs `/tweak`: unknown cause needing diagnosis → `/fix`. Known cause, mechanical change → `/tweak`. If the user can name the exact line/function to change, it is `/tweak`.
+- `/fix` vs `/refactor`: behavior is wrong → `/fix`. Behavior is fine, structure hurts → `/refactor`.
+- `/feature` vs `/tdd`: needs sharpening, a PRD, or issue slicing → `/feature`. Interface and scope already clear, just build it test-first → `/tdd`.
+- `/feature` vs `/prototype`: committing to a real implementation → `/feature`. Resolving an open design question with throwaway code → `/prototype`.
+- `/refactor` vs `/tweak`: cross-cutting structural change with design tradeoffs → `/refactor`. One-spot localized edit → `/tweak`.
+- `/update-docs` vs `/commit-and-document`: aligning doc content with code → `/update-docs`. Recording a change you just made (commit + journal) → `/commit-and-document`.
+- Any of the above when the target area is unknown: route `/explore` first.
+
+## Confidence and presentation
+
+- If the user typed an explicit slash command, route it as-is. Do not second-guess it.
+- If one command clearly fits a free-form request, offer it as the single top choice with a one-line reason, plus one safe alternative when a near-tie exists.
+- If two commands genuinely tie, offer both as numbered choices and let the user pick.
+- Prefer the lighter-weight workflow when impact is comparable (`/tweak` over `/fix`, `/tdd` over `/feature`) — but never trade away a needed diagnosis or planning phase just to save tokens.
+- When suggesting choices, follow `.roo/rules/03-manual-reply-protocol.md`: plain-language numbered options, no slash commands or mode names in the suggestion text.
+
+## Approval gate
+
+The orchestrator proposes; the user approves; only then does the orchestrator delegate.
+
+- An explicitly typed slash command is itself the approval. Route it immediately.
+- A free-form request is never self-approving. Present the proposed workflow (single top choice or numbered options), then **stop and wait** for the user to pick. Do not call `new_task` on the same turn you propose a workflow.
+- Treat a free-form message as approval only when it selects a workflow you already proposed — by number, option text, or an unambiguous restatement. A fresh free-form request restarts the propose-and-wait cycle.
+- If you are unsure whether the user approved, ask. Never assume approval from silence, enthusiasm, or a restated problem description.
+
+## Delegation
+
+Delegate only after the approval gate is satisfied: the user typed an explicit slash command, or selected a workflow you proposed.
+
+When delegating, choose the safest proceed policy from `01-delegation-message.md`.

package/templates/full/.roo/rules-custom-orchestrator/01-delegation-message.md

@@ -1,5 +1,7 @@
 # Delegation Message
 
+A delegated task is the **entire command chain** — every phase and mode switch the command body defines, run to its final phase. A worker returns via `attempt_completion` only after that final phase. Mid-chain handoffs between modes use `switch_mode`, not `attempt_completion`.
+
 Every delegated task must include:
 
 - command with slash

package/templates/full/.roo/rules-system-architect/02-completion.md

@@ -1,8 +1,15 @@
 # System Architect Completion
 
-Use `switch_mode` to `code-tweaker` for same-window implementation handoffs.
+A delegated task is the **entire command chain**, including every phase and every mode switch the command body defines — not the single phase you are currently running.
 
-If created by `custom-orchestrator` via `new_task`, use `attempt_completion` when the delegated task is complete or blocked.
+Choose your exit by where you are in that chain:
+
+- **More phases remain** (this or a later phase is assigned to `code-tweaker`, or control returns to you afterward): use `switch_mode`. Never `attempt_completion`. Writing a plan, diagnosis, or `.scratch/` notes is not "done" — it is a handoff. Switch to `code-tweaker` to implement.
+- **You are running the command's final phase** and it is complete or blocked: use `attempt_completion` to return to the orchestrator.
+
+If you entered this window via `switch_mode` (you are mid-chain, not the entry point) and any phase remains, you hand back with `switch_mode`. Only the command's final phase returns to the orchestrator.
+
+Before any `attempt_completion`, re-read the command body and confirm no later phase is assigned to another mode. If one is, `switch_mode` instead.
 
 Do not use `attempt_completion` to avoid required implementation work.
 

package/templates/full/.roo/skills/engineering/prototype/SKILL.md

@@ -27,11 +27,11 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 ## Rules
 
 1. Mark throwaway clearly.
-2. Place near real module/page.
+2. Place under `.scratch/prototypes/<slug>/` (logic/state/data-model) or near the real module/page (UI). UI prototypes need the real route, data fetching, and auth, so they stay adjacent to the page they mock up; logic prototypes have no such constraint, so they go in `.scratch/` with the other throwaway work.
 3. Follow existing routing/tooling.
 4. Provide one run command.
 5. Default no persistence; state in memory.
-6. Persistence target → scratch DB/file named `PROTOTYPE — wipe me` or equivalent.
+6. Persistence target → scratch DB/file named `PROTOTYPE — wipe me` in the prototype folder.
 7. No polish: no tests, minimal errors, no abstractions.
 8. Surface full relevant state after each action/variant switch.
 9. Done → capture answer in commit/ADR/issue/`NOTES.md`; delete or fold into real code.

package/templates/full/.roo/skills/engineering/to-prd/SKILL.md

@@ -12,12 +12,11 @@ RULE: Do not interview user. Synthesize current context.
 ## Process
 
 1. Explore repo if needed; use glossary; respect ADRs.
-2. Sketch major modules to build/modify.
-3. Find deep modules testable in isolation.
-4. Check with user: modules match expectations? which modules need tests?
-5. Write PRD.
-6. Publish to issue tracker.
-7. Apply `ready-for-agent`.
+2. Sketch test seams. Prefer existing seams; use highest seam possible. Propose new seams at highest point.
+3. Check with user: seams match expectations?
+4. Write PRD.
+5. Publish to issue tracker.
+6. Apply `ready-for-agent`.
 
 ## PRD template
 
@@ -45,7 +44,7 @@ RULE: Do not interview user. Synthesize current context.
 ## Testing Decisions
 
 - Good tests verify external behaviour, not implementation.
-- Modules to test.
+- Seams to test; prefer existing/highest seam.
 - Similar tests/prior art.
 
 ## Out of Scope

package/templates/full/.roo/skills/in-progress/teach/SKILL.md

@@ -40,7 +40,7 @@ User says "I already know X" → record in `learning-records/`.
 ## Knowledge loop
 
 1. Pull from `RESOURCES.md`.
-2. Write HTML explainer to local file. Beautiful, glossary-correct.
+2. Write HTML explainer to local file. Beautiful, glossary-correct. Litter with citations linking external resources backing every claim. Interactive: "try this" callouts to apply the knowledge.
 3. Give one-line CLI command to open it.
 4. Take questions; amend explainer or write a new one.
 5. Once user clearly owns the term, add to `GLOSSARY.md`.

package/templates/full/.roomodes

@@ -40,7 +40,7 @@
       "roleDefinition": "You are a PM and router. You choose workflows and delegate subtasks. You NEVER inspect implementation files, write code, or use switch_mode.",
       "whenToUse": "Use for initial task planning, choosing slash commands, routing work, or discussing workflow.",
       "description": "Router that consults, delegates, and waits for user direction.",
-      "customInstructions": "Use `.roo/rules-custom-orchestrator/` for mode-specific behavior.\n\nRoute only these commands:\n\n- /tweak, /tdd, /update-docs, /commit-and-document, /prototype -> code-tweaker\n- /fix, /feature, /refactor, /explore, /triage -> system-architect\n\nUse `new_task` only. If `new_task` is unavailable, stop and report that orchestrator lacks delegation access.\n\nFollow `.roo/rules/03-manual-reply-protocol.md` when offering workflow choices: use plain-language numbered options, not slash commands or mode names.",
+      "customInstructions": "Use `.roo/rules-custom-orchestrator/` for mode-specific behavior.\n\nRoute only these commands. The exact mode slug to pass to `new_task` is shown after the arrow:\n\n- /tweak, /tdd, /update-docs, /commit-and-document, /prototype -> slug: code-tweaker\n- /fix, /feature, /refactor, /explore, /triage -> slug: system-architect\n\nThe planning/architecture mode slug is ALWAYS `system-architect`. Never use `architect`.\n\nPropose, then wait for approval before delegating. A free-form request is never self-approving: present the workflow and stop. Delegate only after the user types an explicit slash command or picks a workflow you proposed. See `.roo/rules-custom-orchestrator/00-routing.md` (Approval gate).\n\nUse `new_task` only. If `new_task` is unavailable, stop and report that orchestrator lacks delegation access.\n\nFollow `.roo/rules/03-manual-reply-protocol.md` when offering workflow choices: use plain-language numbered options, not slash commands or mode names.",
       "groups": []
     }
   ]