@fernado03/zoo-flow 0.11.1 → 0.11.3

package/docs/command-design.md

@@ -1,38 +0,0 @@
-# Command Design
-
-Zoo Flow should not add a composite command unless it meets all criteria:
-
-1. It crosses `system-architect` / `code-tweaker` boundaries.
-2. It needs hard stops or user approval gates.
-3. It benefits from `.scratch/` phase tracking.
-4. It is common across many projects.
-5. Chaining existing commands manually is awkward or unsafe.
-
-If not, prefer:
-
-- a skill
-- a helper command
-- a routing eval
-- a doctor check
-- documentation
-
-## Good composites
-
-- `/feature`
-- `/fix`
-- `/refactor`
-
-## Good non-composites
-
-- `/review`
-- `/verify`
-- `/update-docs`
-- `/commit-and-document`
-
-## Do not add yet
-
-- `/ship`
-- `/release`
-- `/migrate`
-- `/security-audit`
-- `/cleanup`

package/docs/command-flow.md

@@ -1,133 +0,0 @@
-# Command flow
-
-This document walks the lifecycle of a slash command from chat input to
-completion, and shows the difference between same-window switches and
-delegated subtasks.
-
-## End-to-end: explicit slash command
-
-```mermaid
-sequenceDiagram
-    autonumber
-    actor User
-    participant O as 🪃 custom-orchestrator
-    participant A as 🏗️ system-architect
-    participant T as ⚡ code-tweaker
-
-    User->>O: /fix Login button is dead on second click.
-    O->>O: Look up routing matrix
-    O->>A: new_task("/fix ...", protocol + skill location)
-    A->>A: Load /fix command, run diagnose phases 1-3
-    A-->>User: Hypotheses, HITL stop
-    User->>A: Choose hypothesis 2
-    A->>A: Diagnose phase 4 (instrument), find root cause
-    A->>T: switch_mode (same window) — implement fix
-    T->>T: Phase 5 — patch + tests
-    T->>A: switch_mode — back for post-mortem
-    A->>A: Phase 6 — post-mortem
-    A->>O: attempt_completion (summary, files, blockers)
-    O-->>User: Summary + halt
-```
-
-Notes:
-
-- Step 3 is the only `new_task` in the flow. The orchestrator never uses
-  `switch_mode`.
-- Steps 7 and 9 are `switch_mode` calls in the **same task window**.
-  Context is preserved across them.
-- Step 11 is `attempt_completion`. It returns to the orchestrator, which
-  then halts in step 12.
-
-## End-to-end: free-form request
-
-```mermaid
-sequenceDiagram
-    autonumber
-    actor User
-    participant O as 🪃 custom-orchestrator
-
-    User->>O: Tweak the README to mention Windows first.
-    O->>O: No explicit slash command
-    O->>O: Map to /tweak (or /update-docs)
-    O-->>User: Offers numbered choices: 1. Tweak README 2. Update docs
-    User->>O: 1
-```
-
-After step 5 the flow continues exactly like the explicit case above.
-
-## Same-window vs delegated
-
-| Primitive            | Used by                         | When                                          | Cost      | Context     |
-| -------------------- | ------------------------------- | --------------------------------------------- | --------- | ----------- |
-| `switch_mode`        | architect ↔ tweaker             | Tight loop inside one workflow                | Cheap     | Preserved   |
-| `new_task`           | orchestrator → architect / tweaker | Top-level delegation of a workflow         | Expensive | Fresh       |
-| `attempt_completion` | architect / tweaker → orchestrator | End of the command chain (final phase) | Free | Returns up  |
-
-The orchestrator only uses `new_task`. Modes only use `switch_mode` and
-`attempt_completion`. Crossing those wires is a bug. `attempt_completion`
-fires only after the command's final phase — mid-chain mode handoffs use
-`switch_mode`.
-
-## Phase chains
-
-Some commands are single-skill (`/tweak`, `/prototype`). Others chain
-phases across modes. The composite chains are `/fix`, `/feature`, and
-`/refactor`.
-
-Helper commands are directly runnable in their documented mode because
-their command files include `mode:` frontmatter. `/caveman` is intentionally
-modeless because it changes communication style, not workflow authority.
-
-Each composite command writes an unchecked phase checklist to `.scratch/`
-at the start and updates it before every `switch_mode` or
-`attempt_completion`. A worker must not `attempt_completion` while any
-phase is still unchecked — it `switch_mode`s to the phase's owner instead.
-This anchors the chain so a mid-chain mode does not mistake "this phase is
-done" for "the command is done" after the command body scrolls out of
-attention.
-
-### `/fix` chain
-
-| Phase | Mode      | Action                                          | Hard stop?        |
-| ----- | --------- | ----------------------------------------------- | ----------------- |
-| 1     | Architect | Diagnose phases 1–3, propose hypotheses         | Yes — pick one    |
-| 2     | Architect | Diagnose phase 4, instrument chosen hypothesis  | No                |
-| 3     | Tweaker   | Implement fix, add/extend tests                 | No                |
-| 4     | Architect | Post-mortem; suggest `/refactor` if rot found   | No                |
-| 5     | Tweaker   | Suggest `/verify`, `/review`, then commit       | Yes — user approval|
-
-### `/feature` chain
-
-| Phase | Mode      | Action                                              | Hard stop?                  |
-| ----- | --------- | --------------------------------------------------- | --------------------------- |
-| 1     | Architect | Sharpen via `grill-with-docs`; update docs          | Yes — Prototype or skip?    |
-| 2a    | Tweaker   | Prototype via `/prototype` (only if user picks it)  | Yes — verdict on prototype  |
-| 3     | Architect | Build PRD via `to-prd`                              | Yes — ready to slice?       |
-| 4     | Architect | Slice into issues via `to-issues`                   | Yes — approve issue list    |
-| 5     | Tweaker   | For each issue, run `/tdd`; suggest verify/review/commit | Yes — user approval per issue|
-
-Hard stops are not optional. Removing them is the fastest way to make the
-flow unsafe.
-
-## What the delegated message looks like
-
-When the orchestrator hands work to a mode, the `new_task` message
-contains, at minimum:
-
-- the slash command, including the leading slash
-- the user context
-- a proceed policy
-- a reminder to follow `.roo/rules/01-command-protocol.md`
-- a reminder that skills live under `.roo/skills/...`
-- a completion rule: finish the **whole command chain**, then end with
-  `attempt_completion` containing summary, files inspected/changed,
-  commands/tests run, blockers, and a recommended next command. Mid-chain
-  mode handoffs use `switch_mode`, not `attempt_completion`.
-
-Command normalization is handled by `.roo/rules/01-command-protocol.md`,
-not repeated in the delegated message.
-
-For non-trivial implementation, the recommended follow-up chain is
-`/verify` -> `/review` -> `/commit-and-document`. This is a suggestion,
-not authorization: workers and the orchestrator must not auto-launch those
-commands merely because they were mentioned.

package/docs/comparison.md

@@ -1,86 +0,0 @@
-# Comparison and positioning
-
-A few projects in the agentic-coding space share vocabulary with Zoo
-Flow — "skills", "agents", "commands". They are doing different things.
-This page is meant to make the differences clear so you can pick the
-right tool for the job.
-
-## Short version
-
-- **Superpowers** is a broad methodology and skills library. The center
-  of gravity is the *skills*: a large, well-curated collection of named
-  techniques the agent can pull in.
-- **ECC (Extended Coding Companion / "extended coding context")** is a
-  large agent harness. The center of gravity is the *runtime*: a rich
-  agent loop, memory, and tooling stack.
-- **Zoo Flow** is a Zoo Code-native workflow control plane. It focuses
-  on mode-safe delegation, slash-command routing, and path-safe skill
-  loading. The center of gravity is the
-  *contract*: three modes, a routing matrix, a command protocol, and a
-  path-safety guarantee.
-
-These projects are complementary more than competitive. You can run a
-broad skills library inside Zoo Flow's three-mode contract, and you can
-plug Zoo Flow's commands into a richer harness if you have one.
-
-## What Zoo Flow is not
-
-- It is not a replacement for a methodology like Superpowers. If you
-  want a long, opinionated guide to *how to think* about agentic
-  coding, look there.
-- It is not a runtime. Zoo Flow runs inside Zoo Code; it does not ship
-  its own agent loop, memory store, or tool registry.
-- It is not a giant skills pack. The bundled skills are a starting
-  point. The control plane is the product.
-
-## What Zoo Flow is
-
-- A `.roomodes` file that defines three custom modes with deliberate
-  tool-group boundaries.
-- A handful of always-on rules: path safety, command protocol,
-  three-failure guardrail, manual reply safety, and context economy.
-- A directory layout for slash commands and on-demand skills.
-
-If you only adopt one piece of Zoo Flow, adopt the path-safety rule and
-the command protocol. Those two files alone fix most of the "agent
-hallucinated a path" problems.
-
-## When to pick Zoo Flow
-
-- You are using Zoo Code as your primary host.
-- You want a small, validated control plane more than a big skill set.
-- You care about the mode boundary between planning and implementation.
-- You want explicit human-in-the-loop checkpoints in multi-phase flows
-  like `/fix` and `/feature`.
-
-## When to pick something else
-
-- You want a comprehensive methodology and a broad skill set out of the
-  box. Superpowers and similar projects are a better fit.
-- You are not on Zoo Code and you do not plan to be. Zoo Flow leans on
-  `customModes`, `run_slash_command`, `new_task`, and `switch_mode`
-  semantics from that host.
-- You want a full agent runtime with its own loop and memory layer.
-  ECC-style harnesses are aimed at that.
-
-## Working alongside other projects
-
-Zoo Flow plays well with broader skills libraries. The skills under
-`templates/full/.roo/skills/` follow a standard `SKILL.md` format and
-are loaded by command. If you want to bring in a skill from another
-project, drop it under the right bucket, add a one-line entry to the
-bucket `README.md` and to `docs/skills-index.md`, and reference it from
-a command file. The control plane does not care where the skill came
-from.
-
-The opposite direction works too: if you want to take just the modes
-and the command protocol into a different setup, that is two files
-(`.roomodes` and `01-command-protocol.md`) plus the path-safety rule
-(`00-paths.md`).
-
-## Respect
-
-The projects mentioned here are the work of people who care about this
-problem space. Zoo Flow exists because their work raised the bar.
-Where Zoo Flow disagrees with them, it disagrees on tradeoffs, not on
-intent.

package/docs/context-packs.md

@@ -1,35 +0,0 @@
-# Context Packs
-
-Context packs are optional reusable groups of documentation, rules,
-commands, and skills that can be layered on top of Zoo Flow for
-specific project needs.
-
-## When to use
-
-- A project needs specialized workflow patterns (e.g., writing
-  workflows, database migrations, CI/CD).
-- A team wants to share a common set of conventions across repos.
-- A user wants optional extras without modifying core Zoo Flow files.
-
-## How it works
-
-Context packs live under `.roo/templates/context-packs/`. Each pack is a
-directory with its own `manifest.json` declaring what it adds.
-
-The `/scaffold-context` command detects candidate packs based on project
-shape and offers them as optional additions.
-
-## Built-in candidate packs
-
-These are templates evaluated by `/scaffold-context` but never applied
-without user confirmation:
-
-- **Writing patterns** — shapes, beats, fragments for content projects
-- **ADR starter** — minimal ADR template and convention
-- **Setup docs** — setup conventions beyond the boiletplate
-
-## Quality gate
-
-Context packs must follow the same quality rules as core Zoo Flow:
-canonical `Skill:` markers, correct mode declarations, no built-in
-delegation. They are validated by `doctor`.

package/docs/dogfood/01-small-library.md

@@ -1,28 +0,0 @@
-# Dogfood Report: Small Library
-
-**Date:** YYYY-MM-DD
-**Project shape:** library (npm package, ~2K LOC, 10 exports)
-**Zoo Flow version:** 0.7.0
-
-## Commands tested
-
-- `/scaffold-context` — should detect library shape, propose 5-8 domain terms, 0-1 ADRs
-- `/verify` — should detect package.json, run npm test
-- `/commit-and-document` — should stage, commit, write journal entry
-
-## What Zoo Flow routed correctly
-
-
-## What it over-read
-
-
-## What it tried to create unnecessarily
-
-
-## Token budget impact
-
-
-## Fixes made to Zoo Flow
-
-
-## Remaining risk

package/docs/dogfood/02-web-app.md

@@ -1,29 +0,0 @@
-# Dogfood Report: Web App
-
-**Date:** YYYY-MM-DD
-**Project shape:** web app (Next.js, auth, payments, ~20K LOC)
-**Zoo Flow version:** 0.7.0
-
-## Commands tested
-
-- `/feature` — new payment flow with phase gates
-- `/fix` — checkout crash diagnosis
-- `/review` — branch review with Security/Risk axis
-- `/verify` — targeted test run
-
-## What Zoo Flow routed correctly
-
-
-## What it over-read
-
-
-## What it tried to create unnecessarily
-
-
-## Token budget impact
-
-
-## Fixes made to Zoo Flow
-
-
-## Remaining risk

package/docs/dogfood/03-mixed-monorepo.md

@@ -1,29 +0,0 @@
-# Dogfood Report: Mixed Monorepo
-
-**Date:** YYYY-MM-DD
-**Project shape:** monorepo (apps/web, services/api, workers/billing, packages/core)
-**Zoo Flow version:** 0.7.0
-
-## Commands tested
-
-- `/scaffold-context` — should detect monorepo shape, propose MONOREPO_MAP.md as recommended
-- `/explore` — should map unfamiliar sub-package
-- `/refactor` — should plan cross-package design change
-- `/tweak` — should handle localized change in one package
-
-## What Zoo Flow routed correctly
-
-
-## What it over-read
-
-
-## What it tried to create unnecessarily
-
-
-## Token budget impact
-
-
-## Fixes made to Zoo Flow
-
-
-## Remaining risk

package/docs/mode-rules.md

@@ -1,86 +0,0 @@
-# Mode-specific rules
-
-Zoo Flow uses three rule scopes, each loaded by Zoo Code automatically:
-
-- `.roo/rules/` — loaded for **every** mode, every turn.
-- `.roo/rules-{modeSlug}/` — loaded **only** when that mode is active.
-- `.roo/skills/` — **on-demand**, loaded by slash commands. Never auto-loaded.
-
-> Zoo Flow uses the preferred `.roo/rules-{modeSlug}/` directory form
-> only. Legacy single-file fallbacks such as `.roorules-{modeSlug}` and
-> `.clinerules-{modeSlug}` are not used by this template.
-
-Mode-specific behavior lives in dedicated folders under `.roo/`:
-
-- `.roo/rules-custom-orchestrator/` — routing rules and the delegation
-  message contract for the orchestrator.
-- `.roo/rules-system-architect/` — scope, feature-prototype handoff, and
-  completion rules for the architect.
-- `.roo/rules-code-tweaker/` — scope and completion rules for the
-  tweaker, including the git hard stop.
-
-Files inside these folders are short on purpose. They are concatenated
-into the model's context every turn the matching mode is active, so each
-extra paragraph costs tokens for the entire session.
-
-## What belongs in a mode rules folder
-
-- Standing instructions specific to that mode's job (e.g. "the architect
-  cannot edit application source").
-- Short hard stops (e.g. "halt for explicit user approval before
-  publishing issues").
-- Pointers to global rules the mode must follow.
-
-## What does NOT belong here
-
-- **On-demand skills.** Those live under `.roo/skills/` and are loaded
-  explicitly by slash commands.
-- **Workspace-wide always-on rules** that apply to every mode. Those
-  stay in `.roo/rules/`.
-- **Long policy or knowledge files.** If a policy is long enough to need
-  multiple paragraphs of explanation, write it under `docs/` and
-  reference it from the rule. The mode rule should be a short reminder,
-  not a full essay.
-- **Duplicates of the global command protocol or path safety.** Those
-  live in `.roo/rules/01-command-protocol.md` and
-  `.roo/rules/00-paths.md` respectively.
-
-## Why `.roomodes` is intentionally minimal
-
-Each `customInstructions` block in `.roomodes` is loaded with the mode
-metadata. Putting detailed behavior there duplicates what already lives
-in `.roo/rules-{modeSlug}/`, costs tokens twice, and creates two places
-to keep in sync.
-
-The current `.roomodes` keeps four things per mode:
-
-1. `slug`, `name`, `roleDefinition`, `whenToUse`, `description`,
-   `groups` — these can't move.
-2. A short `customInstructions` that:
-   - points at the matching `.roo/rules-{modeSlug}/` folder,
-    - lists permitted routed commands and permitted direct helper commands
-      (or the routing matrix, for the orchestrator),
-   - references the global rules it calls out directly (`00-paths.md`,
-     `01-command-protocol.md`, `03-manual-reply-protocol.md`). Other
-     global rules, such as `02-three-failure-rule.md` and
-     `04-context-economy.md`, are loaded automatically from
-     `.roo/rules/`.
-    - says what to do if an unsupported command is assigned.
-
-Documented helper commands must have `mode:` frontmatter unless they are
-explicitly modeless utilities such as `/caveman`.
-
-Everything else lives in the mode rules folder.
-
-## Related directories
-
-- [`.roo/rules/`](../templates/full/.roo/rules/) — always-on rules for **all** modes.
-- [`.roo/skills/`](../templates/full/.roo/skills/) — on-demand skills, invoked by slash commands.
-- [`.roo/commands/`](../templates/full/.roo/commands/) — slash command definitions
-  (e.g. `/tweak`, `/fix`).
-- [`.roo/rules-custom-orchestrator/`](../templates/full/.roo/rules-custom-orchestrator/) —
-  router-only rules.
-- [`.roo/rules-system-architect/`](../templates/full/.roo/rules-system-architect/) —
-  architect rules.
-- [`.roo/rules-code-tweaker/`](../templates/full/.roo/rules-code-tweaker/) —
-  tweaker rules.

package/docs/npm-publishing.md

@@ -1,79 +0,0 @@
-# npm Publishing
-
-Zoo Flow is published as a CLI installer.
-
-## Package name
-
-```text
-@fernado03/zoo-flow
-```
-
-## Local validation
-
-```bash
-npm run release:check
-```
-
-## Publish
-
-```bash
-npm login
-npm publish --access public
-```
-
-## Test install after publish
-
-From a separate test project:
-
-```bash
-npx @fernado03/zoo-flow@latest init
-```
-
-If the project already has `.roomodes` or `.roo/`, test:
-
-```bash
-npx @fernado03/zoo-flow@latest init --force
-```
-
-## Test update after publish
-
-From a temporary directory:
-
-```bash
-tmpdir="$(mktemp -d)"
-cd "$tmpdir"
-
-npx @fernado03/zoo-flow@latest init
-npx @fernado03/zoo-flow@latest update --dry-run
-npx @fernado03/zoo-flow@latest update
-
-test -f .roomodes
-test -d .roo
-test -d .zoo-flow-backup
-```
-
-## What ships in the package
-
-The `files` field in `package.json` controls what npm publishes:
-
-- `bin/` — the CLI entry point
-- `scripts/` — validation and release checks
-- `templates/` — the runtime template (`.roomodes` and `.roo/`)
-- `docs/` — product documentation linked from the README
-- `examples/` — worked examples linked from the README
-- `README.md`
-- `LICENSE`
-
-`node_modules/`, `.git/`, `.scratch/`, backups, and generated tarballs are not shipped.
-
-## Versioning
-
-Bump `version` in `package.json` before each publish, following
-[Semantic Versioning](https://semver.org/):
-
-- patch: bug fixes in the CLI or template content
-- minor: new commands, new modes, new skills
-- major: breaking changes to mode slugs, command names, or routing
-
-Update `CHANGELOG.md` under `## [Unreleased]` with the change, then
-move it under a new versioned section when you publish.

package/docs/out-of-scope/mainstream-issue-trackers-only.md

@@ -1,25 +0,0 @@
-# Issue tracker integrations are limited to mainstream tools
-
-`setup-matt-pocock-skills` only offers first-class support for **mainstream** issue trackers. Requests to add support for niche, new, or single-vendor experimental trackers are out of scope.
-
-## Why this is out of scope
-
-Every issue-tracker backend hard-codes a CLI shape into the skills (commands, flags, output parsing). Each new backend is permanent maintenance surface — it has to keep working as the tool's CLI evolves, and it has to keep being tested against `/to-prd`, `/to-issues`, `/triage`, and friends. That cost is only worth paying for trackers a meaningful fraction of users actually have.
-
-"Mainstream" is a judgment call, not a numeric bar:
-
-- GitHub, GitLab, and Backlog.md are the kind of tools we'd consider mainstream — broadly known, widely used, well past the experimental phase.
-- A brand-new agent-focused tool with a few hundred GitHub stars is not, no matter how interesting the design.
-
-Stars, age, and download counts are useful signals when making the call but none of them is the rule. The rule is: would a typical engineer recognise this tool and have plausibly chosen it for their team?
-
-The escape hatches for non-mainstream trackers already exist:
-
-- `local markdown` for lightweight in-repo tracking.
-- `other/custom` for users who want to wire something up themselves.
-
-Neither requires the core skills to know about the specific tool.
-
-## Prior requests
-
-- #99 — "Add dex as an issue tracker backend" (dex was ~3 months old and ~300 stars at the time of the request)

package/docs/out-of-scope/question-limits.md

@@ -1,18 +0,0 @@
-# Hard limits on the number of questions during grilling
-
-The `/grill-me` skill (and grilling sessions inside other skills) does not enforce a maximum number of questions. Requests to add a configurable cap or hard ceiling are out of scope.
-
-## Why this is out of scope
-
-Grilling is intentionally open-ended. The point is to keep digging until each branch of the decision tree is resolved — some plans need three questions, some need fifty. A fixed cap would either cut off useful exploration on hard problems or feel arbitrary on easy ones.
-
-If a session feels too long, the right escape hatches already exist:
-
-- The user can stop the session at any time and accept the current state of the plan.
-- The user can tell the model to wrap up, summarise, and move on — natural-language steering is the intended control surface, not a numeric limit.
-
-Adding a hard cap would also conflate two different failure modes: a model that asks too many questions because the plan is genuinely under-specified (working as intended) vs. a model that asks redundant or low-value questions (a prompt-quality issue, not a quantity issue). The fix for the latter belongs in the skill prompt, not in a counter.
-
-## Prior requests
-
-- #44 — "Codex just asked me 200 questions"

package/docs/out-of-scope/setup-skill-verify-mode.md

@@ -1,15 +0,0 @@
-# Verify/Check Mode for `setup-matt-pocock-skills`
-
-This project will not add a dedicated verify/check mode (or a separate verify skill) for `setup-matt-pocock-skills`.
-
-## Why this is out of scope
-
-A second skill — or a `--verify` flag — for checking whether `docs/agents/*.md` artifacts still match the seed-template schema would duplicate work the existing setup skill already handles in conversation.
-
-The intended workflow is: **run `/setup-matt-pocock-skills` and tell it to verify your current setup.** The skill is prompt-driven, so the maintainer can scope it to a verification pass ("don't rewrite anything, just check my existing files against the current seed templates and report drift") without needing a separate code path. Adding a flag or a sibling skill would split the surface area of a feature that's already expressible through the natural-language entry point.
-
-Keeping configuration management to a single skill also avoids the maintenance cost of two skills drifting from each other when seed templates evolve.
-
-## Prior requests
-
-- #106 — Feature request: verify/check mode for setup-matt-pocock-skills

package/docs/overview.md

@@ -1,61 +0,0 @@
-# Overview
-
-Zoo Flow is a small, opinionated template that turns
-[Zoo Code](https://docs.zoocode.dev/) into a predictable mode +
-command + skill orchestrator. It defines three modes, a fixed routing
-matrix, a command protocol, and path-safety rules. Drop it into a
-workspace and your AI assistant stops freelancing.
-
-## Why this exists
-
-Out of the box, AI coding assistants tend to skip planning when you
-want planning, plan when you want a tweak, and quietly invent file
-paths that do not exist. Adding a pile of skills makes it worse.
-
-Zoo Flow takes a different bet:
-
-- A **router mode** chooses the workflow.
-- An **architect mode** plans, diagnoses, and triages — and cannot
-  edit source code.
-- A **tweaker mode** implements, runs tests, prototypes, and commits —
-  only when explicitly approved.
-- A small set of **slash commands** acts as the public API between
-  you and the modes. Free-form requests go through the orchestrator;
-  typing a slash command jumps straight to its configured mode.
-- A few **always-on rules** keep the path layout honest and stop
-  skill paths from drifting under `.roo/rules/`.
-
-Everything else is optional. The skills bundled in the template are a
-sensible starting point, not the point of the project.
-
-## Core workflow
-
-```mermaid
-flowchart TD
-    User([User])
-    Orchestrator[🪃 custom-orchestrator<br/>router only]
-    Architect[🏗️ system-architect<br/>plan / diagnose / triage<br/>Markdown edits only]
-    Tweaker[⚡ code-tweaker<br/>implement / test / prototype / commit]
-
-    User -- "free-form request" --> Orchestrator
-    Orchestrator -- "proposes /command, waits" --> User
-    User -- "/tweak, /tdd, /update-docs,<br/>/commit-and-document, /prototype, /verify" --> Orchestrator
-    User -- "/fix, /feature, /refactor,<br/>/explore, /triage, /review" --> Orchestrator
-
-    Orchestrator -- "new_task" --> Tweaker
-    Orchestrator -- "new_task" --> Architect
-
-    Architect -- "switch_mode (same window)" --> Tweaker
-    Tweaker -- "switch_mode (same window)" --> Architect
-
-    Tweaker -- "attempt_completion" --> Orchestrator
-    Architect -- "attempt_completion" --> Orchestrator
-    Orchestrator -- "summarize, HALT" --> User
-```
-
-For the deeper "why", see [`philosophy.md`](philosophy.md). For the
-component-level reference, see [`architecture.md`](architecture.md).
-
-For non-trivial work, the normal endgame is implementation, then
-`/verify`, then `/review`, then `/commit-and-document`. These are
-recommendations only; Zoo Flow does not auto-run follow-up commands.