MUSUBI

Ultimate Specification Driven Development Tool for 7 AI Coding Agents

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.

Features

• 🤖 Multi-Agent Support - Works with 7 AI coding agents (Claude Code, GitHub Copilot, Cursor, Gemini CLI, Codex CLI, Qwen Code, Windsurf)
• 📄 Flexible Command Formats - Supports both Markdown and TOML formats (Gemini CLI uses TOML)
• 🎯 25 Specialized Claude Code Skills - Orchestrator, Steering, Requirements, Architecture, Development, Quality, Security, Infrastructure (Claude Code exclusive)
• 📋 Constitutional Governance - 9 immutable articles + Phase -1 Gates for quality enforcement
• 📝 EARS Requirements Format - Unambiguous requirements with complete traceability
• 🔄 Delta Specifications - Brownfield and greenfield project support
• 🧭 Auto-Updating Project Memory - Steering system maintains architecture, tech stack, and product context
• ✅ 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
• Gemini CLI uses TOML format instead of Markdown
• All other agents use Markdown format for commands/prompts

Quick Start

Installation via npx

# Initialize MUSUBI for your preferred agent

# Claude Code (default) - with 25 skills
npx musubi-sdd init
npx musubi-sdd init --claude

# GitHub Copilot
npx musubi-sdd init --copilot

# Cursor IDE
npx musubi-sdd init --cursor

# Gemini CLI
npx musubi-sdd init --gemini

# Codex CLI
npx musubi-sdd init --codex

# Qwen Code
npx musubi-sdd init --qwen

# Windsurf IDE
npx musubi-sdd init --windsurf

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

What Gets Installed

Claude Code (default)

your-project/
├── .claude/
│   ├── skills/              # 25 specialized skills (Claude Code exclusive)
│   │   ├── orchestrator/
│   │   ├── steering/
│   │   ├── requirements-analyst/
│   │   └── ... (22 more)
│   ├── commands/            # Slash commands (/sdd-*)
│   └── CLAUDE.md            # Claude Code guide
├── steering/                # Project memory (all agents)
│   ├── structure.md         # Architecture patterns
│   ├── tech.md              # Technology stack
│   ├── product.md           # Product context
│   └── 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-*, Markdown)
│   OR
├── .cursor/commands/        # For Cursor (/sdd-*, Markdown)
│   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)
│   OR
├── .qwen/commands/          # For Qwen Code (/sdd-*, Markdown)
│   OR
├── .windsurf/workflows/     # For Windsurf (/sdd-*, Markdown)
│
├── AGENTS.md (or GEMINI.md/QWEN.md)  # Agent-specific guide
├── steering/                # Project memory (same for all)
├── templates/               # Document templates (same for all)
└── storage/                 # Specs, changes, features (same for all)

Key Differences:

• Claude Code gets 25 skills + commands (Markdown)
• Gemini CLI uses TOML format for commands (unique)
• Other agents use Markdown for commands/prompts

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

musubi status

Shows the current state of your MUSUBI project:

📊 MUSUBI Project Status

✅ MUSUBI is initialized

📁 Claude Code Skills: 25 installed
   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

25 Skills Overview

Orchestration & Management (3)

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

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

Constitutional Governance

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 integrates with MCP servers for enhanced capabilities:

• 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

# Clone repository
git clone https://github.com/your-org/musubi.git
cd musubi

# Install dependencies
npm install

# Run tests
npm test

# Link for local development
npm link
musubi init

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

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
• Blueprint
• Project Plan
• Framework Comparison

MUSUBI - むすび - Bringing specifications, design, and code together.