openspec

An engineering standard. OpenSpec for the change in flight, ADRs for decisions that outlive it, Mermaid for how the system is organized

Skills: adr auto init
Carries: skillsresources

this project

uze openspec@ai

this machine

uze install openspec@ai -m

Three artifacts

Artifact	Answers	Lives in
OpenSpec change	What are we changing now?	`openspec/changes/<name>/`
ADR	Why is the system this way?	`docs/adr/NNN-*.md`
Architecture	How is the system organized?	the directory the project declares

The flow

Propose. A change gets proposal.md, specs/, design.md and tasks.md. Decisions that might deserve a record go under ## Candidate ADRs in the design.
Apply. The tasks are worked. What the plan didn't decide goes in the change's decisions.md. A change that moves a boundary updates its architecture diagram in the same change.
Archive. Only now are ADRs written, and only for candidates that pass all four questions:
- Is reversing it expensive?
- Was a real alternative rejected?
- Does it bind code that doesn't exist yet?
- Is it recorded nowhere else?

Most changes produce no ADR. Naming, refactors, bug fixes and version bumps never do.

Run it unattended

auto works the whole task list without you: verifies each item by exit code, commits one at a time, and writes every decision down for you to review. It stops for five things only:

a destructive action outside the change
a step that would break a spec
three failed attempts at one task
a credential or a leaked secret
a finding that kills the proposal's premise

init is user only: it writes openspec/, docs/adr/ and the schema into your repository, so it runs when you call it and never on its own. Every step checks before writing, and running it again is safe.

Skills

adr

model + user

Record one Architecture Decision Record under docs/adr/ when the user asks for it, or to backfill a past decision that predates this project's docs/adr/ convention. ADRs in the normal flow are written at archive time, not here - this skill is the out-of-band path, not a second routine door. Not for a decision taken while implementing a change (that goes in the change's decisions.md and is judged at archive), not for documenting how the system is built (that is the architecture diagrams), and not for a naming, layout, refactor or tuning choice however long it was argued.

Needs A project that ran the `init` skill, so docs/adr/ and its README exist.

Read adr/SKILL.md

auto

model + user

Work an OpenSpec change's tasks.md to completion without stopping for approval - deciding alone when the plan runs out, recording each decision for review afterwards, and interrupting only on a closed list of conditions. Use when a change should be implemented unattended - "implementa sozinho", "vai até o fim", "não me pergunta", an overnight run, a long task list nobody is watching. Not for adopting the standard in a project (that is `init`), not for writing a decision record (that is `adr`), not for committing work that is already finished (that is the `git` plugin's `commit`), and not for a change that has no tasks.md yet - write the plan first.

Needs A project that ran the `init` skill, a change with a tasks.md, git, and the `openspec` CLI on PATH for the validate gate.

Read auto/SKILL.md

init

user only

Adopt the personal engineering standard in this project - OpenSpec (proposal/specs/design/tasks) with ADRs written only at archive time, and Mermaid architecture diagrams. Use when someone asks to set this standard up, bootstrap a project onto it, or adopt it in an existing repository. Not for running a change through the standard once it is adopted (that is `auto`), not for writing a single decision record (that is `adr`), and not for setting up agent context portability across harnesses.

Needs The `openspec` CLI on PATH (npm `@fission-ai/openspec`) and python3, on Linux, macOS or Windows. Writes into the current project; run it from the project root.

Scripts openspec-init

Read init/SKILL.md

Bundled files

What init copies into a project. The copy tracks the plugin, so edits to it are overwritten on the next run.