# Agent Team Architecture — Adaptive, Evidence-Driven Upgrade (v2) This document describes the architecture of `dev_agent_team` after the second architectural upgrade: making the existing 14-agent team **adaptive, evidence-driven, repository-aware, cost-aware, and capable of long-horizon work**. It extends — it does not replace — the Repository Intelligence Bootstrap architecture documented in [REPOSITORY_INTELLIGENCE.md](REPOSITORY_INTELLIGENCE.md). > Summary of the change: the system moved from > `"Choose an agent and ask it to do work"` > to > `"Understand the task → estimate complexity → gather the minimum necessary > evidence → choose the best next action → execute → verify → re-plan → learn"`. ## 1. Architecture changes at a glance | Area | Before | After | |------|--------|-------| | Orchestrator behavior | linear `REQUEST → … → REPORT` flow | adaptive `RECALL → UNDERSTAND → ESTIMATE → LOAD CONTEXT → CHOOSE ACTION → EXECUTE → VERIFY → RE-PLAN/STOP → LEARN → STORE` decision loop | | Task sizing | implicit | explicit lightweight complexity estimation (`ESTIMATE → EXECUTE → EXPAND`) | | Action selection | implicit routing by task type | explicit **Action Catalog** (27 actions with purpose/cost/risk/prereq/failure modes); direct tool calls preferred over agent dispatch when cheaper | | Handoffs | prose contract | structured **evidence-state record** (9 fields) for meaningful decisions/investigations/failures/handoffs | | Planning | replan on handoff | **adaptive planning** with failure classification (7 types) and no blind retries | | Verification | verification gate | verification gate + **process quality** detection (lucky-pass, symptom-fixing, etc.) and lightweight **quality gates** | | Cost | — | lightweight cost/token awareness driving routing decisions | | Completion | completion rule | **explicit stop conditions** (goal satisfied + verified, acceptable uncertainty, no useful action, blocked) | | Subagents | role boundaries + handoff formats | role-adapted **Evidence & Handoffs** sections; each agent knows its evidence product, knowledge ownership, stop, and escalation points | | Repository knowledge | bootstrap + skills | unchanged structure + **knowledge lifecycle** rules (discover → classify → identify owner → update only the relevant doc → preserve valid content) | | Agent roster | 13 agents | **now exactly 14 agents** (1 orchestrator primary + 13 subagents); one new role (`breakdowner`) added | | Project memory | — | **deterministic cross-session memory** in `memory/` (decisions, lessons, failures, architecture, sessions) with lifecycle script | | Skills | — | **12 reusable specialized methodologies** in `skills/` loaded by agents when needed | | Improvements | — | **proposal-based improvement system** in `improvements/` requiring human approval | ## 2. Orchestrator decision loop The Orchestrator is a decision engine. Its core loop: ```text UNDERSTAND → ESTIMATE → LOAD CONTEXT → CHOOSE ACTION → EXECUTE → VERIFY → RE-PLAN (or STOP) → LEARN ``` At every iteration it: 1. **Understands** the objective (goal vs investigation vs implementation vs architecture). 2. **Estimates** complexity (scope, likely files, dependency depth, architecture impact, uncertainty, testability, risk, expected actions). 3. **Loads context** — `.opencode/` repository intelligence, refreshed when stale. 4. **Chooses the next action** from the Action Catalog (cheapest reliable action that yields the evidence needed for the NEXT decision). 5. **Executes** — a direct tool call (inspect/search/git/tests) or a specialist dispatch. 6. **Observes + verifies** — evidence over claims; independent verification drives the next decision. 7. **Re-plans** when evidence changes, or **stops** when the stop conditions hold; then updates durable knowledge. Optimization target: **verified progress, minimum sufficient work, correct tool/agent selection, low unnecessary context usage, recoverability, evidence quality, repository consistency** — not maximum agents or maximum reasoning. ## 3. Task complexity estimation A few bullets before committing to a workflow: ```text scope: small | medium | large likely files: dependency depth: shallow | moderate | deep architecture impact: none | local | cross-cutting uncertainty: low | medium | high testability: high | medium | low risk: low | medium | high expected actions: ``` Guiding principle: **`ESTIMATE → EXECUTE → EXPAND`**. Start with the smallest reliable investigation; expand only when evidence says so; shrink when the task is simpler than expected; record why scope expanded; never reread what is already understood. - Trivial → self-serve, no dispatched agents. - Medium → one or two specialists, small verification. - Complex → full context bootstrap, evidence-first investigation, architecture if needed, staged implementation, independent verification, review. ## 4. Action catalog (tool cards) The Orchestrator selects actions from a catalogue of 24 entries. Each entry has: ```text name, purpose, inputs, outputs, read_only, cost, risk, prerequisites, failure_modes ``` Groups: **inspect** (repository, search, git history, dependencies, build system, tests, configuration), **experiment/verify** (run experiment, run verification), **dispatch** (Explorer, Detective, Architect, Designer, Builder, Tester, Reviewer, Workflow Architect, Philosopher, Maintainer, Toolsmith, Writer), **update** (repository knowledge), **terminate** (finish/report, re-plan). Selection rules: prefer the cheapest action yielding the required next-decision evidence; prefer direct inspection over agent dispatch for simple lookups; dispatch agents only for specialist reasoning/evidence/implementation; on failure choose a different action; never run Builder without approved scope, Reviewer without an implementation, or Philosopher after purpose is clear. ## 5. Evidence / state model Meaningful decisions, investigations, failures, and handoffs use the structured state record: ```text goal hypothesis evidence actions_taken result verification confidence remaining_unknowns recommended_next_action ``` Trivial steps use brief prose. The Orchestrator reasons from evidence, not conversational claims; it never accepts "it works" as "evidence shows it works". ### State separation (context management) ```text repository knowledge → .opencode/ skills + AGENTS.md (durable, role-owned) project memory → memory/ decisions, lessons, failures, architecture, sessions (cross-session) task state → AgentsReport// reports (current task only) agent handoff state → the state records passed between agents scratch → /tmp/opencode or in-memory (throwaway) ``` Long-running tasks persist the current state record in the task report so work survives context compaction and can be resumed with identical facts. ## 6. Verification model - Implementation and verification are separate: Builder produces changes; Tester/Reviewer produce independent verification. - Verification uses real evidence: tests, build results, static analysis, runtime behavior, logs, reproducible commands, artifacts, measurements. - Agents do not give themselves full credit for unverified claims. - The Verification Gate requires: objective satisfied, specialists completed, no scope expansion, coherent handoffs, targeted verification passed, project validation performed, no hidden blocker, explicit remaining risks. ### Process quality The outcome alone is not the trajectory. Detected anti-patterns: blind retries, repeated identical actions, unnecessary file reading, implementation before understanding, testing too late, skipping verification, fixing symptoms without evidence, solving only the visible test case, repeatedly calling agents without new information, continuing after sufficient verification. A lucky pass is a finding (Reviewer), not acceptance. ### Quality gates ```text UNDERSTANDING → PLAN → IMPLEMENT → VERIFY → REVIEW → COMPLETE ``` Each transition requires appropriate evidence; gates are skipped for trivial tasks, mandatory for complex ones. ## 7. Handoff model Compact handoffs carry only what the next agent needs: objective, known facts, evidence, files/components, changes made, failed attempts, verification state, open questions, recommended next action. No whole transcripts. Persistent where long-running tasks require it. ## 8. Failure recovery Every significant failure is classified before the next action: | Type | Response | |------|----------| | tool | switch tool/invocation, verify prerequisites | | environment | fix environment or surface BLOCKED | | assumption | record evidence, form new hypothesis | | plan | revise plan from evidence | | implementation | Detective if cause unknown, else Builder fix | | test | Tester corrects the test/strategy | | coordination | re-route or repair handoff | Rules: one immediate retry per failed Task, then classify and choose differently; surface repeated-failure loops instead of looping silently; a failed hypothesis produces a new plan. ## 9. Stop conditions The Orchestrator stops when: goal satisfied AND required verification passed; remaining uncertainty is acceptable (documented); no useful next action remains; or the workflow is genuinely BLOCKED. It does not call agents merely because they are available. ## 10. Cost and token awareness Lightweight execution-cost model driving routing: approximate tool calls, agent dispatches, expensive/repeated ops, unnecessary investigation, context growth. No billing system. Rules: cheapest action that yields the needed evidence; fewer better-scoped agents; equal evidence → cheaper action; context growing faster than progress → stop investigating and re-plan. ## 11. Repository intelligence and knowledge lifecycle `.opencode/` remains the repository-local source of agent context (skills + AGENTS.md + `.bootstrap-meta`). No separate `knowledge/` or `state/` trees were added: the skills already play the role of `architecture.md`/`build.md`/ `conventions.md`, and `AgentsReport/` already separates task state from repo knowledge. Lifecycle: when new durable facts are discovered → decide whether they belong in repository knowledge → identify the owner (Explorer for repo-context, Architect for architecture, Builder/Tester for build-and-test, Maintainer for conventions, Orchestrator for AGENTS.md) → update only that document → preserve valid existing information → never record temporary task details. Stale content is detected by bootstrap fingerprints and corrected by the owning agent. ## 12. Project memory (cross-session persistence) Project memory provides deterministic, inspectable, version-controlled persistence across sessions. It lives in `memory/` at the repository root: ```text memory/ ├── MEMORY.md # index with lifecycle rules ├── decisions/ # architectural/technical choices (evidence-backed) ├── lessons/ # reusable knowledge (proven patterns) ├── failures/ # root causes + prevention (incident records) ├── architecture/ # system structure documentation └── sessions/ # work-in-progress state (session continuity) ``` **Lifecycle script**: `scripts/memory-lifecycle.sh` provides deterministic operations: `recall`, `store`, `list`, `search`, `sessions`, `cleanup`. **Integration**: The Orchestrator recalls relevant memory before task classification and stores durable findings after substantial work. All 12 subagents check memory before investigating/implementing and store lessons after completing their work. **Rules**: Store selectively (not every tool call); entries must be evidence-backed; preserve existing memory; never store task-specific noise as durable knowledge. ## 13. Skills system (reusable methodologies) Skills are reusable, specialized capabilities that agents load when needed. They live in `skills/` at the repository root: ```text skills/ ├── tdd/SKILL.md # Test-Driven Development ├── systematic-debugging/SKILL.md # debugging methodology ├── architecture-design/SKILL.md # architecture decisions ├── code-review/SKILL.md # code review process ├── security-review/SKILL.md # security review ├── repository-analysis/SKILL.md # repo exploration ├── failure-analysis/SKILL.md # failure investigation ├── refactoring/SKILL.md # safe code restructuring ├── test-analysis/SKILL.md # test quality assessment ├── incident-investigation/SKILL.md # production incidents ├── browser-automation/SKILL.md # web interaction patterns └── research/SKILL.md # information gathering ``` **Loading**: When the Orchestrator dispatches a specialist, the brief includes the relevant skill path. The agent reads the skill before starting work. **Ownership**: Skills are owned by their primary agent (e.g., `tdd` by Builder, `systematic-debugging` by Detective). The Orchestrator is the index owner. **Extension**: To add a skill, create `skills//SKILL.md` with frontmatter (name, description, version, owner) and sections (When to use, Core methodology, Step-by-step procedure). Update `skills/SKILLS.md` index. ## 14. Improvement proposals The improvement proposal system provides a structured way to evolve agent behavior, skills, and processes. Proposals live in `improvements/`: ```text improvements/ ├── README.md # proposal format and lifecycle ├── pending/ # proposals awaiting human approval ├── applied/ # approved and implemented proposals └── rejected/ # proposals that were not approved ``` **Rules**: Do NOT modify core agent behavior without human approval. Create proposals in `improvements/pending/`. Present proposals at natural stopping points. Include: observed problem, evidence, root cause, proposed change, risks, verification plan. **Detection triggers** (evidence-driven, not per-task): a proposal is warranted when a failure recurs, a needed skill is missing, routing was inefficient, a documentation gap forced re-derivation, a multi-step process would recur, or a genuinely reusable pattern emerged. Proposals are decisions, not actions — writing one does not implement it; human approval is required for changes that touch core agent behavior, agent prompts, the orchestrator's decision logic, or the agent roster. ### Task lifecycle (full loop) A coherent task runs through these stages; trivial tasks collapse them, complex tasks engage every stage with evidence feeding the next: ```text 1. RECALL — search memory (sessions, decisions, lessons, failures) 2. UNDERSTAND — separate goal from investigation/implementation/architecture 3. ESTIMATE — lightweight complexity (scope, files, impact, uncertainty, risk) 4. LOAD — read .opencode/ repo intelligence (refresh if stale); read skills 5. PLAN — decompose into work items; pick agents; set dependencies 6. DISPATCH — brief each agent (objective, scope, patterns, skill paths, report) 7. VERIFY — check artifacts on disk; confirm evidence; re-plan on mismatch 8. LEARN — classify outcomes: decision / lesson / failure / session 9. STORE — persist durable findings to memory/ via memory-lifecycle.sh 10. IMPROVE — detect improvement proposals; write to improvements/pending/ 11. REPORT — final report mapping result to original objective ``` Memory touch is selective: trivial/ephemeral work is not stored; one-off but meaningful work stores a lesson/decision if durable; recurring patterns store a failure record AND consider a proposal; architectural work stores a decision; long-horizon work maintains a session record. Agent selection is not a fixed pipeline: memory is recalled first, relevant skills are loaded into dispatch briefs, and **skip-when** guards avoid dispatching agents whose reasoning is not required for the next decision. ## 15. Agent ownership of knowledge and evidence | Agent | Knowledge owned | Primary evidence product | Stop when | |-------|-----------------|--------------------------|-----------| | Explorer | repo-context | system map with file:line, certainty levels | findings complete + verified | | Detective | — (consumer) | hypothesis/evidence/confidence, eliminated alternatives | root cause established | | Architect | architecture | decision record (options, trade-offs, scope) `[DECIDED/PROVISIONAL/BLOCKED]` | decision ready | | Builder | build-and-test (with Tester) | files changed + targeted verification actually run | brief end reached | | Breakdowner | .tasks/ structure (per-goal) | valid Task Breakdown + flag.json planning state | invariant holds + handoff ready | | Tester | build-and-test (with Builder) | tests run, pass/fail, coverage gaps | tests ready/provisional | | Designer | — (consumer) | design spec tied to user needs/constraints | design ready | | Reviewer | validation of all skills | verdict + findings with severity/certainty, lucky-pass detection | ACCEPT/CHANGES_REQUIRED/BLOCKED | | Maintainer | conventions (+ audit all) | drift finding + minimal correction + validation | standard restored | | Toolsmith | — (consumer; conventions via Maintainer) | recurrence record + proof safeguard fires | safeguard verified | | Philosopher | — (may add purpose to repo-context) | recorded user voice + reasoning | philosophy ready | | Workflow Architect | — (consumer) | model + justification + resolved ambiguities | model complete + valid | | Writer | — (consumer) | docs mapped to source reports/files | docs ready | Every agent additionally has a role-adapted **Evidence & Handoffs** section with the 9-field state record, explicit evidence product, stop condition, and escalation point. ## 16. Parallelism Parallel only when genuinely independent (no unresolved dependency, no shared state conflicts, independently interpretable results), and only after considering coordination cost. Good: three independent Explorer investigations (architecture, tests, dependencies). Bad: three agents investigating the same files or proposing identical fixes. ## 17. Evaluation Structural readiness is verified by `scripts/test-agent-architecture.sh` (currently 17 checks). Runtime behavior is evaluated through the 12 scenarios in [EVALUATION_SCENARIOS.md](EVALUATION_SCENARIOS.md), scored on success, unnecessary work, repeated actions, verification quality, correct agent selection, cost/context growth, and recovery quality — not just pass/fail. ## 18. Example execution trace — simple task ```text User: "Fix the typo in README.md line 12." 1. UNDERSTAND — trivial, one file, no risk, known. 2. ESTIMATE — scope small; files 1; risk low; actions ≈ 2. 3. LOAD CONTEXT — .opencode fresh; README conventions known. 4. CHOOSE ACTION — A1 inspect repository? No — A2 search code (read README line 12) directly. 5. EXECUTE — self: read README.md, edit the typo. 6. VERIFY — self: re-read the line, confirm correction. 7. STOP — goal satisfied + verified; report. Agents dispatched: 0. Cost: ~4 tool calls. ``` ## 19. Example execution trace — complex task ```text User: "Add a build cache to the pipeline and verify it improves CI time." 1. UNDERSTAND — implementation + measurement; architecture impact possible. 2. ESTIMATE — scope large; files 5–10; impact cross-cutting; uncertainty high; actions ≈ 20+. 3. LOAD CONTEXT — .opencode checkpointed/refreshed; build skill read. 4. INVESTIGATE — dispatch Explorer (build + CI layout) — one scoped pass. 5. EVIDENCE — Explorer returns system map, build commands, cache surfaces. 6. ARCHITECTURE — dispatch Architect: boundary of the cache (which builds share it, invalidation rule). 7. PLAN → IMPLEMENT — dispatch Builder with approved scope + patterns. 8. VERIFY — dispatch Tester: cache correctness + baseline comparison; run before/after CI steps. 9. REVIEW — dispatch Reviewer: scope compliance, lucky-pass check (did tests actually exercise the cache?). 10. LEARN — update .opencode build-and-test with the cache command/invalidation rule. 11. STOP — measured improvement + review accepted; report with evidence. Agents dispatched: 4 (Explorer, Architect, Builder+Tester, Reviewer). Cost: higher, but each dispatch produced decision value. ``` ## 20. Remaining weaknesses - The action catalog and cost model are textual guidance, not enforced tooling; faithful use depends on the orchestrator model following instructions. - Runtime evaluation scenarios require a live opencode session; they are documented, not automated end-to-end. - Staleness of `.opencode/` is detected by bootstrap fingerprints (manifests + layout), not by semantic drift of manually enriched content; manual facts are protected and may still become stale until an owner corrects them. - The 9-field state record is a contract, not a schema validator; adherence is enforced by reviewer attention, not mechanically. - Knowledge ownership depends on role discipline; an agent that enriches the wrong skill would only be caught by review. - Project memory is selective — not every finding is stored; agents must exercise judgment about what constitutes durable knowledge. - Memory retrieval is keyword-based, not semantic; relevant entries may be missed if keywords don't match. - Improvement proposals require human approval, which may slow rapid iteration on agent behavior. ## 21. Task Breakdown (14th agent: breakdowner) `breakdowner` is the 14th agent (approved 2026-09-12, Architect Decision): a planning-only subagent that re-writes LARGE goal prompts into a numbered, state-tracked **Task Breakdown** under `.tasks//` so big goals execute from small, self-contained task files instead of re-feeding the giant prompt into every context. It produces the implementation plan only — never the implementation, the verification, or the workflow model. ### Location and lifecycle - Every breakdown lives at `/.tasks//`, where `` is a short kebab-case slug (e.g. `add-build-cache`). - `.tasks/` is **project-local, local-only, and gitignored — never committed and never installed**. It is not copied by `scripts/install.sh`, is not part of the runtime tree (`${OPENCODE_DEV_AGENT_TEAM}/...`), and must never be referenced as a shipped artifact in docs. - A breakdown is created ONCE per goal and updated only on re-planning: `analyze → break-down → create → verify deps → implement`, with per-task state `pending → in-progress → done` (verify before `done`), next-task selection from `depends-on`, and a living plan whose history is never deleted (append new task numbers, never renumber; removed tasks leave noted gaps). ### Artifact ownership | Artifact | Question answered | Owner | Location | |---|---|---|---| | Task Breakdown | "what tasks must be executed, in what order, in what state" (implementation-plan tree: README.md, 00-overview.md, NN-*.md, flag.json) | **Breakdowner** | `.tasks//` | | Workflow model | "what states/transitions does the resulting system have" (domain behavior spec) | **Workflow Architect** | `AgentsReport/workflow-architect/_.md` | - Workflow Architect READS the breakdown as input context and writes its model only in its own report dir; it writes nothing into `.tasks/`. Breakdowner never models behavior (no FSM/DAG/statechart). - Orchestrator may perform only the two mechanical `flag.json` execution flips (set a task `in-progress` at dispatch; set it `done` only with verified-completion evidence). Every other `.tasks/` mutation is re-planning and must return to Breakdowner. ### Trigger summary Dispatch `breakdowner` for large goals when ANY holds (measured before work dispatch): ≥ 3 likely files or medium/large scope; moderate/deep dependency depth; ≥ 3 specialist roles, or ≥ 2 specialists plus an integration step; goal context > ~800 tokens or > 5 artifacts/reports referenced simultaneously; long-horizon multi-session work with a state-tracked handoff chain. Never dispatch for goals that are single-file, fit one compact brief, need ≤ 2 specialists with no integration, and are low risk. ### Validation Every tree must satisfy the 6-point **validation invariant** before `breakdowner` claims done: `README.md`, `00-overview.md`, `flag.json` exist; `flag.json` parses with exactly the keys `goal`, `status`, `tasks`; every value is `pending|in-progress|done` and `goal` matches the slug; the `tasks` keys equal the set of zero-padded numbered files `NN-*.md` on disk; `00-overview.md` lists every numbered task; numbers are zero-padded ascending with no non-removal gaps. Full convention and spec summary: [Task Breakdown Agent (breakdowner)](TASK_BREAKDOWN_AGENT.md).