openspec-workflow git:20261022.bd117e7A

Immutable. This exact content never changes and is served at /api/v1/blob/40d6648a85a4a961.

---
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**: the preference in `AGENTS.md` (§ Preferences) is `user`, `agent` or `ask`.
  With `ask`, the question is asked at the start of **every session**; the answer applies to that session
  only. `archive` and `sync` always require explicit approval.
- **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.

- Did the refactor introduce weak types (bare strings, booleans or magic numbers carrying semantics)
  or incohesive helpers only to satisfy a size, complexity or CRAP threshold?
- Is the behavior or observability change (logs, metrics, traces) covered by a test, and is the
  refactor declared in the change report and `design.md`?

### 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.