musubi-sdd 2.0.7 → 2.1.0

package/README.ja.md

@@ -4,13 +4,20 @@
 
 MUSUBIは、6つの主要フレームワークのベスト機能を統合した包括的なSDD（仕様駆動開発）フレームワークであり、複数のAIコーディングエージェントに対応した本番環境対応ツールです。
 
-## 🚀 v2.0.0 の新機能
+## 🚀 v2.1.0 の新機能
+
+- 🔄 **ワークフローエンジン** - ステージ管理とメトリクス収集の新CLI `musubi-workflow`
+- 📊 **メトリクス収集** - ステージごとの所要時間、イテレーション回数、フィードバックループを追跡
+- 🔬 **Spike/PoCステージ** - 要件定義前の調査・プロトタイピング用ステージ0
+- 👀 **コードレビューステージ** - 実装とテストの間のステージ5.5
+- 🔄 **振り返りステージ** - 継続的改善のためのステージ9
+- ✅ **ステージ検証ガイド** - ステージ遷移の検証チェックリスト
+
+### 以前のバージョン (v2.0.0)
 
 - 🔌 **CodeGraphMCPServer統合** - 14のMCPツールによる高度なコード分析
 - 🧠 **GraphRAG駆動検索** - Louvainコミュニティ検出によるセマンティックコード理解
 - 🔍 **11エージェント強化** - 主要エージェントがMCPツールを活用して深いコード分析を実現
-- 📊 **依存関係分析** - `find_dependencies`, `find_callers`, `analyze_module_structure`
-- 🎯 **スマートコードナビゲーション** - `local_search`, `global_search`, `query_codebase`
 
 ## 特徴
 

package/README.md

@@ -8,13 +8,20 @@
 
 MUSUBI is a comprehensive SDD (Specification Driven Development) framework that synthesizes the best features from 6 leading frameworks into a production-ready tool for multiple AI coding agents.
 
-## 🚀 What's New in v2.0.0
+## 🚀 What's New in v2.1.0
+
+- 🔄 **Workflow Engine** - New `musubi-workflow` CLI for stage management and metrics
+- 📊 **Metrics Collection** - Track time per stage, iteration counts, feedback loops
+- 🔬 **Spike/PoC Stage** - Stage 0 for research and prototyping before requirements
+- 👀 **Code Review Stage** - Stage 5.5 between implementation and testing
+- 🔄 **Retrospective Stage** - Stage 9 for continuous improvement
+- ✅ **Stage Validation Guide** - Checklists for stage transition validation
+
+### Previous (v2.0.0)
 
 - 🔌 **CodeGraphMCPServer Integration** - 14 MCP tools for enhanced code analysis
 - 🧠 **GraphRAG-Powered Search** - Semantic code understanding with Louvain community detection
 - 🔍 **11 Agents Enhanced** - Key agents now leverage MCP tools for deeper code analysis
-- 📊 **Dependency Analysis** - `find_dependencies`, `find_callers`, `analyze_module_structure`
-- 🎯 **Smart Code Navigation** - `local_search`, `global_search`, `query_codebase`
 
 ## Features
 

package/bin/musubi-workflow.js

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+
+/**
+ * MUSUBI Workflow CLI
+ * 
+ * Manage workflow state, transitions, and metrics.
+ * 
+ * Commands:
+ *   init <feature>    - Initialize workflow for a feature
+ *   status            - Show current workflow status
+ *   next [stage]      - Transition to next stage
+ *   complete          - Complete the workflow
+ *   metrics           - Show workflow metrics summary
+ *   history           - Show workflow history
+ */
+
+const { program } = require('commander');
+const { WorkflowEngine, WORKFLOW_STAGES } = require('../src/managers/workflow');
+const chalk = require('chalk');
+
+const engine = new WorkflowEngine();
+
+// Stage icons for visual feedback
+const STAGE_ICONS = {
+  spike: '🔬',
+  research: '📚',
+  requirements: '📋',
+  design: '📐',
+  tasks: '📝',
+  implementation: '💻',
+  review: '👀',
+  testing: '🧪',
+  deployment: '🚀',
+  monitoring: '📊',
+  retrospective: '🔄'
+};
+
+/**
+ * Format stage name with icon
+ */
+function formatStage(stage) {
+  const icon = STAGE_ICONS[stage] || '📌';
+  return `${icon} ${stage}`;
+}
+
+/**
+ * Display workflow status
+ */
+async function showStatus() {
+  const state = await engine.getState();
+  
+  if (!state) {
+    console.log(chalk.yellow('\n⚠️  No active workflow. Use "musubi-workflow init <feature>" to start.'));
+    return;
+  }
+
+  console.log(chalk.bold('\n📊 Workflow Status\n'));
+  console.log(chalk.white(`Feature: ${chalk.cyan(state.feature)}`));
+  console.log(chalk.white(`Current Stage: ${formatStage(state.currentStage)}`));
+  console.log(chalk.white(`Started: ${new Date(state.startedAt).toLocaleString()}`));
+  
+  // Show stage progress
+  console.log(chalk.bold('\n📈 Stage Progress:\n'));
+  
+  const allStages = Object.keys(WORKFLOW_STAGES);
+  const currentIndex = allStages.indexOf(state.currentStage);
+  
+  allStages.forEach((stage, index) => {
+    const data = state.stages[stage];
+    let status = '';
+    let color = chalk.gray;
+    
+    if (data?.status === 'completed') {
+      status = `✅ Completed (${data.duration})`;
+      color = chalk.green;
+    } else if (stage === state.currentStage) {
+      status = '🔄 In Progress';
+      color = chalk.blue;
+    } else if (index < currentIndex) {
+      status = '⏭️  Skipped';
+      color = chalk.gray;
+    } else {
+      status = '⏳ Pending';
+      color = chalk.gray;
+    }
+    
+    console.log(color(`  ${formatStage(stage).padEnd(25)} ${status}`));
+  });
+
+  // Show valid transitions
+  const validNext = await engine.getValidTransitions();
+  if (validNext.length > 0) {
+    console.log(chalk.bold('\n🔀 Valid Transitions:'));
+    validNext.forEach(stage => {
+      console.log(chalk.cyan(`  → ${formatStage(stage)}`));
+    });
+  }
+}
+
+/**
+ * Display workflow history
+ */
+async function showHistory() {
+  const state = await engine.getState();
+  
+  if (!state || !state.history) {
+    console.log(chalk.yellow('\n⚠️  No workflow history available.'));
+    return;
+  }
+
+  console.log(chalk.bold('\n📜 Workflow History\n'));
+  
+  state.history.forEach(event => {
+    const time = new Date(event.timestamp).toLocaleString();
+    let desc = '';
+    
+    switch (event.action) {
+      case 'workflow-started':
+        desc = `Started workflow for "${event.feature}" at ${formatStage(event.stage)}`;
+        break;
+      case 'stage-transition':
+        desc = `${formatStage(event.from)} → ${formatStage(event.to)}`;
+        if (event.notes) desc += ` (${event.notes})`;
+        break;
+      case 'feedback-loop':
+        desc = `🔄 Feedback: ${formatStage(event.from)} → ${formatStage(event.to)} - ${event.reason}`;
+        break;
+      case 'workflow-completed':
+        desc = `✅ Workflow completed`;
+        if (event.notes) desc += ` (${event.notes})`;
+        break;
+      default:
+        desc = event.action;
+    }
+    
+    console.log(chalk.white(`  ${chalk.gray(time)} ${desc}`));
+  });
+}
+
+/**
+ * Display metrics summary
+ */
+async function showMetrics() {
+  const summary = await engine.getMetricsSummary();
+  
+  console.log(chalk.bold('\n📊 Workflow Metrics Summary\n'));
+  
+  if (summary.message) {
+    console.log(chalk.yellow(`  ${summary.message}`));
+    return;
+  }
+
+  console.log(chalk.white(`  Total Workflows:     ${summary.totalWorkflows}`));
+  console.log(chalk.white(`  Completed:           ${summary.completedWorkflows}`));
+  console.log(chalk.white(`  Stage Transitions:   ${summary.stageTransitions}`));
+  console.log(chalk.white(`  Feedback Loops:      ${summary.feedbackLoops}`));
+  
+  if (summary.averageDuration) {
+    console.log(chalk.white(`  Average Duration:    ${summary.averageDuration}`));
+  }
+
+  if (Object.keys(summary.stageStats).length > 0) {
+    console.log(chalk.bold('\n📈 Stage Visit Counts:\n'));
+    Object.entries(summary.stageStats)
+      .sort((a, b) => b[1].visits - a[1].visits)
+      .forEach(([stage, data]) => {
+        console.log(chalk.white(`  ${formatStage(stage).padEnd(25)} ${data.visits} visits`));
+      });
+  }
+}
+
+// CLI Commands
+program
+  .name('musubi-workflow')
+  .description('MUSUBI Workflow Engine - Manage SDD workflow state and metrics')
+  .version('2.0.7');
+
+program
+  .command('init <feature>')
+  .description('Initialize a new workflow for a feature')
+  .option('-s, --stage <stage>', 'Starting stage', 'requirements')
+  .action(async (feature, options) => {
+    try {
+      const state = await engine.initWorkflow(feature, { startStage: options.stage });
+      console.log(chalk.green(`\n✅ Workflow initialized for "${feature}"`));
+      console.log(chalk.cyan(`   Starting at: ${formatStage(state.currentStage)}`));
+    } catch (error) {
+      console.error(chalk.red(`\n❌ Error: ${error.message}`));
+      process.exit(1);
+    }
+  });
+
+program
+  .command('status')
+  .description('Show current workflow status')
+  .action(showStatus);
+
+program
+  .command('next [stage]')
+  .description('Transition to the next stage')
+  .option('-n, --notes <notes>', 'Transition notes')
+  .action(async (stage, options) => {
+    try {
+      const state = await engine.getState();
+      if (!state) {
+        console.log(chalk.yellow('\n⚠️  No active workflow.'));
+        return;
+      }
+
+      // If no stage specified, show valid options
+      if (!stage) {
+        const validNext = await engine.getValidTransitions();
+        console.log(chalk.bold('\n🔀 Valid next stages:'));
+        validNext.forEach(s => console.log(chalk.cyan(`  → ${formatStage(s)}`)));
+        console.log(chalk.white('\nUse: musubi-workflow next <stage>'));
+        return;
+      }
+
+      await engine.transitionTo(stage, options.notes);
+      console.log(chalk.green(`\n✅ Transitioned to ${formatStage(stage)}`));
+    } catch (error) {
+      console.error(chalk.red(`\n❌ Error: ${error.message}`));
+      process.exit(1);
+    }
+  });
+
+program
+  .command('feedback <from> <to>')
+  .description('Record a feedback loop')
+  .requiredOption('-r, --reason <reason>', 'Reason for feedback loop')
+  .action(async (from, to, options) => {
+    try {
+      await engine.recordFeedbackLoop(from, to, options.reason);
+      await engine.transitionTo(to, `Feedback: ${options.reason}`);
+      console.log(chalk.yellow(`\n🔄 Feedback loop recorded: ${formatStage(from)} → ${formatStage(to)}`));
+      console.log(chalk.gray(`   Reason: ${options.reason}`));
+    } catch (error) {
+      console.error(chalk.red(`\n❌ Error: ${error.message}`));
+      process.exit(1);
+    }
+  });
+
+program
+  .command('complete')
+  .description('Complete the current workflow')
+  .option('-n, --notes <notes>', 'Completion notes')
+  .action(async (options) => {
+    try {
+      const summary = await engine.completeWorkflow(options.notes);
+      
+      console.log(chalk.green('\n✅ Workflow Completed!\n'));
+      console.log(chalk.bold('📊 Summary:'));
+      console.log(chalk.white(`  Feature:        ${summary.feature}`));
+      console.log(chalk.white(`  Total Duration: ${summary.totalDuration}`));
+      console.log(chalk.white(`  Stages:         ${summary.stages.length}`));
+      console.log(chalk.white(`  Feedback Loops: ${summary.feedbackLoops}`));
+      
+      if (summary.stages.length > 0) {
+        console.log(chalk.bold('\n📈 Stage Breakdown:'));
+        summary.stages.forEach(s => {
+          console.log(chalk.white(`  ${formatStage(s.name).padEnd(25)} ${s.duration} (${s.attempts} attempt${s.attempts > 1 ? 's' : ''})`));
+        });
+      }
+    } catch (error) {
+      console.error(chalk.red(`\n❌ Error: ${error.message}`));
+      process.exit(1);
+    }
+  });
+
+program
+  .command('history')
+  .description('Show workflow history')
+  .action(showHistory);
+
+program
+  .command('metrics')
+  .description('Show workflow metrics summary')
+  .action(showMetrics);
+
+program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "musubi-sdd",
-  "version": "2.0.7",
+  "version": "2.1.0",
   "description": "Ultimate Specification Driven Development Tool with 25 Agents for 7 AI Coding Platforms + MCP Integration (Claude Code, GitHub Copilot, Cursor, Gemini CLI, Windsurf, Codex, Qwen Code)",
   "main": "src/index.js",
   "bin": {
@@ -17,7 +17,8 @@
     "musubi-tasks": "bin/musubi-tasks.js",
     "musubi-trace": "bin/musubi-trace.js",
     "musubi-gaps": "bin/musubi-gaps.js",
-    "musubi-change": "bin/musubi-change.js"
+    "musubi-change": "bin/musubi-change.js",
+    "musubi-workflow": "bin/musubi-workflow.js"
   },
   "scripts": {
     "test": "jest",

package/src/managers/workflow.js

@@ -0,0 +1,360 @@
+/**
+ * Workflow Engine for MUSUBI SDD
+ * 
+ * Manages workflow state, stage transitions, and metrics collection.
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const yaml = require('js-yaml');
+
+/**
+ * Workflow stages with their valid transitions
+ */
+const WORKFLOW_STAGES = {
+  spike: { next: ['requirements'], optional: true },
+  research: { next: ['requirements'], optional: true },
+  requirements: { next: ['design'] },
+  design: { next: ['tasks'] },
+  tasks: { next: ['implementation'] },
+  implementation: { next: ['review'] },
+  review: { next: ['testing', 'implementation'] }, // Can go back to implementation
+  testing: { next: ['deployment', 'implementation', 'requirements'] }, // Feedback loops
+  deployment: { next: ['monitoring'] },
+  monitoring: { next: ['retrospective'] },
+  retrospective: { next: ['requirements'] } // New iteration
+};
+
+/**
+ * Workflow state file path
+ */
+const WORKFLOW_STATE_FILE = 'storage/workflow-state.yml';
+
+/**
+ * Metrics file path
+ */
+const METRICS_FILE = 'storage/workflow-metrics.yml';
+
+class WorkflowEngine {
+  constructor(projectRoot = process.cwd()) {
+    this.projectRoot = projectRoot;
+    this.stateFile = path.join(projectRoot, WORKFLOW_STATE_FILE);
+    this.metricsFile = path.join(projectRoot, METRICS_FILE);
+  }
+
+  /**
+   * Initialize workflow for a new feature/iteration
+   */
+  async initWorkflow(featureName, options = {}) {
+    const state = {
+      feature: featureName,
+      currentStage: options.startStage || 'requirements',
+      startedAt: new Date().toISOString(),
+      stages: {},
+      history: []
+    };
+
+    // Record initial stage
+    state.stages[state.currentStage] = {
+      enteredAt: new Date().toISOString(),
+      status: 'in-progress'
+    };
+
+    state.history.push({
+      timestamp: new Date().toISOString(),
+      action: 'workflow-started',
+      stage: state.currentStage,
+      feature: featureName
+    });
+
+    await this.saveState(state);
+    await this.recordMetric('workflow_started', { feature: featureName });
+
+    return state;
+  }
+
+  /**
+   * Get current workflow state
+   */
+  async getState() {
+    if (!await fs.pathExists(this.stateFile)) {
+      return null;
+    }
+    const content = await fs.readFile(this.stateFile, 'utf8');
+    return yaml.load(content);
+  }
+
+  /**
+   * Save workflow state
+   */
+  async saveState(state) {
+    await fs.ensureDir(path.dirname(this.stateFile));
+    await fs.writeFile(this.stateFile, yaml.dump(state, { indent: 2 }));
+  }
+
+  /**
+   * Transition to the next stage
+   */
+  async transitionTo(targetStage, notes = '') {
+    const state = await this.getState();
+    if (!state) {
+      throw new Error('No active workflow. Run initWorkflow first.');
+    }
+
+    const currentStage = state.currentStage;
+    const validTransitions = WORKFLOW_STAGES[currentStage]?.next || [];
+
+    if (!validTransitions.includes(targetStage)) {
+      throw new Error(
+        `Invalid transition: ${currentStage} → ${targetStage}. ` +
+        `Valid transitions: ${validTransitions.join(', ')}`
+      );
+    }
+
+    // Complete current stage
+    if (state.stages[currentStage]) {
+      state.stages[currentStage].completedAt = new Date().toISOString();
+      state.stages[currentStage].status = 'completed';
+      state.stages[currentStage].duration = this.calculateDuration(
+        state.stages[currentStage].enteredAt,
+        state.stages[currentStage].completedAt
+      );
+    }
+
+    // Enter new stage
+    state.stages[targetStage] = state.stages[targetStage] || {};
+    state.stages[targetStage].enteredAt = new Date().toISOString();
+    state.stages[targetStage].status = 'in-progress';
+    state.stages[targetStage].attempts = (state.stages[targetStage].attempts || 0) + 1;
+
+    state.currentStage = targetStage;
+
+    // Record history
+    state.history.push({
+      timestamp: new Date().toISOString(),
+      action: 'stage-transition',
+      from: currentStage,
+      to: targetStage,
+      notes
+    });
+
+    await this.saveState(state);
+    await this.recordMetric('stage_transition', {
+      from: currentStage,
+      to: targetStage,
+      feature: state.feature
+    });
+
+    return state;
+  }
+
+  /**
+   * Record a feedback loop (going back to a previous stage)
+   */
+  async recordFeedbackLoop(fromStage, toStage, reason) {
+    const state = await this.getState();
+    if (!state) return;
+
+    state.history.push({
+      timestamp: new Date().toISOString(),
+      action: 'feedback-loop',
+      from: fromStage,
+      to: toStage,
+      reason
+    });
+
+    await this.saveState(state);
+    await this.recordMetric('feedback_loop', {
+      from: fromStage,
+      to: toStage,
+      reason,
+      feature: state.feature
+    });
+  }
+
+  /**
+   * Complete the workflow
+   */
+  async completeWorkflow(notes = '') {
+    const state = await this.getState();
+    if (!state) {
+      throw new Error('No active workflow.');
+    }
+
+    state.completedAt = new Date().toISOString();
+    state.totalDuration = this.calculateDuration(state.startedAt, state.completedAt);
+    state.status = 'completed';
+
+    // Complete current stage
+    if (state.stages[state.currentStage]) {
+      state.stages[state.currentStage].completedAt = new Date().toISOString();
+      state.stages[state.currentStage].status = 'completed';
+    }
+
+    state.history.push({
+      timestamp: new Date().toISOString(),
+      action: 'workflow-completed',
+      notes
+    });
+
+    await this.saveState(state);
+    await this.recordMetric('workflow_completed', {
+      feature: state.feature,
+      totalDuration: state.totalDuration,
+      stageCount: Object.keys(state.stages).length
+    });
+
+    // Generate summary
+    return this.generateSummary(state);
+  }
+
+  /**
+   * Record a metric
+   */
+  async recordMetric(name, data) {
+    let metrics = [];
+    if (await fs.pathExists(this.metricsFile)) {
+      const content = await fs.readFile(this.metricsFile, 'utf8');
+      metrics = yaml.load(content) || [];
+    }
+
+    metrics.push({
+      timestamp: new Date().toISOString(),
+      name,
+      data
+    });
+
+    await fs.ensureDir(path.dirname(this.metricsFile));
+    await fs.writeFile(this.metricsFile, yaml.dump(metrics, { indent: 2 }));
+  }
+
+  /**
+   * Get workflow metrics summary
+   */
+  async getMetricsSummary() {
+    if (!await fs.pathExists(this.metricsFile)) {
+      return { message: 'No metrics recorded yet.' };
+    }
+
+    const content = await fs.readFile(this.metricsFile, 'utf8');
+    const metrics = yaml.load(content) || [];
+
+    const summary = {
+      totalWorkflows: 0,
+      completedWorkflows: 0,
+      feedbackLoops: 0,
+      stageTransitions: 0,
+      averageDuration: null,
+      stageStats: {}
+    };
+
+    const durations = [];
+
+    metrics.forEach(m => {
+      switch (m.name) {
+        case 'workflow_started':
+          summary.totalWorkflows++;
+          break;
+        case 'workflow_completed':
+          summary.completedWorkflows++;
+          if (m.data.totalDuration) {
+            durations.push(this.parseDuration(m.data.totalDuration));
+          }
+          break;
+        case 'feedback_loop':
+          summary.feedbackLoops++;
+          break;
+        case 'stage_transition': {
+          summary.stageTransitions++;
+          const to = m.data.to;
+          summary.stageStats[to] = summary.stageStats[to] || { visits: 0 };
+          summary.stageStats[to].visits++;
+          break;
+        }
+      }
+    });
+
+    if (durations.length > 0) {
+      const avgMs = durations.reduce((a, b) => a + b, 0) / durations.length;
+      summary.averageDuration = this.formatDuration(avgMs);
+    }
+
+    return summary;
+  }
+
+  /**
+   * Generate workflow summary
+   */
+  generateSummary(state) {
+    const stages = Object.entries(state.stages).map(([name, data]) => ({
+      name,
+      duration: data.duration || 'N/A',
+      attempts: data.attempts || 1
+    }));
+
+    const feedbackLoops = state.history.filter(h => h.action === 'feedback-loop');
+
+    return {
+      feature: state.feature,
+      totalDuration: state.totalDuration,
+      stages,
+      feedbackLoops: feedbackLoops.length,
+      feedbackDetails: feedbackLoops
+    };
+  }
+
+  /**
+   * Calculate duration between two ISO timestamps
+   */
+  calculateDuration(start, end) {
+    const ms = new Date(end) - new Date(start);
+    return this.formatDuration(ms);
+  }
+
+  /**
+   * Format milliseconds to human readable duration
+   */
+  formatDuration(ms) {
+    const seconds = Math.floor(ms / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const days = Math.floor(hours / 24);
+
+    if (days > 0) return `${days}d ${hours % 24}h`;
+    if (hours > 0) return `${hours}h ${minutes % 60}m`;
+    if (minutes > 0) return `${minutes}m`;
+    return `${seconds}s`;
+  }
+
+  /**
+   * Parse duration string to milliseconds
+   */
+  parseDuration(duration) {
+    const match = duration.match(/(\d+)([dhms])/g);
+    if (!match) return 0;
+
+    let ms = 0;
+    match.forEach(part => {
+      const value = parseInt(part);
+      const unit = part.slice(-1);
+      switch (unit) {
+        case 'd': ms += value * 24 * 60 * 60 * 1000; break;
+        case 'h': ms += value * 60 * 60 * 1000; break;
+        case 'm': ms += value * 60 * 1000; break;
+        case 's': ms += value * 1000; break;
+      }
+    });
+    return ms;
+  }
+
+  /**
+   * Get valid next stages from current state
+   */
+  async getValidTransitions() {
+    const state = await this.getState();
+    if (!state) return [];
+    return WORKFLOW_STAGES[state.currentStage]?.next || [];
+  }
+}
+
+module.exports = { WorkflowEngine, WORKFLOW_STAGES };