🤖 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.

✨ Why MUSUBI?

🚀 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

# 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

📊 What's New in v6.2.0

Review Gate Engine 🛡️

New quality gates for systematic review at each development stage.

Review Gates

# 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

📊 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

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:

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)

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
const results = await cg.queryCodebase('authentication');
const callers = await cg.findCallers('UserService::login');

📊 What's New in v5.6.0

Enterprise-Scale Analysis & Rust Migration Support 🏢🦀

Major improvements based on analysis of GCC codebase (10+ million lines, 100,000+ files).

Large Project Analyzer

• Scale-aware analysis: Automatically detects project size and selects appropriate strategy
• Memory-efficient processing: Chunk-based processing with garbage collection for 100K+ files
• Multi-language support: JavaScript, TypeScript, C, C++, Python, Rust, Go, Java
• Giant function detection: Flags functions with 100+ (warning), 500+ (critical), 1000+ (extreme) lines

CodeGraph MCP Integration

• Deep code graph analysis: Integration with CodeGraph MCP for relationship analysis
• Call graph generation: Track callers and callees with configurable depth
• Impact analysis: Identify affected files when code changes
• Hotspot identification: Detect highly-connected entities (refactoring candidates)

Enhanced Complexity Analyzer

• Cyclomatic complexity: Standard decision-point counting
• Cognitive complexity: SonarSource-style readability measurement
• Severity levels: Ideal → Warning → Critical → Extreme thresholds

Rust Migration Generator

• Unsafe pattern detection: Identify C/C++ memory-unsafe patterns
• Migration priority scoring: Automatic prioritization for Rust migration
• Security component analysis: Flag security-critical code sections

// Analyze enterprise-scale projects (100,000+ files)
const { LargeProjectAnalyzer, ComplexityAnalyzer } = require('musubi-sdd');

const analyzer = new LargeProjectAnalyzer('/path/to/gcc');
const result = await analyzer.analyze();
console.log(result.stats); // { totalFiles: 109073, ... }

// Calculate code complexity
const complexity = new ComplexityAnalyzer();
const score = complexity.calculateCyclomaticComplexity(code, 'javascript');

v5.4.0: GitHub Reference & Repository Analysis 📦

• 🔗 --reference / -r Option - Reference multiple GitHub repositories for pattern analysis
• 📊 Repository Analysis - Fetch metadata, structure, and key files via GitHub API
• 🏗️ Pattern Detection - Clean Architecture, Hexagonal, DDD, Monorepo patterns
• 💡 Improvement Suggestions - Architecture and technology recommendations
• 📁 Analysis Output - Saved to steering/references/github-references-YYYY-MM-DD.md

# Reference multiple repositories for improvement suggestions
musubi init -r facebook/react -r vercel/next.js -r denoland/deno

# With branch specification
musubi init --reference tokio-rs/tokio@main

# Full URL format
musubi init --reference https://github.com/rust-lang/rust

v5.3.0: Multi-Language Support 🌐

• 🔄 Technology Stack Selection - Single, Multiple, Undecided, or Help me decide
• 🤖 Language Recommendation Engine - AI-powered suggestions based on app type, performance needs, team expertise
• 🌍 10 Languages Supported - JS/TS, Python, Rust, Go, Java, C#, C++, Swift, Ruby, PHP
• 📄 Dynamic tech.md - Language-specific templates with frameworks and tools

v5.0.0: Phase 5 Advanced Features 🚀

• 🔄 Steering Auto-Update - Automatic project memory synchronization with 5 trigger types
• ✅ Steering Validator - Comprehensive validation for steering documents
• 📋 Template Constraints - Enforce structure requirements with ThinkingChecklist
• 📊 Quality Dashboard - A-F grade metrics with health status monitoring
• 🔍 Advanced Validation - Cross-artifact consistency, gap detection, traceability validation
• 🎯 Phase 5 Integration - Unified access to all advanced features

v4.0.0: Phase 4 Agent Loop & Agentic Features 🤖

• 🧠 Codebase Intelligence - RepositoryMap, ASTExtractor, ContextOptimizer
• 💭 Agentic Reasoning - ReasoningEngine, PlanningEngine, SelfCorrection
• ⚡ Code Generation - CodeGenerator, CodeReviewer with multiple modes
• 🔗 Integrated Agent - Unified agent with all Phase 4 capabilities

# Use advanced features via orchestrator
const { Phase5Integration, createIntegratedAgent } = require('musubi-sdd');

# Quality dashboard
const dashboard = new QualityDashboard();
const metrics = await dashboard.collectMetrics(projectPath);

# Advanced validation
const validator = new AdvancedValidation();
const result = await validator.validateAll(projectPath);

Previous Highlights (v3.11.0)

• 🌐 WebSocket Real-time GUI - Live replanning updates with musubi-browser dashboard
• 📋 GUI Quick Actions - Modal dialog for New Requirement, Validate Project, Export Report
• 🔄 GitHub Actions Integration - musubi-action for CI/CD with MUSUBI validation
• 🔧 OpenAPI Converter - Convert OpenAPI 3.x/Swagger 2.x specs to MUSUBI format
• 🌍 Multi-language Templates - 7 language support (EN, JA, ZH, KO, ES, DE, FR)
• 🤖 Ollama Integration - Local LLM support with 9 model presets

Previous (v3.6.0)

• 🧠 Dynamic Replanning Engine - AI agents can now dynamically adjust plans when tasks fail
• 🔌 LLM Provider Abstraction - Multi-provider support (Copilot, Anthropic, OpenAI)
• 📡 Real-time Plan Monitoring - Detect failures, timeouts, and quality degradation
• 🔄 Alternative Path Generation - LLM-powered alternative strategies with confidence scoring
• 📝 Replan History & Audit - Full audit trail with JSONL persistence and export

Previous (v3.5.1)

• 🔄 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 (v3.5.1)

• 🔧 CLI Integration - Added CLI command references to all 8 Claude Code skills
• 📚 Platform Documentation - CLI Commands section added to all 6 non-Claude platforms

v2.1.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

Features

• 🤖 Multi-Agent Support - Works with 7 AI coding agents (Claude Code, GitHub Copilot, Cursor, Gemini CLI, Codex CLI, Qwen Code, Windsurf)
• 🧠 Dynamic Replanning - AI agents dynamically adjust plans on failure with LLM-powered alternatives (v3.6.0+)
• 🔌 MCP Server Integration - CodeGraphMCPServer for advanced code analysis (v2.0.0)
• 📄 Flexible Command Formats - Supports Markdown, TOML, and AGENTS.md formats
• 🎯 27 Specialized Skills (All Platforms) - 25 platform agents + 5 orchestrator built-in skills (v5.9.0)
  • Claude Code: Skills API (25 skills + 5 built-in)
  • GitHub Copilot & Cursor: AGENTS.md (official support)
  • Other 4 agents: AGENTS.md (compatible format)
• 📋 Constitutional Governance - 9 immutable articles + Phase -1 Gates for quality enforcement
• 📝 EARS Requirements Generator - Create unambiguous requirements with 5 EARS patterns (v0.8.0)
• 🏗️ Design Document Generator - Create C4 models and ADRs with traceability (v0.8.2)
• 🔄 Change Management System - Delta specifications for brownfield projects (v0.8.6)
• 🔍 Gap Detection System - Identify orphaned requirements and untested code (v0.8.7)
• 🧭 Auto-Updating Project Memory - Steering system maintains architecture, tech stack, and product context
• 🚀 Automatic Onboarding - musubi-onboard analyzes existing projects and generates steering docs (2-5 minutes)
• 🔄 Auto-Sync - musubi-sync detects codebase changes and keeps steering docs current
• 🔍 Intelligent Code Analysis - musubi-analyze provides quality metrics, complexity analysis, and technical debt detection
• 🤝 Team Collaboration - musubi-share enables memory sharing, import/export, and multi-platform sync (v0.6.0)
• ✅ Constitutional Validation - musubi-validate enforces 9 immutable governance articles with Phase -1 Gates (v0.7.0)
• ✅ Complete Traceability - Requirements → Design → Code → Tests mapping
• 🌐 Bilingual Documentation - All agent-generated documents created in both English and Japanese

Supported AI Coding Agents

MUSUBI supports 7 AI coding agents, each with tailored configurations:

Notes:

• Skills API is exclusive to Claude Code
• All 7 platforms now support 27 skills via Skills API (Claude Code) or AGENTS.md (others)
• v5.9.0 added 5 built-in orchestrator skills (release, workflow, package, constitution-level, project-config)
• GitHub Copilot uses .prompt.md extension per VS Code official documentation
• AGENTS.md: OpenAI specification, officially supported by GitHub Copilot & Cursor
• Gemini CLI uses TOML format + GEMINI.md integration

Constitutional Governance

MUSUBI enforces 9 Constitutional Articles for quality assurance:

# Validate constitutional compliance
musubi-validate all
musubi-validate constitution
musubi-validate gates
musubi-validate complexity

9 Articles:

1. Library-First Principle - All features begin as independent libraries
2. CLI Interface Mandate - All libraries expose CLI functionality
3. Test-First Imperative - Tests written before code (80% coverage required)
4. EARS Requirements Format - 5 EARS patterns for unambiguous requirements
5. Traceability Mandate - 100% traceability: Requirements ↔ Design ↔ Code ↔ Tests
6. Project Memory - Steering system maintains project context
7. Simplicity Gate - Maximum 3 sub-projects initially (Phase -1 Gate)
8. Anti-Abstraction Gate - Use framework APIs directly (Phase -1 Gate)
9. Integration-First Testing - Integration tests use real services (no mocks)

Phase -1 Gates: Pre-implementation validation checkpoints for Articles VII & VIII. See:

• steering/rules/constitution.md - Full constitutional text
• steering/rules/phase-gates.md - Approval process and active gates
• All other agents use Markdown format + AGENTS.md

Quick Start

Installation via npx

# Initialize MUSUBI for your preferred agent

# Claude Code (default) - 27 Skills (25 + 5 built-in)
npx musubi-sdd init
npx musubi-sdd init --claude

# GitHub Copilot - 27 skills (AGENTS.md, official support)
npx musubi-sdd init --copilot

# Cursor IDE - 27 skills (AGENTS.md, official support)
npx musubi-sdd init --cursor

# Gemini CLI - 27 skills (GEMINI.md integration)
npx musubi-sdd init --gemini

# Codex CLI - 27 skills (AGENTS.md)
npx musubi-sdd init --codex

# Qwen Code - 27 skills (AGENTS.md)
npx musubi-sdd init --qwen

# Windsurf IDE - 27 skills (AGENTS.md)
npx musubi-sdd init --windsurf

# Or install globally
npm install -g musubi-sdd
musubi init --claude    # or --copilot, --cursor, etc.

# Onboard existing project (automatic analysis)
musubi-onboard

# Synchronize steering docs with codebase
musubi-sync
musubi-sync --dry-run        # Preview changes
musubi-sync --auto-approve   # Auto-apply (CI/CD)

# Analyze code quality (v0.5.0)
musubi-analyze                      # Full analysis
musubi-analyze --type=quality       # Quality metrics only
musubi-analyze --type=dependencies  # Dependencies only
musubi-analyze --type=security      # Security audit
musubi-analyze --output=report.md   # Save report

# Share project memories with team (v0.6.0)
musubi-share export                 # Export memories to JSON
musubi-share import memories.json   # Import from teammate
musubi-share sync --platform=copilot # Sync to specific platform

# Validate constitutional compliance (v0.7.0)
musubi-validate constitution        # Validate all 9 articles
musubi-validate article 3           # Validate Test-First Imperative
musubi-validate gates               # Validate Phase -1 Gates
musubi-validate complexity          # Check complexity limits
musubi-validate all -v              # Full validation with details

# Generate EARS requirements documents (v0.8.0)
musubi-requirements init "User Authentication"  # Initialize requirements doc
musubi-requirements add                         # Add requirement interactively
musubi-requirements list                        # List all requirements
musubi-requirements validate                    # Validate EARS format
musubi-requirements trace                       # Show traceability matrix

# Generate design documents (v0.8.2)
musubi-design init "User Authentication"        # Initialize design document
musubi-design add-c4 context                    # Add C4 Context diagram
musubi-design add-c4 container --format plantuml # Add Container with PlantUML
musubi-design add-adr "Use JWT for tokens"      # Add Architecture Decision
musubi-design validate                          # Validate design completeness
musubi-design trace                             # Show requirements traceability

# Break down design into tasks (v0.8.4)
musubi-tasks init "User Authentication"         # Initialize task breakdown
musubi-tasks add "Database Schema"              # Add task interactively
musubi-tasks list                               # List all tasks
musubi-tasks list --priority P0                 # List critical tasks
musubi-tasks update 001 "In Progress"           # Update task status
musubi-tasks validate                           # Validate task completeness
musubi-tasks graph                              # Show dependency graph

# End-to-end traceability (v0.8.5)
musubi-trace matrix                             # Generate traceability matrix
musubi-trace matrix --format markdown > trace.md # Export to markdown
musubi-trace coverage                           # Calculate coverage statistics
musubi-trace coverage --min-coverage 100        # Require 100% coverage
musubi-trace gaps                               # Detect orphaned requirements/code
musubi-trace requirement REQ-AUTH-001           # Trace specific requirement
musubi-trace validate                           # Validate 100% traceability (Article V)
musubi-trace bidirectional                      # Bidirectional traceability analysis (v0.9.4)
musubi-trace impact REQ-AUTH-001                # Impact analysis for requirement changes (v0.9.4)
musubi-trace statistics                         # Comprehensive project statistics (v0.9.4)

# Change management for brownfield projects (v0.8.6)
musubi-change init CHANGE-001 --title "Add authentication"  # Create change proposal
musubi-change validate CHANGE-001 --verbose     # Validate delta specification
musubi-change apply CHANGE-001 --dry-run        # Preview changes
musubi-change apply CHANGE-001                  # Apply changes to codebase
musubi-change archive CHANGE-001                # Archive to specs/
musubi-change list --status pending             # List pending changes
musubi-change list --format json                # List in JSON format

# Gap detection and coverage validation (v0.8.7)
musubi-gaps detect                              # Detect all gaps
musubi-gaps detect --verbose                    # Show detailed gap information
musubi-gaps requirements                        # Detect orphaned requirements
musubi-gaps code                                # Detect untested code
musubi-gaps coverage                            # Calculate coverage statistics
musubi-gaps coverage --min-coverage 100         # Require 100% coverage
musubi-gaps detect --format markdown > gaps.md  # Export gap report

Documentation

Comprehensive guides are available in docs/guides/:

• Brownfield Tutorial - Step-by-step guide for managing changes in existing projects
• Delta Specification Guide - Format reference for change tracking
• Change Management Workflow - End-to-end workflow documentation
• Traceability Matrix Guide - Traceability system usage
• Video Tutorial Plan - Video content script

Project Types

During initialization, MUSUBI asks you to select a Project Type. This determines the workflow and features available:

Greenfield (0→1)

• What it is: Starting a new project from scratch
• Use cases:
  • New application development
  • Proof-of-concept projects
  • Greenfield microservices
• Features enabled:
  • Full 8-stage SDD workflow (Research → Monitoring)
  • /sdd-steering - Generate initial project memory
  • /sdd-requirements - Create new requirements from scratch
  • /sdd-design - Design architecture (C4 model + ADR)
  • /sdd-tasks - Break requirements into tasks
  • /sdd-implement - Implement features (test-first)
  • /sdd-validate - Constitutional compliance checks
• Benefits:
  • Clean start with best practices enforced
  • Constitutional governance from day one
  • Complete traceability from requirements to code

Brownfield (1→n)

• What it is: Working with existing codebases
• Use cases:
  • Adding features to existing applications
  • Refactoring legacy code
  • Migrating/modernizing systems
• Features enabled:
  • Delta Specifications (ADDED/MODIFIED/REMOVED)
  • /sdd-change-init - Create change proposal
  • /sdd-change-apply - Apply changes with impact analysis
  • /sdd-change-archive - Archive completed changes
  • change-impact-analyzer skill (Claude Code) - Automatic impact detection
  • Reverse engineering: /sdd-steering analyzes existing code
• Benefits:
  • Safe incremental changes with impact analysis
  • Preserves existing architecture while improving incrementally
  • Full audit trail of what changed and why

Both

• What it is: Hybrid approach for complex scenarios
• Use cases:
  • Monolith → Microservices migration (brownfield + greenfield services)
  • Platform modernization (keep some, rebuild others)
  • Multi-component systems with mixed maturity
• Features enabled:
  • All Greenfield + Brownfield features
  • Flexibility to choose workflow per component
  • Mixed delta specs and greenfield specs in same project
• Benefits:
  • Maximum flexibility for complex transformation projects
  • Unified steering/governance across all components
  • Single tool for entire modernization journey

Example Selection:

? Project type:
❯ Greenfield (0→1)    ← New projects
  Brownfield (1→n)    ← Existing codebases
  Both                ← Complex/hybrid scenarios

What Gets Installed

Claude Code (Skills API)

your-project/
├── .claude/
│   ├── skills/              # 25 Skills API + 5 built-in (Claude Code exclusive)
│   │   ├── orchestrator/
│   │   ├── steering/
│   │   ├── requirements-analyst/
│   │   └── ... (22 more)
│   ├── commands/            # Slash commands (/sdd-*)
│   └── CLAUDE.md            # Claude Code guide
├── steering/                # Project memory (all agents)
│   ├── project.yml          # Project configuration (v0.2.1+)
│   ├── structure.md         # Architecture patterns
│   ├── tech.md              # Technology stack
│   ├── product.md           # Product context
│   ├── memories/            # Persistent knowledge (v0.2.0+)
│   │   ├── architecture_decisions.md
│   │   ├── development_workflow.md
│   │   ├── domain_knowledge.md
│   │   ├── lessons_learned.md
│   │   ├── suggested_commands.md
│   │   └── technical_debt.md
│   └── rules/
│       ├── constitution.md  # 9 Constitutional Articles
│       ├── workflow.md      # 8-Stage SDD workflow
│       └── ears-format.md   # EARS syntax guide
├── templates/               # Document templates (all agents)
└── storage/                 # Specs, changes, features (all agents)

Other Agents (GitHub Copilot, Cursor, Gemini, etc.)

your-project/
├── .github/prompts/         # For GitHub Copilot (/sdd-*, .prompt.md)
│   ├── sdd-steering.prompt.md    # Prompt files use .prompt.md extension
│   ├── sdd-requirements.prompt.md
│   ├── ... (9 prompt files)
│   └── AGENTS.md             # 27 skills definition (official support)
│   OR
├── .cursor/commands/        # For Cursor (/sdd-*, Markdown)
│   ├── AGENTS.md             # 27 skills definition (official support)
│   OR
├── .gemini/commands/        # For Gemini CLI (/sdd-*, TOML)
│   │   ├── sdd-steering.toml
│   │   ├── sdd-requirements.toml
│   │   └── ... (6 TOML files)
│   OR
├── .codex/prompts/          # For Codex CLI (/prompts:sdd-*, Markdown)
│   ├── AGENTS.md             # 27 skills definition
│   OR
├── .qwen/commands/          # For Qwen Code (/sdd-*, Markdown)
│   ├── AGENTS.md             # 27 skills definition
│   OR
├── .windsurf/workflows/     # For Windsurf (/sdd-*, Markdown)
│   ├── AGENTS.md             # 27 skills definition
│
├── GEMINI.md (root, for Gemini)  # 27 skills integrated into existing file
├── steering/                # Project memory (same for all)
│   ├── project.yml          # Project configuration (v0.2.1+)
│   ├── memories/            # Persistent knowledge (v0.2.0+)
│   │   ├── architecture_decisions.md
│   │   ├── development_workflow.md
│   │   ├── domain_knowledge.md
│   │   ├── lessons_learned.md
│   │   ├── suggested_commands.md
│   │   └── technical_debt.md
│   └── ... (structure.md, tech.md, product.md, rules/)
├── templates/               # Document templates (same for all)
└── storage/                 # Specs, changes, features (same for all)

Key Differences:

• Claude Code: 27 Skills (25 + 5 built-in) + commands (Markdown)
• GitHub Copilot: AGENTS.md (official support) + prompt files (.prompt.md)
• Cursor: AGENTS.md (official support) + commands (Markdown)
• Gemini CLI: GEMINI.md integration (27 skills) + TOML commands (unique)
• Others: AGENTS.md (compatible) + Markdown commands
• All platforms: Same 27 skills, different implementation formats

Usage

CLI Commands

MUSUBI provides several CLI commands for project management:

# Show version
musubi --version
musubi -v

# Show help
musubi --help

# Show comprehensive info
musubi info

# Check project status
musubi status

# Validate constitutional compliance
musubi validate
musubi validate --verbose    # Detailed output
musubi validate --all        # Validate all features

# Initialize MUSUBI (interactive)
musubi init

# Onboard existing project (v0.3.0+)
musubi-onboard
musubi-onboard --auto-approve  # Skip confirmation
musubi-onboard --skip-memories # Skip memory initialization

# Synchronize steering docs with codebase (v0.4.0+)
musubi-sync                    # Interactive mode
musubi-sync --dry-run          # Preview changes only
musubi-sync --auto-approve     # Auto-apply (CI/CD)

# Analyze code quality (v0.5.0+)
musubi-analyze                 # Full analysis (quality + dependencies + security)
musubi-analyze --type=quality  # Code quality metrics only
musubi-analyze --type=dependencies  # Dependency analysis
musubi-analyze --type=security # Security vulnerabilities
musubi-analyze --output=report.md   # Save report to file
musubi-analyze --json          # JSON output

# Share project memories with team (v0.6.0+)
musubi-share export            # Export memories to JSON/YAML
musubi-share export --output=memories.yaml  # YAML format
musubi-share import memories.json  # Import and merge
musubi-share import memories.json --strategy=theirs  # Auto-accept
musubi-share sync              # Sync across AI platforms
musubi-share sync --platform=cursor  # Sync specific platform
musubi-share status            # Show sharing status

musubi-onboard

Automatically analyzes existing projects and generates steering documentation:

🚀 MUSUBI Onboarding Wizard

Analyzing your project...

✅ Project structure analyzed
✅ Technology stack detected
   - Node.js, TypeScript, React, Jest
✅ Steering documents generated
   - steering/structure.md (en + ja)
   - steering/tech.md (en + ja)
   - steering/product.md (en + ja)
✅ Memories initialized (6 files)
✅ Project configuration created
   - steering/project.yml

⏱️  Onboarding completed in 2.5 minutes

💡 Next steps:
   - Review generated steering docs
   - Run: musubi-sync to keep docs current
   - Create requirements: /sdd-requirements [feature]

Features:

• Automatic codebase analysis (package.json, directory structure)
• Technology stack detection (languages, frameworks)
• Bilingual steering docs generation (English + Japanese)
• Memory system initialization (6 memory files)
• Project configuration (project.yml)
• 96% time reduction (2-4 hours → 2-5 minutes)

musubi-sync

Detects codebase changes and keeps steering documents synchronized:

🔄 MUSUBI Steering Sync

Detected changes:
  📦 Version: 0.3.0 → 0.4.0
  ➕ New framework: js-yaml@4.1.0
  📁 New directory: bin/

? Apply these changes? (Y/n) Y

✅ Updated steering/project.yml
✅ Updated steering/tech.md (en + ja)
✅ Updated steering/structure.md (en + ja)
✅ Recorded change in memories/architecture_decisions.md

🎉 Steering synchronized successfully!

Features:

• Change detection (version, languages, frameworks, directories)
• Interactive mode (default): Show changes, ask confirmation
• Auto-approve mode (--auto-approve): CI/CD integration
• Dry-run mode (--dry-run): Preview only
• Bilingual updates (English + Japanese together)
• Memory recording (audit trail)

Usage:

# Interactive (default)
musubi-sync

# Preview changes without applying
musubi-sync --dry-run

# Auto-apply for CI/CD pipelines
musubi-sync --auto-approve

musubi-share

Share and merge project memories across team members and AI platforms (v0.6.0+):

📤 MUSUBI Memory Export

Export Summary:
  File: team-memories.json
  Format: json
  Size: 1098.28 KB
  Memories: 7 files
  Agents: 1 platforms

Features:

• Export: Share memories as JSON/YAML
• Import: Merge memories from teammates
• Sync: Synchronize across AI platforms
• Conflict Resolution: Interactive, auto-accept, keep-local, or merge with markers
• Status: Show installed platforms and memory counts

Usage:

# Export memories
musubi-share export
musubi-share export --output=memories.yaml

# Import and merge
musubi-share import colleague-memories.json
musubi-share import memories.json --strategy=theirs  # Auto-accept
musubi-share import memories.json --strategy=ours    # Keep local
musubi-share import memories.json --strategy=merge   # With markers

# Platform sync
musubi-share sync
musubi-share sync --platform=cursor

# Status check
musubi-share status

musubi status

Shows the current state of your MUSUBI project:

📊 MUSUBI Project Status

✅ MUSUBI is initialized

📁 Claude Code Skills: 27 installed (25 + 5 built-in)
   Location: .claude/skills/

🧭 Steering Context:
   ✅ structure.md (updated: 2025-11-16)
   ✅ tech.md (updated: 2025-11-16)
   ✅ product.md (updated: 2025-11-16)

✅ Constitutional Governance: Enabled

📄 Specifications: 3 documents
   Latest specs:
   - auth-requirements.md
   - auth-design.md
   - auth-tasks.md

💡 Next steps:
   - Review steering files in steering/
   - Create requirements: /sdd-requirements [feature]
   - Validate compliance: musubi validate

musubi validate

Performs quick constitutional compliance checks:

• Article I: Library-First Principle (checks lib/ directory)
• Article II: CLI Interface Mandate (checks for cli.ts files)
• Article IV: EARS Requirements Format (validates EARS patterns)
• Article VI: Project Memory (checks steering files)

For comprehensive validation, use your agent's /sdd-validate (or equivalent) command.

Agent-Specific Commands

Claude Code

# Generate project memory
/sdd-steering

# Create requirements
/sdd-requirements authentication

# Design architecture
/sdd-design authentication

# Break down into tasks
/sdd-tasks authentication

# Implement feature
/sdd-implement authentication

# Validate constitutional compliance
/sdd-validate authentication

Skills (Auto-Invoked): Claude Code automatically selects the appropriate skill:

• "Review my code" → code-reviewer skill
• "Create requirements for user login" → requirements-analyst skill
• "Design API for payment" → api-designer skill

GitHub Copilot

# Use # prefix for custom prompts
#sdd-steering
#sdd-requirements authentication
#sdd-design authentication
#sdd-tasks authentication
#sdd-implement authentication
#sdd-validate authentication

Gemini CLI

# Use / prefix for commands (TOML format)
/sdd-steering
/sdd-requirements authentication
/sdd-design authentication
/sdd-tasks authentication
/sdd-implement authentication
/sdd-validate authentication

Note: Gemini CLI commands are defined in TOML format (.toml files) instead of Markdown.

Cursor IDE, Qwen Code, Windsurf

# Use / prefix for commands (Markdown format)
/sdd-steering
/sdd-requirements authentication
/sdd-design authentication
/sdd-tasks authentication
/sdd-implement authentication
/sdd-validate authentication

Codex CLI

# Use /prompts: prefix
/prompts:sdd-steering
/prompts:sdd-requirements authentication
/prompts:sdd-design authentication
/prompts:sdd-tasks authentication
/prompts:sdd-implement authentication
/prompts:sdd-validate authentication

27 Skills Overview (All Platforms)

Available on all 7 platforms via:

• Claude Code: Skills API (automatic invocation) + 5 built-in orchestrator skills
• GitHub Copilot & Cursor: AGENTS.md (official support, reference via @agent-name)
• Gemini, Windsurf, Codex, Qwen: AGENTS.md (compatible format, natural language reference)

Orchestration & Management (3 + 5 built-in)

• orchestrator - Master coordinator for multi-skill workflows
• steering - Project memory manager (auto-updating context)
• constitution-enforcer - Governance validation (9 Articles + Phase -1 Gates)

Built-in Orchestrator Skills (v5.9.0)

• release-manager - CHANGELOG generation, version management
• workflow-mode-manager - Mode detection (small/medium/large)
• package-manager - Monorepo package & dependency analysis
• constitution-level-manager - Level-aware validation (critical/advisory/flexible)
• project-config-manager - Schema validation & migration

Requirements & Planning (3)

• requirements-analyst - EARS format requirements generation
• project-manager - Project planning, scheduling, risk management
• change-impact-analyzer - Brownfield change analysis

Architecture & Design (4)

• system-architect - C4 model + ADR architecture design
• api-designer - REST/GraphQL/gRPC API design
• database-schema-designer - Database design, ER diagrams, DDL
• ui-ux-designer - UI/UX design, wireframes, prototypes

Development (1)

• software-developer - Multi-language code implementation

Quality & Review (5)

• test-engineer - Unit, integration, E2E testing with EARS mapping
• code-reviewer - Code review, SOLID principles
• bug-hunter - Bug investigation, root cause analysis
• quality-assurance - QA strategy, test planning
• traceability-auditor - Requirements ↔ Code ↔ Test coverage validation

Security & Performance (2)

• security-auditor - OWASP Top 10, vulnerability detection
• performance-optimizer - Performance analysis, optimization

Infrastructure & Operations (5)

• devops-engineer - CI/CD pipelines, Docker/Kubernetes
• cloud-architect - AWS/Azure/GCP, IaC (Terraform/Bicep)
• database-administrator - Database operations, tuning
• site-reliability-engineer - Production monitoring, SLO/SLI, incident response
• release-coordinator - Multi-component release management

Documentation & Specialized (2)

• technical-writer - Technical documentation, API docs
• ai-ml-engineer - ML model development, MLOps

Governance Articles

MUSUBI enforces 9 immutable constitutional articles:

1. Library-First Principle - Features start as libraries
2. CLI Interface Mandate - All libraries expose CLI
3. Test-First Imperative - Tests before code (Red-Green-Blue)
4. EARS Requirements Format - Unambiguous requirements
5. Traceability Mandate - 100% coverage required
6. Project Memory - All skills check steering first
7. Simplicity Gate - Maximum 3 projects initially
8. Anti-Abstraction Gate - Use framework features directly
9. Integration-First Testing - Real services over mocks

SDD Workflow (8 Stages)

1. Research → 2. Requirements → 3. Design → 4. Tasks →
5. Implementation → 6. Testing → 7. Deployment → 8. Monitoring

Each stage has:

• Dedicated skills
• Quality gates
• Traceability requirements
• Constitutional validation

EARS Requirements Format

### Requirement: User Login

WHEN user provides valid credentials,
THEN the system SHALL authenticate the user
AND the system SHALL create a session.

#### Scenario: Successful login

- WHEN user enters correct email and password
- THEN system SHALL verify credentials
- AND system SHALL redirect to dashboard

Bilingual Documentation

All agent-generated documents are created in both English and Japanese.

Language Policy

• English: Reference/source documents (.md)
• Japanese: Translations (.ja.md)
• Skills: Always read English versions for work
• Code References: Requirement IDs, technical terms stay in English

Files Generated Bilingually

Steering Context:

• steering/structure.md + steering/structure.ja.md
• steering/tech.md + steering/tech.ja.md
• steering/product.md + steering/product.ja.md

Specifications:

• storage/specs/auth-requirements.md + storage/specs/auth-requirements.ja.md
• storage/specs/auth-design.md + storage/specs/auth-design.ja.md
• storage/specs/auth-tasks.md + storage/specs/auth-tasks.ja.md

Generation Order

1. English version generated FIRST (reference/source)
2. Japanese version generated SECOND (translation)
3. Technical terms (REQ-XXX-NNN, EARS keywords, API endpoints) remain in English
4. Both versions maintained in sync

Delta Specifications (Brownfield)

## ADDED Requirements

### REQ-NEW-001: Two-Factor Authentication

...

## MODIFIED Requirements

### REQ-001: User Authentication

**Previous**: Email + password
**Updated**: Email + password + OTP
...

## REMOVED Requirements

### REQ-OLD-005: Remember Me

**Reason**: Security policy change

Example Usage

Greenfield Project (0→1)

# 1. Initialize
npx musubi-sdd init

# 2. Generate steering
/sdd-steering

# 3. Create requirements
/sdd-requirements user-authentication

# 4. Design architecture
/sdd-design user-authentication

# 5. Break into tasks
/sdd-tasks user-authentication

# 6. Implement
/sdd-implement user-authentication

Brownfield Project (1→n)

# 1. Initialize with existing codebase
npx musubi-sdd init

# 2. Generate steering from existing code
/sdd-steering

# 3. Create change proposal
/sdd-change-init add-2fa

# 4. Impact analysis (automatic via change-impact-analyzer skill)

# 5. Implement change
/sdd-change-apply add-2fa

# 6. Archive change
/sdd-change-archive add-2fa

Configuration

MCP Server Integration

MUSUBI v2.0.0 integrates with CodeGraphMCPServer for advanced code analysis.

Option 1: Claude Code (Terminal)

# Install CodeGraph MCP with pipx (--force ensures latest version)
pipx install --force codegraph-mcp-server

# Add to Claude Code
claude mcp add codegraph -- codegraph-mcp serve --repo .

# Verify installation
claude mcp list

Option 2: VS Code with Claude Extension

1. Install Prerequisites:

   # --force ensures latest version even if already installed
   pipx install --force codegraph-mcp-server

2. Configure VS Code (.vscode/mcp.json):

   {
     "servers": {
       "codegraph": {
         "type": "stdio",
         "command": "codegraph-mcp",
         "args": ["serve", "--repo", "${workspaceFolder}"]
       }
     }
   }

3. Or use Claude Desktop config (~/.claude/claude_desktop_config.json on macOS/Linux, %APPDATA%\Claude\claude_desktop_config.json on Windows):

   {
     "mcpServers": {
       "codegraph": {
         "command": "codegraph-mcp",
         "args": ["serve", "--repo", "/path/to/your/project"]
       }
     }
   }

Option 3: npx (No Installation)

# Add via npx (no global install needed)
claude mcp add codegraph -- npx -y @anthropic/codegraph-mcp --codebase .

Verify MCP Server is Working

After setup, test in Claude:

Use the init_graph tool to analyze this codebase

If successful, you'll see the code graph initialization output.

Available MCP Tools (14 tools):

Agent × MCP Tool Mapping:

Also integrates with other MCP servers:

• Context7 MCP - Up-to-date library documentation (Next.js, React, etc.)
• Azure MCP - Azure resource management
• Microsoft Learn MCP - Microsoft documentation

Skills automatically use available MCP servers when needed.

Customization

Edit steering files to customize for your project:

# Architecture patterns
steering/structure.md

# Technology stack
steering/tech.md

# Product context
steering/product.md

# Constitutional rules (if needed)
steering/rules/constitution.md

Development

Contributing Workflow

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Make your changes
4. Run tests locally: npm test
5. Run lint: npm run lint
6. Commit with conventional commits: git commit -m "feat: add new feature"
7. Push to your fork: git push origin feature/your-feature
8. Create a Pull Request
9. Wait for CI checks to pass (all checks must succeed)
10. Request review
11. Merge after approval

CI/CD Pipeline

• CI: Runs on every PR and push to main
  • ESLint & Prettier
  • Jest Tests (80% coverage required)
  • Build Verification
  • Security Audit
  • Platform Initialization Tests (7 platforms)
• Release: Automated npm publish on version tags (v*.*.*)
• Dependabot: Weekly dependency updates (Mondays 9:00 JST)

Local Testing

# Clone repository
git clone https://github.com/nahisaho/MUSUBI.git
cd musubi

# Install dependencies
npm install

# Run tests
npm test

# Run lint
npm run lint

# Check formatting
npm run format:check

# Link for local development
npm link
musubi init

Contributing

Contributions welcome! See 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 for details.

Credits

MUSUBI synthesizes features from:

• musuhi - 20-agent system, steering, EARS format
• OpenSpec - Delta specs, brownfield support
• ag2 (AutoGen) - Multi-agent orchestration
• ai-dev-tasks - Simplicity, progressive complexity
• cc-sdd - P-label parallelization, validation gates
• spec-kit - Constitutional governance, test-first

📚 Learn More

• 📖 Documentation
• 📋 SRS v3.0.0
• 📅 Project Plan v3.0.0
• 🏗️ Blueprint
• 📊 Project Plan