Openspec Workflow

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 | Read change artifact status as JSON | | instructions | Get AI-readable next-step instructions | | validate | Validate all OpenSpec specs and changes | | archive | 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 python skills/openspec-workflow/scripts/openspec_cli.py doctor

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

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

uv run python skills/openspec-workflow/scripts/openspec_cli.py status --change  --format json
uv run python skills/openspec-workflow/scripts/openspec_cli.py instructions  --change  --format json

1. Validate before implementation completion or archive:

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.

When a non-trivial change has user-pivotal scope or approach forks, apply instructions/global.md Depth routing and invoke /grill-me before creating or continuing change artifacts.

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:

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:

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: wyattowalsh
• Source: wyattowalsh/agents
• License: MIT
• Homepage: https://agents.w4w.dev

Install and usage instructions live in the source repository linked above.