bigsnarfdude/claude.md

## claude.md

      
    Raw
  

              claude.md
            
          
    Multi-Agent Claude Code Orchestration Instructions

Overview

This document provides instructions for orchestrating multiple Claude Code instances working in parallel. This is not multitasking—this is orchestration: coordinating specialized AI agents to achieve superhuman productivity on complex software projects.

Core Principles

1. Task Decomposition

Break complex work into independent, parallelizable tasks. Each task should:

Have a unique identifier
Specify a type (frontend, backend, testing, docs, refactor, analysis)
Include a clear description of what needs to be done
List dependencies (task IDs that must complete first)
Declare which files will be modified (for conflict prevention)

2. Agent Specialization

Assign agents to specific domains:

Frontend Agent: UI components, styling, client-side logic
Backend Agent: APIs, server logic, database interactions
Testing Agent: Unit tests, integration tests, E2E tests
Documentation Agent: README, API docs, inline comments
Refactoring Agent: Code cleanup, performance optimization
Analysis Agent: Code scanning, dependency analysis, planning

3. File Isolation

Critical Rule: No two agents should modify the same file simultaneously.

Implement file locking before any modifications
Use a dependency graph to understand file relationships
Queue conflicting tasks sequentially rather than in parallel


Workflow Architecture

┌─────────────────────────────────────────────┐
│         Meta-Agent (Orchestrator)           │
│     Analyzes requirements, creates tasks    │
└──────────────────┬──────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────┐
│              Task Queue                      │
│     Prioritized by dependencies             │
└─────┬───────┬───────┬───────┬──────────────┘
      │       │       │       │
      ▼       ▼       ▼       ▼
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ Agent 1 │ │ Agent 2 │ │ Agent 3 │ │ Agent N │
└────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘
     │           │           │           │
     └───────────┴───────────┴───────────┘
                      │
                      ▼
            ┌──────────────────┐
            │  Quality Gate    │
            │  (Tests, Lint)   │
            └──────────────────┘


Task Definition Format

{
  "id": "unique-task-id",
  "type": "frontend|backend|testing|docs|refactor|analysis",
  "description": "Clear description of what needs to be done",
  "dependencies": ["task-id-1", "task-id-2"],
  "files": ["path/to/file1.ts", "path/to/file2.ts"],
  "priority": 1,
  "estimatedComplexity": "low|medium|high"
}

Execution Rules

Before Starting Work


Analyze the full scope before spawning any agents
Map file dependencies to prevent conflicts
Identify parallelizable tasks (no shared file modifications)
Set up quality gates (tests must pass before merging)

During Execution


Acquire file locks before modifying any file
Work in isolation — each agent operates on its designated files only
Report progress to the orchestrator regularly
Release locks immediately after completing modifications
Trigger dependent tasks upon completion

After Completion


Run all affected tests before marking task complete
Validate no conflicts with other agent work
Update documentation if interfaces changed
Report completion with summary of changes


Conflict Prevention Checklist


 Files are locked before modification
 No two agents modify files that import each other
 Shared dependencies are handled sequentially
 All changes pass type checking
 Tests run after each task completion
 Merge conflicts are detected early


Quality Gates

Every agent's work must pass these checks before merging:

Tests Pass: All affected test suites run green
Type Safety: No TypeScript/type errors introduced
No Conflicts: Git merge simulation succeeds
Performance: No significant performance regression
Security: No new vulnerabilities introduced


Resource Management

Scaling Guidelines


Start with 2-3 agents and scale up gradually
Monitor CPU usage (stay under 80%)
Monitor memory (stay under 85%)
Each agent should have dedicated resources

Cost Optimization


Use cheaper models for simple tasks (formatting, simple refactors)
Reserve powerful models for complex reasoning tasks
Batch similar tasks to reduce context-switching overhead


Example: Frontend Refactor Orchestration

Input Requirements

"Convert all class components to functional components with hooks"
Generated Task Plan

[
  {
    "id": "analyze-components",
    "type": "analysis",
    "description": "Scan all components, identify class components, create refactoring plan",
    "dependencies": [],
    "files": []
  },
  {
    "id": "refactor-buttons",
    "type": "frontend",
    "description": "Convert Button components to functional with hooks",
    "dependencies": ["analyze-components"],
    "files": ["components/Button/**/*.tsx"]
  },
  {
    "id": "refactor-forms",
    "type": "frontend",
    "description": "Convert Form components to functional with hooks",
    "dependencies": ["analyze-components"],
    "files": ["components/Form/**/*.tsx"]
  },
  {
    "id": "test-buttons",
    "type": "testing",
    "description": "Update and verify Button component tests",
    "dependencies": ["refactor-buttons"],
    "files": ["__tests__/Button/**/*.test.tsx"]
  },
  {
    "id": "test-forms",
    "type": "testing",
    "description": "Update and verify Form component tests",
    "dependencies": ["refactor-forms"],
    "files": ["__tests__/Form/**/*.test.tsx"]
  },
  {
    "id": "update-docs",
    "type": "docs",
    "description": "Update component documentation for new patterns",
    "dependencies": ["refactor-buttons", "refactor-forms"],
    "files": ["docs/components/**/*.md"]
  }
]
Execution Flow


analyze-components runs first (solo)
refactor-buttons and refactor-forms run in parallel (different files)
test-buttons and test-forms run in parallel after their dependencies
update-docs runs last after all refactoring complete


Communication Protocol

Agent → Orchestrator Messages


TASK_STARTED: Agent began working on task
PROGRESS_UPDATE: Periodic status (% complete, current file)
TASK_COMPLETED: Task finished successfully
TASK_FAILED: Task encountered error (include details)
LOCK_REQUEST: Request file lock
LOCK_RELEASE: Release file lock

Orchestrator → Agent Messages


ASSIGN_TASK: New task assignment with full details
LOCK_GRANTED: File lock approved
LOCK_DENIED: File lock refused (another agent holds it)
ABORT_TASK: Stop current task immediately
PRIORITY_CHANGE: Task priority has changed


Troubleshooting

Common Issues

Deadlock: Two agents waiting for each other's file locks

Solution: Implement lock timeout and retry with backoff

Resource Exhaustion: Too many agents consuming system resources

Solution: Implement resource manager with hard limits

Test Failures: Agent's changes break existing tests

Solution: Run tests incrementally, revert on failure, reassign task

Merge Conflicts: Multiple agents' changes conflict

Solution: Better dependency analysis, stricter file isolation


Best Practices


Start Small: Begin with 2 agents, scale to 10+ as you learn
Observe Everything: Implement comprehensive logging and monitoring
Fail Fast: Detect problems early, revert quickly
Iterate: Refine task decomposition based on results
Document: Keep records of what works and what doesn't


Summary

Multi-agent orchestration transforms software development from sequential work to parallel execution. The keys to success are:

Smart decomposition of tasks
Strict file isolation between agents
Robust quality gates before merging
Real-time observability of all agent activity
Graceful handling of conflicts and failures

This isn't about running more agents—it's about coordinating them effectively.
No results found