OpenSpec Lifecycle

OpenSpec is the spec-driven development system in Omegon. Specs define what must be true before code is written — they are the source of truth for correctness. The full lifecycle: propose, spec, fast-forward, cleave, assess, archive.

Lifecycle Stages

1. Propose — create a change with a name, title, and intent
2. Spec — write Given/When/Then scenarios defining acceptance criteria
3. Fast-Forward — generate design.md (architecture) and tasks.md (work items) from specs
4. Execute — implement via /cleave (parallel) or direct coding
5. Verify — /assess spec checks that implementation satisfies all scenarios
6. Archive — move completed change to baseline

Commands

Spec Format

## Scenario: Provider routing selects best match

Given a routing request for tier "victory"
And providers [anthropic, openai, ollama] are available
When the routing engine scores providers
Then anthropic is selected (highest capability match)
And ollama is ranked last (local tier only)

Directory Structure

openspec/
├── changes/
│   └── my-feature/
│       ├── proposal.md     # Intent and scope
│       ├── specs/
│       │   └── routing.md  # Given/When/Then scenarios
│       ├── design.md       # Generated architecture (from /opsx:ff)
│       └── tasks.md        # Generated work items (from /opsx:ff)
└── baseline/
    └── archived-change/    # Completed changes (from /opsx:archive)

Integration with Design Tree

The primary entry point for tracked work is design_tree_update(implement) on a decided design node. This scaffolds the full OpenSpec change directory automatically, linking the design node to the implementation lifecycle.

1. Design node reaches decided status
2. design_tree_update(implement) creates the OpenSpec change
3. Specs are generated from the node's decisions and acceptance criteria
4. /opsx:ff generates design.md and tasks.md
5. /cleave executes the tasks in parallel
6. /assess spec verifies against the original specs
7. /opsx:archive closes the loop

Reconciliation

After implementation or assessment, the lifecycle may need reconciliation:

• If /assess spec finds issues, reconcile_after_assess reopens work
• If cleave adds files not in the original scope, tasks.md is updated
• Archive refuses to proceed if tasks are incomplete or design-tree binding is stale