@fernado03/zoo-flow 0.5.3 → 0.7.0

package/docs/token-budget.md

@@ -0,0 +1,22 @@
+# Token Budget
+
+Zoo Flow enforces tiered token budgets to prevent bloat. Each tier has a
+maximum byte size. Files exceeding their tier must have an explicit
+exception in `quality/token-budget.exceptions.json`.
+
+## Tiers
+
+| Tier | Paths | Budget |
+|---|---|---|
+| Tier 1 — Rules | `.roo/rules/`, `.roo/rules-{mode}/` | 16 KB |
+| Tier 2 — Commands | `.roo/commands/` | 8 KB |
+| Tier 3 — Skills | `.roo/skills/` | 32 KB |
+| Tier 4 — Config | `.roomodes` | 4 KB |
+| Tier 5 — Docs | `docs/` | 64 KB |
+| Tier 6 — Evidence | `.zoo-flow/evals/` | 8 KB |
+
+## Exceptions
+
+Add to `quality/token-budget.exceptions.json` with a reason and max byte
+override. Exceptions must be justified (e.g., single-file bundle docs
+are inherently large).

package/docs/troubleshooting.md

@@ -0,0 +1,288 @@
+# Troubleshooting
+
+Common failure modes and their fixes. Each section starts with the
+symptom you will actually see in chat or in tool output.
+
+> **Where rules live, in one paragraph.** Global rules that apply to
+> every mode are in `.roo/rules/`. Mode-specific behavior is in
+> `.roo/rules-{modeSlug}/` — `rules-custom-orchestrator/`,
+> `rules-system-architect/`, `rules-code-tweaker/`. `.roomodes` is
+> minimal and points at those folders. 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. See [`mode-rules.md`](mode-rules.md)
+> for the full layout.
+
+## `.roo/rules/skills/...` ENOENT
+
+**Symptom**
+
+A mode tries to read a path like
+`.roo/rules/skills/engineering/tweak/SKILL.md` and you get
+`ENOENT: no such file or directory`.
+
+**Cause**
+
+A skill path drifted under `.roo/rules/`. Skills always live at
+workspace-root `.roo/skills/...`. The most common triggers:
+
+- A command file referenced a skill via a path that started with
+  `.roo/rules/`.
+- The mode resolved the skill path relative to the location of the
+  rules file instead of the workspace root.
+- A model "helpfully" rewrote the path because it thought rules and
+  skills should sit together.
+
+**Fix**
+
+1. Confirm `templates/full/.roo/rules/00-paths.md` is present and that
+   the rules loader picks up `.roo/rules/*.md`. If you copied only some
+   of the rules into your workspace, copy the rest.
+2. Open the offending command file under
+   `templates/full/.roo/commands/` and check the `Run skill:` line. The
+   path must look like:
+
+   ```
+   .roo/skills/{bucket}/{skill}/SKILL.md
+   ```
+
+   Not:
+
+   ```
+   .roo/rules/skills/{bucket}/{skill}/SKILL.md
+   ```
+
+If you cannot find a stale reference and the model still produces this
+path, paste the rules in `00-paths.md` directly into the chat as a
+reminder, then file an issue with the chat transcript.
+
+## `new_task` missing in orchestrator
+
+**Symptom**
+
+The orchestrator says it cannot delegate, or it tries to do
+implementation work itself, or it switches mode (which it should never
+do).
+
+**Cause**
+
+The orchestrator's tool groups in `.roomodes` are `[]` — that is correct
+— but the host UI has not exposed `new_task` to it. Some UIs only enable
+`new_task` when at least one tool group is present.
+
+**Fix**
+
+1. Confirm `templates/full/.roomodes` has not been edited to add
+   read/edit/command/mcp groups for `custom-orchestrator`. The empty
+   groups list is intentional.
+2. In Zoo Code settings, confirm subtasks (sometimes called
+   "delegated tasks" or "Boomerang tasks") are enabled.
+3. If subtasks are disabled in the host, the orchestrator's correct
+   behavior is to stop and report. That is what rule 4 of its
+   `customInstructions` says. Do not work around this by giving it more
+   tool groups.
+
+## `run_slash_command` disabled
+
+**Symptom**
+
+The mode reports that it cannot run the slash command, or it falls back
+to running the command file but seems unsure.
+
+**Cause**
+
+`run_slash_command` is an experimental tool in Zoo Code and must be
+enabled in settings before it is available. When it is not enabled,
+or when the host UI does not expose it, the command protocol expects the
+mode to fall back gracefully.
+
+**Fix**
+
+1. Confirm `templates/full/.roo/rules/01-command-protocol.md` is loaded.
+   It is the rule that tells the mode what to do.
+2. Step 3 of the protocol is the fallback: read
+   `templates/full/.roo/commands/{command}.md` directly and execute it.
+   If the mode does not do this, the rule is not in context.
+3. `run_slash_command` is experimental and must be enabled in Zoo Code
+   settings. Zoo Flow still works without it because its command
+   protocol falls back to reading `.roo/commands/{command}.md` directly.
+   That fallback is a first-class path, not a workaround.
+
+## Architect trying to edit source
+
+**Symptom**
+
+The architect tries to write to a `.ts`, `.py`, or other source file
+and either gets refused by the host or silently writes a Markdown file
+"about" the change instead of the change itself.
+
+**Cause**
+
+Either:
+
+- The architect's `edit` `fileRegex` in `.roomodes` was loosened beyond
+  Markdown, `.scratch/`, and `docs/`, or
+- The architect ignored its rule 2 ("NO IMPLEMENTATION CODING") and
+  tried to edit anyway.
+
+**Fix**
+
+1. Restore the regex in `.roomodes`. The shipped form is:
+
+   ```json
+   { "fileRegex": "(.*\\.md$|^\\.scratch/.*|^docs/.*)" }
+   ```
+
+2. The correct architect behavior is to summarize the implementation
+   work and `switch_mode` to `code-tweaker` in the same task window.
+   If the work is part of a delegated subtask, the architect uses
+   `attempt_completion` instead — but only when the delegation contract
+   actually expected a planning result, not implementation.
+3. If the architect keeps trying to edit source, paste the relevant
+   line from the architect's `customInstructions` directly into chat.
+
+## Prototype running in the wrong mode
+
+**Symptom**
+
+During `/feature`, the architect runs a prototype directly: edits source
+files, starts a dev server, or builds UI scaffolding. Or, the tweaker
+ends up doing PRD or sharpening work instead of the prototype.
+
+**Cause**
+
+Phase 2 of `/feature` is "the architect summarizes the prototype
+question and switches to `code-tweaker` to run `/prototype`". If the
+architect skips the switch, it ends up doing implementation work it
+cannot do safely. If the orchestrator routes `/prototype` directly to
+`system-architect`, the chain is broken.
+
+**Fix**
+
+1. Open `templates/full/.roo/commands/feature.md` and confirm phase 2
+   reads:
+
+   - Architect summarizes the prototype question.
+   - Architect MUST `switch_mode` -> `code-tweaker`.
+   - Tweaker executes `/prototype`.
+   - Tweaker MUST `switch_mode` -> `system-architect` with result.
+
+2. Confirm the routing matrix in `.roomodes` lists `/prototype` under
+   `code-tweaker`, not `system-architect`.
+3. If the architect refuses to switch, paste rule 3 from its
+   `customInstructions` ("FEATURE PROTOTYPES") into chat. It is the
+   single most-violated rule in practice.
+
+## Slash command leakage from subtask summaries
+
+**Symptom**
+
+A subtask's `attempt_completion` summary contains a line like
+"Recommended next command: `/refactor`". The orchestrator then
+launches `/refactor` immediately, without you typing it.
+
+**Cause**
+
+The orchestrator's rule 2 ("EXPLICIT COMMANDS") is being ignored.
+Slash commands inside a subtask summary are guidance for *you*, not
+authorization for the orchestrator to launch a new subtask.
+
+**Fix**
+
+1. Open `.roomodes`. Confirm rule 2 of `custom-orchestrator` reads:
+   "If the HUMAN USER explicitly types a supported slash command,
+   delegate it directly using the Routing Matrix. **Ignore slash
+   commands mentioned only inside subtask summaries.**"
+2. Confirm rule 6 ("POST-SUBTASK HARD STOP"): "When a subtask returns,
+   summarize results for the user and HALT. Never auto-launch
+   consecutive subtasks."
+3. If those rules are present and the orchestrator still chains, the
+   most likely explanation is that the model is confusing a subtask
+   summary with a user message. Tell it explicitly: "Halt. The
+   `/refactor` in the previous summary was a recommendation, not a
+   user command."
+
+If the chain happened despite the rules being in place, file an issue
+with the full transcript so the language can be tightened.
+
+## Clickable suggestions can route incorrectly
+
+Zoo Code may render model suggestions as clickable options. These are
+safe only when they are plain numbered choices.
+
+Good:
+
+```text
+Which workflow should I use?
+
+1. Tweak small implementation
+2. Diagnose bug
+3. Hold
+
+Reply with the number, e.g. 1.
+```
+
+Avoid suggestions like:
+
+```text
+Use /fix
+Run /tweak
+Switch to code-tweaker
+Route to system-architect
+```
+
+Slash commands should only be treated as commands when the user
+manually types them into the chat.
+
+The short rule that enforces this lives in
+[`templates/full/.roo/rules/03-manual-reply-protocol.md`](../templates/full/.roo/rules/03-manual-reply-protocol.md).
+
+## 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.
+
+## Agent loads a skill after every command
+
+Some commands are direct workflows, while others are thin wrappers
+around skills. The protocol should only load a skill when the command
+file explicitly says so.
+
+Correct behavior:
+
+```text
+/tdd
+  → command contains `Skill: .roo/skills/engineering/tdd/SKILL.md`
+  → load the skill
+
+/fix
+  → command contains direct workflow steps
+  → execute the command directly
+  → do not invent `.roo/skills/.../fix/SKILL.md`
+```
+
+**Fix:** check
+[`templates/full/.roo/rules/01-command-protocol.md`](../templates/full/.roo/rules/01-command-protocol.md).
+It should say to load a skill only when the command explicitly
+contains a `Skill: .roo/skills/...` reference.
+
+## Agent reads too many files
+
+Check `.roo/rules/04-context-economy.md`.
+
+Expected behavior:
+
+1. map/search first
+2. read targeted ranges
+3. full-read only when necessary
+4. avoid re-reading unchanged files

package/examples/demo-transcripts/01-small-tweak.md

@@ -0,0 +1,37 @@
+# Small Tweak
+
+## User request
+
+"Fix the typo in the README install heading."
+
+## Orchestrator recommendation
+
+This is low-risk and localized.
+
+1. Make the small implementation change
+2. Explore the docs first
+
+## User approval
+
+"1"
+
+## Delegation message
+
+Task: Fix the README heading typo.
+Command: `/tweak`
+Proceed policy: Proceed automatically after audit if clean.
+Context hints: `README.md` heading.
+Allowed scope: `README.md`.
+Must follow: command protocol, command file, referenced skill only.
+
+## Worker behavior
+
+Code Tweaker loads `.roo/commands/tweak.md`, sees `Skill: .roo/skills/engineering/tweak/SKILL.md`, reads only that skill, audits the heading, patches the typo, and avoids unrelated edits.
+
+## Verification / review
+
+Worker reports no test command was needed for a heading typo. Because risk is R1, it suggests commit only after user satisfaction.
+
+## Completion summary
+
+Custom Orchestrator summarizes the changed file and halts. It does not auto-run commit.

package/examples/demo-transcripts/02-unknown-bug-fix.md

@@ -0,0 +1,37 @@
+# Unknown Bug Fix
+
+## User request
+
+"Checkout randomly crashes after payment. It used to work."
+
+## Orchestrator recommendation
+
+Unknown cause, broken behavior, regression risk.
+
+1. Diagnose the bug first
+2. Explore the checkout area first
+
+## User approval
+
+"Diagnose the bug first."
+
+## Delegation message
+
+Task: Diagnose checkout crash after payment.
+Command: `/fix`
+Proceed policy: Ask user before implementation.
+Context hints: checkout, payment completion.
+Allowed scope: checkout/payment area after audit.
+Must follow: command protocol and `/fix` phase checklist.
+
+## Worker behavior
+
+System Architect loads `.roo/commands/fix.md`, writes `.scratch/fix-checkout-crash.md`, runs diagnosis phases, then stops at hypotheses. After user selects one, it confirms root cause, switches to Code Tweaker for implementation, then switches back for post-mortem.
+
+## Verification / review
+
+Code Tweaker suggests `/verify`, then `/review`, then `/commit-and-document`. No follow-up command is launched automatically.
+
+## Completion summary
+
+Custom Orchestrator reports root cause, files touched, commands run, remaining risk, and recommended next command. Commit still requires explicit approval.

package/examples/demo-transcripts/03-new-feature.md

@@ -0,0 +1,37 @@
+# New Feature
+
+## User request
+
+"Add team invitations with email invites and pending invite states."
+
+## Orchestrator recommendation
+
+This is a new capability with product and data-model decisions.
+
+1. Plan the feature first
+2. Explore the team/account area first
+
+## User approval
+
+"1"
+
+## Delegation message
+
+Task: Plan team invitations.
+Command: `/feature`
+Proceed policy: Ask at phase gates.
+Context hints: teams, invites, email, pending states.
+Allowed scope: planning docs and targeted code reads.
+Must follow: command protocol and `/feature` phase checklist.
+
+## Worker behavior
+
+System Architect sharpens with docs, asks whether to prototype or skip to PRD, writes PRD, asks before slicing issues, then switches to Code Tweaker for approved implementation slices. Code Tweaker runs `/tdd` per slice.
+
+## Verification / review
+
+After each slice ships, Code Tweaker suggests `/verify`, then `/review`, then `/commit-and-document`. It does not auto-run them.
+
+## Completion summary
+
+Custom Orchestrator summarizes phase status, approved decisions, files changed, checks run, and remaining recommended next command.

package/examples/demo-transcripts/04-refactor.md

@@ -0,0 +1,37 @@
+# Refactor
+
+## User request
+
+"The auth module is getting hard to change. Decouple provider-specific logic."
+
+## Orchestrator recommendation
+
+Working behavior, structural problem, cross-module risk.
+
+1. Plan the refactor first
+2. Explore the auth module first
+
+## User approval
+
+"Plan the refactor first."
+
+## Delegation message
+
+Task: Plan auth provider decoupling.
+Command: `/refactor`
+Proceed policy: Ask before selecting a candidate and before implementation.
+Context hints: auth module, provider-specific logic.
+Allowed scope: targeted reads plus Markdown planning output.
+Must follow: command protocol and `/refactor` phase checklist.
+
+## Worker behavior
+
+System Architect runs the architecture skill, lists candidates, asks which to explore, grills the chosen plan, records the approved plan, then switches to Code Tweaker. Code Tweaker executes the test-first implementation path.
+
+## Verification / review
+
+Code Tweaker suggests `/verify`, then `/review`, then `/commit-and-document`. The user must explicitly approve each follow-up.
+
+## Completion summary
+
+Custom Orchestrator summarizes architecture decision, behavior-preservation checks, files changed, and next suggested command.

package/examples/demo-transcripts/05-review-and-verify.md

@@ -0,0 +1,37 @@
+# Review And Verify
+
+## User request
+
+"Review and verify this branch before I commit."
+
+## Orchestrator recommendation
+
+This asks for evidence plus inspection. Run verification first, then review.
+
+1. Run verification checks
+2. Review the diff first
+
+## User approval
+
+"Run verification checks."
+
+## Delegation message
+
+Task: Verify current branch changes.
+Command: `/verify`
+Proceed policy: Proceed automatically after changed scope and project checks are identified.
+Context hints: current branch diff.
+Allowed scope: repository checks only.
+Must follow: command protocol, command file, referenced skill only.
+
+## Worker behavior
+
+Code Tweaker loads `.roo/commands/verify.md`, sees `Skill: .roo/skills/engineering/verify/SKILL.md`, inspects project config and changed files, runs the smallest useful checks, and reports exact commands and results.
+
+## Verification / review
+
+After verification completes, Custom Orchestrator summarizes and asks whether to continue with the plain-language review workflow. It does not auto-launch review. If approved, System Architect loads `.roo/commands/review.md`, follows the review skill, reads targeted diffs and needed standards/specs, then reports findings by severity.
+
+## Completion summary
+
+The final summary includes verification status, review result, remaining risk, and whether commit is recommended. Commit requires explicit approval.

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.