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 → spec → tickets → 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-spec	system-architect	Turn sharpened context into a published spec.
/to-tickets	system-architect	Slice a spec into tickets with blocking edges.
/to-prd	system-architect	Alias for /to-spec.
/to-issues	system-architect	Alias for /to-tickets.
/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 spec or ticket 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.