openspec-boot

One-command bootstrap for OpenSpec + superpowers-bridge in any project. Ships as a Claude Code plugin (also installable on Codex / generic agents). Trigger from natural language — "set up SDD for this project" — and the bundled script does the rest.

Install

Claude Code

npx skills add https://github.com/9Ashwin/openspec-boot.git --skill openspec-boot

Or install the full plugin:

/plugin install https://github.com/9Ashwin/openspec-boot.git

Codex

git clone https://github.com/9Ashwin/openspec-boot.git ~/.codex/openspec-boot
mkdir -p ~/.agents/skills
ln -s ~/.codex/openspec-boot/skills/openspec-boot ~/.agents/skills/openspec-boot

See Codex Install Guide for details.

Optional: CLI command

If you want to run openspec-boot directly from the shell (not just via your agent), add one symlink:

mkdir -p ~/bin
ln -sfn ~/.codex/openspec-boot/skills/openspec-boot/scripts/run.sh ~/bin/openspec-boot
# (Make sure ~/bin is in your PATH — add `export PATH="$HOME/bin:$PATH"` to ~/.zshrc if not.)

After install, in any project just say:

set up SDD for this project

→ the openspec-boot skill triggers and the bundled script does the rest.

What the skill is, exactly

A SKILL.md plus a scripts/run.sh next to it. The agent reads SKILL.md to know when to invoke the skill; on invocation it executes scripts/run.sh against the current project directory. There are no other moving parts — no daemon, no config file.

What it does

In any project root, the script (whether triggered by your agent or run manually as openspec-boot) does:

1. Runs openspec init if no openspec/ directory exists
2. Installs the superpowers-bridge schema into <project>/openspec/schemas/superpowers-bridge/ (project-local; see Why not user-global?)
3. Validates with openspec schema validate superpowers-bridge and confirms resolution via openspec schema which superpowers-bridge
4. Optionally sets superpowers-bridge as the project default in openspec/config.yaml — so /opsx:new no longer needs --schema
5. Optionally appends the workflow-routing fragment to CLAUDE.md or AGENTS.md
6. Reports whether obra/superpowers plugin / skills are detected

The script is idempotent — re-run any time, completed steps are skipped.

Prerequisites

• openspec CLI (npm i -g @fission-ai/openspec)
• git
• (Optional, for Full-tier workflow) obra/superpowers plugin — Claude Code: claude plugin install superpowers@claude-plugins-official

Use

From an AI agent

After install, the matching skill (openspec-boot) is registered. Trigger phrases:

• "set up SDD for this project" / "configure spec-driven workflow"
• "init openspec" / "initialize openspec" / "装一下 openspec"
• "add the SDD workflow to this repo" / "给这个仓库加上 SDD 工作流"

The agent reads SKILL.md, runs scripts/run.sh in the project root, and follows up with the prompts.

From the shell

If you symlinked the CLI:

cd <any-project>
openspec-boot                          # default: project-local schema, prompts
openspec-boot --inject                 # auto-inject CLAUDE.md / AGENTS.md fragment
openspec-boot --no-inject              # skip fragment injection
openspec-boot --default-schema=<name>  # set openspec/config.yaml default schema
openspec-boot --no-default             # leave openspec/config.yaml alone
openspec-boot --tools=<list>           # passed to `openspec init` (default: 'claude' when non-interactive)
openspec-boot --user                   # ALSO install schema to user-global cache (rarely useful)
openspec-boot --locale=zh-TW           # force locale for fragment (auto-detected by default)
openspec-boot --dry-run                # preview actions without running them
openspec-boot --update                 # refresh the user-global schemas source clone
openspec-boot --help

If you didn't install the CLI symlink, invoke directly:

bash ~/.claude/skills/openspec-boot/scripts/run.sh    # (or any of the install paths)

Upgrading

Claude Code plugin install

claude plugin update openspec-boot

Manual clone

git -C <wherever-you-cloned-it> pull

Symlinks track the clone, so git pull propagates updates to all install paths automatically.

Schema source cache

openspec-boot --update     # git pull on ~/.local/share/openspec/_schemas-src

Project-local schemas already-installed are not auto-updated. To pick up the new schema in an existing project:

cd <project>
rm -rf openspec/schemas/superpowers-bridge
openspec-boot              # re-install from refreshed cache

Repository layout

openspec-boot/                              ← this repo (Claude Code plugin)
├── .claude-plugin/
│   └── plugin.json                         ← Claude marketplace manifest
├── .codex-plugin/
│   └── plugin.json                         ← Codex marketplace manifest
├── .codex/
│   └── INSTALL.md                          ← Codex manual install guide
├── skills/
│   └── openspec-boot/                      ← the actual skill
│       ├── SKILL.md                        ← AI trigger doc
│       └── scripts/
│           └── run.sh                      ← bootstrap script
├── README.md
├── LICENSE
└── .gitignore

The plugin spec (.claude-plugin/plugin.json / .codex-plugin/plugin.json) points each marketplace at skills/openspec-boot/ as the skill source.

What the script touches

<project>/openspec/                          # created by `openspec init` if absent
<project>/openspec/schemas/superpowers-bridge/   # project-local schema copy
<project>/openspec/config.yaml               # optionally edited (schema field)
<project>/CLAUDE.md or AGENTS.md             # optionally appended (workflow-routing)
~/.local/share/openspec/_schemas-src/        # superpowers-bridge source cache (one per machine)

The cache is shared across projects — git clone runs once per machine, not once per project.

Why not user-global?

OpenSpec advertises a user-global schemas directory at ~/.local/share/openspec/schemas/, but its resolution is inconsistent (verified May 2026):

Command	Resolves user-global?
openspec schema which <name>	✅ yes
openspec schema validate <name>	✅ yes
openspec new change <name> --schema <user-global>	❌ no — "Unknown schema"
openspec apply / openspec ff	❌ no

The schema sub-commands accept user-global, but the actual workflow commands (new/apply/...) only see project-local + built-in. That makes user-global unusable for real work today.

openspec-boot therefore defaults to project-local install. The schema is a few hundred KB; copying it per project is cheap.

The --user flag is preserved (in case OpenSpec fixes the inconsistency, or you want the schema visible to schema validate/schema which for inspection), but it prints a warning and does not satisfy openspec new.

After bootstrap, in a project

If you accepted the default-schema prompt:

/opsx:new my-feature                          # uses superpowers-bridge by default
/opsx:new my-feature --schema spec-driven     # opt-out for a lighter run

Otherwise:

/opsx:new my-feature --schema superpowers-bridge

For when to pick which schema, see the workflow-routing fragment that openspec-boot optionally injects, or the bridge's README §Entry & exit gates.

Why both a script and a skill?

• Script (scripts/run.sh) = the actual work. Idempotent, scripted, runnable from CI or by hand.
• Skill (SKILL.md) = the trigger. Tells your AI agent when to run the script in natural-language conversation, so you don't have to remember the command name.

Same shape obra/superpowers skills use: SKILL.md describes what and when, scripts/binaries do the how.

Acknowledgements

Stands on top of:

• Fission-AI/OpenSpec — schema engine
• obra/superpowers — execution discipline skills
• JiangWay/openspec-schemas — superpowers-bridge schema (the bootstrap target). openspec-boot actually pulls from 9Ashwin/openspec-schemas, a fork that adds extra locale fragments (notably zh-CN); the fork tracks upstream.

Plugin layout follows 9Ashwin/on-my-sdd.

License

MIT — see LICENSE.