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: after explicit user approval, run openspec archive <change> and sync the specs; commit the archive in the same PR.
6. Merge (the user) and cleanup (branch + worktree).

If the PR is merged without archive, do not rewrite main: open a new archive branch/PR, archive and merge it. If a review after archive changes specs, design or tasks, unarchive, fix, validate and archive again.

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.