Zoo Flow

Workflow control plane for Zoo Code and Claude Code.

Zoo Flow is a workflow-control template that supports both Zoo Code and Claude Code.

It does not try to be a giant skills pack. It makes AI coding assistants predictable: free-form requests are routed through the appropriate profile, risky work gets planning gates, implementation stays in the Implementer profile, architecture stays in the Architect profile, and every command follows a small command/skill contract.

Platform support:

• Zoo Code: Uses .roomodes, .roo/commands/, .roo/skills/, and .roo/rules/
• Claude Code: Uses CLAUDE.md, .claude/commands/, and .claude/skills/

For the deeper rationale, see docs/overview.md and docs/philosophy.md.

Install

Run this from the root of the project where you use Zoo Code or Claude Code:

npx @fernado03/zoo-flow@latest init

Zoo Flow will prompt you to choose a platform:

? Which platform would you like to install for?
  1. Claude Code
  2. Zoo Code

Claude Code Installation

For Claude Code, this copies:

• CLAUDE.md - Project instructions with behavioral profiles and routing guide
• .claude/commands/ - 27 slash commands adapted for Claude Code
• .claude/skills/ - Workflow skills with Claude Code tool names
• .zoo-flow/ - Starter docs and context files

Zoo Flow ensures .claude/ and .zoo-flow/ are listed in .gitignore so generated config and local context docs stay out of normal commits.

If CLAUDE.md or .claude/ already exist, Zoo Flow stops without overwriting. To back up and overwrite:

npx @fernado03/zoo-flow@latest init --force

After install, open Claude Code in the project directory. The slash commands (e.g., /tweak, /fix, /feature) will be available immediately.

Zoo Code Installation

For Zoo Code, this copies:

• .roomodes - Mode definitions (Custom Orchestrator, System Architect, Code Tweaker)
• .roo/commands/ - Slash commands with routing metadata
• .roo/skills/ - Workflow skills with Zoo Code tool names
• .roo/rules/ - Global and mode-specific rules
• .zoo-flow/ - Starter docs and context files

Zoo Flow 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:

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.

Validate Install

Use this inside a project after install or update:

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.

Using Zoo Flow

First run (both platforms)

• Run /scaffold-context when the project needs local context docs.
• Run /setup-matt-pocock-skills when tracker or triage config is needed.

Claude Code

Claude Code reads CLAUDE.md automatically on startup. No mode switching needed.

Daily use:

• Open Claude Code in your project directory
• Describe tasks naturally: "Fix the login bug" → Claude proposes /fix workflow
• Or use slash commands directly: /tweak, /fix, /feature, /review, etc.
• Claude uses behavioral profiles (Architect/Implementer) defined in CLAUDE.md
• Multi-phase commands (like /fix, /feature) use the Agent tool to delegate between profiles

Example:

You: "Fix the login bug"
Claude: "I'll use the /fix workflow. The architect will diagnose, then the implementer will fix it. Proceed?"
You: "Yes"
Claude: [Runs diagnostic, proposes fix, implements after approval]

Zoo Code

Zoo Code uses three custom modes defined in .roomodes.

Daily use:

• Start in custom-orchestrator, describe the task normally.
• The orchestrator proposes a plain-language workflow; approve by number.
• Or type a slash command directly (/tweak, /fix, etc.) to bypass routing.
• Explicit slash commands count as approval. Free-form requests do not.
• Clickable choices must not include slash commands or mode names.

For team usage, see docs/team-mode.md.

Update

npx @fernado03/zoo-flow@latest update

Backs up your current Zoo Flow files to .zoo-flow-backup/<timestamp>/, then replaces them with the latest template. Preview with --dry-run.

• Zoo Code: Backs up .roomodes and .roo/
• Claude Code: Backs up CLAUDE.md and .claude/

Scratch working memory

Certain skills (like /review, /diagnosing-bugs, and /explore) use a scratch working memory pattern for deeper analysis. These skills:

• Create structured .scratch/ subdirectories with date and context
• Write intermediate findings to separate files during multi-pass analysis
• Read back previous passes before synthesizing final insights

Example structure:

.scratch/
  reviews/
    2026-06-14_auth-refactor/
      01_security.md      # Security analysis pass
      02_architecture.md  # Architecture review pass
      03_synthesis.md     # Final insights from both passes

This enables:

• Cross-angle insights: Later passes reference earlier findings, catching issues that span multiple perspectives
• Persistent reasoning: Findings aren't lost in context window limits
• Audit trail: You can review the reasoning process, not just final conclusions
• Ultracode-level depth: Achieves thorough analysis within Zoo Flow's single-agent architecture

See templates/full/.roo/rules/07-scratch-working-memory.md for the protocol details.

Token discipline

Zoo Flow keeps always-loaded rules small. Domain docs (.zoo-flow/CONTEXT.md, .zoo-flow/docs/adr/) are never read by default — only when the task touches domain language, public behavior, or architecture seams. Agents search before broad reads, use targeted line ranges when possible, and avoid re-reading unchanged files. All runtime files 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 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. The detailed behavior lives in .roo/rules-{modeSlug}/ folders. See docs/mode-rules.md.

Commands

The orchestrator routes the core commands. Helper commands are run directly inside system-architect or code-tweaker when needed.

Core (routed by the orchestrator)

| Command | Routes to | What it does | | ------------------------ | -------------------- | ----------------------------------------------------------- | | /tweak | code-tweaker | Direct implementation of small, known changes. | | /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. | | /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)

| Command | Best run in | What it does | | -------------------------------- | -------------------- | ----------------------------------------------------------- | | /diagnosing-bugs | system-architect | Standalone diagnosis loop with HITL checkpoints. | | /grill-with-docs | system-architect | Sharpen a feature spec via QA against current docs. | | /improve-codebase-architecture | system-architect | Generate a deep architecture review report. | | /to-prd | system-architect | Turn sharpened context into a PRD. | | /to-issues | system-architect | Slice a PRD into issues. | | /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. | | /implement | code-tweaker | Implement work from a PRD or issue breakdown. | | /resolve-merge | code-tweaker | Resolve git merge/rebase conflicts. | | /writing-great-skills | 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/. /caveman intentionally has no mode: because it changes communication style, not workflow authority.

Worked examples

• examples/fix-flow.md
• examples/feature-flow.md
• 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.

For command-addition rules, see docs/command-design.md.

Manual install

If you would rather copy the template by hand:

Zoo Code

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 .
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.

Claude Code

git clone https://github.com/Fernado03/zoo-flow.git /tmp/zoo-flow
cp /tmp/zoo-flow/templates/claude-code/CLAUDE.md .
cp -R /tmp/zoo-flow/templates/claude-code/.claude .
cp -R /tmp/zoo-flow/templates/claude-code/.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 ".claude/\n.zoo-flow/\n" >> .gitignore
}

Windows uses the same approach with Copy-Item for .claude\ and .zoo-flow\. Add .claude/ and .zoo-flow/ to .gitignore.

Development

Before publishing, run validation scripts from the package root:

# Run all validation checks
npm run check

# Run individual validations
npm run token-budget
npm run package-manifest
npm run golden-transcripts
npm run project-shapes
npm run score-quality

Note: These validate the template source, not an installed project. To validate an installation, run npx @fernado03/zoo-flow@latest doctor inside the target project.

Migration

Zoo Flow started as a Roo Flow template and was renamed for Zoo Code. The .roo/ folder names are intentionally preserved because Zoo Code still uses those paths for project modes, commands, rules, and skills. Migrating from a Roo Code workspace by copying the same .roo/ directory and .roomodes file is expected to keep working.

Inspiration

Inspired by Matt Pocock's agent-skills workflow ideas — small, composable, task-focused skills for coding agents. Zoo Flow is not affiliated with, endorsed by, or maintained by him; it is an independent Zoo Code workflow-control template.

License

MIT.