@fernado03/zoo-flow 0.5.3 → 0.7.0

package/docs/architecture.md

@@ -0,0 +1,380 @@
+# Architecture
+
+Zoo Flow ships three custom modes, a fixed routing matrix, a small set of
+always-on rules, and a directory layout for slash commands and on-demand
+skills. This document explains what each piece does and why it is shaped
+the way it is.
+
+## Components
+
+```
+templates/full/
+├── .roomodes                       # minimal: slug, groups, short pointers
+└── .roo/
+    ├── rules/                      # always-on, every mode, every turn
+    │   ├── 00-paths.md
+    │   ├── 01-command-protocol.md
+    │   ├── 02-three-failure-rule.md
+    │   ├── 03-manual-reply-protocol.md
+    │   ├── 04-context-economy.md
+    │   └── 05-mcp-awareness.md
+    ├── rules-custom-orchestrator/  # mode-scoped, orchestrator only
+    │   ├── 00-routing.md
+    │   └── 01-delegation-message.md
+    ├── rules-system-architect/     # mode-scoped, architect only
+    │   ├── 00-scope.md
+    │   ├── 01-feature-prototype.md
+    │   └── 02-completion.md
+    ├── rules-code-tweaker/         # mode-scoped, tweaker only
+    │   ├── 00-scope.md
+    │   └── 01-completion.md
+    ├── commands/                   # slash commands (the public API)
+    └── skills/                     # on-demand skills, loaded by commands
+        ├── engineering/
+        ├── productivity/
+        ├── misc/
+        ├── personal/
+        └── in-progress/
+```
+
+`.roomodes` is intentionally minimal. It declares each mode's slug,
+role, tool groups, and a short `customInstructions` block that points
+at the matching `.roo/rules-{modeSlug}/` folder. All detailed mode
+behavior lives in the rule files inside that folder. See
+[`mode-rules.md`](mode-rules.md) for the full layout rationale.
+
+> 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.
+
+## Modes
+
+### `custom-orchestrator`
+
+Defined in `templates/full/.roomodes`. Tool groups: **none**. Detailed
+behavior lives in
+[`.roo/rules-custom-orchestrator/`](../templates/full/.roo/rules-custom-orchestrator/)
+(`00-routing.md`, `01-delegation-message.md`).
+
+The orchestrator cannot read, edit, run commands, or call MCP tools. It
+exists to do exactly four things:
+
+1. Read the user request.
+2. Map it to a command using the routing matrix in its
+   `customInstructions`.
+3. Either delegate via `new_task` (when the user supplied an explicit
+   slash command) or offer 1-2 numbered workflow choices and halt
+   (when they did not).
+4. Summarize the subtask result and halt again.
+
+It never uses `switch_mode`. If `new_task` is unavailable, it stops and
+reports — it does not try to do the work itself.
+
+### `system-architect`
+
+Tool groups: `command`, `mcp`, `read`, and a constrained `edit` that only
+matches Markdown files, `.scratch/`, and `docs/`. The `fileRegex` lives in
+`.roomodes`:
+
+```json
+{ "fileRegex": "(.*\\.md$|^\\.scratch/.*|^docs/.*)" }
+```
+
+Detailed behavior lives in
+[`.roo/rules-system-architect/`](../templates/full/.roo/rules-system-architect/)
+(`00-scope.md`, `01-feature-prototype.md`, `02-completion.md`).
+
+The architect plans, diagnoses, refactors, explores, and triages. It cannot
+edit application source code. When implementation is needed, it
+`switch_mode`s to `code-tweaker` inside the same task window.
+
+Hard stops are baked in:
+
+- 3-strike rule on diagnosis: after three failed attempts, halt and ask
+  the user.
+- HITL stop before testing a hypothesis, finalizing a plan, publishing
+  issues, or making any irreversible decision.
+- During `/feature`, never run a prototype directly. Summarize and
+  switch to the tweaker.
+
+### `code-tweaker`
+
+Tool groups: `read`, `edit`, `command`, `mcp`. Full repo access within the
+assigned command. Detailed behavior lives in
+[`.roo/rules-code-tweaker/`](../templates/full/.roo/rules-code-tweaker/)
+(`00-scope.md`, `01-completion.md`).
+
+The tweaker implements, runs tests, updates docs, builds prototypes, and
+prepares commits.
+
+Hard stops:
+
+- Auto-escalate to the architect on the **same task window** if the work
+  needs major architecture decisions or the same approach fails three times.
+- Git stop: never run `git commit` or `git push` without explicit user
+  approval. Pushes only happen when the user asks.
+- Complete the whole chain, not the current phase. `attempt_completion`
+  returns to the orchestrator only after the command's **final** phase.
+  If a later phase belongs to the architect (e.g. `/fix` post-mortem),
+  hand back with `switch_mode` instead of completing early.
+
+## Command protocol
+
+The protocol is in
+[`templates/full/.roo/rules/01-command-protocol.md`](../templates/full/.roo/rules/01-command-protocol.md).
+It is loaded on every turn for every mode.
+
+When a mode is assigned a slash command:
+
+1. **Normalize.** `/fix` becomes `fix`.
+2. **Prefer `run_slash_command`.** Pass the normalized name as `command`
+   and the full task context as `args`.
+3. **Fall back to the file.** If `run_slash_command` is unavailable,
+   disabled, or fails, read `templates/full/.roo/commands/{command}.md`
+   and execute its instructions.
+4. **Resolve skills via the file.** If the command references a skill,
+   read the exact `.roo/skills/...` path the command provides. Do not
+   compute paths from anywhere else.
+5. **Do not chain.** A command suggested inside a subtask summary is
+   *not* authorization to run that command. Only the human or the
+   orchestrator's routing may launch a new command.
+
+The protocol exists to make slash commands work the same way whether the
+host UI exposes a native command runner or only file reads.
+
+### Command types
+
+Zoo Flow supports two command types:
+
+1. **Skill-wrapper commands.** The command file declares a skill via a
+   line like:
+
+   ```md
+   Skill: `.roo/skills/engineering/tdd/SKILL.md`
+   ```
+
+   The worker loads and follows that skill.
+
+2. **Direct workflow commands.** The command file contains the
+   procedure directly (no `Skill:` line). The worker executes those
+   steps directly and must not invent a skill path.
+
+This prevents redundant loading and avoids hallucinated skill paths.
+
+## Path safety
+
+The path-safety contract is in
+[`templates/full/.roo/rules/00-paths.md`](../templates/full/.roo/rules/00-paths.md).
+Two rules:
+
+- Skills are at workspace-root paths under `.roo/skills/{bucket}/{skill}/SKILL.md`.
+- Commands are at workspace-root paths under `.roo/commands/{name}.md`.
+
+The forbidden form is anything under `.roo/rules/skills/...` or
+`.roo/rules/commands/...`. Modes that try to load skills relative to a
+`rules/` file have produced the most common failure in practice
+(`ENOENT: .roo/rules/skills/...`). The rule blocks it before it happens.
+
+## Slash commands
+
+Each command is a Markdown file with a YAML front matter and a body. The
+front matter declares the target mode and the argument hint:
+
+```markdown
+---
+description: "Direct implementation mode for small, known fixes or UI updates."
+argument-hint: <what to change>
+mode: code-tweaker
+---
+
+Skill: `.roo/skills/engineering/tweak/SKILL.md`
+
+$ARGUMENTS
+```
+
+The body is the actual instruction set. Some commands invoke a single
+skill (`/tweak`, `/prototype`). Others orchestrate a multi-phase chain
+across modes (`/fix`, `/feature`, `/refactor`).
+
+A command can:
+
+- Reference a skill by its exact `.roo/skills/...` path.
+- Spell out HITL stops between phases.
+- Direct a mode to `switch_mode` to another mode at a specific phase.
+- Substitute `$ARGUMENTS` with the user / delegated context.
+
+A command must not:
+
+- Compute skill paths dynamically.
+- Bypass the orchestrator when handing the human a choice.
+- Auto-launch a follow-up command from a subtask summary.
+
+### Core vs. helper commands
+
+The orchestrator's **routing matrix** intentionally only routes a small
+set of core workflow commands:
+
+- `/tweak`, `/tdd`, `/update-docs`, `/commit-and-document`, `/prototype`, `/verify`
+  → `code-tweaker`
+- `/fix`, `/feature`, `/refactor`, `/explore`, `/triage`, `/review`
+  → `system-architect`
+
+Every other command in `templates/full/.roo/commands/` is a **helper**.
+Helpers are real, working commands. They are run directly inside the
+appropriate mode rather than delegated by the orchestrator. This keeps
+the orchestrator's routing matrix small and predictable, while leaving
+the broader command library available when you want it.
+
+If a helper command starts being used often enough to deserve
+delegation, promote it to the routing matrix in `.roomodes` and add it
+to the routed table in [`README.md`](../README.md#commands).
+
+## Skills
+
+Skills live under `templates/full/.roo/skills/`. Each skill is a folder
+with a `SKILL.md` and any supporting files (templates, scripts, sub-docs).
+They are organized into buckets:
+
+- `engineering/` — code work.
+- `productivity/` — non-code workflow.
+- `misc/` — kept around but rarely used.
+- `personal/` — tied to a maintainer's setup, not promoted.
+- `in-progress/` — drafts, not ready to ship.
+
+Skills are loaded **only** through commands. There is no "skill autoloader"
+that pulls them on every turn. The orchestrator does not see skills at all;
+it only sees commands.
+
+The skills index lives in [`docs/skills-index.md`](skills-index.md).
+It is human-facing reference documentation, intentionally kept outside
+`.roo/rules/` because `.roo/rules/` is injected on every turn. Commands
+load skills directly from explicit `.roo/skills/.../SKILL.md` paths, so
+the index is not required for runtime execution.
+
+### Skill output placement
+
+Skills that produce throwaway working files share a single convention
+so cleanup is mechanical:
+
+- `.scratch/<command>-<slug>.md` — phase checklists for `/fix`,
+  `/feature`, `/refactor`; optional `/explore` save-targets under
+  `.scratch/explorations/<date>/`; local PRDs and issues from
+  `setup-matt-pocock-skills` (`.scratch/{feature-slug}/`).
+- `.scratch/prototypes/<slug>/` — logic, state, and data-model
+  prototypes from `/prototype` (`LOGIC.md` branch). UI prototypes stay
+  adjacent to the real page they mock up because they need the route,
+  data fetching, and auth.
+- `docs/journal/` — entries written by `/commit-and-document`.
+- In-place edits — `/tweak`, `/tdd`, `migrate-to-shoehorn`,
+  `update-docs`.
+
+`.scratch/` is on the architect's `fileRegex` allowlist, so it is a
+safe edit target for `system-architect` and a natural bulk-cleanup
+target for the user.
+
+## Three-folder contract
+
+Zoo Flow uses three distinct folders, each with a different lifetime
+and replacement policy. Keeping them separate is intentional:
+
+| Folder | Lifetime | Loaded every turn? | Replaced by `init`/`update`? | Gitignored? | Authored by |
+|---|---|---|---|---|---|
+| `.roo/` | Per release | ✅ (rules/) | ✅ (full replace) | No | Template |
+| `.scratch/` | Per chain | ❌ | ❌ | Convention | Worker |
+| `.zoo-flow/` | Per project | ❌ | ❌ (migrated) | ✅ (init appends) | User via /grill-with-docs |
+
+**Why three folders, not one.** Each row has a different replacement
+policy and a different authorship model. Collapsing them would force
+the host to grow exception mechanisms (don't auto-load, don't replace
+this subset, don't wipe user content) that defeat the point of having
+a single contract.
+
+**Why `.zoo-flow/` instead of root.** Root `CONTEXT.md` and root
+`docs/adr/` polluted every project with files only some projects
+needed. `.zoo-flow/` is hidden, gitignored by default, and houses only
+the universally-essential `CONTEXT.md` placeholder plus user-authored
+ADRs. The other slots (ARCHITECTURE.md, APP_MAP.md, FLOW.md) are
+created on demand and never pre-shipped. The full slot list and
+discovery rule live in
+[`grill-with-docs/CONTEXT-FORMAT.md`](../templates/full/.roo/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md).
+
+## Same-window `switch_mode`
+
+Used inside a single task window when one mode needs the other for a phase
+of the same workflow. Examples:
+
+- `/fix` going architect (diagnose) → tweaker (implement) → architect
+  (post-mortem).
+- `/feature` going architect (sharpen) → tweaker (prototype) → architect
+  (PRD).
+- `code-tweaker` auto-escalating after a 3-strike test failure.
+
+`switch_mode` preserves context. The receiving mode reads the same task
+window and continues. Use it for tight loops where the cost of losing
+context outweighs the benefit of a clean boundary.
+
+## Delegated `new_task`
+
+Used by the orchestrator only. The orchestrator does not implement
+anything; it hands work off to the architect or the tweaker via
+`new_task`. The delegated message must include:
+
+- The slash command, including the leading slash.
+- The user context.
+- A proceed policy. One of: `Proceed automatically after audit if
+  clean`, `Ask user before implementation`, or `Stop and report only`.
+- 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`.
+
+`new_task` opens a fresh subtask window. The boundary is the point.
+Mode-internal context, scratch work, and false starts stay in the
+subtask.
+
+## Proceed policy
+
+Zoo Flow delegated tasks include a proceed policy so workers know when
+to continue and when to ask the user.
+
+Policies:
+
+- `Proceed automatically after audit if clean`
+- `Ask user before implementation`
+- `Stop and report only`
+
+This prevents unnecessary questions during well-specified subtasks,
+while preserving approval gates for hypotheses, architecture decisions,
+commits, issue changes, and irreversible actions.
+
+## `attempt_completion`
+
+Used at the end of a delegated subtask. It is **not** an escape hatch.
+
+A delegated task is the **entire command chain** — every phase and every
+mode switch the command body defines — not the single phase a mode is
+currently running. A worker returns via `attempt_completion` only after
+the command's **final** phase. Mid-chain handoffs between modes use
+`switch_mode`.
+
+Specifically, the architect must not use `attempt_completion` to skip
+required implementation work — if the work belongs to the tweaker, the
+architect uses `switch_mode` first. Likewise the tweaker must not complete
+out from under a remaining architect phase (e.g. `/fix` post-mortem); it
+`switch_mode`s back. Before any `attempt_completion`, the worker re-checks
+the command body and confirms no later phase is assigned to another mode.
+The composite commands (`/fix`, `/feature`, `/refactor`) persist a phase
+checklist under `.scratch/` so this survives context growth and mode
+switches.
+
+`attempt_completion` returns to the orchestrator with a structured summary.
+The orchestrator then summarizes for the user and halts. It never
+auto-launches the next subtask, even if the summary suggests one.
+
+## Context economy
+
+Zoo Flow avoids unnecessary token use by asking agents to search or list before broad reads, use targeted line ranges when possible, and avoid re-reading unchanged files.
+
+Full-file reads are still allowed when correctness requires complete context.

package/docs/bloat-control.md

@@ -0,0 +1,49 @@
+# Bloat Control
+
+Zoo Flow must stay small, focused, and hard to break. Every addition
+of a command, doc, rule, or skill must clear a bloat gate.
+
+## Bloat gate
+
+Before adding any new:
+
+- **Command** (composite or routed)
+- **Documentation file** under `docs/`
+- **Global rule** under `.roo/rules/`
+- **Mode-specific rule** under `.roo/rules-{mode}/`
+- **Skill** that ships by default
+
+Answer these:
+
+1. **Is it needed by most projects?** If not, it should be a
+   context pack or a community skill, not a default.
+2. **Does it cross SA/CT boundaries?** If not, prefer a skill or
+   helper command over a composite.
+3. **Does it add a new check to doctor?** Every file addition should
+   also add a doctor validation for it.
+4. **Does it fit a token budget tier?** Every file has a budget
+   (see `docs/token-budget.md`). If it exceeds the tier, add an
+   exception with justification.
+5. **Does it require documentation?** Every command and every new
+   doc file needs README or docs/ coverage with a link that
+   `check-package-links.js` validates.
+
+## Guardrails
+
+- Do not create optional docs by default. `/scaffold-context` may
+  offer them, but they are never written without user confirmation.
+- Do not add composite commands unless they meet all criteria in
+  `docs/command-design.md`.
+- Do not weaken approval gates or auto-run `/verify`, `/review`, or
+  `/commit-and-document`.
+- Token budgets with explicit exceptions are enforced by
+  `scripts/token-budget.js`.
+
+## Anti-patterns
+
+- Adding a command "because it might be useful" — put it in a skill
+  or context pack.
+- Accepting doc bloat "because it clarifies things" — token budget
+  will catch it.
+- Creating optional docs as defaults — they are only offered through
+  `/scaffold-context` after user confirmation.

package/docs/command-design.md

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

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

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