@fernado03/zoo-flow 0.12.0 → 0.12.1

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.1",
   "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/tests/fixtures/doctor/helper-not-permitted/fixture.json

@@ -1 +1 @@
-{"expect":"fail","mutation":"helper-not-permitted","message":"does not permit documented command /diagnose"}
+{"expect":"fail","mutation":"helper-not-permitted","message":"does not permit documented command /zoo-diagnose"}