openspec-workflow

Use when planning, applying, validating, or archiving OpenSpec changes in this repo, or when downstream AI tools need OpenSpec JSON status/instructions.

openspec-workflow824 wordsMITRepo-owned

Use when planning, applying, validating, or archiving OpenSpec changes in this repo, or when downstream AI tools need OpenSpec JSON status/instructions.

Quick Start

Install:

npx skills add github:wyattowalsh/agents --skill openspec-workflow -y -g --agent antigravity --agent claude-code --agent codex --agent crush --agent cursor --agent gemini-cli --agent github-copilot --agent grok --agent opencode

Use: /openspec-workflow

Works with Claude Code, Gemini CLI, OpenCode, and other agentskills.io-compatible agents.

What It Does

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.

Modes

`$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

Critical Rules

Use OpenSpec for non-trivial changes to public asset formats, downstream tooling, docs generation, hooks, bundle metadata, or validation behavior.
Do not use OpenSpec for isolated typo fixes or single-file local edits where repo conventions fully determine the outcome.
Prefer uv run python skills/openspec-workflow/scripts/openspec_cli.py ... --format json when another AI tool needs machine-readable state or instructions.
Do not commit generated .claude, .cursor, .opencode, .github, .agent, .crush, .codex, or .gemini OpenSpec artifacts unless explicitly promoted.
Validate before archive; never archive a change that has unresolved task, spec, or validation gaps.
Keep downstream generated skills and commands local by default.
Report missing OpenSpec or Node tooling as blockers with the exact command to retry after setup.

Quick Path

Step — Diagnose setup before OpenSpec work:
Step — For non-trivial repo changes, create or continue an OpenSpec change using the generated upstream OpenSpec skills/commands when available.
Step — When generated upstream OpenSpec skills are not available, use repo wrappers for structured state:
Step — Validate before implementation completion or archive:

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
portable skill 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:

uv run python skills/openspec-workflow/scripts/openspec_cli.py init --apply
uv run python skills/openspec-workflow/scripts/openspec_cli.py 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

Agent Asset Changes

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

proposal
affected-surfaces
design
validation-matrix
tasks

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

Archive Readiness

Archive only after implementation and validation are complete. Keep proposal, affected surfaces, design, validation matrix, and tasks aligned with the final shipped state.

Canonical Vocabulary

Use these canonical terms exactly:

Term	Meaning
OpenSpec change	A proposed repo behavior or asset change tracked under `openspec/changes/`
Artifact	A proposal, design, task list, spec delta, or AI-readable instruction document
Downstream tool setup	Generated local skills, commands, or config for external agent harnesses
Archive	Finalize and move a completed change into the durable spec history
Validation matrix	The artifact that maps affected surfaces to required proof commands

Validation Contract

Run from this skill directory before declaring changes complete:

python scripts/check.py
uv run python skills/openspec-workflow/scripts/openspec_cli.py doctor --format json
uv run python skills/openspec-workflow/scripts/openspec_cli.py validate --format json

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.

Completion criteria:

scripts/check.py exits 0.
openspec_cli.py doctor and validate pass, or blockers include exact follow-up commands.
Skill directory stays free of repo control-plane CLI references.
The OpenSpec decision is grounded in repo policy and the actual affected files.
Required artifacts exist or are explicitly skipped with a reason.
Generated downstream artifacts are not committed unless explicitly promoted.

Field	Value
Source Type	`repo-owned`
Display Source	`github:wyattowalsh/agents`
Source Kind	`repo`
Installability	portable command
Review State	reviewed
Target Agents	`antigravity`, `claude-code`, `codex`, `crush`, `cursor`, `gemini-cli`, `github-copilot`, `grok`, `opencode`

Field	Value
Name	`openspec-workflow`
License	MIT
Version	1.0.0
Author	Wyatt Walsh

Field	Value
Compatibility	Node >=20.19.0

View Full SKILL.md

---
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.
compatibility: "Node >=20.19.0"
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 python skills/openspec-workflow/scripts/openspec_cli.py 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 python skills/openspec-workflow/scripts/openspec_cli.py status --change <change> --format json
uv run python skills/openspec-workflow/scripts/openspec_cli.py instructions <artifact> --change <change> --format json
```

4. Validate before implementation completion or archive:

```bash
uv run python skills/openspec-workflow/scripts/openspec_cli.py 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
- portable skill 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 python skills/openspec-workflow/scripts/openspec_cli.py init --apply
uv run python skills/openspec-workflow/scripts/openspec_cli.py 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

### Agent Asset Changes

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.

### Archive Readiness

Archive only after implementation and validation are complete. Keep proposal, affected surfaces, design, validation matrix, and tasks aligned with the final shipped state.

## Canonical Vocabulary

Use these canonical terms exactly:

| Term                  | Meaning                                                                        |
| --------------------- | ------------------------------------------------------------------------------ |
| OpenSpec change       | A proposed repo behavior or asset change tracked under `openspec/changes/`     |
| Artifact              | A proposal, design, task list, spec delta, or AI-readable instruction document |
| Downstream tool setup | Generated local skills, commands, or config for external agent harnesses       |
| Archive               | Finalize and move a completed change into the durable spec history             |
| Validation matrix     | The artifact that maps affected surfaces to required proof commands            |

## Validation Contract

Run from this skill directory before declaring changes complete:

```bash
python scripts/check.py
uv run python skills/openspec-workflow/scripts/openspec_cli.py doctor --format json
uv run python skills/openspec-workflow/scripts/openspec_cli.py validate --format json
```

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`.

Completion criteria:

1. `scripts/check.py` exits 0.
2. `openspec_cli.py doctor` and `validate` pass, or blockers include exact follow-up commands.
3. Skill directory stays free of repo control-plane CLI references.
4. The OpenSpec decision is grounded in repo policy and the actual affected files.
5. Required artifacts exist or are explicitly skipped with a reason.
6. Generated downstream artifacts are not committed unless explicitly promoted.

## Critical Rules

1. Use OpenSpec for non-trivial changes to public asset formats, downstream tooling, docs generation, hooks, bundle metadata, or validation behavior.
2. Do not use OpenSpec for isolated typo fixes or single-file local edits where repo conventions fully determine the outcome.
3. Prefer `uv run python skills/openspec-workflow/scripts/openspec_cli.py ... --format json` when another AI tool needs machine-readable state or instructions.
4. Do not commit generated `.claude`, `.cursor`, `.opencode`, `.github`, `.agent`, `.crush`, `.codex`, or `.gemini` OpenSpec artifacts unless explicitly promoted.
5. Validate before archive; never archive a change that has unresolved task, spec, or validation gaps.
6. Keep downstream generated skills and commands local by default.
7. Report missing OpenSpec or Node tooling as blockers with the exact command to retry after setup.

Download from GitHub

Resources

Skill Catalog Browse custom and external skills.

CLI Reference Install and manage skills.

agentskills.io The open ecosystem for cross-agent skills.

View source on GitHub