ColaFlow/.claude/USAGE_EXAMPLES.md

ColaFlow Agent System - Usage Examples

This document provides practical examples of how to use the ColaFlow multi-agent system.

Table of Contents

1. Simple Tasks
2. Complex Features
3. Parallel Execution
4. Sequential Workflows
5. Code Generation
6. Design and Planning

---

Simple Tasks

Example 1: Generate a PRD

Your Request:

Generate a PRD for the "AI Task Auto-Creation" feature

What Happens:

Main Coordinator → Calls product-manager agent

Sub Agent Response:
- Analyzes the feature requirements
- Generates complete PRD document with:
  - Background & Goals
  - Requirements
  - Acceptance Criteria
  - Timeline

Main Coordinator → Returns integrated PRD to you

---

Example 2: Design System Architecture

Your Request:

Design the architecture for MCP Server integration

What Happens:

Main Coordinator → Calls architect agent

Sub Agent Response:
- Designs MCP Server architecture
- Defines Resources and Tools
- Plans security mechanisms (diff preview)
- Recommends tech stack

Main Coordinator → Returns architecture design to you

---

Complex Features

Example 3: Implement Complete Feature

Your Request:

Implement the Kanban board drag-and-drop feature with the following requirements:
- Users can drag tasks between columns
- Status updates automatically
- Optimistic UI updates with rollback on error
- Works smoothly with 100+ tasks

What Happens:

Main Coordinator analyzes and creates execution plan:

Step 1: Architecture (architect agent)
→ Design component architecture
→ Define state management approach
→ Plan API contract

Step 2: Requirements (product-manager agent)
→ Define acceptance criteria
→ Specify edge cases
→ Set performance requirements

Step 3: Backend (backend agent)
→ Implement PATCH /api/issues/:id/status endpoint
→ Add optimistic locking
→ Write unit tests

Step 4: Frontend (frontend agent)
→ Implement drag-and-drop with react-beautiful-dnd
→ Add optimistic UI updates
→ Handle error rollback
→ Implement virtualization for performance

Step 5: Testing (qa agent)
→ Write E2E tests for drag-and-drop
→ Performance test with 100+ tasks
→ Test error scenarios

Step 6: UX (ux-ui agent)
→ Design drag feedback animations
→ Define success/error states

Main Coordinator → Integrates all outputs and presents complete implementation

---

Parallel Execution

Example 4: Kickoff New Project Phase

Your Request:

We're starting M2 (MCP Server implementation). Prepare the team.

What Happens (Parallel Execution):

Main Coordinator calls multiple agents in PARALLEL:

┌─────────────────────────────────────────────────────┐
│ Task 1: product-manager                             │
│ → Create M2 project plan                            │
│ → Define milestones and deliverables                │
│                                                      │
│ Task 2: architect                                   │
│ → Design detailed MCP Server architecture           │
│ → Define API specifications                         │
│                                                      │
│ Task 3: backend                                     │
│ → Set up project structure for MCP Server           │
│ → Create initial boilerplate code                   │
│                                                      │
│ Task 4: qa                                          │
│ → Draft M2 test strategy                            │
│ → Define quality gates                              │
└─────────────────────────────────────────────────────┘

All execute simultaneously ⚡

Main Coordinator → Waits for all to complete → Integrates results

How to trigger parallel execution: Main coordinator makes multiple Task tool calls in a single message.

---

Sequential Workflows

Example 5: Bug Investigation and Fix

Your Request:

The login API is returning 500 errors intermittently

What Happens (Sequential Execution):

Step 1: qa agent
→ Investigate error logs
→ Identify error pattern
→ Reproduce the issue
→ Reports: "Race condition in session store"

↓ (Wait for results)

Step 2: backend agent (based on QA findings)
→ Reviews session store implementation
→ Identifies root cause
→ Implements fix with proper locking
→ Writes test to prevent regression

↓ (Wait for results)

Step 3: qa agent (verification)
→ Runs regression tests
→ Verifies fix works
→ Confirms no new issues introduced
→ Reports: "Fix verified, ready for deployment"

Main Coordinator → Reports complete investigation and fix

---

Code Generation

Example 6: Generate API Endpoint

Your Request:

Create a REST API endpoint for updating issue priority:
- PATCH /api/issues/:id/priority
- Validate priority (low, medium, high, urgent)
- Log the change in audit trail
- Return updated issue

What Happens:

Main Coordinator → Calls backend agent

Backend Agent Generates:

1. Controller code:
```typescript
@Patch(':id/priority')
async updatePriority(
  @Param('id') id: string,
  @Body() dto: UpdatePriorityDto,
  @CurrentUser() user: User
): Promise<Issue> {
  return this.issueService.updatePriority(id, dto.priority, user.id);
}

2. Service code:

async updatePriority(
  id: string,
  newPriority: Priority,
  userId: string
): Promise<Issue> {
  const issue = await this.findById(id);
  const oldPriority = issue.priority;

  issue.priority = newPriority;
  const updated = await this.issueRepository.save(issue);

  await this.auditService.log({
    entityType: 'Issue',
    entityId: id,
    action: 'UPDATE_PRIORITY',
    userId,
    changes: { priority: { from: oldPriority, to: newPriority } },
  });

  return updated;
}

3. DTO validation:

export const UpdatePrioritySchema = z.object({
  priority: z.enum(['low', 'medium', 'high', 'urgent']),
});

export type UpdatePriorityDto = z.infer<typeof UpdatePrioritySchema>;

4. Unit tests:

describe('updatePriority', () => {
  it('should update priority and log audit', async () => {
    const updated = await service.updatePriority('issue-1', 'urgent', 'user-1');
    expect(updated.priority).toBe('urgent');
    expect(auditService.log).toHaveBeenCalled();
  });
});

Main Coordinator → Returns complete, production-ready code

---

## Design and Planning

### Example 7: Design Sprint Planning UI

**Your Request**:

Design the Sprint Planning interface where PM can:

• Create new sprint
• Drag tasks from backlog to sprint
• Set sprint goals and dates
• View capacity vs planned work

**What Happens**:

Main Coordinator coordinates design process:

Step 1: product-manager agent → Define user stories → Specify acceptance criteria → Identify edge cases

Step 2: ux-ui agent → Create user flow diagram → Design wireframes → Create high-fidelity mockups in Figma → Define interaction states → Specify animations

Delivers:

• User persona analysis
• User journey map
• Low-fidelity wireframes
• High-fidelity Figma mockups
• Component specifications
• Interaction guidelines

Step 3: frontend agent (optional, if implementation requested) → Reviews designs → Identifies technical considerations → Suggests component architecture

Main Coordinator → Integrates design deliverables

---

## Example 8: Full Feature Development Lifecycle

**Your Request**:

Implement the "AI Daily Report Generation" feature from start to finish

**What Happens** (Full lifecycle):

Phase 1: PLANNING (Parallel) ┌─────────────────────────────────────────────────────┐ │ product-manager → Write PRD │ │ architect → Design architecture │ │ ux-ui → Design UI mockups │ └─────────────────────────────────────────────────────┘

↓

Phase 2: IMPLEMENTATION (Sequential + Parallel)

Step 1: ai agent → Design prompt template for daily reports → Implement report generation logic → Set up caching strategy

Step 2a: backend agent (parallel with 2b) → Create POST /api/reports/daily endpoint → Integrate AI service → Implement diff preview for AI reports

Step 2b: frontend agent (parallel with 2a) → Create DailyReport component → Add "Generate Report" button → Display AI-generated report with approval UI

↓

Phase 3: QUALITY ASSURANCE qa agent → Write E2E tests for report generation → Test AI prompt quality → Verify approval workflow → Performance test

↓

Phase 4: DELIVERY product-manager agent → Update documentation → Prepare release notes → Update project timeline

Main Coordinator → Presents complete feature ready for deployment

---

## Tips for Effective Usage

### 1. Be Specific
❌ Bad: "Make the app better"
✅ Good: "Optimize the Kanban board rendering for 100+ tasks using virtualization"

### 2. Provide Context
❌ Bad: "Add authentication"
✅ Good: "Add JWT-based authentication to our NestJS backend, following the architecture in product.md"

### 3. Break Down Large Requests
❌ Bad: "Build the entire ColaFlow system"
✅ Good: "Let's start with M1. First, implement the core project/task data models"

### 4. Leverage Parallel Execution
When tasks are independent, request them together:
✅ "Prepare for M2: Create project plan, design MCP architecture, and draft test strategy"

### 5. Review and Iterate
After receiving output from agents:
- Review the deliverables
- Ask for clarifications or modifications
- Request additional details if needed

---

## Common Workflows

### Workflow 1: New Feature
1. `product-manager` → PRD
2. `architect` → Architecture design
3. `backend` + `frontend` (parallel) → Implementation
4. `qa` → Testing
5. `product-manager` → Documentation

### Workflow 2: Bug Fix
1. `qa` → Reproduce and diagnose
2. `backend` or `frontend` → Fix implementation
3. `qa` → Verify fix

### Workflow 3: Performance Optimization
1. `qa` → Performance profiling
2. `architect` → Optimization strategy
3. `backend`/`frontend` → Implement optimizations
4. `qa` → Verify improvements

### Workflow 4: UI/UX Enhancement
1. `ux-ui` → Design improvements
2. `frontend` → Implementation
3. `qa` → Usability testing

---

## Getting Help

If you're unsure which agent to use, just ask the main coordinator:

"I need to [describe your goal]. Which agents should work on this?"

The main coordinator will create an execution plan and route tasks appropriately.

Happy coding with the ColaFlow agent system! 🚀