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
| Action |
|---|
| Empty | Show the repo OpenSpec quick path |
| Diagnose OpenSpec toolchain and project state |
| Materialize downstream OpenSpec skills/commands locally |
| Read change artifact status as JSON |
instructions <artifact> <change>
| Get AI-readable next-step instructions |
| Validate all OpenSpec specs and changes |
| Validate and archive a completed change |
| Natural language change request | Decide whether OpenSpec is warranted, then create or continue a change |
Quick Path
- Diagnose setup before OpenSpec work:
bash
uv run python skills/openspec-workflow/scripts/openspec_cli.py doctor
-
For non-trivial repo changes, create or continue an OpenSpec change using the generated upstream OpenSpec skills/commands when available.
-
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
- 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:
- , , , , or first-party MCP conventions
- , , or platform bridge files
- , 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
Depth routing and invoke
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:
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:
Do not commit generated
,
,
,
,
, or
OpenSpec artifacts unless the user explicitly promotes a specific artifact to repo-owned source.
Artifact Order
Agent Asset Changes
For this repo's custom
schema, create artifacts in this order:
Use
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 |
| 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
.
Completion criteria:
- exits 0.
- and 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.
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 scripts/openspec_cli.py ... --format json
- Do not commit generated , , , , , , , or 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.