claude-autopm 2.4.0 → 2.5.0

package/bin/autopm.js

@@ -182,6 +182,8 @@ function main() {
     .command(require('./commands/mcp'))
     // Epic management command (STANDALONE)
     .command(require('../lib/cli/commands/epic'))
+    // Issue management command (STANDALONE)
+    .command(require('../lib/cli/commands/issue'))
     // PRD management command (STANDALONE)
     .command(require('../lib/cli/commands/prd'))
     // Task management command (STANDALONE)

package/lib/cli/commands/issue.js

@@ -0,0 +1,520 @@
+/**
+ * CLI Issue Commands
+ *
+ * Provides Issue management commands for ClaudeAutoPM.
+ * Implements subcommands for issue lifecycle management.
+ *
+ * Commands:
+ * - show <number>: Display issue details
+ * - start <number>: Start working on issue
+ * - close <number>: Close and complete issue
+ * - status <number>: Check issue status
+ * - edit <number>: Edit issue in editor
+ * - sync <number>: Sync issue with GitHub/Azure
+ *
+ * @module cli/commands/issue
+ * @requires ../../services/IssueService
+ * @requires fs-extra
+ * @requires ora
+ * @requires chalk
+ * @requires path
+ */
+
+const IssueService = require('../../services/IssueService');
+const fs = require('fs-extra');
+const ora = require('ora');
+const chalk = require('chalk');
+const path = require('path');
+const { spawn } = require('child_process');
+const readline = require('readline');
+
+/**
+ * Get issue file path
+ * @param {number|string} issueNumber - Issue number
+ * @returns {string} Full path to issue file
+ */
+function getIssuePath(issueNumber) {
+  return path.join(process.cwd(), '.claude', 'issues', `${issueNumber}.md`);
+}
+
+/**
+ * Read issue file
+ * @param {number|string} issueNumber - Issue number
+ * @returns {Promise<string>} Issue content
+ * @throws {Error} If file doesn't exist or can't be read
+ */
+async function readIssueFile(issueNumber) {
+  const issuePath = getIssuePath(issueNumber);
+
+  const exists = await fs.pathExists(issuePath);
+  if (!exists) {
+    throw new Error(`Issue file not found: ${issuePath}`);
+  }
+
+  return await fs.readFile(issuePath, 'utf8');
+}
+
+/**
+ * Show issue details
+ * @param {Object} argv - Command arguments
+ */
+async function issueShow(argv) {
+  const spinner = ora(`Loading issue: #${argv.number}`).start();
+
+  try {
+    const issueService = new IssueService();
+    const issue = await issueService.getLocalIssue(argv.number);
+
+    spinner.succeed(chalk.green('Issue loaded'));
+
+    // Display metadata table
+    console.log('\n' + chalk.bold('📋 Issue Details') + '\n');
+    console.log(chalk.gray('─'.repeat(50)) + '\n');
+
+    console.log(chalk.bold('ID:       ') + (issue.id || argv.number));
+    console.log(chalk.bold('Title:    ') + (issue.title || 'N/A'));
+    console.log(chalk.bold('Status:   ') + chalk.yellow(issue.status || 'open'));
+
+    if (issue.assignee) {
+      console.log(chalk.bold('Assignee: ') + issue.assignee);
+    }
+
+    if (issue.labels) {
+      console.log(chalk.bold('Labels:   ') + issue.labels);
+    }
+
+    if (issue.created) {
+      console.log(chalk.bold('Created:  ') + new Date(issue.created).toLocaleDateString());
+    }
+
+    if (issue.started) {
+      console.log(chalk.bold('Started:  ') + new Date(issue.started).toLocaleDateString());
+      const duration = issueService.formatIssueDuration(issue.started);
+      console.log(chalk.bold('Duration: ') + duration);
+    }
+
+    if (issue.completed) {
+      console.log(chalk.bold('Completed:') + new Date(issue.completed).toLocaleDateString());
+      const duration = issueService.formatIssueDuration(issue.started, issue.completed);
+      console.log(chalk.bold('Duration: ') + duration);
+    }
+
+    if (issue.url) {
+      console.log(chalk.bold('URL:      ') + chalk.cyan(issue.url));
+    }
+
+    // Show issue content
+    console.log('\n' + chalk.gray('─'.repeat(80)) + '\n');
+
+    // Extract and display description (skip frontmatter)
+    const contentWithoutFrontmatter = issue.content.replace(/^---[\s\S]*?---\n\n/, '');
+    console.log(contentWithoutFrontmatter);
+
+    console.log('\n' + chalk.gray('─'.repeat(80)) + '\n');
+
+    console.log(chalk.dim(`File: ${issue.path}\n`));
+
+  } catch (error) {
+    spinner.fail(chalk.red('Failed to show issue'));
+
+    if (error.message.includes('not found')) {
+      console.error(chalk.red(`\nError: ${error.message}`));
+      console.error(chalk.yellow('Use: autopm issue list to see available issues'));
+    } else {
+      console.error(chalk.red(`\nError: ${error.message}`));
+    }
+  }
+}
+
+/**
+ * Start working on issue
+ * @param {Object} argv - Command arguments
+ */
+async function issueStart(argv) {
+  const spinner = ora(`Starting issue: #${argv.number}`).start();
+
+  try {
+    const issueService = new IssueService();
+
+    // Check if issue exists
+    await issueService.getLocalIssue(argv.number);
+
+    // Update status to in-progress
+    await issueService.updateIssueStatus(argv.number, 'in-progress');
+
+    spinner.succeed(chalk.green('Issue started'));
+
+    console.log(chalk.green(`\n✅ Issue #${argv.number} is now in progress!`));
+
+    const issuePath = getIssuePath(argv.number);
+    console.log(chalk.cyan(`📄 File: ${issuePath}\n`));
+
+    console.log(chalk.bold('📋 What You Can Do Next:\n'));
+    console.log(`  ${chalk.cyan('1.')} Check status:    ${chalk.yellow('autopm issue status ' + argv.number)}`);
+    console.log(`  ${chalk.cyan('2.')} Edit issue:      ${chalk.yellow('autopm issue edit ' + argv.number)}`);
+    console.log(`  ${chalk.cyan('3.')} Close when done: ${chalk.yellow('autopm issue close ' + argv.number)}\n`);
+
+  } catch (error) {
+    spinner.fail(chalk.red('Failed to start issue'));
+
+    if (error.message.includes('not found')) {
+      console.error(chalk.red(`\nError: ${error.message}`));
+      console.error(chalk.yellow('Use: autopm issue list to see available issues'));
+    } else {
+      console.error(chalk.red(`\nError: ${error.message}`));
+    }
+  }
+}
+
+/**
+ * Close issue
+ * @param {Object} argv - Command arguments
+ */
+async function issueClose(argv) {
+  const spinner = ora(`Closing issue: #${argv.number}`).start();
+
+  try {
+    const issueService = new IssueService();
+
+    // Check if issue exists
+    await issueService.getLocalIssue(argv.number);
+
+    // Update status to closed
+    await issueService.updateIssueStatus(argv.number, 'closed');
+
+    spinner.succeed(chalk.green('Issue closed'));
+
+    console.log(chalk.green(`\n✅ Issue #${argv.number} completed!`));
+
+    const issuePath = getIssuePath(argv.number);
+    console.log(chalk.cyan(`📄 File: ${issuePath}\n`));
+
+    console.log(chalk.bold('📋 What You Can Do Next:\n'));
+    console.log(`  ${chalk.cyan('1.')} View issue:      ${chalk.yellow('autopm issue show ' + argv.number)}`);
+    console.log(`  ${chalk.cyan('2.')} Check status:    ${chalk.yellow('autopm issue status ' + argv.number)}\n`);
+
+  } catch (error) {
+    spinner.fail(chalk.red('Failed to close issue'));
+
+    if (error.message.includes('not found')) {
+      console.error(chalk.red(`\nError: ${error.message}`));
+      console.error(chalk.yellow('Use: autopm issue list to see available issues'));
+    } else {
+      console.error(chalk.red(`\nError: ${error.message}`));
+    }
+  }
+}
+
+/**
+ * Show issue status
+ * @param {Object} argv - Command arguments
+ */
+async function issueStatus(argv) {
+  const spinner = ora(`Analyzing issue: #${argv.number}`).start();
+
+  try {
+    const issueService = new IssueService();
+    const issue = await issueService.getLocalIssue(argv.number);
+
+    spinner.succeed(chalk.green('Status analyzed'));
+
+    // Display status
+    console.log('\n' + chalk.bold('📊 Issue Status Report') + '\n');
+    console.log(chalk.gray('─'.repeat(50)) + '\n');
+
+    console.log(chalk.bold('Metadata:'));
+    console.log(`  ID:        #${issue.id || argv.number}`);
+    console.log(`  Title:     ${issue.title || 'N/A'}`);
+    console.log(`  Status:    ${chalk.yellow(issue.status || 'open')}`);
+
+    if (issue.assignee) {
+      console.log(`  Assignee:  ${issue.assignee}`);
+    }
+
+    if (issue.labels) {
+      console.log(`  Labels:    ${issue.labels}`);
+    }
+
+    console.log('\n' + chalk.bold('Timeline:'));
+
+    if (issue.created) {
+      console.log(`  Created:   ${new Date(issue.created).toLocaleString()}`);
+    }
+
+    if (issue.started) {
+      console.log(`  Started:   ${new Date(issue.started).toLocaleString()}`);
+
+      if (issue.completed) {
+        const duration = issueService.formatIssueDuration(issue.started, issue.completed);
+        console.log(`  Completed: ${new Date(issue.completed).toLocaleString()}`);
+        console.log(`  Duration:  ${duration}`);
+      } else {
+        const duration = issueService.formatIssueDuration(issue.started);
+        console.log(`  Duration:  ${duration} (ongoing)`);
+      }
+    }
+
+    // Show related files
+    const relatedFiles = await issueService.getIssueFiles(argv.number);
+    if (relatedFiles.length > 0) {
+      console.log('\n' + chalk.bold('Related Files:'));
+      relatedFiles.forEach(file => {
+        console.log(`  • ${file}`);
+      });
+    }
+
+    // Show dependencies
+    const dependencies = await issueService.getDependencies(argv.number);
+    if (dependencies.length > 0) {
+      console.log('\n' + chalk.bold('Dependencies:'));
+      dependencies.forEach(dep => {
+        console.log(`  • Issue #${dep}`);
+      });
+    }
+
+    // Show sub-issues
+    const subIssues = await issueService.getSubIssues(argv.number);
+    if (subIssues.length > 0) {
+      console.log('\n' + chalk.bold('Sub-Issues:'));
+      subIssues.forEach(sub => {
+        console.log(`  • Issue #${sub}`);
+      });
+    }
+
+    console.log('\n' + chalk.gray('─'.repeat(50)) + '\n');
+
+    const issuePath = getIssuePath(argv.number);
+    console.log(chalk.dim(`File: ${issuePath}\n`));
+
+  } catch (error) {
+    spinner.fail(chalk.red('Failed to analyze status'));
+
+    if (error.message.includes('not found')) {
+      console.error(chalk.red(`\nError: ${error.message}`));
+    } else {
+      console.error(chalk.red(`\nError: ${error.message}`));
+    }
+  }
+}
+
+/**
+ * Edit issue in editor
+ * @param {Object} argv - Command arguments
+ */
+async function issueEdit(argv) {
+  const spinner = ora(`Opening issue: #${argv.number}`).start();
+
+  try {
+    const issuePath = getIssuePath(argv.number);
+
+    // Check if file exists
+    const exists = await fs.pathExists(issuePath);
+    if (!exists) {
+      spinner.fail(chalk.red('Issue not found'));
+      console.error(chalk.red(`\nError: Issue file not found: ${issuePath}`));
+      console.error(chalk.yellow('Use: autopm issue list to see available issues'));
+      return;
+    }
+
+    spinner.succeed(chalk.green('Opening editor...'));
+
+    // Determine editor
+    const editor = process.env.EDITOR || process.env.VISUAL || 'nano';
+
+    // Spawn editor
+    const child = spawn(editor, [issuePath], {
+      stdio: 'inherit',
+      cwd: process.cwd()
+    });
+
+    // Wait for editor to close
+    await new Promise((resolve, reject) => {
+      child.on('close', (code) => {
+        if (code === 0) {
+          console.log(chalk.green('\n✓ Issue saved'));
+          resolve();
+        } else {
+          reject(new Error(`Editor exited with code ${code}`));
+        }
+      });
+      child.on('error', reject);
+    });
+
+  } catch (error) {
+    spinner.fail(chalk.red('Failed to edit issue'));
+    console.error(chalk.red(`\nError: ${error.message}`));
+  }
+}
+
+/**
+ * Sync issue with GitHub/Azure
+ * @param {Object} argv - Command arguments
+ */
+async function issueSync(argv) {
+  const spinner = ora(`Syncing issue: #${argv.number}`).start();
+
+  try {
+    const issueService = new IssueService();
+
+    // Check if issue exists
+    const issue = await issueService.getLocalIssue(argv.number);
+
+    // TODO: Implement provider integration
+    // For now, just show a message
+    spinner.info(chalk.yellow('Provider sync not yet implemented'));
+
+    console.log(chalk.yellow(`\n⚠️  GitHub/Azure sync feature coming soon!\n`));
+
+    console.log(chalk.dim('This feature will:'));
+    console.log(chalk.dim('  - Create GitHub/Azure issue if not exists'));
+    console.log(chalk.dim('  - Update existing issue'));
+    console.log(chalk.dim('  - Sync issue status and comments\n'));
+
+    console.log(chalk.bold('For now, you can:'));
+    console.log(`  ${chalk.cyan('1.')} View issue:      ${chalk.yellow('autopm issue show ' + argv.number)}`);
+    console.log(`  ${chalk.cyan('2.')} Check status:    ${chalk.yellow('autopm issue status ' + argv.number)}\n`);
+
+  } catch (error) {
+    spinner.fail(chalk.red('Failed to sync issue'));
+
+    if (error.message.includes('not found')) {
+      console.error(chalk.red(`\nError: ${error.message}`));
+    } else {
+      console.error(chalk.red(`\nError: ${error.message}`));
+    }
+  }
+}
+
+/**
+ * Command builder - registers all subcommands
+ * @param {Object} yargs - Yargs instance
+ * @returns {Object} Configured yargs instance
+ */
+function builder(yargs) {
+  return yargs
+    .command(
+      'show <number>',
+      'Display issue details',
+      (yargs) => {
+        return yargs
+          .positional('number', {
+            describe: 'Issue number',
+            type: 'number'
+          })
+          .example('autopm issue show 123', 'Display issue #123');
+      },
+      issueShow
+    )
+    .command(
+      'start <number>',
+      'Start working on issue',
+      (yargs) => {
+        return yargs
+          .positional('number', {
+            describe: 'Issue number',
+            type: 'number'
+          })
+          .example('autopm issue start 123', 'Mark issue #123 as in-progress');
+      },
+      issueStart
+    )
+    .command(
+      'close <number>',
+      'Close and complete issue',
+      (yargs) => {
+        return yargs
+          .positional('number', {
+            describe: 'Issue number',
+            type: 'number'
+          })
+          .example('autopm issue close 123', 'Mark issue #123 as completed');
+      },
+      issueClose
+    )
+    .command(
+      'status <number>',
+      'Check issue status',
+      (yargs) => {
+        return yargs
+          .positional('number', {
+            describe: 'Issue number',
+            type: 'number'
+          })
+          .example('autopm issue status 123', 'Show status of issue #123');
+      },
+      issueStatus
+    )
+    .command(
+      'edit <number>',
+      'Edit issue in your editor',
+      (yargs) => {
+        return yargs
+          .positional('number', {
+            describe: 'Issue number',
+            type: 'number'
+          })
+          .example('autopm issue edit 123', 'Open issue #123 in editor')
+          .example('EDITOR=code autopm issue edit 123', 'Open in VS Code');
+      },
+      issueEdit
+    )
+    .command(
+      'sync <number>',
+      'Sync issue with GitHub/Azure',
+      (yargs) => {
+        return yargs
+          .positional('number', {
+            describe: 'Issue number',
+            type: 'number'
+          })
+          .option('push', {
+            describe: 'Push local changes to provider',
+            type: 'boolean',
+            default: false
+          })
+          .option('pull', {
+            describe: 'Pull updates from provider',
+            type: 'boolean',
+            default: false
+          })
+          .example('autopm issue sync 123', 'Sync issue #123 with provider')
+          .example('autopm issue sync 123 --push', 'Push local changes')
+          .example('autopm issue sync 123 --pull', 'Pull remote updates');
+      },
+      issueSync
+    )
+    .demandCommand(1, 'You must specify an issue command')
+    .strictCommands()
+    .help();
+}
+
+/**
+ * Command export
+ */
+module.exports = {
+  command: 'issue',
+  describe: 'Manage issues and task lifecycle',
+  builder,
+  handler: (argv) => {
+    if (!argv._.includes('issue') || argv._.length === 1) {
+      console.log(chalk.yellow('\nPlease specify an issue command\n'));
+      console.log('Usage: autopm issue <command>\n');
+      console.log('Available commands:');
+      console.log('  show <number>         Display issue details');
+      console.log('  start <number>        Start working on issue');
+      console.log('  close <number>        Close issue');
+      console.log('  status <number>       Check issue status');
+      console.log('  edit <number>         Edit issue in editor');
+      console.log('  sync <number>         Sync with GitHub/Azure');
+      console.log('\nUse: autopm issue <command> --help for more info\n');
+    }
+  },
+  handlers: {
+    show: issueShow,
+    start: issueStart,
+    close: issueClose,
+    status: issueStatus,
+    edit: issueEdit,
+    sync: issueSync
+  }
+};

package/lib/services/IssueService.js

@@ -0,0 +1,591 @@
+/**
+ * IssueService - Issue Management Service
+ *
+ * Pure service layer for issue operations following ClaudeAutoPM patterns.
+ * Follows 3-layer architecture: Service (logic) -> Provider (I/O) -> CLI (presentation)
+ *
+ * Provides comprehensive issue lifecycle management:
+ *
+ * 1. Issue Metadata & Parsing (4 methods):
+ *    - parseIssueMetadata: Parse YAML frontmatter from issue content
+ *    - getLocalIssue: Read local issue file with metadata
+ *    - getIssueStatus: Get current status of an issue
+ *    - validateIssue: Validate issue structure and required fields
+ *
+ * 2. Issue Lifecycle Management (2 methods):
+ *    - updateIssueStatus: Update status with automatic timestamps
+ *    - listIssues: List all issues with optional filtering
+ *
+ * 3. Issue Relationships (3 methods):
+ *    - getIssueFiles: Find all files related to an issue
+ *    - getSubIssues: Get child issues
+ *    - getDependencies: Get blocking issues
+ *
+ * 4. Provider Integration (2 methods):
+ *    - syncIssueToProvider: Push local changes to GitHub/Azure
+ *    - syncIssueFromProvider: Pull updates from provider
+ *
+ * 5. Utility Methods (4 methods):
+ *    - categorizeStatus: Categorize status into standard buckets
+ *    - isIssueClosed: Check if issue is closed
+ *    - getIssuePath: Get file path for issue
+ *    - formatIssueDuration: Format time duration
+ *
+ * Documentation Queries:
+ * - GitHub Issues API v3 best practices (2025)
+ * - Azure DevOps work items REST API patterns
+ * - Agile issue tracking workflow best practices
+ * - mcp://context7/project-management/issue-tracking - Issue lifecycle management
+ * - mcp://context7/markdown/frontmatter - YAML frontmatter patterns
+ */
+
+class IssueService {
+  /**
+   * Create a new IssueService instance
+   *
+   * @param {Object} options - Configuration options
+   * @param {Object} options.provider - Provider instance for GitHub/Azure (optional)
+   * @param {string} [options.issuesDir] - Path to issues directory (default: .claude/issues)
+   * @param {string} [options.defaultStatus] - Default issue status (default: open)
+   */
+  constructor(options = {}) {
+    // Provider for GitHub/Azure integration (optional)
+    this.provider = options.provider || null;
+
+    // CLI operation options
+    this.options = {
+      issuesDir: options.issuesDir || '.claude/issues',
+      defaultStatus: options.defaultStatus || 'open',
+      ...options
+    };
+  }
+
+  // ==========================================
+  // 1. ISSUE METADATA & PARSING (4 METHODS)
+  // ==========================================
+
+  /**
+   * Parse YAML frontmatter from issue content
+   *
+   * Extracts key-value pairs from YAML frontmatter block.
+   * Returns null if frontmatter is missing or malformed.
+   *
+   * @param {string} content - Issue markdown content with frontmatter
+   * @returns {Object|null} Parsed frontmatter object or null
+   *
+   * @example
+   * parseIssueMetadata(`---
+   * id: 123
+   * title: Fix bug
+   * status: open
+   * ---
+   * # Issue Details`)
+   * // Returns: { id: '123', title: 'Fix bug', status: 'open' }
+   */
+  parseIssueMetadata(content) {
+    if (!content || typeof content !== 'string') {
+      return null;
+    }
+
+    // Match frontmatter block: ---\n...\n--- or ---\n---
+    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/) ||
+                             content.match(/^---\n---/);
+
+    if (!frontmatterMatch) {
+      return null;
+    }
+
+    // Empty frontmatter (---\n---)
+    if (!frontmatterMatch[1] && content.startsWith('---\n---')) {
+      return {};
+    }
+
+    const metadata = {};
+    const lines = (frontmatterMatch[1] || '').split('\n');
+
+    for (const line of lines) {
+      // Skip empty lines
+      if (!line.trim()) {
+        continue;
+      }
+
+      // Find first colon to split key and value
+      const colonIndex = line.indexOf(':');
+      if (colonIndex === -1) {
+        continue; // Skip lines without colons
+      }
+
+      const key = line.substring(0, colonIndex).trim();
+      const value = line.substring(colonIndex + 1).trim();
+
+      if (key) {
+        metadata[key] = value;
+      }
+    }
+
+    return metadata;
+  }
+
+  /**
+   * Read local issue file with metadata
+   *
+   * @param {number|string} issueNumber - Issue number
+   * @returns {Promise<Object>} Issue data with metadata and content
+   * @throws {Error} If issue not found
+   *
+   * @example
+   * await getLocalIssue(123)
+   * // Returns: { id: '123', title: '...', status: '...', content: '...' }
+   */
+  async getLocalIssue(issueNumber) {
+    const fs = require('fs-extra');
+
+    const issuePath = this.getIssuePath(issueNumber);
+
+    // Check if issue exists
+    const exists = await fs.pathExists(issuePath);
+    if (!exists) {
+      throw new Error(`Issue not found: ${issueNumber}`);
+    }
+
+    // Read issue content
+    const content = await fs.readFile(issuePath, 'utf8');
+    const metadata = this.parseIssueMetadata(content);
+
+    return {
+      ...metadata,
+      content,
+      path: issuePath
+    };
+  }
+
+  /**
+   * Get current status of an issue
+   *
+   * @param {number|string} issueNumber - Issue number
+   * @returns {Promise<string>} Current status
+   * @throws {Error} If issue not found
+   */
+  async getIssueStatus(issueNumber) {
+    try {
+      const issue = await this.getLocalIssue(issueNumber);
+      return issue.status || this.options.defaultStatus;
+    } catch (error) {
+      if (error.message.includes('not found')) {
+        throw new Error(`Issue not found: ${issueNumber}`);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Validate issue structure and completeness
+   *
+   * @param {number|string} issueNumber - Issue number
+   * @returns {Promise<Object>} Validation result: { valid: boolean, issues: string[] }
+   * @throws {Error} If issue not found
+   */
+  async validateIssue(issueNumber) {
+    const fs = require('fs-extra');
+
+    const issuePath = this.getIssuePath(issueNumber);
+
+    // Check if issue exists
+    const exists = await fs.pathExists(issuePath);
+    if (!exists) {
+      throw new Error(`Issue not found: ${issueNumber}`);
+    }
+
+    const issues = [];
+
+    // Read issue content
+    const content = await fs.readFile(issuePath, 'utf8');
+
+    // Check for frontmatter
+    const metadata = this.parseIssueMetadata(content);
+    if (!metadata) {
+      issues.push('Missing frontmatter');
+    } else {
+      // Check for required fields
+      if (!metadata.id) {
+        issues.push('Missing id in frontmatter');
+      }
+      if (!metadata.title) {
+        issues.push('Missing title in frontmatter');
+      }
+    }
+
+    return {
+      valid: issues.length === 0,
+      issues
+    };
+  }
+
+  // ==========================================
+  // 2. ISSUE LIFECYCLE MANAGEMENT (2 METHODS)
+  // ==========================================
+
+  /**
+   * Update issue status with automatic timestamps
+   *
+   * @param {number|string} issueNumber - Issue number
+   * @param {string} newStatus - New status to set
+   * @returns {Promise<void>}
+   * @throws {Error} If issue not found
+   */
+  async updateIssueStatus(issueNumber, newStatus) {
+    const fs = require('fs-extra');
+
+    const issuePath = this.getIssuePath(issueNumber);
+
+    // Check if issue exists
+    const exists = await fs.pathExists(issuePath);
+    if (!exists) {
+      throw new Error(`Issue not found: ${issueNumber}`);
+    }
+
+    // Read current content
+    let content = await fs.readFile(issuePath, 'utf8');
+
+    // Update status
+    content = content.replace(/^status:\s*.+$/m, `status: ${newStatus}`);
+
+    const now = new Date().toISOString();
+
+    // Add started timestamp when moving to in-progress
+    if (newStatus === 'in-progress' && !content.includes('started:')) {
+      // Try to add after created: field, or after status: if no created: field
+      if (content.includes('created:')) {
+        content = content.replace(/^(created:.+)$/m, `$1\nstarted: ${now}`);
+      } else {
+        content = content.replace(/^(status:.+)$/m, `$1\nstarted: ${now}`);
+      }
+    }
+
+    // Add completed timestamp when closing
+    if (['closed', 'completed', 'done', 'resolved'].includes(newStatus.toLowerCase()) &&
+        !content.includes('completed:')) {
+      // Try to add after created: field, or after status: if no created: field
+      if (content.includes('created:')) {
+        content = content.replace(/^(created:.+)$/m, `$1\ncompleted: ${now}`);
+      } else {
+        content = content.replace(/^(status:.+)$/m, `$1\ncompleted: ${now}`);
+      }
+    }
+
+    // Write updated content
+    await fs.writeFile(issuePath, content);
+  }
+
+  /**
+   * List all issues with optional filtering
+   *
+   * @param {Object} [options] - Filter options
+   * @param {string} [options.status] - Filter by status
+   * @returns {Promise<Array<Object>>} Array of issue objects with metadata
+   */
+  async listIssues(options = {}) {
+    const fs = require('fs-extra');
+    const path = require('path');
+
+    const issuesDir = path.join(process.cwd(), this.options.issuesDir);
+
+    // Check if issues directory exists
+    const dirExists = await fs.pathExists(issuesDir);
+    if (!dirExists) {
+      return [];
+    }
+
+    // Read all issue files
+    let files;
+    try {
+      files = await fs.readdir(issuesDir);
+      // Only process .md files with numeric names
+      files = files.filter(file => /^\d+\.md$/.test(file));
+    } catch (error) {
+      return [];
+    }
+
+    const issues = [];
+
+    for (const file of files) {
+      const filePath = path.join(issuesDir, file);
+
+      try {
+        const content = await fs.readFile(filePath, 'utf8');
+        const metadata = this.parseIssueMetadata(content);
+
+        if (metadata) {
+          // Apply default status if missing
+          metadata.status = metadata.status || this.options.defaultStatus;
+
+          // Filter by status if specified
+          if (options.status && metadata.status !== options.status) {
+            continue;
+          }
+
+          issues.push({
+            ...metadata,
+            path: filePath
+          });
+        }
+      } catch (error) {
+        // Skip files that can't be read
+        continue;
+      }
+    }
+
+    return issues;
+  }
+
+  // ==========================================
+  // 3. ISSUE RELATIONSHIPS (3 METHODS)
+  // ==========================================
+
+  /**
+   * Find all files related to an issue
+   *
+   * @param {number|string} issueNumber - Issue number
+   * @returns {Promise<Array<string>>} Array of related file names
+   */
+  async getIssueFiles(issueNumber) {
+    const fs = require('fs-extra');
+    const path = require('path');
+
+    const issuesDir = path.join(process.cwd(), this.options.issuesDir);
+
+    // Check if issues directory exists
+    const dirExists = await fs.pathExists(issuesDir);
+    if (!dirExists) {
+      return [];
+    }
+
+    // Read all files
+    try {
+      const files = await fs.readdir(issuesDir);
+
+      // Filter files that start with issue number
+      const issueStr = String(issueNumber);
+      const relatedFiles = files.filter(file => {
+        return file.startsWith(`${issueStr}.md`) ||
+               file.startsWith(`${issueStr}-`);
+      });
+
+      return relatedFiles;
+    } catch (error) {
+      return [];
+    }
+  }
+
+  /**
+   * Get child issues of a parent issue
+   *
+   * @param {number|string} issueNumber - Parent issue number
+   * @returns {Promise<Array<string>>} Array of child issue numbers
+   */
+  async getSubIssues(issueNumber) {
+    try {
+      const issue = await this.getLocalIssue(issueNumber);
+      const children = issue.children;
+
+      if (!children) {
+        return [];
+      }
+
+      // Parse children (can be array [101, 102] or string "101, 102")
+      if (typeof children === 'string') {
+        // Remove brackets and split by comma
+        const cleaned = children.replace(/[\[\]]/g, '');
+        return cleaned.split(',').map(c => c.trim()).filter(c => c);
+      }
+
+      return [];
+    } catch (error) {
+      return [];
+    }
+  }
+
+  /**
+   * Get blocking issues (dependencies)
+   *
+   * @param {number|string} issueNumber - Issue number
+   * @returns {Promise<Array<string>>} Array of blocking issue numbers
+   */
+  async getDependencies(issueNumber) {
+    try {
+      const issue = await this.getLocalIssue(issueNumber);
+      const dependencies = issue.dependencies || issue.blocked_by;
+
+      if (!dependencies) {
+        return [];
+      }
+
+      // Parse dependencies (can be array [120, 121] or string "120, 121")
+      if (typeof dependencies === 'string') {
+        // Remove brackets and split by comma
+        const cleaned = dependencies.replace(/[\[\]]/g, '');
+        return cleaned.split(',').map(d => d.trim()).filter(d => d);
+      }
+
+      return [];
+    } catch (error) {
+      return [];
+    }
+  }
+
+  // ==========================================
+  // 4. PROVIDER INTEGRATION (2 METHODS)
+  // ==========================================
+
+  /**
+   * Push local issue changes to GitHub/Azure
+   *
+   * @param {number|string} issueNumber - Issue number
+   * @returns {Promise<Object>} Sync result
+   * @throws {Error} If no provider configured
+   */
+  async syncIssueToProvider(issueNumber) {
+    if (!this.provider || !this.provider.updateIssue) {
+      throw new Error('No provider configured for syncing');
+    }
+
+    // Read local issue
+    const issue = await this.getLocalIssue(issueNumber);
+
+    // Push to provider
+    const result = await this.provider.updateIssue(issue);
+
+    return result;
+  }
+
+  /**
+   * Pull issue updates from GitHub/Azure
+   *
+   * @param {number|string} issueNumber - Issue number
+   * @returns {Promise<Object>} Updated issue data
+   * @throws {Error} If no provider configured
+   */
+  async syncIssueFromProvider(issueNumber) {
+    const fs = require('fs-extra');
+
+    if (!this.provider || !this.provider.getIssue) {
+      throw new Error('No provider configured for syncing');
+    }
+
+    // Fetch from provider
+    const issueData = await this.provider.getIssue(String(issueNumber));
+
+    // Build issue content with frontmatter
+    const frontmatter = `---
+id: ${issueData.id}
+title: ${issueData.title}
+status: ${issueData.status}
+${issueData.assignees && issueData.assignees.length > 0 ? `assignee: ${issueData.assignees[0]}` : ''}
+${issueData.labels && issueData.labels.length > 0 ? `labels: ${issueData.labels.join(', ')}` : ''}
+created: ${issueData.createdAt}
+updated: ${issueData.updatedAt}
+${issueData.url ? `url: ${issueData.url}` : ''}
+---
+
+# ${issueData.title}
+
+${issueData.description || ''}
+`;
+
+    // Write to local file
+    const issuePath = this.getIssuePath(issueNumber);
+    await fs.writeFile(issuePath, frontmatter);
+
+    return issueData;
+  }
+
+  // ==========================================
+  // 5. UTILITY METHODS (4 METHODS)
+  // ==========================================
+
+  /**
+   * Categorize issue status into standard buckets
+   *
+   * Maps various status strings to standardized categories:
+   * - open: Not started, awaiting work
+   * - in_progress: Active development
+   * - closed: Completed/resolved
+   *
+   * @param {string} status - Raw status string
+   * @returns {string} Categorized status (open|in_progress|closed)
+   */
+  categorizeStatus(status) {
+    const lowerStatus = (status || '').toLowerCase();
+
+    // Open statuses
+    if (['open', 'todo', 'new', ''].includes(lowerStatus)) {
+      return 'open';
+    }
+
+    // In-progress statuses
+    if (['in-progress', 'in_progress', 'active', 'started'].includes(lowerStatus)) {
+      return 'in_progress';
+    }
+
+    // Closed statuses
+    if (['closed', 'completed', 'done', 'resolved'].includes(lowerStatus)) {
+      return 'closed';
+    }
+
+    // Default to open for unknown statuses
+    return 'open';
+  }
+
+  /**
+   * Check if issue is in closed/completed state
+   *
+   * @param {Object} issue - Issue object with status field
+   * @returns {boolean} True if issue is closed
+   */
+  isIssueClosed(issue) {
+    if (!issue || !issue.status) {
+      return false;
+    }
+
+    const status = (issue.status || '').toLowerCase();
+    return ['closed', 'completed', 'done', 'resolved'].includes(status);
+  }
+
+  /**
+   * Get file path for issue
+   *
+   * @param {number|string} issueNumber - Issue number
+   * @returns {string} Full path to issue file
+   */
+  getIssuePath(issueNumber) {
+    const path = require('path');
+    return path.join(process.cwd(), this.options.issuesDir, `${issueNumber}.md`);
+  }
+
+  /**
+   * Format time duration between two timestamps
+   *
+   * @param {string} startTime - ISO timestamp for start
+   * @param {string} [endTime] - ISO timestamp for end (defaults to now)
+   * @returns {string} Formatted duration (e.g., "2h 30m", "3 days 4h")
+   */
+  formatIssueDuration(startTime, endTime = null) {
+    const start = new Date(startTime);
+    const end = endTime ? new Date(endTime) : new Date();
+    const diff = end - start;
+
+    const days = Math.floor(diff / (1000 * 60 * 60 * 24));
+    const hours = Math.floor((diff % (1000 * 60 * 60 * 24)) / (1000 * 60 * 60));
+    const minutes = Math.floor((diff % (1000 * 60 * 60)) / (1000 * 60));
+
+    if (days > 0) {
+      return `${days} day${days > 1 ? 's' : ''} ${hours}h`;
+    } else if (hours > 0) {
+      return `${hours}h ${minutes}m`;
+    } else {
+      return `${minutes} minute${minutes > 1 ? 's' : ''}`;
+    }
+  }
+}
+
+module.exports = IssueService;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-autopm",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "Autonomous Project Management Framework for Claude Code - Advanced AI-powered development automation",
   "main": "bin/autopm.js",
   "bin": {