ClickUp Integration

Note: This integration is COMPLETELY OPTIONAL. Use any tool (GitHub Issues, Linear, Jira, Notion) or no tool at all. The workflow works entirely with local session files.

Introduction

ClickUp integration is completely optional in the Claude Workflow system. The workflow is designed to function with or without ClickUp, using local session files as the primary source of truth.

Key Point: You can use any project management tool (GitHub Issues, Linear, Jira, Notion) or no tool at all. ClickUp is just one option.

Why ClickUp is Optional

Session Files are Primary

The workflow is built on session files, not ClickUp:

Primary Source of Truth: Session Files
├── clickup_task_{feature}.md  # Business context
├── plan_{feature}.md           # Technical plan
├── progress_{feature}.md       # Progress tracking
└── context_{feature}.md        # Coordination

Optional Integration: ClickUp
└── Task with status and comments for human visibility

Works Without ClickUp

Complete workflow without ClickUp:

1. Requirements → Write to clickup_task_{feature}.md manually
2. Planning → Architect creates plan_{feature}.md (no ClickUp needed)
3. Development → Track in progress_{feature}.md (no ClickUp needed)
4. QA → Document results in context_{feature}.md (no ClickUp needed)
5. Review → Post review to context_{feature}.md (no ClickUp needed)

What you lose:

• Visual task board for stakeholders
• Centralized task management
• Email notifications
• Task dependencies visualization

What you keep:

• Complete development workflow
• Progress tracking
• Agent coordination
• Decision documentation

---

ClickUp Benefits

With ClickUp

✅ Stakeholder Visibility - Non-technical stakeholders see task status ✅ Centralized Management - All tasks in one place ✅ Notifications - Email/app notifications for updates ✅ Dependencies - Visual task relationships ✅ Sprint Planning - Organize tasks by sprint ✅ Time Tracking - Track time spent on tasks ✅ Reporting - Built-in analytics and dashboards

Without ClickUp

✅ Simpler Setup - No API keys or configuration needed ✅ Offline Work - No internet dependency ✅ Faster - No API call latency ✅ Privacy - All data stays local ✅ Free - No subscription costs ✅ Flexible - Use any tool or method you prefer

---

ClickUp Setup (If Using)

Step 1: Create ClickUp Account

1. Go to clickup.com
2. Sign up for free account
3. Create workspace

Step 2: Generate API Token

1. Click profile picture → Settings
2. Navigate to "Apps"
3. Click "Generate" under API Token
4. Copy token (starts with pk_)

Step 3: Get Workspace, Space, and List IDs

Workspace ID:

ClickUp → Settings → Workspace
Copy number from URL: workspace/[WORKSPACE_ID]/settings

Space ID:

Open your Space
Copy from URL: /space/[SPACE_ID]/

List ID:

Open your List
Copy from URL: /list/[LIST_ID]/

Step 4: Update Configuration

Edit .claude/config/agents.md:

## ClickUp Configuration

**API token:** pk_YOUR_TOKEN_HERE
**Workspace ID:** YOUR_WORKSPACE_ID
**Space:** Your Space Name (ID: YOUR_SPACE_ID)
**Default List:** Product Backlog (ID: YOUR_LIST_ID)
**User:** Your Name (ID: YOUR_USER_ID)

Get User ID:

curl -H "Authorization: pk_YOUR_TOKEN" \
  https://api.clickup.com/api/v2/user

Step 5: Test Connection

curl -H "Authorization: pk_YOUR_TOKEN" \
  https://api.clickup.com/api/v2/team

# Should return your workspace details

---

ClickUp Integration Points

Which Agents Write to ClickUp

Only 3 agents write to ClickUp:

Agent	Create Task	Update Status	Create Bugs	Add Comments
Product Manager	✅	❌	❌	✅
QA Tester	❌	✅	✅	✅
Code Reviewer	❌	❌	❌	✅
All Others	❌	❌	❌	❌

Design Rationale:

• 90% fewer API calls compared to having all agents write
• ClickUp for human visibility (status, bugs, approvals)
• Session files for technical detail (progress, decisions)
• Less friction for developers

What Gets Synced to ClickUp

Task Creation (PM):

await clickup.createTask({
  name: "User Profile Edit",
  description: "Business context + Acceptance criteria",
  status: "backlog",
  assignees: [userId]
})

Status Updates (QA):

// When QA starts testing
await clickup.updateTaskStatus(taskId, "qa")

// If bugs found
await clickup.updateTaskStatus(taskId, "backlog")

// When tests pass
// Status stays "qa" for human review

Bug Creation (QA):

await clickup.createSubtask({
  parent_task_id: taskId,
  name: "Bug: Form validation not working",
  description: "Steps to reproduce...",
  status: "backlog",
  assignees: [developerId]
})

Review Comments (Code Reviewer):

await clickup.addComment(taskId, `
  # Code Review: User Profile Edit
  
  ## Summary
  Overall: Approved ✅
  
  ## Details
  ...
`)

What Stays in Session Files

Everything else:

• Technical planning (architect)
• Progress tracking (developers)
• Implementation decisions (all agents)
• Coordination handoffs (all agents)
• Build validation results
• Test execution details

---

ClickUp Workflow

Task Statuses

Typical Status Flow:

backlog → in progress → qa → done
          ↑            ↓
          └─── bugs ───┘

Status Definitions:

• backlog - Task ready for development
• in progress - (Optional) Task being developed
• qa - QA testing in progress
• done - Task complete and merged

Note: Only QA agent changes status to "qa". Developers don't change status.

Task Structure

Standard Task Format:

# User Profile Edit

## 📋 Contexto

**Por qué:** Users need to update information
**Impacto:** Reduces support tickets
**Beneficios:** Improved user autonomy

**Historia de Usuario:**
Como usuario registrado, quiero editar mi perfil...

## ✅ Criterios de Aceptación

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

## 🔄 Cambios de Scope

(Added if scope changes during development)

## 📝 Notas de Desarrollo

(Comments from agents throughout development)

Bug Sub-Tasks

Bug Template:

❌ BUG ENCONTRADO

**Severidad:** Alta / Media / Baja
**Categoría:** Funcional / Visual / Performance / Seguridad

**Pasos para Reproducir:**
1. Navigate to profile edit page
2. Enter invalid email
3. Click save

**Comportamiento Esperado:**
Validation error should display

**Comportamiento Actual:**
Form submits without validation

**Evidencia:**
- Screenshot: [URL]
- Console errors: None

**Bloqueante:** SÍ / NO

---

Alternative Tools

GitHub Issues

Setup:

## GitHub Configuration

**Repository:** owner/repo
**Token:** ghp_xxxxx
**Project:** Development Board
**Label Schema:**
- feature
- bug
- enhancement

Adaptation:

• PM creates issues instead of ClickUp tasks
• QA adds labels instead of status changes
• Code Reviewer adds review as comments

Linear

Setup:

## Linear Configuration

**Workspace:** your-workspace
**API Key:** lin_api_xxxxx
**Team:** Engineering
**Project:** Q1 2025

Adaptation:

• Similar to ClickUp workflow
• Use Linear API instead

Jira

Setup:

## Jira Configuration

**Instance:** your-company.atlassian.net
**Project Key:** PROJ
**API Token:** xxxxx
**Board:** Sprint Board

Adaptation:

• PM creates Jira tickets
• QA transitions tickets
• Code Reviewer adds comments

Notion

Setup:

## Notion Configuration

**Database:** Projects Database
**API Key:** secret_xxxxx
**Properties:**
- Status (select)
- Assignee (person)
- Priority (select)

Adaptation:

• PM creates pages
• QA updates status property
• Code Reviewer adds comments

No Tool

Complete workflow using only session files:

# 1. Create session manually
mkdir .claude/sessions/user-profile-edit

# 2. Copy templates
cp .claude/sessions/TEMPLATE_* .claude/sessions/user-profile-edit/

# 3. Fill in manually or use agents
# PM: Edit clickup_task_user_profile_edit.md manually
# Architect: Launch architect agent
# Developers: Launch developer agents
# QA: Launch QA agent (document results in context file)
# Reviewer: Launch reviewer (document review in context file)

# 4. Track progress in progress_user_profile_edit.md
# Mark [x] as items complete

# 5. Coordinate via context_user_profile_edit.md
# Each agent adds timestamped entries

# 6. Merge when complete
# Human reviews all session files and merges

Benefits:

• Simplest setup
• No external dependencies
• Complete control
• Perfect for solo developers

Drawbacks:

• No visual task board
• No notifications
• Manual tracking
• Less stakeholder visibility

---

ClickUp Best Practices

Task Naming

Good:

User Profile Edit
API Rate Limiting
Email Notifications System

Bad:

Fix stuff
Update code
Make it better

Guidelines:

• Clear, descriptive names
• Use title case
• Be specific
• No jargon

Task Descriptions

Structure:

1. Context - Why this feature matters
2. User Story - As a... I want... so that...
3. Acceptance Criteria - Numbered list
4. Success Metrics - Measurable outcomes

Keep Updated:

• Document scope changes
• Add important decisions
• Link related tasks

Comments

Use for:

• QA test results
• Bug reports
• Code review summaries
• Scope change notifications
• Blocking issues

Don't use for:

• Technical implementation details (use session files)
• Progress tracking (use progress_{feature}.md)
• Agent coordination (use context_{feature}.md)

Status Management

Keep Simple:

• backlog → qa → done
• Let QA handle status changes
• Avoid too many custom statuses

Avoid:

• Developers changing status manually
• Complex status workflows
• Status as progress indicator (use progress file)

---

Migrating Away from ClickUp

Step 1: Disable ClickUp in Config

## ClickUp Configuration

**Status:** DISABLED

# Comment out or remove:
# **API token:** pk_xxxxx
# **Workspace ID:** xxxxx

Step 2: Update Agent Configs

Edit agents that reference ClickUp:

• product-manager.md
• qa-tester.md
• code-reviewer.md

Replace ClickUp interactions with session file updates.

Step 3: Migrate Existing Tasks

# For each active ClickUp task:
# 1. Copy task description to clickup_task_{feature}.md
# 2. Create session folder if needed
# 3. Continue development with session files

Step 4: Use Alternative (Optional)

Switch to GitHub Issues, Linear, or no tool.

---

Troubleshooting

Problem: API token invalid

Solution:

# Regenerate token in ClickUp
# Update .claude/config/agents.md
# Test with curl

Problem: Can't find workspace/space/list

Solution:

• Check you're logged into correct workspace
• Verify you have access to space/list
• Double-check IDs from URLs

Problem: Task creation fails

Solution:

• Verify API token has write permissions
• Check list ID is correct
• Ensure required fields are provided

Problem: Agents writing when shouldn't

Solution:

• Review agent files
• Ensure only PM, QA, Code Reviewer have ClickUp access
• Update agent configurations

---

Next Steps

• Customization - Adapt workflow to your tools
• Configuration - Complete setup guide
• Development Workflow - See ClickUp in action