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

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:

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
claude-code	claude
codex	codex
crush	crush
cursor	cursor
opencode	opencode

Do not commit generated .claude, .cursor, .opencode, .agent, .crush, or .codex 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.