@fernado03/zoo-flow 0.1.4 → 0.2.0

package/README.md

@@ -86,6 +86,10 @@ 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.
+
 ## Modes
 
 | Slug                  | Name                  | Role                                                       | Edits allowed                                  | Delegation                                  |
@@ -101,9 +105,8 @@ behavior lives in `.roo/rules-{modeSlug}/` folders. See
 
 ## Commands
 
-The orchestrator routes the **core** commands. **Helper** commands you
-run directly inside `system-architect` or `code-tweaker` when you
-need them.
+The orchestrator routes the **core** commands. **Helper** commands are
+run directly inside `system-architect` or `code-tweaker` when needed.
 
 ### Core (routed by the orchestrator)
 

package/bin/zoo-flow.js

@@ -141,6 +141,34 @@ function validateTemplate(rootDir) {
     }
   }
 
+  // Validate skill-wrapper command references. Each command file in
+  // .roo/commands/ may either declare a skill via `Skill:
+  // .roo/skills/.../SKILL.md` (skill-wrapper command) or contain its
+  // workflow steps directly. Direct-workflow commands are valid; we only
+  // verify referenced skills exist.
+  if (pathExists(commandsDir)) {
+    const skillRefRegex = /^Skill:\s*`?(\.roo\/skills\/[^\s`]+SKILL\.md)`?\s*$/m;
+
+    for (const entry of fs.readdirSync(commandsDir)) {
+      if (!entry.endsWith(".md")) continue;
+
+      const commandFile = path.join(commandsDir, entry);
+      const text = fs.readFileSync(commandFile, "utf8");
+      const match = text.match(skillRefRegex);
+
+      if (!match) continue;
+
+      const skillRelative = match[1];
+      const skillAbsolute = path.join(rootDir, skillRelative);
+
+      if (!pathExists(skillAbsolute)) {
+        failures.push(
+          `Command ${path.relative(rootDir, commandFile)} references missing skill: ${skillRelative}`
+        );
+      }
+    }
+  }
+
   const allFiles = walkFiles(rootDir);
   const textFileExtensions = new Set([".md", ".json", ".txt", ".yaml", ".yml"]);
 
@@ -167,7 +195,9 @@ function validateTemplate(rootDir) {
   const requiredRules = [
     ".roo/rules/00-paths.md",
     ".roo/rules/01-command-protocol.md",
-    ".roo/rules/03-manual-reply-protocol.md"
+    ".roo/rules/02-three-failure-rule.md",
+    ".roo/rules/03-manual-reply-protocol.md",
+    ".roo/rules/04-context-economy.md"
   ];
 
   for (const rule of requiredRules) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fernado03/zoo-flow",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Workflow control plane for Zoo Code.",
   "type": "module",
   "bin": {

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

@@ -1,25 +1,23 @@
 # Command Protocol
 
-When assigned a slash command, execute the command workflow before doing task-specific work.
-
-Protocol:
+When assigned a slash command, execute its command workflow before task-specific work.
 
 1. Normalize the command by stripping the leading slash.
-   - `/fix` becomes `fix`
-   - `/tdd` becomes `tdd`
 
-2. Preferred execution:
-   - Use `run_slash_command` if available.
-   - Pass `command` as the normalized command name.
-   - Pass `args` as the full user/delegated task context.
+2. Preferred: use `run_slash_command` with:
+   - `command`: normalized command name
+   - `args`: full user/delegated context
+
+3. Fallback: if `run_slash_command` is unavailable, disabled, rejected, or fails, read `.roo/commands/{command}.md`.
 
-3. Fallback execution:
-   - If `run_slash_command` is unavailable, disabled, rejected, or fails, read the command file from:
-     - `.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 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.
 
-4. If the command file references a skill:
-   - Read the exact `.roo/skills/...` path from the command file.
-   - Follow the skill instructions after loading.
+5. Use only one command-loading path:
+   - If `run_slash_command` succeeds, do not also read `.roo/commands/{command}.md`.
+   - If fallback command-file read succeeds, do not also call `run_slash_command`.
 
-5. Do not auto-run follow-up commands merely because they are mentioned in a subtask summary.
-   - Only the human user or orchestrator routing may authorize a new command.
+6. Do not auto-run follow-up commands merely because they are mentioned in a result or subtask summary.

package/templates/full/.roo/rules/03-manual-reply-protocol.md

@@ -1,15 +1,27 @@
 # Manual Reply Protocol
 
-For workflow choices, ask the question in the message body and put only safe numbered options in suggestions.
+For workflow choices, ask the question in the message body and list numbered options.
 
-Safe options:
+Clickable suggestions may use the plain-language option text, but must not contain slash commands, mode names, or executable routing text.
+
+Users may reply with either the number or the option text.
+
+Example:
 
 1. Tweak small implementation
 2. Diagnose bug
 3. Hold
 
-Do not put slash commands, mode names, or executable routing text in suggestions.
+Safe suggestions:
+
+- Tweak small implementation
+- Diagnose bug
+- Hold
+
+Unsafe suggestions:
 
-Users may reply by typing the number.
+- `/tweak`
+- `Switch to code-tweaker`
+- `Route to system-architect`
 
 Only treat slash commands as commands when manually typed by the user.

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

@@ -0,0 +1,13 @@
+# Context Economy
+
+Use the smallest read that preserves correctness.
+
+Prefer `list_files`, `search_files`, or `codebase_search` before full-file reads.
+
+When reading files, prefer targeted line ranges or indentation/block reads when the relevant area is known.
+
+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.

package/templates/full/.roo/rules-code-tweaker/00-scope.md

@@ -2,6 +2,10 @@
 
 Implement, test, update docs, prototype, and commit only after approval.
 
+Respect the delegated task's proceed policy before implementation.
+
 Do not make broad architecture decisions.
 
 Escalate to `system-architect` with `switch_mode` when architecture decisions are needed.
+
+Respect `.roo/rules/04-context-economy.md` before reading or re-reading files.

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

@@ -11,4 +11,6 @@ Delegate only with `new_task` to:
 - `code-tweaker`
 - `system-architect`
 
+When delegating, choose the safest proceed policy from `01-delegation-message.md`.
+
 After a subtask returns, summarize and stop. Do not auto-launch another subtask.

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

@@ -2,7 +2,37 @@
 
 Every delegated task must include:
 
-- command with slash (e.g. `/refactor`)
+- command with slash
 - user context
+- proceed policy
+- instruction to follow `.roo/rules/01-command-protocol.md`
+- reminder that skills live under `.roo/skills/...`
+- completion rule to use `attempt_completion` with summary, files inspected/changed, commands/tests run, blockers, and recommended next command
+- context hints: known files, symbols, line ranges, or search terms when available
+
+Do not paste huge file contents into delegated task messages. Pass paths, symbols, search terms, and required decisions instead.
 
 Ignore slash commands mentioned only inside subtask summaries.
+
+# Proceed Policy
+
+Every delegated task must include one proceed policy:
+
+- `Proceed automatically after audit if clean`
+- `Ask user before implementation`
+- `Stop and report only`
+
+Use the least-interruptive policy that is safe.
+
+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

package/templates/full/.roo/rules-system-architect/00-scope.md

@@ -2,8 +2,12 @@
 
 Plan, diagnose, explore, refactor-design, and triage.
 
+Respect the delegated task's proceed policy and explicit phase gates.
+
 Do not edit application source code.
 
 Edits are limited to Markdown files, `.scratch/`, and `docs/`.
 
 Use `switch_mode` to `code-tweaker` for implementation, test-writing, runnable prototypes, or source-code edits.
+
+Respect `.roo/rules/04-context-economy.md`: map/search before broad reads, then read only the relevant sections.

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

@@ -124,6 +124,18 @@ Date via `date +%Y-%m-%d`. Create `docs/journal/<YYYY-MM-DD>/` if missing. Write
 
 Report: commit hash + message, journal entry path, whether `.gitignore` was updated, and any issue actions taken. Close with: "All of `docs/` is gitignored, so this entry stays local."
 
+## Context economy
+
+Before broad reads, locate relevant files/symbols with `list_files`, `search_files`, or `codebase_search`.
+
+Prefer targeted `read_file` ranges or indentation/block reads once the relevant area is known.
+
+Read full files only when structure, ordering, or surrounding context is required for correctness.
+
+Do not re-read unchanged files; use prior findings unless the file changed.
+
+Use `git status --short`, `git diff --stat`, and targeted `git diff -- <file>` rather than dumping the full repo diff at once.
+
 ## Safety
 
 - Never `git push`, `--amend`, `--force`, or `reset --hard`.

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

@@ -61,6 +61,18 @@ Rules:
 6. Watch regression pass.
 7. Rerun original loop.
 
+## Context economy
+
+Before broad reads, locate relevant files/symbols with `list_files`, `search_files`, or `codebase_search`.
+
+Prefer targeted `read_file` ranges or indentation/block reads once the relevant area is known.
+
+Read full files only when structure, ordering, or surrounding context is required for correctness.
+
+Do not re-read unchanged files; use prior findings unless the file changed.
+
+For logs or large outputs, search for the failing marker/error first. Read only surrounding ranges needed to prove or disprove a hypothesis.
+
 ## 6. Cleanup
 
 MUST finish:

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

@@ -18,6 +18,16 @@ description: Grilling session that challenges your plan against the existing dom
 
 See `CONTEXT-FORMAT.md` for layout and detection. Create docs lazily only when recording needed.
 
+## Context economy
+
+Before broad reads, locate relevant files/symbols with `list_files`, `search_files`, or `codebase_search`.
+
+Prefer targeted `read_file` ranges or indentation/block reads once the relevant area is known.
+
+Read full files only when structure, ordering, or surrounding context is required for correctness.
+
+Do not re-read unchanged files; use prior findings unless the file changed.
+
 ## MUST
 
 - Challenge glossary conflicts.

package/templates/full/.roo/skills/engineering/improve-codebase-architecture/SKILL.md

@@ -34,6 +34,18 @@ RULE: Use `LANGUAGE.md` terms. Use glossary. Respect ADRs; surface only reopen-w
 9. DO NOT propose interfaces yet.
 10. Ask: `Which of these would you like to explore?`
 
+## Context economy
+
+Before broad reads, locate relevant files/symbols with `list_files`, `search_files`, or `codebase_search`.
+
+Prefer targeted `read_file` ranges or indentation/block reads once the relevant area is known.
+
+Read full files only when structure, ordering, or surrounding context is required for correctness.
+
+Do not re-read unchanged files; use prior findings unless the file changed.
+
+Use searches to identify dependency/call patterns before reading full modules. Read full files only for top candidates.
+
 ## After candidate chosen
 
 1. Walk constraints/deps/seam/hidden implementation/surviving tests.

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

@@ -14,6 +14,16 @@ RULE: Prototype answers one question. Throw away or absorb after answer.
 - Ambiguous → ask.
 - User AFK → infer + state assumption.
 
+## Context economy
+
+Before broad reads, locate relevant files/symbols with `list_files`, `search_files`, or `codebase_search`.
+
+Prefer targeted `read_file` ranges or indentation/block reads once the relevant area is known.
+
+Read full files only when structure, ordering, or surrounding context is required for correctness.
+
+Do not re-read unchanged files; use prior findings unless the file changed.
+
 ## Rules
 
 1. Mark throwaway clearly.

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

@@ -50,6 +50,18 @@ Checklist per cycle:
 - [ ] Code minimal.
 - [ ] No speculation.
 
+## Context economy
+
+Before broad reads, locate relevant files/symbols with `list_files`, `search_files`, or `codebase_search`.
+
+Prefer targeted `read_file` ranges or indentation/block reads once the relevant area is known.
+
+Read full files only when structure, ordering, or surrounding context is required for correctness.
+
+Do not re-read unchanged files; use prior findings unless the file changed.
+
+Read the public interface and nearest existing tests first. Avoid reading unrelated implementation until a failing test or search result points there.
+
 ## References
 
 - `tests.md` — what to assert and what not to.

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

@@ -15,3 +15,15 @@ Use for small known fixes.
 6. DO NOT write new tests unless asked.
 7. Confirm change.
 8. Offer `/commit-and-document` only after user satisfied.
+
+## Context economy
+
+Before broad reads, locate relevant files/symbols with `list_files`, `search_files`, or `codebase_search`.
+
+Prefer targeted `read_file` ranges or indentation/block reads once the relevant area is known.
+
+Read full files only when structure, ordering, or surrounding context is required for correctness.
+
+Do not re-read unchanged files; use prior findings unless the file changed.
+
+For small changes, audit only the named files and nearby call sites. Expand search only if the first audit shows hidden dependencies.

package/templates/full/.roo/skills/engineering/update-docs/SKILL.md

@@ -51,6 +51,16 @@ Use today's date. Include only files actually inspected.
 
 After editing: re-read, confirm referenced paths exist, every major claim maps to code or a cited doc, no stale contradiction with nearby docs. Summarise the change.
 
+## Context economy
+
+Before broad reads, locate relevant files/symbols with `list_files`, `search_files`, or `codebase_search`.
+
+Prefer targeted `read_file` ranges or indentation/block reads once the relevant area is known.
+
+Read full files only when structure, ordering, or surrounding context is required for correctness.
+
+Do not re-read unchanged files; use prior findings unless the file changed.
+
 ## 7. Recommend next step
 
 Recommend one: `/explore` (still unclear), `/feature` (plan emerged), `/refactor` (tangled-but-working code), `/fix` (bug found), `/commit-and-document` (done). Do not auto-run.

package/templates/full/.roo/skills/engineering/zoom-out/SKILL.md

@@ -5,3 +5,15 @@ disable-model-invocation: true
 ---
 
 Zoom out: map relevant modules + callers at higher abstraction. Use glossary vocabulary.
+
+## Context economy
+
+Before broad reads, locate relevant files/symbols with `list_files`, `search_files`, or `codebase_search`.
+
+Prefer targeted `read_file` ranges or indentation/block reads once the relevant area is known.
+
+Read full files only when structure, ordering, or surrounding context is required for correctness.
+
+Do not re-read unchanged files; use prior findings unless the file changed.
+
+Start with `list_files` and `search_files`/`codebase_search`. Read representative files and key entrypoints, not every file in the area.

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.",
+      "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.",
       "groups": []
     }
   ]