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

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

For project-local installation:
`bash
npm install -D openspec-flow@next
npx openspec-flow setup
`

$3

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

$3

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

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/
├── /
│ ├── 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-/
├── ...
└── 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

`bash
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