openspec-workflow · diff

git:20261021.410d14f to git:20261021.79e279d

3 added, 3 removed. Audit A to A.

---

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.

+ - **OpenSpec commands**: the preference lives in `AGENTS.md` (§ Preferences). Read-only commands the

+ agent may run; mutating ones follow the preference and require explicit approval for `archive`/`sync`.

+ Ask only if the preference is missing, and offer to persist it.

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