mdboard 2.1.2 → 2.1.3

package/bin.js

@@ -81,6 +81,8 @@ if (command === 'create') {
   handleList(resolveProjectDir(args), args.slice(1));
 } else if (command === 'preset') {
   require('./src/cli/preset').run(args.slice(1));
+} else if (command === 'agentdocs') {
+  handleAgentDocs();
 } else if (command === 'config') {
   require('./src/cli/config').run(args.slice(1));
   // readline keeps process alive; config.js calls process.exit(0) when done
@@ -96,6 +98,65 @@ if (command === 'create') {
   process.exit(1);
 }
 
+// --- Agent docs handler ---
+
+function handleAgentDocs() {
+  const configEngine = require('./src/core/config');
+  const agentdocs = require('./src/cli/agentdocs');
+  const fs = require('fs');
+  const readline = require('readline');
+
+  const projectDir = process.cwd();
+  const projectMdboard = path.join(projectDir, 'project', 'mdboard.json');
+
+  if (!fs.existsSync(projectMdboard)) {
+    console.error('\n  Error: no project found. Run `mdboard init` first.\n');
+    process.exit(1);
+  }
+
+  const cfg = configEngine.loadConfig(projectDir);
+  const preset = cfg._preset || configEngine.DEFAULT_PRESET;
+
+  // Read project name from PROJECT.md frontmatter
+  let projectName = path.basename(projectDir);
+  try {
+    const projMd = fs.readFileSync(path.join(projectDir, 'project', 'PROJECT.md'), 'utf-8');
+    const nameMatch = projMd.match(/^name:\s*"?([^"\n]+)"?/m);
+    if (nameMatch) projectName = nameMatch[1].trim();
+  } catch (e) { /* use directory name */ }
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  console.log('');
+  console.log('  Generate AI agent context files?');
+  console.log('    1. Both CLAUDE.md + AGENTS.md  (recommended)');
+  console.log('    2. CLAUDE.md only              (Claude Code)');
+  console.log('    3. AGENTS.md only              (Cursor, Copilot, etc.)');
+  rl.question('  Choice [1]: ', function (answer) {
+    rl.close();
+    const choice = (answer || '').trim() || '1';
+    let targets;
+    if (choice === '2') targets = ['claude'];
+    else if (choice === '3') targets = ['agents'];
+    else targets = ['claude', 'agents'];
+
+    // Check which files exist before writing
+    const existsBefore = {};
+    for (const t of targets) {
+      const fname = t === 'claude' ? 'CLAUDE.md' : 'AGENTS.md';
+      existsBefore[fname] = fs.existsSync(path.join(projectDir, fname));
+    }
+
+    const written = agentdocs.generate(projectDir, cfg, preset, projectName, targets);
+    console.log('');
+    for (const p of written) {
+      const fname = path.basename(p);
+      console.log('  ' + (existsBefore[fname] ? 'Updated' : 'Created') + ': ' + fname);
+    }
+    console.log('');
+    process.exit(0);
+  });
+}
+
 // --- Cache handler ---
 
 function handleCache() {
@@ -184,5 +245,5 @@ function printHelp() {
     entityExamples = '\n  CRUD examples:\n    mdboard create <entity> "title" [--flags]\n    mdboard update <entity> <id> --field value\n    mdboard delete <entity> <id>\n    mdboard list <entity>\n';
   }
 
-  console.log('\n  mdboard — Git-based project management dashboard\n\n  Usage:\n    mdboard                    Start the dashboard server\n    mdboard init [name]        Scaffold a new workspace\n    mdboard create <entity>    Create an entity\n    mdboard update <entity>    Update an entity\n    mdboard delete <entity>    Delete an entity\n    mdboard list <entity>      List entities\n    mdboard status             Generate status report\n    mdboard preset             Create & manage presets (scrum, kanban)\n    mdboard config             Setup preferences & AI skill\n    mdboard skill              Install AI skill to IDE/agent\n    mdboard history list|clean  Manage project switch history\n    mdboard cache list|clean   Manage remote source cache\n    mdboard --version          Print version\n    mdboard --help             Show this help\n' + entityExamples + '\n  Options:\n    --project <path>           Workspace root (default: cwd)\n    --preset <name>            Methodology preset (shape-up, scrum, kanban)\n    --config <path>            Path to config directory\n    --port <number>            Server port (default: 3333)\n    --workspace <path>         Path to workspace.json\n');
+  console.log('\n  mdboard — Git-based project management dashboard\n\n  Usage:\n    mdboard                    Start the dashboard server\n    mdboard init [name]        Scaffold a new workspace\n    mdboard create <entity>    Create an entity\n    mdboard update <entity>    Update an entity\n    mdboard delete <entity>    Delete an entity\n    mdboard list <entity>      List entities\n    mdboard status             Generate status report\n    mdboard preset             Create & manage presets (scrum, kanban)\n    mdboard config             Setup preferences & AI skill\n    mdboard skill              Install AI skill to IDE/agent\n    mdboard agentdocs          Generate CLAUDE.md / AGENTS.md context\n    mdboard history list|clean  Manage project switch history\n    mdboard cache list|clean   Manage remote source cache\n    mdboard --version          Print version\n    mdboard --help             Show this help\n' + entityExamples + '\n  Options:\n    --project <path>           Workspace root (default: cwd)\n    --preset <name>            Methodology preset (shape-up, scrum, kanban)\n    --config <path>            Path to config directory\n    --port <number>            Server port (default: 3333)\n    --workspace <path>         Path to workspace.json\n');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdboard",
-  "version": "2.1.2",
+  "version": "2.1.3",
   "description": "Git-based project management dashboard. Reads markdown files with YAML frontmatter and serves a visual kanban board, table, milestones, and metrics views.",
   "main": "./src/server/server.js",
   "bin": {

package/src/cli/agentdocs.js

@@ -0,0 +1,311 @@
+/**
+ * mdboard agentdocs — Generate CLAUDE.md / AGENTS.md context for AI agents
+ *
+ * Dynamically builds project management documentation from the loaded preset
+ * configuration so that any AI agent always has context about how to use mdboard.
+ *
+ * Called during `mdboard init` and also available as `mdboard agentdocs`.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const configEngine = require('../core/config');
+
+const SECTION_START = '<!-- mdboard:start -->';
+const SECTION_END = '<!-- mdboard:end -->';
+
+// ---------------------------------------------------------------------------
+// Content generation
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the full markdown section from config.
+ * @param {object} cfg - Loaded config from configEngine.loadConfig()
+ * @param {string} preset - Preset name (e.g. "shape-up")
+ * @param {string} projectName - Workspace/project name
+ * @returns {string}
+ */
+function generateSection(cfg, preset, projectName) {
+  const lines = [];
+
+  lines.push(SECTION_START);
+  lines.push('');
+  lines.push('## mdboard — Project Management');
+  lines.push('');
+  lines.push('This project uses **mdboard** for project management. All board files live in `project/`.');
+  lines.push('');
+
+  // --- Config summary ---
+  lines.push('### Configuration');
+  lines.push('');
+  lines.push('- **Project**: ' + projectName);
+  lines.push('- **Preset**: ' + preset);
+  lines.push('- **Methodology**: ' + (cfg.entities && cfg.entities.methodology || preset));
+  lines.push('- **Root directory**: `project/`');
+  lines.push('');
+
+  // --- Hierarchy ---
+  const hierarchy = (cfg.structure && cfg.structure.hierarchy) || {};
+  const standalone = (cfg.structure && cfg.structure.standalone) || {};
+  const hierarchyChain = buildHierarchyChain(hierarchy);
+  const standaloneNames = Object.keys(standalone);
+
+  lines.push('### Entity hierarchy');
+  lines.push('');
+  if (hierarchyChain.length > 0) {
+    const entities = cfg.entities && cfg.entities.entities || {};
+    const chainLabels = hierarchyChain.map(t => {
+      const e = entities[t];
+      return e ? e.singular : t;
+    });
+    lines.push('```');
+    lines.push(chainLabels.join(' > '));
+    lines.push('```');
+  } else {
+    lines.push('No hierarchy (flat structure).');
+  }
+  if (standaloneNames.length > 0) {
+    const entities = cfg.entities && cfg.entities.entities || {};
+    const labels = standaloneNames.map(t => {
+      const e = entities[t];
+      return e ? '**' + e.singular + '**' : '**' + t + '**';
+    });
+    lines.push('');
+    lines.push('Standalone entities: ' + labels.join(', '));
+  }
+  lines.push('');
+
+  // --- File structure ---
+  lines.push('### File structure');
+  lines.push('');
+  lines.push('```');
+  const tree = buildFileTree(hierarchy, standalone, cfg.entities && cfg.entities.entities || {});
+  lines.push('project/');
+  for (const line of tree) {
+    lines.push('  ' + line);
+  }
+  lines.push('```');
+  lines.push('');
+
+  // --- Frontmatter enums ---
+  lines.push('### Frontmatter values (strict enums)');
+  lines.push('');
+  const enumTable = buildEnumTable(cfg);
+  if (enumTable.length > 0) {
+    lines.push('| Entity | Field | Allowed values |');
+    lines.push('|--------|-------|----------------|');
+    for (const row of enumTable) {
+      lines.push('| ' + row.entity + ' | ' + row.field + ' | ' + row.values + ' |');
+    }
+  }
+  lines.push('');
+
+  // --- CLI commands ---
+  lines.push('### CLI commands');
+  lines.push('');
+  lines.push('Always use the CLI to create/update/delete entities. Never edit IDs or prefixes manually.');
+  lines.push('');
+  lines.push('```bash');
+
+  // Create commands
+  const allTypes = configEngine.getEntityTypes(cfg);
+  for (const type of allTypes) {
+    const entity = configEngine.getEntity(cfg, type);
+    if (!entity) continue;
+    const ancestors = configEngine.getAncestors(cfg, type);
+    const parentFlags = ancestors.map(a => '--' + a + ' <slug>').join(' ');
+    const cmd = 'mdboard create ' + type + ' "title"';
+    lines.push(cmd + (parentFlags ? ' ' + parentFlags : ''));
+  }
+  lines.push('');
+
+  // Update / list / delete
+  lines.push('# Update any field');
+  lines.push('mdboard update <type> <ID> --<field> <value>');
+  lines.push('');
+  lines.push('# List and delete');
+  lines.push('mdboard list <type>');
+  lines.push('mdboard delete <type> <ID>');
+  lines.push('');
+
+  // System commands
+  lines.push('# System');
+  lines.push('mdboard status    # Project status report');
+  lines.push('```');
+  lines.push('');
+
+  // --- Rules ---
+  lines.push('### Rules');
+  lines.push('');
+  lines.push('- Parent flags (`--cycle`, `--bet`, etc.) use **slugs** (directory names), not IDs.');
+  lines.push('- Status/enum values are **strict** — only use the values listed above.');
+  lines.push('- Use `mdboard status` to get a quick summary of project state.');
+  lines.push('- Do not manually edit entity IDs or prefixes.');
+  lines.push('');
+  lines.push(SECTION_END);
+
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Walk hierarchy to produce an ordered array of type names.
+ * e.g. ["cycle", "bet", "scope", "task"]
+ */
+function buildHierarchyChain(hierarchy) {
+  const chain = [];
+  function walk(node) {
+    for (const [type, def] of Object.entries(node)) {
+      chain.push(type);
+      if (def.children) walk(def.children);
+    }
+  }
+  walk(hierarchy);
+  return chain;
+}
+
+/**
+ * Build a visual file tree array from hierarchy + standalone.
+ */
+function buildFileTree(hierarchy, standalone, entities) {
+  const lines = [];
+
+  function walkTree(node, indent) {
+    for (const [type, def] of Object.entries(node)) {
+      const entity = entities[type];
+      const isDir = entity && entity.file === 'README.md';
+      const isFile = entity && entity.file === 'PREFIX-NNN.md';
+
+      lines.push(indent + def.dir + '/');
+      if (isDir) {
+        // Directory-per-entity: show slug pattern
+        const slug = type + '-nnn/';
+        lines.push(indent + '  ' + slug);
+        if (def.children) {
+          walkTree(def.children, indent + '    ');
+        }
+      } else if (isFile && def.children) {
+        // File-per-entity but has children (unusual, handle anyway)
+        lines.push(indent + '  ' + (entity.prefix || type.toUpperCase()) + '-NNN.md');
+        walkTree(def.children, indent + '  ');
+      } else if (isFile) {
+        lines.push(indent + '  ' + (entity.prefix || type.toUpperCase()) + '-NNN.md');
+      }
+    }
+  }
+
+  walkTree(hierarchy, '');
+
+  for (const [type, def] of Object.entries(standalone)) {
+    const entity = entities[type];
+    lines.push(def.dir + '/');
+    if (entity && entity.file === 'PREFIX-NNN.md') {
+      lines.push('  ' + (entity.prefix || type.toUpperCase()) + '-NNN.md');
+    }
+  }
+
+  return lines;
+}
+
+/**
+ * Build rows for the enum values table.
+ */
+function buildEnumTable(cfg) {
+  const rows = [];
+  const types = configEngine.getEntityTypes(cfg);
+
+  for (const type of types) {
+    const entity = configEngine.getEntity(cfg, type);
+    const fields = configEngine.getFields(cfg, type);
+    if (!entity || !fields) continue;
+
+    for (const [fieldName, fieldDef] of Object.entries(fields)) {
+      if (fieldDef.type !== 'enum') continue;
+      const values = fieldDef.values.map(v => '`' + v.key + '`').join(', ');
+      rows.push({
+        entity: entity.singular,
+        field: fieldName,
+        values: values
+      });
+    }
+  }
+
+  return rows;
+}
+
+// ---------------------------------------------------------------------------
+// File writing (create or append)
+// ---------------------------------------------------------------------------
+
+/**
+ * Write or update agent docs in a target file.
+ * If the file exists and already has an mdboard section, replace it.
+ * If the file exists without a section, append it.
+ * If the file doesn't exist, create it.
+ *
+ * @param {string} filePath - Absolute path to the target file
+ * @param {string} section - Generated markdown section
+ */
+function writeAgentDoc(filePath, section) {
+  if (fs.existsSync(filePath)) {
+    let content = fs.readFileSync(filePath, 'utf-8');
+    const startIdx = content.indexOf(SECTION_START);
+    const endIdx = content.indexOf(SECTION_END);
+
+    if (startIdx !== -1 && endIdx !== -1) {
+      // Replace existing section
+      content = content.substring(0, startIdx) + section + content.substring(endIdx + SECTION_END.length);
+    } else {
+      // Append
+      content = content.trimEnd() + '\n\n' + section + '\n';
+    }
+
+    fs.writeFileSync(filePath, content, 'utf-8');
+  } else {
+    // Create new file
+    fs.writeFileSync(filePath, section + '\n', 'utf-8');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate and write agent documentation files.
+ *
+ * @param {string} cwd - Working directory (repo root)
+ * @param {object} cfg - Loaded config
+ * @param {string} preset - Preset name
+ * @param {string} projectName - Project/workspace name
+ * @param {string[]} targets - Which files to generate: ['claude', 'agents']
+ * @returns {string[]} - Paths of files written
+ */
+function generate(cwd, cfg, preset, projectName, targets) {
+  const section = generateSection(cfg, preset, projectName);
+  const written = [];
+
+  for (const target of targets) {
+    let filename;
+    if (target === 'claude') {
+      filename = 'CLAUDE.md';
+    } else if (target === 'agents') {
+      filename = 'AGENTS.md';
+    } else {
+      continue;
+    }
+
+    const filePath = path.join(cwd, filename);
+    writeAgentDoc(filePath, section);
+    written.push(filePath);
+  }
+
+  return written;
+}
+
+module.exports = { generate, generateSection, writeAgentDoc, SECTION_START, SECTION_END };

package/src/cli/init.js

@@ -14,6 +14,7 @@ const fs = require('fs');
 const path = require('path');
 const readline = require('readline');
 const configEngine = require('../core/config');
+const agentdocs = require('./agentdocs');
 
 const cwd = process.cwd();
 const projectPath = path.join(cwd, 'project');
@@ -50,17 +51,39 @@ if (!fs.existsSync(presetDir)) {
 }
 
 if (nameArg) {
-  scaffold(nameArg);
+  askAgentTargets(function (targets) { scaffold(nameArg, targets); });
 } else {
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   rl.question('  Workspace name: ', function (answer) {
     rl.close();
     const name = answer.trim() || path.basename(cwd);
-    scaffold(name);
+    askAgentTargets(function (targets) { scaffold(name, targets); });
   });
 }
 
-function scaffold(name) {
+/**
+ * Prompt user to select which agent doc files to generate.
+ * @param {function} cb - Callback receiving string[] of targets
+ */
+function askAgentTargets(cb) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  console.log('');
+  console.log('  Generate AI agent context files?');
+  console.log('    1. Both CLAUDE.md + AGENTS.md  (recommended)');
+  console.log('    2. CLAUDE.md only              (Claude Code)');
+  console.log('    3. AGENTS.md only              (Cursor, Copilot, etc.)');
+  console.log('    4. Skip');
+  rl.question('  Choice [1]: ', function (answer) {
+    rl.close();
+    const choice = (answer || '').trim() || '1';
+    if (choice === '2') return cb(['claude']);
+    if (choice === '3') return cb(['agents']);
+    if (choice === '4') return cb([]);
+    return cb(['claude', 'agents']);
+  });
+}
+
+function scaffold(name, agentTargets) {
   // Load preset config
   const cfg = configEngine.loadConfig(null);
   const structure = cfg.structure || {};
@@ -119,6 +142,14 @@ function scaffold(name) {
   console.log('    project/mdboard.css');
   console.log('    workspace.json');
 
+  // Generate AI agent documentation files
+  if (agentTargets && agentTargets.length > 0) {
+    const written = agentdocs.generate(cwd, cfg, preset, name, agentTargets);
+    for (const p of written) {
+      console.log('    ' + path.basename(p));
+    }
+  }
+
   console.log('\n  Next steps:');
   console.log('    1. Edit project/PROJECT.md with your project details');