pi-openspec

OpenSpec deep integration for pi — a pi-package that wires spec-driven development into your agent.

This package bundles:

• extensions/openspec.ts — deep integration extension
• skills/openspec-*/ — official OpenSpec agent skills
• prompts/opsx-*.md — official OpenSpec slash commands (/opsx-…)

Install

pi install npm:openspec-pi
# or from git
pi install git:github.com/tobias-weiss-ai-xr/pi-openspec

Requires the OpenSpec CLI ≥ 1.14.0 on your PATH:

npm install -g @fission-ai/openspec

Restart pi after installing.

What you get

1. Native openspec tool

The agent can query spec-driven development state during a task, without slash commands — status, doctor, context, list, show, validate, instructions, archive, store, spec, new. The tool forwards exactly the flags OpenSpec CLI 1.14.0 accepts (positional item names for show/validate/archive, --specs for list, --store for store-scoped operations).

2. Auto-context injection

At before_agent_start, if the working directory (or an ancestor) contains an OpenSpec root (openspec/config.yaml) or is inside a registered OpenSpec store, the openspec context output is appended to the system prompt. The agent always knows the project's spec context — cached per root and invalidated when the spec tree changes.

3. /ospec command

Run arbitrary OpenSpec CLI commands interactively: /ospec status, /ospec doctor, /ospec context, /ospec archive <change> --json, …

4. Official OpenSpec prompts & skills

The exact same slash commands and skills that openspec init --tools pi generates in .pi/ — now available globally via the package. Synced to OpenSpec CLI 1.14.0 (all 12 workflow profiles: new, propose, explore, continue, apply, ff, update, sync, verify, archive, bulk-archive, onboard):

Workflow	Slash command	Skill	What it does
New	/opsx-new <name>	openspec-new-change	Scaffold a change (openspec new change)
Propose	/opsx-propose <name>	openspec-propose	Create a change with proposal/design/specs/tasks
Explore	/opsx-explore	openspec-explore	Think through an idea, compare options, clarify scope
Continue	/opsx-continue <name>	openspec-continue-change	Build the next pending planning artifacts
Apply	/opsx-apply <name>	openspec-apply-change	Implement a change's tasks
Fast-forward	/opsx-ff <name>	openspec-ff-change	Create all artifacts needed for implementation in one go
Update	/opsx-update <name>	openspec-update-change	Revise a change's artifacts, keep them coherent
Sync	/opsx-sync <name>	openspec-sync-specs	Sync delta specs from a change to main specs
Verify	/opsx-verify	openspec-verify-change	validate + doctor health sweep (pre-commit)
Archive	/opsx-archive <name>	openspec-archive-change	Native openspec archive with pre-flight checks
Bulk archive	/opsx-bulk-archive	openspec-bulk-archive-change	Archive several completed changes at once
Onboard	/opsx-onboard	openspec-onboard	Orient in a repo/store, map changes + specs

Feedback to the OpenSpec maintainers is a plain CLI command now (no longer a workflow skill): /ospec feedback <message>.

Usage

# In any repo with an openspec/ root — the agent gets context automatically.
# Otherwise:
/ospec status       # see change progress
/ospec doctor       # check relationship health
/ospec context      # working context
/ospec validate --all --strict --json

### Registered stores

For a change that lives in a registered standalone store (not the local `openspec/`
root), pass the store id explicitly — to the tool, the command, or the skills:

```bash
openspec store list --json   # discover registered store ids
/ospec status --store <id>
/ospec list --json --store <id>

When running inside a registered store's root, the agent auto-discovers it and injects its openspec context even without a local openspec/ directory.

Troubleshooting

• openspec: command not found — the CLI ≥ 1.14.0 is required on PATH: npm install -g @fission-ai/openspec. Skills declare it in their compatibility frontmatter, and the tool surfaces its stderr as Error: ….
• Stale spec context — the injected context is cached per root and refreshes when the spec tree changes (config.yaml mtime + changes directory). If it looks stale after an explicit edit, run /ospec context to force a refresh.
• Tool says Unsupported command — the curated tool covers status/doctor/context/ list/show/validate/instructions/archive/store/spec/new. For anything else (e.g. openspec feedback) use /ospec <command> passthrough.
• No /opsx-* commands after install — restart pi; slash commands and skills are loaded at agent start.

Uninstall

pi uninstall openspec-pi

Development

The package self-hosts an OpenSpec root (openspec/) with a roadmap spec. To keep skills/prompts in sync with the CLI:

npm run check          # validate skill/prompt pairing + referenced slash commands + manifest/README consistency
npm run check:ext      # JIT-load the extension with a stub API and exercise tool/command paths (needs a pi install)
npm run check:full     # check + openspec validate --all (needs CLI on PATH)

npm run check also runs automatically as a prepack gate before npm pack / npm publish, and both jobs run in CI (check.yml): a hygiene job and a check:full job that installs the OpenSpec CLI.

Assets (e.g. the gallery image assets/pi-openspec.png) are checked to exist on disk and are included in the published tarball.

License

MIT. Skills and prompts are derived from Fission-AI/OpenSpec (MIT, © OpenSpec Contributors). The extension is original.