@fernado03/zoo-flow 0.1.2 → 0.1.4

package/README.md

@@ -1,6 +1,6 @@
 # Zoo Flow
 
-> **Smoke-tested workflow control plane for [Zoo Code](https://docs.zoocode.dev/).**
+> **Workflow control plane for [Zoo Code](https://docs.zoocode.dev/).**
 
 A small, opinionated template that turns Zoo Code into a predictable
 mode + command + skill orchestrator. Three modes, a fixed routing
@@ -32,15 +32,7 @@ A timestamped backup is always written to `.zoo-flow-backup/` before
 overwrite.
 
 After install, reload VS Code (Command Palette → **Developer: Reload
-Window**), open Zoo Code, switch to `custom-orchestrator`, and try a
-small request like:
-
-> change a harmless comment in `README`
-
-Numbered choices are safe to click or type. Suggestions never carry
-slash commands or mode names, so they will not route you into another
-mode — see
-[`docs/troubleshooting.md`](docs/troubleshooting.md#clickable-suggestions-can-route-incorrectly).
+Window**) and open Zoo Code.
 
 > **Note**: `.roomodes`, `.roo/commands/`, and `.roo/rules-{mode-slug}/`
 > are kept as-is because they are the official Zoo Code configuration
@@ -55,6 +47,35 @@ skills know your tracker, labels, and domain layout. Skip it if you
 only plan to use `/tweak`, `/fix`, `/explore`, `/refactor`,
 `/diagnose`, `/prototype`, `/update-docs`, or `/commit-and-document`.
 
+## Using it
+
+Zoo Code switches modes automatically when you type a slash command,
+based on the `mode:` field in the command file. That gives you two
+ways to drive Zoo Flow, and the choice matters:
+
+- **Free-form request from `custom-orchestrator`** (no leading slash).
+  The orchestrator picks a workflow, proposes it as a numbered choice,
+  and delegates only after you confirm. Use this when you want the
+  router to think first. This is how `custom-orchestrator` is
+  designed to work.
+
+  > change a harmless comment in `README`
+
+- **Direct slash command from any mode.** The host switches you to
+  the command's configured mode and runs it, bypassing the
+  orchestrator entirely. Use this when you already know which
+  workflow you want.
+
+  > /tweak fix the typo in `README`
+
+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
 
 ```bash
@@ -118,13 +139,8 @@ need them.
 Command files live in
 [`templates/full/.roo/commands/`](templates/full/.roo/commands).
 
-## Smoke tests
-
-A short, fixed set of smoke tests in
-[`docs/smoke-tests.md`](docs/smoke-tests.md) verifies routing, mode
-boundaries, and skill loading. Worked examples:
+## Worked examples
 
-- [`examples/tweak-smoke-test.md`](examples/tweak-smoke-test.md)
 - [`examples/fix-flow.md`](examples/fix-flow.md)
 - [`examples/feature-flow.md`](examples/feature-flow.md)
 

package/bin/zoo-flow.js

@@ -246,7 +246,7 @@ ${didBackup ? `Backup:\n  ${backupDir}\n` : ""}Next:
   1. Reload VS Code
   2. Open Zoo Code
   3. Switch to custom-orchestrator
-  4. Smoke test:
+  4. Try a small request, e.g.:
        change a harmless comment in README
 
 When workflow choices appear, type the number manually, e.g. 1.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fernado03/zoo-flow",
-  "version": "0.1.2",
-  "description": "Smoke-tested workflow control plane for Zoo Code.",
+  "version": "0.1.4",
+  "description": "Workflow control plane for Zoo Code.",
   "type": "module",
   "bin": {
     "zoo-flow": "bin/zoo-flow.js"

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/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,27 +1,15 @@
 # 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 put only safe numbered options in suggestions.
 
-Suggestions:
+Safe options:
 
-- Descriptive labels OK.
-- No slash commands or mode names.
-- Include a Hold/Skip option when relevant.
+1. Tweak small implementation
+2. Diagnose bug
+3. Hold
 
-Question body:
+Do not put slash commands, mode names, or executable routing text in suggestions.
 
-- One short prompt. Real newlines only; never the literal `\n`.
-- Do not restate the options.
-
-Typed numeric reply is always valid.
-
-Example:
-
-Question: Pick a regression test option.
-
-1. Import-time smoke test
-2. Extract helper and unit-test
-3. AST guard test
-4. Hold
+Users may reply by typing the number.
 
 Only treat slash commands as commands when manually typed by the user.

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

@@ -4,4 +4,4 @@ Implement, test, update docs, prototype, and commit only after approval.
 
 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.

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

@@ -2,11 +2,7 @@
 
 Every delegated task must include:
 
-- command with slash
-- normalized command name
+- command with slash (e.g. `/refactor`)
 - user context
-- 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
 
 Ignore slash commands mentioned only inside subtask summaries.

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,131 @@
+---
+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."
+
+## 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
 

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,7 @@ 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.
 
 ## 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/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,11 @@ Checklist per cycle:
 - [ ] Test survives internal refactor.
 - [ ] Code minimal.
 - [ ] No speculation.
+
+## 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/update-docs/SKILL.md

@@ -0,0 +1,56 @@
+---
+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.
+
+## 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.