@fernado03/zoo-flow 0.9.1 → 0.11.0

package/README.md

@@ -1,64 +1,120 @@
 # Zoo Flow
 
-> **Workflow control plane for [Zoo Code](https://docs.zoocode.dev/).**
-
-Zoo Flow is a Zoo Code workflow-control template.
-
-It does not try to be a giant skills pack. It makes Zoo Code predictable:
-free-form requests are routed through Custom Orchestrator, risky work gets
-planning gates, implementation stays in Code Tweaker, architecture stays in
-System Architect, and every command follows a small command/skill contract.
+> **Workflow control plane for [Zoo Code](https://docs.zoocode.dev/) and [Claude Code](https://docs.anthropic.com/en/docs/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`](docs/overview.md)
 and [`docs/philosophy.md`](docs/philosophy.md).
 
 ## Install
 
-Run this from the root of the project where you use Zoo Code:
+Run this from the root of the project where you use Zoo Code or Claude Code:
 
 ```bash
 npx @fernado03/zoo-flow@latest init
 ```
 
-This copies the runtime template (`.roomodes` and `.roo/`) plus the
-`.zoo-flow/` starter docs into your project. It does not copy this
-repository's `docs/` folder. Zoo Flow also ensures `.roo/`, `.roomodes`, and `.zoo-flow/` are
-listed in `.gitignore` so generated config and local context docs stay
-out of normal commits.
+Zoo Flow will prompt you to choose a platform:
+
+```
+? Which platform would you like to install for?
+  1. Claude Code
+  2. Zoo Code
+```
 
-If `.roomodes` or `.roo/` already exist, Zoo Flow stops without
-overwriting. To back up and overwrite:
+### Claude Code Installation
+
+For Claude Code, this copies:
+- `CLAUDE.md` - Project instructions with behavioral profiles and routing guide
+- `.claude/commands/` - 25 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:
 
 ```bash
 npx @fernado03/zoo-flow@latest init --force
 ```
 
-A timestamped backup is always written to `.zoo-flow-backup/` before
-overwrite.
+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:
+
+```bash
+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:
 
-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:
-
-```bash
-npx @fernado03/zoo-flow@latest doctor
-```
+```bash
+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:
+## 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.
-
-Daily use:
+- 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.
@@ -66,7 +122,7 @@ Daily use:
 - 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`.
+For team usage, see `docs/team-mode.md`.
 
 ## Update
 
@@ -84,11 +140,11 @@ Zoo Flow keeps always-loaded rules small. Domain docs (`.zoo-flow/CONTEXT.md`, `
 
 ## 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`         |
+| 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`](templates/full/.roomodes). The detailed
@@ -108,14 +164,14 @@ run directly inside `system-architect` or `code-tweaker` when needed.
 | `/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.                      |
+| `/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)
 
@@ -127,31 +183,31 @@ run directly inside `system-architect` or `code-tweaker` when needed.
 | `/to-prd`                        | `system-architect`   | Turn sharpened context into a PRD.                          |
 | `/to-issues`                     | `system-architect`   | Slice a PRD into issues.                                    |
 | `/zoom-out`                      | `system-architect`   | Pull back to architectural altitude.                        |
-| `/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.               |
+| `/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.               |
 | `/write-a-skill`                 | `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/`](templates/full/.roo/commands).
-`/caveman` intentionally has no `mode:` because it changes communication style, not workflow authority.
+Command files live in
+[`templates/full/.roo/commands/`](templates/full/.roo/commands).
+`/caveman` intentionally has no `mode:` because it changes communication style, not workflow authority.
 
 ## Worked examples
 
-- [`examples/fix-flow.md`](examples/fix-flow.md)
-- [`examples/feature-flow.md`](examples/feature-flow.md)
-- [`examples/demo-transcripts/`](examples/demo-transcripts/)
+- [`examples/fix-flow.md`](examples/fix-flow.md)
+- [`examples/feature-flow.md`](examples/feature-flow.md)
+- [`examples/demo-transcripts/`](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`](docs/comparison.md).
-
-For command-addition rules, see [`docs/command-design.md`](docs/command-design.md).
+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`](docs/comparison.md).
+
+For command-addition rules, see [`docs/command-design.md`](docs/command-design.md).
 
 ## Manual install
 
@@ -159,25 +215,25 @@ If you would rather copy the template by hand:
 
 ```sh
 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`.
-
-## Development
-
-Before publishing, run:
-
-```bash
-npm run release:check
-```
+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`.
+
+## Development
+
+Before publishing, run:
+
+```bash
+npm run release:check
+```
 
 ## Migration