git:20261022.bd117e7 to git:20261023.9bbc790

---

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

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.