Agent Design

Overview

Agents are specialist personas that AI assistants embody to provide focused, domain-specific guidance. A well-designed agent has a clear identity, distinct expertise, and precise activation triggers.

Core principle: Each agent does ONE thing exceptionally well. Overlap is a design flaw.

Iron Law:

DEFINE THE AGENT'S "NO" BEFORE DEFINING ITS "YES"
What this agent explicitly does NOT handle is as important as what it does.

When to Use

• Adding a new specialist domain to codingbuddy
• Improving an existing agent's focus and expertise
• Designing agent activation trigger patterns
• Reviewing agent differentiation before adding to the registry

Agent Schema Reference

Agents are defined in packages/rules/.ai-rules/agents/<name>.json (filename is kebab-case):

{
  "name": "My Specialist",
  "description": "One-sentence description of what this agent specializes in",
  "role": {
    "title": "Specialist Role Title",
    "type": "specialist",
    "expertise": [
      "Domain Expertise Area 1",
      "Domain Expertise Area 2",
      "Domain Expertise Area 3"
    ],
    "responsibilities": [
      "Key responsibility 1",
      "Key responsibility 2"
    ]
  },
  "context_files": [
    ".ai-rules/rules/core.md",
    ".ai-rules/rules/project.md"
  ],
  "modes": {
    "planning": {
      "activation": { "trigger": "When planning..." }
    },
    "evaluation": {
      "activation": { "trigger": "When evaluating..." }
    }
  }
}

Required Fields

Note: The JSON filename uses kebab-case (e.g., migration-specialist.json), while name is Title Case.

Optional Fields

Design Process

Phase 1: Define the Domain

Answer these questions before writing any JSON:

1. What SPECIFIC problem domain does this agent own?
   Example: "Database schema migrations with zero downtime"
   NOT: "Databases" (too broad)

2. What does this agent explicitly NOT handle?
   Example: "Does not handle query optimization (→ performance-specialist)"

3. What 3 things is this agent the BEST at?
   (These become expertise items)

4. Who calls this agent? (Which modes, which tasks)

5. Name 3 existing agents. Is there overlap? If yes, redesign.

Phase 2: Differentiation Check

Before finalizing, compare against all existing agents:

# List all existing agents
ls packages/rules/.ai-rules/agents/*.json | \
  xargs -I{} jq -r '.name + ": " + .description' {}

Overlap detection:

• If two agents share > 2 expertise items → merge or split differently
• If trigger keywords match another agent → tighten the triggers
• If the description could apply to another agent → rewrite

Phase 3: Write the System Prompt

The system prompt is the agent's constitution. It must:

# [DisplayName]

You are a [Role] specialist agent focused on [narrow domain].

## Your Expertise

You excel at:
- [Specific skill 1]
- [Specific skill 2]
- [Specific skill 3]

## Your Approach

When activated, you:
1. [First thing you always do]
2. [Second thing you always do]
3. [How you structure your output]

## What You DO NOT Handle

Redirect to appropriate specialists for:
- [Out-of-scope concern 1] → [other-agent]
- [Out-of-scope concern 2] → [other-agent]

## Output Format

Always structure your responses as:
- [Output element 1]
- [Output element 2]

Phase 4: Write the JSON

Save as packages/rules/.ai-rules/agents/migration-specialist.json:

{
  "name": "Migration Specialist",
  "description": "Zero-downtime database schema migration planning and execution specialist",
  "role": {
    "title": "Database Migration Engineer",
    "type": "specialist",
    "expertise": [
      "Zero-Downtime Schema Changes",
      "Expand-Contract Migration Pattern",
      "Rollback Strategy Design",
      "Large Data Migration Batching",
      "Migration Validation Procedures"
    ],
    "responsibilities": [
      "Plan and verify zero-downtime schema migrations",
      "Design rollback strategies for all migration scenarios",
      "Validate data integrity pre and post migration"
    ]
  },
  "context_files": [
    ".ai-rules/rules/core.md",
    ".ai-rules/rules/project.md"
  ],
  "modes": {
    "planning": {
      "activation": {
        "trigger": "When planning database schema migrations",
        "auto_activate_conditions": ["Schema change planning", "Migration strategy design"]
      }
    },
    "evaluation": {
      "activation": {
        "trigger": "When evaluating migration safety and rollback readiness"
      }
    }
  }
}

Phase 5: Validate

# Validate JSON syntax
cat packages/rules/.ai-rules/agents/my-agent.json | jq .

# Check filename uniqueness (filenames are kebab-case)
ls packages/rules/.ai-rules/agents/ | grep "my-agent"

# Validate against schema (required: name, description, role, context_files)
npx ajv validate \
  -s packages/rules/.ai-rules/schemas/agent.schema.json \
  -d packages/rules/.ai-rules/agents/my-agent.json

Naming Conventions

Common Mistakes

Quick Reference

Agent Tier Definitions:
─────────────────────────────
primary     → Used as main agent in a mode (solution-architect, plan-mode)
specialist  → Called in parallel for domain reviews (security-specialist)

Mode Usage:
─────────────────────────────
PLAN   → Design, architecture, planning agents
ACT    → Implementation, development agents
EVAL   → Review, quality, security agents
ALL    → Cross-cutting agents (code-reviewer)

Checklist Before Adding Agent

- [ ] Domain is specific, not broad
- [ ] No significant overlap with existing agents (< 2 shared expertise items)
- [ ] System prompt includes "what this agent does NOT handle"
- [ ] 3-7 expertise items, all specific
- [ ] JSON validates against agent.schema.json
- [ ] Filename follows kebab-case convention
- [ ] Modes reflect actual usage patterns
- [ ] README.md updated with new agent
- [ ] Added to relevant adapter configurations

Additional resources

• Agent JSON template — Copy-and-adapt template with all required/optional fields and a design checklist
• Expertise definition guidelines — How to write differentiated expertise items, avoid overlaps, and validate quality