@fernado03/zoo-flow 0.4.0 → 0.5.0

package/README.md

@@ -18,8 +18,11 @@ Run this from the root of the project where you use Zoo Code:
 npx @fernado03/zoo-flow@latest init
 ```
 
-This copies only the runtime template (`.roomodes` and `.roo/`) into
-your project. It does not copy this repository's `docs/` folder.
+This copies the runtime template (`.roomodes` and `.roo/`) plus the
+`.zoo-flow/` starter docs into your project. It does not copy this
+repository's `docs/` folder. Zoo Flow also ensures `.zoo-flow/` is
+listed in `.gitignore` so local context docs stay out of normal
+commits.
 
 If `.roomodes` or `.roo/` already exist, Zoo Flow stops without
 overwriting. To back up and overwrite:
@@ -40,13 +43,25 @@ Window**) and open Zoo Code.
 
 ### Before using `/triage`, `/to-issues`, or `/to-prd`
 
-Switch to `code-tweaker` and run `/setup-matt-pocock-skills` once per
-repo. It seeds an `## Agent skills` block in `AGENTS.md` or
+Run `/setup-matt-pocock-skills` once per repo. It seeds an `## Agent skills` block in `AGENTS.md` or
 `CLAUDE.md` and a few files under `docs/agents/` so the issue and PRD
 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 Zoo Flow
+
+After installing this template, read:
+
+[`.zoo-flow/START_HERE.md`](templates/full/.zoo-flow/START_HERE.md)
+
+That file explains first-run initialization, when to run
+`/scaffold-context`, when to run `/setup-matt-pocock-skills`, and how
+to start normal work from Custom Orchestrator mode.
+
+For daily use, start in Custom Orchestrator mode and describe the
+task normally. Slash commands are optional power-user shortcuts.
+
 ## Using it
 
 Zoo Code switches modes automatically when you type a slash command,
@@ -163,9 +178,11 @@ If you would rather copy the template by hand:
 git clone https://github.com/Fernado03/zoo-flow.git /tmp/zoo-flow
 cp /tmp/zoo-flow/templates/full/.roomodes .
 cp -R /tmp/zoo-flow/templates/full/.roo .
+cp -R /tmp/zoo-flow/templates/full/.zoo-flow .
+grep -qxF ".zoo-flow/" .gitignore 2>/dev/null || printf "\n.zoo-flow/\n" >> .gitignore
 ```
 
-Windows uses `git clone ... C:\Temp\zoo-flow` and `Copy-Item` instead.
+Windows uses `git clone ... C:\Temp\zoo-flow` and `Copy-Item` (including `Copy-Item -Recurse` for `.zoo-flow\`) instead.
 
 ## Migration
 

package/bin/zoo-flow.js

@@ -106,21 +106,31 @@ function migrateRootContextDocs(projectRoot) {
   const rootContext = path.join(projectRoot, "CONTEXT.md");
   const targetContext = path.join(targetFlowDir, "CONTEXT.md");
   if (pathExists(rootContext) && !pathExists(targetContext)) {
-    fs.copyFileSync(rootContext, targetContext);
+    fs.renameSync(rootContext, targetContext);
     moved.push("CONTEXT.md");
   }
 
   const rootAdr = path.join(projectRoot, "docs", "adr");
   const targetAdr = path.join(targetFlowDir, "docs", "adr");
-  if (pathExists(rootAdr)) {
+  if (pathExists(rootAdr) && !pathExists(targetAdr)) {
     fs.mkdirSync(targetAdr, { recursive: true });
     copyRecursive(rootAdr, targetAdr);
+    removeRecursive(rootAdr);
     moved.push("docs/adr/");
   }
 
   return moved;
 }
 
+function copyZooFlowIfMissing(projectRoot) {
+  const target = path.join(projectRoot, ".zoo-flow");
+  if (pathExists(target)) return false;
+  const source = path.join(templateRoot, ".zoo-flow");
+  if (!pathExists(source)) return false;
+  copyRecursive(source, target);
+  return true;
+}
+
 function makeTimestamp() {
   return new Date().toISOString().replace(/[:.]/g, "-");
 }
@@ -307,21 +317,29 @@ Run again with --force to back up and overwrite:
   copyRecursive(sourceRoo, targetRoo);
 
   const didAddGitignore = appendZooFlowToGitignore(projectRoot);
+  const didAddZooFlow = copyZooFlowIfMissing(projectRoot);
+
+  const copiedLines = ["  - .roomodes", "  - .roo/"];
+  if (didAddZooFlow) {
+    copiedLines.push("  - .zoo-flow/CONTEXT.md");
+    copiedLines.push("  - .zoo-flow/docs/adr/0001-record-architecture-decisions.md");
+  }
+  if (didAddGitignore) {
+    copiedLines.push("  - appended .zoo-flow/ to .gitignore");
+  }
 
   console.log(`
 Zoo Flow installed.
 
 Copied:
-  - .roomodes
-  - .roo/
-  - .zoo-flow/CONTEXT.md
-  - .zoo-flow/docs/adr/0001-record-architecture-decisions.md
-${didAddGitignore ? "  - appended .zoo-flow/ to .gitignore\n" : ""}
-${didBackup ? `Backup:\n  ${backupDir}\n` : ""}Next:
-  1. Reload VS Code
-  2. Open Zoo Code
-  3. Switch to custom-orchestrator
-  4. Try a small request, e.g.:
+${copiedLines.join("\n")}
+${didBackup ? `\nBackup:\n  ${backupDir}\n` : ""}
+Next:
+  1. Open .zoo-flow/START_HERE.md (first-run guide)
+  2. Reload VS Code
+  3. Open Zoo Code
+  4. Switch to custom-orchestrator
+  5. 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",
   "description": "Workflow control plane for Zoo Code.",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "bin": {
     "zoo-flow": "bin/zoo-flow.js"

package/templates/full/.roo/commands/scaffold-context.md

@@ -0,0 +1,13 @@
+---
+description: "Bootstrap .zoo-flow/CONTEXT.md (and 0-2 starter ADRs) for an existing project by scanning code for domain terms and cross-cutting decisions. Shows proposed entries inline and asks for confirm before writing. Use when starting Zoo Flow on a project with no CONTEXT.md, or to expand a thin one."
+argument-hint: <optional focus area, e.g. "auth", "billing", or empty for whole project>
+mode: code-tweaker
+---
+
+EXECUTION RULES:
+1. APPLY the slot discovery rule from `.roo/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md` to find current CONTEXT.md, ADRs.
+2. IF `.zoo-flow/CONTEXT.md` exists and is non-empty, ASK: skip / merge (default) / replace. Skip = do nothing. Merge = add only new terms, never overwrite. Replace = full rewrite from scan.
+3. RUN skill: `.roo/skills/engineering/scaffold-context/SKILL.md` with the same focus area.
+4. DO NOT auto-launch any follow-up commands.
+
+$ARGUMENTS

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

@@ -1,5 +1,6 @@
 ---
 description: "Sets up an `## Agent skills` block in AGENTS.md/CLAUDE.md and `docs/agents/` so the engineering skills know this repo's issue tracker (GitHub or local markdown), triage label vocabulary, and domain doc layout. Run before first use of `to-issues`, `to-prd`, or `triage` — or if those skills appear to be missing issue tracker, triage label, or domain-doc configuration."
+mode: code-tweaker
 ---
 
 Run skill: `.roo/skills/engineering/setup-matt-pocock-skills/SKILL.md`

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

@@ -1,13 +1,29 @@
-# 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.
+# 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.
+
+## Domain-doc read gate
+
+Do not read CONTEXT.md, CONTEXT-MAP.md, FLOW.md, APP_MAP.md, ARCHITECTURE.md, or ADRs by default.
+
+Read domain docs only when at least one is true:
+
+- The task touches domain language or terminology.
+- The task changes public behavior.
+- The task changes architecture, module seams, persistence, API shape, auth, payments, security, migrations, or cross-module design.
+- The command explicitly requires those docs, such as `/feature`, `/refactor`, `/grill-with-docs`, `/scaffold-context`, or relevant `/update-docs`.
+- The user asks for documentation, architecture, product, or domain-context work.
+
+For low-risk localized edits, prefer code search and targeted file reads first.
+
+Missing CONTEXT.md or ADRs is not an error. Use the slot discovery rule in `.roo/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md` to detect what is present, and proceed silently when nothing is.

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

@@ -1,79 +1,54 @@
-# Orchestrator Routing
-
-The orchestrator is a router only.
-
-Do not inspect implementation files, edit files, run shell commands, or answer technical implementation questions directly.
-
-Delegate only with `new_task` to these exact slugs:
-
-- `code-tweaker`
-- `system-architect`
-
-The planning/architecture mode slug is always `system-architect`. Never use `architect`.
-
-After a subtask returns, summarize and stop. Do not auto-launch another subtask.
-
-## Routed commands
-
-| Command                | Mode             | Routed when the user wants to…                                        |
-| ---------------------- | ---------------- | --------------------------------------------------------------------- |
-| `/tweak`               | code-tweaker     | Make a small, known, low-risk change. Cause is understood.            |
-| `/tdd`                 | code-tweaker     | Build a unit of behavior test-first, red-green-refactor.              |
-| `/update-docs`         | code-tweaker     | Align existing docs with current code.                                |
-| `/commit-and-document` | code-tweaker     | Stage, write a Conventional Commit, journal the change.               |
-| `/prototype`           | code-tweaker     | Throw away code to resolve a design uncertainty.                      |
-| `/fix`                 | system-architect | Resolve a bug whose cause is unknown. Diagnose → fix → post-mortem.   |
-| `/feature`             | system-architect | Add new capability needing planning. Sharpen → PRD → slice → build.   |
-| `/refactor`            | system-architect | Improve working code's structure without changing behavior.          |
-| `/explore`             | system-architect | Map unfamiliar code before deciding what to do.                       |
-| `/triage`              | system-architect | Create, sort, or prepare issues in a tracker.                         |
-
-## Routing decision guide
-
-Read the request for intent, not keywords. Work top-down:
-
-1. **Unfamiliar territory?** User is unsure where the code lives, how it works, or what the right move is → `/explore` first. It produces a written map and recommends the next command.
-2. **Something is broken and the cause is unknown?** Error, crash, regression, "it used to work", flaky, slow → `/fix`. The diagnosis loop lives inside it.
-3. **New capability that needs planning?** Net-new behavior, multiple unknowns, or design questions → `/feature`.
-4. **Working code, structure is the problem?** "Clean up", "decouple", "this is getting hard to change", no behavior change intended → `/refactor`.
-5. **Small and well-understood?** Cause known, scope tight, no design questions → `/tweak`.
-6. **Test-first unit of behavior, cause/interface clear?** → `/tdd`.
-7. **Design uncertainty worth throwing code at?** → `/prototype`.
-8. **Docs drifted from code?** → `/update-docs`.
-9. **Ready to record finished work?** → `/commit-and-document`.
-10. **Issue/tracker management?** → `/triage`.
-
-## Disambiguation
-
-These pairs overlap. Choose by the distinguishing signal, not surface wording.
-
-- `/fix` vs `/tweak`: unknown cause needing diagnosis → `/fix`. Known cause, mechanical change → `/tweak`. If the user can name the exact line/function to change, it is `/tweak`.
-- `/fix` vs `/refactor`: behavior is wrong → `/fix`. Behavior is fine, structure hurts → `/refactor`.
-- `/feature` vs `/tdd`: needs sharpening, a PRD, or issue slicing → `/feature`. Interface and scope already clear, just build it test-first → `/tdd`.
-- `/feature` vs `/prototype`: committing to a real implementation → `/feature`. Resolving an open design question with throwaway code → `/prototype`.
-- `/refactor` vs `/tweak`: cross-cutting structural change with design tradeoffs → `/refactor`. One-spot localized edit → `/tweak`.
-- `/update-docs` vs `/commit-and-document`: aligning doc content with code → `/update-docs`. Recording a change you just made (commit + journal) → `/commit-and-document`.
-- Any of the above when the target area is unknown: route `/explore` first.
-
-## Confidence and presentation
-
-- If the user typed an explicit slash command, route it as-is. Do not second-guess it.
-- If one command clearly fits a free-form request, offer it as the single top choice with a one-line reason, plus one safe alternative when a near-tie exists.
-- If two commands genuinely tie, offer both as numbered choices and let the user pick.
-- Prefer the lighter-weight workflow when impact is comparable (`/tweak` over `/fix`, `/tdd` over `/feature`) — but never trade away a needed diagnosis or planning phase just to save tokens.
-- When suggesting choices, follow `.roo/rules/03-manual-reply-protocol.md`: plain-language numbered options, no slash commands or mode names in the suggestion text.
-
-## Approval gate
-
-The orchestrator proposes; the user approves; only then does the orchestrator delegate.
-
-- An explicitly typed slash command is itself the approval. Route it immediately.
-- A free-form request is never self-approving. Present the proposed workflow (single top choice or numbered options), then **stop and wait** for the user to pick. Do not call `new_task` on the same turn you propose a workflow.
-- Treat a free-form message as approval only when it selects a workflow you already proposed — by number, option text, or an unambiguous restatement. A fresh free-form request restarts the propose-and-wait cycle.
-- If you are unsure whether the user approved, ask. Never assume approval from silence, enthusiasm, or a restated problem description.
-
-## Delegation
-
-Delegate only after the approval gate is satisfied: the user typed an explicit slash command, or selected a workflow you proposed.
-
-When delegating, choose the safest proceed policy from `01-delegation-message.md`.
+# Orchestrator Routing
+
+Router only. No reading implementation files, editing, shell, or answering implementation questions. Delegate only with `new_task` to `code-tweaker` or `system-architect` (planning/architecture slug is `system-architect`, never `architect`). Summarize and stop after a subtask returns; do not auto-launch another.
+
+## Natural language first
+
+Users are not expected to know slash commands. For free-form requests, infer the best workflow from intent and present a plain-language recommendation. Slash commands are optional power-user overrides. Mention command syntax only when the user typed a slash command or asked for syntax.
+
+## User-facing workflow names
+
+Slash commands are internal routing labels unless the user explicitly typed one or asked for syntax. For free-form requests, use plain-language workflow names only: small implementation, test-first, diagnosis, feature planning, refactor planning, exploration, documentation update, commit and journal, prototype, issue triage. Never show slash commands as selectable options for free-form requests. Internal delegation may still use the slash command after approval.
+
+## Routed commands
+
+| Workflow             | Command                | Mode             |
+| -------------------- | ---------------------- | ---------------- |
+| small implementation | `/tweak`               | code-tweaker     |
+| test-first           | `/tdd`                 | code-tweaker     |
+| documentation update | `/update-docs`         | code-tweaker     |
+| commit and journal   | `/commit-and-document` | code-tweaker     |
+| prototype            | `/prototype`           | code-tweaker     |
+| diagnosis            | `/fix`                 | system-architect |
+| feature planning     | `/feature`             | system-architect |
+| refactor planning    | `/refactor`            | system-architect |
+| exploration          | `/explore`             | system-architect |
+| issue triage         | `/triage`              | system-architect |
+
+## Routing decision guide
+
+Read intent, not keywords. Top-down: 1. unknown code area or unclear next move → exploration; 2. broken behavior with unknown cause → diagnosis; 3. new capability needing design, PRD, issue slicing, or phase gates → feature planning; 4. working behavior but structure is the problem → refactor planning; 5. small known low-risk change → small implementation; 6. clear behavior and interface, user wants tests first → test-first; 7. throwaway design/state/UI uncertainty → prototype; 8. docs drift from code → documentation update; 9. finished work needs commit/journal → commit and journal; 10. issue creation, sorting, labels, or tracker workflow → issue triage.
+
+## Routing weight
+
+Prefer the lightest workflow that preserves correctness. Use small implementation for known, localized, low-risk changes. Do not use feature planning merely because code will be added. Do not use diagnosis when the cause and target change are already known. Do not use refactor planning for one-file cleanup without design tradeoffs. If the target area is unknown, choose exploration first.
+
+## Risk levels
+
+Use risk to choose the lightest safe workflow. Risk does not override command intent; explicit slash commands still route as-is. R1 copy/style/doc typo/one-line obvious edit → small implementation. R2 localized code change with known target → small implementation or test-first. R3 behavior change with clear interface → test-first. R4 cross-module change or design tradeoff → feature planning or refactor planning. R5 auth/payments/security/migrations/data loss/external API contracts → strict planning/diagnosis with explicit approval gates.
+
+## Disambiguation
+
+Diagnosis vs small implementation: unknown cause → diagnosis; known cause → small implementation. Diagnosis vs refactor planning: wrong behavior → diagnosis; working behavior but bad structure → refactor planning. Feature planning vs test-first: needs sharpening/PRD/issues → feature planning; clear interface/behavior → test-first. Feature planning vs prototype: real implementation → feature planning; throwaway design check → prototype. Refactor planning vs small implementation: cross-module design tradeoff → refactor planning; localized edit → small implementation. Documentation update vs commit and journal: align docs with code → documentation update; record finished work → commit and journal. Unknown target area beats all: choose exploration first.
+
+## Confidence and presentation
+
+Explicit slash command from user = approval; route as-is. Clear free-form request = recommend one plain-language workflow plus one safe alternative if useful. Genuine tie = offer numbered plain-language choices. Prefer lighter workflow when safe, but do not skip needed diagnosis, planning, or approval. Follow `.roo/rules/03-manual-reply-protocol.md`: no slash commands, mode names, or executable routing text in selectable options. Good free-form option: 1. Make the small implementation change; 2. Explore the area first. Bad free-form option: 1. `/tweak`; 2. `/explore`.
+
+## Approval gate
+
+The orchestrator proposes; the user approves; then the orchestrator delegates. Explicit slash command = approval; route immediately. Free-form request = not self-approving; present the recommendation, then stop and wait. Treat replies as approval only when they select the proposed workflow by number, option text, or clear restatement. A fresh free-form request restarts routing. If unsure whether the user approved, ask.
+
+## Delegation
+
+Delegate only after the approval gate is satisfied. Choose the safest proceed policy from `01-delegation-message.md`.

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

@@ -1,40 +1,62 @@
-# Delegation Message
-
-A delegated task is the **entire command chain** — every phase and mode switch the command body defines, run to its final phase. A worker returns via `attempt_completion` only after that final phase. Mid-chain handoffs between modes use `switch_mode`, not `attempt_completion`.
-
-Every delegated task must include:
-
-- 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
+# Delegation Message
+
+A delegated task is the **entire command chain** — every phase and mode switch the command body defines, run to its final phase. A worker returns via `attempt_completion` only after that final phase. Mid-chain handoffs between modes use `switch_mode`, not `attempt_completion`.
+
+## Compact delegation template
+
+Use this shape unless the task needs more detail:
+
+```
+Task:
+Command:
+Proceed policy:
+Context hints:
+Allowed scope:
+Must follow:
+- `.roo/rules/01-command-protocol.md`
+- relevant command file
+- referenced skill only
+Completion must include:
+- files inspected/changed
+- commands/tests run
+- status
+- blockers
+- recommended next command
+```
+
+Fields expand as:
+
+- **Task** — what the user asked for, in plain language.
+- **Command** — the slash command being delegated, with leading slash.
+- **Proceed policy** — one of the three policies below.
+- **Context hints** — known files, symbols, line ranges, or search terms when available. Pass paths, not file bodies.
+- **Allowed scope** — what the worker may edit or read, when it is not "the whole repo".
+
+Do not paste long rule bodies, command bodies, or file contents into delegation messages. Pass paths, symbols, search terms, and decisions instead.
+
+The receiving worker already loads `.roo/rules/01-command-protocol.md` and `.roo/rules/00-paths.md` on every turn. Reminders are not needed for those, but command-file and skill-path pointers still help when the worker has not loaded them yet.
+
+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/skills/engineering/scaffold-context/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: scaffold-context
+description: Bootstrap .zoo-flow/CONTEXT.md from an existing codebase by detecting project shape and scanning for domain terms and cross-cutting decisions. Proposes 5-12 terms + 0-2 ADRs, asks for confirm before writing. Use on projects with no CONTEXT.md, or to expand a thin one.
+---
+
+# Scaffold Context
+
+## Loop
+
+1. Read existing context via slot discovery rule (see `CONTEXT-FORMAT.md`).
+2. Detect project shape (see Detection).
+3. Scan codebase for terms (see Detection).
+4. Propose 5-12 terms with one-line definitions + evidence (file:line counts).
+5. Show inline, ask: confirm / edit / cancel.
+6. On confirm, write to `.zoo-flow/CONTEXT.md` (preserve any existing entries in merge mode).
+7. If 1-2 cross-cutting decisions are visible in code, propose ADRs (see ADR gate).
+8. Show ADR draft(s) inline, ask confirm per ADR.
+9. On confirm, write to `.zoo-flow/docs/adr/NNNN-slug.md` using `ADR-FORMAT.md` numbering.
+10. Report what was written, with file paths.
+
+## Detection
+
+### Step 1: Detect project shape
+
+Inspect (in order):
+- `package.json` `keywords`, `name`, `scripts` (Node/JS)
+- `pyproject.toml` / `setup.py` / `setup.cfg` (Python)
+- `Cargo.toml` (Rust)
+- `go.mod` (Go)
+- Top-level folder names
+- `README.md` first paragraph
+
+Pick the dominant shape:
+
+| Signal folders / files | Shape | Priority sources for terms |
+|---|---|---|
+| `app/`, `pages/`, `routes/`, `controllers/`, `api/` | web app | API routes, page names, URL paths, model types |
+| `lib/`, `pkg/`, `src/` (no `app/`) | library | exported types, public API surface |
+| `cmd/`, `bin/`, `commands/`, `cli/` | CLI tool | subcommand names, flag names |
+| `workers/`, `jobs/`, `tasks/`, `etl/`, `pipelines/` | data pipeline | job/queue/event names |
+| `services/`, `lambda/`, `functions/`, `handlers/` | serverless | function names, event sources, triggers |
+| `services/` + `web/` + `workers/` | monorepo | treat each top-level as a sub-shape; ask user if unclear |
+
+If signals are mixed, prefer the shape that owns the entry point (`main.*`, `index.*`, `server.*`).
+
+### Step 2: Extract candidate terms
+
+For the chosen shape, prefer:
+- **Web app**: route paths (`/accounts/:id`), controller class names, view/component names
+- **Library**: exported type/class/interface names
+- **CLI**: subcommand names, top-level argument names
+- **Data pipeline**: job names, queue names, event types
+- **Serverless**: function names, event source names
+
+Universal signals (any shape):
+- Type/class/struct/interface definitions with noun names
+- Database table/model names (migrations, `schema.prisma`, `models/`, SQL files)
+- Top-level module/folder names that are nouns
+- README/docs that state purpose ("we manage X for Y")
+
+### Step 3: Filter
+
+Drop without showing:
+- Generic: `utils`, `helpers`, `common`, `base`, `lib`, `core`, `misc`, `types`, `models`, `helpers`, `shared`, `internal`, `errors`, `tests`
+- Single-letter or unexpanded acronym: `T`, `M`, `VM`, `DTO` (unless defined in code)
+- Already-defined terms in existing `CONTEXT.md` (merge mode)
+- Framework-required boilerplate: `App`, `Server`, `Router`, `Config`
+
+Keep candidates that:
+- Appear in 2+ distinct files OR
+- Appear in 1 file but are central (entry point, root config, README)
+- Are domain nouns (Account, Order, Tenant, Invoice) over technical nouns (Worker, Queue)
+
+### Step 4: Score and rank
+
+For each kept candidate, count:
+- Type/def files where it appears
+- Route/file references
+- DB schema references
+
+Take the top 5-12. Show the count in the proposal so the user can judge.
+
+## ADR gate
+
+Propose an ADR only if ALL:
+- You can point at code: a single pattern/import/module used across N+ files
+- The pattern is not obvious from the framework (e.g. "uses Express" is obvious, "all errors go through `Result<T, AppError>`" is not)
+- A reasonable engineer would be surprised to learn it from scratch
+- It maps to `ADR-FORMAT.md` "Qualifies" criteria (hard to reverse, real trade-off)
+
+Do NOT propose ADRs for:
+- Framework defaults
+- Single-file patterns
+- Speculative "this might be a decision" guesses
+- Anything where the README doesn't hint at reasoning
+
+Cap at 0-2 ADRs per scaffold. Zero is fine. Better to ship no ADR than a wrong one.
+
+## MUST
+
+- Ask confirm before writing `CONTEXT.md` (show full proposed list + diff against existing)
+- Ask confirm per ADR before writing
+- Never overwrite non-empty `CONTEXT.md` without explicit "replace"
+- Never invent cross-cutting decisions; only propose ADRs you can point at code
+- Keep `CONTEXT.md` glossary-only; no impl/spec notes
+- Use `ADR-FORMAT.md` for any proposed ADR (template + numbering)
+- Report file paths and section headers at the end
+- In merge mode, append new terms below existing ones; do not reorder
+
+## Context economy
+
+Before broad reads, locate candidates with `list_files`, `search_files`, or `codebase_search`.
+
+Prefer targeted `read_file` ranges or block reads once the candidate 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.
+
+## Output shape (for the inline confirm step)
+
+```
+## Proposed CONTEXT.md entries (N)
+
+1. **Account** — a tenant-scoped record of a customer relationship.
+   Evidence: 12 type defs, 4 routes, 1 DB table.
+2. **Order** — a request to purchase one or more SKUs.
+   Evidence: 8 type defs, 3 routes, 1 DB table.
+...
+
+Confirm? (yes / edit / cancel)
+```
+
+```
+## Proposed ADR (1 of N)
+
+# Use Result type for all fallible operations
+
+We use a Rust-style `Result<T, AppError>` for all operations that can
+fail, instead of throwing exceptions. This is enforced by a linter
+rule and visible in every service module.
+
+Considered Options:
+- Exceptions
+- Error codes (Go-style)
+- Result type (chosen)
+
+Consequences: easier to reason about error paths; verbose for happy
+paths.
+
+Confirm? (yes / edit / cancel)
+```

package/templates/full/.roomodes

@@ -4,9 +4,9 @@
       "slug": "code-tweaker",
       "name": "⚡ Code Tweaker",
       "roleDefinition": "You are an Execution Specialist. You implement, test, update docs, prototype, and commit when explicitly approved.",
-      "whenToUse": "Use for direct implementation, CSS/UI changes, TDD loops, documentation updates, runnable prototypes, known fixes, and local commits.",
+      "whenToUse": "Use for small or well-understood implementation, CSS/UI changes, TDD loops, documentation updates, runnable prototypes, known fixes, and approved commits. Do not make broad architecture decisions.",
       "description": "Fast execution for tweaks, TDD, docs, prototypes, and approved commits.",
-      "customInstructions": "Use `.roo/rules-code-tweaker/` for mode-specific behavior.\n\nPermitted commands: /tweak, /tdd, /update-docs, /commit-and-document, /prototype.\n\nFollow `.roo/rules/01-command-protocol.md` to load and execute commands. Follow `.roo/rules/00-paths.md` for path safety. Follow `.roo/rules/03-manual-reply-protocol.md` when asking the user to choose, approve, or continue.\n\nIf assigned any other command, stop and report the routing error.",
+      "customInstructions": "Use `.roo/rules-code-tweaker/` for mode-specific behavior.\n\nPermitted commands: /tweak, /tdd, /update-docs, /commit-and-document, /prototype, /scaffold-context.\n\nFollow `.roo/rules/01-command-protocol.md` to load and execute commands. Follow `.roo/rules/00-paths.md` for path safety. Follow `.roo/rules/03-manual-reply-protocol.md` when asking the user to choose, approve, or continue.\n\nIf assigned any other command, stop and report the routing error.",
       "groups": [
         "read",
         "edit",
@@ -18,7 +18,7 @@
       "slug": "system-architect",
       "name": "🏗️ System Architect",
       "roleDefinition": "You are a System Architect. You plan, diagnose, explore, triage, and design. You do NOT write implementation code.",
-      "whenToUse": "Use for complex debugging (/fix), feature planning (/feature), architecture changes (/refactor), issue triage (/triage), and codebase exploration (/explore).",
+      "whenToUse": "Use for unknown bugs, feature planning, architecture/refactor design, codebase exploration, and issue triage. Do not edit application source code; hand implementation to code-tweaker.",
       "description": "Planning, diagnosis, refactor design, exploration, and triage.",
       "customInstructions": "Use `.roo/rules-system-architect/` for mode-specific behavior.\n\nPermitted commands: /feature, /fix, /refactor, /explore, /triage.\n\nFollow `.roo/rules/01-command-protocol.md` to load and execute commands. Follow `.roo/rules/00-paths.md` for path safety. Follow `.roo/rules/03-manual-reply-protocol.md` when asking the user to choose, approve, or continue.\n\nIf assigned any other command, stop and report the routing error.",
       "groups": [
@@ -38,7 +38,7 @@
       "slug": "custom-orchestrator",
       "name": "🪃 Custom Orchestrator",
       "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.",
+      "whenToUse": "Use as the default entry mode for normal user requests. Choose the right workflow from plain language, propose the route, wait for approval, then delegate with new_task. Use slash commands only when the user explicitly invokes them.",
       "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. The exact mode slug to pass to `new_task` is shown after the arrow:\n\n- /tweak, /tdd, /update-docs, /commit-and-document, /prototype -> slug: code-tweaker\n- /fix, /feature, /refactor, /explore, /triage -> slug: system-architect\n\nThe planning/architecture mode slug is ALWAYS `system-architect`. Never use `architect`.\n\nPropose, then wait for approval before delegating. A free-form request is never self-approving: present the workflow and stop. Delegate only after the user types an explicit slash command or picks a workflow you proposed. See `.roo/rules-custom-orchestrator/00-routing.md` (Approval gate).\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": []

package/templates/full/.zoo-flow/START_HERE.md

@@ -0,0 +1,61 @@
+# Zoo Flow Quick Start
+
+## After installation
+
+1. Start in Custom Orchestrator mode.
+
+2. For an existing project, bootstrap project context:
+
+   `/scaffold-context`
+
+   This scans the codebase and proposes initial `.zoo-flow/CONTEXT.md` terms plus optional starter ADRs. It asks before writing anything.
+
+3. If you plan to use PRDs, issue slicing, or triage, configure agent skill metadata:
+
+   `/setup-matt-pocock-skills`
+
+   This sets up issue tracker, triage label, and domain-doc configuration used by PRD, issue, and triage workflows.
+
+4. After that, describe tasks normally. You do not need slash commands unless you already know the workflow.
+
+## First-run checklist
+
+- [ ] Custom Orchestrator mode is selected.
+- [ ] Run `/scaffold-context` for an existing codebase.
+- [ ] Run `/setup-matt-pocock-skills` if using PRDs, issue slicing, or triage.
+- [ ] Start normal work by describing the task in plain language.
+
+## Common requests
+
+| What you want | What Zoo Flow will likely do |
+|---|---|
+| Small obvious edit | Small implementation workflow |
+| Known localized fix | Small implementation workflow |
+| Bug with unknown cause | Diagnosis workflow |
+| New feature needing planning | Feature planning workflow |
+| Improve structure without behavior change | Refactor workflow |
+| Understand unfamiliar area | Exploration workflow |
+| Write tests first | TDD workflow |
+| Update docs | Documentation workflow |
+| Commit finished work | Commit + journal workflow |
+
+## What the orchestrator will show you
+
+For normal requests, the orchestrator should recommend plain-language workflows, not slash commands.
+
+Example:
+
+> "This looks like a small implementation change. Proceed?"
+
+Slash commands below are optional shortcuts for users who already know the workflow.
+
+## Power-user shortcuts
+
+You may type slash commands directly when you already know the workflow, but this is optional.
+
+Examples:
+
+- `/tweak change button copy`
+- `/fix checkout crashes after payment`
+- `/feature add team invitations`
+- `/refactor simplify auth service`

package/templates/full/.zoo-flow/evals/no-regression-checklist.md

@@ -0,0 +1,23 @@
+# Zoo Flow No-Regression Checklist
+
+Before accepting workflow changes, verify:
+
+- [ ] Users can start in Custom Orchestrator and describe tasks normally.
+- [ ] Slash commands are optional power-user overrides.
+- [ ] No `/choose` command exists.
+- [ ] Free-form requests require route proposal and user approval before delegation.
+- [ ] Explicit slash commands route immediately.
+- [ ] Orchestrator delegates only with `new_task`.
+- [ ] Orchestrator delegates only to `code-tweaker` or `system-architect`.
+- [ ] Code Tweaker does not make architecture decisions.
+- [ ] System Architect does not edit application source code.
+- [ ] CONTEXT.md / ADRs are read only when useful or command-required.
+- [ ] Small known changes prefer the lightest safe workflow.
+- [ ] High-risk changes keep approval gates.
+- [ ] Commit and push still require explicit approval.
+- [ ] Free-form routing recommendations use plain-language workflow names, not slash command names.
+- [ ] Slash command names appear only when the user explicitly invokes them, asks for syntax, or inside internal delegation context.
+- [ ] README links to `.zoo-flow/START_HERE.md`.
+- [ ] README does not duplicate the full Zoo Flow onboarding guide.
+- [ ] `.zoo-flow/START_HERE.md` remains the source of truth for first-run initialization.
+- [ ] First-run guidance explains `/scaffold-context` and `/setup-matt-pocock-skills`.

package/templates/full/.zoo-flow/evals/routing-cases.md

@@ -0,0 +1,187 @@
+# Routing Eval Cases
+
+Use these cases to check whether the orchestrator chooses the expected workflow.
+
+In every case:
+
+- The user did **not** type a slash command.
+- A free-form request is never self-approving. The orchestrator proposes, then waits.
+- Slash commands, mode names, and executable routing text must not appear in clickable suggestions.
+- Slash commands are optional. The user should never be told to type one to use Zoo Flow.
+
+## Case 1 — Tiny copy change
+
+User:
+"Change the Save button text to Submit."
+
+Expected:
+Recommend the small implementation workflow.
+
+Must not:
+- Route to feature.
+- Read architecture docs by default.
+- Ask the user to type a slash command.
+
+## Case 2 — Unknown crash
+
+User:
+"Checkout randomly crashes after payment. It used to work."
+
+Expected:
+Recommend the diagnosis workflow.
+
+Must:
+- Reproduce before hypothesizing.
+- Present hypotheses before fix.
+
+## Case 3 — New capability
+
+User:
+"Add team invitations with email invites and pending invite states."
+
+Expected:
+Recommend feature planning.
+
+Must:
+- Plan before implementation.
+- Use phase gates.
+
+## Case 4 — Structural cleanup
+
+User:
+"The auth module is getting hard to change. I want to decouple provider-specific logic."
+
+Expected:
+Recommend refactor workflow.
+
+Must:
+- Preserve behavior.
+- Explore architecture candidates before implementation.
+
+## Case 5 — Unknown area
+
+User:
+"I need to change billing but I don't know where that logic lives."
+
+Expected:
+Recommend exploration first.
+
+Must:
+- Produce a map before choosing feature/fix/refactor.
+
+## Case 6 — Known mechanical fix
+
+User:
+"The env var name changed from API_KEY to ZOO_API_KEY. Update the config loader."
+
+Expected:
+Recommend small implementation workflow.
+
+Must not:
+- Route to diagnosis.
+- Route to feature.
+
+## Case 7 — TDD with clear interface
+
+User:
+"Add a slugify helper for article URLs. I want it test-first."
+
+Expected:
+Recommend TDD workflow.
+
+Must:
+- Write the failing test first.
+- Confirm the public interface (input, output, edge cases) is clear before coding.
+
+## Case 8 — Stale documentation
+
+User:
+"The ARCHITECTURE.md file describes a checkout flow we removed last quarter. Bring it in line with the code."
+
+Expected:
+Recommend the documentation update workflow.
+
+Must:
+- Audit code first, then make surgical doc edits.
+- Not rewrite the file wholesale.
+
+## Case 9 — Ready to commit
+
+User:
+"I finished the small tweak. Please commit it and add a journal entry."
+
+Expected:
+Recommend the commit + journal workflow.
+
+Must:
+- Propose a Conventional Commit message and wait for approval before running `git commit` or `git push`.
+
+## Case 10 — Issue triage
+
+User:
+"We have 30 incoming bug reports from the support team. Triage them into the issue tracker."
+
+Expected:
+Recommend the triage workflow.
+
+Must:
+- Ask before publishing, labeling, closing, or making any irreversible tracker change.
+
+## Case 11 — Throwaway design probe
+
+User:
+"I'm not sure if the new search ranking should run inline or in a queue. Can we try both and see?"
+
+Expected:
+Recommend a throwaway prototype.
+
+Must:
+- Keep the work on a prototype branch or `.scratch/prototypes/<slug>/` so it is clearly throwaway.
+- Resolve the design question, not commit to a real implementation.
+
+## Case 12 — Explicit slash command
+
+User:
+"/tweak rename the cancel button to close."
+
+Expected:
+Route immediately. Do not second-guess the explicit command.
+
+Must not:
+- Repropose the workflow as a numbered choice.
+- Treat the explicit command as if approval were still pending.
+
+## Case 13 — Ambiguous "fix" for a known mechanical change
+
+User:
+"Fix the typo in the cancel-button label and update the aria-label to match."
+
+Expected:
+Recommend the small implementation workflow, not diagnosis.
+
+Must:
+- Recognize the cause and target are known.
+- Not run a full diagnosis loop for a one-line copy fix.
+
+## Case — Free-form request must not expose slash commands
+
+User:
+"Change the Save button text to Submit."
+
+Expected:
+Recommend the small implementation workflow in plain language.
+
+Good response:
+"This looks like a small implementation change because the target is known and the risk is low.
+
+1. Make the small implementation change
+2. Explore the area first"
+
+Must not:
+- Say "use `/tweak`" in the user-facing recommendation.
+- Offer `/tweak` as a selectable option.
+- Tell the user to type a slash command.
+
+Allowed:
+- Internally delegate using `/tweak` after the user approves.
+- Mention slash commands only if the user explicitly asks for command syntax.