@fernado03/zoo-flow 0.5.2 → 0.7.0

package/README.md

@@ -1,11 +1,13 @@
 # Zoo Flow
 
-> **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
-matrix, a command protocol, and path-safety rules. Drop it into a
-workspace and your AI assistant stops freelancing.
+> **Workflow control plane for [Zoo Code](https://docs.zoocode.dev/).**
+
+Zoo Flow is a Zoo Code workflow-control template.
+
+It does not try to be a giant skills pack. It makes Zoo Code predictable:
+free-form requests are routed through Custom Orchestrator, risky work gets
+planning gates, implementation stays in Code Tweaker, architecture stays in
+System Architect, and every command follows a small command/skill contract.
 
 For the deeper rationale, see [`docs/overview.md`](docs/overview.md)
 and [`docs/philosophy.md`](docs/philosophy.md).
@@ -20,9 +22,9 @@ npx @fernado03/zoo-flow@latest init
 
 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.
+repository's `docs/` folder. Zoo Flow also ensures `.roo/`, `.roomodes`, and `.zoo-flow/` are
+listed in `.gitignore` so generated config and local context docs stay
+out of normal commits.
 
 If `.roomodes` or `.roo/` already exist, Zoo Flow stops without
 overwriting. To back up and overwrite:
@@ -34,62 +36,53 @@ npx @fernado03/zoo-flow@latest init --force
 A timestamped backup is always written to `.zoo-flow-backup/` before
 overwrite.
 
-After install, reload VS Code (Command Palette → **Developer: Reload
-Window**) and open Zoo Code.
+After install, reload VS Code (Command Palette → **Developer: Reload
+Window**) and open Zoo Code.
+
+## Validate Install
+
+Use this inside a project after install or update:
+
+```bash
+npx @fernado03/zoo-flow@latest doctor
+```
 
 > **Note**: `.roomodes`, `.roo/commands/`, and `.roo/rules-{mode-slug}/`
 > are kept as-is because they are the official Zoo Code configuration
 > paths. Zoo Flow does not introduce a `.zoo/` directory.
 
-### Before using `/triage`, `/to-issues`, or `/to-prd`
-
-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,
-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).
+## Using Zoo Flow
+
+First run:
+
+- Read [`.zoo-flow/START_HERE.md`](templates/full/.zoo-flow/START_HERE.md).
+- Run `/scaffold-context` when the project needs local context docs.
+- Run `/setup-matt-pocock-skills` when tracker or triage config is needed.
+
+Daily use:
+
+- Start in `custom-orchestrator`.
+- Describe the task normally.
+- The orchestrator proposes a plain-language workflow.
+- Approve by number or option text.
+
+Power-user path:
+
+- Type a slash command directly when you already know the workflow.
+- Zoo Code switches mode from the command file's `mode:` field.
+
+Safety:
+
+- Workflow choices must be plain language.
+- Clickable choices must not include slash commands or mode names.
+- Explicit slash commands count as approval.
+- Free-form requests do not self-approve.
+
+When Zoo Flow asks a workflow question, reply by typing the number, for
+example `1`. See
+[`docs/troubleshooting.md`](docs/troubleshooting.md#clickable-suggestions-can-route-incorrectly).
+
+For team usage and deciding what to commit, see `docs/team-mode.md`.
 
 ## Update
 
@@ -105,13 +98,17 @@ template. Preview with `--dry-run`.
 
 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.
 
+## Token discipline
+
+Domain docs (`.zoo-flow/CONTEXT.md`, `.zoo-flow/docs/adr/`) are never read by default. They are loaded only when the task touches domain language, changes public behavior, or crosses architecture/auth/persistence seams. All runtime files (rules, commands, skills) have tiered token budgets enforced by `scripts/token-budget.js`.
+
 ## Modes
 
-| Slug                  | Name                  | Role                                                       | Edits allowed                                  | Delegation                                  |
-| --------------------- | --------------------- | ---------------------------------------------------------- | ---------------------------------------------- | ------------------------------------------- |
-| `custom-orchestrator` | 🪃 Custom Orchestrator | Router. Picks workflow, delegates, waits for the user.     | None                                           | `new_task` to architect or tweaker          |
-| `system-architect`    | 🏗️ System Architect   | Planning, diagnosis, refactor design, exploration, triage. | Markdown, `.scratch/`, `docs/`                 | `switch_mode` to tweaker in same window     |
-| `code-tweaker`        | ⚡ Code Tweaker        | Implementation, TDD, docs updates, prototypes, commits.    | Full repo edits within the assigned command    | `switch_mode` to architect in same window   |
+| Slug                  | Name                  | Role                                                       | Edits allowed                                  | Delegation                                  |
+| --------------------- | --------------------- | ---------------------------------------------------------- | ---------------------------------------------- | ------------------------------------------- |
+| `custom-orchestrator` | 🪃 Custom Orchestrator | Router. Picks workflow, delegates, waits for the user.     | None                                           | `new_task` to Zoo Flow modes only           |
+| `system-architect`    | 🏗️ System Architect   | Planning, diagnosis, refactor design, exploration, review. | Markdown, `.scratch/`, `docs/`                 | `switch_mode` to `code-tweaker`             |
+| `code-tweaker`        | ⚡ Code Tweaker        | Implementation, TDD, verify, docs, prototypes, commits.    | Full repo edits within the assigned command    | `switch_mode` to `system-architect`         |
 
 Modes are defined in
 [`templates/full/.roomodes`](templates/full/.roomodes). The detailed
@@ -131,12 +128,14 @@ run directly inside `system-architect` or `code-tweaker` when needed.
 | `/tdd`                   | `code-tweaker`       | Test-first implementation loop.                             |
 | `/prototype`             | `code-tweaker`       | Throwaway prototype to settle a design uncertainty.         |
 | `/update-docs`           | `code-tweaker`       | Reconcile docs with code reality.                           |
-| `/commit-and-document`   | `code-tweaker`       | Stage, message, commit, journal — pauses for approval.      |
-| `/fix`                   | `system-architect`   | Diagnose → implement → post-mortem chain.                   |
-| `/feature`               | `system-architect`   | Sharpen → optional prototype → PRD → issues → TDD chain.    |
-| `/refactor`              | `system-architect`   | Plan and stage architecture changes.                        |
-| `/explore`               | `system-architect`   | Map unfamiliar code before touching it.                     |
-| `/triage`                | `system-architect`   | Clean and prioritize an issue queue.                        |
+| `/commit-and-document`   | `code-tweaker`       | Stage, message, commit, journal — pauses for approval.      |
+| `/verify`                | `code-tweaker`       | Run targeted tests, typecheck, lint, or build checks.       |
+| `/fix`                   | `system-architect`   | Diagnose → implement → post-mortem chain.                   |
+| `/feature`               | `system-architect`   | Sharpen → optional prototype → PRD → issues → TDD chain.    |
+| `/refactor`              | `system-architect`   | Plan and stage architecture changes.                        |
+| `/explore`               | `system-architect`   | Map unfamiliar code before touching it.                     |
+| `/triage`                | `system-architect`   | Clean and prioritize an issue queue.                        |
+| `/review`                | `system-architect`   | Review a diff or branch before commit.                      |
 
 ### Helper (run directly when needed)
 
@@ -148,27 +147,31 @@ run directly inside `system-architect` or `code-tweaker` when needed.
 | `/to-prd`                        | `system-architect`   | Turn sharpened context into a PRD.                          |
 | `/to-issues`                     | `system-architect`   | Slice a PRD into issues.                                    |
 | `/zoom-out`                      | `system-architect`   | Pull back to architectural altitude.                        |
-| `/handoff`                       | either               | Produce a clean handoff package for another agent or human. |
-| `/grill-me`                      | either               | Adversarial Q&A to sharpen an idea.                         |
-| `/caveman`                       | either               | Ultra-compressed communication mode.                        |
+| `/handoff`                       | `system-architect`   | Produce a clean handoff package for another agent or human. |
+| `/grill-me`                      | `system-architect`   | Adversarial Q&A to sharpen an idea.                         |
+| `/caveman`                       | modeless             | Ultra-compressed communication style utility.               |
 | `/write-a-skill`                 | `code-tweaker`       | Author a new skill following the bucket layout.             |
 | `/setup-matt-pocock-skills`      | `code-tweaker`       | One-shot setup helper for the bundled skill set.            |
 
-Command files live in
-[`templates/full/.roo/commands/`](templates/full/.roo/commands).
+Command files live in
+[`templates/full/.roo/commands/`](templates/full/.roo/commands).
+`/caveman` intentionally has no `mode:` because it changes communication style, not workflow authority.
 
 ## Worked examples
 
-- [`examples/fix-flow.md`](examples/fix-flow.md)
-- [`examples/feature-flow.md`](examples/feature-flow.md)
+- [`examples/fix-flow.md`](examples/fix-flow.md)
+- [`examples/feature-flow.md`](examples/feature-flow.md)
+- [`examples/demo-transcripts/`](examples/demo-transcripts/)
 
 ## How this is different
 
-Zoo Flow is not a methodology and not a giant skills pack. It is a
-thin Zoo-native control plane: three modes, a routing matrix, and a
-path-safety contract that turn into a predictable workflow. For a
-longer comparison with adjacent projects, see
-[`docs/comparison.md`](docs/comparison.md).
+Zoo Flow is not a methodology and not a giant skills pack. It is a
+thin Zoo-native control plane: three modes, a routing matrix, and a
+path-safety contract that turn into a predictable workflow. For a
+longer comparison with adjacent projects, see
+[`docs/comparison.md`](docs/comparison.md).
+
+For command-addition rules, see [`docs/command-design.md`](docs/command-design.md).
 
 ## Manual install
 
@@ -176,13 +179,25 @@ If you would rather copy the template by hand:
 
 ```sh
 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` (including `Copy-Item -Recurse` for `.zoo-flow\`) instead.
+cp /tmp/zoo-flow/templates/full/.roomodes .
+cp -R /tmp/zoo-flow/templates/full/.roo .
+cp -R /tmp/zoo-flow/templates/full/.zoo-flow .
+touch .gitignore
+grep -qxF "# Zoo Flow — generated config (never committed)" .gitignore 2>/dev/null || {
+  printf "\n# Zoo Flow — generated config (never committed)\n" >> .gitignore
+  printf ".roomodes\n.roo/\n.zoo-flow/\n" >> .gitignore
+}
+```
+
+Windows uses `git clone ... C:\Temp\zoo-flow` and `Copy-Item` (including `Copy-Item -Recurse` for `.roo\` and `.zoo-flow\`) instead. Add `.roomodes`, `.roo/`, and `.zoo-flow/` to `.gitignore`.
+
+## Development
+
+Before publishing, run:
+
+```bash
+npm run release:check
+```
 
 ## Migration