Agent Development Guide

Prerequisites

Before developing CODITECT agents, ensure you have:

• CODITECT framework cloned and configured
• Python 3.10+ installed
• Understanding of YAML frontmatter format
• Familiarity with Claude Code Task tool

Verify environment:

# Check CODITECT installation
ls -la .coditect/

# Verify agents directory
ls agents/ | head -10

Agent Development Guide

Complete guide to developing CODITECT agents with proper frontmatter, MoE classification, and thinking budget configuration.

---

Quick Start

Step 1: Create Agent File

Create a new agent in agents/your-agent-name.md:

---
title: "Your Agent Name"
component_type: agent
version: "1.0.0"
audience: contributor
status: stable
summary: "One-line description (max 100 chars)"
keywords: ['keyword1', 'keyword2']
tokens: ~2000
created: 2025-12-22
updated: 2025-12-22
agent_type: specialist
domain: ['development']
moe_role: specialist
moe_capabilities:
  - specialized_analysis
  - task_execution
invocation_pattern: "Task(subagent_type='your-agent-name', prompt='...')"
requires_context: true
model: sonnet
tools: "Read, Write, Edit, Grep, Glob"
quality_score: 75
last_reviewed: 2025-12-22
---

You are a [Your Agent Role] responsible for [primary responsibility].

## Core Capabilities
- Capability 1
- Capability 2

## When to Use
- Use case 1
- Use case 2

Step 2: Configure Frontmatter

Review and customize all required fields (see schema below).

Step 3: Activate Agent

python3 scripts/update-component-activation.py activate agent your-agent-name --reason "Purpose"
python3 scripts/update-component-counts.py

---

Agent Frontmatter Schema (ADR-018)

Required Fields

Field	Type	Description
title	string	Human-readable agent name
component_type	string	Always agent
version	semver	Agent version (e.g., "1.0.0")
audience	enum	customer, contributor, or both
status	enum	draft, experimental, stable, production, deprecated
summary	string	One-line description (max 100 chars)
keywords	array	Search keywords for discovery
tokens	string	Estimated token count (e.g., ~2000)
created	date	Creation date (YYYY-MM-DD)
updated	date	Last update date (YYYY-MM-DD)

Agent-Specific Fields

Field	Type	Description
agent_type	enum	specialist, analyst, judge, orchestrator, reviewer, generator
domain	array	Areas of expertise: security, development, qa, devops, documentation, research
moe_role	enum	MoE classification (see below)
moe_capabilities	array	Agent capabilities for MoE routing
invocation_pattern	string	How to invoke this agent
requires_context	bool	Whether agent needs conversation context
model	enum	sonnet, opus, haiku
tools	string	Available tools (comma-separated)
quality_score	int	Quality score 0-100
last_reviewed	date	Last review date

---

MoE Role Classification

CODITECT uses Mixture of Experts (MoE) for intelligent agent routing.

Role Types

Role	Purpose	Capabilities
orchestrator	Coordinate multi-agent workflows	task_decomposition, agent_selection, workflow_coordination
analyst	Deep analysis and pattern recognition	deep_analysis, pattern_recognition, evidence_gathering
judge	Evaluate and score outputs	evaluation, scoring, verdict_generation, consensus_building
specialist	Domain-specific expertise	specialized_analysis, task_execution
none	No MoE routing needed	-

Example MoE Configurations

Orchestrator Agent:

moe_role: orchestrator
moe_capabilities:
  - task_decomposition
  - agent_selection
  - workflow_coordination
  - result_aggregation

Analyst Agent:

moe_role: analyst
moe_capabilities:
  - deep_analysis
  - pattern_recognition
  - evidence_gathering
  - uncertainty_quantification

Judge Agent:

moe_role: judge
moe_capabilities:
  - evaluation
  - scoring
  - verdict_generation
  - consensus_building

---

Thinking Budgets

Configure thinking budget in frontmatter for cost control:

thinking:
  budget_tokens: 10000      # Max thinking tokens
  enabled: true             # Enable extended thinking
  level: standard           # minimal, standard, extended, maximum

Budget Levels

Level	Tokens	Use Case
minimal	2,000	Simple lookups, quick responses
standard	10,000	Most development tasks
extended	25,000	Complex analysis, code review
maximum	50,000	Architecture decisions, deep research

See Thinking Budget System for details.

---

Agent Body Structure

After frontmatter, include:

1. Role Statement

You are a [Role] responsible for [primary responsibility].

2. Core Capabilities

## Core Capabilities
- Capability 1 with description
- Capability 2 with description

3. When to Use

## When to Use
- Use case 1
- Use case 2

## When NOT to Use
- Anti-pattern 1
- Anti-pattern 2

4. Usage Examples

## Usage Examples

**Example 1: Basic Usage**
\`\`\`
Task(subagent_type='your-agent', prompt='Do something specific')
\`\`\`

---

Invocation Patterns

Direct Task Invocation

Task(subagent_type='agent-name', prompt='Your detailed prompt here')

With Model Override

Task(subagent_type='agent-name', prompt='...', model='opus')

Background Execution

Task(subagent_type='agent-name', prompt='...', run_in_background=True)

---

Agent Activation

After creating an agent, activate it:

# Add to activation status
python3 scripts/update-component-activation.py activate agent YOUR-AGENT-NAME --reason "Purpose"

# Update component counts
python3 scripts/update-component-counts.py

# Verify
python3 scripts/update-component-activation.py status agent YOUR-AGENT-NAME

---

Best Practices

DO

• Use descriptive, action-oriented names (e.g., code-reviewer, security-auditor)
• Include clear "When to Use" and "When NOT to Use" sections
• Provide concrete usage examples
• Set appropriate thinking budgets for complexity
• List all required tools explicitly

DON'T

• Create agents that overlap significantly with existing ones
• Use vague summaries or descriptions
• Skip the MoE role classification
• Hardcode paths or project-specific values
• Create agents without activation

---

Troubleshooting

Agent Not Activating

Problem: New agent doesn't appear in component counts Solution: Run activation command:

python3 scripts/update-component-activation.py activate agent YOUR-AGENT --reason "purpose"
python3 scripts/update-component-counts.py

Frontmatter Validation Errors

Problem: Agent fails frontmatter validation Solution: Verify all required fields present (title, component_type, version, status, summary)

MoE Role Not Recognized

Problem: Agent not routed correctly by MoE system Solution: Verify moe_role is one of: orchestrator, analyst, judge, specialist, none

---

Related Documentation

• ADR-018: Agentic Documentation Standard
• Thinking Budget System
• Agent Frontmatter Config
• Component Activation Guide

---

Next Steps

After creating your agent:

1. Test invocation: /agent your-agent-name "test task"
2. Review: Component Activation Guide
3. Explore: Thinking Budget System
4. Reference: Agent Frontmatter Config

---

Last Updated: 2025-12-28 Compliance: CODITECT Documentation Standard v1.0.0