Development Workflow

Note: This is a REFERENCE workflow. Adapt phases, skip steps, or add custom processes to match your team. Not all phases are required.

Introduction

The Claude Workflow provides a phased development approach from requirements definition through code review. This structured workflow ensures quality, clarity, and complete documentation throughout the development lifecycle.

Key Point: This workflow is one possible approach. Teams can simplify, modify, or create their own workflow based on size, complexity, and preferences.

Workflow Overview

┌─────────────────────────────────────────────────────────────────┐
│                    DEVELOPMENT WORKFLOW                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Phase 1: Requirements (Product Manager)                        │
│     │                                                            │
│     ├─> Define business requirements                            │
│     ├─> Create ClickUp task (optional)                          │
│     ├─> Initialize session folder                               │
│     └─> Output: clickup_task_{feature}.md, context_{feature}.md │
│                                                                  │
│  Phase 2: Planning (Architecture Supervisor)                    │
│     │                                                            │
│     ├─> Analyze requirements                                    │
│     ├─> Create technical plan                                   │
│     ├─> Define implementation phases                            │
│     └─> Output: plan_{feature}.md, progress_{feature}.md        │
│                                                                  │
│  Phase 3: Implementation (Developers)                           │
│     │                                                            │
│     ├─> Follow technical plan                                   │
│     ├─> Mark progress locally                                   │
│     ├─> Validate build passes                                   │
│     └─> Output: Code changes, updated progress_{feature}.md     │
│                                                                  │
│  Phase 4: QA Testing (QA Tester)                               │
│     │                                                            │
│     ├─> Execute test cases                                      │
│     ├─> Validate acceptance criteria                            │
│     ├─> Create bug reports if needed                            │
│     └─> Output: Test results, bug sub-tasks (if applicable)     │
│                                                                  │
│  Phase 5: Code Review (Code Reviewer)                          │
│     │                                                            │
│     ├─> Review code quality                                     │
│     ├─> Check security and performance                          │
│     ├─> Verify best practices                                   │
│     └─> Output: Review report, approval/feedback                │
│                                                                  │
│  Human: Merge & Deploy                                          │
│     │                                                            │
│     ├─> Review agent outputs                                    │
│     ├─> Make final decisions                                    │
│     ├─> Merge feature branch                                    │
│     └─> Mark task complete                                      │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Phase 1: Requirements Definition

Agent: Product Manager

Purpose: Define business requirements and initialize task tracking.

Responsibilities:

1. Understand business problem and user needs
2. Define clear, measurable acceptance criteria
3. Create task in project management tool (optional)
4. Initialize session folder structure
5. Document business context

Inputs:

• Feature description from stakeholder
• User stories
• Business objectives

Process:

// 1. Read feature request
const featureRequest = "Add user profile edit functionality"

// 2. Analyze requirements
- Who needs this? (users, admins, all roles)
- Why is it needed? (business justification)
- What are success criteria? (measurable outcomes)
- What are edge cases? (validation, security)

// 3. Create ClickUp task (if enabled)
await clickup.createTask({
  name: featureRequest,
  description: `
    ## Business Context
    - Why: Users need to update personal information
    - Impact: Reduces support tickets
    - Value: Improved user autonomy
    
    ## Acceptance Criteria
    1. User can access edit page from dashboard
    2. User can update name, email, and photo
    3. Email changes require verification
    4. Changes save successfully
    5. Validation errors display clearly
  `,
  status: "backlog",
  assignees: [userId]
})

// 4. Initialize session folder
mkdir .claude/sessions/user-profile-edit/

// 5. Create session files
- clickup_task_user_profile_edit.md (metadata + business context)
- context_user_profile_edit.md (coordination log)

// 6. Add PM entry to context file

Outputs:

• Task created in project management (optional)
• Session folder initialized
• Business requirements documented
• Acceptance criteria defined

ClickUp Interaction: ✅ Can write (task creation, comments)

---

Phase 2: Technical Planning

Agent: Architecture Supervisor

Purpose: Create detailed technical implementation plan.

Responsibilities:

1. Analyze business requirements
2. Design technical approach
3. Define implementation phases
4. Create progress tracking template
5. Document technical decisions

Inputs:

• clickup_task_{feature}.md - Business requirements
• context_{feature}.md - Previous agent context
• Existing codebase patterns

Process:

// 1. Read business requirements
const requirements = readFile('clickup_task_user_profile_edit.md')

// 2. Create technical plan
createFile('plan_user_profile_edit.md', `
  ## Technical Summary
  - Approach: RESTful API + React form components
  - Database: Add profile fields to users table
  - Frontend: Form with Zod validation
  - Security: Rate limiting, email verification
  
  ## Phase 1: Backend (Database + API)
  - [ ] Create migration: add profile fields
  - [ ] Implement PUT /api/profile endpoint
  - [ ] Add Zod validation schema
  - [ ] Add rate limiting (5 updates/hour)
  - [ ] Implement email verification for email changes
  - [ ] Write API tests
  
  ## Phase 2: Frontend (UI Components)
  - [ ] Create ProfileEditForm component
  - [ ] Add form validation with Zod
  - [ ] Implement image upload
  - [ ] Add i18n translations (en, es)
  - [ ] Add loading states
  - [ ] Write component tests
  
  ## Phase 3: Integration
  - [ ] End-to-end flow testing
  - [ ] Performance validation
  - [ ] Security review
  
  ## Phase 4: QA Plan
  Functional Tests:
  - Valid profile update
  - Invalid email format
  - Email verification flow
  - Image upload validation
  - Rate limiting enforcement
  
  Visual Tests:
  - Desktop layout (1920x1080)
  - Mobile layout (375x667)
  - Form error states
  - Loading states
`)

// 3. Create progress template
createFile('progress_user_profile_edit.md', `
  # Progress Tracking: User Profile Edit
  
  ## Phase 1: Backend ⏳
  - [ ] Database migration
  - [ ] API endpoint
  - [ ] Validation
  - [ ] Tests
  
  ## Phase 2: Frontend ⏳
  - [ ] Form component
  - [ ] Validation
  - [ ] i18n
  - [ ] Tests
  
  ## Phase 3: Integration ⏳
  - [ ] E2E tests
  - [ ] Performance
  - [ ] Security
  
  ## Phase 4: QA ⏳
  - [ ] Functional tests
  - [ ] Visual tests
  - [ ] Acceptance criteria
  
  ## Phase 5: Code Review ⏳
  - [ ] Quality review
  - [ ] Security review
  - [ ] Best practices
`)

// 4. Update context file
appendToFile('context_user_profile_edit.md', `
  ## [2025-01-19 10:00] Architecture Supervisor
  
  **Status:** ✅ Completed
  
  **Work Summary:**
  - Created technical plan with 4 phases
  - Defined REST API approach
  - Specified database changes
  - Documented security considerations
  
  **Technical Decisions:**
  - Using Zod for validation (both client and server)
  - Rate limiting: 5 updates per hour
  - Email verification for email changes
  
  **Next Step:** Backend developer can begin Phase 1
`)

Outputs:

• plan_{feature}.md - Complete technical plan
• progress_{feature}.md - Progress tracking template
• Updated context_{feature}.md

ClickUp Interaction: ❌ Cannot write (session files only)

---

Phase 3: Implementation

Agents: Frontend Developer, Backend Developer, Plugin Developer

Purpose: Implement feature following technical plan.

Responsibilities:

1. Follow technical plan step-by-step
2. Mark progress locally as work completes
3. Validate build passes
4. Update context with decisions
5. Coordinate with other developers

Inputs:

• plan_{feature}.md - Technical guidance
• progress_{feature}.md - Progress tracking
• context_{feature}.md - Agent coordination
• Existing codebase

Process:

// 1. Read technical plan
const plan = readFile('plan_user_profile_edit.md')

// 2. Implement Phase 1 (Backend)
- Create migration
- Implement API endpoint
- Add validation
- Write tests

// 3. Mark progress locally
updateFile('progress_user_profile_edit.md', `
  ## Phase 1: Backend ✅
  - [x] Database migration
  - [x] API endpoint
  - [x] Validation
  - [x] Tests
`)

// 4. Validate build
$ pnpm build
// Must pass with no errors

// 5. Update context
appendToFile('context_user_profile_edit.md', `
  ## [2025-01-19 14:00] Backend Developer
  
  **Status:** ✅ Completed
  
  **Work Summary:**
  - Created migration: 20250119_add_profile_fields.sql
  - Implemented PUT /api/profile endpoint
  - Added Zod validation schema
  - Wrote 12 API tests (100% coverage)
  
  **Decisions:**
  - Using separate email_verification table
  - Rate limiting via middleware
  
  **Next Step:** Frontend developer can implement UI
`)

// 6. Continue with Phase 2 (Frontend)
- Create form component
- Add validation
- Implement i18n
- Write tests

// 7. Mark frontend progress
updateFile('progress_user_profile_edit.md', `
  ## Phase 2: Frontend ✅
  - [x] Form component
  - [x] Validation
  - [x] i18n
  - [x] Tests
`)

Outputs:

• Implemented code changes
• Updated progress_{feature}.md
• Build validation passing
• Updated context_{feature}.md

ClickUp Interaction: ❌ Cannot write (local progress tracking only)

Build Validation (Mandatory):

# Must pass before considering phase complete
pnpm build

# Fix all TypeScript and linting errors
# Only mark phase complete when build is clean

---

Phase 4: QA Testing

Agent: QA Tester

Purpose: Validate functionality and acceptance criteria.

Responsibilities:

1. Execute test cases from QA plan
2. Validate acceptance criteria
3. Test across devices and browsers
4. Create bug reports for issues
5. Update task status
6. Document test results

Inputs:

• clickup_task_{feature}.md - Acceptance criteria
• plan_{feature}.md - QA test cases (Phase 4)
• progress_{feature}.md - Development progress
• context_{feature}.md - Implementation context
• Live application

Process:

// 1. Read session files
const acceptanceCriteria = readFile('clickup_task_user_profile_edit.md')
const testCases = readFile('plan_user_profile_edit.md').phase4
const devProgress = readFile('progress_user_profile_edit.md')

// 2. Verify development complete
if (!allPhasesComplete(devProgress)) {
  throw new Error('Development phases not complete')
}

// 3. Update ClickUp status
await clickup.updateTaskStatus(taskId, "qa")
await clickup.addComment(taskId, "🧪 Starting QA testing")

// 4. Execute functional tests
const functionalResults = await runTests([
  'Valid profile update',
  'Invalid email format',
  'Email verification flow',
  'Image upload validation',
  'Rate limiting enforcement'
])

// 5. Execute visual tests
const visualResults = await runVisualTests([
  { viewport: 'desktop', size: '1920x1080' },
  { viewport: 'mobile', size: '375x667' },
  { viewport: 'tablet', size: '768x1024' }
])

// 6. Mark test progress locally
updateFile('progress_user_profile_edit.md', `
  ## Phase 4: QA ✅
  - [x] Functional tests (all passed)
  - [x] Visual tests (all passed)
  - [x] Acceptance criteria (all met)
`)

// 7. If bugs found
if (bugsFound) {
  for (const bug of bugs) {
    await clickup.createSubtask({
      parent_task_id: taskId,
      name: `Bug: ${bug.title}`,
      description: bug.description,
      status: 'backlog',
      assignees: [originalDeveloper]
    })
  }
  
  await clickup.updateTaskStatus(taskId, "backlog")
  await clickup.addComment(taskId, `@architect Found ${bugs.length} bugs`)
  
  // Update context
  appendToFile('context_user_profile_edit.md', `
    ## [2025-01-19 16:00] QA Tester
    
    **Status:** ⚠️ Bugs Found
    
    **Test Results:**
    - Functional: 4/5 passed
    - Visual: All passed
    
    **Bugs Created:** ${bugs.length} sub-tasks
    
    **Next Step:** Developer must fix bugs
  `)
} else {
  // 8. All tests passed
  await clickup.addComment(taskId, `
    ✅ QA Approved
    
    **Test Results:**
    - Functional: 5/5 passed
    - Visual: All passed
    - Acceptance Criteria: All met
    
    Ready for code review.
  `)
  
  appendToFile('context_user_profile_edit.md', `
    ## [2025-01-19 16:00] QA Tester
    
    **Status:** ✅ Completed
    
    **Test Results:**
    - All functional tests passed
    - All visual tests passed
    - All acceptance criteria met
    
    **Next Step:** Code reviewer can begin review
  `)
}

Outputs:

• Test execution results
• Bug sub-tasks (if issues found)
• ClickUp status updated
• Test summary in ClickUp comment
• Updated progress_{feature}.md
• Updated context_{feature}.md

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

---

Phase 5: Code Review

Agent: Code Reviewer

Purpose: Validate code quality, security, and best practices.

Responsibilities:

1. Review implementation code
2. Check security vulnerabilities
3. Validate performance
4. Verify best practices
5. Ensure patterns compliance
6. Generate review report

Inputs:

• clickup_task_{feature}.md - Business context
• plan_{feature}.md - Technical plan
• progress_{feature}.md - What was implemented
• context_{feature}.md - Development decisions
• Feature branch code

Process:

// 1. Read session files for context
const businessContext = readFile('clickup_task_user_profile_edit.md')
const technicalPlan = readFile('plan_user_profile_edit.md')
const progress = readFile('progress_user_profile_edit.md')
const context = readFile('context_user_profile_edit.md')

// 2. Checkout feature branch
$ git checkout feature/user-profile-edit

// 3. Comprehensive review
const review = await performReview({
  checks: [
    'Pattern compliance (.rules/)',
    'Security vulnerabilities',
    'Performance issues',
    'Code quality',
    'Test coverage',
    'Documentation',
    'Accessibility'
  ]
})

// 4. Generate review report
const reviewReport = `
  # Code Review: User Profile Edit
  
  ## Summary
  Overall: ${review.overallRating}
  
  ## Security ✅
  - No SQL injection risks
  - Rate limiting implemented
  - Email verification enforced
  
  ## Performance ✅
  - No N+1 queries
  - Proper caching
  - Optimized bundle size
  
  ## Code Quality ✅
  - TypeScript strict mode
  - Proper error handling
  - Clean code principles
  
  ## Issues Found
  ${review.issues.length === 0 ? 'None' : review.issues}
  
  ## Recommendations
  ${review.recommendations}
  
  ## Approval Status
  ${review.approved ? '✅ Approved for merge' : '❌ Changes requested'}
`

// 5. Post review to ClickUp
await clickup.addComment(taskId, reviewReport)
await clickup.addComment(taskId, `@assignedUser Code review complete`)

// 6. Update context
appendToFile('context_user_profile_edit.md', `
  ## [2025-01-19 18:00] Code Reviewer
  
  **Status:** ✅ Completed
  
  **Review Summary:**
  - Security: Approved
  - Performance: Approved
  - Code Quality: Approved
  - Issues Found: None
  
  **Approval:** Ready for merge
  
  **Next Step:** Human decision to merge
`)

Outputs:

• Comprehensive review report
• ClickUp comment with review
• Notification to assignee
• Updated context_{feature}.md

ClickUp Interaction: ✅ Can write (review comments only)

---

ClickUp Interaction Matrix

Summary of which agents can 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

Design Rationale:

• 90% fewer API calls - Progress tracked locally
• ClickUp for visibility - Status changes, bugs, approvals
• Session files for detail - Complete technical history
• Less friction - Developers work in files, not APIs

---

Simplified Workflows

Solo Developer (2-Phase)

1. Planning (self) → 2. Implementation (self)

Skip PM, QA, and code review for simple projects.

Small Team (3-Phase)

1. Requirements (PM) → 2. Implementation (Dev) → 3. Review (Lead)

Skip architect and QA for straightforward features.

Enterprise (6-Phase)

1. Requirements → 2. Architecture → 3. Development → 
4. QA → 5. Security Review → 6. Code Review

Add security review phase for compliance.

Next Steps

• Sessions - Learn session-based task management
• Commands - Use pre-built workflow commands
• Customization - Adapt workflow to your needs