ADR-007 — Agent Architecture
ADR-007 — Agent Architecture
Sección titulada «ADR-007 — Agent Architecture»Accepted
Context
Sección titulada «Context»Coveris is built with AI assistance at every layer: specification ([[PRD]], ADRs), compliance verification, backlog management, and code generation. A single monolithic agent that handles everything mixes responsibilities, consumes unnecessary context, and produces inconsistent quality across tasks that vary widely in complexity.
The project needs: (1) specialized agents with distinct roles and appropriate model tiers, (2) persistent memory across conversations, (3) a clear escalation path from lightweight checks to authoritative verification, and (4) reusable skills that encode domain-specific patterns for any agent — human or AI — working on the codebase.
Decision
Sección titulada «Decision»A specialized agent architecture is adopted, anchored in .claude/ within the repository. Components are organized into four categories: project agents, context servers, personas, and invocable skills.
Taxonomy. Each category has a fixed location, purpose, and invocation method:
| Category | Location | Purpose | Invocation |
|---|---|---|---|
| Project agents | .claude/agents/*.md | Autonomous agents with defined roles and write permissions | Auto-dispatched by Claude Code based on context |
| Context servers | .claude/agents/*.md | Singleton read-only agents that pre-load documents into context | Auto-dispatched; persist across queries in a conversation |
| Personas | .claude/agents/personas/*.md | Role-play agents for BDD story enactment | Invoked explicitly for scenario testing |
| Skills | .claude/skills/*/SKILL.md | Domain-specific instructions loaded on demand | Invoked with /skill-name from the chat |
Model tier policy. The model assigned to each agent is a cost/benefit decision:
| Tier | Model | Use case |
|---|---|---|
| Authority | Opus | Final arbiter, orchestration, complex reasoning |
| Editor | Sonnet | Spec editing, code generation, backlog fixing |
| Sentinel | Haiku | High-frequency checks, context caching, persona enactment |
Project agents. Five agents cover the full authoring and verification lifecycle:
| Agent | Model | Role | Writes | Memory |
|---|---|---|---|---|
coveris-adr-editor | Sonnet | Creates and maintains ADRs in docs/adr/ | Yes | Yes |
coveris-prd-editor | Sonnet | Edits /PRD.md exclusively | Yes | Yes |
prd-adr-expert | Opus | SSOT authority — verifies code vs spec, never edits | No | Yes |
prd-inspector | Haiku | Lightweight sentinel — fires on business logic changes | No | No |
kdx-notion-issue-fixer | Sonnet | Backlog worker — receives one issue, implements fix in worktree | Yes | Yes |
Context servers. Singleton agents that pre-load large document sets into context at startup and answer queries with exact quotes, line numbers, and cross-references. They do not write files. Their value is amortized context: load once, query many times within a conversation. Send RESET to force a re-read after editing the underlying documents.
| Server | Model | Pre-loads | Does NOT handle |
|---|---|---|---|
adr-context-server | Haiku | All ADR files in docs/adr/ | PRD, API, code |
prd-context-server | Haiku | PRD.md, API.md, docs/stack/api-conventions.md | ADRs, code |
Personas. Five Haiku agents representing fictional users of Clinica Bienestar, used for BDD story enactment and scenario validation. Each persona has a defined role (ADMIN, MANAGER, SUPERVISOR) and acts in first person.
| Persona | Role | Use case |
|---|---|---|
| Valentina Rodriguez | ADMIN (Directora) | Owner-level decisions, full access scenarios |
| Matias Fernandez | MANAGER (Jefe RRHH) | HR management, employee lifecycle |
| Renato Molina | MANAGER (Jefe Operaciones) | Scheduling, capacity planning |
| Gonzalo Navarro | SUPERVISOR (Admin RRHH) | Day-to-day HR operations, audit review |
| Sofia Alvarez | SUPERVISOR (Admin RRHH) | Administrative tasks, data entry |
Invocable skills. Skills are domain-specific instruction sets, not autonomous agents. They are loaded into the current conversation when invoked and provide patterns, constraints, and generation rules. They are grouped by concern:
Frontend patterns — Angular 21 component, signal, form, HTTP, and routing conventions:
kdx-angular-component, kdx-angular-signals, kdx-angular-forms, kdx-angular-http, kdx-angular-routing
Design system — PrimeNG component mapping, Tailwind extensions, and design system modifications:
kdx-design-system-use, kdx-tailwind-design-system, kdx-design-system-modification
Audit and validation — Read-only verification against spec:
kdx-adr-format, kdx-audit-prd, kdx-api-ssot-checker, kdx-backlog-sync
Release and operations — Version tagging and dev server management:
kdx-version, operate-dev-server (with platform delegates operate-dev-server-linux, operate-dev-server-win)
Backlog orchestration — Multi-agent backlog resolution:
kdx-notion-backlog-review (orchestrator, dispatches parallel kdx-notion-backlog-fix-issue workers in isolated worktrees)
Escalation pattern. prd-inspector (Haiku) fires on every code change that touches business logic. If it detects major drift from the specification, it escalates to prd-adr-expert (Opus). The expert is the final authority — it diagnoses and cites spec but never edits code or documents. For full-scope audits, kdx-audit-prd (skill) launches an Opus orchestrator that, for each PRD section with content, dispatches parallel Haiku subagents: one searches code, one reads ADRs, one queries the Notion backlog. Opus reconciles findings.
Persistent memory. Agents that accumulate decisions across conversations have a memory directory in .claude/agent-memory/<name>/. Each directory contains a MEMORY.md index and individual memory files. Memory records resolved ambiguities, schema decisions, and cross-document dependencies that are not derivable from code or git history alone. Not all agents have memory — context servers and the inspector are stateless by design.
Registry authority. CLAUDE.md (repository root) is the authoritative, always-loaded registry of all available agents and skills. It lists every agent and skill with its trigger, description, and usage rules. This ADR documents the architectural decision and taxonomy; CLAUDE.md documents the current inventory. When adding a new agent or skill, update CLAUDE.md — not this ADR.
Consequences
Sección titulada «Consequences»- Adding a new agent requires defining: model tier, role, write permissions, and whether it has persistent memory. The taxonomy table in this ADR is the template.
- Adding a new skill requires only a
SKILL.mdin.claude/skills/<name>/and an entry inCLAUDE.md. Skills do not need an ADR update. - Context servers are a distinct category from project agents — they are stateless, read-only, and singleton within a conversation.
- Personas are a distinct category from project agents — they do not have memory, do not write files, and exist solely for BDD scenario enactment.
- The model tier is explicit: Haiku for high-frequency/low-cost (inspector, context servers, personas), Sonnet for editing (ADR, PRD, code), Opus for authority and orchestration (expert, audit).
CLAUDE.mdis the living registry; this ADR is the structural contract. Keeping them separate avoids the triple-maintenance problem (ADR + CLAUDE.md + README).