ADR-003: CODITECT Agent System

Status

ACCEPTED (2026-02-03)

Context

CODITECT needed a robust agent system that:

1. Extends Claude Code - Add specialized agents beyond built-in types
2. Enables Specialization - Domain-specific expertise (security, docs, DevOps)
3. Supports Discovery - Find the right agent for any task
4. Maintains Standards - Consistent format across 210+ agents

Claude Code Built-in vs CODITECT Agents

Aspect	Claude Code Built-in	CODITECT Custom
Count	~52 types	210+ agents
Invocation	Task(subagent_type="...")	/agent <name> "task"
Definition	Internal	agents/*.md files
Customization	None	Full control

Decision

Agent Definition Format

All CODITECT agents are Markdown files with YAML frontmatter:

---
name: agent-name
description: Brief description (max 1024 chars)
tools: Read, Write, Edit, Bash, Grep, Glob, LS
model: sonnet  # sonnet | opus | haiku
---

# Agent Role Statement
You are a [role] specialist who [purpose].

## Core Responsibilities
- Responsibility 1
- Responsibility 2

## Capabilities
### Capability 1
Description of capability

## Invocation Examples
/agent agent-name "task description"

File Structure

agents/
├── codi-documentation-writer.md
├── security-specialist.md
├── devops-engineer.md
├── senior-architect.md
├── database-architect.md
├── testing-specialist.md
├── frontend-react-typescript-expert.md
├── orchestrator.md
└── ... (210+ total)

Agent Discovery

# Find agent for task
/which <task-description>

# Example
/which "deploy to kubernetes"
# → k8s-statefulset-specialist (94% match)

# Query database directly
python3 scripts/component-indexer.py --type agent --search "security"

Agent Invocation Methods

Method	Syntax	Use Case
Slash Command	/agent <name> "task"	Interactive
Task Tool	Task(subagent_type="<name>")	Programmatic
Dispatcher	agent_dispatcher.py	Multi-agent routing

Agent Categories

Category	Count	Examples
Development	~25	orchestrator, senior-architect
DevOps	~15	devops-engineer, cloud-architect
Security	~10	security-specialist, penetration-testing
Documentation	~8	codi-documentation-writer
Business	~12	business-intelligence-analyst
Data	~10	database-architect
Research	~8	research-agent
Quality	~10	testing-specialist

Model Binding

Agents specify their preferred model:

Model	Token Cost	Use Case
haiku	Lowest	Quick, simple tasks
sonnet	Medium	Most tasks (default)
opus	Highest	Complex reasoning

# In agent frontmatter
model: sonnet

Tool Access

Agents declare required tools:

tools: Read, Write, Edit, Bash, Grep, Glob, LS, TodoWrite

Available Tools:

• Read - Read files
• Write - Create new files
• Edit - Modify existing files
• Bash - Execute shell commands
• Grep - Search file contents
• Glob - Find files by pattern
• LS - List directory contents
• TodoWrite - Task management
• WebSearch - Web search
• WebFetch - Fetch web content

Agent Routing

The /which command uses semantic search to match tasks to agents:

Task Analysis → Keyword Extraction → Database Query → Ranking → Recommendation

Match Scoring:

• 90-100%: Exact match - agent specializes in this task
• 75-89%: Strong match - agent well-suited
• 60-74%: Moderate match - agent can help
• <60%: Weak match - consider alternatives

Integration with Skills

Agents can reference skills for additional capabilities:

# In agent definition
related_skills:
  - security-audit
  - vulnerability-assessment

Track Assignment

Each agent has an associated PILOT track:

Track	Primary Agents
A (Backend)	senior-architect, database-architect
B (Frontend)	frontend-react-typescript-expert
C (DevOps)	devops-engineer, cloud-architect
D (Security)	security-specialist
E (Testing)	testing-specialist
F (Docs)	codi-documentation-writer
H (Framework)	orchestrator, senior-architect

Consequences

Positive

1. Specialization - Domain experts for every task type
2. Discoverability - /which finds the right agent
3. Extensibility - Add agents without core changes
4. Standardization - Consistent format and behavior
5. Model Efficiency - Right-sized models per task

Negative

1. Agent Sprawl - 210+ agents to maintain
2. Overlap - Some agents have similar capabilities
3. Learning Curve - Users must learn agent ecosystem

Risks

Risk	Mitigation
Wrong agent selection	/which command with scoring
Inconsistent definitions	CODITECT-STANDARD-AGENTS.md
Model cost overruns	Default to sonnet, opus for complex only

Implementation

Creating New Agents

# Use HOW-TO guide
cat coditect-core-standards/HOW-TO-CREATE-NEW-AGENT.md

# Use component-create command
/component-create agent my-new-agent

Agent Validation

# Validate agent format
python3 scripts/validate-agent.py agents/my-agent.md

Agent Indexing

# Index all agents to platform.db
python3 scripts/component-indexer.py --type agent

Related

• ADR-001: Framework Architecture
• ADR-013: Agent-Skills Framework Adoption
• CODITECT-STANDARD-AGENTS.md: Agent definition standard
• HOW-TO-CREATE-NEW-AGENT.md: Agent creation guide

---

Track: H (Framework Autonomy) Task: F.12.2.2