@fernado03/zoo-flow 0.5.2 → 0.7.0

package/bin/zoo-flow.js

@@ -5,27 +5,74 @@ 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 __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 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 --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 the 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
@@ -80,20 +127,21 @@ function backupIfExists(projectRoot, backupDir, relativePath) {
   return true;
 }
 
-const ZOO_FLOW_GITIGNORE_MARKER = "# Zoo Flow — local context scaffolding";
+const ZOO_FLOW_GITIGNORE_MARKER = "# Zoo Flow — generated config (never committed)";
 
 function appendZooFlowToGitignore(projectRoot) {
   const gi = path.join(projectRoot, ".gitignore");
+  const entries = [".roomodes", ".roo/", ".zoo-flow/"];
 
   if (pathExists(gi)) {
     const content = fs.readFileSync(gi, "utf8");
     if (content.includes(ZOO_FLOW_GITIGNORE_MARKER)) return false;
-    const addition = `\n${ZOO_FLOW_GITIGNORE_MARKER} (never committed)\n.zoo-flow/\n`;
+    const addition = `\n${ZOO_FLOW_GITIGNORE_MARKER}\n${entries.join("\n")}\n`;
     fs.appendFileSync(gi, addition);
     return true;
   }
 
-  const fresh = `${ZOO_FLOW_GITIGNORE_MARKER} (never committed)\n.zoo-flow/\n`;
+  const fresh = `${ZOO_FLOW_GITIGNORE_MARKER}\n${entries.join("\n")}\n`;
   fs.writeFileSync(gi, fresh);
   return true;
 }
@@ -143,7 +191,7 @@ function readJson(filePath) {
   }
 }
 
-function walkFiles(rootDir) {
+function walkFiles(rootDir) {
   const files = [];
 
   function walk(current) {
@@ -163,10 +211,110 @@ function walkFiles(rootDir) {
   }
 
   walk(rootDir);
-  return files;
-}
-
-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");
@@ -181,33 +329,38 @@ function validateTemplate(rootDir) {
   if (!pathExists(skillsDir)) failures.push("Missing .roo/skills/");
   if (!pathExists(rulesDir)) failures.push("Missing .roo/rules/");
 
-  if (pathExists(roomodesPath)) {
-    try {
-      const parsed = readJson(roomodesPath);
-      if (!Array.isArray(parsed.customModes)) {
-        failures.push(".roomodes must contain customModes array");
-      }
-    } catch (error) {
-      failures.push(error.message);
-    }
+  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 skill-wrapper command references. Each command file in
-  // .roo/commands/ may either declare a skill via `Skill:
-  // .roo/skills/.../SKILL.md` (skill-wrapper command) or contain its
-  // workflow steps directly. Direct-workflow commands are valid; we only
-  // verify referenced skills exist.
-  if (pathExists(commandsDir)) {
-    const skillRefRegex = /^Skill:\s*`?(\.roo\/skills\/[^\s`]+SKILL\.md)`?\s*$/m;
-
+  // 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 (!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);
@@ -216,14 +369,112 @@ function validateTemplate(rootDir) {
         failures.push(
           `Command ${path.relative(rootDir, commandFile)} references missing skill: ${skillRelative}`
         );
-      }
-    }
-  }
-
-  const allFiles = walkFiles(rootDir);
+      }
+    }
+  }
+
+  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;
 
@@ -233,15 +484,34 @@ function validateTemplate(rootDir) {
       ".roo/skills///SKILL.md",
       ".roo/commands/.md",
       "your-org/roo-flow",
-      ".zoo/"
+      ".zoo/",
+      "CONTEXT-MAP.md",
+      "FLOW.md",
+      "APP_MAP.md"
     ];
 
-    for (const pattern of badPatterns) {
-      if (text.includes(pattern)) {
-        failures.push(`Bad pattern "${pattern}" in ${path.relative(rootDir, file)}`);
-      }
-    }
-  }
+    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",
@@ -325,7 +595,7 @@ Run again with --force to back up and overwrite:
     copiedLines.push("  - .zoo-flow/docs/adr/0001-record-architecture-decisions.md");
   }
   if (didAddGitignore) {
-    copiedLines.push("  - appended .zoo-flow/ to .gitignore");
+    copiedLines.push("  - appended .roo/, .roomodes, .zoo-flow/ to .gitignore");
   }
 
   console.log(`
@@ -348,20 +618,99 @@ When workflow choices appear, type the number manually, e.g. 1.
 
 function doctor() {
   const args = new Set(process.argv.slice(3));
-  const rootToCheck = args.has("--template-only") ? templateRoot : process.cwd();
+  const templateOnly = args.has("--template-only");
+  const rootToCheck = templateOnly ? templateRoot : process.cwd();
   const failures = validateTemplate(rootToCheck);
+  const optionalInfo = [];
+
+  if (!templateOnly) {
+    // Installed-project checks
+    const projectRoot = process.cwd();
+
+    // .gitignore check
+    const gi = path.join(projectRoot, ".gitignore");
+    if (pathExists(gi)) {
+      const giContent = fs.readFileSync(gi, "utf8");
+      if (!giContent.includes(ZOO_FLOW_GITIGNORE_MARKER)) {
+        optionalInfo.push("info: .gitignore does not contain Zoo Flow entries (.roomodes, .roo/, .zoo-flow/)");
+      }
+    } else {
+      optionalInfo.push("info: .gitignore missing — run `npx @fernado03/zoo-flow@latest init` to create it");
+    }
+
+    // START_HERE.md check
+    const startHere = path.join(projectRoot, ".zoo-flow", "START_HERE.md");
+    if (!pathExists(startHere)) {
+      optionalInfo.push("info: .zoo-flow/START_HERE.md missing — run `npx @fernado03/zoo-flow@latest init` to install starter docs");
+    }
+
+    // CONTEXT.md check
+    const contextMd = path.join(projectRoot, ".zoo-flow", "CONTEXT.md");
+    if (!pathExists(contextMd)) {
+      optionalInfo.push("info: .zoo-flow/CONTEXT.md missing — run `/scaffold-context` to create project context");
+    }
+
+    // Project-profile check
+    const profile = path.join(projectRoot, ".zoo-flow", "project-profile.json");
+    if (!pathExists(profile)) {
+      optionalInfo.push("info: .zoo-flow/project-profile.json missing — run `/setup-matt-pocock-skills` to configure");
+    }
+
+    // LESSONS check
+    const lessons = path.join(projectRoot, ".zoo-flow", "LESSONS.md");
+    if (!pathExists(lessons)) {
+      optionalInfo.push("info: .zoo-flow/LESSONS.md missing — optional, created on demand");
+    }
+
+    // Verify three modes exist in .roomodes
+    const roomodesPath = path.join(projectRoot, ".roomodes");
+    if (pathExists(roomodesPath)) {
+      try {
+        const roomodes = readJson(roomodesPath);
+        const slugs = (roomodes.customModes || []).map((m) => m.slug);
+        const required = ["custom-orchestrator", "system-architect", "code-tweaker"];
+        for (const slug of required) {
+          if (!slugs.includes(slug)) {
+            failures.push(`.roomodes missing required mode slug: ${slug}`);
+          }
+        }
+      } catch (error) {
+        failures.push(`.roomodes parse error: ${error.message}`);
+      }
+    }
+
+    // .roo/commands and .roo/rules exist
+    if (!pathExists(path.join(projectRoot, ".roo", "commands"))) {
+      failures.push(".roo/commands/ missing — run `npx @fernado03/zoo-flow@latest update`");
+    }
+    if (!pathExists(path.join(projectRoot, ".roo", "rules"))) {
+      failures.push(".roo/rules/ missing — run `npx @fernado03/zoo-flow@latest update`");
+    }
+  }
 
   if (failures.length > 0) {
     console.error("\nZoo Flow doctor found problems:\n");
     for (const failure of failures) {
       console.error(`- ${failure}`);
     }
+    if (!templateOnly) {
+      console.error("\nRun `npx @fernado03/zoo-flow@latest update --dry-run` to preview replacing local Zoo Flow config.");
+    }
     console.error("");
     process.exit(1);
   }
 
-  console.log(`Zoo Flow doctor passed: ${rootToCheck}`);
-}
+  const targetName = templateOnly ? "bundled template" : "current project";
+  console.log(`Zoo Flow doctor passed for ${targetName}: ${rootToCheck}`);
+
+  if (optionalInfo.length > 0) {
+    console.log("\nOptional info:\n");
+    for (const info of optionalInfo) {
+      console.log(`  ${info}`);
+    }
+    console.log("");
+  }
+}
 
 function update() {
   const args = new Set(process.argv.slice(3));
@@ -406,7 +755,7 @@ Would replace with latest template:
   - .roomodes
   - .roo/
 ${wouldMigrate.length > 0 ? `\nWould migrate to .zoo-flow/:\n${wouldMigrate.map((p) => `  - ${p}\n`).join("")}` : ""}
-Would append .zoo-flow/ to .gitignore (idempotent).
+Would append .roo/, .roomodes, .zoo-flow/ to .gitignore (idempotent).
 
 Run this to update:
   npx @fernado03/zoo-flow@latest update
@@ -442,7 +791,7 @@ ${didBackup ? `Backup:\n  ${backupDir}\n\nTo restore the previous config:\n  rm
   2. Open Zoo Code
   3. Confirm the three custom modes still appear
 `);
-}
+}
 
 if (!command || command === "--help" || command === "-h") {
   console.log(HELP);