ODF Agent Team — AGENTS.md
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-codegraphflag or viaodf_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 statusand 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, orgit 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-mergejob squash-merges same-repository, non-draft PRs once thetestjob 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 usegit add -Aorgit 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
- Update skills/agents/commands in this repo
- Run
node scripts/odf-registry-validate.js(withODF_CONFIG_DIRset to repo root) to catch broken paths - Publish → install into
~/.config/opencode/→ run/odf-registry-refreshfrom inside an Odoo project
#Gotchas
openspec/config.yamlhastesting.strict_tdd: false— correct; this repo uses YAML scenarios + Vitest, not a traditional coverage suitescripts/odf-cli.jsis 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 andindex.html) are generated from Markdown bynpm run docs:build; edit the.mdsource, never the generated page, and commit both- After modifying an agent or skill file, run
/odf-registry-refreshfrom inside an Odoo project to pick up changes