ADR-002: Agent decomposition — vertical implementers × horizontal specialists

Accepted2026-06-01

Context

The platform was building its expert-agent roster from agents-developer-kit — a generic, outdated template kit (TypeORM, password-reset examples) that Aviad asked us to disregard. The first Wave 2 agent (backend-developer, PR #48) was authored from it and came out wrong-grained (a monolith that swallowed security, observability, async, notifications, BFF, API-first) and wrong-sourced (it ignored cursor-rules and the real codebase).

We needed to define, once, how agents are decomposed — at what granularity, by what principle — so the platform's brain always speaks on the same basis. The trigger question: do we keep a few broad implementer agents, or many fine-grained specialists, and how do we avoid either a bloated generalist or a context-budget blowout from loading too many agents per task?

A scan of the real bewith-dev GitHub org (≈60 repos) showed the landscape is far richer than the 16-agent roster assumed: production AI/LLM + vector search (OpenSearch + Voyage + Bedrock/Anthropic/OpenAI), Stripe + Payme payments, a 9-queue multi-channel notification hub, EKS-primary infra, Flutter mobile (no BFF), Angular-8 alongside the React/Next frontends, vendor-neutral observability (Datadog being dropped).

Decision

Decompose agents on two axes plus an orthogonal group, and split a concern into its own agent only by an explicit rule:

• Vertical implementers — bound to a surface/runtime (NestJS, React/Next, Flutter, Angular, Yii2, design-system, infra). They implement.
• Horizontal specialists — cross-cutting expertise (auth, database, payments, notifications, async-messaging, observability, i18n, privacy, AI/LLM, search/vector, contracts, integrations, QA). Any vertical calls them.
• Orthogonal gate/design/product agents — architect, code-reviewer, process-guardian, prd-writer, gatekeeper, product-manager.

Split rule: a concern becomes its own agent only when it has a distinct body of knowledge (a different human specialist would own it) and is cross-cutting or independently triggered. Otherwise it is a rule inside an agent or a skill.

Granularity is intentionally fine, and that is safe because agent loading is lazy and policy-driven (/continue step 4→5 via agent-guard): a task loads only the agents its files trigger, so we never pay for granularity we do not use.

The full roster, sourcing hierarchy, and build sequence live in docs/methodology/agent-taxonomy.md. This ADR records the decision; that doc is the reference.

Decisions taken on the open questions

• Database: one agent, not split — Mongo + Aurora/MySQL + Redis + migrations under one DBA persona, because cross-store consistency is itself the expertise.
• Flutter, Angular-8, Yii2: separate agents each — different bodies of knowledge, and not every task loads all of them.
• AI/LLM + vector-search: real but a small share — defined now, built by impact×criticality (Wave D), still within the 24–48h push.
• Frontend: split by framework/runtime expertise, not per-repo (frontend-developer for the React/Next family, frontend-angular separate, embedded-widgets a candidate).

Rationale

Factor	Monolithic implementers	Per-repo agents	Vertical × horizontal (chosen)
Relevant expertise	Low (generalist)	High but duplicated	High, non-duplicated
Context economy	Loads unused breadth	Many near-identical agents	Lazy-loaded; pay per use
Cross-cutting reuse	Duplicated per implementer	Duplicated per repo	Owned once, called by all
Maintenance	One giant file	N repos × M concerns	One owner per boundary

The Team Topologies framing (stream-aligned verticals + enabling-team horizontals) and DDD bounded contexts give the split a named, proven basis.

Consequences

Positive:

• The brain speaks on one basis; new agents are checked against the roster + split rule (enforced via new-artifact).
• Each agent stays focused; cross-cutting concerns are owned once.
• Fine granularity without context bloat, thanks to lazy policy-driven loading.

Negative / costs:

• More agents to author (~26) — mitigated by the impact-ordered build sequence and the shared 7-section template.
• The already-shipped architect/code-reviewer/process-guardian were partly sourced from agents-developer-kit; they need a later grounding pass against cursor-rules + the real codebase.
• backend-developer PR #48 was closed; it will be rebuilt under this taxonomy.

Alternatives considered

• Keep the agents-developer-kit roster — rejected: not our stack, Aviad asked to drop it, wrong granularity.
• A few broad implementer agents — rejected: a generalist lacks deep expertise and loads irrelevant breadth.
• One agent per repo — rejected: ≈60 repos, massive duplication of the same cross-cutting concerns.
• Treat cursor-rules as ground truth — rejected: it is a non-binding reference to mine for good rules, not to copy.