Agents

Note: This is a PROPOSED agent system. You can customize, add, or remove agents based on your team's needs. See Customization Guide for details.

Introduction

Agents are specialized AI assistants with defined roles, tools, and responsibilities within the development workflow. Each agent handles a specific phase of feature development, from requirements definition to code review.

Key Point: Agents are modular and optional. Use only the agents you need, customize existing ones, or create your own.

📑 Table of Contents

Quick Navigation: Jump to any agent or section below

🤖 Available Agents

#	Agent	Role
1	Product Manager	Business requirements and task creation
2	Architecture Supervisor	Technical planning and coordination
3	Frontend Developer	UI components and client-side logic
4	Backend Developer	Server logic, APIs, and database
5	Plugin Developer	Plugin development and registry integration
6	QA Tester	Test writing, execution, and bug reporting
7	Code Reviewer	Code quality, security, and best practices
8	Documentation Writer	Feature documentation and guides
9	Release Manager	Version management and semantic releases

📚 Additional Sections

• Agent Interaction Patterns - How agents coordinate with each other
• ClickUp Interaction Matrix - ClickUp integration for each agent
• Customizing Agents - How to modify and extend agents
• Best Practices - Tips for effective agent usage

---

Available Agents

1. Product Manager

File: .claude/agents/product-manager.md
Model: Claude Sonnet
Color: Green

Purpose: Translates business needs into structured tasks with clear acceptance criteria.

Responsibilities:

• Analyze business requirements and user needs
• Create ClickUp tasks (or alternative project management tool)
• Define acceptance criteria from business perspective
• Initialize session folder structure
• Provide business context for technical team

Tools:

• Read/Write files
• ClickUp integration (optional)
• Session management

When to Use:

• Starting new features
• Need business perspective on requirements
• Want structured task creation
• Team needs clear acceptance criteria

Example Usage:

# Via command
/init-task Add user profile edit functionality

# Direct agent launch
Launch product-manager agent to create task for: [feature description]

Output:

• ClickUp task with business context (if enabled)
• Session folder with clickup_task_{feature}.md
• Initial context_{feature}.md entry

---

2. Architecture Supervisor

File: .claude/agents/architecture-supervisor.md
Model: Claude Sonnet
Color: Blue

Purpose: Creates detailed technical implementation plans and coordinates development phases.

Responsibilities:

• Analyze business requirements and create technical plans
• Define implementation phases (Backend, Frontend, Integration, QA)
• Create progress tracking templates
• Document technical decisions
• Ensure registry patterns and best practices
• Coordinate between different development phases

Tools:

• Read/Write files
• Codebase analysis
• Session management

When to Use:

• After PM creates requirements
• Need technical planning for complex features
• Want structured implementation guidance
• Coordinating frontend and backend work

Example Usage:

# Usually automatic after PM
/init-task [description]  # PM then Architect run sequentially

# Direct launch
Launch architecture-supervisor to create plan for session: user-profile-edit

Output:

• plan_{feature}.md with 4-phase implementation guide
• progress_{feature}.md template with all checkboxes
• Updated context_{feature}.md with technical decisions

---

3. Frontend Developer

File: .claude/agents/frontend-developer.md
Model: Claude Sonnet
Color: Purple

Purpose: Implements UI components, forms, and client-side functionality.

Responsibilities:

• Implement React/Next.js components
• Create forms with validation
• Integrate with backend APIs
• Add internationalization (i18n)
• Write frontend tests
• Follow design system patterns
• Mark progress in progress_{feature}.md

Tools:

• Read/Write files
• Code editing
• Test execution
• Linting

When to Use:

• Implementing UI components
• Creating forms and interactions
• Frontend-specific features
• After architect creates plan

Example Usage:

/execute-task [feature-name]  # If frontend phase

# Direct launch
Launch frontend-developer to implement Phase 2 of session: user-profile-edit

Output:

• React components
• Form validation
• API integration
• i18n translations
• Frontend tests
• Updated progress_{feature}.md

---

4. Backend Developer

File: .claude/agents/backend-developer.md
Model: Claude Sonnet
Color: Orange

Purpose: Implements server-side logic, APIs, and database operations.

Responsibilities:

• Create database migrations
• Implement API endpoints
• Add server-side validation
• Implement business logic
• Write backend tests
• Follow security best practices
• Mark progress in progress_{feature}.md

Tools:

• Read/Write files
• Code editing
• Database operations
• API testing

When to Use:

• Implementing APIs
• Database schema changes
• Server-side logic
• After architect creates plan

Example Usage:

/execute-task [feature-name]  # If backend phase

# Direct launch
Launch backend-developer to implement Phase 1 of session: user-profile-edit

Output:

• Database migrations
• API endpoints
• Server-side validation
• Backend tests
• Updated progress_{feature}.md

---

5. Plugin Developer

File: .claude/agents/dev-plugin.md
Model: Claude Sonnet
Color: Cyan

Purpose: Develops and maintains plugins within the boilerplate system.

Responsibilities:

• Create plugin structure
• Implement plugin configuration
• Add plugin entities
• Create plugin routes
• Add plugin translations
• Follow plugin patterns
• Mark progress in progress_{feature}.md

Tools:

• Read/Write files
• Code editing
• Plugin registry system

When to Use:

• Creating new plugins
• Extending plugin functionality
• Plugin-specific features
• Plugin system modifications

Example Usage:

# Direct launch
Launch dev-plugin to create new AI assistant plugin

Output:

• Plugin structure
• Plugin configuration
• Plugin components
• Plugin documentation
• Updated progress_{feature}.md

---

6. QA Tester

File: .claude/agents/qa-tester.md
Model: Claude Sonnet
Color: Yellow

Purpose: Validates functionality, creates test reports, and manages bug tracking.

Responsibilities:

• Execute test cases from QA plan
• Validate acceptance criteria
• Test across browsers and devices
• Create bug reports (ClickUp sub-tasks)
• Update task status to "qa"
• Mark test results in progress_{feature}.md
• Document test results in ClickUp comments

Tools:

• Read/Write files
• Browser testing
• ClickUp integration (optional)
• Test execution

When to Use:

• After development phase completes
• Need systematic testing
• Want bug tracking
• Before code review

Example Usage:

# When development is marked complete
Launch qa-tester to test session: user-profile-edit

Output:

• Executed test cases
• Bug sub-tasks in ClickUp (if applicable)
• ClickUp status updated to "qa"
• Test summary in ClickUp comment
• Updated progress_{feature}.md with test results

ClickUp Interaction: ✅ Can write (status changes, bugs, comments)

---

7. Code Reviewer

File: .claude/agents/code-reviewer.md
Model: Claude Sonnet
Color: Red

Purpose: Reviews code quality, security, and adherence to best practices.

Responsibilities:

• Comprehensive code review
• Verify .rules/ compliance
• Security analysis
• Performance evaluation
• Check best practices
• Generate review report
• Post review to ClickUp comments
• Update context_{feature}.md

Tools:

• Read files
• Code analysis
• ClickUp integration (optional)

When to Use:

• After QA approval
• Before merging feature
• Want quality validation
• Need security review

Example Usage:

# After QA phase
Launch code-reviewer to review session: user-profile-edit

Output:

• Comprehensive review document (Spanish)
• ClickUp comment with review
• Notification to assignee
• Updated context_{feature}.md

ClickUp Interaction: ✅ Can write (review comments only)

---

8. Documentation Writer

File: .claude/agents/documentation-writer.md
Model: Claude Sonnet
Color: Teal

Purpose: Creates and updates documentation for features and systems.

Responsibilities:

• Write feature documentation
• Update existing docs
• Follow documentation standards
• Add code examples
• Create diagrams
• Maintain consistency

Tools:

• Read/Write files
• Documentation registry

When to Use:

• New features need documentation
• Existing docs need updates
• API changes
• Architecture changes

Example Usage:

/document-feature user-profile-edit

# Direct launch
Launch documentation-writer to document new API endpoints

Output:

• Markdown documentation
• Code examples
• Diagrams (if needed)
• Updated documentation registry

---

9. Release Manager

File: .claude/agents/release-manager.md
Model: Claude Sonnet
Color: Purple

Purpose: Analyzes changes and creates core version releases with intelligent semantic version determination.

Responsibilities:

• Analyze git commits and session context
• Determine appropriate version bump (MAJOR/MINOR/PATCH)
• Read Semantic Versioning documentation
• Present recommendation with clear justification
• Wait for user approval before executing
• Execute pnpm release commands
• Push version tags to remote repository

Tools:

• Read/Write files
• Bash (git commands, release scripts)
• Session management

When to Use:

• Ready to create a new core release
• Need version analysis and recommendation
• Want automated semantic versioning
• After features/fixes are complete and committed

Example Usage:

# Via command (recommended)
/release

# Explicit version type
/release make a minor release

# Specific version
/release as v2.0.0

# Direct agent launch
Launch release-manager agent to analyze changes and create release

Output:

• Analysis of recent changes
• Version recommendation with justification
• Executed release command
• Git tags pushed to remote
• Completion report with new version

Prerequisites:

• All changes committed (clean git status)
• On main/master branch
• User review of changes

---

Agent Interaction Patterns

Sequential Workflow

Most common pattern - agents run in sequence:

PM → Architect → Developer → QA → Code Reviewer

Each agent reads previous agent's output from session files.

Parallel Workflow

Multiple developers can work in parallel:

Architect
   ↓
   ├─→ Frontend Developer
   └─→ Backend Developer
   ↓
QA (after both complete)

Both update same progress_{feature}.md file.

Iterative Workflow

Development cycles with feedback loops:

Developer → QA → (bugs found) → Developer → QA → Reviewer

QA creates bug sub-tasks, developer fixes, QA retests.

ClickUp Interaction Matrix

Only specific agents write to ClickUp:

Agent	Create Task	Update Status	Create Bugs	Add Comments
Product Manager	✅ Yes	❌ No	❌ No	✅ Yes
Architecture Supervisor	❌ No	❌ No	❌ No	❌ No
Frontend Developer	❌ No	❌ No	❌ No	❌ No
Backend Developer	❌ No	❌ No	❌ No	❌ No
Plugin Developer	❌ No	❌ No	❌ No	❌ No
QA Tester	❌ No	✅ Yes	✅ Yes	✅ Yes
Code Reviewer	❌ No	❌ No	❌ No	✅ Yes
Documentation Writer	❌ No	❌ No	❌ No	❌ No
Release Manager	❌ No	❌ No	❌ No	❌ No

Design Rationale:

• Reduces ClickUp API calls by 90%
• Progress tracked locally in files
• ClickUp for human visibility only
• Developers work in files, not APIs

Customizing Agents

Modify Existing Agent

Edit agent file to change behavior:

<!-- .claude/agents/frontend-developer.md -->

## Custom Responsibilities

Add your team-specific requirements:
- Use Styled Components instead of Tailwind
- Follow company design system
- Create Storybook stories

Create Custom Agent

# Create new agent file
touch .claude/agents/mobile-developer.md

---
name: mobile-developer
description: Develops mobile app features using React Native
model: sonnet
color: pink
tools: Bash, Read, Write, Edit
---

You are an expert mobile developer...

Simplified Agent Set

For solo developers:

# Use only essential agents
.claude/agents/
├── architect.md        # Planning
└── developer.md        # Implementation (combined FE/BE)

Remove Agents

Delete agent files you don't need:

# If not using ClickUp or formal PM process
rm .claude/agents/product-manager.md

# If not doing formal code reviews
rm .claude/agents/code-reviewer.md

Agent Configuration

Agent File Structure

---
name: agent-name
description: When to use this agent
model: sonnet | opus | haiku
color: blue | green | red | yellow | purple | orange
tools: Bash, Read, Write, Edit, ClickUp, etc.
---

# Agent Prompt

You are an expert [role]...

## Responsibilities

- Responsibility 1
- Responsibility 2

## Context

- Important context
- Project patterns

Model Selection

• Sonnet - Balanced (most agents)
• Opus - Complex reasoning (architect, reviewer)
• Haiku - Fast, simple tasks

Tool Access

Limit tools to agent needs:

• Read/Write - File operations
• Edit - Code modifications
• Bash - Terminal commands
• ClickUp - Project management
• TodoWrite - Task management

Best Practices

Agent Usage

✅ DO:

• Launch appropriate agent for the task
• Let agents read session files for context
• Use sequential workflow for handoffs
• Update session files after agent completes

❌ DON'T:

• Skip architect for complex features
• Mix responsibilities between agents
• Bypass session file system
• Manually edit ClickUp when agents should

Agent Coordination

Use Context Files:

Each agent should:

1. Read context_{feature}.md before starting
2. Add timestamped entry when done
3. Include status and next steps
4. Document decisions made

Example Entry:

## [2025-01-19 14:30] Backend Developer

**Status:** ✅ Completado

**Work Summary:**
- Created user_profiles table migration
- Implemented /api/profile endpoints (GET, PUT)
- Added validation for email updates
- Written API tests (95% coverage)

**Decisions:**
- Using separate email_verification table for email changes
- Implementing rate limiting (5 updates per hour)

**Next Step:** Frontend developer can implement UI

Next Steps

• Development Workflow - Learn the complete workflow
• Sessions - Understand session management
• Commands - Use pre-built workflows