---
name: openspec-bootstrap
description: One-time setup that installs OpenSpec into a project already (or about to be) managed by GSD Core, scaffolds this capability's integration state, and explains the unified lifecycle. Use when starting /gsd-new-project or /gsd-onboard on a project that doesn't have openspec/ yet, or when a user asks to "add OpenSpec to this GSD project".
allowed-tools: Bash, Read, Write, Glob
license: MIT
metadata:
  author: openspec-gsd-integration
  version: "0.1.0"
---

## Purpose

Make a project OpenSpec-and-GSD-ready in one idempotent pass: install the OpenSpec CLI's project scaffold, install this capability, and create the integration-owned state directories — without touching anything GSD or OpenSpec already own.

## Invocation conditions

- Explicitly via `/gsd-new-project` or `/gsd-onboard` (this capability's `discuss:pre` fragment will otherwise nag on every phase without it).
- Directly, any time, by a user or agent that wants to (re-)check the setup — it is safe to run repeatedly.

## Required inputs

- None. Reads the current working directory as the project root.

## Files read

- `openspec/` (existence check only)
- `.planning/` (existence check only)
- `.gsd-capabilities.json` (existence + whether `openspec` is already installed)

## Files this skill may write

- `openspec/` (via `openspec init`, if absent) — never overwrites an existing `openspec/`
- `.planning/openspec/` (`id-registry.json`, `TRACEABILITY.md`, `EVIDENCE.json`, `AUDIT-SUMMARY.md` — created empty/seeded, never overwritten if present)
- Nothing under `.planning/phases/`, `.planning/PROJECT.md`, `.planning/ROADMAP.md`, `.planning/STATE.md` — those are GSD's own and this skill only reads them if present

## Algorithm

1. Check `command -v openspec`. If absent, stop and tell the user to run `npm install -g @fission-ai/openspec@latest` — do not attempt a project-local install of a global CLI tool.
2. If `openspec/` does not exist: run `openspec init --tools claude` (or the tool matching the detected runtime). If it exists, run `openspec list --json` to confirm it's healthy; do not re-init.
3. Check `.gsd-capabilities.json` for an `openspec` entry with `status: active` (`gsd-tools capability list --raw`). If absent, run `gsd-tools capability install ./capabilities/openspec --scope project` — this project must therefore already contain `capabilities/openspec/` (this capability's own source, vendored or fetched); if it's missing, tell the user to add the capability source (URL/git-ref/npm) before continuing, per [Publish a capability](https://github.com/open-gsd/gsd-core) conventions. Never invent a manifest at runtime.
4. Create `.planning/openspec/` if `.planning/` exists (GSD already onboarded) and the subdirectory doesn't: seed `id-registry.json` as `{}`, leave the three Markdown files absent (generators create them on first real run — an empty placeholder would be misleading "evidence").
5. If both `openspec/` and `.planning/` pre-existed with real content (retrofitting an existing project onto this integration): do **not** auto-generate OpenSpec specs from `.planning/REQUIREMENTS.md`. Instead print the brownfield note below and stop — `openspec-drift` in forensic mode is the correct next step, not this skill.
6. Print a one-paragraph summary of the unified lifecycle (Discuss→Propose→Specs→Design→Tasks→Plan→Execute→Verify→Audit→Ship→Archive) and the two entry points (`/gsd-discuss-phase`, `/opsx:propose`).

**Brownfield note** (shown at step 5): "Both `openspec/` and `.planning/` already have content. This skill will not guess which existing requirements in `REQUIREMENTS.md` correspond to which (if any) OpenSpec specs — that mapping needs a human or `openspec-drift --mode forensic` to propose it for review, never an automatic merge."

## Outputs

- `openspec/` scaffold (via real `openspec init`)
- `openspec` capability `active` in the GSD capability registry
- `.planning/openspec/id-registry.json` seeded

## Failure states

- `openspec` CLI not installed → **stop**, give the exact install command, do not proceed.
- Capability source (`capabilities/openspec/`) missing → **stop**, this is a packaging problem, not something to paper over.
- Both dirs pre-exist with content → **stop with brownfield note**, hand off to `openspec-drift`.

## Guardrails

- Never runs `openspec init` over an existing `openspec/` (would risk clobbering config/specs).
- Never fabricates OpenSpec specs from existing GSD requirements without flagging them `inferred: true` (delegated to `openspec-drift`, never done here).
- Never edits `.planning/PROJECT.md`, `ROADMAP.md`, `STATE.md`, or any `phases/` content — those are exclusively GSD's.

## Idempotency

Safe to re-run at any time: every step is existence-gated. A second run with everything already in place produces no file changes and prints the setup summary again.

## Example

```
$ /gsd-new-project
...
[openspec-bootstrap] openspec/ created (openspec init --tools claude)
[openspec-bootstrap] capability "openspec" installed, status: active
[openspec-bootstrap] .planning/openspec/ scaffolded
Ready. Next: /gsd-discuss-phase 1, or /opsx:propose <change-id> first if you want to scope the phase in OpenSpec before discussing it.
```