agent-method 1.5.0

package/lib/cli/route.js

@@ -0,0 +1,62 @@
+/** agent-method route — show how a query routes through the pipeline. */
+
+import {
+  resolveProjectType,
+  getPipeline,
+  loadRegistryData,
+} from "./helpers.js";
+
+export function register(program) {
+  program
+    .command("route <query>")
+    .description("Show how a query routes through the pipeline")
+    .option(
+      "-p, --project-type <type>",
+      "Project type: code, context, data, mix, general (auto-detected if omitted)"
+    )
+    .option("-s, --stage <stage>", "Workflow stage", "scope")
+    .option("--first-session", "Force WF-04 bootstrap")
+    .option("--registry <path>", "Path to feature-registry.yaml")
+    .option("--json", "Output as JSON")
+    .action(async (query, opts) => {
+      const { route, detectProjectType } = await getPipeline();
+      const reg = await loadRegistryData(opts.registry);
+
+      let projectType;
+      if (opts.projectType) {
+        projectType = resolveProjectType(opts.projectType);
+      } else {
+        const detected = detectProjectType(".");
+        projectType = detected.project_type || "general";
+      }
+
+      const result = route(
+        query,
+        projectType,
+        opts.stage,
+        reg,
+        opts.firstSession || false
+      );
+      console.log(`Routing: "${query}" (type: ${projectType})`);
+
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        for (const section of [
+          "S1_classify",
+          "S2_select",
+          "S3_resolve",
+          "S4_compute",
+        ]) {
+          console.log(`\n  ${section}:`);
+          for (const [k, v] of Object.entries(result[section])) {
+            if (Array.isArray(v)) {
+              console.log(`    ${k}: [${v.join(", ")}]`);
+            } else {
+              console.log(`    ${k}: ${v}`);
+            }
+          }
+        }
+      }
+    });
+}

package/lib/cli/scan.js

@@ -0,0 +1,28 @@
+/** agent-method scan — detect project type from directory contents. */
+
+import { getPipeline, outputData } from "./helpers.js";
+
+export function register(program) {
+  program
+    .command("scan [directory]")
+    .description("Detect project type from directory contents")
+    .option("--registry <path>", "Path to feature-registry.yaml")
+    .option("--json", "Output as JSON")
+    .action(async (directory, opts) => {
+      directory = directory || ".";
+      const { detectProjectType } = await getPipeline();
+      const result = detectProjectType(directory);
+
+      const ptype = result.project_type || "general";
+      const friendlyMap = { analytical: "context", mixed: "mix" };
+      if (ptype in friendlyMap) {
+        result.friendly_name = friendlyMap[ptype];
+        result.init_command = `agent-method init ${friendlyMap[ptype]}`;
+      } else {
+        result.init_command = `agent-method init ${ptype}`;
+      }
+
+      console.log(`Scanning: ${directory}`);
+      outputData(result, opts.json);
+    });
+}

package/lib/cli/status.js

@@ -0,0 +1,61 @@
+/** agent-method status — check if methodology version is current. */
+
+import { findEntryPoint, readMethodVersion, basename_of, pkg } from "./helpers.js";
+
+export function register(program) {
+  program
+    .command("status [directory]")
+    .description("Check if your methodology version is current")
+    .option("--json", "Output as JSON")
+    .action(async (directory, opts) => {
+      directory = directory || ".";
+      const ep = findEntryPoint(directory);
+      if (!ep) {
+        console.error(
+          `No entry point found in ${directory} ` +
+            "(looked for CLAUDE.md, .cursorrules, AGENT.md)"
+        );
+        process.exit(1);
+      }
+
+      const epVersion = readMethodVersion(ep);
+      const installed = pkg.version;
+
+      let verStatus, message;
+      if (!epVersion) {
+        verStatus = "no_version";
+        message =
+          `Entry point ${basename_of(ep)} has no method_version setting. ` +
+          `Add 'method_version: ${installed.split(".").slice(0, 2).join(".")}' ` +
+          `to enable version tracking.`;
+      } else if (epVersion === installed.split(".").slice(0, 2).join(".")) {
+        verStatus = "current";
+        message =
+          `Entry point ${basename_of(ep)} is current ` +
+          `(method_version: ${epVersion}, installed: ${installed})`;
+      } else {
+        verStatus = "outdated";
+        message =
+          `Entry point ${basename_of(ep)} is outdated ` +
+          `(method_version: ${epVersion}, installed: ${installed}). ` +
+          `Run \`agent-method upgrade ${directory}\` to update.`;
+      }
+
+      if (opts.json) {
+        console.log(
+          JSON.stringify(
+            {
+              entry_point: ep,
+              entry_point_version: epVersion,
+              installed_version: installed,
+              status: verStatus,
+            },
+            null,
+            2
+          )
+        );
+      } else {
+        console.log(message);
+      }
+    });
+}

package/lib/cli/upgrade.js

@@ -0,0 +1,146 @@
+/** agent-method upgrade — brownfield-safe methodology update. */
+
+import {
+  readFileSync, existsSync, copyFileSync, mkdirSync, writeFileSync,
+} from "node:fs";
+import { resolve, join, dirname } from "node:path";
+import {
+  findEntryPoint, readMethodVersion, basename_of, pkg, packageRoot,
+} from "./helpers.js";
+
+export function register(program) {
+  program
+    .command("upgrade [directory]")
+    .description("Update your project to the latest methodology version")
+    .option("--dry-run", "Show what would change without modifying files")
+    .action(async (directory, opts) => {
+      directory = directory || ".";
+      const d = resolve(directory);
+      const ep = findEntryPoint(directory);
+      const actions = [];
+
+      const templateDirs = {
+        starter: join(packageRoot, "templates", "starter"),
+        full: join(packageRoot, "templates", "full"),
+      };
+
+      // Determine which template tier this project uses
+      let tier = "starter";
+      if (existsSync(join(d, ".context", "REGISTRY.md"))) {
+        tier = "full";
+      } else if (
+        existsSync(join(d, "REQUIREMENTS.md")) &&
+        existsSync(join(d, "SUMMARY.md"))
+      ) {
+        tier = "full";
+      }
+      const srcDir = templateDirs[tier] || templateDirs.starter;
+
+      if (!existsSync(srcDir)) {
+        console.error(
+          `Template directory not found: ${srcDir}. ` +
+            "Run from the agent-method repo or install from source."
+        );
+        process.exit(1);
+      }
+
+      // 1. Update method_version in entry point
+      if (ep) {
+        let content = readFileSync(ep, "utf-8");
+        const currentVer = readMethodVersion(ep);
+        const newVer = pkg.version.split(".").slice(0, 2).join(".");
+        if (currentVer && currentVer !== newVer) {
+          actions.push(
+            `Update ${basename_of(ep)}: method_version ${currentVer} -> ${newVer}`
+          );
+          if (!opts.dryRun) {
+            content = content.replace(/(method_version:\s*)\S+/, `$1${newVer}`);
+            writeFileSync(ep, content, "utf-8");
+          }
+        } else if (!currentVer) {
+          actions.push(`Add method_version: ${newVer} to ${basename_of(ep)}`);
+          if (!opts.dryRun) {
+            if (content.includes("## Conventions")) {
+              const insert =
+                `## Method version\n\n` +
+                `method_version: ${newVer}\n` +
+                `<!-- Tracks which methodology version generated this entry point -->\n` +
+                `<!-- Use \`agent-method status\` to compare against latest -->\n\n`;
+              content = content.replace("## Conventions", insert + "## Conventions");
+              writeFileSync(ep, content, "utf-8");
+            }
+          }
+        }
+      }
+
+      // 2. Add missing methodology files (brownfield-safe: skip existing)
+      const methodologyFiles = ["SESSION-LOG.md", "PROJECT-PROFILE.md"];
+      if (tier === "full") {
+        methodologyFiles.push(join(".context", "METHODOLOGY.md"));
+      }
+
+      for (const fname of methodologyFiles) {
+        const src = join(srcDir, fname);
+        const dst = join(d, fname);
+        if (existsSync(src) && !existsSync(dst)) {
+          actions.push(`Create ${fname} (new)`);
+          if (!opts.dryRun) {
+            mkdirSync(dirname(dst), { recursive: true });
+            copyFileSync(src, dst);
+          }
+        }
+      }
+
+      // 3. Check for session close cascade (add if missing)
+      if (ep) {
+        let content = readFileSync(ep, "utf-8");
+        if (!content.toLowerCase().includes("session close")) {
+          actions.push(`Add session close cascade rule to ${basename_of(ep)}`);
+          if (!opts.dryRun) {
+            if (content.includes("<!-- INSTRUCTION: Add project-specific cascade")) {
+              content = content.replace(
+                "<!-- INSTRUCTION: Add project-specific cascade",
+                "| Session close | SESSION-LOG.md (append micro-entry" +
+                  " \u2014 workflow, features, cascades, friction, findings) " +
+                  "|\n\n<!-- INSTRUCTION: Add project-specific cascade"
+              );
+              writeFileSync(ep, content, "utf-8");
+            }
+          }
+        }
+
+        // 4. Check for session observation convention
+        content = readFileSync(ep, "utf-8");
+        if (!content.toLowerCase().includes("session-log")) {
+          actions.push(
+            `Add session observation convention to ${basename_of(ep)}`
+          );
+          if (!opts.dryRun) {
+            if (content.includes("## Do not")) {
+              content = content.replace(
+                "## Do not",
+                "- At session close, append a micro-entry to " +
+                  "SESSION-LOG.md \u2014 never skip, never read " +
+                  "previous entries during normal work\n\n" +
+                  "## Do not"
+              );
+              writeFileSync(ep, content, "utf-8");
+            }
+          }
+        }
+      }
+
+      // Report
+      if (actions.length === 0) {
+        console.log(`Project at ${directory} is up to date (v${pkg.version}).`);
+      } else if (opts.dryRun) {
+        console.log(`Dry run \u2014 ${actions.length} changes needed:`);
+        for (const a of actions) console.log(`  - ${a}`);
+      } else {
+        console.log(
+          `Upgraded ${directory} to methodology v${pkg.version} (${actions.length} changes):`
+        );
+        for (const a of actions) console.log(`  - ${a}`);
+      }
+    });
+}

package/lib/init.js

@@ -0,0 +1,240 @@
+/**
+ * Interactive project setup — Node.js port of setup.sh.
+ *
+ * Creates a new methodology instance from templates with interactive
+ * prompts for project configuration.
+ */
+
+import { existsSync, mkdirSync, copyFileSync, readFileSync, writeFileSync, readdirSync } from "node:fs";
+import { resolve, join, dirname, basename, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const EXTENSION_MAP = {
+  code: "code-project.md",
+  data: "data-exploration.md",
+  analytical: "analytical-system.md",
+};
+
+const FRIENDLY_NAMES = {
+  code: "Code project",
+  data: "Data exploration",
+  analytical: "Analytical/prompt system",
+  mixed: "Multi-type project",
+  general: "General project",
+};
+
+/**
+ * Set up a new project with methodology templates.
+ */
+export async function initProject(projectType, directory, opts = {}) {
+  const { tier = "starter", registryPath } = opts;
+  const targetDir = resolve(directory);
+  const methodRoot = resolve(__dirname, "..");
+
+  const templateDir = join(methodRoot, "templates", tier);
+  if (!existsSync(templateDir)) {
+    console.error(`Template directory not found: ${templateDir}`);
+    process.exit(1);
+  }
+
+  console.log(`\nSetting up ${FRIENDLY_NAMES[projectType] || projectType} project`);
+  console.log(`  Template: ${tier}`);
+  console.log(`  Target:   ${targetDir}\n`);
+
+  // Detect brownfield (existing project with methodology files)
+  const isBrownfield = detectBrownfield(targetDir);
+  if (isBrownfield) {
+    console.log("  Detected existing methodology files (brownfield mode)");
+    console.log("  Will append to existing entry points, not overwrite.\n");
+  }
+
+  // Create target directory
+  mkdirSync(targetDir, { recursive: true });
+
+  // Copy template files
+  const copied = [];
+  const skipped = [];
+  copyTemplateDir(templateDir, targetDir, copied, skipped, isBrownfield);
+
+  // Apply extensions based on project type
+  const extensions = getExtensions(projectType);
+  for (const ext of extensions) {
+    const extFile = join(methodRoot, "templates", "extensions", ext);
+    if (existsSync(extFile)) {
+      mergeExtension(extFile, targetDir, isBrownfield);
+      copied.push(`extension: ${ext}`);
+    }
+  }
+
+  // Replace placeholders in entry points
+  replacePlaceholders(targetDir, projectType, tier);
+
+  // Report
+  console.log(`  Files created: ${copied.length}`);
+  for (const f of copied) console.log(`    + ${f}`);
+  if (skipped.length > 0) {
+    console.log(`  Files skipped (already exist): ${skipped.length}`);
+    for (const f of skipped) console.log(`    ~ ${f}`);
+  }
+
+  console.log(`\nNext steps:`);
+  console.log(`  1. cd ${relative(process.cwd(), targetDir) || "."}`);
+  console.log(`  2. Fill in PROJECT.md with your project vision`);
+  console.log(`  3. Delete the two entry point files you don't use`);
+  console.log(`     (keep CLAUDE.md, .cursorrules, or AGENT.md)`);
+  console.log(`  4. Start a conversation — the agent reads the entry point`);
+  console.log(`\nRun \`agent-method check\` to validate your setup.`);
+}
+
+function detectBrownfield(dir) {
+  if (!existsSync(dir)) return false;
+  const indicators = ["CLAUDE.md", ".cursorrules", "AGENT.md", "STATE.md", ".context"];
+  let count = 0;
+  for (const ind of indicators) {
+    if (existsSync(join(dir, ind))) count++;
+  }
+  return count >= 2;
+}
+
+function copyTemplateDir(src, dst, copied, skipped, isBrownfield) {
+  if (!existsSync(src)) return;
+  mkdirSync(dst, { recursive: true });
+
+  for (const entry of readdirSync(src, { withFileTypes: true })) {
+    const srcPath = join(src, entry.name);
+    const dstPath = join(dst, entry.name);
+
+    if (entry.isDirectory()) {
+      copyTemplateDir(srcPath, dstPath, copied, skipped, isBrownfield);
+    } else {
+      // Entry points: special handling in brownfield
+      const isEntryPoint = ["CLAUDE.md", ".cursorrules", "AGENT.md"].includes(entry.name);
+
+      if (existsSync(dstPath)) {
+        if (isEntryPoint && isBrownfield) {
+          // Append methodology sections to existing entry point
+          appendToEntryPoint(srcPath, dstPath);
+          copied.push(`${relative(dst, dstPath)} (merged)`);
+        } else {
+          skipped.push(relative(dst, dstPath));
+        }
+      } else {
+        copyFileSync(srcPath, dstPath);
+        copied.push(relative(dst, dstPath));
+      }
+    }
+  }
+}
+
+function appendToEntryPoint(srcPath, dstPath) {
+  const srcContent = readFileSync(srcPath, "utf-8");
+  let dstContent = readFileSync(dstPath, "utf-8");
+
+  // Extract sections from template that don't exist in target
+  const sections = ["## Scoping rules", "## Dependency cascade", "## Conventions", "## Do not"];
+  for (const section of sections) {
+    if (!dstContent.includes(section) && srcContent.includes(section)) {
+      const idx = srcContent.indexOf(section);
+      // Find the next section or end
+      let endIdx = srcContent.length;
+      for (const nextSection of sections) {
+        const nextIdx = srcContent.indexOf(nextSection, idx + section.length);
+        if (nextIdx > idx && nextIdx < endIdx) {
+          endIdx = nextIdx;
+        }
+      }
+      const sectionContent = srcContent.slice(idx, endIdx).trim();
+      dstContent += "\n\n" + sectionContent;
+    }
+  }
+
+  writeFileSync(dstPath, dstContent, "utf-8");
+}
+
+function getExtensions(projectType) {
+  if (projectType === "mixed") {
+    return Object.values(EXTENSION_MAP);
+  }
+  const ext = EXTENSION_MAP[projectType];
+  return ext ? [ext] : [];
+}
+
+function mergeExtension(extFile, targetDir, isBrownfield) {
+  const content = readFileSync(extFile, "utf-8");
+
+  // Extract scoping rows and cascade rows from extension file
+  const scopingRows = [];
+  const cascadeRows = [];
+  let inScoping = false;
+  let inCascade = false;
+
+  for (const line of content.split("\n")) {
+    if (line.includes("## Scoping")) inScoping = true;
+    if (line.includes("## Cascade") || line.includes("## Dependency cascade"))
+      inCascade = true;
+    if (line.startsWith("## ") && !line.includes("Scoping") && !line.includes("Cascade")) {
+      inScoping = false;
+      inCascade = false;
+    }
+
+    if (inScoping && line.startsWith("|") && !line.startsWith("| Query") && !line.startsWith("|--")) {
+      scopingRows.push(line);
+    }
+    if (inCascade && line.startsWith("|") && !line.startsWith("| When") && !line.startsWith("|--")) {
+      cascadeRows.push(line);
+    }
+  }
+
+  // Inject rows into entry points
+  for (const epName of ["CLAUDE.md", ".cursorrules", "AGENT.md"]) {
+    const epPath = join(targetDir, epName);
+    if (!existsSync(epPath)) continue;
+
+    let epContent = readFileSync(epPath, "utf-8");
+
+    // Inject scoping rows before the instruction comment or at end of table
+    if (scopingRows.length > 0) {
+      const placeholder = "<!-- INSTRUCTION: Add project-specific scoping";
+      if (epContent.includes(placeholder)) {
+        epContent = epContent.replace(
+          placeholder,
+          scopingRows.join("\n") + "\n" + placeholder
+        );
+      }
+    }
+
+    // Inject cascade rows
+    if (cascadeRows.length > 0) {
+      const placeholder = "<!-- INSTRUCTION: Add project-specific cascade";
+      if (epContent.includes(placeholder)) {
+        epContent = epContent.replace(
+          placeholder,
+          cascadeRows.join("\n") + "\n" + placeholder
+        );
+      }
+    }
+
+    writeFileSync(epPath, epContent, "utf-8");
+  }
+}
+
+function replacePlaceholders(targetDir, projectType, tier) {
+  for (const epName of ["CLAUDE.md", ".cursorrules", "AGENT.md"]) {
+    const epPath = join(targetDir, epName);
+    if (!existsSync(epPath)) continue;
+
+    let content = readFileSync(epPath, "utf-8");
+
+    // Replace project type placeholder
+    content = content.replace(/\{your-project-type\}/g, projectType);
+    content = content.replace(/\{your-domain-type\}/g, projectType);
+
+    // Set template tier
+    content = content.replace(/template_tier:\s*\S+/, `template_tier: ${tier}`);
+
+    writeFileSync(epPath, content, "utf-8");
+  }
+}