openspecpm 0.1.0-alpha.0

package/cli/src/commands/assign.js

@@ -0,0 +1,78 @@
+import { readConfig } from '../config.js';
+import { loadAdapter } from '../adapters/index.js';
+import { loadChange } from '../tracking.js';
+import { changeExists } from '../openspec-bridge.js';
+
+/**
+ * Generic "set fields on this work item" command. Wraps adapter.updateWorkItem
+ * so users don't have to know per-adapter field names.
+ *
+ * Examples:
+ *   openspecpm assign demo "Add toggle" --assignee alice
+ *   openspecpm assign demo "Add toggle" --sprint S5 --story-points 3
+ *   openspecpm assign demo "Add toggle" --iteration Sprint-12 --area Web/Mobile
+ */
+export async function runAssign({
+  feature,
+  task: taskRef,
+  assignee,
+  sprint,
+  iteration,
+  area,
+  storyPoints,
+} = {}) {
+  if (!feature) throw new Error('feature name is required');
+  if (!taskRef) throw new Error('task title or external_id is required');
+  const config = await readConfig();
+  if (!config) {
+    const err = new Error('No .openspecpm/config.json found.');
+    err.remediation = 'Run `openspecpm init` first.';
+    throw err;
+  }
+  if (!changeExists(feature)) throw new Error(`OpenSpec change "${feature}" not found.`);
+
+  const change = await loadChange(feature);
+  const task = change.items.find((t) => t.title === taskRef) ?? change.items.find((t) => String(t.external_id) === String(taskRef));
+  if (!task) {
+    const err = new Error(`Task "${taskRef}" not found in feature "${feature}".`);
+    err.remediation = 'Run `openspecpm status` to see available tasks.';
+    throw err;
+  }
+  if (!task.external_id) {
+    const err = new Error(`Task "${task.title}" has no external_id — it hasn't been synced yet.`);
+    err.remediation = `Run \`openspecpm sync ${feature}\` first.`;
+    throw err;
+  }
+
+  const adapter = loadAdapter(config.adapter, config);
+  await adapter.init();
+
+  // Per-adapter field translation. Each adapter accepts the keys it supports
+  // and ignores the rest; this is a deliberate "best-effort" surface.
+  const patch = {};
+  if (assignee) patch.assignee = assignee;
+  if (sprint) {
+    // Jira sprint id, ADO iteration path, Linear cycle id, GitLab milestone id
+    patch.sprint = sprint;
+    patch.iterationPath = sprint;
+    patch.milestoneId = sprint;
+    patch.cycleId = sprint;
+  }
+  if (iteration) {
+    patch.iterationPath = iteration;
+    patch.sprint = iteration;
+  }
+  if (area) patch.areaPath = area;
+  if (storyPoints !== undefined) {
+    patch.estimate = Number(storyPoints);    // Linear / Jira customField map externally
+    patch.weight = Number(storyPoints);      // GitLab
+    patch.storyPoints = Number(storyPoints); // semantic key for future adapters
+  }
+
+  await adapter.updateWorkItem({ adapter: config.adapter, id: task.external_id }, patch);
+  process.stdout.write(`✓ Updated ${task.external_id} on ${config.adapter}.\n`);
+  const fields = Object.entries({ assignee, sprint, iteration, area, storyPoints })
+    .filter(([, v]) => v !== undefined && v !== null && v !== '')
+    .map(([k, v]) => `${k}=${v}`).join(', ');
+  if (fields) process.stdout.write(`  Set: ${fields}\n`);
+}

package/cli/src/commands/blocked.js

@@ -0,0 +1,17 @@
+import { listChanges, findBlockedTasks } from '../tracking.js';
+
+export async function runBlocked() {
+  const changes = await listChanges();
+  const blocked = findBlockedTasks(changes);
+  out(`openspecpm blocked — ${blocked.length} task(s) waiting on dependencies\n`);
+  if (!blocked.length) return;
+  for (const { change, task, unmet } of blocked) {
+    const tag = task.external_id ? ` [${task.external_id}]` : ' [unsynced]';
+    out(`  • ${change} — ${task.title}${tag}`);
+    for (const u of unmet) out(`      ↳ ${u.reason}: ${u.dep}`);
+  }
+}
+
+function out(s) {
+  process.stdout.write(s + '\n');
+}

package/cli/src/commands/bug-report.js

@@ -0,0 +1,78 @@
+import { readConfig } from '../config.js';
+import { loadAdapter } from '../adapters/index.js';
+import { loadChange } from '../tracking.js';
+import { changeExists } from '../openspec-bridge.js';
+
+export async function runBugReport({ feature, task: taskRef, title, body } = {}) {
+  if (!feature) throw new Error('feature name is required');
+  if (!taskRef) throw new Error('task title or external_id is required');
+  if (!title) throw new Error('bug title is required (use --title)');
+  const config = await readConfig();
+  if (!config) {
+    const err = new Error('No .openspecpm/config.json found.');
+    err.remediation = 'Run `openspecpm init` first.';
+    throw err;
+  }
+  if (!changeExists(feature)) throw new Error(`OpenSpec change "${feature}" not found.`);
+
+  const change = await loadChange(feature);
+  const orig = change.items.find((t) => t.title === taskRef) ?? change.items.find((t) => String(t.external_id) === String(taskRef));
+  if (!orig) {
+    const err = new Error(`Task "${taskRef}" not found in feature "${feature}".`);
+    err.remediation = 'Run `openspecpm status` to see available tasks.';
+    throw err;
+  }
+  if (!orig.external_id) {
+    const err = new Error(`Cannot file a bug against an unsynced task.`);
+    err.remediation = `Run \`openspecpm sync ${feature}\` first.`;
+    throw err;
+  }
+
+  const adapter = loadAdapter(config.adapter, config);
+  await adapter.init();
+
+  const epicRef = change.proposal.external?.[config.adapter];
+
+  const bugTitle = `[bug] ${title}`;
+  const bugBody = [
+    body ?? '',
+    '',
+    `Reported against task "${orig.title}" (${orig.external_id})`,
+    epicRef ? `Epic: ${epicRef.url ?? epicRef.id}` : '',
+    `Feature: ${feature}`,
+    '',
+    'Reproduce:',
+    '1. <steps>',
+    '',
+    'Expected:',
+    '',
+    'Actual:',
+    '',
+    `Filed via \`openspecpm bug-report\`.`,
+  ].filter(Boolean).join('\n');
+
+  const bugRef = await adapter.createWorkItem(
+    epicRef ?? { id: orig.external_id, feature },
+    { title: bugTitle, body: bugBody, type: 'Bug' },
+  );
+  process.stdout.write(`✓ Created bug ${bugRef.url ?? bugRef.id}\n`);
+
+  // Link bug ↔ original.
+  try {
+    await adapter.linkWorkItems({ adapter: config.adapter, id: orig.external_id }, bugRef, 'Relates');
+  } catch (err) {
+    process.stdout.write(`  (warning: failed to link to original: ${err.message})\n`);
+  }
+
+  // Comment on the original referencing the bug.
+  try {
+    await adapter.addProgressComment(
+      { adapter: config.adapter, id: orig.external_id },
+      `<!-- SYNCED: ${new Date().toISOString()} -->\nFollow-up bug filed: ${bugRef.url ?? bugRef.id} — ${title}`,
+    );
+  } catch (err) {
+    process.stdout.write(`  (warning: failed to comment on original: ${err.message})\n`);
+  }
+
+  process.stdout.write(`Done. Bug is now visible in your PM tool, linked to ${orig.external_id}.\n`);
+}

package/cli/src/commands/bulk.js

@@ -0,0 +1,67 @@
+import * as p from '@clack/prompts';
+import { listChanges, summarizeChange } from '../tracking.js';
+import { runSync } from './sync.js';
+import { runShip } from './ship.js';
+
+export async function runSyncAll({ dryRun = false, force = false, yes = false } = {}) {
+  const changes = await listChanges();
+  if (!changes.length) {
+    process.stdout.write('No OpenSpec changes to sync.\n');
+    return;
+  }
+
+  if (!yes) {
+    p.intro('openspecpm sync --all');
+    p.note(`Will sync ${changes.length} change(s): ${changes.map((c) => c.name).join(', ')}`, 'plan');
+    const ok = await p.confirm({ message: 'Proceed?', initialValue: false });
+    if (p.isCancel(ok) || !ok) { p.cancel('Aborted.'); return; }
+  }
+
+  let synced = 0;
+  let failed = 0;
+  for (const change of changes) {
+    process.stdout.write(`\n── ${change.name} ──\n`);
+    try {
+      await runSync({ feature: change.name, dryRun, force });
+      synced++;
+    } catch (err) {
+      process.stderr.write(`✖ ${change.name} sync failed: ${err.message}\n`);
+      if (err.remediation) process.stderr.write(`  → ${err.remediation}\n`);
+      failed++;
+    }
+  }
+  process.stdout.write(`\nSummary: ${synced} synced, ${failed} failed.\n`);
+}
+
+export async function runShipAllReady({ yes = false, skipArchive = false } = {}) {
+  const changes = await listChanges();
+  const ready = changes.filter((c) => {
+    const s = summarizeChange(c);
+    return s.total > 0 && s.counts.pending === 0 && s.counts.failed === 0;
+  });
+  if (!ready.length) {
+    process.stdout.write('No changes are fully synced and ready to ship.\n');
+    return;
+  }
+
+  if (!yes) {
+    p.intro('openspecpm ship --all-ready');
+    p.note(`Will ship ${ready.length} change(s): ${ready.map((c) => c.name).join(', ')}`, 'plan');
+    const ok = await p.confirm({ message: 'Close all of these in the PM tool and archive?', initialValue: false });
+    if (p.isCancel(ok) || !ok) { p.cancel('Aborted.'); return; }
+  }
+
+  let shipped = 0;
+  let failed = 0;
+  for (const change of ready) {
+    process.stdout.write(`\n── ${change.name} ──\n`);
+    try {
+      await runShip({ feature: change.name, yes: true, skipArchive });
+      shipped++;
+    } catch (err) {
+      process.stderr.write(`✖ ${change.name} ship failed: ${err.message}\n`);
+      failed++;
+    }
+  }
+  process.stdout.write(`\nSummary: ${shipped} shipped, ${failed} failed.\n`);
+}

package/cli/src/commands/comment.js

@@ -0,0 +1,83 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { readConfig } from '../config.js';
+import { loadAdapter } from '../adapters/index.js';
+import { loadChange } from '../tracking.js';
+import { changeDir, changeExists } from '../openspec-bridge.js';
+
+export async function runComment({ feature, task: taskRef, message, dryRun = false } = {}) {
+  if (!feature) throw new Error('feature name is required');
+  if (!taskRef) throw new Error('task title or external_id is required');
+  const config = await readConfig();
+  if (!config) {
+    const err = new Error('No .openspecpm/config.json found.');
+    err.remediation = 'Run `openspecpm init` first.';
+    throw err;
+  }
+  if (!changeExists(feature)) {
+    const err = new Error(`OpenSpec change "${feature}" not found.`);
+    throw err;
+  }
+
+  const change = await loadChange(feature);
+  const task = resolveTask(change.items, taskRef);
+  if (!task) {
+    const err = new Error(`Task "${taskRef}" not found in feature "${feature}".`);
+    err.remediation = `Run \`openspecpm status\` to see available tasks.`;
+    throw err;
+  }
+  if (!task.external_id) {
+    const err = new Error(`Task "${task.title}" has no external_id — it hasn't been synced yet.`);
+    err.remediation = `Run \`openspecpm sync ${feature}\` first.`;
+    throw err;
+  }
+
+  const body = await resolveBody({ message, feature, taskRef, taskTitle: task.title });
+  const stamped = `<!-- SYNCED: ${new Date().toISOString()} -->\n${body}`;
+
+  if (dryRun) {
+    process.stdout.write(`[dry-run] would post to ${config.adapter} item ${task.external_id}:\n`);
+    process.stdout.write(stamped + '\n');
+    return;
+  }
+
+  const adapter = loadAdapter(config.adapter, config);
+  await adapter.init();
+  await adapter.addProgressComment({ adapter: config.adapter, id: task.external_id }, stamped);
+  process.stdout.write(`✓ Comment posted to ${task.external_id}.\n`);
+
+  // Append to local progress.md so the local narrative reflects the broadcast.
+  await appendLocalProgress(feature, taskRef, stamped);
+}
+
+function resolveTask(items, ref) {
+  return items.find((t) => t.title === ref) ?? items.find((t) => String(t.external_id) === String(ref));
+}
+
+async function resolveBody({ message, feature, taskRef, taskTitle }) {
+  if (message) return message;
+  const slug = slugify(taskRef === taskTitle ? taskTitle : taskRef);
+  const progressPath = join(changeDir(feature), 'updates', slug, 'progress.md');
+  if (existsSync(progressPath)) {
+    const raw = await readFile(progressPath, 'utf8');
+    return raw.trim() || `(progress.md is empty)`;
+  }
+  const err = new Error('No --message provided and no local progress.md to post.');
+  err.remediation = `Either pass --message "..." or create ${progressPath}.`;
+  throw err;
+}
+
+async function appendLocalProgress(feature, taskRef, body) {
+  const slug = slugify(taskRef);
+  const dir = join(changeDir(feature), 'updates', slug);
+  await mkdir(dir, { recursive: true });
+  const file = join(dir, 'progress.md');
+  const existing = existsSync(file) ? await readFile(file, 'utf8') : '';
+  const sep = existing && !existing.endsWith('\n') ? '\n\n' : '\n';
+  await writeFile(file, existing + sep + body + '\n', 'utf8');
+}
+
+function slugify(s) {
+  return String(s).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60) || 'task';
+}

package/cli/src/commands/decompose.js

@@ -0,0 +1,106 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { changeDir, changeExists } from '../openspec-bridge.js';
+import { parseScenarios } from '../bdd/linter.js';
+import * as fm from '../frontmatter.js';
+
+export async function runDecompose({ feature, force = false } = {}) {
+  if (!feature) throw new Error('feature name is required');
+  if (!changeExists(feature)) {
+    const err = new Error(`OpenSpec change "${feature}" not found.`);
+    err.remediation = `Run \`openspecpm propose ${feature}\` first.`;
+    throw err;
+  }
+
+  const dir = changeDir(feature);
+  const proposalPath = join(dir, 'proposal.md');
+  const tasksPath = join(dir, 'tasks.md');
+
+  let existingItems = [];
+  if (existsSync(tasksPath)) {
+    const raw = await readFile(tasksPath, 'utf8');
+    const { data } = fm.parse(raw);
+    existingItems = data.items ?? [];
+    if (existingItems.length && !force) {
+      process.stdout.write(`tasks.md already has ${existingItems.length} item(s). Pass --force to merge.\n`);
+      return;
+    }
+  }
+
+  const proposal = existsSync(proposalPath) ? await readFile(proposalPath, 'utf8') : '';
+  const specsItems = await extractFromSpecs(dir);
+  const proposalItems = extractFromProposal(proposal);
+  const merged = dedupe([...existingItems, ...proposalItems, ...specsItems]);
+
+  const out = fm.serialize(
+    { schema_version: 1, items: merged },
+    `\n# Tasks\n\nGenerated by \`openspecpm decompose\`. Refine titles, set depends_on, mark parallel: true where safe.\n`,
+  );
+  await writeFile(tasksPath, out, 'utf8');
+  process.stdout.write(`✓ Wrote ${merged.length} task(s) to ${tasksPath}.\n`);
+  if (proposalItems.length) process.stdout.write(`  ${proposalItems.length} from proposal headings/checklists.\n`);
+  if (specsItems.length) process.stdout.write(`  ${specsItems.length} from BDD scenarios in specs/.\n`);
+  process.stdout.write(`Next: review tasks.md, then \`openspecpm sync ${feature}\`.\n`);
+}
+
+function extractFromProposal(md) {
+  if (!md) return [];
+  const { body } = fm.parse(md);
+  const items = [];
+  let inTasksSection = false;
+  for (const raw of body.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (/^#+\s*(tasks|implementation|deliverables|steps)/i.test(line)) {
+      inTasksSection = true;
+      continue;
+    }
+    if (/^#+\s/.test(line)) inTasksSection = false;
+    const check = line.match(/^-\s*\[( |x|X)\]\s+(.+)/);
+    if (check) {
+      items.push({ title: check[2].trim(), sync_state: 'pending', parallel: false, depends_on: [] });
+      continue;
+    }
+    if (inTasksSection) {
+      const bullet = line.match(/^[-*]\s+(.+)/);
+      const numbered = line.match(/^\d+[.)]\s+(.+)/);
+      const match = bullet ?? numbered;
+      if (match) items.push({ title: match[1].trim(), sync_state: 'pending', parallel: false, depends_on: [] });
+    }
+  }
+  return items;
+}
+
+async function extractFromSpecs(featureDir) {
+  const specsDir = join(featureDir, 'specs');
+  if (!existsSync(specsDir)) return [];
+  const { readdir } = await import('node:fs/promises');
+  const files = await readdir(specsDir);
+  const items = [];
+  for (const f of files) {
+    if (!f.endsWith('.md')) continue;
+    const raw = await readFile(join(specsDir, f), 'utf8');
+    for (const scenario of parseScenarios(raw)) {
+      items.push({
+        title: `Implement: ${scenario.title}`,
+        sync_state: 'pending',
+        parallel: false,
+        depends_on: [],
+        spec: f,
+      });
+    }
+  }
+  return items;
+}
+
+function dedupe(items) {
+  const seen = new Set();
+  const out = [];
+  for (const item of items) {
+    const key = (item.title ?? '').trim().toLowerCase();
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    out.push(item);
+  }
+  return out;
+}

package/cli/src/commands/doctor.js

@@ -0,0 +1,61 @@
+import { readConfig } from '../config.js';
+import { loadAdapter, listAdapters, resolveAdapter } from '../adapters/index.js';
+import { probe, OpenSpecError } from '../openspec-bridge.js';
+import { installCommand, patSetup, osName } from '../install-hints.js';
+
+export async function runDoctor({ adapter, install = false, setupAuth = false } = {}) {
+  process.stdout.write('openspecpm doctor\n\n');
+
+  // OpenSpec health
+  try {
+    const { version } = await probe();
+    line(true, `OpenSpec ${version} on PATH`);
+  } catch (err) {
+    if (err instanceof OpenSpecError) {
+      line(false, err.message, err.remediation);
+      if (install) suggestInstall('openspec');
+    } else {
+      throw err;
+    }
+  }
+
+  const config = await readConfig();
+  const adapters = adapter
+    ? [resolveAdapter(adapter)]
+    : (config ? [resolveAdapter(config.adapter)] : listAdapters());
+
+  for (const name of adapters) {
+    process.stdout.write(`\n[${name}]\n`);
+    const cfg = config && resolveAdapter(config.adapter) === name ? config : {};
+    const a = loadAdapter(name, cfg);
+    const findings = await a.doctor();
+    for (const f of findings) line(f.ok, f.msg, f.remediation);
+    if (install) suggestAdapterInstall(name);
+    if (setupAuth) suggestAuth(name);
+  }
+}
+
+function line(ok, msg, remediation) {
+  process.stdout.write(`  ${ok ? '✓' : '✖'} ${msg}\n`);
+  if (!ok && remediation) process.stdout.write(`    → ${remediation}\n`);
+}
+
+function suggestInstall(tool) {
+  const cmd = installCommand(tool);
+  if (!cmd) return;
+  process.stdout.write(`    → on ${osName()}: ${cmd}\n`);
+}
+
+function suggestAdapterInstall(name) {
+  if (name === 'github') suggestInstall('gh');
+  if (name === 'azure') suggestInstall('az');
+  // Linear, GitLab, Jira use REST directly — no CLI required.
+}
+
+function suggestAuth(adapterName) {
+  const info = patSetup(adapterName);
+  if (!info) return;
+  process.stdout.write(`    auth setup:\n`);
+  process.stdout.write(`      • create token at: ${info.url}\n`);
+  process.stdout.write(`      • required scopes: ${info.scopes}\n`);
+}

package/cli/src/commands/fan-out.js

@@ -0,0 +1,79 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { loadChange, unmetDeps } from '../tracking.js';
+import { changeDir, changeExists } from '../openspec-bridge.js';
+import { record } from '../audit.js';
+
+export async function runFanOut({ feature, limit = 5 } = {}) {
+  if (!feature) throw new Error('feature name is required');
+  if (!changeExists(feature)) throw new Error(`OpenSpec change "${feature}" not found.`);
+  const change = await loadChange(feature);
+
+  const candidates = change.items.filter(
+    (t) => !t.done && !t.closed && t.parallel === true && unmetDeps(t, change.items).length === 0,
+  );
+  if (!candidates.length) {
+    process.stdout.write('No tasks ready for parallel fan-out.\n');
+    process.stdout.write('  Tip: mark tasks with `parallel: true` in tasks.md and ensure depends_on are met.\n');
+    return;
+  }
+
+  const proposal = await readFileSafe(join(changeDir(feature), 'proposal.md'));
+  const design = await readFileSafe(join(changeDir(feature), 'design.md'));
+  const tasks = candidates.slice(0, limit);
+
+  process.stdout.write(`openspecpm fan-out ${feature} — ${tasks.length} parallel task(s) ready\n\n`);
+  process.stdout.write(`Copy each prompt below into a separate agent session. The agent should treat\n`);
+  process.stdout.write(`the BDD scenarios in specs/ as acceptance criteria.\n`);
+  process.stdout.write(`${'='.repeat(72)}\n\n`);
+
+  for (const [i, task] of tasks.entries()) {
+    const specFile = task.spec ? join(changeDir(feature), 'specs', task.spec) : null;
+    const specBlock = specFile && existsSync(specFile) ? await readFile(specFile, 'utf8') : '(no spec file linked — read all of specs/)';
+    process.stdout.write(`--- Agent ${i + 1} of ${tasks.length} ---\n`);
+    process.stdout.write(`Task: ${task.title}${task.external_id ? ` [#${task.external_id}]` : ''}\n\n`);
+    process.stdout.write(`Prompt to paste:\n\n`);
+    process.stdout.write([
+      `Implement the task "${task.title}" from feature "${feature}".`,
+      ``,
+      `Context (proposal):`,
+      truncate(proposal, 1200),
+      ``,
+      `Design notes:`,
+      truncate(design, 800),
+      ``,
+      `Acceptance criteria (BDD scenarios):`,
+      truncate(specBlock, 1200),
+      ``,
+      `Rules:`,
+      `- Only modify files relevant to this task. Leave other parallel streams alone.`,
+      `- When done, append progress notes to openspec/changes/${feature}/updates/${slugify(task.title)}/progress.md.`,
+      `- If you discover the spec is ambiguous, stop and ask before guessing.`,
+    ].join('\n') + '\n\n');
+  }
+  process.stdout.write(`${'='.repeat(72)}\n`);
+  process.stdout.write(`After dispatching, run \`openspecpm standup\` to see updates as agents post progress.\n`);
+
+  try {
+    await record({
+      command: 'fan-out',
+      args: { feature, dispatched: tasks.map((t) => t.title) },
+      result: 'ok',
+    });
+  } catch { /* never break the user */ }
+}
+
+async function readFileSafe(p) {
+  if (!existsSync(p)) return '';
+  try { return await readFile(p, 'utf8'); } catch { return ''; }
+}
+
+function truncate(s, max) {
+  if (!s) return '(none)';
+  return s.length > max ? s.slice(0, max) + '\n…' : s;
+}
+
+function slugify(s) {
+  return String(s).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60) || 'task';
+}

package/cli/src/commands/help.js

@@ -0,0 +1,69 @@
+const SECTIONS = [
+  {
+    title: 'Setup',
+    rows: [
+      ['init', 'Interactive wizard to pick a PM tool and write .openspecpm/config.json'],
+      ['doctor [adapter]', 'Diagnose auth + tooling; English remediation hints'],
+    ],
+  },
+  {
+    title: 'Plan',
+    rows: [
+      ['propose <feature>', 'Author proposal.md, design.md, tasks.md, specs/ via OpenSpec'],
+      ['decompose <feature>', 'Extract tasks from proposal + BDD scenarios into tasks.md'],
+    ],
+  },
+  {
+    title: 'Sync',
+    rows: [
+      ['sync <feature>', 'Push to PM tool (idempotent, BDD-linted)'],
+      ['comment <feature> <task>', 'Broadcast progress.md (or --message) to the PM tool'],
+      ['reconcile <feature>', 'Pull remote state back into local frontmatter'],
+      ['bug-report <feature> <task>', 'File a regression against a shipped task'],
+    ],
+  },
+  {
+    title: 'Track',
+    rows: [
+      ['status', 'Per-change task counts'],
+      ['standup [--since 24h]', 'Recent progress.md updates, newest first'],
+      ['next [-l 5]', 'Tasks ready to start (no unmet deps)'],
+      ['blocked', 'Tasks waiting on unmet deps'],
+      ['validate', 'Schema + dependency + BDD-lint sweep across every change'],
+      ['search <query>', 'Grep across changes, specs, progress notes'],
+    ],
+  },
+  {
+    title: 'Execute / Ship',
+    rows: [
+      ['fan-out <feature>', 'Emit parallel-agent prompts for parallel:true tasks'],
+      ['ship <feature>', 'Close every task + epic + archive the OpenSpec change'],
+    ],
+  },
+];
+
+export function runHelp({ topic } = {}) {
+  if (topic) {
+    const section = SECTIONS.find((s) => s.title.toLowerCase() === topic.toLowerCase());
+    if (!section) {
+      process.stdout.write(`Unknown topic "${topic}". Try: ${SECTIONS.map((s) => s.title.toLowerCase()).join(', ')}\n`);
+      return;
+    }
+    print([section]);
+    return;
+  }
+  process.stdout.write('OpenSpecPM — command reference by phase\n\n');
+  print(SECTIONS);
+  process.stdout.write('\nDetails: `openspecpm <command> --help` (Commander auto-help).\n');
+  process.stdout.write('Skill docs: skill/openspecpm/references/{plan,structure,sync,execute,track}.md\n');
+}
+
+function print(sections) {
+  const w = Math.max(...sections.flatMap((s) => s.rows.map((r) => r[0].length))) + 2;
+  for (const s of sections) {
+    process.stdout.write(`\n[${s.title}]\n`);
+    for (const [cmd, desc] of s.rows) {
+      process.stdout.write(`  ${cmd.padEnd(w)} ${desc}\n`);
+    }
+  }
+}