@fernado03/zoo-flow 0.1.3 → 0.2.0

package/README.md

@@ -68,9 +68,12 @@ ways to drive Zoo Flow, and the choice matters:
 
   > /tweak fix the typo in `README`
 
-Numbered choices the orchestrator presents are answered by typing
-the number. Clicking is safe when the suggestion has no mode-switch
-indicator at the bottom-right; otherwise type instead. See
+When Zoo Flow asks a workflow question, reply by typing the number,
+for example `1`.
+
+Zoo Flow may show numbered options, but those options should be
+plain-language choices only. They should not contain slash commands,
+mode names, or executable routing text. See
 [`docs/troubleshooting.md`](docs/troubleshooting.md#clickable-suggestions-can-route-incorrectly).
 
 ## Update
@@ -83,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                                  |
@@ -98,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.3",
+  "version": "0.2.0",
   "description": "Workflow control plane for Zoo Code.",
   "type": "module",
   "bin": {

package/templates/full/.roo/commands/commit-and-document.md

@@ -1,202 +1,11 @@
 ---
-description: "Update repo documentation so it matches the current code."
-argument-hint: <doc or area to update>
+description: "Stage changes, write a Conventional Commit, link any GitHub issue, and append a dated journal entry under docs/journal/."
+argument-hint: <optional context for the commit message>
 mode: code-tweaker
 ---
 
-You are running the **commit + document** procedure. This is a deterministic flow, not a skill — execute the steps in order. Do not deviate.
+Run the **commit + document** procedure: inspect git, propose a Conventional Commit, optionally link a GitHub issue, stage selected files, commit, and write a dated entry under `docs/journal/`. Follow the skill exactly.
 
-## Step 1 — Inspect git changes
-
-Run these three commands and read the output:
-
-- `git status --short`
-- `git diff --stat`
-- `git diff --cached --stat` (in case anything is already staged)
-
-Summarise to the user what's changed: which files, roughly what the changes do.
-
-## Step 2 — Suggest a Conventional Commit message
-
-Propose ONE single-line commit message in this exact format:
-
-```
-<type>(<scope>): <short, action-focused summary>
-```
-
-- **type** — one of: `feat`, `fix`, `refactor`, `docs`, `chore`, `test`, `style`, `perf`
-- **scope** — the area of the repo touched (e.g. `chat`, `documents`, `ui`, `core`, or a specific module name). Omit parens if scope is unclear.
-- **summary** — imperative mood, present tense, under 70 chars total. Start with a verb.
-
-Show the user the proposed message, the list of files that will be staged, and a separate list of excluded files such as test files, test folders, docs, or secrets. Ask: "Commit with this message? (yes / edit / cancel)"
-
-If they say `edit`, take their revised message. If `cancel`, stop the whole procedure and report.
-
-## Step 2.5 — Detect or ask for an issue reference
-
-This step links the commit to a GitHub issue if one applies. It is opt-in — if no issue applies, skip cleanly.
-
-### Pre-checks (silent, fast bail-out)
-
-Before asking the user anything, run these silent checks:
-
-1. Run `git remote -v` and look for a `github.com` remote.
-2. If no GitHub remote exists, skip this entire step. Do NOT prompt.
-3. If `gh` CLI is not installed (check with `command -v gh`), skip this entire step. Do NOT prompt.
-
-### Detection
-
-Scan the proposed commit message from Step 2 for issue references:
-
-- Closing keywords: `Closes #N`, `Close #N`, `Closed #N`, `Fixes #N`, `Fix #N`, `Fixed #N`, `Resolves #N`, `Resolve #N`, `Resolved #N` (case-insensitive)
-- Bare references: `#N` anywhere in the message
-
-### Branch A — Commit message already has a closing keyword
-
-Show the user the detected reference and ask:
-
-> Detected `Closes #42` in the commit message. After commit, comment on issue #42 and close it? (yes / no)
-
-- yes → proceed; remember `{action: close, issue: 42}` for Step 3.5
-- no → proceed without issue actions
-
-### Branch B — Commit message has bare `#N` (not a closing keyword)
-
-> Detected `#42` in the commit message. After commit, post a progress comment on issue #42? (yes / no / close)
-
-- yes → remember `{action: comment, issue: 42}`
-- close → remember `{action: close, issue: 42}`
-- no → no issue actions
-
-### Branch C — No reference detected
-
-Ask once:
-
-> Is this commit related to a GitHub issue? (issue number / no / skip)
-
-- A number like `42` → ask one follow-up: "Comment only or close after commit? (comment / close)" — remember the chosen action
-- `no` or `skip` or empty input → no issue actions; do NOT ask again
-- Anything that doesn't parse as a number → treat as `no`
-
-### Carry-over
-
-Whatever was decided in Branch A / B / C, store it as `issue_action` for Step 3.5 to act on. If nothing was decided, `issue_action` is `none`.
-
-## Step 3 — Stage and commit
-
-Stage the specific files (not `git add .`). Use `git add <file1> <file2> ...` with the files identified in Step 1.
-
-Before staging, exclude:
-- any file or folder under `test/`, `tests/`, `__tests__/`, `spec/`, or `specs/`
-- any test file matching `*.test.*`, `*.spec.*`, `test_*`, or `*_test.*`
-- any file that looks like it contains secrets (`.env`, credentials, tokens)
-
-Flag excluded files to the user instead of staging them.
-
-Commit with the approved message: `git commit -m "<message>"`.
-
-Capture the commit hash from the commit output. The user will need it for Step 6. You can also run `git rev-parse --short HEAD` to get it.
-
-## Step 3.5 — Act on the issue reference (if any)
-
-If `issue_action` from Step 2.5 is `none`, skip this step entirely.
-
-Otherwise, do the following:
-
-1. Capture the short commit hash from Step 3.
-2. Construct a comment body:
-
-```
-> *This was generated by AI during commit.*
-
-Linked from commit `<short-hash>`: <commit message subject line>
-```
-
-3. Post the comment with `gh issue comment <N> --body "<body>"`.
-4. If `issue_action.action == "close"`, also run `gh issue close <N>`. Do NOT pass a comment to `gh issue close`; the comment was already posted in step 3.
-5. If either gh command fails (auth missing, issue doesn't exist, network error), DO NOT abort the workflow. Print the error to the user with a clear note: "Issue update failed — commit and journal entry are still complete. Re-run `gh issue comment <N>` manually if needed." Then continue.
-
-Safety:
-
-- Never use `gh issue close --comment` — comment first, then close, so a closing comment is always posted even if `gh close` later fails.
-- Never close an issue you couldn't successfully comment on.
-- Never push. The commit stays local; gh API calls are separate from `git push`.
-
-## Step 4 — Ensure docs/ is gitignored
-
-Read [`.gitignore`](.gitignore:1). The repo treats the entire `docs/` tree as local-only — nothing under `docs/` should ever be committed.
-
-If `.gitignore` does NOT contain a line matching `docs/` (with or without trailing slash), append this block to the end:
-
-```
-# Local documentation — never committed
-docs/
-```
-
-If `.gitignore` was modified, tell the user — but do NOT commit the gitignore change as part of this flow.
-
-If the user has staged any file under `docs/` in Step 3 by mistake, unstage it (`git restore --staged docs/<path>`) and warn them: "Files under `docs/` should not be committed. Unstaged."
-
-## Step 5 — Inspect existing docs/journal/ structure
-
-Look at the current shape of `docs/journal/` if it exists:
-
-- Run `ls -la docs/journal/` (or list it via tools).
-- Note the existing date subfolders and file naming pattern, if any. Match whatever convention is already in use.
-
-If `docs/journal/` does not exist yet, create it.
-
-## Step 6 — Create a dated subfolder and write the entry
-
-Determine today's date in `YYYY-MM-DD` format using `date +%Y-%m-%d`.
-
-Create `docs/journal/<YYYY-MM-DD>/` if it does not exist.
-
-Inside that folder, write a new markdown file named `<HH-MM>-<short-slug>.md` where:
-- `<HH-MM>` is the current local time in 24-hour format
-- `<short-slug>` is a kebab-case version of the commit summary (3–6 words max)
-
-Use this template for the entry:
-
-```md
-# <Commit summary>
-
-**Commit:** <full commit hash>
-**Short hash:** <short hash>
-**Date:** <YYYY-MM-DD HH:MM local time>
-
-## What changed
-
-<2–4 sentences describing what the commit changes. Plain English, not a file list.>
-
-## Why
-
-<1–3 sentences on the motivation. Pull from the conversation context if available.>
-
-## Notes for future me
-
-<Any gotchas, follow-ups, or things to revisit. One paragraph max. Skip the section if there's nothing worth saying.>
-```
-
-Fill in the placeholders from:
-- The commit hash from Step 3
-- The conversation context for "What changed" and "Why"
-
-## Step 7 — Confirm
-
-Tell the user:
-- Commit hash and message
-- Path to the journal entry just created
-- Whether `.gitignore` was updated
-- If `issue_action` was acted on: "Issue #N commented and closed." or "Issue #N commented." (whichever applies)
-
-End with: "All of `docs/` is gitignored, so this entry stays local."
-
-## Safety notes
-
-- Never run `git push`. Commits stay local.
-- Never use `--amend`, `--force`, or `reset --hard`.
-- If `git status` shows the working tree is clean, abort early: tell the user there's nothing to commit and skip the rest of the flow.
-- If files look like they contain secrets, flag them and skip staging them.
+Skill: `.roo/skills/engineering/commit-and-document/SKILL.md`
 
 $ARGUMENTS

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

@@ -6,11 +6,7 @@ mode: system-architect
 EXECUTION RULES (Run sequentially. Wait for user between phases):
 1. SHARPEN (Architect): Run skill `.roo/skills/engineering/grill-with-docs/SKILL.md`. Update docs.
    HARD STOP: Ask user to choose: Prototype OR skip to PRD.
-2. PROTOTYPE [Optional]:
-   - Architect summarizes the prototype question, constraints, relevant context, and expected decision.
-   - Architect MUST `switch_mode` -> `code-tweaker`.
-   - Tweaker executes the `/prototype` command workflow using `.roo/rules/01-command-protocol.md`.
-   - Tweaker MUST `switch_mode` -> `system-architect` with prototype result, run command/URL if any, files changed, and decision needed.
+2. PROTOTYPE [Optional]: Follow `.roo/rules-system-architect/01-feature-prototype.md` for the architect→tweaker handoff.
    HARD STOP: Wait for user verdict.
 3. PRD (Architect): Run skill `.roo/skills/engineering/to-prd/SKILL.md` using a 3-bullet summary of prior phases.
    HARD STOP: Ask "Ready to slice into issues?". Wait for approval.

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

@@ -4,127 +4,17 @@ argument-hint: <doc or area to update>
 mode: code-tweaker
 ---
 
-You are guiding the user through the **Update Docs** workflow. Use this when the goal is to make repo documentation match the current code.
+Update repo documentation so it matches the current code. Surgical edits only — read existing docs first, verify claims against code, never rewrite wholesale unless the existing doc is unsalvageable. Follow the skill exactly.
 
-This command edits repo docs such as:
-
-- `FLOW.md` files
-- `APP_MAP.md`
-- `ARCHITECTURE.md`
-- `README.md`
-- Other markdown docs that explain how code works
+Skill: `.roo/skills/engineering/update-docs/SKILL.md`
 
 Do NOT use this for:
 
-- Domain glossary terms — use `/grill-with-docs` instead
-- ADRs / architectural decisions — use `/grill-with-docs` or `/refactor` so ADRs are offered properly
+- Domain glossary terms — use `/grill-with-docs`
+- ADRs — use `/grill-with-docs` or `/refactor`
 - Local commit journal entries — use `/commit-and-document`
 - Read-only understanding — use `/explore`
 
-The user may pass a target doc or area as `$ARGUMENTS`, e.g.:
-
-- `apps/kikonnekt_w_sso/core/chat/FLOW.md`
-- `chat flow`
-- `documents flow`
-- `APP_MAP.md`
-- `ARCHITECTURE.md`
-
-If no target is provided, ask once: "Which documentation file or area should I update?"
-
-## Phase 1 — Identify target doc
-
-Infer or ask for the target documentation file.
-
-Prefer existing docs when possible:
-
-- For a subsystem flow, look for a nearby `FLOW.md`.
-- For app-wide navigation or module mapping, use `APP_MAP.md`.
-- For system-level structure and constraints, use `ARCHITECTURE.md`.
-- For setup or usage, use `README.md`.
-
-If the target doc does not exist, ask before creating it. Do not invent a new doc location silently.
-
-## Phase 2 — Read existing docs first
-
-Read the target doc fully before editing.
-
-Also read nearby related docs, if relevant:
-
-- Neighboring `FLOW.md` files
-- `APP_MAP.md`
-- `ARCHITECTURE.md`
-- `README.md`
-- Any module-local docs in the same subtree
-
-Goal: match the existing documentation style, section structure, vocabulary, and level of detail.
-
-## Phase 3 — Verify against code
-
-Inspect the code that the doc claims to describe. Update docs from code reality, not guesses.
-
-Check:
-
-- Entrypoints
-- Main functions/classes
-- Data flow
-- State changes
-- Side effects
-- Dependencies
-- Error/fallback paths
-- Files involved
-
-If a claim cannot be verified, either remove it or move it to an `Open questions` section. Do not present guesses as facts.
-
-## Phase 4 — Make surgical edits
-
-Do not rewrite the whole doc by default.
-
-Prefer surgical edits:
-
-- Keep useful existing sections
-- Update stale sections
-- Add missing flows
-- Remove false claims
-- Preserve heading style
-- Preserve existing tone and detail level
-
-Only rewrite the whole file if the current doc is too stale to salvage. If doing that, say why before editing.
-
-## Phase 5 — Add or update freshness block
-
-At the bottom of the doc, add or update this section if it fits the existing style:
-
-```md
-## Freshness
-
-Last checked against code: YYYY-MM-DD
-Relevant files checked:
-- `path/to/file.py`
-- `path/to/other_file.py`
-```
-
-Use today's date. Include only files actually inspected.
-
-## Phase 6 — Sanity check
-
-After editing:
-
-- Re-read the updated doc
-- Check referenced file paths exist
-- Ensure every major claim maps to code or a cited doc
-- Ensure no stale contradiction remains with nearby docs
-- Summarise what changed
-
-## Phase 7 — Recommend next step
-
-Recommend one next command:
-
-- `/explore` if the user still seems unsure how the area works
-- `/feature` if the docs update revealed a feature plan
-- `/refactor` if the docs update revealed tangled-but-working code
-- `/fix` if the docs update revealed a bug
-- `/commit-and-document` if the docs update is complete
-
-Do not auto-run the next command. The user chooses.
+If `$ARGUMENTS` is empty, ask once: "Which documentation file or area should I update?"
 
 $ARGUMENTS

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/02-three-failure-rule.md

@@ -0,0 +1,12 @@
+# Three-Failure Rule
+
+After 3 failed attempts at the same loop, test, hypothesis, or approach, stop and surface to the user rather than continuing.
+
+When stopping, include:
+
+- what was attempted
+- exact errors or evidence
+- the blocker
+- what input is needed to proceed
+
+Applies to TDD red-green cycles, diagnosis loops, architecture probes, and any other repeating task. Escalate via `switch_mode` or `attempt_completion` when running under another mode or orchestrator.

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

@@ -1,28 +1,27 @@
 # Manual Reply Protocol
 
-For workflow choices, put options in the suggestions, not in the question body. Map the chosen number back to a command privately.
+For workflow choices, ask the question in the message body and list numbered options.
 
-Suggestions:
+Clickable suggestions may use the plain-language option text, but must not contain slash commands, mode names, or executable routing text.
 
-- Descriptive labels OK.
-- No slash commands or mode names.
-- No per-option mode-switch indicator unless clicking that option really should switch modes. For "pick a number" routing questions, leave the indicator off.
-- Include a Hold/Skip option when relevant.
+Users may reply with either the number or the option text.
 
-Question body:
+Example:
 
-- One short prompt. Real newlines only; never the literal `\n`.
-- Do not restate the options.
+1. Tweak small implementation
+2. Diagnose bug
+3. Hold
 
-Typed numeric reply is always valid.
+Safe suggestions:
 
-Example:
+- Tweak small implementation
+- Diagnose bug
+- Hold
 
-Question: Pick a regression test option.
+Unsafe suggestions:
 
-1. Import-time sanity check
-2. Extract helper and unit-test
-3. AST guard test
-4. Hold
+- `/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 or the same test/approach fails 3 times.
+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

@@ -3,10 +3,36 @@
 Every delegated task must include:
 
 - command with slash
-- normalized command name
 - 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/rules-system-architect/02-completion.md

@@ -7,5 +7,3 @@ If created by `custom-orchestrator` via `new_task`, use `attempt_completion` whe
 Do not use `attempt_completion` to avoid required implementation work.
 
 Halt for explicit user approval before testing a bug hypothesis, finalizing an architecture plan, publishing issues, or making irreversible decisions.
-
-If diagnosis fails after 3 attempts, halt and request user intervention with attempts, evidence, and needed input.

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

@@ -0,0 +1,143 @@
+---
+name: commit-and-document
+description: Stage selected files, write a Conventional Commit, optionally link a GitHub issue, and append a dated journal entry under docs/journal/. Use when the user wants to commit work and capture a local record of what changed.
+---
+
+# Commit and Document
+
+Deterministic flow. Execute steps in order; do not deviate.
+
+## 1. Inspect git changes
+
+Run and read:
+
+- `git status --short`
+- `git diff --stat`
+- `git diff --cached --stat`
+
+Summarise: which files, what changed.
+
+If the working tree is clean, stop and report. Skip the rest.
+
+## 2. Propose a Conventional Commit
+
+One-line message:
+
+```
+<type>(<scope>): <short, action-focused summary>
+```
+
+- **type**: `feat`, `fix`, `refactor`, `docs`, `chore`, `test`, `style`, `perf`
+- **scope**: area touched. Omit parens if unclear.
+- **summary**: imperative, present tense, under 70 chars, starts with a verb.
+
+Show: proposed message, files to stage, files excluded (tests, docs, secrets). Ask: "Commit with this message? (yes / edit / cancel)". On `cancel`, stop and report.
+
+## 2.5 Detect or ask for an issue reference
+
+Silent pre-checks first:
+
+1. `git remote -v` → bail if no `github.com` remote.
+2. `command -v gh` → bail if `gh` is not installed.
+
+Detection on the proposed message:
+
+- Closing keywords: `Closes/Close/Closed/Fixes/Fix/Fixed/Resolves/Resolve/Resolved #N` (case-insensitive)
+- Bare `#N` anywhere
+
+Branches:
+
+- **A — closing keyword present**: ask "After commit, comment on issue #N and close it? (yes / no)". `yes` → `{action: close, issue: N}`.
+- **B — bare `#N`**: ask "After commit, post a progress comment on issue #N? (yes / no / close)". Map to `comment` / `close` / none.
+- **C — no reference**: ask once "Is this commit related to a GitHub issue? (issue number / no / skip)". On a number, ask "Comment only or close after commit? (comment / close)". Anything non-numeric → none.
+
+Carry the result as `issue_action` (default `none`).
+
+## 3. Stage and commit
+
+Stage explicit files with `git add <file>...` (never `git add .`). Exclude:
+
+- anything under `test/`, `tests/`, `__tests__/`, `spec/`, `specs/`
+- files matching `*.test.*`, `*.spec.*`, `test_*`, `*_test.*`
+- anything that looks like secrets (`.env`, credentials, tokens)
+
+Flag exclusions to the user.
+
+Commit with the approved message. Capture the short hash via `git rev-parse --short HEAD`.
+
+## 3.5 Act on the issue reference
+
+If `issue_action` is `none`, skip.
+
+Otherwise build:
+
+```
+> *This was generated by AI during commit.*
+
+Linked from commit `<short-hash>`: <commit subject>
+```
+
+Run `gh issue comment <N> --body "<body>"`. If `action == close`, then run `gh issue close <N>` (never `--comment`; comment first).
+
+If either fails, report the error and continue. Do not abort. Do not close an issue you could not comment on.
+
+## 4. Ensure docs/ is gitignored
+
+Read `.gitignore`. If no line matches `docs/`, append:
+
+```
+# Local documentation — never committed
+docs/
+```
+
+Do not commit the gitignore change. If the user accidentally staged anything under `docs/`, unstage it (`git restore --staged docs/<path>`) and warn.
+
+## 5. Inspect existing docs/journal/
+
+List `docs/journal/` if present; match its existing date/file convention. Create the directory if missing.
+
+## 6. Write a dated entry
+
+Date via `date +%Y-%m-%d`. Create `docs/journal/<YYYY-MM-DD>/` if missing. Write `<HH-MM>-<short-slug>.md` (kebab-case slug, 3–6 words from the summary). Template:
+
+```md
+# <Commit summary>
+
+**Commit:** <full hash>
+**Short hash:** <short hash>
+**Date:** <YYYY-MM-DD HH:MM local time>
+
+## What changed
+
+<2–4 sentences. Plain English, not a file list.>
+
+## Why
+
+<1–3 sentences on motivation, pulled from conversation context.>
+
+## Notes for future me
+
+<Gotchas/follow-ups, one paragraph max. Skip if nothing worth saying.>
+```
+
+## 7. Confirm
+
+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`.
+- Flag suspected secrets; do not stage them.
+- If `git status` is clean, abort early.

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

@@ -24,7 +24,6 @@ MUST build fast pass/fail loop. Try order:
 Rules:
 - MUST make loop faster/sharper/deterministic.
 - Flake: run 100x, parallelise, stress, add sleeps, raise repro rate.
-- 3 failed loop attempts → STOP; ask env/HAR/log/core/screen recording/temp prod instrumentation.
 
 ## 2. Reproduce
 
@@ -62,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

@@ -43,3 +43,14 @@ Detection:
 2. Else if root `CONTEXT.md`, use it.
 3. Else create root `CONTEXT.md` lazily on first resolved term.
 4. If context ambiguous, ask.
+
+## Companion docs
+
+Canonical names for code-explanation docs (read by `/explore`, edited by `/update-docs`):
+
+- `FLOW.md` — subsystem flow / data path; lives next to the code it describes.
+- `APP_MAP.md` — app-wide module/navigation map; root-level.
+- `ARCHITECTURE.md` — system-level structure, constraints, seams; root-level.
+- `README.md` — setup and usage; root-level.
+
+Use these names when creating new docs of these kinds. A subsystem may have its own `FLOW.md`; `APP_MAP.md` and `ARCHITECTURE.md` are typically singular per repo.

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

@@ -16,9 +16,17 @@ description: Grilling session that challenges your plan against the existing dom
 
 ## Docs
 
-- Single-context: root `CONTEXT.md`, root `docs/adr/`.
-- Multi-context: root `CONTEXT-MAP.md` → per-context `CONTEXT.md` + ADRs.
-- Create docs lazily only when recording needed.
+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
 

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

@@ -84,5 +84,4 @@ Include candidate name, one-sentence reason, anchor link.
 
 ## Vocabulary
 
-Use: module, interface, implementation, depth, deep, shallow, seam, adapter, leverage, locality.
-Avoid: component, service, unit, API, signature, boundary, layer, wrapper.
+See `LANGUAGE.md`.

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/setup-matt-pocock-skills/domain.md

@@ -11,22 +11,7 @@ If missing, proceed silently.
 
 ## Layouts
 
-Single-context:
-
-```text
-/CONTEXT.md
-/docs/adr/
-/src/
-```
-
-Multi-context:
-
-```text
-/CONTEXT-MAP.md
-/docs/adr/
-/src/{context}/CONTEXT.md
-/src/{context}/docs/adr/
-```
+See `.roo/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md` for layout and detection.
 
 ## Rules
 

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

@@ -33,7 +33,6 @@ Rules:
 - Public interface only.
 - Minimal code only.
 - No speculative features.
-- 3 failed green attempts → STOP; show blocker + exact error; ask user.
 
 ## Refactor
 
@@ -50,3 +49,23 @@ Checklist per cycle:
 - [ ] Test survives internal refactor.
 - [ ] 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.
+- `mocking.md` — when (and when not) to mock.
+- `interface-design.md` — designing testable interfaces.
+- `deep-modules.md` — interface vs implementation depth.
+- `refactoring.md` — refactor candidates after green.

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

@@ -0,0 +1,66 @@
+---
+name: update-docs
+description: Update repo documentation (flow, app map, architecture, README, module docs) so it matches current code. Use when docs are stale and need to be reconciled with the codebase.
+---
+
+# Update Docs
+
+Edit repo docs that explain how code works (flow docs, app/module maps, architecture overviews, README, module-local markdown). Surgical edits, not rewrites.
+
+## 1. Identify target
+
+Infer or ask for the target doc. Prefer existing docs over new ones:
+
+- Subsystem flow → nearby flow doc.
+- App-wide navigation/module map → app map doc.
+- System-level structure → architecture doc.
+- Setup/usage → `README.md`.
+
+If the doc does not exist, ask before creating. Never invent a new doc location silently.
+
+## 2. Read first
+
+Read the target fully before editing. Also read nearby related docs (neighbouring flow docs, app/architecture docs, README, module-local docs). Match the existing style, structure, vocabulary, and detail level.
+
+## 3. Verify against code
+
+Inspect the code the doc describes. Update from code reality, not guesses. Check entrypoints, main functions/classes, data flow, state changes, side effects, deps, error/fallback paths, files involved.
+
+Unverifiable claims → remove or move to an `Open questions` section. Never present guesses as facts.
+
+## 4. Surgical edits
+
+Default to small edits: keep useful sections, update stale ones, add missing flows, remove false claims, preserve heading style and tone. Rewrite the whole file only if it is too stale to salvage; if so, say why before editing.
+
+## 5. Freshness block
+
+If it fits the doc's style, add or update at the bottom:
+
+```md
+## Freshness
+
+Last checked against code: YYYY-MM-DD
+Relevant files checked:
+- `path/to/file.py`
+- `path/to/other_file.py`
+```
+
+Use today's date. Include only files actually inspected.
+
+## 6. Sanity check
+
+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": []
     }
   ]