@fernado03/zoo-flow 0.1.4 → 0.3.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,7 +1,7 @@
 {
   "name": "@fernado03/zoo-flow",
-  "version": "0.1.4",
   "description": "Workflow control plane for Zoo Code.",
+  "version": "0.3.0",
   "type": "module",
   "bin": {
     "zoo-flow": "bin/zoo-flow.js"

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/CONTEXT-FORMAT.md

@@ -23,10 +23,8 @@ _Avoid_: Purchase, transaction
 - MUST pick canonical term; aliases under `_Avoid_`.
 - MUST flag ambiguity + resolution.
 - Define term in 1–2 sentences: what it is, not behavior.
-- Include relationships/cardinality when obvious.
 - Include domain terms only; exclude generic programming terms.
 - Group under headings when useful.
-- Include example dialogue.
 
 ## Layout
 

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/.roo/skills/in-progress/README.md

@@ -3,6 +3,7 @@
 Draft skills. Excluded from plugin/top README until stable.
 
 - **[review](./review/SKILL.md)** — Review diff on Standards + Spec axes.
+- **[teach](./teach/SKILL.md)** — Stateful teaching workspace (mission, glossary, resources, learning records).
 - **[writing-beats](./writing-beats/SKILL.md)** — Assemble article beat-by-beat.
 - **[writing-fragments](./writing-fragments/SKILL.md)** — Capture raw writing fragments.
 - **[writing-shape](./writing-shape/SKILL.md)** — Shape raw material into article.

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

@@ -0,0 +1,59 @@
+---
+name: teach
+description: Teach a topic over multiple stateful sessions, treating the current directory as a teaching workspace. Tracks mission, glossary, resources, and learning records to ground every session and pace the user inside their zone of proximal development. Use when user asks to be taught a topic, wants to learn something over time, or mentions ongoing study.
+disable-model-invocation: true
+argument-hint: "What would you like to learn about?"
+---
+
+# Teach
+
+Stateful. Treat current directory as the teaching workspace.
+
+## Files
+
+- `MISSION.md` — why user wants this; grounds every decision. Format: `mission-format.md`.
+- `GLOSSARY.md` — canonical terms; all output conforms. Format: `glossary-format.md`.
+- `RESOURCES.md` — trusted knowledge + community sources. Format: `resources-format.md`.
+- `learning-records/NNNN-slug.md` — non-obvious lessons + prior knowledge. Format: `learning-record-format.md`.
+
+## Triad
+
+- **Knowledge** — drawn from `RESOURCES.md`. Never parametric.
+- **Skills** — exercises built from the knowledge.
+- **Wisdom** — real-world community interaction via `RESOURCES.md`.
+
+Topic mix varies: theoretical → knowledge-heavy; practical → skills-heavy.
+
+## Mission first
+
+If `MISSION.md` missing or vague, interview before teaching. No mission = no grounding, abstract exercises, no signal for what's next.
+
+## Zone of proximal development
+
+Pick next topic by:
+1. Read `learning-records/`.
+2. Align to `MISSION.md`.
+3. Pick tightest scope that still stretches the user.
+
+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.
+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`.
+
+## Skills loop
+
+Tools:
+- Interactive HTML explainers with quizzes / in-browser drills.
+- Step-through HTML guides for real-world tasks.
+- In-agent scenario quizzes.
+
+Every exercise closes a tight feedback loop.
+
+## Wisdom
+
+Default: attempt an answer, then route to a high-reputation community from `RESOURCES.md`. If user opted out of communities, record it in `RESOURCES.md` and stop suggesting.

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

@@ -0,0 +1,35 @@
+# GLOSSARY.md Format
+
+Canonical language for the workspace. All explainers/exercises/records conform. Building it is itself learning: tight definition = compressed understanding.
+
+## Template
+
+```markdown
+# {Topic} Glossary
+
+{One or two sentence description of what this glossary covers.}
+
+## Terms
+
+**Hypertrophy**:
+Muscle growth driven by mechanical tension and metabolic stress over repeated training sessions.
+_Avoid_: Bulking, getting big
+
+**Progressive overload**:
+Systematically increasing the demand on a muscle over time — via load, volume, or intensity.
+_Avoid_: Pushing harder, levelling up
+
+**RPE (Rate of Perceived Exertion)**:
+A 1–10 self-rating of how hard a set felt, where 10 is failure and 8 means two reps left in the tank.
+_Avoid_: Effort score, intensity rating
+```
+
+## Rules
+
+- Add a term only when user demonstrates understanding. Glossary records compressed knowledge; it is not a dictionary to read.
+- Be opinionated. Pick one canonical term; list rivals as `_Avoid_`.
+- Tight: 1–2 sentences. Define what term IS, not how to do it.
+- Use glossary's own terms inside other definitions. That's how complex terms compress.
+- Group under subheadings when natural clusters emerge (`## Anatomy`, `## Programming`). Flat list fine otherwise.
+- Flag ambiguities. "In this workspace, 'set' means working set."
+- Revise in place. Stale entries lie.

package/templates/full/.roo/skills/in-progress/teach/learning-record-format.md

@@ -0,0 +1,46 @@
+# Learning Record Format
+
+Live in `learning-records/`. Sequential numbering: `0001-slug.md`, `0002-slug.md`. Create directory lazily on first record.
+
+Teaching equivalent of ADRs. Capture non-obvious lessons, key insights, stated prior knowledge. Steer future sessions; calibrate ZPD.
+
+## Template
+
+```markdown
+# {Short title of what was learned or established}
+
+{1-3 sentences: what was learned (or what prior knowledge was established), and why it matters for future sessions.}
+```
+
+That is the whole format. A single paragraph counts. Value is recording _that_ this is now known and _why_ it changes what to teach next.
+
+## Optional sections
+
+Use only when they add value. Most records skip these.
+
+- **Status** frontmatter (`active | superseded by LR-NNNN`) — when an earlier understanding is replaced.
+- **Evidence** — how the user demonstrated understanding. Useful when the claim might be revisited.
+- **Implications** — what this unlocks/rules out. Worth recording when non-obvious.
+
+## Numbering
+
+Scan `learning-records/`, take highest number, increment.
+
+## When to write
+
+Write when any are true:
+
+1. User demonstrated genuine understanding of something non-trivial — evidence, not exposure. Sets a new floor.
+2. User disclosed prior knowledge — "I already know X." Record it + claimed depth.
+3. Misconception corrected — high-value; predicts future stumbles.
+4. Mission shifted in response to learning — cross-link to `MISSION.md` and update it.
+
+### Skip
+
+- Material merely covered. Coverage ≠ learning.
+- Anything tersely captured in `GLOSSARY.md`. No duplication.
+- Session activity logs. Records are decision-grade, not a journal.
+
+## Supersession
+
+When a later record contradicts an earlier one, mark old one `Status: superseded by LR-NNNN`. Don't delete. The history is itself signal.

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

@@ -0,0 +1,30 @@
+# MISSION.md Format
+
+Lives at workspace root. Captures _why_ the user is learning this. Every teaching decision traces back here.
+
+## Template
+
+```markdown
+# Mission: {Topic}
+
+## Why
+{1-3 sentences. Concrete real-world goal. What changes in user's life/work when they have this skill? Avoid "to understand X" — push for the underlying outcome.}
+
+## Success looks like
+- {Specific observable thing user will be able to do}
+- {Another}
+
+## Constraints
+- {Time, budget, prior commitments, learning preferences}
+
+## Out of scope
+- {Adjacent topics user explicitly skips — protects ZPD}
+```
+
+## Rules
+
+- One mission per workspace. Two unrelated topics = two workspaces.
+- Concrete over abstract. "Run a half marathon by October" beats "get fitter."
+- Push back on vagueness. Bad mission > no mission.
+- Revise when goal moves. Stale mission steers wrong.
+- One screen max. Past that, it's a plan, not a compass.

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

@@ -0,0 +1,32 @@
+# RESOURCES.md Format
+
+Curated trusted sources. Knowledge for explainers comes from here, not parametric guesses. Wisdom routes to communities listed here.
+
+## Template
+
+```markdown
+# {Topic} Resources
+
+## Knowledge
+
+- [Book: _The Science and Practice of Strength Training_ — Zatsiorsky & Kraemer](https://example.com)
+  Foundational text on programming and adaptation. Use for: periodisation, recovery, intensity zones.
+- [Article: "How Much Should I Train?" — Greg Nuckols (Stronger By Science)](https://example.com)
+  Evidence-based review of volume landmarks. Use for: weekly set targets per muscle group.
+
+## Wisdom (Communities)
+
+- [r/weightroom](https://reddit.com/r/weightroom)
+  High-signal subreddit, moderated against bro-science. Use for: programme critique, plateau troubleshooting.
+- Local: Tuesday strength class at {gym name}
+  Use for: real-time coaching feedback on lifts.
+```
+
+## Rules
+
+- High-trust only. Primary sources, recognised experts, peer-reviewed work, well-moderated communities. Marketing-as-education stays out.
+- Annotate every entry. One line: what it covers + when to reach for it.
+- Group `## Knowledge` / `## Wisdom`. Mirrors the triad in `SKILL.md`. Single-group entries fine.
+- Surface gaps. `## Gaps` section lists missing areas the mission needs. Drives future search.
+- Prune ruthlessly. Remove wrong/shallow/off-mission. Five sharp > thirty mediocre.
+- Record community opt-out here so future sessions stop proposing them.

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": []
     }
   ]