claude-autopm 1.25.0 → 1.27.0

package/autopm/.claude/lib/frontmatter.js

@@ -0,0 +1,224 @@
+/**
+ * Frontmatter Utilities
+ *
+ * Provides utilities for parsing, validating, and manipulating YAML frontmatter
+ * in markdown files. Used by Local Mode for PRD, Epic, and Task management.
+ *
+ * Documentation Source: Context7 - /eemeli/yaml
+ * Trust Score: 9.4, 100 code snippets
+ */
+
+const { parse, stringify } = require('yaml');
+const fs = require('fs').promises;
+
+/**
+ * Parse YAML frontmatter from markdown content
+ *
+ * @param {string} content - Markdown content with optional frontmatter
+ * @returns {{frontmatter: Object, body: string}} Parsed frontmatter and body
+ *
+ * @example
+ * const { frontmatter, body } = parseFrontmatter(content);
+ * console.log(frontmatter.id); // 'task-001'
+ */
+function parseFrontmatter(content) {
+  if (!content || typeof content !== 'string') {
+    return { frontmatter: {}, body: content || '' };
+  }
+
+  // Check for frontmatter delimiters
+  // Handles both empty (---\n---\n) and non-empty frontmatter
+  const frontmatterRegex = /^---\r?\n([\s\S]*?)^---\r?\n?([\s\S]*)$/m;
+  const match = content.match(frontmatterRegex);
+
+  if (!match) {
+    // No frontmatter found, return entire content as body
+    return { frontmatter: {}, body: content };
+  }
+
+  const [, yamlContent, body] = match;
+
+  // Handle empty frontmatter
+  if (!yamlContent.trim()) {
+    return { frontmatter: {}, body: body || '' };
+  }
+
+  try {
+    // Parse YAML using Context7-documented pattern
+    const frontmatter = parse(yamlContent);
+    return {
+      frontmatter: frontmatter || {},
+      body: body || ''
+    };
+  } catch (error) {
+    // Invalid YAML syntax
+    throw new Error(`Invalid YAML syntax in frontmatter: ${error.message}`);
+  }
+}
+
+/**
+ * Stringify frontmatter and body into markdown format
+ *
+ * @param {Object} data - Frontmatter data object
+ * @param {string} body - Markdown body content
+ * @returns {string} Complete markdown with frontmatter
+ *
+ * @example
+ * const markdown = stringifyFrontmatter({ id: 'task-001' }, 'Body content');
+ */
+function stringifyFrontmatter(data, body = '') {
+  // Handle empty frontmatter - don't add empty object literal
+  if (!data || Object.keys(data).length === 0) {
+    return `---\n---\n${body}`;
+  }
+
+  // Use Context7-documented stringify with default options
+  const yamlContent = stringify(data);
+
+  // Format: ---\nYAML\n---\nBODY
+  return `---\n${yamlContent}---\n${body}`;
+}
+
+/**
+ * Update frontmatter fields in a file
+ *
+ * Supports nested field updates using dot notation:
+ * - 'status' → updates top-level field
+ * - 'providers.github.owner' → updates nested field
+ *
+ * @param {string} filePath - Path to markdown file
+ * @param {Object} updates - Fields to update (supports dot notation for nested)
+ * @returns {Promise<void>}
+ *
+ * @example
+ * await updateFrontmatter('task.md', { status: 'done', 'metadata.updated': '2025-10-05' });
+ */
+async function updateFrontmatter(filePath, updates) {
+  // Read existing file
+  const content = await fs.readFile(filePath, 'utf8');
+
+  // Parse current frontmatter
+  const { frontmatter, body } = parseFrontmatter(content);
+
+  // Apply updates (supports nested fields via dot notation)
+  const updatedFrontmatter = { ...frontmatter };
+
+  for (const [key, value] of Object.entries(updates)) {
+    if (key.includes('.')) {
+      // Nested field update: 'providers.github.owner'
+      const keys = key.split('.');
+      let current = updatedFrontmatter;
+
+      for (let i = 0; i < keys.length - 1; i++) {
+        const k = keys[i];
+        if (!current[k] || typeof current[k] !== 'object') {
+          current[k] = {};
+        }
+        current = current[k];
+      }
+
+      current[keys[keys.length - 1]] = value;
+    } else {
+      // Top-level field update
+      updatedFrontmatter[key] = value;
+    }
+  }
+
+  // Write updated content
+  const updated = stringifyFrontmatter(updatedFrontmatter, body);
+  await fs.writeFile(filePath, updated, 'utf8');
+}
+
+/**
+ * Validate frontmatter against schema
+ *
+ * Schema format:
+ * {
+ *   required: ['id', 'title', 'status'],
+ *   fields: {
+ *     id: { type: 'string', pattern: /^task-\d+$/ },
+ *     status: { type: 'string', enum: ['pending', 'in_progress', 'completed'] },
+ *     tasks_total: { type: 'number' }
+ *   }
+ * }
+ *
+ * @param {Object} data - Frontmatter data to validate
+ * @param {Object} schema - Validation schema
+ * @returns {{valid: boolean, errors: string[]}} Validation result
+ *
+ * @example
+ * const result = validateFrontmatter(data, schema);
+ * if (!result.valid) console.error(result.errors);
+ */
+function validateFrontmatter(data, schema) {
+  const errors = [];
+
+  // Check required fields
+  if (schema.required) {
+    for (const field of schema.required) {
+      if (!(field in data)) {
+        errors.push(`Missing required field: ${field}`);
+      }
+    }
+  }
+
+  // Check field types and constraints
+  if (schema.fields) {
+    for (const [field, constraints] of Object.entries(schema.fields)) {
+      const value = data[field];
+
+      // Skip validation if field is not present and not required
+      if (value === undefined) {
+        continue;
+      }
+
+      // Type validation
+      if (constraints.type) {
+        const actualType = Array.isArray(value) ? 'array' : typeof value;
+        if (actualType !== constraints.type) {
+          errors.push(`Field '${field}' must be of type ${constraints.type}, got ${actualType}`);
+          continue; // Skip other validations if type is wrong
+        }
+      }
+
+      // Enum validation
+      if (constraints.enum && !constraints.enum.includes(value)) {
+        errors.push(`Field '${field}' must be one of [${constraints.enum.join(', ')}], got '${value}' (invalid enum value)`);
+      }
+
+      // Pattern validation (for strings)
+      if (constraints.pattern && typeof value === 'string') {
+        if (!constraints.pattern.test(value)) {
+          errors.push(`Field '${field}' does not match required pattern (pattern validation failed)`);
+        }
+      }
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+
+/**
+ * Strip frontmatter and return only body content
+ *
+ * @param {string} content - Markdown content with optional frontmatter
+ * @returns {string} Body content only
+ *
+ * @example
+ * const body = stripBody(content);
+ */
+function stripBody(content) {
+  const { body } = parseFrontmatter(content);
+  return body;
+}
+
+module.exports = {
+  parseFrontmatter,
+  stringifyFrontmatter,
+  updateFrontmatter,
+  validateFrontmatter,
+  stripBody
+};

package/autopm/.claude/lib/task-utils.js

@@ -0,0 +1,64 @@
+/**
+ * Task Utilities
+ *
+ * Shared utilities for task ID generation and formatting.
+ * Ensures consistency across all task-related operations.
+ *
+ * Usage:
+ *   const { generateTaskId, generateTaskNumber, generateTaskFilename } = require('./task-utils');
+ *
+ *   const taskId = generateTaskId('epic-001', 5);  // 'task-epic-001-005'
+ *   const taskNum = generateTaskNumber(5);          // '005'
+ *   const filename = generateTaskFilename(5);       // 'task-005.md'
+ */
+
+/**
+ * Generate zero-padded task number (001, 002, etc.)
+ *
+ * @param {number} index - Task index (1-based)
+ * @returns {string} Zero-padded task number
+ */
+function generateTaskNumber(index) {
+  return String(index).padStart(3, '0');
+}
+
+/**
+ * Generate full task ID with epic prefix
+ *
+ * @param {string} epicId - Epic ID (e.g., 'epic-001')
+ * @param {number} index - Task index (1-based)
+ * @returns {string} Full task ID (e.g., 'task-epic-001-005')
+ */
+function generateTaskId(epicId, index) {
+  const taskNum = generateTaskNumber(index);
+  return `task-${epicId}-${taskNum}`;
+}
+
+/**
+ * Generate short task ID without epic prefix (for dependency analyzer)
+ *
+ * @param {number} index - Task index (1-based)
+ * @returns {string} Short task ID (e.g., 'task-005')
+ */
+function generateShortTaskId(index) {
+  const taskNum = generateTaskNumber(index);
+  return `task-${taskNum}`;
+}
+
+/**
+ * Generate task filename
+ *
+ * @param {number} index - Task index (1-based)
+ * @returns {string} Task filename (e.g., 'task-005.md')
+ */
+function generateTaskFilename(index) {
+  const taskNum = generateTaskNumber(index);
+  return `task-${taskNum}.md`;
+}
+
+module.exports = {
+  generateTaskNumber,
+  generateTaskId,
+  generateShortTaskId,
+  generateTaskFilename
+};

package/autopm/.claude/scripts/pm-epic-decompose-local.js

@@ -0,0 +1,158 @@
+/**
+ * Epic Decomposition - Local Mode
+ *
+ * AI-powered decomposition of epics into right-sized tasks (4-8h each).
+ * Generates task files with frontmatter, dependencies, and acceptance criteria.
+ *
+ * Usage:
+ *   const { decomposeLocalEpic } = require('./pm-epic-decompose-local');
+ *
+ *   const result = await decomposeLocalEpic('epic-001', {
+ *     aiProvider: new OpenAIProvider(),
+ *     maxTasks: 10
+ *   });
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+const { showLocalEpic } = require('./pm-epic-show-local');
+const { updateLocalEpic } = require('./pm-epic-update-local');
+const { stringifyFrontmatter } = require('../lib/frontmatter');
+const { TaskGenerator } = require('../lib/ai-task-generator');
+const { analyzeDependencies } = require('../lib/dependency-analyzer');
+const { generateTaskId, generateTaskNumber, generateTaskFilename } = require('../lib/task-utils');
+
+/**
+ * Decompose epic into tasks using AI
+ *
+ * @param {string} epicId - Epic ID to decompose
+ * @param {Object} options - Decomposition options
+ * @param {Object} [options.aiProvider] - AI provider instance (for testing)
+ * @param {number} [options.maxTasks=15] - Maximum tasks to generate
+ * @param {boolean} [options.validateDependencies=false] - Validate dependency graph
+ * @returns {Promise<Object>} Decomposition result
+ */
+async function decomposeLocalEpic(epicId, options = {}) {
+  const {
+    aiProvider = null,
+    maxTasks = 15,
+    validateDependencies = false
+  } = options;
+
+  // 1. Load epic
+  const epic = await showLocalEpic(epicId);
+  const epicDir = path.dirname(epic.path);
+
+  // 2. Generate tasks using AI
+  const generator = new TaskGenerator(aiProvider);
+  const tasks = await generator.generate(epic.body, { maxTasks });
+
+  // Handle empty response
+  if (tasks.length === 0) {
+    return {
+      epicId,
+      tasksCreated: 0,
+      warning: 'No tasks generated by AI provider'
+    };
+  }
+
+  // 3. Validate dependencies if requested
+  if (validateDependencies) {
+    const analysis = analyzeDependencies(tasks);
+    if (analysis.hasCircularDependencies) {
+      throw new Error(
+        `Circular dependency detected: ${analysis.cycles.map(c => c.join(' -> ')).join(', ')}`
+      );
+    }
+  }
+
+  // 4. Create task files
+  const taskIds = [];
+  for (let i = 0; i < tasks.length; i++) {
+    const task = tasks[i];
+    const taskId = generateTaskId(epicId, i + 1);
+    const taskFilename = generateTaskFilename(i + 1);
+    const taskPath = path.join(epicDir, taskFilename);
+
+    // Build task frontmatter
+    const taskFrontmatter = {
+      id: taskId,
+      epic_id: epicId,
+      title: task.title,
+      status: 'pending',
+      priority: task.priority || 'medium',
+      estimated_hours: task.estimated_hours || 4,
+      dependencies: task.dependencies || [],
+      created: new Date().toISOString().split('T')[0]
+    };
+
+    // Build task body
+    const taskBody = buildTaskBody(task);
+
+    // Write task file
+    const taskContent = stringifyFrontmatter(taskFrontmatter, taskBody);
+    await fs.writeFile(taskPath, taskContent, 'utf8');
+
+    taskIds.push(taskId);
+  }
+
+  // 5. Update epic with task count
+  await updateLocalEpic(epicId, {
+    tasks_total: tasks.length,
+    tasks_completed: 0,
+    task_ids: taskIds
+  });
+
+  return {
+    epicId,
+    tasksCreated: tasks.length,
+    taskIds
+  };
+}
+
+/**
+ * Build task body content from AI-generated task
+ *
+ * @param {Object} task - Task object from AI
+ * @returns {string} Markdown body content
+ */
+function buildTaskBody(task) {
+  let body = `# ${task.title}\n\n`;
+
+  // Description
+  if (task.description) {
+    body += `## Description\n\n${task.description}\n\n`;
+  }
+
+  // Acceptance Criteria
+  body += `## Acceptance Criteria\n\n`;
+  if (task.acceptance_criteria && task.acceptance_criteria.length > 0) {
+    task.acceptance_criteria.forEach(criterion => {
+      body += `- [ ] ${criterion}\n`;
+    });
+  } else {
+    body += `- [ ] Implementation complete\n`;
+    body += `- [ ] Tests passing\n`;
+    body += `- [ ] Code reviewed\n`;
+  }
+
+  body += `\n`;
+
+  // Technical Notes (if provided)
+  if (task.technical_notes) {
+    body += `## Technical Notes\n\n${task.technical_notes}\n\n`;
+  }
+
+  // Dependencies
+  if (task.dependencies && task.dependencies.length > 0) {
+    body += `## Dependencies\n\n`;
+    task.dependencies.forEach(dep => {
+      body += `- ${dep}\n`;
+    });
+    body += `\n`;
+  }
+
+  return body.trim();
+}
+
+module.exports = { decomposeLocalEpic };

package/autopm/.claude/scripts/pm-epic-list-local.js

@@ -0,0 +1,103 @@
+/**
+ * List Local Epics
+ *
+ * Lists all epics in the local `.claude/epics/` directory
+ * with optional filtering by status or PRD ID.
+ *
+ * Usage:
+ *   const { listLocalEpics } = require('./pm-epic-list-local');
+ *
+ *   // List all epics
+ *   const epics = await listLocalEpics();
+ *
+ *   // Filter by status
+ *   const inProgress = await listLocalEpics({ status: 'in_progress' });
+ *
+ *   // Filter by PRD
+ *   const prdEpics = await listLocalEpics({ prd_id: 'prd-001' });
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+const { parseFrontmatter } = require('../lib/frontmatter');
+
+/**
+ * List all local epics with optional filtering
+ *
+ * @param {Object} options - Filter options
+ * @param {string} [options.status] - Filter by epic status (planning, in_progress, completed, etc.)
+ * @param {string} [options.prd_id] - Filter by PRD ID
+ * @returns {Promise<Array>} Array of epic objects with frontmatter
+ */
+async function listLocalEpics(options = {}) {
+  const basePath = process.cwd();
+  const epicsDir = path.join(basePath, '.claude', 'epics');
+
+  // Check if epics directory exists
+  try {
+    await fs.access(epicsDir);
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return []; // No epics directory = no epics
+    }
+    throw err;
+  }
+
+  // Read all epic directories
+  const dirs = await fs.readdir(epicsDir);
+  const epics = [];
+
+  // Process each epic directory
+  for (const dir of dirs) {
+    // Skip hidden directories and files
+    if (dir.startsWith('.')) continue;
+
+    const epicDir = path.join(epicsDir, dir);
+    const epicPath = path.join(epicDir, 'epic.md');
+
+    try {
+      // Check if it's a directory with epic.md
+      const stat = await fs.stat(epicDir);
+      if (!stat.isDirectory()) continue;
+
+      // Read and parse epic.md
+      const content = await fs.readFile(epicPath, 'utf8');
+      const { frontmatter } = parseFrontmatter(content);
+
+      // Only include valid epics with required fields
+      if (frontmatter && frontmatter.id) {
+        epics.push({
+          ...frontmatter,
+          directory: dir
+        });
+      }
+    } catch (err) {
+      // Skip invalid epic directories (missing epic.md, parse errors, etc.)
+      if (err.code !== 'ENOENT') {
+        console.warn(`Warning: Could not process epic in ${dir}:`, err.message);
+      }
+    }
+  }
+
+  // Apply filters
+  let filtered = epics;
+
+  if (options.status) {
+    filtered = filtered.filter(epic => epic.status === options.status);
+  }
+
+  if (options.prd_id) {
+    filtered = filtered.filter(epic => epic.prd_id === options.prd_id);
+  }
+
+  // Sort by creation date (newest first)
+  filtered.sort((a, b) => {
+    const dateA = new Date(a.created || 0);
+    const dateB = new Date(b.created || 0);
+    return dateB - dateA; // Descending order (newest first)
+  });
+
+  return filtered;
+}
+
+module.exports = { listLocalEpics };

package/autopm/.claude/scripts/pm-epic-show-local.js

@@ -0,0 +1,70 @@
+/**
+ * Show Local Epic
+ *
+ * Displays details of a specific epic including frontmatter,
+ * body content, and directory information.
+ *
+ * Usage:
+ *   const { showLocalEpic } = require('./pm-epic-show-local');
+ *
+ *   const epic = await showLocalEpic('epic-001');
+ *   console.log(epic.frontmatter.title);
+ *   console.log(epic.body);
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+const { parseFrontmatter } = require('../lib/frontmatter');
+
+/**
+ * Get epic details by ID
+ *
+ * @param {string} epicId - Epic ID to retrieve
+ * @returns {Promise<Object>} Epic object with frontmatter, body, and directory
+ * @throws {Error} If epic not found
+ */
+async function showLocalEpic(epicId) {
+  const basePath = process.cwd();
+  const epicsDir = path.join(basePath, '.claude', 'epics');
+
+  // Check if epics directory exists
+  try {
+    await fs.access(epicsDir);
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      throw new Error(`Epic not found: ${epicId} (epics directory does not exist)`);
+    }
+    throw err;
+  }
+
+  // Find epic directory by ID
+  const dirs = await fs.readdir(epicsDir);
+  const epicDir = dirs.find(dir => dir.startsWith(`${epicId}-`));
+
+  if (!epicDir) {
+    throw new Error(`Epic not found: ${epicId}`);
+  }
+
+  const epicDirPath = path.join(epicsDir, epicDir);
+  const epicPath = path.join(epicDirPath, 'epic.md');
+
+  // Read and parse epic file
+  try {
+    const content = await fs.readFile(epicPath, 'utf8');
+    const { frontmatter, body } = parseFrontmatter(content);
+
+    return {
+      frontmatter,
+      body,
+      directory: epicDir,
+      path: epicPath
+    };
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      throw new Error(`Epic not found: ${epicId} (epic.md missing in ${epicDir})`);
+    }
+    throw err;
+  }
+}
+
+module.exports = { showLocalEpic };

package/autopm/.claude/scripts/pm-epic-update-local.js

@@ -0,0 +1,56 @@
+/**
+ * Update Local Epic
+ *
+ * Updates epic frontmatter fields while preserving body content.
+ * Supports updating single or multiple fields at once.
+ *
+ * Usage:
+ *   const { updateLocalEpic } = require('./pm-epic-update-local');
+ *
+ *   // Update status
+ *   await updateLocalEpic('epic-001', { status: 'in_progress' });
+ *
+ *   // Update multiple fields
+ *   await updateLocalEpic('epic-001', {
+ *     status: 'completed',
+ *     tasks_completed: 5
+ *   });
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+const { parseFrontmatter, stringifyFrontmatter } = require('../lib/frontmatter');
+const { showLocalEpic } = require('./pm-epic-show-local');
+
+/**
+ * Update epic frontmatter fields
+ *
+ * @param {string} epicId - Epic ID to update
+ * @param {Object} updates - Fields to update in frontmatter
+ * @returns {Promise<Object>} Updated epic object
+ * @throws {Error} If epic not found
+ */
+async function updateLocalEpic(epicId, updates) {
+  // Get current epic
+  const epic = await showLocalEpic(epicId);
+
+  // Merge updates into frontmatter
+  const updatedFrontmatter = {
+    ...epic.frontmatter,
+    ...updates
+  };
+
+  // Preserve body content
+  const updatedContent = stringifyFrontmatter(updatedFrontmatter, epic.body);
+
+  // Write updated content back to file
+  await fs.writeFile(epic.path, updatedContent, 'utf8');
+
+  return {
+    epicId,
+    frontmatter: updatedFrontmatter,
+    body: epic.body
+  };
+}
+
+module.exports = { updateLocalEpic };