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:

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:

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:

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:

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.