OpenSpec-Flow

Alpha Software: APIs may change between versions.

Bridges OpenSpec (specification-driven change management) with Claude Flow (multi-agent orchestration) via Claude Code. Provides MCP tools and slash commands for automated implementation workflows.

Installation

npm install -g openspec-flow@next
openspec-flow setup

For project-local installation:

npm install -D openspec-flow@next
npx openspec-flow setup

Dependencies

Dependency	Required	Install
OpenSpec CLI	Yes (for /osf:ideate, /osf:archive)	npm install -g @anthropic/openspec
Claude-Flow MCP	For /osf:implement, /osf:verify, /osf:review	See below

Claude-Flow setup:

claude mcp add claude-flow -- npx @anthropic/claude-flow@alpha mcp start

What It Does

The setup command:

1. Installs slash commands to .claude/commands/osf/
2. Configures the MCP server in .mcp.json (project) or ~/.claude.json (global)
3. Auto-detects project tech stack and generates config
4. Checks for OpenSpec CLI and Claude-Flow dependencies

Commands

All commands are namespaced under osf::

Command	Description	Dependencies
/osf:ideate <req>	Create new change from requirements	OpenSpec CLI
/osf:list	List all OpenSpec changes with status	-
/osf:work <id>	Generate work brief for a change	-
/osf:analyze <id>	Analyze change size/complexity	-
/osf:split <id>	Split large change into phases	-
/osf:implement <id>	Implement via multi-agent swarm	Claude-Flow
/osf:verify <id>	Verify implementation via agents	Claude-Flow
/osf:review <id>	Review against requirements	Claude-Flow
/osf:deferred <id>	Analyze incomplete tasks	-
/osf:log <id>	Create implementation flow log	-
/osf:archive <id>	Archive completed/closed change	OpenSpec CLI
/osf:help	Help and command reference	-

Partial Change IDs

Commands support partial change ID matching:

/osf:work fix-auth    # Matches "fix-auth-flow-20241201"
/osf:work 001         # Matches "001-add-feature"

Workflow

1. /osf:ideate "feature"   Create new change from requirements
   OR manually create openspec/changes/<id>/

2. /osf:list               List available changes
3. /osf:analyze CHANGE-001 Check size/complexity
4. /osf:split CHANGE-001   Split if too large (optional)
5. /osf:work CHANGE-001    Generate work brief
6. /osf:implement CHANGE-001 Implement via agent swarm
7. /osf:verify CHANGE-001  Verify via test agents
8. /osf:review CHANGE-001  Review via review agents
9. /osf:deferred CHANGE-001 Check incomplete items
10. /osf:log CHANGE-001    Document implementation
11. /osf:archive CHANGE-001 Archive when done

MCP Tools

The MCP server exposes these tools:

Tool	Description
get_proposal_workflow	Get OpenSpec proposal workflow instructions
list_changes	List all OpenSpec changes
resolve_change_id	Resolve partial change ID to full ID
generate_work_brief	Create work brief for a change
get_change_context	Get file paths and summary
scaffold_change	Create new change directory
save_change_artifact	Save/update change files
analyze_change	Analyze size and complexity
split_change	Split into phased sub-changes
analyze_deferred	Analyze incomplete tasks
create_flow_log	Create implementation log
archive_change	Archive via OpenSpec CLI

OpenSpec Structure

OpenSpec-Flow reads from the standard OpenSpec directory structure:

openspec/
└── changes/
    ├── <CHANGE-ID>/
    │   ├── proposal.md     # Change proposal
    │   ├── tasks.md        # Implementation checklist
    │   ├── design.md       # Optional design docs
    │   ├── work-brief.md   # Generated by /osf:work
    │   ├── flow-log.md     # Generated by /osf:log
    │   └── specs/          # Spec delta files
    └── archive/            # Archived changes
        └── YYYY-MM-DD-<CHANGE-ID>/
            ├── ...
            └── archive-metadata.yaml

Configuration (Optional)

Project configuration is auto-generated during setup in .openspec-flow/config/:

.openspec-flow/config/
├── project.yaml      # Project name, build/test commands
├── tech-stack.yaml   # Runtime, database, etc.
├── paths.yaml        # Source directories
├── patterns.yaml     # Architecture patterns
└── constraints.yaml  # Project constraints

Safe Install/Uninstall

Commands are marked with an internal identifier. The setup process:

• Detects conflicts with existing custom commands
• Only overwrites files that belong to openspec-flow
• Preserves user's custom commands in the osf/ directory

Uninstall

openspec-flow uninstall

Requirements

• Node.js >= 18.0.0
• Claude Code
• OpenSpec CLI (for /osf:ideate, /osf:archive)
• Claude-Flow MCP (for /osf:implement, /osf:verify, /osf:review)

License

MIT - Scott Wilkos

Related

• OpenSpec - Specification-driven change management
• Claude Flow - Multi-agent orchestration
• Claude Code - AI-powered development