agent-design

name	agent-design
description	Use when creating new specialist agent definitions for codingbuddy. Covers JSON schema design, expertise definition, system prompt authoring, and differentiation from existing agents.

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

Field	Type	Rules
name	string	Display name, Title Case (e.g., "Migration Specialist")
description	string	10+ chars, one sentence
role	object	Must include title at minimum
role.title	string	Official role title
role.expertise	string[]	3-7 items, specific domains
context_files	string[]	Paths starting with .ai-rules/

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

Optional Fields

Field	Type	Description
role.type	string	primary (main agent in a mode) / specialist (domain reviews)
role.responsibilities	string[]	Key responsibilities
modes.planning	object	Planning mode activation config
modes.implementation	object	Implementation mode activation config
modes.evaluation	object	Evaluation mode activation config
activation	object	Activation triggers, workflow integration
model	object	Preferred AI model config (preferred, reason)

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

Pattern	Example	Use for
<domain>-specialist	security-specialist	Narrow domain expert
<role>-engineer	devops-engineer	Engineering role
<role>-developer	frontend-developer	Developer persona
<role>-architect	solution-architect	Architecture role
<domain>-mode	plan-mode	Workflow mode agent

Common Mistakes

Mistake	Fix
Too broad ("backend developer")	Narrow to specific domain (e.g., "api-designer")
Expertise overlaps with existing agent	Merge or redefine scope
System prompt has no "you do NOT handle"	Every agent needs explicit boundaries
Expertise items are vague ("databases")	Make specific ("PostgreSQL Query Optimization")
No mode specified	Always define which PLAN/ACT/EVAL modes apply
Filename uses camelCase	Use kebab-case for filenames (e.g., my-agent.json)

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