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](#simple-tasks)
2. [Complex Features](#complex-features)
3. [Parallel Execution](#parallel-execution)
4. [Sequential Workflows](#sequential-workflows)
5. [Code Generation](#code-generation)
6. [Design and Planning](#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:
```typescript
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:
```typescript
export const UpdatePrioritySchema = z.object({
  priority: z.enum(['low', 'medium', 'high', 'urgent']),
});

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

4. Unit tests:
```typescript
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! 🚀