@fernado03/zoo-flow 0.5.3 → 0.7.1

package/scripts/token-budget.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageRoot = path.resolve(__dirname, "..");
+
+const EXCEPTIONS_PATH = path.join(packageRoot, "quality", "token-budget.exceptions.json");
+const TIERS = [
+  { label: "tier-1-rules", dirs: [".roo/rules/", ".roo/rules-code-tweaker/", ".roo/rules-system-architect/", ".roo/rules-custom-orchestrator/"], max_bytes: 16000 },
+  { label: "tier-2-commands", dirs: [".roo/commands/"], max_bytes: 8000 },
+  { label: "tier-3-skills", dirs: [".roo/skills/"], max_bytes: 32000 },
+  { label: "tier-4-config", dirs: [".roomodes", ".roo/"], max_bytes: 4000, allow_files: true },
+  { label: "tier-5-docs", dirs: ["docs/"], max_bytes: 64000 },
+  { label: "tier-6-evidence", dirs: [".zoo-flow/evals/"], max_bytes: 8000 }
+];
+
+const failures = [];
+let exceptions = { overrides: {} };
+
+if (fs.existsSync(EXCEPTIONS_PATH)) {
+  try {
+    exceptions = JSON.parse(fs.readFileSync(EXCEPTIONS_PATH, "utf8"));
+  } catch (error) {
+    failures.push(`Invalid exceptions file: ${error.message}`);
+  }
+}
+
+function getExceptionKey(relativePath) {
+  return relativePath.replace(/\\/g, "/");
+}
+
+function getMaxOverride(relativePath) {
+  const key = getExceptionKey(relativePath);
+  const override = exceptions.overrides && exceptions.overrides[key];
+  return override ? override.max_bytes : null;
+}
+
+for (const tier of TIERS) {
+  for (const dirPattern of tier.dirs) {
+    const absPath = path.join(packageRoot, dirPattern);
+    if (!fs.existsSync(absPath)) continue;
+
+    let tierSize = 0;
+
+    if (tier.allow_files && fs.statSync(absPath).isFile()) {
+      const override = getMaxOverride(dirPattern);
+      if (override !== null) continue; // override allows it
+      const size = fs.statSync(absPath).size;
+      if (size > tier.max_bytes) {
+        failures.push(`${dirPattern} (${size} bytes) exceeds tier ${tier.label} limit (${tier.max_bytes})`);
+      }
+      continue;
+    }
+
+    const walkDir = (dir) => {
+      for (const entry of fs.readdirSync(dir)) {
+        const full = path.join(dir, entry);
+        const stat = fs.statSync(full);
+        if (stat.isDirectory()) {
+          walkDir(full);
+        } else {
+          const ext = path.extname(full);
+          if (![".md", ".json", ".txt", ".yaml", ".yml", ".jsonl"].includes(ext)) continue;
+
+          const relative = path.relative(packageRoot, full).replace(/\\/g, "/");
+          const override = getMaxOverride(relative);
+          if (override !== null) continue; // allowed by exception
+
+          tierSize += stat.size;
+        }
+      }
+    };
+
+    walkDir(absPath);
+
+    if (tierSize > tier.max_bytes) {
+      failures.push(`${dirPattern} tree (${tierSize} bytes) exceeds tier ${tier.label} limit (${tier.max_bytes})`);
+    }
+  }
+}
+
+// Also check README and CONTEXT.md sizes
+const readmePath = path.join(packageRoot, "README.md");
+if (fs.existsSync(readmePath)) {
+  const size = fs.statSync(readmePath).size;
+  const override = getMaxOverride("README.md");
+  if (override === null && size > 24000) {
+    failures.push(`README.md (${size} bytes) exceeds default limit (24000)`);
+  }
+}
+
+if (failures.length > 0) {
+  console.error("\nToken budget check failed:\n");
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  console.error("\nAdd exceptions in quality/token-budget.exceptions.json if this is intentional.\n");
+  process.exit(1);
+}
+
+console.log("Token budget check passed");

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

@@ -2,6 +2,6 @@
 description: "Ultra-compressed communication mode. Cuts token usage ~75% by dropping filler, articles, and pleasantries while keeping full technical accuracy. Use when user says \"caveman mode\", \"talk like caveman\", \"use caveman\", \"less tokens\", \"be brief\", or invokes /caveman."
 ---
 
-Run skill: `.roo/skills/productivity/caveman/SKILL.md`
+Skill: `.roo/skills/productivity/caveman/SKILL.md`
 
 $ARGUMENTS

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

@@ -1,7 +1,8 @@
 ---
 description: "Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says \"diagnose this\" / \"debug this\", reports a bug, says something is broken/throwing/failing, or describes a performance regression."
+mode: system-architect
 ---
 
-Run skill: `.roo/skills/engineering/diagnose/SKILL.md`
+Skill: `.roo/skills/engineering/diagnose/SKILL.md`
 
 $ARGUMENTS

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/feature.md

@@ -16,6 +16,6 @@ EXECUTION RULES (Run sequentially. Wait for user between phases):
 5. IMPLEMENT (Tweaker):
    - Architect summarizes issues.
    - Architect MUST `switch_mode` -> `code-tweaker`.
-   - Tweaker: For each issue, execute the `/tdd` command workflow (per `.roo/rules/01-command-protocol.md`). After each ships, suggest `/commit-and-document`.
+   - Tweaker: For each issue, execute the `/tdd` command workflow (per `.roo/rules/01-command-protocol.md`). After each ships, suggest `/verify`, then `/review`, then `/commit-and-document`. Do not auto-launch.
 
 $ARGUMENTS

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

@@ -15,6 +15,6 @@ EXECUTION RULES:
    - Tweaker MUST `switch_mode` -> `system-architect`.
 4. POST-MORTEM (Architect): Execute Phase 6. If architectural rot, suggest `/refactor`.
    - Architect MUST `switch_mode` -> `code-tweaker`.
-5. COMMIT (Tweaker): Suggest `/commit-and-document`.
+5. FOLLOW-UP (Tweaker): Suggest `/verify`, then `/review`, then `/commit-and-document`. Do not auto-launch.
 
 $ARGUMENTS

package/templates/full/.roo/commands/grill-me.md

@@ -1,7 +1,8 @@
 ---
 description: "Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions \"grill me\"."
+mode: system-architect
 ---
 
-Run skill: `.roo/skills/productivity/grill-me/SKILL.md`
+Skill: `.roo/skills/productivity/grill-me/SKILL.md`
 
 $ARGUMENTS

package/templates/full/.roo/commands/grill-with-docs.md

@@ -1,7 +1,8 @@
 ---
 description: "Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions."
+mode: system-architect
 ---
 
-Run skill: `.roo/skills/engineering/grill-with-docs/SKILL.md`
+Skill: `.roo/skills/engineering/grill-with-docs/SKILL.md`
 
 $ARGUMENTS

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

@@ -1,8 +1,9 @@
 ---
 description: "Compact the current conversation into a handoff document for another agent to pick up."
 argument-hint: "What will the next session be used for?"
+mode: system-architect
 ---
 
-Run skill: `.roo/skills/productivity/handoff/SKILL.md`
+Skill: `.roo/skills/productivity/handoff/SKILL.md`
 
 $ARGUMENTS

package/templates/full/.roo/commands/improve-codebase-architecture.md

@@ -1,7 +1,8 @@
 ---
 description: "Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable."
+mode: system-architect
 ---
 
-Run skill: `.roo/skills/engineering/improve-codebase-architecture/SKILL.md`
+Skill: `.roo/skills/engineering/improve-codebase-architecture/SKILL.md`
 
 $ARGUMENTS

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

@@ -4,6 +4,6 @@ argument-hint: <prototype question or design uncertainty>
 mode: code-tweaker
 ---
 
-Run skill: `.roo/skills/engineering/prototype/SKILL.md`
+Skill: `.roo/skills/engineering/prototype/SKILL.md`
 
 $ARGUMENTS

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

@@ -13,6 +13,6 @@ EXECUTION RULES:
    - Architect summarizes approved plan.
    - Architect MUST `switch_mode` -> `code-tweaker`.
    - Tweaker executes the `/tdd` command workflow (per `.roo/rules/01-command-protocol.md`) — new tests at interface, delete old.
-   - Tweaker suggests `/commit-and-document`.
+   - Tweaker suggests `/verify`, then `/review`, then `/commit-and-document`. Do not auto-launch.
 
 $ARGUMENTS

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

@@ -0,0 +1,11 @@
+---
+description: "Review a diff or branch against the requested spec, project standards, architecture, and likely regressions. Use before committing non-trivial work."
+argument-hint: <optional base ref, files, issue, PRD, or review focus>
+mode: system-architect
+---
+
+Review the current diff or requested target. Follow the skill exactly.
+
+Skill: `.roo/skills/engineering/review/SKILL.md`
+
+$ARGUMENTS

package/templates/full/.roo/commands/setup-matt-pocock-skills.md

@@ -3,6 +3,6 @@ description: "Sets up an `## Agent skills` block in AGENTS.md/CLAUDE.md and `doc
 mode: code-tweaker
 ---
 
-Run skill: `.roo/skills/engineering/setup-matt-pocock-skills/SKILL.md`
+Skill: `.roo/skills/engineering/setup-matt-pocock-skills/SKILL.md`
 
 $ARGUMENTS

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

@@ -4,6 +4,6 @@ argument-hint: <feature or bug to build>
 mode: code-tweaker
 ---
 
-Run skill: `.roo/skills/engineering/tdd/SKILL.md`
+Skill: `.roo/skills/engineering/tdd/SKILL.md`
 
 $ARGUMENTS

package/templates/full/.roo/commands/to-issues.md

@@ -1,7 +1,8 @@
 ---
 description: "Break a plan, spec, or PRD into independently-grabbable issues on the project issue tracker using tracer-bullet vertical slices. Use when user wants to convert a plan into issues, create implementation tickets, or break down work into issues."
+mode: system-architect
 ---
 
-Run skill: `.roo/skills/engineering/to-issues/SKILL.md`
+Skill: `.roo/skills/engineering/to-issues/SKILL.md`
 
 $ARGUMENTS

package/templates/full/.roo/commands/to-prd.md

@@ -1,7 +1,8 @@
 ---
 description: "Turn the current conversation context into a PRD and publish it to the project issue tracker. Use when user wants to create a PRD from the current context."
+mode: system-architect
 ---
 
-Run skill: `.roo/skills/engineering/to-prd/SKILL.md`
+Skill: `.roo/skills/engineering/to-prd/SKILL.md`
 
 $ARGUMENTS

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

@@ -3,6 +3,6 @@ description: "Triage issues through a state machine driven by triage roles. Use
 mode: system-architect
 ---
 
-Run skill: `.roo/skills/engineering/triage/SKILL.md`
+Skill: `.roo/skills/engineering/triage/SKILL.md`
 
 $ARGUMENTS

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

@@ -4,6 +4,6 @@ argument-hint: <what to change>
 mode: code-tweaker
 ---
 
-Run skill: `.roo/skills/engineering/tweak/SKILL.md`
+Skill: `.roo/skills/engineering/tweak/SKILL.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/commands/verify.md

@@ -0,0 +1,11 @@
+---
+description: "Run the smallest useful verification checks for the current change: tests, typecheck, lint, build, or targeted project checks. Never claim verified unless checks actually ran."
+argument-hint: <optional focus area, file, test, or command>
+mode: code-tweaker
+---
+
+Verify the current change with the smallest useful checks. Follow the skill exactly.
+
+Skill: `.roo/skills/engineering/verify/SKILL.md`
+
+$ARGUMENTS

package/templates/full/.roo/commands/write-a-skill.md

@@ -1,7 +1,8 @@
 ---
 description: "Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill."
+mode: code-tweaker
 ---
 
-Run skill: `.roo/skills/productivity/write-a-skill/SKILL.md`
+Skill: `.roo/skills/productivity/write-a-skill/SKILL.md`
 
 $ARGUMENTS

package/templates/full/.roo/commands/zoom-out.md

@@ -1,7 +1,8 @@
 ---
 description: "Tell the agent to zoom out and give broader context or a higher-level perspective. Use when you're unfamiliar with a section of code or need to understand how it fits into the bigger picture."
+mode: system-architect
 ---
 
-Run skill: `.roo/skills/engineering/zoom-out/SKILL.md`
+Skill: `.roo/skills/engineering/zoom-out/SKILL.md`
 
 $ARGUMENTS

package/templates/full/.roo/rules/01-command-protocol.md

@@ -11,7 +11,7 @@ When assigned a slash command, execute its command workflow before task-specific
 3. Fallback: if `run_slash_command` is unavailable, disabled, rejected, or fails, read `.roo/commands/{command}.md`.
 
 4. After command content is loaded:
-   - If it explicitly contains `Skill: .roo/skills/.../SKILL.md`, read that exact skill and follow it.
+   - If it explicitly contains the canonical `Skill:` marker with `.roo/skills/.../SKILL.md`, read that exact skill and follow it.
    - If it contains direct workflow steps, execute those steps directly.
    - Do not assume every command has a skill.
    - Do not read any skill unless the command explicitly references it.

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

@@ -14,16 +14,14 @@ For long command output, summarize or search the output instead of dumping every
 
 ## Domain-doc read gate
 
-Do not read CONTEXT.md, CONTEXT-MAP.md, FLOW.md, APP_MAP.md, ARCHITECTURE.md, or ADRs by default.
+Do not read `.zoo-flow/CONTEXT.md` or `.zoo-flow/docs/adr/` files by default.
 
 Read domain docs only when at least one is true:
 
 - The task touches domain language or terminology.
 - The task changes public behavior.
 - The task changes architecture, module seams, persistence, API shape, auth, payments, security, migrations, or cross-module design.
-- The command explicitly requires those docs, such as `/feature`, `/refactor`, `/grill-with-docs`, `/scaffold-context`, or relevant `/update-docs`.
+- The command explicitly requires those docs (e.g. `/feature`, `/refactor`, `/grill-with-docs`, `/scaffold-context`, `/update-docs`).
 - The user asks for documentation, architecture, product, or domain-context work.
 
-For low-risk localized edits, prefer code search and targeted file reads first.
-
-Missing CONTEXT.md or ADRs is not an error. Use the slot discovery rule in `.roo/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md` to detect what is present, and proceed silently when nothing is.
+Missing CONTEXT.md or ADRs is not an error. Proceed silently when nothing is present.

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

@@ -13,11 +13,17 @@ Before any `attempt_completion`, re-read the command body and confirm no later p
 
 `attempt_completion` must include:
 
-- what was done
-- files changed or inspected
-- commands/tests run
-- status
-- blockers
-- recommended next command
-
-Before running `git commit` or `git push`, halt and wait for explicit user approval. Never push unless explicitly asked.
+- what was done (exact scope)
+- files changed or inspected (paths)
+- 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)
+
+The orchestrator forwards your output to the user. Include enough detail that the user can act on it without re-running commands.
+
+Before running `git commit` or `git push`, halt and wait for explicit user approval. Never push unless explicitly asked.
+
+For non-trivial `/tdd`, `/fix`, `/feature`, `/refactor`, or R3+ `/tweak` work, recommend `/verify` before `/review` before `/commit-and-document`. Do not auto-launch those commands.
+
+If the user explicitly says to remember a project rule, or the same mistake has repeated, ask before appending a short lesson to `.zoo-flow/LESSONS.md`. Do not read or write lessons by default.

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

@@ -1,29 +1,47 @@
 # 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. Show the worker's full output to the user without truncating or summarizing.
+2. Add one line: recommended next command (if any).
+3. 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.
 
-If a task sounds like "ask", "inspect", "review", "analyze", "deep inspection", "investigate", or "reason about safety", route it to `system-architect`.
+Slash commands bypass this — the extension reads `mode:` from the command frontmatter and switches directly.
 
-If a task requires source edits, tests, docs updates, prototypes, or commits, route it to `code-tweaker`.
+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.
 
 ## User-facing workflow names
 
-Slash commands are internal routing labels unless the user explicitly typed one or asked for syntax. For free-form requests, use plain-language workflow names only: small implementation, test-first, diagnosis, feature planning, refactor planning, exploration, documentation update, commit and journal, prototype, issue triage. Never show slash commands as selectable options for free-form requests. Internal delegation may still use the slash command after approval.
+Slash commands are internal routing labels unless the user explicitly typed one or asked for syntax. For free-form requests, use plain-language workflow names only: small implementation, test-first, diagnosis, feature planning, refactor planning, exploration, documentation update, commit and journal, prototype, issue triage, review, verification. Never show slash commands as selectable options for free-form requests. Internal delegation may still use the slash command after approval.
 
 ## Routed commands
 
@@ -37,12 +55,14 @@ Slash commands are internal routing labels unless the user explicitly typed one
 | diagnosis            | `/fix`                 | system-architect |
 | feature planning     | `/feature`             | system-architect |
 | refactor planning    | `/refactor`            | system-architect |
-| exploration          | `/explore`             | system-architect |
-| issue triage         | `/triage`              | system-architect |
+| exploration          | `/explore`             | system-architect |
+| issue triage         | `/triage`              | system-architect |
+| review               | `/review`              | system-architect |
+| verification         | `/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.
+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.
 
 ## Routing weight
 
@@ -50,7 +70,7 @@ Prefer the lightest workflow that preserves correctness. Use small implementatio
 
 ## Risk levels
 
-Use risk to choose the lightest safe workflow. Risk does not override command intent; explicit slash commands still route as-is. R1 copy/style/doc typo/one-line obvious edit → small implementation. R2 localized code change with known target → small implementation or test-first. R3 behavior change with clear interface → test-first. R4 cross-module change or design tradeoff → feature planning or refactor planning. R5 auth/payments/security/migrations/data loss/external API contracts → strict planning/diagnosis with explicit approval gates.
+Use risk to choose the lightest safe workflow. Risk does not override command intent; explicit slash commands still route as-is. R1 copy/style/doc typo/one-line obvious edit → small implementation. R2 localized code change with known target → small implementation or test-first. R3 behavior change with clear interface → test-first, then suggest verification or review. R4 cross-module change or design tradeoff → feature planning or refactor planning, then suggest verification and review. R5 auth/payments/security/migrations/data loss/external API contracts → strict planning/diagnosis with explicit approval gates, then suggest verification and review.
 
 ## Disambiguation
 
@@ -62,8 +82,20 @@ 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. Free-form request = not self-approving; 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
 
-Delegate only after the approval gate is satisfied. Choose the safest proceed policy from `01-delegation-message.md`.
+Delegate only after the approval gate is satisfied. Choose the safest proceed policy from `01-delegation-message.md`.
+
+## Follow-up recommendations
+
+For non-trivial work, suggest the next command chain only after the current command completes. Do not auto-launch follow-up commands merely because they are mentioned.
+
+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+

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

@@ -53,10 +53,14 @@ Defaults:
 - `/tweak`: proceed automatically after audit if clean
 - `/tdd`: proceed automatically after audit if clean, unless the public interface, expected behavior, or test target is unclear
 - `/explore`: proceed automatically; ask only if the target area is ambiguous
-- `/update-docs`: proceed automatically after audit if the target doc/area is clear; ask if unclear
-- `/prototype`: proceed automatically if prototype branch is clear; ask if logic vs UI is ambiguous
-- `/fix`: ask after reproduced hypotheses before instrumentation/fix
-- `/feature`: ask at phase gates: Prototype/PRD, prototype verdict, slice approval, issue approval
-- `/refactor`: ask before selecting a candidate and before implementation
-- `/triage`: ask before publishing, closing, labeling, or making irreversible tracker changes unless the user explicitly requested it
-- `/commit-and-document`: always ask before `git commit`, `git push`, or issue close actions
+- `/update-docs`: proceed automatically after audit if the target doc/area is clear; ask if unclear
+- `/prototype`: proceed automatically if prototype branch is clear; ask if logic vs UI is ambiguous
+- `/verify`: proceed automatically after changed scope and project checks are identified; report exact commands run
+- `/review`: stop and report only; do not patch application source
+- `/fix`: ask after reproduced hypotheses before instrumentation/fix
+- `/feature`: ask at phase gates: Prototype/PRD, prototype verdict, slice approval, issue approval
+- `/refactor`: ask before selecting a candidate and before implementation
+- `/triage`: ask before publishing, closing, labeling, or making irreversible tracker changes unless the user explicitly requested it
+- `/commit-and-document`: always ask before `git commit`, `git push`, or issue close actions
+
+Do not auto-launch `/verify`, `/review`, or `/commit-and-document` merely because a worker recommended it. Suggest only; wait for explicit approval.

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

@@ -11,6 +11,10 @@ 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.
+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.
 
-Halt for explicit user approval before testing a bug hypothesis, finalizing an architecture plan, publishing issues, or making irreversible decisions.
+Halt for explicit user approval before testing a bug hypothesis, finalizing an architecture plan, publishing issues, or making irreversible decisions.
+
+For non-trivial completed plans or reviews, recommend the next command only. Typical chain: implementation command -> `/verify` -> `/review` -> `/commit-and-document`. Do not auto-launch those commands.
+
+If the user explicitly says to remember a project rule, or the same mistake has repeated, ask before appending a short lesson to `.zoo-flow/LESSONS.md`. Do not read or write lessons by default.

package/templates/full/.roo/skills/engineering/README.md

@@ -10,3 +10,5 @@
 - **[to-prd](./to-prd/SKILL.md)** — Context → PRD issue.
 - **[zoom-out](./zoom-out/SKILL.md)** — Map modules/callers.
 - **[prototype](./prototype/SKILL.md)** — Throwaway logic/UI prototype.
+- **[review](./review/SKILL.md)** — Diff/branch review against spec and standards.
+- **[verify](./verify/SKILL.md)** — Targeted tests/typecheck/lint/build evidence.

package/templates/full/.roo/skills/engineering/commit-and-document/SKILL.md

@@ -123,8 +123,7 @@ Date via `date +%Y-%m-%d`. Create `docs/journal/<YYYY-MM-DD>/` if missing. Write
 ## 7. Surface stale docs (if any)
 
 Read `git diff --cached --stat`. If any staged path overlaps with a path
-referenced in `.zoo-flow/CONTEXT.md`, `.zoo-flow/ARCHITECTURE.md`,
-`.zoo-flow/APP_MAP.md`, or any nearby `FLOW.md`, output exactly one line
+referenced in `.zoo-flow/CONTEXT.md`, output exactly one line
 before "Confirm":
 
   "Public surface may have drifted. Run /update-docs? (yes / skip)"

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

@@ -1,6 +1,6 @@
 # ADR Format
 
-Path: `docs/adr/NNNN-slug.md`. Create dir lazily.
+Path: `.zoo-flow/docs/adr/NNNN-slug.md`. Create dir lazily.
 
 ## Template
 

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

@@ -24,38 +24,13 @@ _Avoid_: Purchase, transaction
 - Define term in 1–2 sentences: what it is, not behavior.
 - Include domain terms only; exclude generic programming terms.
 
-## Slots
+## Directory layout
 
-| Slot | File (if present) | Authored by | Default location |
-|---|---|---|---|
-| Domain language | `CONTEXT.md` | User via /grill-with-docs | `.zoo-flow/CONTEXT.md` |
-| Decisions | `docs/adr/<NNNN-slug>.md` | User via /grill-with-docs | `.zoo-flow/docs/adr/` |
-| Subsystem flow | `FLOW.md` | Subsystem owner | Next to the code |
-| App map | `APP_MAP.md` | User via /update-docs | `.zoo-flow/APP_MAP.md` |
-| Architecture | `ARCHITECTURE.md` | User via /update-docs | `.zoo-flow/ARCHITECTURE.md` |
-| Setup | `README.md` | Project owner | Project root |
+- `.zoo-flow/CONTEXT.md` — domain language glossary
+- `.zoo-flow/docs/adr/<NNNN-slug>.md` — architecture decisions
 
-## Discovery rule (used by /explore, /update-docs, /grill-with-docs)
+## Discovery rule
 
-For each slot, in this order:
-
-1. If the file exists at the documented location, read it.
-2. If the slot is empty/missing, that is **not an error**. The user has
-   not authored it yet. Do not invent content. Do not lazy-create unless
-   the calling command explicitly says so (e.g. /grill-with-docs on a
-   first resolved term).
-3. If the calling command depends on a populated slot and none exist,
-   surface once: "Slot `<name>` not yet authored. Run /grill-with-docs
-   to fill, or continue without."
-
-## Multi-context (rare)
-
-A single project can hold multiple domain contexts when subsystems do
-not share language. Use:
-
-- `.zoo-flow/CONTEXT-MAP.md` — index of contexts.
-- `.zoo-flow/contexts/<slug>/CONTEXT.md` — per-context.
-- `.zoo-flow/contexts/<slug>/docs/adr/` — per-context ADRs.
-
-`/grill-with-docs` and `/explore` consult the map first, then the
-relevant per-context file.
+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."