agent-method 1.5.5 → 1.5.6

package/lib/cli/refine.js

@@ -1,7 +1,7 @@
 /** wwa refine — extract refinement report from session history. */
 
-import { readFileSync, existsSync, writeFileSync } from "node:fs";
-import { findSessionLog } from "./helpers.js";
+import { readFileSync, existsSync } from "node:fs";
+import { findSessionLog, safeWriteFile } from "./helpers.js";
 
 export function register(program) {
   program
@@ -15,7 +15,7 @@ export function register(program) {
         if (!sessionLog) {
           console.error(
             "No SESSION-LOG.md found in current directory.\n" +
-              "Specify a path: npx agent-method refine path/to/SESSION-LOG.md"
+              "Specify a path: wwa refine path/to/SESSION-LOG.md"
           );
           process.exit(1);
         }
@@ -37,7 +37,7 @@ export function register(program) {
       }
 
       if (opts.output) {
-        writeFileSync(opts.output, result, "utf-8");
+        safeWriteFile(opts.output, result, "utf-8");
         console.log(
           `Refinement report written to ${opts.output} (${parsed.entries.length} sessions)`
         );

package/lib/cli/review.js

@@ -0,0 +1,68 @@
+/** wwa review — display project review dashboard. */
+
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+
+export function register(program) {
+  program
+    .command("review [directory]")
+    .description("Display project review dashboard from Reviews/INDEX.md")
+    .option("--json", "Output as JSON")
+    .action(async (directory, opts) => {
+      directory = directory || ".";
+      const d = resolve(directory);
+
+      const reviewIndex = join(d, "Reviews", "INDEX.md");
+      const hasReviews = existsSync(reviewIndex);
+
+      // Fallback: synthesize from intelligence layer files
+      const sources = {
+        roadmap: join(d, "ROADMAP.md"),
+        plan: join(d, "PLAN.md"),
+        state: join(d, "STATE.md"),
+        requirements: join(d, "REQUIREMENTS.md"),
+        backlog: join(d, "todos", "backlog.md"),
+      };
+
+      const available = {};
+      for (const [key, path] of Object.entries(sources)) {
+        available[key] = existsSync(path);
+      }
+
+      if (opts.json) {
+        const data = { hasReviewsDir: hasReviews, available };
+        if (hasReviews) {
+          data.indexContent = readFileSync(reviewIndex, "utf-8");
+        }
+        console.log(JSON.stringify(data, null, 2));
+        return;
+      }
+
+      if (hasReviews) {
+        // Display Reviews/INDEX.md content
+        const content = readFileSync(reviewIndex, "utf-8");
+        console.log(content);
+        return;
+      }
+
+      // Synthesize a quick review from available files
+      console.log("\n  Project Review Dashboard\n");
+      console.log("  No Reviews/ directory found. Showing available sources:\n");
+
+      for (const [key, path] of Object.entries(sources)) {
+        if (available[key]) {
+          const content = readFileSync(path, "utf-8");
+          const lines = content.split("\n").length;
+          const title = content.match(/^#\s+(.+)$/m)?.[1] || key;
+          console.log(`    [+] ${key.padEnd(14)} ${title} (${lines} lines)`);
+        } else {
+          console.log(`    [ ] ${key.padEnd(14)} not found`);
+        }
+      }
+
+      console.log(
+        "\n  To get full reviews, use the full template tier:" +
+          "\n    wwa init <type> --tier full\n"
+      );
+    });
+}

package/lib/cli/scan.js

@@ -17,9 +17,9 @@ export function register(program) {
       const friendlyMap = { analytical: "context", mixed: "mix" };
       if (ptype in friendlyMap) {
         result.friendly_name = friendlyMap[ptype];
-        result.init_command = `npx agent-method init ${friendlyMap[ptype]}`;
+        result.init_command = `wwa init ${friendlyMap[ptype]}`;
       } else {
-        result.init_command = `npx agent-method init ${ptype}`;
+        result.init_command = `wwa init ${ptype}`;
       }
 
       console.log(`Scanning: ${directory}`);

package/lib/cli/status.js

@@ -38,7 +38,7 @@ export function register(program) {
         message =
           `Entry point ${basename_of(ep)} is outdated ` +
           `(method_version: ${epVersion}, installed: ${installed}). ` +
-          `Run \`npx agent-method upgrade ${directory}\` to update.`;
+          `Run \`wwa upgrade ${directory}\` to update.`;
       }
 
       if (opts.json) {

package/lib/cli/upgrade.js

@@ -1,11 +1,12 @@
 /** wwa upgrade — brownfield-safe methodology update. */
 
 import {
-  readFileSync, existsSync, copyFileSync, mkdirSync, writeFileSync,
+  readFileSync, existsSync, mkdirSync,
 } from "node:fs";
 import { resolve, join, dirname } from "node:path";
 import {
   findEntryPoint, readMethodVersion, basename_of, pkg, packageRoot,
+  safeWriteFile, safeCopyFile,
 } from "./helpers.js";
 
 export function register(program) {
@@ -55,7 +56,7 @@ export function register(program) {
           );
           if (!opts.dryRun) {
             content = content.replace(/(method_version:\s*)\S+/, `$1${newVer}`);
-            writeFileSync(ep, content, "utf-8");
+            safeWriteFile(ep, content, "utf-8");
           }
         } else if (!currentVer) {
           actions.push(`Add method_version: ${newVer} to ${basename_of(ep)}`);
@@ -65,9 +66,9 @@ export function register(program) {
                 `## Method version\n\n` +
                 `method_version: ${newVer}\n` +
                 `<!-- Tracks which methodology version generated this entry point -->\n` +
-                `<!-- Use \`npx agent-method status\` to compare against latest -->\n\n`;
+                `<!-- Use \`wwa status\` to compare against latest -->\n\n`;
               content = content.replace("## Conventions", insert + "## Conventions");
-              writeFileSync(ep, content, "utf-8");
+              safeWriteFile(ep, content, "utf-8");
             }
           }
         }
@@ -86,7 +87,7 @@ export function register(program) {
           actions.push(`Create ${fname} (new)`);
           if (!opts.dryRun) {
             mkdirSync(dirname(dst), { recursive: true });
-            copyFileSync(src, dst);
+            safeCopyFile(src, dst);
           }
         }
       }
@@ -104,7 +105,7 @@ export function register(program) {
                   " \u2014 effort, ambiguity, context level, tokens, time, user response, refinement delta, workflow, features, cascades, friction, findings) " +
                   "|\n\n<!-- INSTRUCTION: Add project-specific cascade"
               );
-              writeFileSync(ep, content, "utf-8");
+              safeWriteFile(ep, content, "utf-8");
             }
           }
         }
@@ -127,7 +128,7 @@ export function register(program) {
                   "previous entries during normal work\n\n" +
                   "## Do not"
               );
-              writeFileSync(ep, content, "utf-8");
+              safeWriteFile(ep, content, "utf-8");
             }
           }
         }

package/lib/init.js

@@ -5,9 +5,23 @@
  * prompts for project configuration.
  */
 
-import { existsSync, mkdirSync, copyFileSync, readFileSync, writeFileSync, readdirSync, unlinkSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, copyFileSync, writeFileSync } from "node:fs";
 import { resolve, join, dirname, basename, relative } from "node:path";
 import { fileURLToPath } from "node:url";
+import { safeCopyFile, safeWriteFile } from "./cli/helpers.js";
+
+/** Entry point filenames that bypass the extension-based safety check. */
+const ENTRY_POINT_NAMES = new Set(["CLAUDE.md", ".cursorrules", "AGENT.md"]);
+
+/** Write file — allows entry points (e.g. .cursorrules) plus safe extensions. */
+function writeInitFile(filePath, content, encoding = "utf-8") {
+  const name = basename(filePath);
+  if (ENTRY_POINT_NAMES.has(name)) {
+    writeFileSync(filePath, content, encoding);
+  } else {
+    safeWriteFile(filePath, content, encoding);
+  }
+}
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -36,7 +50,7 @@ const RUNTIME_ENTRY_POINTS = {
  * Set up a new project with methodology templates.
  */
 export async function initProject(projectType, directory, opts = {}) {
-  const { tier = "starter", runtime = "all", profile = "standard", registryPath } = opts;
+  const { tier = "starter", runtime = "all", profile = "standard", onboarding = "auto", registryPath } = opts;
   const targetDir = resolve(directory);
   const methodRoot = resolve(__dirname, "..");
 
@@ -47,16 +61,25 @@ export async function initProject(projectType, directory, opts = {}) {
   }
 
   console.log(`\nSetting up ${FRIENDLY_NAMES[projectType] || projectType} project`);
-  console.log(`  Template: ${tier}`);
-  console.log(`  Profile:  ${profile}`);
-  console.log(`  Runtime:  ${runtime}`);
-  console.log(`  Target:   ${targetDir}\n`);
+  console.log(`  Template:   ${tier}`);
+  console.log(`  Profile:    ${profile}`);
+  console.log(`  Runtime:    ${runtime}`);
+  console.log(`  Onboarding: ${onboarding}`);
+  console.log(`  Target:     ${targetDir}\n`);
+
+  // Determine brownfield mode from user selection or auto-detection
+  let isBrownfield;
+  if (onboarding === "brownfield") {
+    isBrownfield = true;
+  } else if (onboarding === "greenfield") {
+    isBrownfield = false;
+  } else {
+    // auto — detect from existing files
+    isBrownfield = detectBrownfield(targetDir);
+  }
 
-  // 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");
+    console.log("  Brownfield mode — will append to existing entry points, not overwrite.\n");
   }
 
   // Create target directory
@@ -65,7 +88,7 @@ export async function initProject(projectType, directory, opts = {}) {
   // Copy template files
   const copied = [];
   const skipped = [];
-  copyTemplateDir(templateDir, targetDir, copied, skipped, isBrownfield);
+  copyTemplateDir(templateDir, targetDir, copied, skipped, isBrownfield, runtime);
 
   // Apply extensions based on project type
   const extensions = getExtensions(projectType);
@@ -77,12 +100,21 @@ export async function initProject(projectType, directory, opts = {}) {
     }
   }
 
+  // Copy feature-registry.yaml to user project (populated, from package)
+  copyFeatureRegistry(methodRoot, targetDir, copied);
+
+  // Create project-specific doc-tokens.yaml with initial values
+  createProjectTokens(targetDir, projectType, tier, profile, onboarding, copied);
+
   // Replace placeholders in entry points
   replacePlaceholders(targetDir, projectType, tier);
 
   // Set integration profile in entry points
   setProfile(targetDir, profile);
 
+  // Set onboarding scenario in PROJECT-PROFILE.md
+  setOnboardingScenario(targetDir, onboarding, isBrownfield, projectType);
+
   // Remove unused entry points based on runtime choice
   const removed = removeUnusedEntryPoints(targetDir, runtime, isBrownfield);
 
@@ -104,14 +136,21 @@ export async function initProject(projectType, directory, opts = {}) {
     : "CLAUDE.md / .cursorrules / AGENT.md";
 
   console.log(`\nNext steps:`);
-  console.log(`  1. cd ${relative(process.cwd(), targetDir) || "."}`);
-  console.log(`  2. Fill in PROJECT.md with your project vision`);
+  let step = 1;
+  console.log(`  ${step++}. cd ${relative(process.cwd(), targetDir) || "."}`);
   if (runtime === "all") {
-    console.log(`  3. Delete the two entry point files you don't use`);
+    console.log(`  ${step++}. Delete the two entry point files you don't use`);
     console.log(`     (keep CLAUDE.md, .cursorrules, or AGENT.md)`);
   }
-  console.log(`  ${runtime === "all" ? "4" : "3"}. Start a conversation — the agent reads ${keptEntry} automatically`);
-  console.log(`\nVerify: npx agent-method check`);
+  console.log(`  ${step++}. Start a conversation with your agent — it reads ${keptEntry} automatically`);
+  if (isBrownfield) {
+    console.log(`     The agent will scan your codebase and walk you through 5 onboarding stages`);
+    console.log(`     (scan → clarify → map → organize → starting state)`);
+  } else {
+    console.log(`     The agent will walk you through 4 onboarding stages`);
+    console.log(`     (vision → architecture → goals → starting state)`);
+  }
+  console.log(`\nVerify: wwa check`);
 }
 
 function detectBrownfield(dir) {
@@ -124,7 +163,7 @@ function detectBrownfield(dir) {
   return count >= 2;
 }
 
-function copyTemplateDir(src, dst, copied, skipped, isBrownfield) {
+function copyTemplateDir(src, dst, copied, skipped, isBrownfield, runtime) {
   if (!existsSync(src)) return;
   mkdirSync(dst, { recursive: true });
 
@@ -133,11 +172,24 @@ function copyTemplateDir(src, dst, copied, skipped, isBrownfield) {
     const dstPath = join(dst, entry.name);
 
     if (entry.isDirectory()) {
-      copyTemplateDir(srcPath, dstPath, copied, skipped, isBrownfield);
+      copyTemplateDir(srcPath, dstPath, copied, skipped, isBrownfield, runtime);
     } else {
       // Entry points: special handling in brownfield
       const isEntryPoint = ["CLAUDE.md", ".cursorrules", "AGENT.md"].includes(entry.name);
 
+      // Skip entry points that won't be kept (avoids safety invariant issue with .cursorrules)
+      if (isEntryPoint && runtime !== "all" && !isBrownfield) {
+        const keep = RUNTIME_ENTRY_POINTS[runtime];
+        if (keep && entry.name !== keep) continue;
+      }
+
+      // Defer heavy infrastructure files in brownfield to reduce first-session load
+      const isDeferredInBrownfield = isBrownfield && entry.name === "REGISTRY.md";
+      if (isDeferredInBrownfield) {
+        skipped.push(`${relative(dst, dstPath)} (deferred — created on first file split)`);
+        continue;
+      }
+
       if (existsSync(dstPath)) {
         if (isEntryPoint && isBrownfield) {
           // Append methodology sections to existing entry point
@@ -146,9 +198,13 @@ function copyTemplateDir(src, dst, copied, skipped, isBrownfield) {
         } else {
           skipped.push(relative(dst, dstPath));
         }
-      } else {
+      } else if (isEntryPoint) {
+        // Entry points bypass safeCopyFile (e.g. .cursorrules has no .md extension)
         copyFileSync(srcPath, dstPath);
         copied.push(relative(dst, dstPath));
+      } else {
+        safeCopyFile(srcPath, dstPath);
+        copied.push(relative(dst, dstPath));
       }
     }
   }
@@ -176,7 +232,7 @@ function appendToEntryPoint(srcPath, dstPath) {
     }
   }
 
-  writeFileSync(dstPath, dstContent, "utf-8");
+  writeInitFile(dstPath, dstContent, "utf-8");
 }
 
 function getExtensions(projectType) {
@@ -242,7 +298,7 @@ function mergeExtension(extFile, targetDir, isBrownfield) {
       }
     }
 
-    writeFileSync(epPath, epContent, "utf-8");
+    writeInitFile(epPath, epContent, "utf-8");
   }
 }
 
@@ -260,7 +316,7 @@ function replacePlaceholders(targetDir, projectType, tier) {
     // Set template tier
     content = content.replace(/template_tier:\s*\S+/, `template_tier: ${tier}`);
 
-    writeFileSync(epPath, content, "utf-8");
+    writeInitFile(epPath, content, "utf-8");
   }
 }
 
@@ -271,10 +327,136 @@ function setProfile(targetDir, profile) {
 
     let content = readFileSync(epPath, "utf-8");
     content = content.replace(/tier:\s*(lite|standard|full)/, `tier: ${profile}`);
-    writeFileSync(epPath, content, "utf-8");
+    writeInitFile(epPath, content, "utf-8");
   }
 }
 
+function setOnboardingScenario(targetDir, onboarding, isBrownfield, projectType) {
+  const profilePath = join(targetDir, "PROJECT-PROFILE.md");
+  if (!existsSync(profilePath)) return;
+
+  let content = readFileSync(profilePath, "utf-8");
+
+  // Set lifecycle stage based on scenario
+  const stage = isBrownfield ? "discovery" : "design";
+  content = content.replace(/\*\*Stage\*\*:\s*\{stage\}/, `**Stage**: ${stage}`);
+  content = content.replace(/\*\*Maturity\*\*:\s*\{maturity\}/, `**Maturity**: new`);
+
+  const today = new Date().toISOString().slice(0, 10);
+  content = content.replace(
+    /\*\*Last transition\*\*:\s*\{date\}.*$/m,
+    `**Last transition**: ${today} (setup -> ${stage})`
+  );
+
+  // Set project type
+  content = content.replace(/\[{project-type}\]/, `[${projectType}]`);
+
+  // Set onboarding hint so the agent knows which first-session flow
+  const scenario = onboarding === "auto"
+    ? (isBrownfield ? "brownfield (auto-detected)" : "greenfield (auto-detected)")
+    : onboarding;
+
+  // Add onboarding scenario after lifecycle section
+  if (!content.includes("**Onboarding**")) {
+    content = content.replace(
+      /(\*\*Last transition\*\*:.*$)/m,
+      `$1\n- **Onboarding**: ${scenario}`
+    );
+  }
+
+  // Set extension stack
+  const extensions = getExtensions(projectType);
+  const extNames = extensions.map(e => e.replace(".md", ""));
+  content = content.replace(/\[{extensions-applied}\]/, `[${extNames.join(", ") || "none"}]`);
+
+  for (const ext of ["code-project", "data-exploration", "analytical-system"]) {
+    const isActive = extNames.includes(ext) ? "yes" : "no";
+    const source = extNames.includes(ext) ? "wwa init" : "—";
+    content = content.replace(
+      new RegExp(`\\| ${ext} \\| \\{yes/no\\} \\| \\{setup\\.sh / manual\\} \\|`),
+      `| ${ext} | ${isActive} | ${source} |`
+    );
+  }
+
+  safeWriteFile(profilePath, content, "utf-8");
+}
+
+function createProjectTokens(targetDir, projectType, tier, profile, onboarding, copied) {
+  const ctxDir = join(targetDir, ".context");
+  mkdirSync(ctxDir, { recursive: true });
+  const dst = join(ctxDir, "doc-tokens.yaml");
+  if (existsSync(dst)) return; // don't overwrite
+
+  const today = new Date().toISOString().slice(0, 10);
+
+  // Count files that were actually created
+  const mdFiles = [];
+  const countMdFiles = (dir) => {
+    if (!existsSync(dir)) return;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const p = join(dir, entry.name);
+      if (entry.isDirectory()) countMdFiles(p);
+      else if (entry.name.endsWith(".md") || entry.name.endsWith(".yaml") || entry.name.endsWith(".yml")) {
+        mdFiles.push(relative(targetDir, p).replace(/\\/g, "/"));
+      }
+    }
+  };
+  countMdFiles(targetDir);
+
+  const content = [
+    "# Project Token Registry",
+    "# Computed by wwa init. Updated by wwa close.",
+    "# Used by wwa casestudy for methodology reference data.",
+    "#",
+    "# Agent: read this before writing docs. Check values are current.",
+    "",
+    "tokens:",
+    "",
+    "  # --- Project identity ---",
+    `  project_type: ${projectType}`,
+    `  template_tier: ${tier}`,
+    `  integration_profile: ${profile}`,
+    `  onboarding: ${onboarding}`,
+    `  created: "${today}"`,
+    `  last_close: "${today}"`,
+    "",
+    "  # --- File counts (updated at close) ---",
+    `  methodology_file_count: ${mdFiles.length}`,
+    "  docs_file_count: 0",
+    "  context_file_count: 0",
+    "",
+    "  # --- Session metrics (updated at close) ---",
+    "  session_count: 0",
+    "  decision_count: 0",
+    "  total_features_referenced: 0",
+    "",
+    "  # --- Scale indicators (updated at close) ---",
+    "  files_near_threshold: 0           # files with 250+ lines",
+    "  files_over_threshold: 0           # files with 300+ lines (need splitting)",
+    "",
+    "  # --- Docs coverage (updated at close) ---",
+    "  docs_inventory_count: 0",
+    "  docs_on_disk: 0",
+    "  docs_missing: 0",
+    "  component_mappings: 0",
+    "",
+  ].join("\n");
+
+  safeWriteFile(dst, content, "utf-8");
+  copied.push(".context/doc-tokens.yaml");
+}
+
+function copyFeatureRegistry(methodRoot, targetDir, copied) {
+  const src = join(methodRoot, "docs", "internal", "feature-registry.yaml");
+  if (!existsSync(src)) return;
+  const ctxDir = join(targetDir, ".context");
+  mkdirSync(ctxDir, { recursive: true });
+  const dst = join(ctxDir, "feature-registry.yaml");
+  if (existsSync(dst)) return; // don't overwrite existing
+  safeCopyFile(src, dst);
+  copied.push(".context/feature-registry.yaml");
+}
+
 function removeUnusedEntryPoints(targetDir, runtime, isBrownfield) {
   if (runtime === "all" || isBrownfield) return [];
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-method",
-  "version": "1.5.5",
+  "version": "1.5.6",
   "description": "CLI tools for the wwa methodology — registry-driven routing, validation, and project setup for AI-agent-assisted development",
   "keywords": [
     "ai-agents",
@@ -8,7 +8,13 @@
     "context-engineering",
     "methodology",
     "developer-tools",
-    "cli"
+    "cli",
+    "claude-code",
+    "cursor",
+    "gemini",
+    "codex",
+    "mcp",
+    "agent-framework"
   ],
   "type": "module",
   "license": "MIT",
@@ -21,7 +27,8 @@
     "bin/",
     "lib/",
     "templates/",
-    "docs/internal/feature-registry.yaml"
+    "docs/internal/feature-registry.yaml",
+    "docs/internal/doc-tokens.yaml"
   ],
   "main": "lib/registry.js",
   "engines": {