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