musubi-sdd 2.1.1 → 2.2.0

package/README.ja.md

@@ -1,10 +1,77 @@
-# MUSUBI
+<div align="center">
 
-> 7つのAIコーディングエージェント向け究極の仕様駆動開発ツール + MCP統合
+# 🎋 MUSUBI
 
-MUSUBIは、6つの主要フレームワークのベスト機能を統合した包括的なSDD（仕様駆動開発）フレームワークであり、複数のAIコーディングエージェントに対応した本番環境対応ツールです。
+**究極の仕様駆動開発ツール**
 
-## 🚀 v2.1.0 の新機能
+[![CI](https://github.com/nahisaho/musubi/actions/workflows/ci.yml/badge.svg)](https://github.com/nahisaho/musubi/actions/workflows/ci.yml)
+[![npm version](https://badge.fury.io/js/musubi-sdd.svg)](https://www.npmjs.com/package/musubi-sdd)
+[![npm downloads](https://img.shields.io/npm/dm/musubi-sdd.svg)](https://www.npmjs.com/package/musubi-sdd)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)
+
+[English](README.md) | [日本語](README.ja.md) | [ドキュメント](docs/) | [npm](https://www.npmjs.com/package/musubi-sdd)
+
+</div>
+
+---
+
+> 🤖 **7つのAIエージェント** × 📋 **25の専門スキル** × ⚖️ **憲法ガバナンス**
+
+MUSUBI（結び）は、6つの主要フレームワークのベスト機能を統合した包括的な**仕様駆動開発（SDD）**フレームワークです。複数のAIコーディングエージェントに対応した本番環境対応ツールです。
+
+<div align="center">
+
+![MUSUBI Demo](docs/assets/demo.svg)
+
+</div>
+
+## ✨ なぜMUSUBI？
+
+| 課題 | MUSUBIのソリューション |
+|------|----------------------|
+| 🔀 AIツールの分断 | **7エージェント、1つの統一ワークフロー** |
+| 📝 曖昧な要件定義 | **5パターンのEARS形式** |
+| 🔍 トレーサビリティの喪失 | **100% 要件→設計→コード→テスト追跡** |
+| ⚠️ 品質の不一致 | **9つの憲法条項 + フェーズ-1ゲート** |
+| 🔄 既存プロジェクトの課題 | **差分仕様 + 変更管理** |
+
+## 🚀 クイックスタート
+
+```bash
+# 30秒でインストール＆初期化
+npx musubi-sdd init
+
+# 既存プロジェクト向け - 自動分析とステアリングドキュメント生成
+npx musubi-sdd onboard
+
+# 完了！AIエージェントでSDDコマンドを使用:
+# Claude Code: /sdd-requirements, /sdd-design, /sdd-implement
+# GitHub Copilot: #sdd-requirements, #sdd-design, #sdd-implement
+```
+
+<details>
+<summary>📦 その他のインストールオプション</summary>
+
+```bash
+# グローバルインストール
+npm install -g musubi-sdd
+
+# 特定のAIエージェント向けに初期化
+musubi init --copilot   # GitHub Copilot
+musubi init --cursor    # Cursor IDE
+musubi init --gemini    # Gemini CLI
+musubi init --codex     # Codex CLI
+musubi init --qwen      # Qwen Code
+musubi init --windsurf  # Windsurf IDE
+```
+
+</details>
+
+---
+
+## 📊 v2.1.0 の新機能
 
 - 🔄 **ワークフローエンジン** - ステージ管理とメトリクス収集の新CLI `musubi-workflow`
 - 📊 **メトリクス収集** - ステージごとの所要時間、イテレーション回数、フィードバックループを追跡
@@ -837,6 +904,15 @@ musubi init
 
 貢献を歓迎します！ガイドラインについては[CONTRIBUTING.md](CONTRIBUTING.md)を参照してください。
 
+## ⭐ サポート
+
+MUSUBIが役立つと感じたら、ぜひ：
+
+- ⭐ **このリポジトリにスターを** - 他の人がMUSUBIを発見する助けになります
+- 🐛 **問題を報告** - 改善にご協力ください
+- 💡 **機能を提案** - あなたのアイデアを大切にします
+- 📝 **体験を共有** - ブログでMUSUBIについて書いてください
+
 ## ライセンス
 
 MITライセンス - 詳細は[LICENSE](LICENSE)を参照してください。
@@ -852,13 +928,22 @@ MUSUBIは以下のフレームワークから機能を統合しています。
 - **cc-sdd** - Pラベル並列化、検証ゲート
 - **spec-kit** - 憲法ガバナンス、テストファースト
 
-## 詳細情報
+## 📚 詳細情報
 
-- [ドキュメント](https://musubi-sdd.dev)
-- [ブループリント](Ultimate-SDD-Tool-Blueprint-v3-25-Skills.md)
-- [プロジェクト計画](PROJECT-PLAN-MUSUBI.md)
-- [フレームワーク比較](SDD-Framework-Comparison-Report.md)
+- [📖 ドキュメント](docs/)
+- [📋 SRS v3.0.0](docs/requirements/srs/srs-musubi-v3.0.0.ja.md)
+- [📅 プロジェクト計画 v3.0.0](docs/plans/project-plan-v3.0.0.ja.md)
+- [🏗️ ブループリント](Ultimate-SDD-Tool-Blueprint-v3-25-Skills.md)
+- [📊 プロジェクト計画](PROJECT-PLAN-MUSUBI.md)
 
 ---
 
-**MUSUBI** - むすび - 仕様、設計、コードを結びつける。
+<div align="center">
+
+**🎋 MUSUBI** - むすび - 仕様、設計、コードを結びつける。
+
+[![GitHub stars](https://img.shields.io/github/stars/nahisaho/musubi?style=social)](https://github.com/nahisaho/musubi)
+
+Made with ❤️ for the AI Coding Community
+
+</div>

package/README.md

@@ -1,14 +1,77 @@
-# MUSUBI
+<div align="center">
+
+# 🎋 MUSUBI
+
+**Ultimate Specification Driven Development Tool**
 
 [![CI](https://github.com/nahisaho/musubi/actions/workflows/ci.yml/badge.svg)](https://github.com/nahisaho/musubi/actions/workflows/ci.yml)
 [![npm version](https://badge.fury.io/js/musubi-sdd.svg)](https://www.npmjs.com/package/musubi-sdd)
+[![npm downloads](https://img.shields.io/npm/dm/musubi-sdd.svg)](https://www.npmjs.com/package/musubi-sdd)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)
+
+[English](README.md) | [日本語](README.ja.md) | [Documentation](docs/) | [npm](https://www.npmjs.com/package/musubi-sdd)
+
+</div>
+
+---
+
+> 🤖 **7 AI Coding Agents** × 📋 **25 Specialized Skills** × ⚖️ **Constitutional Governance**
+
+MUSUBI (結び - "connection/binding") is a comprehensive **Specification Driven Development (SDD)** framework that synthesizes the best features from 6 leading frameworks into a production-ready tool for multiple AI coding agents.
+
+<div align="center">
+
+![MUSUBI Demo](docs/assets/demo.svg)
+
+</div>
+
+## ✨ Why MUSUBI?
+
+| Challenge | MUSUBI Solution |
+|-----------|-----------------|
+| 🔀 Fragmented AI tools | **7 agents, 1 unified workflow** |
+| 📝 Ambiguous requirements | **EARS format with 5 patterns** |
+| 🔍 Lost traceability | **100% Req→Design→Code→Test mapping** |
+| ⚠️ Quality inconsistency | **9 Constitutional Articles + Phase -1 Gates** |
+| 🔄 Brownfield challenges | **Delta specs + Change management** |
+
+## 🚀 Quick Start
+
+```bash
+# Install and initialize in 30 seconds
+npx musubi-sdd init
 
-> Ultimate Specification Driven Development Tool for 7 AI Coding Agents + MCP Integration
+# For existing projects - auto-analyze and generate steering docs
+npx musubi-sdd onboard
 
-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.
+# That's it! Now use your AI agent with SDD commands:
+# Claude Code: /sdd-requirements, /sdd-design, /sdd-implement
+# GitHub Copilot: #sdd-requirements, #sdd-design, #sdd-implement
+```
+
+<details>
+<summary>📦 More installation options</summary>
+
+```bash
+# Global installation
+npm install -g musubi-sdd
 
-## 🚀 What's New in v2.1.0
+# Initialize for specific AI agent
+musubi init --copilot   # GitHub Copilot
+musubi init --cursor    # Cursor IDE
+musubi init --gemini    # Gemini CLI
+musubi init --codex     # Codex CLI
+musubi init --qwen      # Qwen Code
+musubi init --windsurf  # Windsurf IDE
+```
+
+</details>
+
+---
+
+## 📊 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
@@ -1043,6 +1106,15 @@ musubi init
 
 Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
+## ⭐ Support
+
+If you find MUSUBI useful, please consider:
+
+- ⭐ **Star this repository** - It helps others discover MUSUBI
+- 🐛 **Report issues** - Help us improve
+- 💡 **Suggest features** - We value your ideas
+- 📝 **Share your experience** - Write about MUSUBI on your blog
+
 ## License
 
 MIT License - see [LICENSE](LICENSE) for details.
@@ -1058,13 +1130,22 @@ MUSUBI synthesizes features from:
 - **cc-sdd** - P-label parallelization, validation gates
 - **spec-kit** - Constitutional governance, test-first
 
-## Learn More
+## 📚 Learn More
 
-- [Documentation](https://musubi-sdd.dev)
-- [Blueprint](Ultimate-SDD-Tool-Blueprint-v3-25-Skills.md)
-- [Project Plan](PROJECT-PLAN-MUSUBI.md)
-- [Framework Comparison](SDD-Framework-Comparison-Report.md)
+- [📖 Documentation](docs/)
+- [📋 SRS v3.0.0](docs/requirements/srs/srs-musubi-v3.0.0.md)
+- [📅 Project Plan v3.0.0](docs/plans/project-plan-v3.0.0.md)
+- [🏗️ Blueprint](Ultimate-SDD-Tool-Blueprint-v3-25-Skills.md)
+- [📊 Project Plan](PROJECT-PLAN-MUSUBI.md)
 
 ---
 
-**MUSUBI** - むすび - Bringing specifications, design, and code together.
+<div align="center">
+
+**🎋 MUSUBI** - むすび - Bringing specifications, design, and code together.
+
+[![GitHub stars](https://img.shields.io/github/stars/nahisaho/musubi?style=social)](https://github.com/nahisaho/musubi)
+
+Made with ❤️ for the AI Coding Community
+
+</div>

package/bin/musubi-analyze.js

@@ -60,10 +60,11 @@ program
   .name('musubi-analyze')
   .description('Analyze codebase for quality, complexity, and technical debt')
   .version('0.5.0')
-  .option('-t, --type <type>', 'Analysis type: quality, dependencies, security, all', 'all')
+  .option('-t, --type <type>', 'Analysis type: quality, dependencies, security, stuck, all', 'all')
   .option('-o, --output <file>', 'Output file for analysis report')
   .option('--json', 'Output in JSON format')
   .option('--threshold <level>', 'Quality threshold: low, medium, high', 'medium')
+  .option('--detect-stuck', 'Detect stuck agent patterns (repetitive errors, circular edits)')
   .option('-v, --verbose', 'Verbose output')
   .parse(process.argv);
 
@@ -405,6 +406,210 @@ async function generateReport(analysisData) {
   log(`Report saved to: ${reportPath}`, 'success');
 }
 
+// ============================================================================
+// Stuck Detection Analysis
+// ============================================================================
+
+async function analyzeStuckPatterns() {
+  log('Stuck Pattern Analysis', 'analyze');
+  console.log();
+
+  const stuckPatterns = {
+    isStuck: false,
+    confidence: 0,
+    patterns: [],
+    suggestions: []
+  };
+
+  try {
+    // Check git log for repetitive patterns
+    const { execSync } = require('child_process');
+    
+    // Get recent commits
+    let commits = [];
+    try {
+      const gitLog = execSync(
+        'git log --oneline -20 --format="%h|%s" 2>/dev/null',
+        { encoding: 'utf8' }
+      ).trim();
+      commits = gitLog.split('\n').filter(Boolean).map(line => {
+        const [hash, ...msgParts] = line.split('|');
+        return { hash, message: msgParts.join('|') };
+      });
+    } catch {
+      // Not in git repo or no commits
+    }
+
+    // Pattern 1: Repetitive revert/fix cycles
+    const revertPattern = commits.filter(c => 
+      c.message.toLowerCase().includes('revert') ||
+      c.message.toLowerCase().includes('undo')
+    );
+    if (revertPattern.length >= 3) {
+      stuckPatterns.patterns.push({
+        type: 'revert-cycle',
+        severity: 'high',
+        message: `${revertPattern.length} revert commits detected in recent history`,
+        commits: revertPattern.slice(0, 3).map(c => c.message)
+      });
+      stuckPatterns.confidence += 30;
+    }
+
+    // Pattern 2: Same file edited repeatedly
+    let recentChanges = [];
+    try {
+      const gitDiff = execSync(
+        'git diff --stat HEAD~5 HEAD 2>/dev/null',
+        { encoding: 'utf8' }
+      ).trim();
+      recentChanges = gitDiff.split('\n').filter(Boolean);
+    } catch {
+      // No recent changes or not enough history
+    }
+
+    const fileEditCounts = {};
+    for (let i = 0; i < Math.min(commits.length, 10); i++) {
+      try {
+        const files = execSync(
+          `git show --name-only --format= ${commits[i].hash} 2>/dev/null`,
+          { encoding: 'utf8' }
+        ).trim().split('\n').filter(Boolean);
+        files.forEach(f => {
+          fileEditCounts[f] = (fileEditCounts[f] || 0) + 1;
+        });
+      } catch {
+        // Skip this commit
+      }
+    }
+
+    const frequentlyEdited = Object.entries(fileEditCounts)
+      .filter(([, count]) => count >= 4)
+      .map(([file, count]) => ({ file, count }));
+
+    if (frequentlyEdited.length > 0) {
+      stuckPatterns.patterns.push({
+        type: 'circular-edit',
+        severity: 'medium',
+        message: 'Files being edited repeatedly without resolution',
+        files: frequentlyEdited
+      });
+      stuckPatterns.confidence += 25;
+    }
+
+    // Pattern 3: Test failures in recent runs
+    const testResultsPath = path.join(process.cwd(), 'coverage', 'test-results.json');
+    if (fs.existsSync(testResultsPath)) {
+      try {
+        const testResults = fs.readJsonSync(testResultsPath);
+        if (testResults.numFailedTests > 0) {
+          stuckPatterns.patterns.push({
+            type: 'test-failure',
+            severity: 'medium',
+            message: `${testResults.numFailedTests} tests failing`,
+            failedTests: testResults.testResults?.filter(t => t.status === 'failed').slice(0, 5)
+          });
+          stuckPatterns.confidence += 20;
+        }
+      } catch {
+        // Cannot read test results
+      }
+    }
+
+    // Pattern 4: Error log patterns
+    const errorLogPath = path.join(process.cwd(), 'logs', 'error.log');
+    if (fs.existsSync(errorLogPath)) {
+      try {
+        const errorLog = fs.readFileSync(errorLogPath, 'utf8');
+        const recentErrors = errorLog.split('\n').slice(-50);
+        const errorCounts = {};
+        recentErrors.forEach(line => {
+          const match = line.match(/Error: (.+)/);
+          if (match) {
+            const key = match[1].slice(0, 50);
+            errorCounts[key] = (errorCounts[key] || 0) + 1;
+          }
+        });
+
+        const repetitiveErrors = Object.entries(errorCounts)
+          .filter(([, count]) => count >= 3)
+          .map(([error, count]) => ({ error, count }));
+
+        if (repetitiveErrors.length > 0) {
+          stuckPatterns.patterns.push({
+            type: 'repetitive-error',
+            severity: 'high',
+            message: 'Same errors occurring repeatedly',
+            errors: repetitiveErrors
+          });
+          stuckPatterns.confidence += 30;
+        }
+      } catch {
+        // Cannot read error log
+      }
+    }
+
+    // Determine if stuck
+    stuckPatterns.isStuck = stuckPatterns.confidence >= 50;
+
+    // Generate suggestions based on patterns
+    if (stuckPatterns.patterns.some(p => p.type === 'revert-cycle')) {
+      stuckPatterns.suggestions.push('Consider stepping back to review the overall approach');
+      stuckPatterns.suggestions.push('Break down the problem into smaller, testable pieces');
+    }
+    if (stuckPatterns.patterns.some(p => p.type === 'circular-edit')) {
+      stuckPatterns.suggestions.push('Focus on one file at a time and verify changes work');
+      stuckPatterns.suggestions.push('Run tests after each change to catch issues early');
+    }
+    if (stuckPatterns.patterns.some(p => p.type === 'test-failure')) {
+      stuckPatterns.suggestions.push('Fix failing tests before making new changes');
+      stuckPatterns.suggestions.push('Review test expectations vs implementation');
+    }
+    if (stuckPatterns.patterns.some(p => p.type === 'repetitive-error')) {
+      stuckPatterns.suggestions.push('Address root cause of repetitive errors');
+      stuckPatterns.suggestions.push('Consider using different approach if error persists');
+    }
+
+    // Display results
+    if (stuckPatterns.isStuck) {
+      console.log(chalk.bold.red('🚨 Stuck Pattern Detected!\n'));
+    } else if (stuckPatterns.patterns.length > 0) {
+      console.log(chalk.bold.yellow('⚠️ Potential Issues Found\n'));
+    } else {
+      console.log(chalk.bold.green('✓ No stuck patterns detected\n'));
+      return stuckPatterns;
+    }
+
+    console.log(chalk.dim(`Confidence: ${stuckPatterns.confidence}%\n`));
+
+    stuckPatterns.patterns.forEach(pattern => {
+      const severityColor = {
+        high: chalk.red,
+        medium: chalk.yellow,
+        low: chalk.blue
+      }[pattern.severity] || chalk.white;
+
+      console.log(severityColor(`[${pattern.severity.toUpperCase()}] ${pattern.type}`));
+      console.log(chalk.dim(`  ${pattern.message}`));
+      console.log();
+    });
+
+    if (stuckPatterns.suggestions.length > 0) {
+      console.log(chalk.bold('Suggestions:'));
+      stuckPatterns.suggestions.forEach(s => {
+        console.log(chalk.cyan(`  → ${s}`));
+      });
+      console.log();
+    }
+
+    return stuckPatterns;
+  } catch (error) {
+    if (options.verbose) {
+      log(`Stuck analysis error: ${error.message}`, 'error');
+    }
+    return stuckPatterns;
+  }
+}
+
 // ============================================================================
 // Main Function
 // ============================================================================
@@ -415,6 +620,19 @@ async function main() {
   const analysisData = {};
 
   try {
+    // Handle --detect-stuck option
+    if (options.detectStuck || options.type === 'stuck') {
+      analysisData.stuck = await analyzeStuckPatterns();
+      
+      if (options.json) {
+        console.log(JSON.stringify(analysisData.stuck, null, 2));
+      }
+      
+      if (options.type === 'stuck') {
+        process.exit(analysisData.stuck?.isStuck ? 1 : 0);
+      }
+    }
+
     if (options.type === 'quality' || options.type === 'all') {
       analysisData.quality = await analyzeQuality();
     }