@fernado03/zoo-flow 0.7.0 → 0.7.3

package/README.md

@@ -53,36 +53,20 @@ npx @fernado03/zoo-flow@latest doctor
 
 ## Using Zoo Flow
 
-First run:
-
-- Read [`.zoo-flow/START_HERE.md`](templates/full/.zoo-flow/START_HERE.md).
-- Run `/scaffold-context` when the project needs local context docs.
+First run:
+
+- Run `/scaffold-context` when the project needs local context docs.
 - Run `/setup-matt-pocock-skills` when tracker or triage config is needed.
 
-Daily use:
-
-- Start in `custom-orchestrator`.
-- Describe the task normally.
-- The orchestrator proposes a plain-language workflow.
-- Approve by number or option text.
-
-Power-user path:
-
-- Type a slash command directly when you already know the workflow.
-- Zoo Code switches mode from the command file's `mode:` field.
-
-Safety:
-
-- Workflow choices must be plain language.
-- Clickable choices must not include slash commands or mode names.
-- Explicit slash commands count as approval.
-- Free-form requests do not self-approve.
-
-When Zoo Flow asks a workflow question, reply by typing the number, for
-example `1`. See
-[`docs/troubleshooting.md`](docs/troubleshooting.md#clickable-suggestions-can-route-incorrectly).
-
-For team usage and deciding what to commit, see `docs/team-mode.md`.
+Daily use:
+
+- Start in `custom-orchestrator`, describe the task normally.
+- The orchestrator proposes a plain-language workflow; approve by number.
+- Or type a slash command directly (`/tweak`, `/fix`, etc.) to bypass routing.
+- Explicit slash commands count as approval. Free-form requests do not.
+- **Clickable choices must not include slash commands or mode names.**
+
+For team usage, see `docs/team-mode.md`.
 
 ## Update
 
@@ -94,13 +78,9 @@ Backs up your current `.roomodes` and `.roo/` to
 `.zoo-flow-backup/<timestamp>/`, then replaces them with the latest
 template. Preview with `--dry-run`.
 
-## Context economy
-
-Zoo Flow avoids unnecessary token use by asking agents to search or list before broad reads, use targeted line ranges when possible, and avoid re-reading unchanged files. Full-file reads are still allowed when correctness requires complete context.
-
 ## Token discipline
 
-Domain docs (`.zoo-flow/CONTEXT.md`, `.zoo-flow/docs/adr/`) are never read by default. They are loaded only when the task touches domain language, changes public behavior, or crosses architecture/auth/persistence seams. All runtime files (rules, commands, skills) have tiered token budgets enforced by `scripts/token-budget.js`.
+Zoo Flow keeps always-loaded rules small. Domain docs (`.zoo-flow/CONTEXT.md`, `.zoo-flow/docs/adr/`) are never read by default — only when the task touches domain language, public behavior, or architecture seams. Agents search before broad reads, use targeted line ranges when possible, and avoid re-reading unchanged files. All runtime files have tiered token budgets enforced by `scripts/token-budget.js`.
 
 ## Modes
 

package/package.json

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

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

@@ -4,10 +4,10 @@ argument-hint: <feature or folder to map>
 mode: system-architect
 ---
 EXECUTION RULES:
-1. APPLY the slot discovery rule from `.roo/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md` to the target area. Missing slots are not an error. If no slots are populated, output one line before step 2: "No context docs found. Run /grill-with-docs to start CONTEXT.md, or continue without context."
+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. RUN skill: `.roo/skills/engineering/zoom-out/SKILL.md`.
 3. OUTPUT MAP: Create markdown with sections: Domain language, Modules, Data flow, Seams/callers, ADRs, Open questions.
-4. NEXT STEPS: Suggest `/grill-with-docs`, `/feature`, `/refactor`, or `/fix`. DO NOT auto-launch.
+4. NEXT STEPS: Suggest `/scaffold-context`, `/feature`, `/refactor`, or `/fix`. DO NOT auto-launch.
 5. SAVE (Optional): Ask to save map to .scratch/explorations/<date>/explore-<slug>.md.
 
 $ARGUMENTS

package/templates/full/.roo/commands/update-docs.md

@@ -8,7 +8,7 @@ Update repo documentation so it matches the current code. Surgical edits only
 
 Skill: `.roo/skills/engineering/update-docs/SKILL.md`
 
-Apply the slot discovery rule from `.roo/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md` to locate the target doc. If the slot is empty, ask once: "No <slot> found. Create a stub at .zoo-flow/<slot>? (yes / pick-existing / skip)".
+Find the target doc in `.zoo-flow/` or `docs/`. If it does not exist, ask once: "No <slot> found. Create a stub at .zoo-flow/<slot>? (yes / pick-existing / skip)".
 
 Do NOT use this for:
 

package/templates/full/.roo/rules/04-context-economy.md

@@ -10,7 +10,7 @@ Batch related small reads when useful.
 
 Do not re-read unchanged files unless needed.
 
-For long command output, summarize or search the output instead of dumping everything.
+For long shell command output (tests, builds, lint), summarize or search the output instead of dumping everything. This is about context window management, not about hiding results from the user.
 
 ## Domain-doc read gate
 

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

@@ -18,7 +18,11 @@ Before any `attempt_completion`, re-read the command body and confirm no later p
 - commands/tests run (exact commands, pass/fail per command)
 - status (complete / partial / blocked with reason)
 - remaining risk (what was not checked or is uncertain)
-- recommended next command (one only, no auto-launch)
+- recommended next command (one only, no auto-launch)
+
+The orchestrator forwards your output to the user. Include enough detail that the user can act on it without re-running commands.
+
+If the output is long (multi-file diff summary, full test output, verification report), write it to `.scratch/` first and reference the path in `attempt_completion`. The extension may truncate long completion messages, so files ensure nothing is lost.
 
 Before running `git commit` or `git push`, halt and wait for explicit user approval. Never push unless explicitly asked.
 

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

@@ -1,22 +1,41 @@
 # Orchestrator Routing
 
-Router only. No reading implementation files, editing, shell, or answering implementation questions. Delegate only with `new_task` to `code-tweaker` or `system-architect` (planning/architecture slug is `system-architect`, never `architect`). Summarize and stop after a subtask returns; do not auto-launch another.
+Router only. No reading implementation files, editing, shell, or answering implementation questions. Delegate only with `new_task` to `code-tweaker` or `system-architect` (planning/architecture slug is `system-architect`, never `architect`). When a subtask returns, present its full result to the user first, then add one-line recommendation. Do not summarize away detail. Do not auto-launch another command.
+
+## Subtask result handling
+
+After `attempt_completion` from a worker, the orchestrator must:
+
+1. If the completion message references a `.scratch/` file, read and present that file's content.
+2. Show the worker's full output to the user without truncating or summarizing.
+3. Add one line: recommended next command (if any).
+4. Stop and wait for user input.
+
+Do not route a new user message until the previous subtask result is fully presented. If the user sends a new message before the result was shown, finish presenting the result first, then route the new message.
 
 ## Hard delegation boundary
 
-The only valid `new_task` target slugs are:
+For free-form requests, the only valid `new_task` target slugs are:
 
 - `code-tweaker`
 - `system-architect`
 
 Never delegate to built-in/default modes, including Ask, Code, Debug, Architect, or Orchestrator.
 
+Slash commands bypass this — the extension reads `mode:` from the command frontmatter and switches directly.
+
 If a task sounds like "ask", "inspect", "review", "branch review", "pre-commit review", "analyze", "deep inspection", "investigate", or "reason about safety", route it to `system-architect`.
 
 If a task requires source edits, tests, verification, docs updates, prototypes, or commits, route it to `code-tweaker`.
 
 If neither custom mode is suitable, stop and report that no valid Zoo Flow mode exists. Do not fall back to Ask mode.
 
+## Slash command handling
+
+When the user types a slash command (e.g. `/tweak`, `/explore`), the extension reads the `mode:` frontmatter from the command file and auto-switches to that mode. The orchestrator does not route slash commands — the extension handles it.
+
+The orchestrator only routes **free-form requests** (natural language without a leading `/`).
+
 ## Natural language first
 
 Users are not expected to know slash commands. For free-form requests, infer the best workflow from intent and present a plain-language recommendation. Slash commands are optional power-user overrides. Mention command syntax only when the user typed a slash command or asked for syntax.
@@ -64,7 +83,7 @@ Explicit slash command from user = approval; route as-is. Clear free-form reques
 
 ## Approval gate
 
-The orchestrator proposes; the user approves; then the orchestrator delegates. Explicit slash command = approval; route immediately. A free-form request is never self-approving; propose a workflow and wait for approval. Present the recommendation, then stop and wait. Treat replies as approval only when they select the proposed workflow by number, option text, or clear restatement. A fresh free-form request restarts routing. If unsure whether the user approved, ask.
+The orchestrator proposes; the user approves; then the orchestrator delegates. Slash commands are auto-approved — the extension switches mode and executes immediately. A free-form request is never self-approving; propose a workflow and wait for approval. Present the recommendation, then stop and wait. Treat replies as approval only when they select the proposed workflow by number, option text, or clear restatement. A fresh free-form request restarts routing. If unsure whether the user approved, ask.
 
 ## Delegation
 

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

@@ -11,7 +11,9 @@ If you entered this window via `switch_mode` (you are mid-chain, not the entry p
 
 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. Every `attempt_completion` must include evidence of what was produced or discovered, not just summaries.
+Do not use `attempt_completion` to avoid required implementation work. Every `attempt_completion` must include the full output the user needs to see (review findings, exploration map, diagnosis, plan), not just summaries. The orchestrator will forward your output to the user; if you summarize, the user loses detail.
+
+If the output is long (multi-page review, full exploration map, detailed diagnosis), write it to `.scratch/` first and reference the path in `attempt_completion`. The extension may truncate long completion messages, so files ensure nothing is lost.
 
 Halt for explicit user approval before testing a bug hypothesis, finalizing an architecture plan, publishing issues, or making irreversible decisions.
 

package/templates/full/.roo/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md

@@ -32,5 +32,4 @@ _Avoid_: Purchase, transaction
 ## Discovery rule
 
 1. If the file exists, read it.
-2. If the file is missing, that is **not an error**. Do not invent content.
-3. For commands that depend on populated context, surface once: "No CONTEXT.md or ADRs found yet. Run /grill-with-docs or /scaffold-context to fill, or continue without."
+2. If the file is missing, that is **not an error**. Do not invent content. Surface once: "No CONTEXT.md found. Run /scaffold-context to fill, or continue without."

package/templates/full/.zoo-flow/START_HERE.md

@@ -1,61 +1,8 @@
-# Zoo Flow Quick Start
-
-## After installation
-
-1. Start in Custom Orchestrator mode.
-
-2. For an existing project, bootstrap project context:
-
-   `/scaffold-context`
-
-   This scans the codebase and proposes initial `.zoo-flow/CONTEXT.md` terms plus optional starter ADRs. It asks before writing anything.
-
-3. If you plan to use PRDs, issue slicing, or triage, configure agent skill metadata:
-
-   `/setup-matt-pocock-skills`
-
-   This sets up issue tracker, triage label, and domain-doc configuration used by PRD, issue, and triage workflows.
-
-4. After that, describe tasks normally. You do not need slash commands unless you already know the workflow.
-
-## First-run checklist
-
-- [ ] Custom Orchestrator mode is selected.
-- [ ] Run `/scaffold-context` for an existing codebase.
-- [ ] Run `/setup-matt-pocock-skills` if using PRDs, issue slicing, or triage.
-- [ ] Start normal work by describing the task in plain language.
-
-## Common requests
-
-| What you want | What Zoo Flow will likely do |
-|---|---|
-| Small obvious edit | Small implementation workflow |
-| Known localized fix | Small implementation workflow |
-| Bug with unknown cause | Diagnosis workflow |
-| New feature needing planning | Feature planning workflow |
-| Improve structure without behavior change | Refactor workflow |
-| Understand unfamiliar area | Exploration workflow |
-| Write tests first | TDD workflow |
-| Update docs | Documentation workflow |
-| Commit finished work | Commit + journal workflow |
-
-## What the orchestrator will show you
-
-For normal requests, the orchestrator should recommend plain-language workflows, not slash commands.
-
-Example:
-
-> "This looks like a small implementation change. Proceed?"
-
-Slash commands below are optional shortcuts for users who already know the workflow.
-
-## Power-user shortcuts
-
-You may type slash commands directly when you already know the workflow, but this is optional.
-
-Examples:
-
-- `/tweak change button copy`
-- `/fix checkout crashes after payment`
-- `/feature add team invitations`
-- `/refactor simplify auth service`
+# Zoo Flow Quick Start
+
+## After installation
+
+1. Reload VS Code and open Zoo Code.
+2. Switch to **Custom Orchestrator** mode.
+3. Run `/scaffold-context` for an existing project, or `/setup-matt-pocock-skills` if using PRDs, issue slicing, or triage.
+4. Then describe tasks normally.