CODITECT STANDARD: Agents

Version: 1.0.0 Status: Production Standard Last Updated: December 3, 2025 Authority: Based on Anthropic Agent SDK Official Documentation Scope: All agent definitions in .coditect/agents/

1. Executive Summary

This document defines the authoritative standard for CODITECT agent files. All agents MUST comply with this standard to ensure consistency, maintainability, and compatibility with the Anthropic Claude Agent SDK.

Compliance: Mandatory for all agents in coditect-core repository.

2. Required File Format

2.1 File Naming Convention

Pattern: {agent-name}.md

Rules:

Lowercase only
Hyphen-separated words (kebab-case)
No spaces, underscores, or special characters
Maximum 64 characters
Must match name field in YAML frontmatter

Valid Examples:

codebase-analyzer.md
biographical-researcher.md
rust-expert-developer.md

Invalid Examples:

CodebaseAnalyzer.md (uppercase)
codebase_analyzer.md (underscore)
codebase analyzer.md (space)

2.2 File Location

Path: .coditect/agents/{agent-name}.md

NOT allowed:

Subdirectories within agents/
Agents outside .coditect/agents/
Duplicate agent names

3. YAML Frontmatter Structure

3.1 Required Fields

All agents MUST include YAML frontmatter at the start of the file:

---
name: agent-name
description: Brief description of agent purpose and capabilities (max 1024 characters)
tools: Read, Write, Edit, Bash, Grep, Glob, LS, TodoWrite
model: sonnet
---

Field Specifications:

Field	Type	Required	Max Length	Validation
`name`	string	YES	64 chars	Lowercase, hyphens only, no "anthropic" or "claude"
`description`	string	YES	1024 chars	Non-empty, no XML tags
`tools`	array/string	YES	N/A	Comma-separated tool names
`model`	string	YES	N/A	`sonnet`, `opus`, or `haiku`

Tool Names (Official Anthropic 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 capability
WebFetch - Fetch web content

3.2 CODITECT Metadata Fields (Recommended)

All agents SHOULD include these metadata fields for version observability and lifecycle tracking (H.24):

Field	Type	Required	Format	Description
`version`	string	Recommended	SemVer (`1.0.0`)	Component version
`component_type`	string	Recommended	Fixed: `agent`	Component type identifier
`created`	string	Recommended	`'YYYY-MM-DD'`	Creation date
`updated`	string	Recommended	`'YYYY-MM-DD'`	Last content modification date
`last_reviewed`	string	Recommended	`'YYYY-MM-DD'`	Last human/AI review date
`track`	string	Recommended	Single letter	CODITECT track assignment (e.g., `H`)
`status`	string	Recommended	`active` / `deprecated`	Lifecycle status
`audience`	string	Recommended	`customer` / `contributor`	Target audience
`tokens`	string	Recommended	`~1500`	Approximate token cost
`tags`	array	Recommended	`[agent, automation]`	Category tags

last_reviewed vs updated:

updated records when the content was last modified (auto-set on edit)
last_reviewed records when the content was last verified for correctness (set deliberately)
A component where updated > last_reviewed has been changed but not yet verified — use /version --outdated to find these
A component where last_reviewed is older than 90 days is stale — use /version --stale to find these

3.3 Optional Fields (CODITECT Extensions)

---
# ... required fields ...

# Context Awareness DNA (CODITECT Enhancement)
context_awareness:
  auto_scope_keywords:
    primary_domain: ["keyword1", "keyword2", "keyword3"]
    secondary_domain: ["keyword4", "keyword5"]

  entity_detection:
    entity_type_1: ["pattern1", "pattern2"]
    entity_type_2: ["pattern3", "pattern4"]

  progress_checkpoints:
    - 25%: "Description of 25% completion state"
    - 50%: "Description of 50% completion state"
    - 75%: "Description of 75% completion state"
    - 100%: "Description of 100% completion state"
---

Context Awareness Fields:

Field	Purpose	Format	Example
`auto_scope_keywords`	Trigger keywords for agent activation	Object with arrays	`architecture_analysis: ["architecture", "patterns"]`
`entity_detection`	Patterns for entity recognition	Object with arrays	`file_types: [".py", ".js"]`
`progress_checkpoints`	Status reporting at milestones	Array of percentage: description	`25%: "Initial scan complete"`

4. Agent Instruction Format

4.1 Required Sections

After YAML frontmatter, agent instructions MUST follow this structure:

---
[YAML frontmatter here]
---

# Agent Role Statement
[One paragraph describing who this agent is and what it does]

## Core Responsibilities

[Bulleted list of 3-7 primary responsibilities]

## Capabilities

### Capability 1: [Name]
[Description of what this capability does]

### Capability 2: [Name]
[Description of what this capability does]

## Invocation Examples

### Direct Agent Call
```python
Task(subagent_type="agent-name",
     description="Brief task description",
     prompt="Detailed instructions for agent")

Via Slash Command (if applicable)

/command-name [arguments]

Limitations

[What this agent does NOT do or is not responsible for]

Integration

[How this agent works with other CODITECT components]

### 4.2 Section Descriptions

**Agent Role Statement:**
- 1-2 sentences
- Written in second person ("You are...")
- Defines agent identity and primary purpose
- Must be clear and unambiguous

**Core Responsibilities:**
- 3-7 bullet points
- Each starts with action verb
- Specific, measurable outcomes
- Avoid vague or overlapping responsibilities

**Capabilities:**
- Organized as H3 subsections
- Each capability has clear name and description
- Include examples where helpful
- Link to related skills or commands

**Invocation Examples:**
- MUST include Task() pattern
- Show realistic use cases
- Include required and optional parameters
- Link to related commands/skills

**Limitations:**
- Explicitly state what agent does NOT do
- Prevent scope creep
- Guide users to appropriate alternatives
- Avoid negative framing (state facts, not complaints)

**Integration:**
- List related agents, skills, commands
- Describe workflow patterns
- Explain dependencies
- Reference documentation

---

## 5. Progressive Disclosure Implementation

Agents implement 2-level progressive disclosure:

**Level 1: Metadata (Always Loaded)**
- YAML frontmatter: `name`, `description`, `tools`, `model`
- Estimated token cost: 50-150 tokens
- Loaded at session start
- Used for agent discovery and selection

**Level 2: Instructions (On-Demand)**
- Full markdown body loaded when agent invoked
- Estimated token cost: 500-5000 tokens
- Loaded only when agent is actively used

**Optimization Guidelines:**
- Keep description concise but informative
- Front-load critical information in instructions
- Use examples sparingly (link to separate docs if extensive)
- Defer detailed reference material to skills or separate docs

---

## 6. Quality Criteria

### 6.1 Compliance Checklist

All agents must pass these checks:

**File Format (Weight: 20%)**
- [ ] Filename matches pattern `{agent-name}.md`
- [ ] Located in `.coditect/agents/`
- [ ] No duplicate names in repository

**YAML Frontmatter (Weight: 40%)**
- [ ] All required fields present: name, description, tools, model
- [ ] `name` matches filename (without .md)
- [ ] `description` under 1024 characters, no XML tags
- [ ] `tools` lists valid Anthropic tool names
- [ ] `model` is sonnet, opus, or haiku

**Instruction Quality (Weight: 30%)**
- [ ] Agent role statement present and clear
- [ ] Core responsibilities listed (3-7 items)
- [ ] Capabilities organized with H3 headings
- [ ] Invocation examples include Task() pattern
- [ ] Limitations section present
- [ ] Integration section present

**Documentation Standards (Weight: 10%)**
- [ ] Markdown formatting valid
- [ ] Links functional (if present)
- [ ] Code examples properly formatted
- [ ] Grammar and spelling correct

### 6.2 Grading Scale

**Grade A (90-100%):** Production-ready, exemplary quality
**Grade B (80-89%):** Production-ready, minor improvements needed
**Grade C (70-79%):** Functional, moderate improvements needed
**Grade D (60-69%):** Requires significant improvements
**Grade F (<60%):** Does not meet minimum standards, rework required

### 6.3 Automated Validation

Agents can be validated using:

```bash
python3 .coditect/scripts/validate-agent.py agents/{agent-name}.md

Validation Output:

Compliance score (0-100%)
Failed checks with line numbers
Recommendations for improvement
Grade assignment

7. Template

7.1 Minimal Agent Template

---
name: example-agent
description: Brief description of what this agent does and when to use it
tools: Read, Write, Edit, Bash, Grep, Glob, TodoWrite
model: sonnet
---

You are a specialist agent for [specific purpose]. Your role is to [primary function] following [methodology or framework].

## Core Responsibilities

1. **[Responsibility 1]:** [Brief description]
2. **[Responsibility 2]:** [Brief description]
3. **[Responsibility 3]:** [Brief description]

## Capabilities

### 1. [Capability Name]

[Description of what this capability does and how it works]

**Examples:**
- [Example use case 1]
- [Example use case 2]

### 2. [Capability Name]

[Description of second capability]

## Invocation

### Direct Agent Call

```python
Task(subagent_type="example-agent",
     description="Task description",
     prompt="Detailed instructions for agent")

Limitations

This agent does NOT:

[Limitation 1]
[Limitation 2]

For [alternative use case], use [other-agent] instead.

Integration

Related Components:

Skills: [skill-name] - [purpose]
Commands: /command-name - [purpose]
Agents: [agent-name] - [relationship]

### 7.2 Full Agent Template (with CODITECT Extensions)

```markdown
---
name: advanced-agent
description: Comprehensive agent with context awareness and progress tracking
tools: Read, Write, Edit, Bash, Grep, Glob, LS, TodoWrite, WebSearch
model: sonnet

# CODITECT Metadata (Recommended)
version: 1.0.0
component_type: agent
created: '2026-02-12'
updated: '2026-02-12'
last_reviewed: '2026-02-12'
track: H
status: active

# Context Awareness DNA
context_awareness:
  auto_scope_keywords:
    primary_domain: ["keyword1", "keyword2", "keyword3"]
    technical_indicators: ["indicator1", "indicator2"]

  entity_detection:
    file_patterns: ["*.py", "*.js", "*.md"]
    domain_terms: ["term1", "term2"]

  progress_checkpoints:
    - 25%: "Initial analysis complete - key components identified"
    - 50%: "Core implementation underway - primary objectives addressed"
    - 75%: "Integration phase - connecting components and validating"
    - 100%: "Task complete - all objectives achieved and documented"
---

You are [agent role description]. Your mission is to [primary objective] by [methodology].

## Core Responsibilities

1. **[Responsibility 1]:** [Detailed description of what this entails]
2. **[Responsibility 2]:** [Detailed description]
3. **[Responsibility 3]:** [Detailed description]
4. **[Responsibility 4]:** [Detailed description]

## Capabilities

### 1. [Capability Name]

[Comprehensive description of capability]

**Process:**
1. [Step 1]
2. [Step 2]
3. [Step 3]

**Examples:**

[Code or usage example]

### 2. [Capability Name]

[Description]

### 3. [Capability Name]

[Description]

## Invocation

### Direct Agent Call

```python
Task(subagent_type="advanced-agent",
     description="Descriptive task summary",
     prompt="""
     [Detailed multi-line instructions]

     Context: [contextual information]
     Requirements: [specific requirements]
     Output: [expected output format]
     """)

Via Skill

# Skill provides reusable capability
# See: skills/related-skill/SKILL.md

Via Slash Command

/related-command [arguments]

Workflow Patterns

Pattern 1: [Workflow Name]

[Description of when to use this pattern]

Steps:

[Step 1]
[Step 2]
[Step 3]

Pattern 2: [Workflow Name]

[Description]

Limitations

This agent is designed for [specific scope] and does NOT:

[Limitation 1 with rationale]
[Limitation 2 with rationale]
[Limitation 3 with rationale]

For alternative use cases:

[Use case] → Use [alternative-agent]
[Use case] → Use [alternative-agent]

Integration

Dependencies:

Skills: [skill-name] - [how it's used]
Commands: /command - [relationship]

Complementary Agents:

[agent-name]: [when to use together]
[agent-name]: [workflow integration]

Configuration:

Requires: [any settings or environment setup]
Optional: [optional configuration]

References

[Link to related documentation]
[Link to examples]
[Link to skill definitions]

---

## 8. Migration Guide

### 8.1 Upgrading Existing Agents

**Step 1: Add Missing Required Fields**

Check YAML frontmatter for all required fields:
```bash
python3 scripts/check-agent-fields.py agents/your-agent.md

Step 2: Standardize Structure

Ensure sections match standard order:

YAML frontmatter
Agent role statement
Core Responsibilities
Capabilities
Invocation examples
Limitations
Integration

Step 3: Validate Compliance

python3 scripts/validate-agent.py agents/your-agent.md

Step 4: Update Documentation References

Ensure all links and references are current.

8.2 Common Migration Issues

Issue 1: Missing Tools Field

# Before
---
name: my-agent
description: Does things
---

# After
---
name: my-agent
description: Does things
tools: Read, Write, Edit, Bash, Grep, Glob, TodoWrite
model: sonnet
---

Issue 2: Inconsistent Section Names

Standardize section headings to match template.

Issue 3: Missing Invocation Examples

Add Task() invocation pattern if missing.

9. References

9.1 Anthropic Official Documentation

9.2 CODITECT Standards

CODITECT-STANDARD-SKILLS.md - Skills format standard
CODITECT-STANDARD-COMMANDS.md - Commands format standard
CODITECT-STANDARD-HOOKS.md - Hooks format standard

10. Version History

Version	Date	Changes	Author
1.0.0	2025-12-03	Initial standard based on Anthropic documentation	CODITECT Team

11. Enforcement

Compliance Deadline: All agents must achieve Grade B (80%) or higher within 30 days of standard publication.

Validation Method: Automated CI/CD checks on all PRs affecting agent files.

Review Process: Manual quarterly audits of agent quality and consistency.

Exceptions: Requests for standard exemption must be documented with rationale and approved by technical lead.

Document Control:

Owner: CODITECT Core Team
Approvers: Technical Lead, Documentation Lead
Review Cycle: Quarterly
Next Review: 2026-03-03

1. Executive Summary​

2. Required File Format​

2.1 File Naming Convention​

2.2 File Location​

3. YAML Frontmatter Structure​

3.1 Required Fields​

3.2 CODITECT Metadata Fields (Recommended)​

3.3 Optional Fields (CODITECT Extensions)​

4. Agent Instruction Format​

4.1 Required Sections​

Via Slash Command (if applicable)​

Limitations​

Integration​

7. Template​

7.1 Minimal Agent Template​

Limitations​

Integration​

Via Skill​

Via Slash Command​

Workflow Patterns​

Pattern 1: [Workflow Name]​

Pattern 2: [Workflow Name]​

Limitations​

Integration​

References​

8.2 Common Migration Issues​

9. References​

9.1 Anthropic Official Documentation​

9.2 CODITECT Standards​

10. Version History​

11. Enforcement​

1. Executive Summary

2. Required File Format

2.1 File Naming Convention

2.2 File Location

3. YAML Frontmatter Structure

3.1 Required Fields

3.2 CODITECT Metadata Fields (Recommended)

3.3 Optional Fields (CODITECT Extensions)

4. Agent Instruction Format

4.1 Required Sections

Via Slash Command (if applicable)

Limitations

Integration

7. Template

7.1 Minimal Agent Template

Limitations

Integration

Via Skill

Via Slash Command

Workflow Patterns

Pattern 1: [Workflow Name]

Pattern 2: [Workflow Name]

Limitations

Integration

References

8.2 Common Migration Issues

9. References

9.1 Anthropic Official Documentation

9.2 CODITECT Standards

10. Version History

11. Enforcement