dotmd-cli 0.11.0 → 0.12.0

package/README.md

@@ -120,6 +120,8 @@ dotmd plans                  List all plans
 dotmd stale                  List stale docs
 dotmd actionable             List docs with next steps
 dotmd index [--write]        Generate/update docs.md index block
+dotmd pickup <file>          Pick up a plan (in-session + print)
+dotmd finish <file>          Finish a plan (done or active)
 dotmd status <file> <status> Transition document status
 dotmd archive <file>         Archive (status + move + update refs)
 dotmd touch <file>           Bump updated date

package/bin/dotmd.mjs

@@ -8,7 +8,7 @@ import { buildIndex } from '../src/index.mjs';
 import { renderCompactList, renderVerboseList, renderContext, renderCheck, renderCoverage, buildCoverage } from '../src/render.mjs';
 import { renderIndexFile, writeIndex } from '../src/index-file.mjs';
 import { runFocus, runQuery } from '../src/query.mjs';
-import { runStatus, runArchive, runTouch, runBulkArchive } from '../src/lifecycle.mjs';
+import { runStatus, runArchive, runTouch, runBulkArchive, runPickup, runFinish } from '../src/lifecycle.mjs';
 import { runInit } from '../src/init.mjs';
 import { runNew } from '../src/new.mjs';
 import { runCompletions } from '../src/completions.mjs';
@@ -62,6 +62,8 @@ Validate & Fix:
   fix-refs [--dry-run]              Auto-fix broken reference paths + body links
 
 Lifecycle:
+  pickup <file>                     Pick up a plan (set in-session + print)
+  finish <file> [done|active]       Finish a plan (set done or active)
   status <file> <status>            Transition document status
   archive <file>                    Archive (status + move + update refs)
   bulk archive <f1> <f2> ...        Archive multiple files at once
@@ -130,6 +132,28 @@ Filters:
   --summarize-limit <n>  Max docs to summarize (default: 5)
   --model <name>         Model for AI summaries`,
 
+  pickup: `dotmd pickup <file> — pick up a plan and start working
+
+Sets the plan to in-session and prints its content.
+Fails if the plan is already in-session, blocked, done, or archived.
+
+Options:
+  --json                 Output as JSON
+  --dry-run, -n          Preview without writing
+
+If no file is given, prompts with a list of active plans.`,
+
+  finish: `dotmd finish <file> [done|active] — finish working on a plan
+
+Sets the plan status to done (default) or back to active.
+Only works on plans currently in-session.
+
+Options:
+  --json                 Output as JSON
+  --dry-run, -n          Preview without writing
+
+If no file is given, prompts with a list of in-session plans.`,
+
   status: `dotmd status <file> <new-status> — transition document status
 
 Moves the document to the new status. If transitioning to an archive
@@ -393,12 +417,6 @@ async function main() {
     return;
   }
 
-  // Init and completions don't need config
-  if (command === 'init') {
-    runInit(process.cwd());
-    return;
-  }
-
   if (command === 'completions') {
     runCompletions(args.slice(1));
     return;
@@ -418,6 +436,12 @@ async function main() {
 
   const config = await resolveConfig(process.cwd(), explicitConfig);
 
+  // Init — now has access to config for Claude command generation
+  if (command === 'init') {
+    runInit(process.cwd(), config.configFound ? config : null);
+    return;
+  }
+
   // Watch is a pure proxy — pass raw args so the child process gets all flags
   if (command === 'watch') { runWatch(args.slice(1), config); return; }
 
@@ -468,6 +492,8 @@ async function main() {
   if (command === 'notion') { await runNotion(restArgs, config, { dryRun }); return; }
 
   // Lifecycle commands
+  if (command === 'pickup') { await runPickup(restArgs, config, { dryRun }); return; }
+  if (command === 'finish') { await runFinish(restArgs, config, { dryRun }); return; }
   if (command === 'status') { await runStatus(restArgs, config, { dryRun }); return; }
   if (command === 'archive') { runArchive(restArgs, config, { dryRun }); return; }
   if (command === 'bulk' && restArgs[0] === 'archive') { runBulkArchive(restArgs.slice(1), config, { dryRun }); return; }
@@ -698,7 +724,7 @@ async function main() {
   // Unknown command — suggest closest match
   const allCommands = [
     'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'context',
-    'focus', 'query', 'plans', 'stale', 'actionable', 'index', 'status', 'archive', 'touch', 'doctor',
+    'focus', 'query', 'plans', 'stale', 'actionable', 'index', 'pickup', 'finish', 'status', 'archive', 'touch', 'doctor',
     'fix-refs', 'lint', 'rename', 'migrate', 'notion', 'export', 'summary',
     'watch', 'diff', 'new', 'init', 'completions',
   ];

package/dotmd.config.example.mjs

@@ -147,6 +147,8 @@ export const presets = {
 // export function onNew({ path, status, title, template }) {}
 // export function onRename({ oldPath, newPath, referencesUpdated }) {}
 // export function onLint({ path, fixes }) {}
+// export function onPickup({ path, oldStatus, newStatus }) {}
+// export function onFinish({ path, oldStatus, newStatus }) {}
 
 // AI hooks — override summarization (replaces local MLX model).
 // export function summarizeDoc(body, meta) { return 'Custom summary'; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, Notion sync, AI summaries.",
   "type": "module",
   "license": "MIT",

package/src/claude-commands.mjs

@@ -0,0 +1,151 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { green, dim, yellow } from './color.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+const VERSION_MARKER = `<!-- dotmd-generated: ${pkg.version} -->`;
+const VERSION_REGEX = /^<!-- dotmd-generated: ([\d.]+) -->/;
+
+function generatePlansCommand(config) {
+  const lines = [VERSION_MARKER, ''];
+  lines.push('Run `dotmd context` to get the current plans briefing, then use it to orient yourself.');
+  lines.push('');
+  lines.push(`Plans are managed by **dotmd** (v${pkg.version}). Config at \`dotmd.config.mjs\`. Always use \`dotmd\` directly.`);
+  lines.push('');
+  lines.push('Plan-specific commands:');
+  lines.push('- `dotmd context` — briefing with active/paused/ready plans, age tags, next steps');
+  lines.push('- `dotmd health` — plan velocity, aging, checklist progress, pipeline view');
+  lines.push('- `dotmd unblocks <file>` — what depends on / is blocked by a plan');
+  lines.push('- `dotmd next` — ready plans with next steps (what to promote)');
+  lines.push('- `dotmd new <name> --template plan` — scaffold with full phase structure');
+  lines.push('- `dotmd archive <file>` — archive with auto ref-fixing (both directions)');
+  lines.push('- `dotmd bulk archive <files>` — archive multiple at once');
+  lines.push('- `dotmd status <file> <status>` — transition status');
+  lines.push('- `dotmd query --keyword <term>` — find plans by keyword');
+
+  if (config.raw?.glossary) {
+    lines.push('- `dotmd glossary <term>` — domain term lookup with related plans');
+  }
+
+  lines.push('');
+  lines.push('If the user asks about a specific plan, read its file directly (path is in the briefing or findable via `dotmd query --keyword <term>`).');
+  lines.push('');
+  lines.push('If the user asks to change a plan\'s status, use `dotmd status <file> <status>`.');
+  lines.push('If the user asks to archive a plan, use `dotmd archive <file>`.');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+function generateDocsCommand(config) {
+  const roots = Array.isArray(config.raw?.root) ? config.raw.root : [config.raw?.root ?? 'docs'];
+  const rootCount = roots.length;
+
+  const lines = [VERSION_MARKER, ''];
+  lines.push(`All documentation in this repo is managed by **dotmd** (v${pkg.version}). Docs across ${rootCount} root${rootCount > 1 ? 's' : ''}: ${roots.join(', ')}. Config at \`dotmd.config.mjs\`.`);
+  lines.push('');
+
+  // Document types from config
+  const types = config.raw?.types ? Object.keys(config.raw.types) : [];
+  if (types.length > 0) {
+    lines.push(`Document types: ${types.map(t => '`' + t + '`').join(', ')}.`);
+    lines.push('');
+  }
+
+  lines.push('Commands for working with docs:');
+  lines.push('- `dotmd context` — LLM-oriented briefing across all types');
+  lines.push('- `dotmd check` — validate frontmatter, refs, body links (target: 0 errors)');
+  lines.push('- `dotmd doctor` — auto-fix everything in one pass (refs, lint, dates, index)');
+  lines.push('- `dotmd query [filters]` — search by status, keyword, module, surface, type, staleness');
+  lines.push('- `dotmd health` — plan pipeline, velocity, aging');
+  lines.push('- `dotmd stats` — doc health dashboard (completeness, checklists, audit coverage)');
+  lines.push('- `dotmd graph [--dot]` — visualize document relationships');
+  lines.push('- `dotmd deps [file]` — dependency tree');
+  lines.push('- `dotmd unblocks <file>` — impact analysis for a doc');
+  lines.push('- `dotmd diff [file]` — git changes since last updated date');
+  lines.push('- `dotmd list` — all docs grouped by status');
+  lines.push('- `dotmd focus <status>` — detailed view for one status group');
+
+  if (config.raw?.glossary) {
+    lines.push('- `dotmd glossary <term>` — domain term lookup with related docs and plans');
+  }
+
+  lines.push('');
+  lines.push('Lifecycle:');
+  lines.push('- `dotmd new <name> --template plan` — scaffold new plan');
+  lines.push('- `dotmd status <file> <status>` — transition status');
+  lines.push('- `dotmd archive <file>` — archive with auto ref-fixing');
+  lines.push('- `dotmd bulk archive <files>` — archive multiple at once');
+  lines.push('- `dotmd touch --git` — bulk-sync updated dates from git history');
+  lines.push('- `dotmd lint --fix` — auto-fix frontmatter issues');
+  lines.push('- `dotmd fix-refs` — repair broken references and body links');
+  lines.push('- `dotmd rename <old> <new>` — rename doc + update all references');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+function getInstalledVersion(filePath) {
+  if (!existsSync(filePath)) return null;
+  const content = readFileSync(filePath, 'utf8');
+  const match = content.match(VERSION_REGEX);
+  return match ? match[1] : null;
+}
+
+export function scaffoldClaudeCommands(cwd, config) {
+  const claudeDir = path.join(cwd, '.claude');
+  if (!existsSync(claudeDir)) return [];
+
+  const commandsDir = path.join(claudeDir, 'commands');
+  const results = [];
+
+  const files = [
+    { name: 'plans.md', generate: () => generatePlansCommand(config) },
+    { name: 'docs.md', generate: () => generateDocsCommand(config) },
+  ];
+
+  for (const { name, generate } of files) {
+    const filePath = path.join(commandsDir, name);
+    const installedVersion = getInstalledVersion(filePath);
+
+    if (installedVersion === pkg.version) {
+      results.push({ name, action: 'current' });
+    } else if (installedVersion) {
+      // Outdated — regenerate
+      mkdirSync(commandsDir, { recursive: true });
+      writeFileSync(filePath, generate(), 'utf8');
+      results.push({ name, action: 'updated', from: installedVersion, to: pkg.version });
+    } else if (!existsSync(filePath)) {
+      // New — create
+      mkdirSync(commandsDir, { recursive: true });
+      writeFileSync(filePath, generate(), 'utf8');
+      results.push({ name, action: 'created' });
+    } else {
+      // File exists but no version marker — user-managed, don't touch
+      results.push({ name, action: 'skipped' });
+    }
+  }
+
+  return results;
+}
+
+export function checkClaudeCommands(cwd) {
+  const commandsDir = path.join(cwd, '.claude', 'commands');
+  if (!existsSync(commandsDir)) return [];
+
+  const warnings = [];
+  for (const name of ['plans.md', 'docs.md']) {
+    const filePath = path.join(commandsDir, name);
+    const installedVersion = getInstalledVersion(filePath);
+    if (installedVersion && installedVersion !== pkg.version) {
+      warnings.push({
+        path: `.claude/commands/${name}`,
+        level: 'warning',
+        message: `Claude command outdated (v${installedVersion} → v${pkg.version}). Run \`dotmd doctor\` to update.`,
+      });
+    }
+  }
+  return warnings;
+}

package/src/completions.mjs

@@ -2,7 +2,7 @@ import { die } from './util.mjs';
 
 const COMMANDS = [
   'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'unblocks', 'health', 'glossary', 'context', 'focus', 'query',
-  'plans', 'stale', 'actionable', 'index', 'status', 'archive', 'bulk', 'touch', 'doctor', 'lint', 'rename', 'migrate',
+  'plans', 'stale', 'actionable', 'index', 'pickup', 'finish', 'status', 'archive', 'bulk', 'touch', 'doctor', 'lint', 'rename', 'migrate',
   'fix-refs', 'notion', 'export', 'summary', 'watch', 'diff', 'init', 'new', 'completions',
 ];
 
@@ -32,6 +32,8 @@ const COMMAND_FLAGS = {
   plans: ['--status', '--json', '--sort', '--limit', '--all', '--stale', '--has-next-step'],
   stale: ['--json', '--sort', '--limit', '--all'],
   actionable: ['--json', '--sort', '--limit', '--all'],
+  pickup: ['--json'],
+  finish: ['--json'],
   status: [],
   archive: [],
   doctor: [],

package/src/doctor.mjs

@@ -4,7 +4,8 @@ import { runTouch } from './lifecycle.mjs';
 import { buildIndex } from './index.mjs';
 import { renderIndexFile, writeIndex } from './index-file.mjs';
 import { renderCheck } from './render.mjs';
-import { bold } from './color.mjs';
+import { bold, dim, green, yellow } from './color.mjs';
+import { scaffoldClaudeCommands } from './claude-commands.mjs';
 
 export function runDoctor(argv, config, opts = {}) {
   const { dryRun } = opts;
@@ -34,8 +35,21 @@ export function runDoctor(argv, config, opts = {}) {
     }
   }
 
-  // Step 5: Show remaining check
-  process.stdout.write('\n' + bold('5. Remaining issues:') + '\n');
+  // Step 5: Refresh Claude Code commands
+  const claudeResults = dryRun ? [] : scaffoldClaudeCommands(config.repoRoot, config);
+  if (claudeResults.some(r => r.action !== 'current' && r.action !== 'skipped')) {
+    process.stdout.write('\n' + bold('5. Claude Code commands:') + '\n');
+    for (const r of claudeResults) {
+      if (r.action === 'updated') {
+        process.stdout.write(`${green('Updated')} .claude/commands/${r.name} (v${r.from} → v${r.to})\n`);
+      } else if (r.action === 'created') {
+        process.stdout.write(`${green('Created')} .claude/commands/${r.name}\n`);
+      }
+    }
+  }
+
+  // Step 6: Show remaining check
+  process.stdout.write('\n' + bold('6. Remaining issues:') + '\n');
   const freshIndex = buildIndex(config);
   process.stdout.write(renderCheck(freshIndex, config));
 }

package/src/index.mjs

@@ -5,6 +5,7 @@ import { extractFirstHeading, extractSummary, extractStatusSnapshot, extractNext
 import { asString, normalizeStringList, normalizeBlockers, mergeUniqueStrings, toRepoPath, warn } from './util.mjs';
 import { validateDoc, checkBidirectionalReferences, checkGitStaleness, computeDaysSinceUpdate, computeIsStale, computeChecklistCompletionRate } from './validate.mjs';
 import { checkIndex } from './index-file.mjs';
+import { checkClaudeCommands } from './claude-commands.mjs';
 
 export function buildIndex(config) {
   const docs = collectDocFiles(config).map(f => parseDocFile(f, config));
@@ -70,6 +71,9 @@ export function buildIndex(config) {
   const gitWarnings = checkGitStaleness(transformedDocs, config);
   warnings.push(...gitWarnings);
 
+  const claudeWarnings = checkClaudeCommands(config.repoRoot);
+  warnings.push(...claudeWarnings);
+
   return {
     generatedAt: new Date().toISOString(),
     docs: transformedDocs,

package/src/init.mjs

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { green, dim } from './color.mjs';
+import { scaffoldClaudeCommands } from './claude-commands.mjs';
 
 const STARTER_CONFIG = `// dotmd.config.mjs — document management configuration
 // All exports are optional. See dotmd.config.example.mjs for full reference.
@@ -103,7 +104,7 @@ function generateDetectedConfig(scan, rootPath) {
   return lines.join('\n');
 }
 
-export function runInit(cwd) {
+export function runInit(cwd, config) {
   const configPath = path.join(cwd, 'dotmd.config.mjs');
   const docsDir = path.join(cwd, 'docs');
   const indexPath = path.join(docsDir, 'docs.md');
@@ -137,6 +138,18 @@ export function runInit(cwd) {
     process.stdout.write(`  ${green('create')}  docs/docs.md\n`);
   }
 
+  // Claude Code integration — auto-detect .claude/ directory
+  if (config) {
+    const results = scaffoldClaudeCommands(cwd, config);
+    for (const r of results) {
+      if (r.action === 'created') {
+        process.stdout.write(`  ${green('create')}  .claude/commands/${r.name}\n`);
+      } else if (r.action === 'current') {
+        process.stdout.write(`  ${dim('current')} .claude/commands/${r.name}\n`);
+      }
+    }
+  }
+
   process.stdout.write(`\nReady. Create your first doc:\n`);
   process.stdout.write(`  dotmd new my-doc\n`);
   process.stdout.write(`  dotmd list\n\n`);

package/src/lifecycle.mjs

@@ -119,6 +119,118 @@ export async function runStatus(argv, config, opts = {}) {
   }); } catch (err) { warn(`Hook 'onStatusChange' threw: ${err.message}`); }
 }
 
+export async function runPickup(argv, config, opts = {}) {
+  const { dryRun } = opts;
+  const json = argv.includes('--json');
+  let input = argv.find(a => !a.startsWith('-'));
+
+  // Interactive: pick from active plans
+  if (!input) {
+    if (!isInteractive()) die('Usage: dotmd pickup <file>');
+    const index = buildIndex(config);
+    const active = index.docs.filter(d => d.type === 'plan' && (d.status === 'active' || d.status === 'planned'));
+    if (active.length === 0) die('No active or planned plans to pick up.');
+    const choice = await promptChoice('Pick a plan:', active.map(d => `${d.title} (${d.status}) — ${d.path}`));
+    if (!choice) die('No plan selected.');
+    const idx = active.findIndex((_, i) => choice === `${active[i].title} (${active[i].status}) — ${active[i].path}`);
+    if (idx === -1) die('No plan selected.');
+    input = active[idx].path;
+  }
+
+  const filePath = resolveDocPath(input, config);
+  if (!filePath) die(`File not found: ${input}`);
+
+  const raw = readFileSync(filePath, 'utf8');
+  const { frontmatter: fmRaw, body } = extractFrontmatter(raw);
+  const parsedFm = parseSimpleFrontmatter(fmRaw);
+  const docType = asString(parsedFm.type) ?? null;
+  const oldStatus = asString(parsedFm.status);
+  const title = asString(parsedFm.title) ?? path.basename(filePath, '.md');
+  const repoPath = toRepoPath(filePath, config.repoRoot);
+
+  if (docType && docType !== 'plan') warn(`${repoPath} has type '${docType}', not 'plan'.`);
+
+  if (oldStatus === 'in-session') die(`Already in-session — another Claude instance may be working on this.\n  ${repoPath}`);
+  if (oldStatus === 'blocked') {
+    const blockers = parsedFm.blockers ? (Array.isArray(parsedFm.blockers) ? parsedFm.blockers.join(', ') : String(parsedFm.blockers)) : 'unknown';
+    die(`Plan is blocked: ${blockers}\n  ${repoPath}`);
+  }
+  const pickupable = new Set(['active', 'planned']);
+  if (oldStatus && !pickupable.has(oldStatus)) die(`Cannot pick up a plan with status '${oldStatus}'. Must be active or planned.\n  ${repoPath}`);
+
+  const today = new Date().toISOString().slice(0, 10);
+
+  if (dryRun) {
+    process.stderr.write(`${dim('[dry-run]')} Would update: status: ${oldStatus} → in-session, updated: ${today}\n`);
+  } else {
+    updateFrontmatter(filePath, { status: 'in-session', updated: today });
+  }
+
+  if (json) {
+    process.stdout.write(JSON.stringify({ path: repoPath, oldStatus, newStatus: 'in-session', title, body: body?.trim() ?? '' }, null, 2) + '\n');
+  } else {
+    process.stderr.write(`${green('▶ Picked up')}: ${repoPath} (${oldStatus} → in-session)\n\n`);
+    if (body?.trim()) process.stdout.write(body.trim() + '\n');
+  }
+
+  try { config.hooks.onPickup?.({ path: repoPath, oldStatus, newStatus: 'in-session' }); } catch (err) { warn(`Hook 'onPickup' threw: ${err.message}`); }
+}
+
+export async function runFinish(argv, config, opts = {}) {
+  const { dryRun } = opts;
+  const json = argv.includes('--json');
+  const positional = argv.filter(a => !a.startsWith('-'));
+  let input = positional[0];
+  const targetStatus = positional[1] ?? 'done';
+
+  if (!['done', 'active'].includes(targetStatus)) die(`Invalid finish status: ${targetStatus}. Use 'done' or 'active'.`);
+
+  // Interactive: pick from in-session plans
+  if (!input) {
+    if (!isInteractive()) die('Usage: dotmd finish <file> [done|active]');
+    const index = buildIndex(config);
+    const inSession = index.docs.filter(d => d.status === 'in-session');
+    if (inSession.length === 0) die('No plans currently in-session.');
+    if (inSession.length === 1) {
+      input = inSession[0].path;
+      process.stderr.write(`${dim(`Auto-selected: ${input}`)}\n`);
+    } else {
+      const choice = await promptChoice('Finish which plan:', inSession.map(d => `${d.title} — ${d.path}`));
+      if (!choice) die('No plan selected.');
+      const idx = inSession.findIndex((_, i) => choice === `${inSession[i].title} — ${inSession[i].path}`);
+      if (idx === -1) die('No plan selected.');
+      input = inSession[idx].path;
+    }
+  }
+
+  const filePath = resolveDocPath(input, config);
+  if (!filePath) die(`File not found: ${input}`);
+
+  const raw = readFileSync(filePath, 'utf8');
+  const { frontmatter: fmRaw } = extractFrontmatter(raw);
+  const parsedFm = parseSimpleFrontmatter(fmRaw);
+  const oldStatus = asString(parsedFm.status);
+  const repoPath = toRepoPath(filePath, config.repoRoot);
+
+  if (oldStatus !== 'in-session') die(`Plan is not in-session (current: ${oldStatus}).\n  ${repoPath}`);
+
+  const today = new Date().toISOString().slice(0, 10);
+
+  if (dryRun) {
+    process.stderr.write(`${dim('[dry-run]')} Would update: status: in-session → ${targetStatus}, updated: ${today}\n`);
+  } else {
+    updateFrontmatter(filePath, { status: targetStatus, updated: today });
+  }
+
+  if (json) {
+    process.stdout.write(JSON.stringify({ path: repoPath, oldStatus, newStatus: targetStatus }, null, 2) + '\n');
+  } else {
+    process.stdout.write(`${green('✓ Finished')}: ${repoPath} (in-session → ${targetStatus})\n`);
+  }
+
+  try { config.hooks.onFinish?.({ path: repoPath, oldStatus, newStatus: targetStatus }); } catch (err) { warn(`Hook 'onFinish' threw: ${err.message}`); }
+}
+
 export function runArchive(argv, config, opts = {}) {
   const { dryRun } = opts;
   const input = argv[0];