cospec — conventional openspec: OpenSpec change management, sized to your
commit type. feat gets the full treatment; ci takes two minutes.
cospec ships as standalone executables — one per platform — so it runs with no JS runtime required, and installs cleanly on Node, Deno, or Bun.
mise use github:aligned-team/cospec
cospec initThe binary is fully self-contained: no JS runtime, no node_modules, no extra
install step. It embeds the pinned OpenSpec CLI as a single-file bundle and runs
it with its own bun runtime, so every wrapped command (new, validate,
apply, archive, …) works out of the box.
mise's github backend applies a default release-age cooldown (
minimum_release_age) that hides very recent releases from "latest" resolution. If you're testing a release cut in the last day or so and it doesn't show up, pin the exact version instead:mise use github:aligned-team/cospec@0.5.2(a fullmajor.minor.patch, not@0.5) — exact pins bypass the cooldown.
Works with Node, Deno, and Bun — the launcher execs the prebuilt binary for your
platform. With a project install, wrapped commands use your project's
node_modules@fission-ai/openspec (any >=1.0.0 <2.0.0) as before; the
embedded copy is the fallback when none is installed:
npm i -D @aligned-team/cospec && npx cospec init
pnpm add -D @aligned-team/cospec && pnpm cospec init
bun add -d @aligned-team/cospec && bun run cospec initgit clone https://github.com/aligned-team/cospec
cd cospec
mise install && bun install
mise run cospec -- initcospec init scaffolds openspec/, materializes the eleven typed schemas, and
generates agent skills for your harness. It is idempotent — run it again and a
clean tree stays clean.
cospec is a thin wrapper around
OpenSpec1.5.0 that maps the
spec-driven workflow onto your conventional-commit type. One schema per type;
the heavier the type, the more the workflow asks of you.
| type | proposal | blocking-changes | specs | design | verification | tasks | what it's for |
|---|---|---|---|---|---|---|---|
feat | full | full | ✅ | opt | ✅ | ✅ | a new feature — the full workflow |
fix | full | full | opt | opt | ✅ | ✅ | a bug fix |
perf | full | full | opt | opt | ✅ | ✅ | performance, behavior unchanged |
refactor | full | full | opt | ✅ | ✅ | ✅ | restructure, behavior unchanged |
revert | full | full | opt | ✗ | opt | ✅ | roll back a shipped change |
build | lite | lite | ✗ | ✗ | opt | ✅ | build config, dependencies, lockfiles |
ci | lite | lite | ✗ | ✗ | opt | ✅ | CI workflows and automation |
chore | lite | lite | ✗ | ✗ | ✗ | ✅ | maintenance |
docs | lite | lite | ✗ | ✗ | ✗ | ✅ | documentation |
style | lite | lite | ✗ | ✗ | ✗ | ✅ | formatting, no semantic change |
test | lite | lite | ✗ | ✗ | ✗ | ✅ | tests for already-specified behavior |
✅ required · opt optional · ✗ forbidden (cospec validate errors if present).
For verification, opt means trigger-promoted: absent by default, but checking
a ## Surfaces flag in the proposal soft-nudges it into the apply gate. Full
matrix and per-type rationale: docs/schemas.md.
cospec never replaces OpenSpec — it wraps the real, version-pinned binary
(resolved by path, spawned, never $PATH) and adds typed schemas, real change
validation with stable rule IDs, a deterministic apply gate, a
filesystem-verified archive, a machine-parsed verification evidence ledger
enforced by hard archive gates, ## Surfaces proposal flags that soft-trigger
verification and design sections, versioned schemas with schemaVersion
grandfathering, and a blocking-changes ledger with auto-sync.
| command | what it does |
|---|---|
cospec init [path] | scaffold openspec/, schemas, and harness files (idempotent) |
cospec update [--check] | re-generate managed files from canon; --check is a drift gate |
cospec doctor | read-only health check, incl. changes still on schemaVersion 1 |
cospec new <type> <slug> | create a typed change; prints the artifact plan |
cospec migrate <change> | stamp a grandfathered change to the current schemaVersion, scaffolding deferred verification |
cospec validate [name] | validate changes and specs (--all/--changes/--specs); --strict promotes warnings |
cospec status / cospec list | change status with type, gate, and archive-readiness columns (list --specs lists living specs) |
cospec instructions <artifact> | print the authoring instruction for one artifact |
cospec apply <change> | the gate — exit 0 clear, 2 blocked, 3 soft-blocked |
cospec archive <change> | validate, archive, verify the move, fan out blocker sync |
cospec sync-blockers | check off blocker entries whose target has shipped |
cospec show <item> | read a change or spec's markdown or JSON |
cospec view | the OpenSpec dashboard |
cospec store <sub> | manage stores: setup/register (auto-init) / unregister / remove / ls / doctor |
cospec context | a store's cross-repo working-set brief (--json, --code-workspace) |
cospec workset <sub> | personal cross-repo working views: create / list / remove / open |
cospec schemas / schema | inspect resolvable schemas (schema which/validate) |
cospec templates | list per-artifact template paths |
Global flags on every command: --json, --no-color, --cwd <path>,
--store <id>. --store runs the whole change lifecycle against a registered
OpenSpec store (a standalone planning repo) instead of the local repo — one
source of truth several code repos can plan against. cospec wraps every store,
context, and workset operation too, so you never drop out to bare openspec.
See docs/stores.md. Full reference:
docs/validation.md (rules) and
docs/apply-archive.md (gate + archive algorithms).
- new —
cospec new feat add-widgetpicks the type and writes.openspec.yaml; cospec prints how heavy the type is. - propose — author each artifact with
cospec instructions <artifact> --change add-widget, thencospec validate add-widget --strict. Forfeat/fix/perf/refactor,cospec instructions verificationplans the acceptance-evidence ledger before you write any code. - apply —
cospec apply add-widgetis the gate. Obey the exit code:0clear (work the tasks),2blocked (stop, report the blockers),3soft-blocked (confirm with the user, then re-run with--allow-soft). The gate is deterministic — never re-derive it from files. - implement — check off
tasks.mdas you go, and record verification evidence: mark each row[x]with the observed result after->, or[~] defer: <reason>for a row you will not run. - archive —
cospec archive add-widgetvalidates, gates on unchecked tasks and on the two hard verification gates (archive/verification-incomplete,archive/scenario-preservation— no--force), delegates toopenspec archive, verifies the directory actually moved on disk, and checks off this change's slug in every other change's blocking-changes ledger. - flywheel — archiving reports which changes just became unblocked and the
exact
cospec applyto run next.
cospec init --harness <list> generates agent files by direct project-file
injection — no marketplaces, no plugin packages, no global state. Every workflow
calls only cospec commands, so a single permission entry covers the whole
loop.
- Claude Code —
.claude/commands/cospec/*.md(/cospec:propose …) and.claude/skills/cospec-*/SKILL.md. init additively mergesBash(cospec *)into.claude/settings.json. Restart Claude Code to pick up the/cospec:*commands. - Codex —
.codex/skills/cospec-*/SKILL.mdplus.codex/rules/cospec.rules, which pre-approves the read-only and gate calls (archiveis intentionally not pre-approved). Skills load per session. - OpenCode —
.opencode/commands/cospec-*.md(full bodies) and.opencode/skills/cospec-*/SKILL.md. Reload the project.
Details and a per-harness smoke checklist: docs/harness-integration.md.
cospec pins @fission-ai/openspec1.5.0 for its own dev/CI and accepts any
>=1.0.0 <2.0.0 at runtime (the range is asserted at startup; the pin is the
build the contract suite is probed against) and adds, on top of it:
- Typed schemas — eleven schemas, one per conventional-commit type, with a required/optional/forbidden artifact matrix instead of one generic workflow.
- Real validation —
cospec validateruns cospec's own rules (stable IDs, greppable) as a superset of the satisfiable OpenSpec checks. - A gated apply — a deterministic blocker gate with an exit code an agent cannot rationalize past, backed by the same rule in schema prose.
- A verified archive — filesystem verification that catches OpenSpec's exit-0-but-aborted failure mode, plus a spec-merge spot-check.
- A verification ledger — a machine-parsed acceptance-evidence artifact
(
verification.md) that archive gates on: every[critical]behavior needs recorded evidence, and unfinished rows block the move (no--force). - Surface triggers and grandfathering — closed
## Surfacesproposal flags that soft-promote verification/design without ever hard-requiring them, and versioned schemas so pre-verification changes stay unblocked until an explicitcospec migrate. - Blocker sync — a machine-parsed dependency ledger that checks itself off as dependencies ship.
- architecture.md — wrapper boundaries, the wrapped-call discipline, the failure modes cospec defends against
- schemas.md — the artifact matrix, per-type rationale, customization tiers
- validation.md — every rule ID with an example failure
- apply-archive.md — the apply gate and archive algorithms as a user-facing contract
- blocking-changes.md — the ledger grammar and sync semantics
- harness-integration.md — per-harness files, the managed-file protocol, coexistence with OpenSpec's own files
- eval.md — the advisory DeepSeek eval and its redaction contract
- self-hosting.md — how cospec manages its own
openspec/tree - release.md — the npm + binary release pipeline, required secrets, and trusted publishing (OIDC) with provenance
See CONTRIBUTING.md. We self-host: every substantive change to this repo is a cospec-typed OpenSpec change.
See SECURITY.md.