ODF docs
GitHub ↗
Documentation menu

ODF Agent Team — AGENTS.md

9 min read

This repo is the source for the ODF Agent Team, an OpenCode skill/agent pack for structured Odoo development. It is not an Odoo project itself. It installs into ~/.config/opencode/ via install.sh and is used from Odoo worktrees.


#ODF Overview — What It Does

ODF is a route-driven harness for delivering Odoo changes:

init → health/preflight → one resolved route → required QA/VERIFY → archived when applicable

The route determines which stages and roles apply; not every request runs every stage. The orchestrator never writes code — it delegates, tracks state, and enforces required evidence and human gates.

#What you can do

Command Purpose
/odf-new <name> Start a new change on its resolved route; planning is proportional to risk/scope
/odf-continue [name] Resume a change from its last completed stage
/odf-status [name] Show change state, artifacts, task progress
/odf-explore <topic> Investigate Odoo patterns before committing to a change
/odf-fix <description> Lightweight 3-step bugfix: diagnose → fix → verify
/odf-agent-new <description> Create custom Odoo sub-agents from natural language
/odf-profile switch Toggle between default (r1 for ASSESS/VERIFY, kimi for others) and cheap (kimi for all)
/odf-registry-refresh Pick up skill/agent changes after install
/odf-tdd on/off Toggle strict test-before-code enforcement
/odf-health Verify installation and project detection
/odf-feedback <change> Preview and optionally submit explicitly confirmed, privacy-bounded feedback

#Pipeline stages

Stage Role Agent Output Gate
DECIDE PROPOSE odoo_proposer Business intent, scope, capabilities, risks for routes that need formal DECIDE Ask only for an unresolved human decision
DECIDE ASSESS odoo_functional_consultant Strategy (standard vs custom) + functional spec when formal DECIDE is routed Continue/adjust only at a required decision
PLAN QA-PLAN (conditional) odoo_qa_engineer Formal test plan, scenarios, coverage targets for routes requiring PLAN or explicit risk escalation Approve/adjust only when this formal plan is required; small changes keep focused QA inline
PLAN DESIGN odoo_backend_engineer / odoo_frontend_engineer Technical design + tasks when formal PLAN is routed Approve/adjust only when the plan is required
BUILD — Agent by task domain Code + focused tests/checks, in batches, when the route includes BUILD Pause only at a required gate or real decision
VERIFY — odoo_qa_engineer Test run, lint, spec compliance when required by the route PASS or FAIL; evidence gate remains mandatory
FIX — Agent by task domain Root-cause analysis + minimal regression for the bugfix route Evidence gate remains mandatory
EXPLORE — odoo_explorer Read-only investigation using local and web sources; ephemeral, not a bound workflow —
ARCHIVED — (auto) Retrospective saved to Engram; only for VERIFY-terminal routes —

These are available stage roles, not a promise that every request runs every row. The user sees one route selected by work_type; triage labels and stage roles are internal mappings. Every code-changing route carries focused QA, while a formal QA-PLAN is conditional on the resolved route or an explicit risk escalation.


#Architecture

                   ┌──────────────────────┐
                   │   odoo_orchestrator   │  ← NEVER writes code, only delegates
                   │   (AGENT)             │
                   └──────┬───────┬───────┘
                          │       │
              ┌───────────┘       └───────────┐
              ▼                               ▼
   ┌──────────────────────┐       ┌──────────────────────┐
    │   odf-delegation.ts  │       │   11 sub-agents       │
   │   (PLUGIN)           │──────▶│   (via task())        │
   │                      │       │                       │
   │   Registry cache     │       │  odoo_backend_engineer │
   │   Profile resolution │       │  odoo_frontend_enginee │
   │   Skill injection    │       │  odoo_qa_engineer      │
   │   Status resolver    │       │  odoo_functional_con.  │
    │   Community tools    │       │  odoo_code_reviewer    │
    │                      │       │  odoo_explorer         │
   └──────────────────────┘       │  odoo_api_integrator   │
                                  │  odoo_dba_devops       │
                                   │  odoo_upgrade_migrator │
                                  └──────────────────────┘

#Plugin tools (odf-delegation.ts)

29 tools injected at runtime into the orchestrator's tool list:

Tool Purpose
odf_delegate Route a stage role + prompt to the right sub-agent with skill injection
odf_delegation_prepare Resolve agent/skills/profile/prompt and mint a bounded delegation token
odf_delegation_launch Digest-check and submit prepared prompts through the V2 session API
odf_delegation_late_seal_prepare Verify an expired native child and issue a bound, single-use late-seal capability
odf_proposal_write Persist the token-bound PROPOSE artifact to its canonical OpenSpec path
odf_delegation_seal Seal a native delegation: verify the child session, run the stage gates, return the standard envelope
odf_parallel_delegate Run a cross-domain BUILD as 2-3 parallel branches with one aggregate join
odf_parallel_prepare Prepare a native parallel BUILD (branch prompts + one token)
odf_parallel_seal Seal a native parallel BUILD: verify the branch sessions, run the aggregate scheduler and commit once
odf_workflow_route Resolve the canonical stage route for a work type
odf_workflow_advance Preview/verify a canonical workflow transition (read-only)
odf_workflow_archive Locked, idempotent terminal ARCHIVE transition through the selected store
odf_workflow_override Audited skip/re-enter/re-plan/settle-stale-attempt for an existing change
odf_workflow_bind Start or bind canonical workflow state in the selected store
odf_entry_triage Classify a change entry (micro/standard/full) and pick the work type
odf_context_manifest Bounded, read-only context manifest for a change candidate
odf_skill_inject Match and inject relevant skill compact rules into a prompt
odf_skill_resolve Preview which skills match a task WITHOUT executing
odf_registry_read Read and cache odf-registry.json with TTL and file watcher
odf_profile_select Preview which model profile applies to a stage role
odf_community_tool_detect Check if a community tool (e.g., CodeGraph) is available
odf_community_tool_install Install and wire a community tool
odf_workflow_status Read canonical workflow status (stages, receipts, resumability)
odf_feedback_submit Preview or submit one explicitly confirmed, privacy-bounded feedback aggregate
odf_policy_gate Resolve + persist the TDD/risk Policy Gate before IMPLEMENT/VERIFY
odf_receipt Persist a failure-disposition receipt for a change
odf_governance_provenance Record OCA AI provenance in .odf/ai-provenance.json
odf_governance_check Read-only OCA governance gate (diff, trailers, provenance)
odf_health Read-only installed/runtime ODF health check

#Skills system

51 skills covering:

  • OCA governance: PR workflow, maturity levels, commit messages, contribution guidelines
  • OCA style: Python, XML, JavaScript/CSS standards
  • Odoo patterns: field types, computed fields, inheritance, constraints, domains, onchange, context/env, security, data migration, API integration, migration guides, debug patterns
  • ODF stage roles: assess, design, implement, bounded batch implementation, verify, fix, TDD, QA, exploration, agent builder, chained PR
  • Shared conventions: Engram persistence, result contract, skill resolver, Odoo source paths
  • ODF onboarding: guided walkthrough of the full pipeline on a real codebase

Max 5 skills per delegation via compact rules; the canonical stage skill also injects its full SKILL.md body.

#Model profiles

Profile ASSESS VERIFY Other stage roles
default current current current
cheap current current current

All stage roles inherit the current session model (no hardcoded model override). Profiles apply ONLY to SDD pipeline stage roles. General queries and non-SDD tasks use the default runtime model.

#Community tools

ODF can install and detect optional tools:

  • CodeGraph (npm install -g @colbymchenry/codegraph): SQLite knowledge graph for structural queries — one round-trip instead of grep + Read loops. Install with --with-codegraph flag or via odf_community_tool_install.

#Persistence

The preflight artifact_store selects the authoritative workflow state and role-artifact store:

  • OpenSpec: openspec/changes/{change}/ state and artifact files.
  • Engram: deterministic odf/{change}/{artifact-type} state/artifact refs.
  • Hybrid: OpenSpec is canonical; matching Engram state/artifacts are mirrored on commits, which must fail if either write fails. Status can recover missing OpenSpec state from the mirror without merging conflicting content.

Runtime Policy Gate, validation evidence, and failure receipts remain in .odf/*.json regardless of the selected artifact store. Legacy dual-read is for migration only; old changes are not rewritten automatically.

#Preflight gate

9 fields required before any stage runs:

  • change (kebab-case name)
  • execution_mode (interactive | batch | auto)
  • artifact_store (engram | openspec | hybrid)
  • delivery_strategy (ask-always | ask-on-risk | auto-chain | single-pr)
  • review_budget_lines (100-5000)
  • odoo_version (16 | 17 | 18 | 19)
  • tdd_mode (true | false)
  • solution_strategy (standard | custom | pending)
  • chain_strategy (none | chained | feature-branch)

Missing fields are collected via question tool.

#Orchestrator safety checks (gentle-ai inspired)

  • Sub-agent launch deduplication: same (stage role, fingerprint) never launched twice
  • Fresh review rule: adversarial review gets a fresh context for independent judgment
  • Incident rule: after state corruption, stop and audit before continuing
  • Long-session rule: after ~20 tool calls or 5 file reads without delegation, delegate instead of accumulating context
  • Apply-progress continuity: continuation batches merge with existing progress, never overwrite
  • Model routing scope: profiles only apply to SDD pipeline stage roles, not general queries

#Development and collaboration practices

These practices apply when changing the ODF harness repository. In customer Odoo projects, follow that project's instructions and the relevant OCA/Odoo skills; do not impose this repository's language or tooling conventions there.

#Communication and scope

  • Answer the user's direct question first. Be concise, concrete, and clear; explain non-trivial designs as problem → example or behavior → solution, including why the solution is needed.
  • State assumptions and uncertainty. Verify details rather than guessing, especially for external APIs, framework behavior, and repository-specific commands.
  • Keep changes focused on the request. Avoid unrelated cleanup, speculative abstractions, compatibility layers, or dependency upgrades. Understand apparently intentional behavior before proposing its removal; ask before making a consequential removal outside the requested scope.

#Programming practices

  • Follow nearby code, tests, and the repository's authoritative documentation. Prefer the smallest readable change that preserves existing module boundaries and sources of truth.
  • Keep the main path easy to follow. Use helpers when they name a meaningful concept, isolate non-trivial logic, or are reused; avoid extracting trivial one-use expressions without a readability benefit.
  • Prefer explicit domain types and validation at trust boundaries. Avoid any, unchecked casts, and weakening validation to make a change pass; use the narrowest type or a runtime guard that fits the codebase.
  • Handle errors at the boundary that can make a useful decision. Do not silently swallow failures. Comments should explain non-obvious constraints, invariants, or surprising behavior—not restate the code.
  • Before editing generated or derived files, identify their authoritative source and generation process. Update the source and use the documented generator where applicable; do not hand-edit generated output by default.
  • Avoid new runtime dependencies unless they are justified. Treat dependency manifests and lockfiles as one change; review the resulting dependency diff and consult authoritative release notes when an upgrade may change behavior.

#Tests and verification

  • Test observable behavior through the real implementation where practical. Avoid duplicating production logic in tests; use mocks only at external, nondeterministic, or otherwise difficult-to-control boundaries.
  • Add or update focused regression coverage for bug fixes and behavior changes. For routing, state, authorization, or evidence-handling changes, cover relevant invalid, duplicate/retry, stale, and failure cases as well as the happy path.
  • Run the focused tests and documented checks relevant to the change. If a test file changes, run that test; do not trigger networked, paid, production, or destructive test paths without explicit authorization.
  • Report exactly what was run and its result. Never describe an unrun check as passing; call out remaining validation clearly.

#Repository and workflow safety

  • Inspect git status and the relevant diff before editing or operating on Git state. Preserve changes made by the user or other agents; work only on files in scope.
  • Stage explicit paths. Never use broad or destructive cleanup/rollback commands such as git reset --hard, git checkout --, git clean, git stash, git add -A, or git add .. Never force-push, and commit only when the user explicitly asks.
  • These practices do not replace ODF's route, Policy Gate, required seals, evidence, or human approvals. Never bypass a mandatory workflow gate or treat explanatory prose as machine-validated evidence.
  • For OCA governance, Odoo coding standards, issues, and PR workflows, use the relevant registered skills and repository guidance rather than copying project-specific rules into this section.

#Branch, PR, and merge workflow

main is protected. Every change reaches it through a pull request, never a direct push — including one-line fixes.

# 1. Sync and branch
git fetch origin
git switch main
git merge --ff-only origin/main
git switch -c <type>/<short-description>

# 2. Implement, then verify
npm run typecheck
npm run test:unit
npm run test:yaml
npm run validate:skills
node scripts/odf-registry-validate.js

# 3. Stage explicit paths only
git add path/one path/two
git commit -m "type(scope): summary"

# 4. Push and open the PR
git push -u origin <type>/<short-description>
gh pr create --base main --head <type>/<short-description> \
  --title "type(scope): summary" --body-file <body.md>
  • CI (.github/workflows/ci.yml) runs typecheck, unit tests, YAML scenarios, registry validation, skill validation, and a diff check.
  • The auto-merge job squash-merges same-repository, non-draft PRs once the test job passes. Opening the PR is enough: do not merge manually and do not force-push the branch.
  • Keep the PR body problem-first: why, what, verification (commands and observed results), and risk.
  • After merge, sync and clean up:
git switch main
git fetch origin
git merge --ff-only origin/main
git branch -d <type>/<short-description>
  • If CI fails, fix on the same branch and push again; do not open a second PR. Never push directly to main, never force-push, and never use git add -A or git add ..

#Key structure

agent/              — 12 agent instructions (orchestrator + 11 sub-agents)
command/            — 23 slash command definitions (Markdown)
plugins/            — odf-delegation.ts (OpenCode plugin)
scripts/            — test runner (1477 Vitest tests + 331 YAML scenarios), CLI wrapper, registry and skill validators
skills/              — 51 skills, one directory per skill (`skills/<name>/SKILL.md`)
  _shared/          — shared conventions (result contract, persistence, Odoo sources)
openspec/           — SDD change artifacts (when artifact_store=openspec)
docs/               — intended-usage, architecture, skill-style-guide
install.sh          — idempotent installer (backup, --dry-run, --force)
odf-registry.json   — SINGLE SOURCE OF TRUTH (51 skills, 12 agents, 2 profiles, community tools)

#Quick start

# From an Odoo worktree:
curl -fsSL https://raw.githubusercontent.com/antoniodavid/odf-agent-team/main/install.sh | bash
# Or with CodeGraph:
curl -fsSL https://raw.githubusercontent.com/antoniodavid/odf-agent-team/main/install.sh | bash -s -- --with-codegraph

# Then inside OpenCode:
/odf-init           # Detect project context
/odf-new my-feature # Start first change

#ODF vs SDD

ODF is a superset of the generic SDD workflow:

Aspect SDD (gentle-ai) ODF
Phases propose → spec → design → tasks → apply → verify propose → assess → qa-plan → design → implement → verify
Domain Generic Odoo-specific
Sub-agents 7 generic agents 10 specialized Odoo agents (backend, frontend, QA, DBA, etc.)
Skills Code style, commit conventions OCA governance, Odoo patterns, migration guides
Profile system No Yes (default/cheap profiles per stage role)
Community tools CodeGraph CodeGraph + extensible via plugin tools
Persistence Engram default Selected openspec, engram, or hybrid mode

#Tests

npm test              # 1477 Vitest tests + 331 YAML scenarios
npm run test:yaml     # YAML scenario runner only
npm run test:unit     # Vitest only
npm run typecheck     # tsc --noEmit
npm run validate:skills                # Agent Skills + compact-rule validation
npm run docs:build                     # regenerate docs/*.html + search index
npm run docs:check                     # fail if generated docs are stale
node scripts/odf-registry-validate.js   # validates all registered paths exist

Registry selection: the test runner honors an absolute ODF_CONFIG_DIR, otherwise scripts/lib/config-dir.js derives the registry from the pack the module ships in, then XDG_CONFIG_HOME/opencode, then HOME/.config/opencode. Set ODF_CONFIG_DIR=/path/to/repo to validate against the repo copy.

#Registry lifecycle

  1. Update skills/agents/commands in this repo
  2. Run node scripts/odf-registry-validate.js (with ODF_CONFIG_DIR set to repo root) to catch broken paths
  3. Publish → install into ~/.config/opencode/ → run /odf-registry-refresh from inside an Odoo project

#Gotchas

  • openspec/config.yaml has testing.strict_tdd: false — correct; this repo uses YAML scenarios + Vitest, not a traditional coverage suite
  • scripts/odf-cli.js is a minimal parser that emits orchestrator routing envelopes, NOT the orchestrator itself
  • Plugin tools are injected at runtime into the model's tool list — they are NOT MCP tools
  • docs/*.html (except the diagrams and index.html) are generated from Markdown by npm run docs:build; edit the .md source, never the generated page, and commit both
  • After modifying an agent or skill file, run /odf-registry-refresh from inside an Odoo project to pick up changes