Multi-Agent Workflow System for Claude Code

A sophisticated multi-agent system designed for Claude Code to manage complex development workflows, particularly optimized for GPU acceleration projects like OpenFOAM.

🚀 Quick Start

Installation

1. Clone this repository or copy the agent files to your project:

# If in existing project, copy the agents directory
cp -r agents/ your-project/
cp -r .claude/ your-project/

2. Run the setup script:

python setup_agents.py

3. Test the installation:

python setup_agents.py --test

Basic Usage

Interactive Mode

python orchestrator.py --interactive

Start a Workflow

python orchestrator.py --workflow "Implement GPU acceleration for k-epsilon model"

Check Status

python orchestrator.py --status

📋 System Overview

Architecture

The system consists of four specialized agents, each with distinct responsibilities:

┌──────────────┐
│   Manager    │ ← Coordinates workflow
└──────┬───────┘
       │
   ┌───┴────┬────────┬──────────┐
   ▼        ▼        ▼          ▼
┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐
│Planner│ │Actor │ │Testor│ │Logger│
└──────┘ └──────┘ └──────┘ └──────┘

Agent Roles

🎯 Manager Agent

• Purpose: Workflow coordination and task delegation
• Responsibilities:
  • Decompose high-level tasks into subtasks
  • Assign tasks to appropriate agents
  • Track progress and manage state
  • Coordinate multi-agent workflows
• Output: doc/manager/todos.md, workflow_status.json

📝 Planner Agent

• Purpose: Create detailed plans and strategies
• Responsibilities:
  • Analyze requirements and constraints
  • Create step-by-step implementation plans
  • Design test strategies
  • Identify dependencies and risks
• Output: doc/planner/current_plan.md, test_strategy.md

⚙️ Actor Agent

• Purpose: Strict execution of detailed plans
• Responsibilities:
  • Validate plan executability
  • Execute commands exactly as specified
  • Implement code according to specifications
  • Document all actions taken
• Output: doc/actor/execution_details.md, implementation_log.md

🧪 Testor Agent

• Purpose: Rigorous testing and validation
• Responsibilities:
  • Execute test plans
  • Run performance benchmarks
  • Compare results (CPU vs GPU)
  • Generate test reports
• Output: doc/testor/test_report.md, performance_metrics.json

💬 Slash Commands

Use these commands in Claude Code or via the orchestrator:

Manager Commands

/manager start-workflow "description" [priority=high] [category=gpu]
/manager status
/manager assign <task_id> to <agent>

Planner Commands

/planner create-plan "description"
/planner optimize-plan <plan_id>
/planner test-strategy "target"

Actor Commands

/actor execute <plan_id>
/actor validate <plan_id>

Testor Commands

/testor run <test_id>
/testor benchmark <target>

📁 Directory Structure

project/
├── agents/                 # Agent implementation
│   ├── __init__.py
│   ├── base.py            # Base agent class
│   ├── state_manager.py   # State persistence
│   ├── command_router.py  # Command routing
│   ├── logger.py          # Logging utility
│   ├── manager/           # Manager agent
│   ├── planner/           # Planner agent
│   ├── actor/             # Actor agent
│   └── testor/            # Testor agent
├── .claude/               # Claude Code configuration
│   ├── commands/          # Slash command definitions
│   └── config.json        # System configuration
├── .agent-state/          # Runtime state (gitignored)
│   ├── current_workflow.json
│   ├── task_queue.json
│   └── session_logs/
├── doc/                   # Agent documentation
│   ├── manager/           # Manager outputs
│   ├── planner/           # Planner outputs
│   ├── actor/             # Actor outputs
│   └── testor/            # Testor outputs
├── orchestrator.py        # Main orchestrator
├── setup_agents.py        # Setup script
└── README.md             # This file

🔄 Workflow Example

Here's a complete workflow for implementing GPU acceleration:

1. Start the Workflow

/manager "Implement GPU-accelerated k-epsilon turbulence model" priority=high

2. Manager Creates Workflow

• Decomposes task into subtasks
• Creates TODO list in doc/manager/todos.md
• Assigns planning task to Planner

3. Planner Creates Plan

• Analyzes requirements
• Creates implementation steps
• Generates test strategy
• Outputs to doc/planner/current_plan.md

4. Manager Reviews and Assigns

• Reviews plan completeness
• Assigns execution to Actor
• Updates workflow status

5. Actor Executes

• Validates plan is executable
• Executes commands step by step
• Documents actions in doc/actor/execution_details.md

6. Testor Validates

• Runs test plan from Planner
• Compares CPU vs GPU results
• Generates report in doc/testor/test_report.md

7. Manager Completes

• Reviews test results
• Updates workflow status
• Documents completion

⚙️ Configuration

Edit .claude/config.json to customize:

{
  "agents": {
    "manager": {
      "auto_decompose": true,
      "max_subtasks": 10
    },
    "actor": {
      "safe_mode": true,
      "require_validation": true
    },
    "testor": {
      "default_iterations": 3,
      "performance_tracking": true
    }
  }
}

🔧 Advanced Features

State Persistence

The system maintains state across sessions:

• Current workflow status
• Task queue
• Agent execution history
• Performance metrics

Error Recovery

• Automatic task retry on failure
• Graceful degradation
• Comprehensive error logging
• Rollback capabilities

Performance Tracking

• Execution time metrics
• Resource usage monitoring
• Agent performance statistics
• Workflow optimization suggestions

🐛 Troubleshooting

Common Issues

1. Import Errors

   # Ensure Python path includes project root
   export PYTHONPATH=$PYTHONPATH:$(pwd)

2. Permission Errors

   # Make scripts executable
   chmod +x orchestrator.py setup_agents.py

3. State Corruption

   # Reset system state
   python setup_agents.py --reset

Debug Mode

Enable detailed logging:

# In .claude/config.json
"workflow": {
  "logging_level": "DEBUG"
}

🚢 Deployment

GitHub Transfer

1. Commit the agent system:

git add agents/ .claude/ orchestrator.py setup_agents.py
git commit -m "Add multi-agent workflow system"
git push

2. On new machine:

git clone <repository>
cd <project>
python setup_agents.py

Docker Integration

For projects using Docker (like OpenFOAM):

# Agents automatically use Docker commands
/actor execute docker_build_plan

📊 Metrics and Reporting

The system tracks:

• Workflow completion rates
• Agent execution counts
• Task success/failure rates
• Performance benchmarks
• Time-to-completion metrics

Access metrics:

python orchestrator.py --status | jq '.metrics'

🤝 Contributing

Adding New Agents

1. Create new agent class inheriting from BaseAgent
2. Implement required methods: execute(), validate_task()
3. Add to orchestrator agent registry
4. Create command patterns in command_router.py
5. Add slash command documentation

Extending Functionality

• Custom workflow templates in agents/*/templates/
• New command patterns in CommandRouter
• Additional state tracking in StateManager
• Enhanced logging in AgentLogger

📜 License

This multi-agent system is designed for use with Claude Code and is provided as-is for educational and development purposes.

🙏 Acknowledgments

Designed specifically for Claude Code to enhance development workflow management, particularly for complex projects like GPU acceleration of computational fluid dynamics software.

📞 Support

For issues or questions:

1. Check the troubleshooting section
2. Review agent logs in .agent-state/session_logs/
3. Run system test: python setup_agents.py --test
4. Create an issue with detailed logs and configuration