Use when planning, applying, validating, or archiving OpenSpec changes in this repo, or when downstream AI tools need OpenSpec JSON status/instructions.
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.
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.
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 |
| `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`.
