🎋 MUSUBI

Ultimate Specification Driven Development Tool

</div>

🤖 7 AI Coding Agents × 📋 31 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.

MUSUBI Demo

</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

# Install and initialize in 30 seconds
npx musubi-sdd init

# For existing projects - auto-analyze and generate steering docs
npx musubi-sdd onboard

# 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>

# Global installation
npm install -g musubi-sdd

# 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 v6.3.0

SDD Document Path Unification 📂

Complete separation of document types for better organization and clarity.

Storage Structure

| Document Type | Storage Path | Naming Pattern | |---------------|--------------|----------------| | Requirements | storage/specs/ | {feature}-requirements.md | | Design | storage/design/ | {feature}-design.md | | Tasks | storage/tasks/ | {feature}-tasks.md | | Validation | storage/validation/ | {feature}-validation-report.md |

storage/
├── specs/          # Requirements only
│   └── auth-requirements.md
├── design/         # Design documents only
│   └── auth-design.md
├── tasks/          # Tasks only
│   └── auth-tasks.md
└── validation/     # Validation reports
    └── auth-validation-report.md

Updated All 7 Agent Platforms

All prompts and templates updated with correct storage paths:

Claude Code, GitHub Copilot, Cursor, Gemini CLI, Codex CLI, Qwen Code, Windsurf

Test Results

Unit Tests: 4,827 passing ✅
Integration Tests: 660 passing ✅

📊 What's New in v6.2.0

Review Gate Engine 🛡️

New quality gates for systematic review at each development stage.

Review Gates

| Gate | Description | Prompt | |------|-------------|--------| | Requirements Gate | EARS format, priority, acceptance criteria validation | #sdd-review-requirements | | Design Gate | C4 model, ADR, component design validation | #sdd-review-design | | Implementation Gate | Code quality, test coverage, naming conventions | #sdd-review-implementation | | Full Review | All gates in sequence | #sdd-review-all |

# Use review prompts in your AI agent
#sdd-review-requirements user-auth
#sdd-review-design user-auth
#sdd-review-implementation user-auth

Workflow Dashboard

Progress Visualization: Real-time progress across 5 stages
Blocker Management: Add, resolve, and track blockers
Transition Recording: Record and analyze stage transitions
Sprint Planning: Task prioritization with velocity tracking

musubi dashboard show <feature>     # Show workflow status
musubi dashboard start <feature>    # Start new workflow
musubi dashboard blocker <feature>  # Manage blockers

Traceability System

Auto-Extraction: Automatic ID extraction from code, tests, commits
Gap Detection: Detect missing design, implementation, or tests
Matrix Storage: YAML-based traceability matrix with history

musubi-trace extract <dir>   # Extract traceability IDs
musubi-trace gaps <feature>  # Detect gaps
musubi-trace matrix          # Generate matrix report

Enterprise Features

| Feature | Description | |---------|-------------| | Error Recovery | Auto error analysis with remediation steps | | Rollback Manager | File/commit/stage/sprint level rollback | | CI Reporter | GitHub Actions integration | | Phase -1 Gate | Constitutional compliance before all stages | | Steering Sync | Auto-update steering files on version change |

📊 What's New in v5.9.0

Phase 1-4 Enterprise Features 🏢

Major update with enterprise-ready features for large-scale projects and monorepo support.

Workflow Flexibility (Phase 1)

3 Workflow Modes: small (bug fixes), medium (features), large (architecture)
Auto-detection: Smart mode selection based on feature name patterns
musubi-release: New CLI for release automation with CHANGELOG generation

# Generate CHANGELOG from commits
musubi-release

# Show detected mode for a feature
musubi-workflow mode --detect "feat: user authentication"

Monorepo Support (Phase 2)

Package Registry: steering/packages.yml for dependency management
Dependency Graphs: Mermaid diagram generation for visualization
Coverage Tracking: Per-package test coverage reporting

Constitution Level Management (Phase 3)

3 Enforcement Levels: critical (blocking), advisory (warnings), flexible (suggestions)
Level-aware Validation: Different enforcement based on article importance
Project Overrides: Custom levels per project type

| Level | Articles | Behavior | |-------|----------|----------| | Critical | CONST-001, 002, 003, 005, 009 | Blocks workflow | | Advisory | CONST-004, 006, 007 | Warnings only | | Flexible | CONST-008 | Suggestions |

Project Configuration (Phase 4)

musubi-config: New CLI for configuration management
Schema Validation: v2.0 schema with AJV validation
Auto-migration: Upgrade v1.0 configs to v2.0

musubi-config validate  # Validate project.yml
musubi-config migrate   # Migrate to v2.0
musubi-config show      # Show effective config

Orchestrator Integration

5 new built-in skills for programmatic access:

| Skill | Category | Usage | |-------|----------|-------| | release-manager | release | CHANGELOG generation | | workflow-mode-manager | workflow | Mode detection & management | | package-manager | configuration | Package & dependency analysis | | constitution-level-manager | validation | Level-aware validation | | project-config-manager | configuration | Config validation & migration |

const { workflowModeSkill } = require('musubi-sdd/src/orchestration');

const result = await workflowModeSkill.execute({
  action: 'detect',
  featureName: 'fix: minor bug'
});
console.log(result.detectedMode); // 'small'

📊 What's New in v5.8.0

CodeGraph MCP v0.8.0 Integration 🔗

Major update to CodeGraph MCP integration with expanded language support and new features.

16 Language Support (NEW: Kotlin, Swift, Scala, Lua)

Python, TypeScript, JavaScript - Full AST analysis
Rust, Go, Java, PHP, C# - Enterprise language support
C, C++, HCL (Terraform) - System and infrastructure code
Ruby - Dynamic language support
Kotlin (NEW) - .kt, .kts files with classes, interfaces, functions
Swift (NEW) - .swift files with classes, structs, protocols
Scala (NEW) - .scala, .sc files with traits, objects
Lua (NEW) - .lua files with functions, table assignments

File Watching & Auto Re-indexing

codegraph-mcp watch - Real-time file monitoring
Debounce configuration - Configurable delay (default: 1.0s)
Community detection - Optional --community flag after re-index

Enhanced MCP Tools (14 Tools)

| Category | Tools | |----------|-------| | Graph Query | query_codebase, find_dependencies, find_callers, find_callees, find_implementations, analyze_module_structure | | Code Retrieval | get_code_snippet, read_file_content, get_file_structure | | GraphRAG | global_search, local_search | | Management | suggest_refactoring, reindex_repository, execute_shell_command |

Security & Performance (v0.7.3)

Security fixes: Path traversal and command injection protection
Connection pooling: Improved database performance
Caching: Faster repeated queries

// Use CodeGraph MCP integration
const { CodeGraphIntegration } = require('musubi-sdd');

const cg = new CodeGraphIntegration('/path/to/repo');
await cg.indexRepository();

// File watching (v0.7.0+)
await cg.startWatch({ debounce: 2.0, community: true });

// Query codebase

MUSUBI

Install / Use

README