OpenSpec Lifecycle

Discovery path: OpenSpec is a full-mode feature. In om (slim mode), the agent won't reference it. When you want spec-driven development — defining acceptance criteria before writing code — switch to full mode with /warp and ask the agent to create or manage an OpenSpec change.

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

Runtime Surface

OpenSpec lifecycle operations are exposed through the agent tool openspec_manage. The older /opsx:* slash commands are not part of the current Rust runtime.

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       # Architecture notes
│       └── tasks.md        # Work items tracked by register_tasks
└── baseline/
    └── archived-change/    # Completed changes

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. openspec_manage(register_tasks) records task progress from tasks.md
5. /cleave executes the tasks in parallel
6. /assess spec verifies against the original specs
7. openspec_manage(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