@fernado03/zoo-flow 0.8.8 → 0.9.0

package/bin/zoo-flow.js

@@ -5,74 +5,75 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const packageRoot = path.resolve(__dirname, "..");
-const templateRoot = path.join(packageRoot, "templates", "full");
-
-const COMMAND_POLICY = {
-  routed: {
-    "tweak": "code-tweaker",
-    "tdd": "code-tweaker",
-    "update-docs": "code-tweaker",
-    "commit-and-document": "code-tweaker",
-    "prototype": "code-tweaker",
-    "scaffold-context": "code-tweaker",
-    "verify": "code-tweaker",
-    "fix": "system-architect",
-    "feature": "system-architect",
-    "refactor": "system-architect",
-    "explore": "system-architect",
-    "triage": "system-architect",
-    "review": "system-architect"
-  },
-  helpers: {
-    "diagnose": "system-architect",
-    "grill-with-docs": "system-architect",
-    "improve-codebase-architecture": "system-architect",
-    "to-prd": "system-architect",
-    "to-issues": "system-architect",
-    "zoom-out": "system-architect",
-    "handoff": "system-architect",
-    "grill-me": "system-architect",
-    "write-a-skill": "code-tweaker",
-    "setup-matt-pocock-skills": "code-tweaker"
-  },
-  modelessUtilities: ["caveman"]
-};
-
-const ALLOWED_COMMAND_MODES = new Set(["system-architect", "code-tweaker", "custom-orchestrator"]);
-const BUILT_IN_MODE_NAMES = new Set([
-  "Ask",
-  "Code",
-  "Debug",
-  "Architect",
-  "Orchestrator",
-  "ask",
-  "code",
-  "debug",
-  "architect",
-  "orchestrator"
-]);
+const __dirname = path.dirname(__filename);
+const packageRoot = path.resolve(__dirname, "..");
+const templateRoot = path.join(packageRoot, "templates", "full");
+
+const COMMAND_POLICY = {
+  routed: {
+    "tweak": "code-tweaker",
+    "tdd": "code-tweaker",
+    "update-docs": "code-tweaker",
+    "commit-and-document": "code-tweaker",
+    "prototype": "code-tweaker",
+    "scaffold-context": "code-tweaker",
+    "verify": "code-tweaker",
+    "fix": "system-architect",
+    "feature": "system-architect",
+    "refactor": "system-architect",
+    "explore": "system-architect",
+    "triage": "system-architect",
+    "review": "system-architect"
+  },
+  helpers: {
+    "diagnose": "system-architect",
+    "grill-with-docs": "system-architect",
+    "improve-codebase-architecture": "system-architect",
+    "to-prd": "system-architect",
+    "to-issues": "system-architect",
+    "zoom-out": "system-architect",
+    "handoff": "system-architect",
+    "grill-me": "system-architect",
+    "write-a-skill": "code-tweaker",
+    "setup-matt-pocock-skills": "code-tweaker",
+    "teach": "code-tweaker"
+  },
+  modelessUtilities: ["caveman"]
+};
+
+const ALLOWED_COMMAND_MODES = new Set(["system-architect", "code-tweaker", "custom-orchestrator"]);
+const BUILT_IN_MODE_NAMES = new Set([
+  "Ask",
+  "Code",
+  "Debug",
+  "Architect",
+  "Orchestrator",
+  "ask",
+  "code",
+  "debug",
+  "architect",
+  "orchestrator"
+]);
 
 const command = process.argv[2];
 
 const HELP = `
 Zoo Flow
 
-Usage:
+Usage:
   npx @fernado03/zoo-flow@latest init
   npx @fernado03/zoo-flow@latest init --force
   npx @fernado03/zoo-flow@latest update
   npx @fernado03/zoo-flow@latest update --dry-run
-  npx @fernado03/zoo-flow@latest update --force
-  npx @fernado03/zoo-flow@latest doctor
-  npx @fernado03/zoo-flow@latest doctor --template-only
+  npx @fernado03/zoo-flow@latest update --force
+  npx @fernado03/zoo-flow@latest doctor
+  npx @fernado03/zoo-flow@latest doctor --template-only
 
 Commands:
   init              Install Zoo Flow into the current project
   update            Back up current config and copy the latest template
-  doctor            Validate Zoo Flow in the current project
-  doctor --template-only   Validate this package's bundled template
+  doctor            Validate Zoo Flow in the current project
+  doctor --template-only   Validate this package's bundled template
 
 Options:
   --force           Overwrite existing .roomodes and .roo after backup
@@ -191,7 +192,7 @@ function readJson(filePath) {
   }
 }
 
-function walkFiles(rootDir) {
+function walkFiles(rootDir) {
   const files = [];
 
   function walk(current) {
@@ -211,110 +212,110 @@ function walkFiles(rootDir) {
   }
 
   walk(rootDir);
-  return files;
-}
-
-function stripFrontmatter(text) {
-  if (!text.startsWith("---")) return text;
-
-  const lines = text.split(/\r?\n/);
-  for (let index = 1; index < lines.length; index += 1) {
-    if (lines[index].trim() === "---") {
-      return lines.slice(index + 1).join("\n");
-    }
-  }
-
-  return text;
-}
-
-function getFrontmatter(text) {
-  if (!text.startsWith("---")) return "";
-
-  const lines = text.split(/\r?\n/);
-  for (let index = 1; index < lines.length; index += 1) {
-    if (lines[index].trim() === "---") {
-      return lines.slice(1, index).join("\n");
-    }
-  }
-
-  return "";
-}
-
-function getFrontmatterMode(text) {
-  const frontmatter = getFrontmatter(text);
-  const match = frontmatter.match(/^mode:\s*([^\r\n#]+)\s*$/m);
-  return match ? match[1].trim().replace(/^['"]|['"]$/g, "") : null;
-}
-
-function getCommandPolicyMode(commandName) {
-  return COMMAND_POLICY.routed[commandName] || COMMAND_POLICY.helpers[commandName] || null;
-}
-
-function getPolicyCommandEntries() {
-  return Object.entries({ ...COMMAND_POLICY.routed, ...COMMAND_POLICY.helpers });
-}
-
-function isThinNonCanonicalSkillWrapper(text) {
-  const body = stripFrontmatter(text);
-  const lines = body
-    .split(/\r?\n/)
-    .map((line) => line.trim())
-    .filter(Boolean);
-
-  const runSkillLines = lines.filter((line) =>
-    /^run skill:\s*`?\.roo\/skills\/[^\s`]+SKILL\.md`?\s*$/i.test(line)
-  );
-
-  if (runSkillLines.length !== 1) return false;
-
-  const otherLines = lines.filter((line) =>
-    !/^run skill:/i.test(line) && line !== "$ARGUMENTS"
-  );
-
-  return otherLines.every(
-    (line) => line.length <= 120 && !/^(#{1,6}\s|[-*]\s|\d+[.)]\s|[A-Z][A-Z\s]+:)/.test(line)
-  );
-}
-
-function getRoutedCommandRows(routingText) {
-  const routedSection = routingText.match(/## Routed commands\s*\n([\s\S]*?)(?=\n## |$)/);
-  if (!routedSection) return [];
-
-  return routedSection[1]
-    .split(/\r?\n/)
-    .map((line) => line.trim())
-    .filter((line) => line.startsWith("|") && !/^\|\s*-+/.test(line))
-    .map((line) => line.split("|").slice(1, -1).map((cell) => cell.trim()))
-    .filter((cells) => cells.length >= 3 && cells[1].includes("`/"));
-}
-
-function findPositiveBuiltInDelegation(text) {
-  const findings = [];
-  const target = "(ask|code|debug|architect|orchestrator)";
-  const end = "(?=$|[\\s.,;:)\\]`])";
-  const optionalBacktick = "[`]?";
-  const patterns = [
-    new RegExp("\\bnew_task\\b[^\\n]*(?:to|target|slug:)\\s*" + optionalBacktick + target + optionalBacktick + end, "i"),
-    new RegExp("\\bdelegate(?:s|d)?\\b[^\\n]*(?:to|into|with)\\s*" + optionalBacktick + target + optionalBacktick + end, "i"),
-    new RegExp("\\bswitch_mode\\b[^\\n]*(?:to|->|slug:)\\s*" + optionalBacktick + target + optionalBacktick + end, "i"),
-    new RegExp("\\bswitch\\s+to\\s*" + optionalBacktick + target + "(?:\\s+mode)?" + optionalBacktick + end, "i")
-  ];
-
-  const negativePattern = /\b(never|do not|don't|must not|no valid|not fall back|outside zoo flow)\b/i;
-
-  for (const line of text.split(/\r?\n/)) {
-    const trimmed = line.trim();
-    if (!trimmed || negativePattern.test(trimmed)) continue;
-
-    if (patterns.some((pattern) => pattern.test(trimmed))) {
-      findings.push(trimmed);
-    }
-  }
-
-  return findings;
-}
-
-function validateTemplate(rootDir) {
+  return files;
+}
+
+function stripFrontmatter(text) {
+  if (!text.startsWith("---")) return text;
+
+  const lines = text.split(/\r?\n/);
+  for (let index = 1; index < lines.length; index += 1) {
+    if (lines[index].trim() === "---") {
+      return lines.slice(index + 1).join("\n");
+    }
+  }
+
+  return text;
+}
+
+function getFrontmatter(text) {
+  if (!text.startsWith("---")) return "";
+
+  const lines = text.split(/\r?\n/);
+  for (let index = 1; index < lines.length; index += 1) {
+    if (lines[index].trim() === "---") {
+      return lines.slice(1, index).join("\n");
+    }
+  }
+
+  return "";
+}
+
+function getFrontmatterMode(text) {
+  const frontmatter = getFrontmatter(text);
+  const match = frontmatter.match(/^mode:\s*([^\r\n#]+)\s*$/m);
+  return match ? match[1].trim().replace(/^['"]|['"]$/g, "") : null;
+}
+
+function getCommandPolicyMode(commandName) {
+  return COMMAND_POLICY.routed[commandName] || COMMAND_POLICY.helpers[commandName] || null;
+}
+
+function getPolicyCommandEntries() {
+  return Object.entries({ ...COMMAND_POLICY.routed, ...COMMAND_POLICY.helpers });
+}
+
+function isThinNonCanonicalSkillWrapper(text) {
+  const body = stripFrontmatter(text);
+  const lines = body
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+
+  const runSkillLines = lines.filter((line) =>
+    /^run skill:\s*`?\.roo\/skills\/[^\s`]+SKILL\.md`?\s*$/i.test(line)
+  );
+
+  if (runSkillLines.length !== 1) return false;
+
+  const otherLines = lines.filter((line) =>
+    !/^run skill:/i.test(line) && line !== "$ARGUMENTS"
+  );
+
+  return otherLines.every(
+    (line) => line.length <= 120 && !/^(#{1,6}\s|[-*]\s|\d+[.)]\s|[A-Z][A-Z\s]+:)/.test(line)
+  );
+}
+
+function getRoutedCommandRows(routingText) {
+  const routedSection = routingText.match(/## Routed commands\s*\n([\s\S]*?)(?=\n## |$)/);
+  if (!routedSection) return [];
+
+  return routedSection[1]
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line.startsWith("|") && !/^\|\s*-+/.test(line))
+    .map((line) => line.split("|").slice(1, -1).map((cell) => cell.trim()))
+    .filter((cells) => cells.length >= 3 && cells[1].includes("`/"));
+}
+
+function findPositiveBuiltInDelegation(text) {
+  const findings = [];
+  const target = "(ask|code|debug|architect|orchestrator)";
+  const end = "(?=$|[\\s.,;:)\\]`])";
+  const optionalBacktick = "[`]?";
+  const patterns = [
+    new RegExp("\\bnew_task\\b[^\\n]*(?:to|target|slug:)\\s*" + optionalBacktick + target + optionalBacktick + end, "i"),
+    new RegExp("\\bdelegate(?:s|d)?\\b[^\\n]*(?:to|into|with)\\s*" + optionalBacktick + target + optionalBacktick + end, "i"),
+    new RegExp("\\bswitch_mode\\b[^\\n]*(?:to|->|slug:)\\s*" + optionalBacktick + target + optionalBacktick + end, "i"),
+    new RegExp("\\bswitch\\s+to\\s*" + optionalBacktick + target + "(?:\\s+mode)?" + optionalBacktick + end, "i")
+  ];
+
+  const negativePattern = /\b(never|do not|don't|must not|no valid|not fall back|outside zoo flow)\b/i;
+
+  for (const line of text.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || negativePattern.test(trimmed)) continue;
+
+    if (patterns.some((pattern) => pattern.test(trimmed))) {
+      findings.push(trimmed);
+    }
+  }
+
+  return findings;
+}
+
+function validateTemplate(rootDir) {
   const roomodesPath = path.join(rootDir, ".roomodes");
   const rooDir = path.join(rootDir, ".roo");
   const commandsDir = path.join(rooDir, "commands");
@@ -329,38 +330,38 @@ function validateTemplate(rootDir) {
   if (!pathExists(skillsDir)) failures.push("Missing .roo/skills/");
   if (!pathExists(rulesDir)) failures.push("Missing .roo/rules/");
 
-  let roomodes = null;
-
-  if (pathExists(roomodesPath)) {
-    try {
-      roomodes = readJson(roomodesPath);
-      if (!Array.isArray(roomodes.customModes)) {
-        failures.push(".roomodes must contain customModes array");
-      }
-    } catch (error) {
-      failures.push(error.message);
-    }
-  }
-
-  // Validate command references. Commands may either declare a skill via
-  // `Skill: .roo/skills/.../SKILL.md` or contain workflow steps directly.
-  if (pathExists(commandsDir)) {
-    const skillRefRegex = /^Skill:\s*`?(\.roo\/skills\/[^\s`]+SKILL\.md)`?\s*$/m;
-
+  let roomodes = null;
+
+  if (pathExists(roomodesPath)) {
+    try {
+      roomodes = readJson(roomodesPath);
+      if (!Array.isArray(roomodes.customModes)) {
+        failures.push(".roomodes must contain customModes array");
+      }
+    } catch (error) {
+      failures.push(error.message);
+    }
+  }
+
+  // Validate command references. Commands may either declare a skill via
+  // `Skill: .roo/skills/.../SKILL.md` or contain workflow steps directly.
+  if (pathExists(commandsDir)) {
+    const skillRefRegex = /^Skill:\s*`?(\.roo\/skills\/[^\s`]+SKILL\.md)`?\s*$/m;
+
     for (const entry of fs.readdirSync(commandsDir)) {
       if (!entry.endsWith(".md")) continue;
 
-      const commandFile = path.join(commandsDir, entry);
-      const text = fs.readFileSync(commandFile, "utf8");
-      const match = text.match(skillRefRegex);
-
-      if (isThinNonCanonicalSkillWrapper(text)) {
-        failures.push(
-          `Command ${path.relative(rootDir, commandFile)} uses non-canonical skill wrapper. Use \`Skill: .roo/skills/.../SKILL.md\`.`
-        );
-      }
-
-      if (!match) continue;
+      const commandFile = path.join(commandsDir, entry);
+      const text = fs.readFileSync(commandFile, "utf8");
+      const match = text.match(skillRefRegex);
+
+      if (isThinNonCanonicalSkillWrapper(text)) {
+        failures.push(
+          `Command ${path.relative(rootDir, commandFile)} uses non-canonical skill wrapper. Use \`Skill: .roo/skills/.../SKILL.md\`.`
+        );
+      }
+
+      if (!match) continue;
 
       const skillRelative = match[1];
       const skillAbsolute = path.join(rootDir, skillRelative);
@@ -369,112 +370,112 @@ function validateTemplate(rootDir) {
         failures.push(
           `Command ${path.relative(rootDir, commandFile)} references missing skill: ${skillRelative}`
         );
-      }
-    }
-  }
-
-  const routingPath = path.join(rootDir, ".roo", "rules-custom-orchestrator", "00-routing.md");
-  const allowedRoutedModes = new Set(["system-architect", "code-tweaker"]);
-
-  if (pathExists(routingPath)) {
-    const routingText = fs.readFileSync(routingPath, "utf8");
-    const routedRows = getRoutedCommandRows(routingText);
-
-    if (routedRows.length === 0) {
-      failures.push("Routing table missing routed command rows");
-    }
-
-    for (const cells of routedRows) {
-      const commandMatch = cells[1].match(/`\/(.+?)`/);
-      const mode = cells[2].replace(/`/g, "");
-
-      if (commandMatch) {
-        const commandName = commandMatch[1];
-        const commandPath = path.join(commandsDir, `${commandName}.md`);
-        if (!pathExists(commandPath)) {
-          failures.push(`Routed command /${commandName} is missing .roo/commands/${commandName}.md`);
-        }
-      }
-
-      if (!allowedRoutedModes.has(mode)) {
-        failures.push(`Routed command table uses invalid mode slug: ${mode}`);
-      }
-    }
-  } else {
-    failures.push("Missing .roo/rules-custom-orchestrator/00-routing.md");
-  }
-
-  if (roomodes && Array.isArray(roomodes.customModes)) {
-    const slugs = new Set(roomodes.customModes.map((mode) => mode.slug));
-    for (const slug of ["custom-orchestrator", "system-architect", "code-tweaker"]) {
-      if (!slugs.has(slug)) {
-        failures.push(`Missing required mode slug in .roomodes: ${slug}`);
-      }
-    }
-
-    const modesBySlug = new Map(roomodes.customModes.map((mode) => [mode.slug, mode]));
-    for (const [commandName, modeSlug] of getPolicyCommandEntries()) {
-      const mode = modesBySlug.get(modeSlug);
-      const instructions = mode && typeof mode.customInstructions === "string" ? mode.customInstructions : "";
-      if (!instructions.includes(`/${commandName}`)) {
-        failures.push(`.roomodes ${modeSlug} does not permit documented command /${commandName}`);
-      }
-    }
-  }
-
-  if (pathExists(commandsDir)) {
-    for (const [commandName, expectedMode] of getPolicyCommandEntries()) {
-      const commandPath = path.join(commandsDir, `${commandName}.md`);
-      if (!pathExists(commandPath)) {
-        failures.push(`Command policy references missing command file: .roo/commands/${commandName}.md`);
-        continue;
-      }
-
-      const commandText = fs.readFileSync(commandPath, "utf8");
-      const actualMode = getFrontmatterMode(commandText);
-      if (actualMode !== expectedMode) {
-        failures.push(`Command .roo/commands/${commandName}.md must declare mode: ${expectedMode}`);
-      }
-    }
-
-    for (const commandName of COMMAND_POLICY.modelessUtilities) {
-      const commandPath = path.join(commandsDir, `${commandName}.md`);
-      if (!pathExists(commandPath)) {
-        failures.push(`Command policy references missing modeless utility: .roo/commands/${commandName}.md`);
-      }
-    }
-
-    for (const entry of fs.readdirSync(commandsDir)) {
-      if (!entry.endsWith(".md")) continue;
-
-      const commandName = entry.slice(0, -3);
-      const commandPath = path.join(commandsDir, entry);
-      const commandText = fs.readFileSync(commandPath, "utf8");
-      const mode = getFrontmatterMode(commandText);
-
-      if (mode && !ALLOWED_COMMAND_MODES.has(mode)) {
-        failures.push(`Command .roo/commands/${entry} uses invalid mode: ${mode}`);
-      }
-
-      if (mode && BUILT_IN_MODE_NAMES.has(mode)) {
-        failures.push(`Command .roo/commands/${entry} uses built-in/default mode: ${mode}`);
-      }
-
-      if (!getCommandPolicyMode(commandName) && !COMMAND_POLICY.modelessUtilities.includes(commandName)) {
-        failures.push(`Command .roo/commands/${entry} is missing from command policy`);
-      }
-    }
-  }
-
-  const allFiles = [];
-  for (const validationRoot of [roomodesPath, rooDir, path.join(rootDir, ".zoo-flow")]) {
-    if (pathExists(validationRoot)) {
-      allFiles.push(...walkFiles(validationRoot));
-    }
-  }
+      }
+    }
+  }
+
+  const routingPath = path.join(rootDir, ".roo", "rules-custom-orchestrator", "00-routing.md");
+  const allowedRoutedModes = new Set(["system-architect", "code-tweaker"]);
+
+  if (pathExists(routingPath)) {
+    const routingText = fs.readFileSync(routingPath, "utf8");
+    const routedRows = getRoutedCommandRows(routingText);
+
+    if (routedRows.length === 0) {
+      failures.push("Routing table missing routed command rows");
+    }
+
+    for (const cells of routedRows) {
+      const commandMatch = cells[1].match(/`\/(.+?)`/);
+      const mode = cells[2].replace(/`/g, "");
+
+      if (commandMatch) {
+        const commandName = commandMatch[1];
+        const commandPath = path.join(commandsDir, `${commandName}.md`);
+        if (!pathExists(commandPath)) {
+          failures.push(`Routed command /${commandName} is missing .roo/commands/${commandName}.md`);
+        }
+      }
+
+      if (!allowedRoutedModes.has(mode)) {
+        failures.push(`Routed command table uses invalid mode slug: ${mode}`);
+      }
+    }
+  } else {
+    failures.push("Missing .roo/rules-custom-orchestrator/00-routing.md");
+  }
+
+  if (roomodes && Array.isArray(roomodes.customModes)) {
+    const slugs = new Set(roomodes.customModes.map((mode) => mode.slug));
+    for (const slug of ["custom-orchestrator", "system-architect", "code-tweaker"]) {
+      if (!slugs.has(slug)) {
+        failures.push(`Missing required mode slug in .roomodes: ${slug}`);
+      }
+    }
+
+    const modesBySlug = new Map(roomodes.customModes.map((mode) => [mode.slug, mode]));
+    for (const [commandName, modeSlug] of getPolicyCommandEntries()) {
+      const mode = modesBySlug.get(modeSlug);
+      const instructions = mode && typeof mode.customInstructions === "string" ? mode.customInstructions : "";
+      if (!instructions.includes(`/${commandName}`)) {
+        failures.push(`.roomodes ${modeSlug} does not permit documented command /${commandName}`);
+      }
+    }
+  }
+
+  if (pathExists(commandsDir)) {
+    for (const [commandName, expectedMode] of getPolicyCommandEntries()) {
+      const commandPath = path.join(commandsDir, `${commandName}.md`);
+      if (!pathExists(commandPath)) {
+        failures.push(`Command policy references missing command file: .roo/commands/${commandName}.md`);
+        continue;
+      }
+
+      const commandText = fs.readFileSync(commandPath, "utf8");
+      const actualMode = getFrontmatterMode(commandText);
+      if (actualMode !== expectedMode) {
+        failures.push(`Command .roo/commands/${commandName}.md must declare mode: ${expectedMode}`);
+      }
+    }
+
+    for (const commandName of COMMAND_POLICY.modelessUtilities) {
+      const commandPath = path.join(commandsDir, `${commandName}.md`);
+      if (!pathExists(commandPath)) {
+        failures.push(`Command policy references missing modeless utility: .roo/commands/${commandName}.md`);
+      }
+    }
+
+    for (const entry of fs.readdirSync(commandsDir)) {
+      if (!entry.endsWith(".md")) continue;
+
+      const commandName = entry.slice(0, -3);
+      const commandPath = path.join(commandsDir, entry);
+      const commandText = fs.readFileSync(commandPath, "utf8");
+      const mode = getFrontmatterMode(commandText);
+
+      if (mode && !ALLOWED_COMMAND_MODES.has(mode)) {
+        failures.push(`Command .roo/commands/${entry} uses invalid mode: ${mode}`);
+      }
+
+      if (mode && BUILT_IN_MODE_NAMES.has(mode)) {
+        failures.push(`Command .roo/commands/${entry} uses built-in/default mode: ${mode}`);
+      }
+
+      if (!getCommandPolicyMode(commandName) && !COMMAND_POLICY.modelessUtilities.includes(commandName)) {
+        failures.push(`Command .roo/commands/${entry} is missing from command policy`);
+      }
+    }
+  }
+
+  const allFiles = [];
+  for (const validationRoot of [roomodesPath, rooDir, path.join(rootDir, ".zoo-flow")]) {
+    if (pathExists(validationRoot)) {
+      allFiles.push(...walkFiles(validationRoot));
+    }
+  }
   const textFileExtensions = new Set([".md", ".json", ".txt", ".yaml", ".yml"]);
 
-  for (const file of allFiles) {
+  for (const file of allFiles) {
     const ext = path.extname(file);
     if (!textFileExtensions.has(ext)) continue;
 
@@ -490,28 +491,28 @@ function validateTemplate(rootDir) {
       "APP_MAP.md"
     ];
 
-    for (const pattern of badPatterns) {
-      if (text.includes(pattern)) {
-        failures.push(`Bad pattern "${pattern}" in ${path.relative(rootDir, file)}`);
-      }
-    }
-  }
-
-  const runtimeFiles = allFiles.filter((file) => {
-    const relative = path.relative(rootDir, file).replace(/\\/g, "/");
-    return relative === ".roomodes" || /^\.roo\/rules(?:-|\/)/.test(relative);
-  });
-
-  for (const file of runtimeFiles) {
-    const text = fs.readFileSync(file, "utf8");
-    const findings = findPositiveBuiltInDelegation(text);
-
-    for (const finding of findings) {
-      failures.push(
-        `Built-in/default delegation target in ${path.relative(rootDir, file)}: ${finding}`
-      );
-    }
-  }
+    for (const pattern of badPatterns) {
+      if (text.includes(pattern)) {
+        failures.push(`Bad pattern "${pattern}" in ${path.relative(rootDir, file)}`);
+      }
+    }
+  }
+
+  const runtimeFiles = allFiles.filter((file) => {
+    const relative = path.relative(rootDir, file).replace(/\\/g, "/");
+    return relative === ".roomodes" || /^\.roo\/rules(?:-|\/)/.test(relative);
+  });
+
+  for (const file of runtimeFiles) {
+    const text = fs.readFileSync(file, "utf8");
+    const findings = findPositiveBuiltInDelegation(text);
+
+    for (const finding of findings) {
+      failures.push(
+        `Built-in/default delegation target in ${path.relative(rootDir, file)}: ${finding}`
+      );
+    }
+  }
 
   const requiredRules = [
     ".roo/rules/00-paths.md",
@@ -710,7 +711,7 @@ function doctor() {
     }
     console.log("");
   }
-}
+}
 
 function update() {
   const args = new Set(process.argv.slice(3));

package/docs/skills-index.md

@@ -12,17 +12,20 @@ paths, so this index is not required for runtime execution.
 
 | Skill | Path |
 |---|---|
+| `commit-and-document` | `.roo/skills/engineering/commit-and-document/SKILL.md` |
 | `diagnose` | `.roo/skills/engineering/diagnose/SKILL.md` |
 | `grill-with-docs` | `.roo/skills/engineering/grill-with-docs/SKILL.md` |
 | `improve-codebase-architecture` | `.roo/skills/engineering/improve-codebase-architecture/SKILL.md` |
 | `prototype` | `.roo/skills/engineering/prototype/SKILL.md` |
 | `review` | `.roo/skills/engineering/review/SKILL.md` |
+| `scaffold-context` | `.roo/skills/engineering/scaffold-context/SKILL.md` |
 | `setup-matt-pocock-skills` | `.roo/skills/engineering/setup-matt-pocock-skills/SKILL.md` |
 | `tdd` | `.roo/skills/engineering/tdd/SKILL.md` |
 | `to-issues` | `.roo/skills/engineering/to-issues/SKILL.md` |
 | `to-prd` | `.roo/skills/engineering/to-prd/SKILL.md` |
 | `triage` | `.roo/skills/engineering/triage/SKILL.md` |
 | `tweak` | `.roo/skills/engineering/tweak/SKILL.md` |
+| `update-docs` | `.roo/skills/engineering/update-docs/SKILL.md` |
 | `verify` | `.roo/skills/engineering/verify/SKILL.md` |
 | `zoom-out` | `.roo/skills/engineering/zoom-out/SKILL.md` |
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fernado03/zoo-flow",
   "description": "Workflow control plane for Zoo Code.",
-  "version": "0.8.8",
+  "version": "0.9.0",
   "type": "module",
   "bin": {
     "zoo-flow": "bin/zoo-flow.js"

package/templates/full/.roo/commands/feature.md

@@ -17,6 +17,6 @@ EXECUTION RULES (Run sequentially. Wait for user between phases):
 5. IMPLEMENT (Tweaker):
    - Architect summarizes issues.
    - Architect MUST `switch_mode` -> `code-tweaker`.
-   - Tweaker: For each issue, execute the `/tdd` command workflow (per `.roo/rules/01-command-protocol.md`). After each ships, suggest `/verify`, then `/review`, then `/commit-and-document`. Do not auto-launch.
+   - Tweaker: For each issue, execute the `/tdd` command workflow (per `.roo/rules/01-command-protocol.md`). After each ships, suggest `/verify`, then `/review` (requires `switch_mode` back to system-architect), then `/commit-and-document`. Do not auto-launch.
 
 $ARGUMENTS

package/templates/full/.roo/commands/refactor.md

@@ -14,6 +14,7 @@ EXECUTION RULES:
    - Architect summarizes approved plan.
    - Architect MUST `switch_mode` -> `code-tweaker`.
    - Tweaker executes the `/tdd` command workflow (per `.roo/rules/01-command-protocol.md`) — new tests at interface, delete old.
-   - Tweaker suggests `/verify`, then `/review`, then `/commit-and-document`. Do not auto-launch.
+   - Tweaker suggests `/verify`, then `/review` (requires `switch_mode` back to system-architect), then `/commit-and-document`. Do not auto-launch.
+   - Tweaker calls `attempt_completion` with: what was refactored, files changed, tests added, status, and recommended next command.
 
 $ARGUMENTS

package/templates/full/.roo/commands/review.md

@@ -1,5 +1,5 @@
 ---
-description: "Review a diff or branch against the requested spec, project standards, architecture, and likely regressions. Use before committing non-trivial work."
+description: "Review a diff, branch, PR, or work-in-progress change against the requested spec, project standards, architecture, and likely regressions. Use before committing non-trivial work."
 argument-hint: <optional base ref, files, issue, PRD, or review focus>
 mode: system-architect
 ---

package/templates/full/.roo/commands/teach.md

@@ -1,6 +1,7 @@
 ---
 description: "Teach a topic over multiple stateful sessions. Tracks mission, glossary, resources, and learning records. Use when user asks to be taught a topic, wants to learn something, or mentions ongoing study."
 argument-hint: "What would you like to learn about?"
+mode: code-tweaker
 ---
 
 Skill: `.roo/skills/productivity/teach/SKILL.md`

package/templates/full/.roo/commands/triage.md

@@ -1,5 +1,6 @@
 ---
 description: "Triage issues through a state machine driven by triage roles. Use when user wants to create an issue, triage issues, review incoming bugs or feature requests, prepare issues for an AFK agent, or manage issue workflow."
+argument-hint: "Describe the issue(s) to triage or 'all' to review all open issues"
 mode: system-architect
 ---
 

package/templates/full/.roo/commands/update-docs.md

@@ -8,7 +8,7 @@ Update repo documentation so it matches the current code. Surgical edits only
 
 Skill: `.roo/skills/engineering/update-docs/SKILL.md`
 
-Find the target doc in `.zoo-flow/` or `docs/`. If it does not exist, ask once: "No <slot> found. Create a stub at .zoo-flow/<slot>? (yes / pick-existing / skip)".
+Find the target doc in `.zoo-flow/` or `docs/`. If it does not exist, ask once: "No <doc> found. Create a stub at .zoo-flow/<doc>? (yes / pick-existing / skip)".
 
 Do NOT use this for:
 

package/templates/full/.roo/rules/04-context-economy.md

@@ -21,7 +21,7 @@ Read domain docs only when at least one is true:
 - The task touches domain language or terminology.
 - The task changes public behavior.
 - The task changes architecture, module seams, persistence, API shape, auth, payments, security, migrations, or cross-module design.
-- The command explicitly requires those docs (e.g. `/feature`, `/refactor`, `/grill-with-docs`, `/scaffold-context`, `/update-docs`).
+- The command explicitly requires those docs (e.g. `/feature`, `/refactor`, `/grill-with-docs`, `/scaffold-context`, `/update-docs`, `/tdd`).
 - The user asks for documentation, architecture, product, or domain-context work.
 
 Missing CONTEXT.md or ADRs is not an error. Proceed silently when nothing is present.

package/templates/full/.roo/rules-custom-orchestrator/00-routing.md

@@ -22,9 +22,9 @@ Never delegate to built-in/default modes, including Ask, Code, Debug, Architect,
 
 Slash commands bypass this — the extension reads `mode:` from the command frontmatter and switches directly.
 
-If a task sounds like "ask", "inspect", "review", "branch review", "pre-commit review", "analyze", "deep inspection", "investigate", or "reason about safety", route it to `system-architect`.
+If a task sounds like "ask", "inspect", "review", "branch review", "pre-commit review", "analyze", "deep inspection", "investigate", or "reason about safety", route it to `system-architect`.
 
-If a task requires source edits, tests, verification, docs updates, prototypes, or commits, route it to `code-tweaker`.
+If a task requires source edits, tests, verification, docs updates, prototypes, or commits, route it to `code-tweaker`.
 
 If neither custom mode is suitable, stop and report that no valid Zoo Flow mode exists. Do not fall back to Ask mode.
 
@@ -40,7 +40,7 @@ Users are not expected to know slash commands. For free-form requests, infer the
 
 ## User-facing workflow names
 
-Slash commands are internal routing labels unless the user explicitly typed one or asked for syntax. For free-form requests, use plain-language workflow names only: small implementation, test-first, diagnosis, feature planning, refactor planning, exploration, documentation update, commit and journal, prototype, issue triage, review, verification. Never show slash commands as selectable options for free-form requests. Internal delegation may still use the slash command after approval.
+Slash commands are internal routing labels unless the user explicitly typed one or asked for syntax. For free-form requests, use plain-language workflow names only: small implementation, test-first, diagnosis, feature planning, refactor planning, exploration, documentation update, commit and journal, prototype, issue triage, review, verification. Never show slash commands as selectable options for free-form requests. Internal delegation may still use the slash command after approval.
 
 ## Routed commands
 
@@ -51,17 +51,18 @@ Slash commands are internal routing labels unless the user explicitly typed one
 | documentation update | `/update-docs`         | code-tweaker     |
 | commit and journal   | `/commit-and-document` | code-tweaker     |
 | prototype            | `/prototype`           | code-tweaker     |
+| context scaffolding  | `/scaffold-context`    | code-tweaker     |
 | diagnosis            | `/fix`                 | system-architect |
 | feature planning     | `/feature`             | system-architect |
 | refactor planning    | `/refactor`            | system-architect |
-| exploration          | `/explore`             | system-architect |
-| issue triage         | `/triage`              | system-architect |
-| review               | `/review`              | system-architect |
-| verification         | `/verify`              | code-tweaker     |
+| exploration          | `/explore`             | system-architect |
+| issue triage         | `/triage`              | system-architect |
+| review               | `/review`              | system-architect |
+| verification         | `/verify`              | code-tweaker     |
 
 ## Routing decision guide
 
-Read intent, not keywords. Top-down: 1. unknown code area or unclear next move → exploration; 2. broken behavior with unknown cause → diagnosis; 3. new capability needing design, PRD, issue slicing, or phase gates → feature planning; 4. working behavior but structure is the problem → refactor planning; 5. small known low-risk change → small implementation; 6. clear behavior and interface, user wants tests first → test-first; 7. throwaway design/state/UI uncertainty → prototype; 8. docs drift from code → documentation update; 9. finished work needs commit/journal → commit and journal; 10. issue creation, sorting, labels, or tracker workflow → issue triage; 11. diff, branch, PR, standards, architecture, or pre-commit inspection → review; 12. check if this passes, run tests for this change, verify the branch, or make sure nothing broke → verification.
+Read intent, not keywords. Top-down: 1. unknown code area or unclear next move → exploration; 2. broken behavior with unknown cause → diagnosis; 3. new capability needing design, PRD, issue slicing, or phase gates → feature planning; 4. working behavior but structure is the problem → refactor planning; 5. small known low-risk change → small implementation; 6. clear behavior and interface, user wants tests first → test-first; 7. throwaway design/state/UI uncertainty → prototype; 8. docs drift from code → documentation update; 9. finished work needs commit/journal → commit and journal; 10. issue creation, sorting, labels, or tracker workflow → issue triage; 11. diff, branch, PR, standards, architecture, or pre-commit inspection → review; 12. check if this passes, run tests for this change, verify the branch, or make sure nothing broke → verification.
 
 ## Routing weight
 
@@ -69,7 +70,7 @@ Prefer the lightest workflow that preserves correctness. Use small implementatio
 
 ## Risk levels
 
-Use risk to choose the lightest safe workflow. Risk does not override command intent; explicit slash commands still route as-is. R1 copy/style/doc typo/one-line obvious edit → small implementation. R2 localized code change with known target → small implementation or test-first. R3 behavior change with clear interface → test-first, then suggest verification or review. R4 cross-module change or design tradeoff → feature planning or refactor planning, then suggest verification and review. R5 auth/payments/security/migrations/data loss/external API contracts → strict planning/diagnosis with explicit approval gates, then suggest verification and review.
+Use risk to choose the lightest safe workflow. Risk does not override command intent; explicit slash commands still route as-is. R1 copy/style/doc typo/one-line obvious edit → small implementation. R2 localized code change with known target → small implementation or test-first. R3 behavior change with clear interface → test-first, then suggest verification or review. R4 cross-module change or design tradeoff → feature planning or refactor planning, then suggest verification and review. R5 auth/payments/security/migrations/data loss/external API contracts → strict planning/diagnosis with explicit approval gates, then suggest verification and review.
 
 ## Disambiguation
 
@@ -81,20 +82,20 @@ Explicit slash command from user = approval; route as-is. Clear free-form reques
 
 ## Approval gate
 
-The orchestrator proposes; the user approves; then the orchestrator delegates. Slash commands are auto-approved — the extension switches mode and executes immediately. A free-form request is never self-approving; propose a workflow and wait for approval. Present the recommendation, then stop and wait. Treat replies as approval only when they select the proposed workflow by number, option text, or clear restatement. A fresh free-form request restarts routing. If unsure whether the user approved, ask.
+The orchestrator proposes; the user approves; then the orchestrator delegates. Slash commands are auto-approved — the extension switches mode and executes immediately. A free-form request is never self-approving; propose a workflow and wait for approval. Present the recommendation, then stop and wait. Treat replies as approval only when they select the proposed workflow by number, option text, or clear restatement. A fresh free-form request restarts routing. If unsure whether the user approved, ask.
 
 ## Delegation
 
-Delegate only after the approval gate is satisfied. Choose the safest proceed policy from `01-delegation-message.md`.
-
-## Follow-up recommendations
-
-For non-trivial work, suggest the next command chain only after the current command completes. Do not auto-launch follow-up commands merely because they are mentioned.
-
-Recommended chains:
-
-- test-first → verification → review → commit and journal
-- diagnosis → verification → review → commit and journal
-- refactor planning → verification → review → commit and journal
-- feature planning → verification → review → commit and journal
-- small implementation → verification or review when risk is R3+
+Delegate only after the approval gate is satisfied. Choose the safest proceed policy from `01-delegation-message.md`.
+
+## Follow-up recommendations
+
+For non-trivial work, suggest the next command chain only after the current command completes. Do not auto-launch follow-up commands merely because they are mentioned.
+
+Recommended chains:
+
+- test-first → verification → review → commit and journal
+- diagnosis → verification → review → commit and journal
+- refactor planning → verification → review → commit and journal
+- feature planning → verification → review → commit and journal
+- small implementation → verification or review when risk is R3+

package/templates/full/.roo/rules-system-architect/02-completion.md

@@ -2,23 +2,19 @@
 
 A delegated task is the **entire command chain**, including every phase and every mode switch the command body defines — not the single phase you are currently running.
 
-## CRITICAL: Never switch to "code" mode
+## CRITICAL: Valid mode slugs
 
-When implementation is needed, you MUST:
-1. Call `attempt_completion` with the recommended next command (e.g., `/feature`)
-2. Wait for the orchestrator to route the task
-3. The orchestrator will delegate to `code-tweaker`
+The only valid mode slugs for `switch_mode` are:
+- `code-tweaker` — for implementation, tests, source-code edits
+- `system-architect` — for planning, review, diagnosis
 
-NEVER call `switch_mode` directly to "code", "Code", or any variant. The only valid mode slugs are:
-- `code-tweaker` (for implementation)
-- `system-architect` (for planning/review)
-
-If you need implementation, call `attempt_completion` and recommend the next command. Do not switch modes yourself.
+NEVER call `switch_mode` to the built-in `code`, `Code`, `ask`, `Ask`, `debug`, `Debug`, `architect`, `Architect`, or `Orchestrator` modes. Those slugs do not exist in Zoo Flow.
 
 ## Choosing your exit
 
-- **More phases remain** (this or a later phase is assigned to `code-tweaker`, or control returns to you afterward): use `switch_mode` to `code-tweaker` (exact slug, never `code`). Never `attempt_completion`. Writing a plan, diagnosis, or `.scratch/` notes is not "done" — it is a handoff. Switch to `code-tweaker` to implement.
+- **More phases remain** (this or a later phase is assigned to `code-tweaker`, or control returns to you afterward): use `switch_mode` to `code-tweaker` (exact slug, never `code`). Never `attempt_completion` mid-chain. Writing a plan, diagnosis, or `.scratch/` notes is not "done" — it is a handoff. Switch to `code-tweaker` to implement.
 - **You are running the command's final phase** and it is complete or blocked: use `attempt_completion` to return to the orchestrator.
+- **Standalone command with no implementation phase** (e.g. `/review`, `/explore`, `/grill-with-docs`, `/triage`): use `attempt_completion` with the recommended next command.
 
 If you entered this window via `switch_mode` (you are mid-chain, not the entry point) and any phase remains, you hand back with `switch_mode`. Only the command's final phase returns to the orchestrator.
 
@@ -46,4 +42,4 @@ Halt for explicit user approval before testing a bug hypothesis, finalizing an a
 
 For non-trivial completed plans or reviews, recommend the next command only. Typical chain: implementation command -> `/verify` -> `/review` -> `/commit-and-document`. Do not auto-launch those commands.
 
-If the user explicitly says to remember a project rule, or the same mistake has repeated, ask before appending a short lesson to `.zoo-flow/LESSONS.md`. Do not read or write lessons by default.
+If the user explicitly says to remember a project rule, or the same mistake has repeated, ask before appending a short lesson to `.zoo-flow/LESSONS.md`. Do not read or write lessons by default.

package/templates/full/.roo/skills/engineering/commit-and-document/SKILL.md

@@ -31,7 +31,7 @@ One-line message:
 - **scope**: area touched. Omit parens if unclear.
 - **summary**: imperative, present tense, under 70 chars, starts with a verb.
 
-Show: proposed message, files to stage, files excluded (tests, docs, secrets). Ask: "Commit with this message? (yes / edit / cancel)". On `cancel`, stop and report.
+Show: proposed message, files to stage, files excluded (tests, docs, secrets). Ask: "Commit with this message? (yes / edit / cancel)". On `edit`, accept the user's revised message verbatim and re-run detection (step 2.5) on it before proceeding. On `cancel`, stop and report.
 
 ## 2.5 Detect or ask for an issue reference
 
@@ -94,7 +94,7 @@ Do not commit the gitignore change. If the user accidentally staged anything und
 
 ## 5. Inspect existing docs/journal/
 
-List `docs/journal/` if present; match its existing date/file convention. Create the directory if missing.
+List `docs/journal/` if present. If it uses a different date/file convention than the default below, follow its existing convention. Create the directory if missing.
 
 ## 6. Write a dated entry
 

package/templates/full/.roo/skills/engineering/diagnose/SKILL.md

@@ -53,6 +53,10 @@ Rules:
 
 ## 5. Fix + regression
 
+**OWNER: code-tweaker** (requires source-code edits)
+
+Architect MUST `switch_mode` to `code-tweaker` before this phase. Tweaker executes:
+
 1. If correct seam exists, write regression test before fix.
 2. Correct seam = real call-site bug pattern.
 3. If seam shallow/missing, document architecture gap.
@@ -61,6 +65,22 @@ Rules:
 6. Watch regression pass.
 7. Rerun original loop.
 
+Tweaker does NOT call `attempt_completion` here — more phases remain. Continue to Phase 6.
+
+## 6. Cleanup
+
+**OWNER: code-tweaker** (requires source-code edits and git commit)
+
+MUST finish:
+- [ ] Original repro passes.
+- [ ] Regression passes or missing seam documented.
+- [ ] `[DEBUG-...]` logs removed from source.
+- [ ] Throwaway harnesses deleted/moved.
+- [ ] Winning hypothesis stated in commit/PR.
+- [ ] Seam/locality blocker → recommend `/improve-codebase-architecture`.
+
+Tweaker MUST `switch_mode` back to `system-architect` for Phase 7.
+
 ## Context economy
 
 Before broad reads, locate relevant files/symbols with `list_files`, `search_files`, or `codebase_search`.
@@ -73,16 +93,10 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 For logs or large outputs, search for the failing marker/error first. Read only surrounding ranges needed to prove or disprove a hypothesis.
 
-## 6. Cleanup
-
-MUST finish:
-- [ ] Original repro passes.
-- [ ] Regression passes or missing seam documented.
-- [ ] `[DEBUG-...]` logs removed.
-- [ ] Throwaway harnesses deleted/moved.
-- [ ] Winning hypothesis stated in commit/PR.
-- [ ] Seam/locality blocker → recommend `/improve-codebase-architecture`.
-
 ## 7. Save
 
+**OWNER: system-architect** (writes to `.scratch/`)
+
 Write the full diagnosis (hypotheses, instrumentation, root cause, fix) to `.scratch/diagnoses/<date>/diagnose-<slug>.md`.
+
+Call `attempt_completion` with: diagnosis file path, root cause summary, fix applied, status, and recommended next command (typically `/verify` then `/review` then `/commit-and-document`).

package/templates/full/.roo/skills/engineering/grill-with-docs/SKILL.md

@@ -16,7 +16,7 @@ description: Grilling session that challenges your plan against the existing dom
 
 ## Docs
 
-See `CONTEXT-FORMAT.md` for layout and detection. Create docs lazily only when recording needed.
+See `.roo/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md` for layout and detection. Create docs lazily only when recording needed.
 
 ## Context economy
 

package/templates/full/.roo/skills/engineering/improve-codebase-architecture/SKILL.md

@@ -23,16 +23,15 @@ RULE: Use `.zoo-flow/CONTEXT.md` terms. Use glossary. Respect ADRs; surface only
 
 ## Report
 
-1. Temp dir: `$TMPDIR` else `/tmp` (Windows `%TEMP%`).
-2. Write fresh `{tmpdir}/architecture-review-{timestamp}.html`.
-3. Use Tailwind CDN + Mermaid CDN.
-4. Include candidate cards with before/after visuals.
-5. Per candidate include: files/modules; problem; solution; locality/leverage/testing benefits; diagram; strength `Strong`/`Worth exploring`/`Speculative`; ADR conflict only if real.
-6. Include Top recommendation.
-7. Open file: Linux `xdg-open {path}`, macOS `open {path}`, Windows `start {path}`.
-8. Tell user absolute path.
-9. DO NOT propose interfaces yet.
-10. Ask: `Which of these would you like to explore?`
+1. Write fresh `.scratch/architecture-review-{timestamp}.html`.
+2. Use Tailwind CDN + Mermaid CDN.
+3. Include candidate cards with before/after visuals.
+4. Per candidate include: files/modules; problem; solution; locality/leverage/testing benefits; diagram; strength `Strong`/`Worth exploring`/`Speculative`; ADR conflict only if real.
+5. Include Top recommendation.
+6. Open file: Linux `xdg-open {path}`, macOS `open {path}`, Windows `start {path}`.
+7. Tell user absolute path.
+8. DO NOT propose interfaces yet.
+9. Ask: `Which of these would you like to explore?`
 
 ## Context economy
 
@@ -52,4 +51,15 @@ Use searches to identify dependency/call patterns before reading full modules. R
 2. If module name introduces unresolved domain term, update `CONTEXT.md` lazily.
 3. If term sharpened, update `CONTEXT.md` immediately.
 4. Durable rejected reason useful later → offer ADR.
-5. Interface options requested → run interface-design workflow.
+5. Interface options requested → run interface-design workflow from `INTERFACE-DESIGN.md` in this skill directory.
+
+## Complete
+
+Call `attempt_completion` with:
+- report file path (`.scratch/architecture-review-{timestamp}.html`)
+- candidates found (count and titles)
+- user selection (which candidate was chosen, if any)
+- status (complete / blocked with reason)
+- recommended next command (`/refactor` to implement the chosen candidate, or `/feature` if it requires PRD + issue slicing)
+
+Do NOT use `ask_followup_question` or write results as plain text without calling the tool.

package/templates/full/.roo/skills/engineering/prototype/SKILL.md

@@ -34,7 +34,7 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 6. Persistence target → scratch DB/file named `PROTOTYPE — wipe me` in the prototype folder.
 7. No polish: no tests, minimal errors, no abstractions.
 8. Surface full relevant state after each action/variant switch.
-9. Done → capture answer in commit/ADR/issue/`NOTES.md`; delete or fold into real code.
+9. Done → capture answer in commit (only after explicit user approval)/ADR/issue/`NOTES.md`; delete or fold into real code.
 
 ## Complete
 
@@ -44,4 +44,4 @@ Call `attempt_completion` with:
 - outcome (absorbed / discarded / needs decision)
 - recommended next command
 
-Do NOT use `ask_followup_question` or write results as plain text without calling the tool.
+Do NOT end the task with `ask_followup_question` or write results as plain text without calling the tool.

package/templates/full/.roo/skills/engineering/to-issues/SKILL.md

@@ -43,3 +43,12 @@ Issue tracker + label vocabulary should exist; run `/setup-matt-pocock-skills` i
 ```
 
 If no blockers: `None - can start immediately`.
+
+## Complete
+
+Call `attempt_completion` with:
+- issues created (count and tracker URLs or `.scratch/{feature-slug}/issues/` path)
+- status (complete / blocked with reason)
+- recommended next command (`/tweak` or `/tdd` to start implementing the first issue)
+
+Do NOT use `ask_followup_question` or write results as plain text without calling the tool.

package/templates/full/.roo/skills/engineering/to-prd/SKILL.md

@@ -55,3 +55,12 @@ RULE: Do not interview user. Synthesize current context.
 
 {other notes}
 ```
+
+## Complete
+
+Call `attempt_completion` with:
+- PRD location (issue tracker URL or `.scratch/{feature-slug}/PRD.md` path)
+- status (complete / blocked with reason)
+- recommended next command (`/to-issues` to break it into implementation tickets)
+
+Do NOT use `ask_followup_question` or write results as plain text without calling the tool.

package/templates/full/.roo/skills/engineering/tweak/SKILL.md

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

package/templates/full/.roo/skills/engineering/update-docs/SKILL.md

@@ -51,16 +51,6 @@ Use today's date. Include only files actually inspected.
 
 After editing: re-read, confirm referenced paths exist, every major claim maps to code or a cited doc, no stale contradiction with nearby docs. Summarise the change.
 
-## Context economy
-
-Before broad reads, locate relevant files/symbols with `list_files`, `search_files`, or `codebase_search`.
-
-Prefer targeted `read_file` ranges or indentation/block reads once the relevant area is known.
-
-Read full files only when structure, ordering, or surrounding context is required for correctness.
-
-Do not re-read unchanged files; use prior findings unless the file changed.
-
 ## 7. Recommend next step
 
 Recommend one: `/explore` (still unclear), `/feature` (plan emerged), `/refactor` (tangled-but-working code), `/fix` (bug found), `/commit-and-document` (done). Do not auto-run.
@@ -74,3 +64,13 @@ Call `attempt_completion` with:
 - recommended next command
 
 Do NOT use `ask_followup_question` or write results as plain text without calling the tool.
+
+## Context economy
+
+Before broad reads, locate relevant files/symbols with `list_files`, `search_files`, or `codebase_search`.
+
+Prefer targeted `read_file` ranges or indentation/block reads once the relevant area is known.
+
+Read full files only when structure, ordering, or surrounding context is required for correctness.
+
+Do not re-read unchanged files; use prior findings unless the file changed.

package/templates/full/.roomodes

@@ -6,7 +6,7 @@
       "roleDefinition": "You are an Execution Specialist. You implement, test, update docs, prototype, and commit when explicitly approved.",
       "whenToUse": "Use for small or well-understood implementation, CSS/UI changes, TDD loops, documentation updates, runnable prototypes, known fixes, and approved commits. Do not make broad architecture decisions.",
       "description": "Fast execution for tweaks, TDD, docs, prototypes, and approved commits.",
-      "customInstructions": "Use `.roo/rules-code-tweaker/` for mode-specific behavior.\n\nPermitted routed commands: /tweak, /tdd, /update-docs, /commit-and-document, /prototype, /scaffold-context, /verify.\n\nPermitted direct helper commands: /write-a-skill, /setup-matt-pocock-skills.\n\nFollow `.roo/rules/01-command-protocol.md` to load and execute commands. Follow `.roo/rules/00-paths.md` for path safety. Follow `.roo/rules/03-manual-reply-protocol.md` when asking the user to choose, approve, or continue.\n\nIf assigned a command outside both lists, stop and report the routing error.",
+      "customInstructions": "Use `.roo/rules-code-tweaker/` for mode-specific behavior.\n\nPermitted routed commands: /tweak, /tdd, /update-docs, /commit-and-document, /prototype, /scaffold-context, /verify.\n\nPermitted direct helper commands: /write-a-skill, /setup-matt-pocock-skills, /teach.\n\nFollow `.roo/rules/01-command-protocol.md` to load and execute commands. Follow `.roo/rules/00-paths.md` for path safety. Follow `.roo/rules/03-manual-reply-protocol.md` when asking the user to choose, approve, or continue.\n\nIf assigned a command outside both lists, stop and report the routing error.",
       "groups": [
         "read",
         "edit",
@@ -20,7 +20,7 @@
       "roleDefinition": "You are a System Architect. You plan, diagnose, explore, triage, and design. You do NOT write implementation code.",
       "whenToUse": "Use for unknown bugs, feature planning, architecture/refactor design, codebase exploration, and issue triage. Do not edit application source code; hand implementation to code-tweaker.",
       "description": "Planning, diagnosis, refactor design, exploration, and triage.",
-      "customInstructions": "Use `.roo/rules-system-architect/` for mode-specific behavior.\n\nPermitted routed commands: /feature, /fix, /refactor, /explore, /triage, /review.\n\nPermitted direct helper commands: /diagnose, /grill-with-docs, /improve-codebase-architecture, /to-prd, /to-issues, /zoom-out, /handoff, /grill-me.\n\nFollow `.roo/rules/01-command-protocol.md` to load and execute commands. Follow `.roo/rules/00-paths.md` for path safety. Follow `.roo/rules/03-manual-reply-protocol.md` when asking the user to choose, approve, or continue.\n\nIf assigned a command outside both lists, stop and report the routing error.",
+      "customInstructions": "Use `.roo/rules-system-architect/` for mode-specific behavior.\n\nPermitted routed commands: /feature, /fix, /refactor, /explore, /triage, /review.\n\nPermitted direct helper commands: /diagnose, /grill-with-docs, /improve-codebase-architecture, /to-prd, /to-issues, /zoom-out, /handoff, /grill-me.\n\nFollow `.roo/rules/01-command-protocol.md` to load and execute commands. Follow `.roo/rules/00-paths.md` for path safety. Follow `.roo/rules/03-manual-reply-protocol.md` when asking the user to choose, approve, or continue.\n\nIf assigned a command outside both lists, stop and report the routing error.",
       "groups": [
         "command",
         "mcp",
@@ -40,7 +40,7 @@
       "roleDefinition": "You are a PM and router. You choose workflows and delegate subtasks. You NEVER inspect implementation files, write code, or use switch_mode.",
       "whenToUse": "Use as the default entry mode for normal user requests. Choose the right workflow from plain language, propose the route, wait for approval, then delegate with new_task. Use slash commands only when the user explicitly invokes them.",
       "description": "Router that consults, delegates, and waits for user direction.",
-      "customInstructions": "Use `.roo/rules-custom-orchestrator/` for mode-specific behavior.\n\nRoute only these commands. The exact mode slug to pass to `new_task` is shown after the arrow:\n\n- /tweak, /tdd, /update-docs, /commit-and-document, /prototype, /verify -> slug: code-tweaker\n- /fix, /feature, /refactor, /explore, /triage, /review -> slug: system-architect\n\nThe planning/architecture mode slug is ALWAYS `system-architect`. Never use `architect`.\n\nPropose, then wait for approval before delegating. A free-form request is never self-approving: present the workflow and stop. Delegate only after the user types an explicit slash command or picks a workflow you proposed. See `.roo/rules-custom-orchestrator/00-routing.md` (Approval gate).\n\nUse `new_task` only. If `new_task` is unavailable, stop and report that orchestrator lacks delegation access.\n\nFollow `.roo/rules/03-manual-reply-protocol.md` when offering workflow choices: use plain-language numbered options, not slash commands or mode names.\n\nNever use built-in/default modes for new_task. Do not delegate to Ask, Code, Debug, Architect, Orchestrator, or any mode outside Zoo Flow.\n\nFor analysis/review/inspection tasks, use slug: system-architect.\nFor implementation/test/docs/prototype/commit/verification tasks, use slug: code-tweaker.",
+      "customInstructions": "Use `.roo/rules-custom-orchestrator/` for mode-specific behavior.\n\nRoute only these commands. The exact mode slug to pass to `new_task` is shown after the arrow:\n\n- /tweak, /tdd, /update-docs, /commit-and-document, /prototype, /scaffold-context, /verify -> slug: code-tweaker\n- /fix, /feature, /refactor, /explore, /triage, /review -> slug: system-architect\n\nThe planning/architecture mode slug is ALWAYS `system-architect`. Never use `architect`.\n\nPropose, then wait for approval before delegating. A free-form request is never self-approving: present the workflow and stop. Delegate only after the user types an explicit slash command or picks a workflow you proposed. See `.roo/rules-custom-orchestrator/00-routing.md` (Approval gate).\n\nUse `new_task` only. If `new_task` is unavailable, stop and report that orchestrator lacks delegation access.\n\nFollow `.roo/rules/03-manual-reply-protocol.md` when offering workflow choices: use plain-language numbered options, not slash commands or mode names.\n\nNever use built-in/default modes for new_task. Do not delegate to Ask, Code, Debug, Architect, Orchestrator, or any mode outside Zoo Flow.\n\nFor analysis/review/inspection tasks, use slug: system-architect.\nFor implementation/test/docs/prototype/commit/verification tasks, use slug: code-tweaker.",
       "groups": []
     }
   ]

package/templates/full/.zoo-flow/evals/routing-cases.jsonl

@@ -18,3 +18,4 @@
 {"name":"R3 behavior change with clear interface","user":"Add a rate limiter to the public API. 100 req/min per key.","expected_workflow":"test-first","expected_command":"/tdd","expected_mode":"code-tweaker","must_require_approval":true,"must_not_include":["/tdd","code-tweaker","Ask mode"],"risk":"R3","context_required":true,"recommended_followup":"/verify"}
 {"name":"no doc bloat for small tweak","user":"Change the Save button text to Submit.","expected_workflow":"small implementation","expected_command":"/tweak","expected_mode":"code-tweaker","must_require_approval":true,"must_not_include":["architecture docs","domain docs","CONTEXT.md"],"risk":"R1","context_required":false,"no_doc_bloat":true}
 {"name":"diagnosis with cause unknown","user":"The payment webhook stopped firing after the last deploy.","expected_workflow":"diagnosis","expected_command":"/fix","expected_mode":"system-architect","must_require_approval":true,"must_not_include":["/fix","system-architect","Ask mode"],"risk":"R4","context_required":true}
+{"name":"context scaffolding","user":"This project has no CONTEXT.md yet. Bootstrap one.","expected_workflow":"context scaffolding","expected_command":"/scaffold-context","expected_mode":"code-tweaker","must_require_approval":true,"must_not_include":["/scaffold-context","code-tweaker","Ask mode"],"risk":"R2","context_required":false}