feat gets the full treatment — proposal, blocking-changes, specs, verification, tasks. ci, chore, and docs take two minutes with three short artifacts.
npm i -D @aligned-team/cospec
npx cospec initpnpm add -D @aligned-team/cospec
pnpm cospec initbun add -d @aligned-team/cospec
bun run cospec initcospec init scaffolds openspec/, materializes the eleven typed schemas, and generates agent skills for your harness. It's idempotent — run it again and a clean tree stays clean.
Once installed, the loop is the same for every change, only the artifact list changes:
cospec new feat add-widget # pick the type; cospec prints the artifact plan
cospec validate add-widget --strict
cospec apply add-widget # the gate — exit 0 clear, 2 blocked, 3 soft-blocked
# implement, checking off tasks.md as you go
cospec archive add-widget # validates, gates, archives, verifies the moveSee the full walkthrough, including how to author each artifact, in The workflow.
Every type gets a proposal and tasks; the rest scales with how much the change touches. This is the simplified view — schemas also mark artifacts opt (optional, sometimes trigger-promoted) as well as required and forbidden. For the full matrix, per-type rationale, and how the ## Surfaces trigger works, see Commit types & the artifact matrix.
| type | specs | verification | design | what it's for |
|---|---|---|---|---|
feat | ✅ | ✅ | – | a new feature — the full workflow |
fix | – | ✅ | – | a bug fix |
perf | – | ✅ | – | performance, behavior unchanged |
refactor | – | ✅ | ✅ | restructure, behavior unchanged |
revert | – | – | ✗ | roll back a shipped change |
build | ✗ | – | ✗ | build config, dependencies, lockfiles |
ci | ✗ | – | ✗ | CI workflows and automation |
chore | ✗ | ✗ | ✗ | maintenance |
docs | ✗ | ✗ | ✗ | documentation |
style | ✗ | ✗ | ✗ | formatting, no semantic change |
test | ✗ | ✗ | ✗ | tests for already-specified behavior |
✅ required · – optional · ✗ forbidden (cospec validate errors if present).