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