Design Tree
The design tree is a markdown-backed knowledge graph for tracking architecture exploration.
Each node is a markdown file in docs/ with structured sections: overview,
research, decisions, open questions, and implementation notes.
The Omegon project itself has design tree nodes tracking everything from provider routing policy to TUI color choices. The tree is visualized as an SVG on the Design Graph page.
Node Lifecycle
| Status | Meaning |
|---|---|
seed | Idea captured, not yet explored |
exploring | Active research and discussion |
resolved | Questions answered, design clear — awaiting formal gate |
decided | Ready for implementation. Can bridge to OpenSpec. |
blocked | Waiting on a dependency or external input |
deferred | Deliberately postponed |
Node Structure
Each design node has structured sections:
- Overview — what this node is about
- Research — findings with headings and content
- Decisions — choices with title, status (exploring/decided/rejected), and rationale
- Open Questions — unknowns that need resolution before deciding
- Implementation Notes — file scope and constraints for implementation
- Acceptance Criteria — Given/When/Then scenarios and falsifiability tests
Agent Tools
| Tool | Purpose |
|---|---|
design_tree(list) | List all nodes |
design_tree(node, id) | Read full node content |
design_tree(frontier) | Find nodes with open questions |
design_tree(ready) | Find decided nodes ready for implementation |
design_tree(blocked) | Find blocked nodes and what's blocking them |
design_tree_update(create) | Create a new design node |
design_tree_update(branch) | Spawn child node from a parent's open question |
design_tree_update(implement) | Bridge to OpenSpec — scaffold a change directory |
Implementation Bridge
When a design node reaches decided status, it can be bridged to the
OpenSpec lifecycle for implementation:
design_tree_update(implement)scaffolds an OpenSpec change directory- Specs are generated from the node's decisions and acceptance criteria
/cleaveparallelizes the implementation across git worktrees/assess specverifies the specs are satisfied- Node status updates as implementation progresses
Operator Commands
/checkin # Triage: open designs, active changes, recent issues
/status # Harness status including design tree summary