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

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.