methodology-m 0.3.1

package/src/commands/init.mjs

@@ -0,0 +1,51 @@
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { copyDistM } from '../lib/copy.mjs';
+import { readInstalledVersion, writeInstalledVersion, readAvailableVersion } from '../lib/version-file.mjs';
+import { detectAgents } from '../lib/detect-agent.mjs';
+import { generateClaudeWrappers } from '../lib/wrappers/claude.mjs';
+
+export async function init(args) {
+  const target = resolve(args[0] || '.');
+  const version = readAvailableVersion();
+  const installed = readInstalledVersion(target);
+
+  if (installed) {
+    console.log(`M v${installed} is already installed. Use "m update" to upgrade.`);
+    return;
+  }
+
+  console.log(`Installing Methodology M v${version} into ${target}`);
+  console.log('');
+
+  // 1. Copy .m/ directory
+  const destDir = copyDistM(target);
+  console.log(`  ✓ .m/ directory created`);
+
+  // 2. Write version file
+  writeInstalledVersion(target, version);
+  console.log(`  ✓ .m-version written (v${version})`);
+
+  // 3. Detect agent runtimes and generate wrappers
+  const agents = detectAgents(target);
+
+  if (agents.includes('claude')) {
+    const { created, skipped } = generateClaudeWrappers(target);
+    for (const f of created) console.log(`  ✓ ${f} created`);
+    for (const f of skipped) console.log(`  · ${f} already exists (skipped)`);
+  }
+
+  if (!agents.length) {
+    console.log('  · No agent runtime detected (.claude/ or .kiro/)');
+    console.log('    Create .claude/ or .kiro/ first, then re-run "m init" to generate wrappers.');
+  }
+
+  // 4. Summary
+  console.log('');
+  console.log(`Methodology M v${version} installed.`);
+  console.log('');
+  console.log('Next steps:');
+  console.log('  1. Tell your AI agent: "Read .m/m.md and bootstrap this project"');
+  console.log('  2. The agent will discover capabilities and guide you through setup');
+  console.log('  3. Run "m version" to check your installed version');
+}

package/src/commands/update.mjs

@@ -0,0 +1,41 @@
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { copyDistM } from '../lib/copy.mjs';
+import { readInstalledVersion, writeInstalledVersion, readAvailableVersion } from '../lib/version-file.mjs';
+import { diffTrees, formatDiff } from '../lib/diff-trees.mjs';
+
+export async function update(args) {
+  const target = resolve(args[0] || '.');
+  const installed = readInstalledVersion(target);
+  const available = readAvailableVersion();
+
+  if (!installed) {
+    console.error('M is not installed in this project. Run "m init" first.');
+    process.exit(1);
+  }
+
+  if (installed === available) {
+    console.log(`Already at v${installed}. Nothing to update.`);
+    return;
+  }
+
+  const installedDir = join(target, '.m');
+  const availableDir = join(import.meta.dirname, '..', '..', 'dist-m');
+
+  // Show what will change
+  console.log(`Updating Methodology M: v${installed} → v${available}`);
+  console.log('');
+
+  const result = diffTrees(installedDir, availableDir);
+  console.log(formatDiff(result));
+  console.log('');
+
+  // Apply the update
+  copyDistM(target);
+  writeInstalledVersion(target, available);
+
+  console.log(`Updated to v${available}.`);
+  console.log('');
+  console.log('Agent wrappers (.claude/, .kiro/) were NOT touched.');
+  console.log('Review the changes above and update your agent wrappers if needed.');
+}

package/src/commands/version.mjs

@@ -0,0 +1,43 @@
+import { resolve } from 'node:path';
+import { execSync } from 'node:child_process';
+import { readInstalledVersion, readAvailableVersion } from '../lib/version-file.mjs';
+
+export async function version(args) {
+  const target = resolve(args[0] || '.');
+  const bundled = readAvailableVersion();
+  const installed = readInstalledVersion(target);
+  const latest = checkRegistry();
+
+  console.log(`Bundled:   v${bundled} (shipped with this CLI)`);
+
+  if (installed) {
+    console.log(`Installed: v${installed}`);
+  } else {
+    console.log('Installed: not installed (run "m init")');
+  }
+
+  if (latest) {
+    console.log(`Latest:    v${latest} (npm registry)`);
+    if (installed && installed !== latest) {
+      console.log('');
+      console.log(`Update available: v${installed} → v${latest}`);
+      console.log('Run "npm i -g methodology-m@latest" then "m update"');
+    }
+  } else {
+    console.log('Latest:    (not published yet / offline)');
+  }
+}
+
+/** Check npm registry for the latest published version. Fails silently. */
+function checkRegistry() {
+  try {
+    return execSync('npm view methodology-m version 2>/dev/null', {
+      stdio: 'pipe',
+      timeout: 5000,
+    })
+      .toString()
+      .trim();
+  } catch {
+    return null;
+  }
+}

package/src/lib/copy.mjs

@@ -0,0 +1,20 @@
+import { cpSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Copy the dist-m/ snapshot into the target project's .m/ directory.
+ * Overwrites existing files. Creates directories as needed.
+ */
+export function copyDistM(target) {
+  const distDir = join(import.meta.dirname, '..', '..', 'dist-m');
+  const destDir = join(target, '.m');
+
+  if (!existsSync(distDir)) {
+    throw new Error(
+      'dist-m/ not found. Run "npm run snapshot" first, or install from npm.'
+    );
+  }
+
+  cpSync(distDir, destDir, { recursive: true, force: true });
+  return destDir;
+}

package/src/lib/detect-agent.mjs

@@ -0,0 +1,25 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Detect which AI agent runtimes are present in the target directory.
+ * Returns an array of detected runtime names.
+ */
+export function detectAgents(target) {
+  const agents = [];
+
+  // Claude Code — .claude/ directory or CLAUDE.md
+  if (
+    existsSync(join(target, '.claude')) ||
+    existsSync(join(target, 'CLAUDE.md'))
+  ) {
+    agents.push('claude');
+  }
+
+  // Kiro — .kiro/ directory
+  if (existsSync(join(target, '.kiro'))) {
+    agents.push('kiro');
+  }
+
+  return agents;
+}

package/src/lib/diff-trees.mjs

@@ -0,0 +1,95 @@
+import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+/**
+ * Walk a directory tree and return all file paths relative to root.
+ */
+function walk(dir, root = dir) {
+  const results = [];
+  if (!existsSync(dir)) return results;
+
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...walk(full, root));
+    } else {
+      results.push(relative(root, full));
+    }
+  }
+  return results.sort();
+}
+
+/**
+ * Compare two directory trees and return a structured diff.
+ * Returns { added: [], removed: [], changed: [], unchanged: [] }
+ * Each entry in changed has { file, installedContent, availableContent }.
+ */
+export function diffTrees(installedDir, availableDir) {
+  const installedFiles = new Set(walk(installedDir));
+  const availableFiles = new Set(walk(availableDir));
+
+  const added = [];
+  const removed = [];
+  const changed = [];
+  const unchanged = [];
+
+  // Files in available but not installed
+  for (const file of availableFiles) {
+    if (!installedFiles.has(file)) {
+      added.push(file);
+    }
+  }
+
+  // Files in installed but not available
+  for (const file of installedFiles) {
+    if (!availableFiles.has(file)) {
+      removed.push(file);
+    }
+  }
+
+  // Files in both — compare content
+  for (const file of availableFiles) {
+    if (!installedFiles.has(file)) continue;
+    const a = readFileSync(join(installedDir, file), 'utf8');
+    const b = readFileSync(join(availableDir, file), 'utf8');
+    if (a === b) {
+      unchanged.push(file);
+    } else {
+      changed.push(file);
+    }
+  }
+
+  return { added, removed, changed, unchanged };
+}
+
+/**
+ * Format a diff result as a human-readable string.
+ */
+export function formatDiff(result) {
+  const lines = [];
+
+  if (result.added.length) {
+    lines.push('Added:');
+    for (const f of result.added) lines.push(`  + ${f}`);
+  }
+  if (result.removed.length) {
+    lines.push('Removed:');
+    for (const f of result.removed) lines.push(`  - ${f}`);
+  }
+  if (result.changed.length) {
+    lines.push('Changed:');
+    for (const f of result.changed) lines.push(`  ~ ${f}`);
+  }
+
+  if (!lines.length) {
+    lines.push('No differences.');
+  } else {
+    const total = result.added.length + result.removed.length + result.changed.length;
+    lines.push('');
+    lines.push(
+      `${total} file(s) differ (${result.added.length} added, ${result.removed.length} removed, ${result.changed.length} changed, ${result.unchanged.length} unchanged)`
+    );
+  }
+
+  return lines.join('\n');
+}

package/src/lib/topology.mjs

@@ -0,0 +1,62 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Read project.yaml and extract topology information.
+ * Uses a simple line parser — no YAML library dependency.
+ *
+ * @param {string} rootRepoDir — path to the cloned root repo
+ * @returns {{ project: string, group: string, components: Array<{name, type, location}> }}
+ */
+export function readTopology(rootRepoDir) {
+  const filePath = join(rootRepoDir, 'project.yaml');
+  const content = readFileSync(filePath, 'utf8');
+
+  const result = { project: '', group: '', components: [] };
+  let currentComponent = null;
+
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+
+    // Top-level scalars
+    if (trimmed.startsWith('project:')) {
+      result.project = extractValue(trimmed);
+    } else if (trimmed.startsWith('group:')) {
+      result.group = extractValue(trimmed);
+    }
+
+    // Component list entries
+    if (trimmed.startsWith('- name:')) {
+      if (currentComponent) result.components.push(currentComponent);
+      currentComponent = { name: extractValue(trimmed.replace('- ', '')), type: '', location: '' };
+    } else if (currentComponent && trimmed.startsWith('type:')) {
+      currentComponent.type = extractValue(trimmed);
+    } else if (currentComponent && trimmed.startsWith('location:')) {
+      currentComponent.location = extractValue(trimmed);
+    }
+  }
+
+  if (currentComponent) result.components.push(currentComponent);
+
+  return result;
+}
+
+function extractValue(line) {
+  const parts = line.split(':');
+  parts.shift();
+  return parts.join(':').trim().replace(/^["']|["']$/g, '');
+}
+
+/**
+ * Get the list of referenced (external) repos from the topology.
+ * Returns the repo name (last segment of location) and full location.
+ */
+export function getReferencedRepos(topology) {
+  return topology.components
+    .filter((c) => c.type === 'referenced')
+    .map((c) => ({
+      name: c.name,
+      location: c.location,
+      repoName: c.location.split('/').pop(),
+    }));
+}

package/src/lib/version-file.mjs

@@ -0,0 +1,25 @@
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { createRequire } from 'node:module';
+
+const VERSION_FILE = '.m-version';
+
+/** Read the installed M version from .m-version in the target dir. */
+export function readInstalledVersion(target) {
+  const file = join(target, VERSION_FILE);
+  if (!existsSync(file)) return null;
+  return readFileSync(file, 'utf8').trim();
+}
+
+/** Write the M version to .m-version in the target dir. */
+export function writeInstalledVersion(target, version) {
+  const file = join(target, VERSION_FILE);
+  writeFileSync(file, version + '\n', 'utf8');
+}
+
+/** Read the available (bundled) M version from the CLI's package.json. */
+export function readAvailableVersion() {
+  const require = createRequire(import.meta.url);
+  const pkg = require('../../package.json');
+  return pkg.version;
+}

package/src/lib/workspace.mjs

@@ -0,0 +1,40 @@
+import { writeFileSync } from 'node:fs';
+import { join, basename } from 'node:path';
+
+/**
+ * Generate an IDE workspace file for the project.
+ *
+ * @param {string} parentDir  — directory containing all cloned repos
+ * @param {string} projectName — project name (used for the file name)
+ * @param {string[]} repoDirs — directory names of all repos (root + managed)
+ * @param {object} options
+ * @param {string} options.ide — IDE to generate for (default: 'vscode')
+ * @returns {string} path to the generated workspace file
+ */
+export function generateWorkspace(parentDir, projectName, repoDirs, options = {}) {
+  const ide = options.ide || 'vscode';
+
+  switch (ide) {
+    case 'vscode':
+      return generateVSCodeWorkspace(parentDir, projectName, repoDirs);
+    default:
+      throw new Error(
+        `Unsupported IDE: "${ide}". Supported: vscode. ` +
+        `(More IDEs can be added — PRs welcome.)`
+      );
+  }
+}
+
+function generateVSCodeWorkspace(parentDir, projectName, repoDirs) {
+  const workspace = {
+    folders: repoDirs.map((dir) => ({
+      name: dir,
+      path: dir,
+    })),
+    settings: {},
+  };
+
+  const filePath = join(parentDir, `${projectName}.code-workspace`);
+  writeFileSync(filePath, JSON.stringify(workspace, null, 2) + '\n', 'utf8');
+  return filePath;
+}

package/src/lib/wrappers/claude.mjs

@@ -0,0 +1,54 @@
+import { cpSync, existsSync, mkdirSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Generate Claude Code wrapper files:
+ *   .claude/steering/m-steering.md
+ *   .claude/skills/<name>/SKILL.md  (one per M capability)
+ *
+ * Only creates files that don't already exist — respects project ownership.
+ */
+export function generateClaudeWrappers(target) {
+  const created = [];
+  const skipped = [];
+  const templatesDir = join(import.meta.dirname, '..', '..', '..', 'templates', 'claude');
+
+  // Steering wrapper (single file)
+  const steeringPair = {
+    src: join(templatesDir, 'steering', 'm-steering.md'),
+    dest: join(target, '.claude', 'steering', 'm-steering.md'),
+    label: '.claude/steering/m-steering.md',
+  };
+
+  if (existsSync(steeringPair.dest)) {
+    skipped.push(steeringPair.label);
+  } else {
+    mkdirSync(join(steeringPair.dest, '..'), { recursive: true });
+    cpSync(steeringPair.src, steeringPair.dest);
+    created.push(steeringPair.label);
+  }
+
+  // Skill wrappers (one directory per capability)
+  const skillsTemplateDir = join(templatesDir, 'skills');
+  if (existsSync(skillsTemplateDir)) {
+    for (const name of readdirSync(skillsTemplateDir, { withFileTypes: true })) {
+      if (!name.isDirectory()) continue;
+
+      const src = join(skillsTemplateDir, name.name, 'SKILL.md');
+      const dest = join(target, '.claude', 'skills', name.name, 'SKILL.md');
+      const label = `.claude/skills/${name.name}/SKILL.md`;
+
+      if (!existsSync(src)) continue;
+
+      if (existsSync(dest)) {
+        skipped.push(label);
+      } else {
+        mkdirSync(join(dest, '..'), { recursive: true });
+        cpSync(src, dest);
+        created.push(label);
+      }
+    }
+  }
+
+  return { created, skipped };
+}

package/templates/claude/skills/bootstrap-root-repo/SKILL.md

@@ -0,0 +1,13 @@
+# bootstrap-root-repo
+
+Create and seed the root repo with topology manifest and Story Zero
+
+## Triggers
+
+bootstrap root repo, create root repo
+
+## Execution
+
+Read and execute the full capability at `.m/capabilities/bootstrap-root-repo/SKILL.md`.
+
+Follow the M execution protocol defined in `.m/m.md`.

package/templates/claude/skills/decompose-story/SKILL.md

@@ -0,0 +1,13 @@
+# decompose-story
+
+Map story-level PATs to components, generate sub-tasks and readiness tracker
+
+## Triggers
+
+decompose story, break down story
+
+## Execution
+
+Read and execute the full capability at `.m/capabilities/decompose-story/SKILL.md`.
+
+Follow the M execution protocol defined in `.m/m.md`.

package/templates/claude/skills/generate-acceptance-tests/SKILL.md

@@ -0,0 +1,13 @@
+# generate-acceptance-tests
+
+Compile PAT stubs into executable acceptance tests (CATs)
+
+## Triggers
+
+generate acceptance tests, compile cats
+
+## Execution
+
+Read and execute the full capability at `.m/capabilities/generate-acceptance-tests/SKILL.md`.
+
+Follow the M execution protocol defined in `.m/m.md`.

package/templates/claude/skills/generate-pats/SKILL.md

@@ -0,0 +1,13 @@
+# generate-pats
+
+Transform story acceptance criteria into PAT.yaml format
+
+## Triggers
+
+generate pats, create acceptance tests
+
+## Execution
+
+Read and execute the full capability at `.m/capabilities/generate-pats/SKILL.md`.
+
+Follow the M execution protocol defined in `.m/m.md`.

package/templates/claude/skills/scaffold-repo/SKILL.md

@@ -0,0 +1,13 @@
+# scaffold-repo
+
+Create and configure a managed repo from a sub-task file
+
+## Triggers
+
+scaffold repo, create managed repo
+
+## Execution
+
+Read and execute the full capability at `.m/capabilities/scaffold-repo/SKILL.md`.
+
+Follow the M execution protocol defined in `.m/m.md`.

package/templates/claude/skills/setup-workspace/SKILL.md

@@ -0,0 +1,13 @@
+# setup-workspace
+
+Create a project workspace (group/org) on the SCM platform
+
+## Triggers
+
+setup workspace, create project workspace
+
+## Execution
+
+Read and execute the full capability at `.m/capabilities/setup-workspace/SKILL.md`.
+
+Follow the M execution protocol defined in `.m/m.md`.

package/templates/claude/skills/tag-release/SKILL.md

@@ -0,0 +1,13 @@
+# tag-release
+
+Tag a managed repo at a version and update root repo topology
+
+## Triggers
+
+tag release, version component
+
+## Execution
+
+Read and execute the full capability at `.m/capabilities/tag-release/SKILL.md`.
+
+Follow the M execution protocol defined in `.m/m.md`.

package/templates/claude/skills/wire-orchestration/SKILL.md

@@ -0,0 +1,13 @@
+# wire-orchestration
+
+Connect managed repos to root repo orchestration (webhooks, CI, tokens)
+
+## Triggers
+
+wire orchestration, connect repos
+
+## Execution
+
+Read and execute the full capability at `.m/capabilities/wire-orchestration/SKILL.md`.
+
+Follow the M execution protocol defined in `.m/m.md`.

package/templates/claude/steering/m-steering.md

@@ -0,0 +1,3 @@
+# Methodology M — Claude Steering
+
+Read and follow the canonical steering at `.m/m.md`.