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 truebefore code is written — they are the source of truth for correctness. The full lifecycle: propose, specify, plan, test, implement, verify, 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. Plan — write design.md (architecture) and tasks.md (scenario-owned work items)
4. Test — register failing test files before implementation
5. Implement — execute directly, with a bounded delegate, or through cleave when coordinated worktree isolation is justified
6. Verify — assess every scenario against implementation and test evidence
7. Archive — move completed change to baseline

Runtime Surface

OpenSpec lifecycle operations are exposed through the agent toolopenspec_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 grade "B"
And providers [anthropic, openai-codex, ollama] are available
When the route controller scores providers
Then the selected route preserves the requested grade intent
And the served bridge reports the authenticated provider/model that actually handles turns

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. Continue implementation directly, through a bounded delegate, or with cleave for coordinated child scopes
6. Assess implementation and tests against the original scenarios
7. openspec_manage(archive) closes the loop

Reconciliation

After implementation or assessment, the lifecycle may need reconciliation:

• If scenario assessment finds issues, reopen implementation and update lifecycle state
• 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