openspec-stack-init

Initialize OpenSpec + Beads + claude-mem + skills in any project — one command.

Usage

# Current directory
npx openspec-stack-init

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

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

What it installs

| Tool | What it does | How | |---|---|---| | OpenSpec | Spec-driven development | openspec init --tools claude --profile core --force | | Beads | Git-backed issue tracker / agent memory | bd init --quiet + bd setup claude (CLI hooks) | | claude-mem | Automatic session memory via hooks | claude plugin marketplace add + claude plugin install | | openspec-to-beads | Syncs OpenSpec tasks.md → Beads issues | npx @smithery/cli skill add | | /migrate-to-openspec | Brownfield migration skill | Copied to .claude/skills/migrate-to-openspec/ |

Beads: CLI vs Claude Code Plugin

This package installs Beads CLI level only:

• bd init — creates .beads/ and issues.jsonl in your project (git-committed)
• bd setup claude — installs SessionStart and PreCompact hooks so Claude Code gets task context automatically

There is also an optional Beads Claude Code Plugin that adds slash commands (/beads:ready, /beads:create, etc.) and an MCP server. It cannot be installed automatically from a shell script — install it manually inside Claude Code if you want it:

/plugin marketplace add steveyegge/beads
/plugin install beads

For most projects the CLI level is sufficient — Claude Code agents call bd via bash.

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-stack-init.

| Tool | Install instructions | |---|---| | OpenSpec | github.com/Fission-AI/OpenSpec | | Beads | INSTALLING.md | | claude-mem | github.com/thedotmack/claude-mem | | 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

Step 1 — Initialize Claude Code in your project

Open Claude Code in the project directory and run:

/init

This creates CLAUDE.md — Claude Code's project-level memory file. It also ensures the .claude/ folder is fully recognized by Claude Code. Run this before using any skills or slash commands.

Note: openspec-stack-init 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 — Brownfield project

Run inside Claude Code:

/migrate-to-openspec

This scans the codebase using 4 parallel scout agents and auto-generates all OpenSpec files: config.yaml, architecture specs, feature specs, and active changes from TODOs/FIXMEs. See openspec/MIGRATION_REPORT.md for a summary of what was created and what needs human review.

Step 2 — Greenfield project

Skip /migrate-to-openspec. Instead:

1. Edit openspec/config.yaml — describe your planned stack and conventions
2. Run /opsx:propose <feature> to start your first spec

Local development / run without publishing

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

Publish to npm (optional)

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