@fernado03/zoo-flow 0.12.0 → 0.12.2

package/examples/fix-flow.md

@@ -0,0 +1,139 @@
+# Example: `/fix` flow
+
+A worked example of the multi-phase `/fix` chain: orchestrator delegates
+to the architect, architect diagnoses, architect switches to the tweaker
+to implement, tweaker switches back, architect runs the post-mortem,
+tweaker prepares the commit. The whole flow has explicit HITL stops.
+
+## Setup
+
+- Active mode: `🪃 Custom Orchestrator`.
+- Workspace has a real bug to fix. For this example, assume:
+
+  > "The login button does nothing on the second click. First click
+  > works."
+
+## Phase 1 — orchestrator routes
+
+Type:
+
+```
+/fix The login button does nothing on the second click. First click works.
+```
+
+**Expected**
+
+Orchestrator looks up the routing matrix and delegates with `new_task`
+targeting `system-architect`. The delegated message includes the
+slash form, user context, proceed policy, command-protocol pointer,
+skills location, and the completion rule.
+
+## Phase 2 — architect diagnoses
+
+The new task window opens in `🏗️ System Architect`. The architect:
+
+1. Loads `/fix` per the command protocol.
+2. Runs the `diagnose` skill, phases 1–3.
+3. Produces a short list of hypotheses.
+4. **Halts** and asks you to pick one.
+
+**Expected message (paraphrased)**
+
+> Hypotheses:
+> 1. Click handler is wired once and never re-bound after a state change.
+> 2. The button enters a disabled state on first click and never resets.
+> 3. A queued network request is canceling the second click's handler.
+>
+> Which would you like to instrument? (1 / 2 / 3)
+
+You answer:
+
+```
+2
+```
+
+## Phase 3 — architect instruments
+
+The architect runs phase 4 of the `diagnose` skill on hypothesis 2.
+This phase may involve reading state-management code, adding a
+console-log or instrumentation suggestion (Markdown only — the architect
+cannot edit source), and producing a confirmed root cause.
+
+**Expected**
+
+> Root cause confirmed: `LoginButton` sets `disabled` on the first
+> click and the `onSuccess` handler does not reset it. The second
+> click is being absorbed by the disabled state.
+
+The architect summarizes the proposed fix and prepares to hand off.
+
+## Phase 4 — architect switches to tweaker
+
+The architect calls `switch_mode` to `code-tweaker` **inside the same
+task window** with a summary of:
+
+- The root cause.
+- The proposed fix (`onSuccess` resets `disabled`).
+- The files involved.
+- The tests to add or extend.
+
+The tweaker takes over without losing context.
+
+## Phase 5 — tweaker implements
+
+The tweaker:
+
+1. Edits the `LoginButton` component to reset `disabled` on success
+   and on error.
+2. Adds or extends tests covering the second-click case.
+3. Runs the test suite.
+4. Reports back.
+
+**HITL stop**: the tweaker does not commit. Per the git rule, it waits
+for your approval.
+
+## Phase 6 — back to architect for post-mortem
+
+The tweaker calls `switch_mode` back to `system-architect`. The
+architect runs phase 6 of `diagnose` (post-mortem):
+
+- What was the original assumption that masked the bug?
+- Is this an isolated mistake or a pattern?
+- If a pattern, would `/refactor` help?
+
+The architect produces a short post-mortem note in `docs/` or
+`.scratch/` (Markdown only) and either drops the matter there or
+suggests `/refactor`.
+
+## Phase 7 — tweaker prepares the commit
+
+The architect switches back to the tweaker. The tweaker suggests
+`/commit-and-document`. **The orchestrator does not auto-launch it.**
+That command runs only when you type it.
+
+## Phase 8 — return to orchestrator
+
+When the chain is complete (or blocked), the active mode calls
+`attempt_completion`. The orchestrator summarizes for you and halts.
+
+## Pass criteria
+
+- [ ] Orchestrator delegated to `system-architect`, not the tweaker.
+- [ ] Architect halted after phase 3 hypotheses, did not instrument
+      until you picked one.
+- [ ] Architect did not edit source code at any point.
+- [ ] Architect used `switch_mode` (same window) to hand off, not
+      `new_task`.
+- [ ] Tweaker did not run `git commit` or `git push` without your
+      explicit approval.
+- [ ] After return, orchestrator halted instead of auto-launching
+      `/commit-and-document`.
+
+## Common slips
+
+- Architect tries to edit source: see
+  [`docs/troubleshooting.md`](../docs/troubleshooting.md#architect-trying-to-edit-source).
+- Tweaker commits without approval: tighten the git rule in the
+  tweaker's `customInstructions`.
+- Orchestrator launches `/commit-and-document` automatically: see
+  [`docs/troubleshooting.md`](../docs/troubleshooting.md#slash-command-leakage-from-subtask-summaries).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fernado03/zoo-flow",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "description": "Structured workflow templates for AI coding assistants",
   "type": "module",
   "bin": {
@@ -10,7 +10,10 @@
     "bin/",
     "templates/",
     "scripts/",
-    "tests/"
+    "tests/",
+    "docs/",
+    "examples/",
+    "LICENSE"
   ],
   "keywords": [
     "ai",

package/scripts/check-package-links.js

@@ -12,7 +12,7 @@ const packageJsonPath = path.join(packageRoot, "package.json");
 
 const failures = [];
 const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
-const files = Array.isArray(packageJson.files) ? packageJson.files : [];
+const files = Array.isArray(packageJson.files) ? packageJson.files.map((f) => f.replace(/\/$/, "")) : [];
 const forbidden = [".git", "node_modules", ".scratch", ".zoo-flow-backup", "*.tgz"];
 
 for (const entry of files) {

package/scripts/eval-routing.js

@@ -105,7 +105,7 @@ if (!fs.existsSync(casesPath)) {
         fail(lineNumber, "expected_command must start with /");
       } else {
         const commandName = record.expected_command.slice(1);
-        const commandPath = path.join(templateRoot, ".roo", "commands", `${commandName}.md`);
+        const commandPath = path.join(templateRoot, ".roo", "commands", `zoo-${commandName}.md`);
         if (!fs.existsSync(commandPath)) {
           fail(lineNumber, `missing command file for ${record.expected_command}`);
         } else {

package/scripts/score-quality.js

@@ -37,7 +37,7 @@ function check(condition, description, category) {
     const files = fs.readdirSync(commandsDir).filter((f) => f.endsWith(".md"));
     for (const file of files) {
       const text = fs.readFileSync(path.join(commandsDir, file), "utf8");
-      const isModeless = file === "caveman.md";
+      const isModeless = file === "zoo-caveman.md";
       r.total++;
       if (isModeless) {
         r.pass++; // modeless by design, not a failure
@@ -183,7 +183,7 @@ function check(condition, description, category) {
 (function () {
   const r = { pass: 0, total: 0 };
 
-  const verifyCmd = path.join(templateRoot, ".roo", "commands", "verify.md");
+  const verifyCmd = path.join(templateRoot, ".roo", "commands", "zoo-verify.md");
   r.total++;
   r.pass += check(fs.existsSync(verifyCmd), "verify command exists", "verification") ? 1 : 0;
 
@@ -209,7 +209,7 @@ function check(condition, description, category) {
 (function () {
   const r = { pass: 0, total: 0 };
 
-  const reviewCmd = path.join(templateRoot, ".roo", "commands", "review.md");
+  const reviewCmd = path.join(templateRoot, ".roo", "commands", "zoo-review.md");
   r.total++;
   r.pass += check(fs.existsSync(reviewCmd), "review command exists", "review_process") ? 1 : 0;
 

package/scripts/test-doctor.js

@@ -42,21 +42,21 @@ function mutate(root, mutation) {
   if (mutation === "missing-roomodes") {
     fs.rmSync(path.join(root, ".roomodes"));
   } else if (mutation === "missing-command") {
-    fs.rmSync(command("review.md"));
+    fs.rmSync(command("zoo-review.md"));
   } else if (mutation === "missing-skill") {
     fs.rmSync(skill("engineering", "tweak", "SKILL.md"));
   } else if (mutation === "bad-skill-wrapper") {
-    replaceInFile(command("caveman.md"), "Skill:", "Run skill:");
+    replaceInFile(command("zoo-caveman.md"), "Skill:", "Run skill:");
   } else if (mutation === "bad-mode-slug") {
-    replaceInFile(command("review.md"), "mode: system-architect", "mode: architect");
+    replaceInFile(command("zoo-review.md"), "mode: system-architect", "mode: architect");
   } else if (mutation === "bad-built-in-delegation") {
     fs.appendFileSync(path.join(root, ".roo", "rules-custom-orchestrator", "00-routing.md"), "\nUse new_task to architect for review.\n");
   } else if (mutation === "bad-zoo-path") {
     fs.appendFileSync(path.join(root, ".roo", "rules", "00-paths.md"), "\nBad path: .zoo/commands/example.md\n");
   } else if (mutation === "helper-missing-mode") {
-    replaceInFile(command("diagnose.md"), /^mode: system-architect\r?\n/m, "");
+    replaceInFile(command("zoo-diagnose.md"), /^mode: system-architect\r?\n/m, "");
   } else if (mutation === "helper-not-permitted") {
-    replaceInFile(path.join(root, ".roomodes"), "/diagnose, ", "");
+    replaceInFile(path.join(root, ".roomodes"), "/zoo-diagnose, ", "");
   } else {
     throw new Error(`Unknown mutation: ${mutation}`);
   }

package/templates/claude-code/.claude/skills/engineering/diagnose/SKILL.md

@@ -97,7 +97,7 @@ MUST finish:
 - [ ] `[DEBUG-...]` logs removed from source.
 - [ ] Throwaway harnesses deleted/moved.
 - [ ] Winning hypothesis stated in commit/PR.
-- [ ] Seam/locality blocker → recommend `/improve-codebase-architecture`.
+- [ ] Seam/locality blocker → recommend `/zoo-improve-codebase-architecture`.
 
 Implementer returns results back to architect profile for Phase 7.
 
@@ -134,4 +134,4 @@ Write `<session-dir>/diagnosis.md` with full log (hypotheses, instrumentation re
 - root cause summary
 - fix applied
 - status
-- recommended next command (typically `/verify` then `/review` then `/commit-and-document`)
+- recommended next command (typically `/zoo-verify` then `/zoo-review` then `/zoo-commit-and-document`)

package/templates/claude-code/.claude/skills/engineering/explore/SKILL.md

@@ -48,7 +48,7 @@ Look for:
 - modules/components identified
 - key dependencies and relationships
 - seams and integration points
-- recommended next command (typically `/fix`, `/feature`, or `/refactor` if changes needed, `/tdd` if implementation needed)
+- recommended next command (typically `/zoo-fix`, `/zoo-feature`, or `/zoo-refactor` if changes needed, `/zoo-tdd` if implementation needed)
 
 ## Context economy
 

package/templates/claude-code/.claude/skills/engineering/feature/SKILL.md

@@ -54,7 +54,7 @@ Delegate to implementer profile via `Agent` tool. Implementer executes:
 
 - feature implemented
 - tests status (all passing)
-- recommended next command (typically `/verify` then `/review` then `/commit-and-document`)
+- recommended next command (typically `/zoo-verify` then `/zoo-review` then `/zoo-commit-and-document`)
 
 ## Context economy
 

package/templates/claude-code/.claude/skills/engineering/fix/SKILL.md

@@ -47,7 +47,7 @@ Delegate to implementer profile via `Agent` tool. Implementer executes:
 - fix implemented
 - regression test added
 - all tests passing
-- recommended next command (typically `/verify` then `/review` then `/commit-and-document`)
+- recommended next command (typically `/zoo-verify` then `/zoo-review` then `/zoo-commit-and-document`)
 
 ## Context economy
 

package/templates/claude-code/.claude/skills/engineering/grill-with-docs/SKILL.md

@@ -33,4 +33,4 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 - documentation location
 - key findings and insights
-- recommended next command (typically `/feature` or `/refactor` if changes needed)
+- recommended next command (typically `/zoo-feature` or `/zoo-refactor` if changes needed)

package/templates/claude-code/.claude/skills/engineering/improve-codebase-architecture/SKILL.md

@@ -37,4 +37,4 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 - architecture proposal location
 - key improvements identified
-- recommended next command (typically `/refactor` to implement changes)
+- recommended next command (typically `/zoo-refactor` to implement changes)

package/templates/claude-code/.claude/skills/engineering/refactor/SKILL.md

@@ -47,7 +47,7 @@ Delegate to implementer profile via `Agent` tool. Implementer executes:
 - what was refactored
 - structural improvements achieved
 - tests status (all passing)
-- recommended next command (typically `/verify` then `/review` then `/commit-and-document`)
+- recommended next command (typically `/zoo-verify` then `/zoo-review` then `/zoo-commit-and-document`)
 
 ## Context economy
 

package/templates/claude-code/.claude/skills/engineering/review/SKILL.md

@@ -135,11 +135,11 @@ Write `<session-dir>/synthesis.md` with:
 
 If fixes are needed, recommend one next command only:
 
-- small fix -> `/tweak`
-- behavior fix -> `/tdd`
-- unknown cause -> `/fix`
-- design issue -> `/refactor`
-- ready for evidence -> `/verify`
-- ready to commit -> `/commit-and-document`
+- small fix -> `/zoo-tweak`
+- behavior fix -> `/zoo-tdd`
+- unknown cause -> `/zoo-fix`
+- design issue -> `/zoo-refactor`
+- ready for evidence -> `/zoo-verify`
+- ready to commit -> `/zoo-commit-and-document`
 
 Do not auto-launch any follow-up command.

package/templates/claude-code/.claude/skills/engineering/scaffold-context/SKILL.md

@@ -42,4 +42,4 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 - CONTEXT.md location
 - sections added/updated
-- recommended next command (typically `/explore` to deepen understanding, or `/feature`/`/refactor` to start work)
+- recommended next command (typically `/zoo-explore` to deepen understanding, or `/zoo-feature`/`/zoo-refactor` to start work)

package/templates/claude-code/.claude/skills/engineering/setup-matt-pocock-skills/SKILL.md

@@ -46,4 +46,4 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 - configuration files updated
 - conventions document location
-- recommended next command (typically `/verify` to ensure config is valid)
+- recommended next command (typically `/zoo-verify` to ensure config is valid)

package/templates/claude-code/.claude/skills/engineering/tdd/SKILL.md

@@ -50,7 +50,7 @@ Checklist per cycle:
 - [ ] Code minimal.
 - [ ] No speculation.
 
-After green, suggest `/verify`, then `/review`, then `/commit-and-document` for non-trivial work. Do not auto-launch follow-up commands.
+After green, suggest `/zoo-verify`, then `/zoo-review`, then `/zoo-commit-and-document` for non-trivial work. Do not auto-launch follow-up commands.
 
 ## Complete
 

package/templates/claude-code/.claude/skills/engineering/to-issues/SKILL.md

@@ -35,4 +35,4 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 - issues directory location
 - issue count and summary
 - dependency graph
-- recommended next command (typically `/tdd` or `/tweak` to start implementing first issue)
+- recommended next command (typically `/zoo-tdd` or `/zoo-tweak` to start implementing first issue)

package/templates/claude-code/.claude/skills/engineering/to-prd/SKILL.md

@@ -37,4 +37,4 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 - PRD location
 - summary of requirements
-- recommended next command (typically `/to-issues` to break down into tasks)
+- recommended next command (typically `/zoo-to-issues` to break down into tasks)

package/templates/claude-code/.claude/skills/engineering/triage/SKILL.md

@@ -34,4 +34,4 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 - triage document location
 - prioritized list summary
-- recommended next command (typically `/fix` for bugs, `/feature` for features, or `/refactor` for tech debt)
+- recommended next command (typically `/zoo-fix` for bugs, `/zoo-feature` for features, or `/zoo-refactor` for tech debt)

package/templates/claude-code/.claude/skills/engineering/tweak/SKILL.md

@@ -14,7 +14,7 @@ Use for small known fixes.
 5. If existing test covers touched area, run it via `Bash`.
 6. DO NOT write new tests unless asked.
 7. Confirm change.
-8. For R3+ risk, suggest `/verify` before `/review` before `/commit-and-document`. Do not auto-launch. Otherwise offer `/commit-and-document` only after user satisfied.
+8. For R3+ risk, suggest `/zoo-verify` before `/zoo-review` before `/zoo-commit-and-document`. Do not auto-launch. Otherwise offer `/zoo-commit-and-document` only after user satisfied.
 9. Do not auto-launch follow-up commands.
 
 ## Complete

package/templates/claude-code/.claude/skills/engineering/update-docs/SKILL.md

@@ -31,4 +31,4 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 - documentation files updated
 - summary of changes
-- recommended next command (typically `/verify` to ensure docs are accurate)
+- recommended next command (typically `/zoo-verify` to ensure docs are accurate)

package/templates/claude-code/.claude/skills/engineering/verify/SKILL.md

@@ -36,4 +36,4 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 - verification commands run
 - pass/fail status for each
-- recommended next command (typically `/review` if passed, or `/fix` if failed)
+- recommended next command (typically `/zoo-review` if passed, or `/zoo-fix` if failed)

package/templates/claude-code/.claude/skills/engineering/zoom-out/SKILL.md

@@ -72,4 +72,4 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 - `<session-dir>/synthesis.md` file path
 - high-level structure summary
-- recommended next command (typically `/explore` for deeper dive, or `/feature`/`/refactor` if changes needed)
+- recommended next command (typically `/zoo-explore` for deeper dive, or `/zoo-feature`/`/zoo-refactor` if changes needed)

package/templates/claude-code/.claude/skills/productivity/caveman/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: caveman
-description: Ultra-compressed communication mode. Cuts token usage ~75% by dropping filler, articles, and pleasantries while keeping full technical accuracy. Use when user says "caveman mode", "talk like caveman", "use caveman", "less tokens", "be brief", or invokes /caveman.
+description: Ultra-compressed communication mode. Cuts token usage ~75% by dropping filler, articles, and pleasantries while keeping full technical accuracy. Use when user says "caveman mode", "talk like caveman", "use caveman", "less tokens", "be brief", or invokes /zoo-caveman.
 ---
 
 # Caveman

package/templates/claude-code/.zoo-flow/CONTEXT.md

@@ -1,5 +1,5 @@
 # Context
-<!-- Domain language, terms, and ambiguities for this project. Run /grill-with-docs to fill. -->
+<!-- Domain language, terms, and ambiguities for this project. Run /zoo-grill-with-docs to fill. -->
 
 ## Language
 <!-- Term: 1-2 sentence definition. _Avoid_: aliases. -->

package/templates/claude-code/.zoo-flow/START_HERE.md

@@ -5,15 +5,15 @@
 ### For Claude Code users
 
 1. Open Claude Code in this project.
-2. Run `/scaffold-context` for an existing project, or `/setup-matt-pocock-skills` if using PRDs, issue slicing, or triage.
+2. Run `/zoo-scaffold-context` for an existing project, or `/zoo-setup-matt-pocock-skills` if using PRDs, issue slicing, or triage.
 3. Then describe tasks normally — Claude Code will read CLAUDE.md automatically.
-4. Slash commands like `/fix`, `/feature`, `/tweak` work the same way.
+4. Slash commands like `/zoo-fix`, `/zoo-feature`, `/zoo-tweak` work the same way.
 
 ### For Zoo Code users
 
 1. Reload VS Code and open Zoo Code.
 2. Switch to **Custom Orchestrator** mode.
-3. Run `/scaffold-context` for an existing project, or `/setup-matt-pocock-skills` if using PRDs, issue slicing, or triage.
+3. Run `/zoo-scaffold-context` for an existing project, or `/zoo-setup-matt-pocock-skills` if using PRDs, issue slicing, or triage.
 4. Then describe tasks normally.
 
 ## What's installed
@@ -24,5 +24,5 @@
 
 ## Getting help
 
-Run `/grill-me` to stress-test your understanding of a plan or design.
-Run `/explore` to understand unfamiliar code before making changes.
+Run `/zoo-grill-me` to stress-test your understanding of a plan or design.
+Run `/zoo-explore` to understand unfamiliar code before making changes.

package/templates/claude-code/.zoo-flow/evals/no-regression-checklist.md

@@ -16,11 +16,11 @@ Before accepting workflow changes, verify:
 - [ ] Slash command names appear only when the user explicitly invokes them, asks for syntax, or inside internal delegation context.
 - [ ] START_HERE.md includes both Claude Code and Zoo Code quick start sections.
 - [ ] `.zoo-flow/START_HERE.md` remains the source of truth for first-run initialization.
-- [ ] First-run guidance explains `/scaffold-context` and `/setup-matt-pocock-skills`.
+- [ ] First-run guidance explains `/zoo-scaffold-context` and `/zoo-setup-matt-pocock-skills`.
 - [ ] Analysis, review, inspection, and safety-check subtasks use architect profile.
 - [ ] Implementation, tests, docs, prototype, and commit subtasks use implementer profile.
 - [ ] Verification requests use implementer profile.
-- [ ] Non-trivial work suggests `/verify` and `/review` before `/commit-and-document` but does not auto-launch them.
+- [ ] Non-trivial work suggests `/zoo-verify` and `/zoo-review` before `/zoo-commit-and-document` but does not auto-launch them.
 - [ ] CLAUDE.md contains behavioral profiles, routing guide, delegation protocol, and global rules.
 - [ ] `.claude/commands/` contains all 25 command files with proper frontmatter.
 - [ ] `.claude/skills/` contains adapted skill files with Claude Code tool references.

package/templates/claude-code/.zoo-flow/evals/routing-cases.md

@@ -142,7 +142,7 @@ Must:
 ## Case 12 — Explicit slash command
 
 User:
-"/tweak rename the cancel button to close."
+"/zoo-tweak rename the cancel button to close."
 
 Expected:
 Route immediately. Do not second-guess the explicit command.
@@ -178,12 +178,12 @@ Good response:
 2. Explore the area first"
 
 Must not:
-- Say "use `/tweak`" in the user-facing recommendation.
-- Offer `/tweak` as a selectable option.
+- Say "use `/zoo-tweak`" in the user-facing recommendation.
+- Offer `/zoo-tweak` as a selectable option.
 - Tell the user to type a slash command.
 
 Allowed:
-- Internally delegate using `/tweak` after the user approves.
+- Internally delegate using `/zoo-tweak` after the user approves.
 - Mention slash commands only if the user explicitly asks for command syntax.
 
 ## Case — Review