---
name: openspec-bridge-propose
description: Ensures a GSD phase has a valid, complete OpenSpec change (proposal+specs+design+tasks) before /gsd-discuss-phase or /gsd-plan-phase will proceed. Wraps native /opsx:propose (or /opsx:ff for the expanded profile) and validates the result, rather than reimplementing artifact generation.
allowed-tools: Bash, Read
license: MIT
metadata:
  author: openspec-gsd-integration
  version: "0.1.0"
---

## Purpose

This is the skill `discuss:pre` tells the user to run when no change is linked. It is a validating wrapper around OpenSpec's own proposal-generation skills — never a reimplementation of them — because duplicating that logic would create exactly the "two competing spec systems" this integration exists to avoid.

## Invocation conditions

- User runs it directly (or is told to by the `discuss:pre` fragment).
- Called with a change-id and a one-sentence description of the change.

## Required inputs

- `change-id` (kebab-case, matches OpenSpec's own naming convention)
- A one-sentence description of intent — passed straight to `/opsx:propose`.
- Optionally, the GSD phase number this change is meant to satisfy.

## Files read

- `openspec/config.yaml` (for schema/profile — read-only, never modified by this skill)
- `.planning/ROADMAP.md` (if a phase number is given, to sanity-check the change's scope against the phase goal)

## Files this skill may write

- None directly — `proposal.md`/`specs/`/`design.md`/`tasks.md` are written by the native OpenSpec skill it invokes. This skill only *validates* after the fact.

## Algorithm

1. Run the native proposal flow: `/opsx:propose <change-id>` (core profile) or `/opsx:ff <change-id>` (expanded profile, if `openspec config profile` selected it) — do not hand-author `proposal.md`; that is exactly the job OpenSpec's own skill already does well, with project `context:`/`rules:` injection this skill has no reason to reimplement.
2. After the native skill finishes, run `openspec validate --change "<change-id>" --json` (or `openspec status --change "<change-id>" --json`) to confirm `proposal`, `specs`, and `design` artifacts are all `done` and pass validation. `tasks` may remain `ready` — that's fine, `openspec-plan` consumes it next.
3. If validation fails, do not proceed to GSD planning — surface the exact `validate --json` issues to the user and stop. Never tell GSD "the change is ready" when OpenSpec itself says otherwise.
4. If a phase number was given and the change's scope (from `proposal.md`) doesn't obviously match the phase goal (from `ROADMAP.md`), flag the mismatch as a question, not a silent auto-link — the user (or the discussing agent) decides whether this is the right change for this phase.
5. On success, report the `change-id` back so `discuss:post` can pick it up on the next `/gsd-discuss-phase` run — this skill does not write `OPENSPEC-LINK.md` itself; that is `discuss:post`'s job, scoped to when a phase discussion is actually happening.

## Outputs

- A validated OpenSpec change (artifacts owned by OpenSpec's own skills)
- A pass/fail report to the user, with the exact `validate --json` payload on failure

## Failure states

- `SPEC_VALIDATION_FAILED` — native validate reports issues; skill stops, surfaces issues verbatim.
- `SCOPE_MISMATCH` — change scope doesn't match the named phase goal; skill asks, does not assume.

## Guardrails

- Never writes OpenSpec artifacts directly — always delegates to `/opsx:propose`/`/opsx:ff`.
- Never marks a change "ready for planning" without a fresh `validate --json` pass on this exact run — a stale assumption from an earlier check is not evidence.
- Never silently narrows or widens the proposal's scope to match a phase goal — surfaces the mismatch instead.

## Idempotency

Re-running against an existing, valid change is a no-op after step 1 is skipped (native skill itself is idempotent — it won't recreate existing artifacts) — step 2's validation still re-runs, since "still valid" must be re-confirmed, not cached.

## Example

```
$ openspec-bridge-propose add-health-check-endpoint "Add a /healthz endpoint with readiness and liveness status" --phase 1
[openspec-bridge-propose] delegating to /opsx:propose add-health-check-endpoint
✓ proposal.md, specs/health-check/spec.md, design.md, tasks.md created
[openspec-bridge-propose] openspec validate --change add-health-check-endpoint --json → all items valid
[openspec-bridge-propose] scope matches Phase 1 goal ("Operational readiness basics") — ready for /gsd-discuss-phase 1
```