ODF Architecture
This document maps the components of ODF and explains how they interact.
Visual version: phase flow · harness architecture · delegation efficiency (interactive HTML).
#Workflow Model
ODF runs the thin-spine workflow:
health/preflight → one resolved route → only its required stages → archive when applicable
The delegation API accepts the canonical stage plus a role only for the two composite stages. This is the single vocabulary table:
| Canonical stage | Roles | Applies when | Role artifacts |
|---|---|---|---|
DECIDE |
PROPOSE + ASSESS |
routes that include DECIDE; terminal for standard config | canonical decision, or propose + assess; expectations when delegated |
PLAN |
QA-PLAN + DESIGN |
only when the resolved route or risk requires formal planning | canonical plan, or design; qa-plan when routed |
BUILD |
— | the route's required plan is closed | canonical build/implement-progress |
VERIFY |
— | verification is required | verify-report |
FIX |
— | bugfix route (terminal FIX, then BUILD/VERIFY) | fix |
EXPLORE |
— | investigation | explore |
Rules: state.yaml (or odf/{change}/state) persists the canonical stage. A
composite stage requires one of its roles; single-role stages reject a role.
Role identifiers still name the artifact and the agent capability inside the
registry, but they are not a separate workflow stage and are never accepted as
a top-level delegation stage.
The executable artifact names, aliases, route completion alternatives, and
OpenSpec discovery stems are centralized in odf-plugin/odf-artifact-contract.ts;
the store values and their supported subsets live in odf-plugin/odf-artifact-stores.js.
odf_workflow_status exposes a typed
next_handoff built from that route, selected store, and persisted artifact
references; the orchestrator forwards it unchanged instead of reconstructing
the next stage role's inputs from result prose. The route/stage/artifact/gate
matrix lives in docs/route-contract.md.
The user sees one route selected by work_type; triage level (micro,
standard, full), canonical stages, and stage roles are internal mappings,
not extra user-facing stages. The optional shadow prediction is advisory and
does not change execution.
Every code-changing route carries focused QA tied to approved Expectations.
Small changes, inline features, and bugfixes keep a compact test/check plan
inline and do not require a separate qa-plan artifact. Routes requiring PLAN,
or an explicit risk/complexity escalation, use formal QA-PLAN.
QA-REVIEW/QA-AGGREGATE/QA-REPORT run only when routed. The concrete route is
resolved per work type (standard config can stop after DECIDE; small change and
feature-inline are DECIDE → BUILD → VERIFY; a bugfix is FIX → BUILD → VERIFY;
feature/cross-domain/migration/security use DECIDE → PLAN → BUILD → VERIFY;
investigation uses EXPLORE). feature-inline runs its bounded ASSESS only when
the deterministic entry gate selects assess; a clear entry binds a terminal
DECIDE with no ASSESS delegation. Required VERIFY and evidence gates are never
removed by inline QA.
#Component Overview
┌─────────────────────────────────────────────────────────────────────┐
│ User / OpenCode Chat │
└──────────────┬──────────────────────────────────────────────────────┘
│ /odf-new, /odf-continue, /odf-status, /odf-explore
▼
┌──────────────────────────────┐
│ command/*.md definitions │ ← parse args, route to orchestrator
└──────────────┬───────────────┘
│
▼
┌──────────────────────────────┐
│ agent/odoo_orchestrator.md │ ← preflight gate, thin-spine state,
│ │ policy gate, receipts
└──────────────┬───────────────┘
│ odf_delegate(stage, role, prompt, context_files)
▼
┌──────────────────────────────┐
│ plugins/odf-delegation.ts │ ← resolve agent/skills, select transport,
│ │ route + status adapters, gates
└───────┬──────────────┬───────┘
│ │
▼ ▼
┌──────────────┐ ┌──────────────┐
│ odf-registry │ │ Transport │
│ .json │ │ adapter/SDK │
└──────────────┘ └──────┬───────┘
│
▼
┌─────────────────┐
│ stage role agents │ ← odoo_backend_engineer, etc.
└────────┬────────┘
│
▼
┌─────────────────┐
│ skills/<name>/ │ ← compact rules + stage body
└─────────────────┘
#Persistence Roles
The workflow selects one authoritative artifact store:
- OpenSpec (
openspec/changes/{change}/): versioned workflow state (state.yaml) and artifacts. It is authoritative when selected, and is the canonical authority for Hybrid. - Engram: artifacts at deterministic
odf/{change}/{artifact-type}refs. It is authoritative for Engram-only changes and a recovery mirror for Hybrid. - Hybrid: OpenSpec is authoritative; matching Engram state/artifacts are mirrored on commits. A commit must not report success if either write fails.
.odf/*.json: runtime seals — Policy Gate (policy-gate-{change}.json), validation evidence (validation-evidence-{change}.json), and failure receipts (receipt-{change}.json).
The status adapter (odf_workflow_status) reads the bound authority and runtime
sidecars read-only. Hybrid reads prefer OpenSpec and may recover missing state
from its Engram mirror; a change without a canonical state is reported as
state_kind: none and is not resumable. Old changes are never rewritten
automatically, and status never changes the bound store.
#Component Responsibilities
#odf-registry.json
Source of truth for:
- Skills with triggers, compact rules, paths, and Odoo version support.
- Agents with stage-role eligibility, descriptions, and paths.
- Profiles with per-role model/temperature settings.
- Commands registered for native orchestrator routing.
- Package metadata (name, version, repository, dependencies).
- Flags such as
use_relative_pathsandpr_size_budget.
Relative paths are resolved against the directory containing odf-registry.json. Absolute legacy paths keep working.
#plugins/odf-delegation.ts
The ODF delegation engine and plugin entrypoint. Exposes tools such as
odf_delegate, odf_delegation_prepare, odf_delegation_launch, odf_delegation_seal,
odf_workflow_route, odf_workflow_status,
odf_workflow_override, odf_workflow_bind, odf_entry_triage,
odf_skill_inject, odf_skill_resolve, odf_registry_read,
odf_profile_select, odf_policy_gate,
and odf_receipt.
odf_delegation_prepare/odf_delegation_launch/odf_delegation_seal implement
the native prepare/launch/seal route (roadmap #55): prepare resolves the agent,
skills, profile and source-authority contract and returns the enriched prompt
plus a bounded odf-tok-… token under .odf/; launch verifies the prompt
digest and submits it through the V2 session API; seal independently verifies
the child transcript, reads its ODF Result, runs composite gates and returns the
standard delegation envelope. Fast-lane BUILD/VERIFY still use odf_delegate.
Seal binds the child to its running attempt once the exact prepared prompt and
idle state are proven, even when no assistant result exists: an aborted child
reports delegation-child-aborted and an idle child without text reports
delegation-child-no-result, so settle-attempt can recover the attempt
instead of leaving it running with no supported settlement path.
The entrypoint stays a monolith for the delegation/workflow core but its
self-contained sections live in cohesive modules under odf-plugin/:
odf-delegation-shared.ts— safe paths, registry path resolution, the registry type model,ODF_REGISTERED_TOOLS.odf-delegation-metrics.ts— telemetry records, flush loop, token estimation.odf-delegation-health.ts— read-only health inspection, the native task adapter (when exposed), SDK session fallback, and result normalization helpers.
The entrypoint re-exports their public names, so imports and tests keep working unchanged.
odf_delegate does the following:
- Loads the registry.
- Resolves the target agent from the stage role and task keywords (shared logic in
scripts/lib/agent-resolve.js— single source of truth also used by the test runner andodf-toolkit;matchSkillsstays per-consumer because the plugin uses a role-aware canonical variant). - Matches up to 5 relevant skills.
- Injects compact rules for matched skills, the canonical stage skill's full
SKILL.mdbody, and the active SDD profile into the prompt. - Enforces the authoritative TDD Policy Gate for BUILD/VERIFY, the
stop-validation evidence seal,
design_closedcoercion, and claimedartifact_refexistence. - Uses the explicit native task adapter when the host exposes
toolCtx.task; otherwise creates an isolated child withclient.session.createand sendsclient.session.promptwith the agent, known model, and relative context references. SDK metadata binding is best-effort. - Returns a result envelope with
status(delegated,blocked,error,timeout),agent,skills, andresult; unavailable task APIs block without an executable fallback prompt, and task failures auto-seal a receipt.
The SDK session fallback is the supported current-runtime transport because the
official ToolContext does not expose task. It preserves ODF's gates,
receipts, metrics, timeout, cancellation, and result validation, but it cannot
reproduce native task permission derivation; native host permissions remain the
authority when the adapter is available.
odf_workflow_route resolves the canonical thin-spine route for a work type;
odf_workflow_status derives canonical status (read-only) from
OpenSpec/Engram/.odf with OpenSpec as authority, including nested OpenSpec
artifact discovery, the binding_pending marker, and recovery_work_type_required
for canonical states without a work type. odf_workflow_override is the
audited escape hatch (skip DECIDE/PLAN, re-enter, re-plan with Expectations
revisions); BUILD/VERIFY can never be skipped.
#scripts/lib/
Shared deterministic libraries consumed by the plugin, the CLIs, and the test runner:
preflight.js— preflight validation/defaults (includingvalidation_mode).agent-resolve.js— STOP_WORDS, filterStopWords, and score-basedresolveAgent(single source of truth; the scoring fix lives in exactly one place).orchestrator.js— legacy state-machine helpers for the YAML scenario runner.
#Deterministic CLIs (scripts/)
odf-project-scan.js— full Doodba environment scan (addons.yaml sources, compose, linting, git, CodeGraph, dependency matrix), verified persistence, checksum cache,--diff,--deep, exit codes.odf-toolkit.js— read-side subcommands:context(CodeGraph explore),state,result,resolve,evidence,metrics,manual-evidence,redundancy.odf-env-detect.js— Doodba addons.yaml parser + dependency matrix (lib used by the scan).odf-safety.js— pre-tool safety inspection.odf-metrics.js,odf-estimator.js,odf-design-library.js,odf-learning-bridge.js,odf-engram-maintenance.js— observability and learning helpers.odf-evaluation.js— offline/online/golden evaluation plus the decision-quality report (decisions), local review, agreement, period comparison, cadence, and human-approved proposals; seedocs/decision-evaluation.md.odf-harness.test.ts(npm run test:harness) — integral smoke test: real registry, triage/workflow/status/expectations/resolve, every CLI subcommand end-to-end, safety inspection, and registry path integrity.
#agent/odoo_orchestrator.md
Conversational state machine. It:
- Runs the preflight gate before delegating any stage role.
- Loads and persists change state to OpenSpec/Engram.
- Resolves the thin-spine route (
DECIDE→ optionalPLAN→BUILD→VERIFY) via the workflow route tool. - Shows approval gates after each stage role.
- Consults
odf_workflow_statusfor canonical stage/resumable state. - Decides the next stage and calls
odf_delegate. - Handles
/odf-continueand/odf-statuslogic.
#command/*.md
Slash command definitions. They parse arguments and route to the orchestrator. They contain no business logic. The native orchestrator commands are:
/odf-new/odf-continue/odf-status/odf-explore
#install.sh + package.json
install.sh deploys the ODF pack idempotently. It:
- Validates prerequisites (python3, curl/wget, Node.js 18+).
- Creates a timestamped backup.
- Merges files into
ODF_DIR. - Runs
npm installifpackage.jsonexists. - Runs the ODF self-test.
package.json declares Node dependencies, test scripts, and peer dependencies for the OpenCode plugin SDK.
#scripts/odf-test-runner.js
Regression runner. It:
- Runs Vitest unit tests when
--plugin-testsis passed. - Discovers and runs YAML scenario suites from
scripts/odf-agent-tests/. - Supports suite types: agent, preflight, orchestrator, cli, installer, registry.
#Data Flow
#/odf-new
command/odf-new.mdparses change name, optional description, and--fast.- Orchestrator loads existing change state if any.
- If preflight is missing/invalid, the orchestrator asks preflight questions.
- Preflight record is written to
openspec/changes/{change}/state.yaml. - Orchestrator resolves the thin-spine route for the work type.
- It builds one bounded Context Manifest (
odf_context_manifest) after the entry gate and approved Expectations, and forwards it unchanged to ASSESS and BUILD. - It runs DECIDE through its PROPOSE and ASSESS roles via
odf_delegate. Forfeature-inline, the deterministic entry gate selectsskip(terminaldecision),assess(one bounded ASSESS), orescalate(formalfeatureroute). - Plugin resolves agent/skills, enforces gates, selects the native adapter or SDK child-session transport, and returns the result.
- Orchestrator updates state and shows an approval gate.
- Optional PLAN, then BUILD, then VERIFY repeat the delegate-update-gate cycle according to the resolved route.
Every blocked or failed envelope carries a stop_disposition, so the
orchestrator reports the named continuation instead of guessing a recovery.
#/odf-continue
command/odf-continue.mdparses optional change name.- Orchestrator consults
odf_workflow_statusfor the canonical stage, pending stage, resumable flag, and receipt. - If no name is given, continues only when discovery is complete and exactly one active change exists; otherwise it asks the user to choose or reports the discovery blocker. It never selects by recency.
- If the receipt is pending, it re-presents the failure disposition with evidence and stops.
- Determines the next pending canonical stage from status.
- Calls
odf_delegatefor that stage role. - Updates state and shows the gate.
#/odf-status
command/odf-status.mdparses optional change name.- Orchestrator calls
odf_workflow_status(read-only); OpenSpec state is authority, Engram completes missing groups with warnings. - Renders a table or single-change detail including
canonical_stage,pending_stage,resumable,receipt,progress, andsource.
#/odf-explore
command/odf-explore.mdparses topic,--version, and--module.- Orchestrator delegates a short research task via
odf_delegate(stage="EXPLORE"). - Returns an exploration report and suggests
/odf-newif needed.
#State Shape
Runtime state and role artifacts live in the selected authoritative store:
openspec/changes/{change}/state.yaml for OpenSpec, deterministic
odf/{change}/{artifact-type} refs for Engram, or synchronized representations
for Hybrid. Hybrid reads prefer OpenSpec and may recover missing state from the
Engram mirror, but do not merge conflicting artifact content. Runtime seals
remain in .odf/*.json.
When completed_canonical_stages is present, it is the completion record used
by workflow status. A stage omitted from the list stays pending even if a fresh
artifact exists: a child can write artifact bytes before its parent seal
commits the stage. Those bytes remain visible, but do not advance the workflow.
States without this list fall back to explicit completion flags and artifact
evidence.
change: my-feature
canonical_stage: PLAN # DECIDE | PLAN | BUILD | VERIFY | ARCHIVED
completed_canonical_stages: [DECIDE] # stages committed by workflow transitions
preflight:
change: my-feature
execution_mode: auto
artifact_store: hybrid
delivery_strategy: ask-on-risk
review_budget_lines: 400
odoo_version: 18
tdd_mode: false
solution_strategy: custom
chain_strategy: feature-branch
persisted_at: "2026-06-18T00:00:00Z"
project:
name: my-project
odoo_version: 18
test_command: npm test
lint_command: npx tsc --noEmit
artifacts:
decision: true
plan: false
build: false
verify: false
tasks_progress:
completed: ["1.1", "1.2"]
pending: ["1.3"]