Skip to content

Latest commit

 

History

History
265 lines (198 loc) · 8.99 KB

AGENTS.md

File metadata and controls

265 lines (198 loc) · 8.99 KB

AGENTS.md

This file provides guidance to Codex when working with code in this repository. To use these agents in another project, copy the codex folder to your repository root and merge this file with your existing AGENTS.md.

Project Overview

This is the Awesome Codex Agents repository - a collection of specialized AI agents that extend Codex's capabilities through intelligent orchestration and domain expertise. The agents work together as a development team, with each agent having specific expertise and delegation patterns.

Working with Agents

When creating or modifying agents:

  1. Agents are Markdown files with YAML frontmatter
  2. Most agents should omit the tools field to inherit all available tools
  3. Use XML-style examples in descriptions for intelligent invocation
  4. Agents return structured findings for main agent coordination

Orchestration Pattern for Codex

Since sub-agents in Codex cannot directly invoke other sub-agents, orchestration follows this strict pattern:

CRITICAL: Agent Routing Protocol

When handling complex tasks, you MUST:

  1. ALWAYS start with tech-lead-orchestrator for any multi-step task
  2. FOLLOW the agent routing map returned by tech-lead EXACTLY
  3. USE ONLY the agents explicitly recommended by tech-lead
  4. NEVER select agents independently - tech-lead knows which agents exist

Example: Building a Feature with Agent Routing

User: "Build a user management system"

Main Codex Agent:
1. First, I'll use the tech-lead-orchestrator to analyze and get routing
   → Tech lead returns Agent Routing Map with SPECIFIC agents
   
2. I MUST use ONLY the agents listed in the routing map:
   - If tech-lead says "use django-api-developer" → Use that EXACT agent
   - If tech-lead says "use react-component-architect" → Use that EXACT agent
   - DO NOT substitute with generic agents unless specified as fallback
   
3. Execute tasks in the order specified by tech-lead using TodoWrite

Key Orchestration Rules

  1. Tech-Lead is Routing Authority: Tech-lead determines which agents can handle each task
  2. Strict Agent Selection: Use ONLY agents from tech-lead's "Available Agents" list
  3. No Improvisation: Do NOT select agents based on your own judgment
  4. Deep Reasoning: Apply careful thought when coordinating the recommended agents
  5. Structured Handoffs: Extract and pass information between agent invocations

Agent Selection Flow

CORRECT FLOW:
User Request → Tech-Lead Analysis → Agent Routing Map → Execute with Listed Agents

INCORRECT FLOW:
User Request → Main Agent Guesses → Wrong Agent Selected → Task Fails

Example Tech-Lead Response You Must Follow

When tech-lead returns:

## Available Agents for This Project
- django-backend-expert: Django tasks
- django-api-developer: API tasks  
- react-component-architect: React UI

You MUST use these specific agents, NOT generic alternatives like "backend-developer"

High-Level Architecture

Agent Organization

The project follows a hierarchical structure:

  1. Orchestrators (agents/orchestrators/)

    • tech-lead-orchestrator: Coordinates complex projects through three-phase workflow (Research → Planning → Execution)
    • project-analyst: Detects technology stack and enables intelligent routing
    • team-configurator: Creates agent routing rules in AGENTS.md files

  2. Core Agents (agents/core/)

    • Cross-cutting concerns like code archaeology, reviews, performance, and documentation
    • These agents support all technology stacks

  3. Universal Agents (agents/universal/)

    • Framework-agnostic specialists (API, backend, frontend, Tailwind)
    • Fallback when no framework-specific agent exists

  4. Specialized Agents (agents/specialized/)

    • Framework-specific experts organized by technology
    • Subdirectories: laravel/, django/, rails/, react/, vue/

Three-Phase Orchestration Workflow (Main Agent Coordinated)

The main Codex agent implements a human-in-the-loop workflow using the tech-lead-orchestrator:

  1. Research Phase: Tech-lead analyzes requirements and returns structured findings
  2. Approval Gate: Main agent presents findings and waits for human approval
  3. Planning Phase: Main agent creates tasks with TodoWrite based on tech-lead's recommendations
  4. Execution Phase: Main agent invokes specialists sequentially with filtered context

Agent Communication Protocol

Since sub-agents cannot directly communicate or invoke each other:

  • Structured Returns: Each agent returns findings in a parseable format
  • Context Passing: Main agent extracts relevant information from returns
  • Sequential Coordination: Main agent manages the execution flow
  • Handoff Information: Agents include what the next specialist needs in their returns

Example return format:

## Task Completed: API Design
- Endpoints defined: GET/POST/PUT/DELETE /api/users
- Authentication: Bearer token required
- Next specialist needs: This API specification for implementation

Intelligent Routing

The system automatically routes tasks based on:

  1. Project context (detected by project-analyst)
  2. Framework-specific routing when applicable
  3. Universal fallback for unknown stacks
  4. Task requirements and agent expertise

Key Concepts

Agent Definition Format

---
name: agent-name
description: |
  Expertise description with XML examples
  Examples:
  - <example>
    Context: When to use
    user: "Request"
    assistant: "I'll use agent-name"
    <commentary>Why selected</commentary>
  </example>
# tools: omit for all tools, specify for restrictions
---

# Agent Name
System prompt content...

Ambiguity Detection

  • Project-analyst flags uncertainties in analysis
  • Tech-lead presents research findings for approval before execution
  • Agents should identify assumptions needing clarification

Tool Inheritance

  • Omitting tools field = inherit all tools (recommended)
  • Specify tools only for security restrictions
  • Includes WebFetch, MCP tools when available

Development Guidelines

  1. Creating New Agents:

    • Use templates/agent-template.md as starting point
    • Focus on single domain expertise
    • Include 2-3 XML examples
    • Define structured return format

  2. Agent Return Patterns:

    • Always return findings in structured format
    • Include "Next Steps" or "Handoff Information"
    • Specify what context next specialist needs
    • Main agent will parse and coordinate

  3. Testing Agents:

    • Test invocation patterns
    • Verify delegation works correctly
    • Ensure quality of output

Important Files and Patterns

  • docs/orchestration-patterns.md: Detailed three-phase workflow documentation
  • docs/creating-agents.md: Guide for creating new agents
  • docs/best-practices.md: Agent development best practices
  • examples/: Real-world usage examples
  • All agents support human-in-the-loop through the tech-lead's approval gate

Complete Orchestration Example

Here's a full example showing proper agent routing:

User Request:

"Help me build an authentication system for my web app"

Step 1: Tech-Lead Analysis

Main Agent: "I'll use the tech-lead-orchestrator to analyze this request and determine the best approach."

[Invokes tech-lead-orchestrator]

Step 2: Tech-Lead Returns Routing Map

## Agent Routing Map

Task 1: Detect Project Technology
- PRIMARY AGENT: project-analyst
- REASON: Need to identify framework for proper routing

Task 2: Design Authentication Schema  
- PRIMARY AGENT: database-architect
- REASON: Framework-agnostic database design

Task 3: Implement Auth Backend
- PRIMARY AGENT: django-backend-expert
- FALLBACK AGENT: backend-developer
- REASON: Django detected in project

Task 4: Create Auth API Endpoints
- PRIMARY AGENT: django-api-developer
- FALLBACK AGENT: api-architect
- REASON: Django REST Framework patterns

## Available Agents for This Project
- project-analyst
- database-architect  
- django-backend-expert
- django-api-developer
- code-reviewer

## CRITICAL INSTRUCTION
Use ONLY the agents listed above. Do NOT use laravel, rails, or other framework agents.

Step 3: Main Agent Executes Plan

Main Agent: "Based on the tech-lead's routing, I'll now coordinate the implementation:"

1. ✓ Using project-analyst to analyze the codebase
2. ✓ Using database-architect for auth schema design  
3. ✓ Using django-backend-expert for implementation
4. ✓ Using django-api-developer for API endpoints
5. ✓ Using code-reviewer for security audit

[Executes each step with the EXACT agents specified]

What NOT to Do:

❌ "I'll use backend-developer" (when tech-lead specified django-backend-expert)
❌ "I'll use rails-api-developer" (wrong framework)
❌ "I'll skip the tech-lead and choose agents myself" (bypasses routing)

Critical Reminders

  • ALWAYS use tech-lead-orchestrator for multi-step tasks to get proper agent routing
  • FOLLOW the agent routing map exactly - do not improvise
  • USE deep reasoning when coordinating the recommended agents
  • TRUST the tech-lead's expertise in agent selection