---
name: openspec-workflow
description: Use when planning, applying, validating, or archiving OpenSpec changes in this repo, or when downstream AI tools need OpenSpec JSON status/instructions. NOT for generic code review, unrelated docs edits, or replacing generated upstream openspec-* skills.
license: MIT
metadata:
  author: Wyatt Walsh
  version: 1.0.0
---

# OpenSpec Workflow

Use OpenSpec as the spec/change control plane for non-trivial changes to this repository's portable agent assets, downstream tooling, docs generation, hooks, bundle metadata, or validation behavior.

## Dispatch

| `$ARGUMENTS` | Action |
|---|---|
| Empty | Show the repo OpenSpec quick path |
| `doctor` | Diagnose OpenSpec toolchain and project state |
| `init [tools]` | Materialize downstream OpenSpec skills/commands locally |
| `status <change>` | Read change artifact status as JSON |
| `instructions <artifact> <change>` | Get AI-readable next-step instructions |
| `validate` | Validate all OpenSpec specs and changes |
| `archive <change>` | Validate and archive a completed change |
| Natural language change request | Decide whether OpenSpec is warranted, then create or continue a change |

## Quick Path

1. Diagnose setup before OpenSpec work:

```bash
uv run wagents openspec doctor
```

2. For non-trivial repo changes, create or continue an OpenSpec change using the generated upstream OpenSpec skills/commands when available.

3. When generated upstream OpenSpec skills are not available, use repo wrappers for structured state:

```bash
uv run wagents openspec status --change <change> --format json
uv run wagents openspec instructions <artifact> --change <change> --format json
```

4. Validate before implementation completion or archive:

```bash
uv run wagents openspec validate
```

## When To Use OpenSpec

Use OpenSpec when the change affects any of these surfaces:

- `skills/`, `agents/`, `mcp/`, `mcp.json`, or first-party MCP conventions
- `AGENTS.md`, `instructions/`, or platform bridge files
- `agent-bundle.json`, plugin manifests, sync manifests, or downstream harness setup
- `wagents` CLI behavior, generated README/docs output, or docs navigation
- OpenSpec specs, schemas, or generated downstream tool setup

Skip OpenSpec for small, isolated typo fixes or single-file local changes where the user's request and repo conventions fully determine the outcome.

## Downstream Tooling

OpenSpec-generated upstream skills and commands are local/generated by default. Materialize them when a downstream tool should expose native OpenSpec workflows:

```bash
uv run wagents openspec init --apply
uv run wagents openspec update --apply
```

The default repo mapping is:

| Repo agent | OpenSpec tool |
|---|---|
| `antigravity` | `antigravity` |
| `claude-code` | `claude` |
| `codex` | `codex` |
| `crush` | `crush` |
| `cursor` | `cursor` |
| `gemini-cli` | `gemini` |
| `github-copilot` | `github-copilot` |
| `opencode` | `opencode` |

Do not commit generated `.claude`, `.cursor`, `.opencode`, `.github`, `.agent`, `.crush`, `.codex`, or `.gemini` OpenSpec artifacts unless the user explicitly promotes a specific artifact to repo-owned source.

## Artifact Order

For this repo's custom `agent-asset-change` schema, create artifacts in this order:

1. `proposal`
2. `affected-surfaces`
3. `design`
4. `validation-matrix`
5. `tasks`

Use `openspec status --json` to confirm which artifact is ready before asking the AI to create it.

## Validation Contract

Before claiming OpenSpec work is complete, run the relevant commands:

- `uv run wagents openspec validate` for OpenSpec specs, schemas, or changes
- `uv run wagents validate` for skill, agent, MCP, and hook changes
- `uv run wagents readme --check` when README generation or skill descriptions changed
- `uv run wagents docs generate` or docs tests when docs generation changed

If a command is blocked by missing Node/OpenSpec tooling, report the blocker and the exact command that should be run after installing Node `>=20.19.0`.