---
name: openspec-workflow
description: "OpenSpec pipeline: explore → propose → apply → QA → review → archive, with a consistency checkpoint."
license: MIT
---

# OpenSpec pipeline

## Phases

```
explore → propose (proposal, specs, design, adr, tasks) → apply → QA → review → archive
```

### Artifact order

`proposal → specs → design → adr → tasks`

Each artifact is written only when its dependencies are complete and the user approves it.

### Rules

- **OpenSpec commands**: read-only ones (`list`, `show`, `status`, `instructions`, `context`, `validate`,
  `doctor`) the agent may run; mutating ones (`new change`, `archive`, `sync`) the user runs or are run
  with explicit permission. Ask once per session who runs them.
- **The user reviews each artifact** before moving to the next one.
- **Command syntax depends on the host**: the wrappers are generated by
  `openspec init/update --tools <host>`.
- **Never proceed without explicit approval.**
- **Phase gates** (orchestrated mode): artifact approval, **implementation start**, QA start, pull
  request, archive/merge. The user decides when implementation begins; it may be postponed to another
  session.

## Phases in detail

### 1. Explore

Think, ask, visualize. Do not implement. If the idea crystallizes, propose a change.

### 2. Propose

Generate proposal, specs, design, adr and tasks. Add `qa-scenarios.md` when the change has an
end-to-end flow worth testing.

### 3. Apply

TDD per task: red → green → refactor → commit. Run the project's quality gate before closing.

### 4. QA

Scenario inventory → gap analysis → execution. Approval requires `-FINAL` with zero open high-severity
findings.

### 5. Consistency checkpoint

Before QA: does the code implement the approved design? Did the scope change? Are the new ADRs
coherent? If there is drift, fix the design **before** spending QA and review iterations.

### 6. Review

Code review against the declared architecture and security, plus quantitative gates. No critical
findings and highs resolved → `-FINAL`.

### 7. Close the cycle

1. **Consistency check** (design → code): does the implementation match the approved design? Did the
   scope change? Are the new ADRs coherent?
2. **Documentation**: invoke `doc-writer`. It updates technical and functional documentation and returns
   a summary; if the code diverges from the specs, it flags the divergence instead of documenting it.
3. **Analyst validates** that the documentation matches the approved change and the specs.
4. **Pull request**: open it with the documentation included. The user reviews the PR **once**.
5. **Archive**: `openspec archive <change>` and sync the specs.
6. **Merge** (the user) and **cleanup** (branch + worktree).

## Limits

- Maximum 5 iterations between QA and review.
- If QA reports `BLOQUEADO` (3+ high findings on the second iteration), return to design with the user.
- No finding is closed silently: it is fixed or documented with the user's approval.