openspec-migration

Migrate any project to OpenSpec - auto-generates specs from existing codebases

Usage

# Current directory
npx openspec-migration

# Specific project path
npx openspec-migration ./my-project
npx openspec-migration /absolute/path/to/project

# Preview without making changes
npx openspec-migration --dry-run
npx openspec-migration ./my-project --dry-run

What it installs

| Tool | What it does | How | |---|---|---| | OpenSpec | Spec-driven development | openspec init --tools claude --profile core --force | | /migrate-to-openspec | Brownfield migration skill | Copied to .claude/skills/migrate-to-openspec/ |

Prerequisites

⚠️ This package does NOT install the tools below for you. It only wires them together in your project. Make sure all of the following are installed before running npx openspec-migration.

| Tool | Install instructions | |---|---| | OpenSpec | github.com/Fission-AI/OpenSpec | | Claude Code | npm install -g @anthropic-ai/claude-code | | Node.js | nodejs.org (v18+) |

Each tool has multiple installation options — pick whichever works best for your environment.

Platform support

Works on macOS, Windows, and Linux — it's a Node.js script, no bash required.

Requires Node.js 18+.

After running

This tool is designed to be run from within Claude Code. After running npx openspec-migration, follow these steps:

Step 1 — Initialize Claude Code (if not already done)

If you haven't already initialized Claude Code in this project, run:

/init

This creates CLAUDE.md — Claude Code's project-level memory file. If you're already working in Claude Code and have a CLAUDE.md file, skip this step.

Note: openspec-migration already creates .claude/skills/ so the installed skills will be found automatically. But without CLAUDE.md (generated by /init), Claude Code has no project context to work with.

Step 2 — Migrate your project

Run inside Claude Code:

/migrate-to-openspec

This scans the codebase using a multi-agent system with 4 parallel scout agents:

1. Scout 1 — Project structure & tech stack analysis
2. Scout 2 — Existing docs & CLAUDE.md audit (identifies redundant doc references)
3. Scout 3 — Technical debt & active work (TODOs, FIXMEs, git signals)
4. Scout 4 — Module boundaries & feature map

After all scouts return, the skill synthesizes results and auto-generates all OpenSpec files: config.yaml, architecture specs, feature specs, and active changes from TODOs/FIXMEs. It also optimizes CLAUDE.md by removing redundant doc references now covered by OpenSpec.

See openspec/MIGRATION_REPORT.md for a summary of what was created and what needs human review.

Local development / run without publishing

git clone <this-repo>
cd openspec-migration
npm install
node index.js ./target-project

Publish to npm (optional)

npm publish --access public
# Then anyone can run: npx openspec-migration