ClickUp Commander

Squad de automação completa do ClickUp via MCP e REST API. 8 agentes especializados, 31 tasks, 3 workflows para setup de workspace, gerenciamento de tasks, sprints, análise de métricas e migração de outras ferramentas.

Visão Geral

O ClickUp Commander é um conjunto de agentes de IA que operam sobre o ClickUp via MCP nativo ou REST API, selecionados automaticamente por ambiente. O squad cobre o ciclo completo de operação de um workspace:

Setup — Estrutura de spaces, folders, lists, views, custom fields e automações do zero
Task Management — Criação individual com qualidade ou bulk operations via CSV
Sprint — Planning com base em velocity histórica, daily digests e retrospectivas estruturadas
Analytics — Cycle time, lead time, throughput, bottlenecks e forecasts com intervalo de confiança
Migração — Trello, Asana e Notion → ClickUp com dry run e integrity check

Integração Dual: MCP + REST API

O agente clickup-integrator detecta automaticamente o ambiente de execução:

Método	Quando usar	Setup necessário
MCP (`mcp__clickup__*`)	Operações simples e interativas	Zero — nativo no Claude Code
REST API	Bulk operations, webhooks, automações	`CLICKUP_API_KEY` no ambiente

Os agentes de negócio nunca chamam o ClickUp diretamente — tudo passa pelo integrator. O método utilizado é transparente para o usuário.

Agentes

#	Ícone	ID	Título	Tier
1	🎯	`clickup-chief`	ClickUp Commander Chief	Orchestrator
2	🏗️	`workspace-architect`	Workspace Architect	Tier 0
3	✅	`task-creator`	Task Creator	Tier 1
4	⚙️	`task-engine`	Task Engine	Tier 1
5	🏃	`sprint-master`	Sprint Master	Tier 1
6	📊	`data-analyst`	Data Analyst	Tier 2
7	🚚	`workspace-migrator`	Workspace Migrator	Tier 2
8	🔌	`clickup-integrator`	Integration Dispatcher	Transport

Escopo por Agente

workspace-architect (Tier 0) Recebe briefing e projeta a hierarquia completa do workspace: Spaces → Folders → Lists → Views → Custom Fields → Status sets. Executa a criação via clickup-integrator.

task-creator (Tier 1) Criação de tasks individuais com qualidade: título verb-first, description com contexto, acceptance criteria, estimativas, dependências, assignees e tags. Garante o contrato completo de cada task.

task-engine (Tier 1) Operações em volume: bulk create a partir de CSV, bulk update de campos em massa, setup de automation rules, criação de templates e geração de checklists em lote. Usa REST API batch — nunca MCP loop para 10+ tasks.

sprint-master (Tier 1) Ciclo completo de sprint: planning com cálculo de capacidade (85% rule), daily digest automatizado, sprint review report, retrospectiva Start/Stop/Continue e velocity tracking histórico.

data-analyst (Tier 2) Transforma dados brutos em decisões. Calcula cycle time, lead time, throughput, WIP, completion rate e blocked rate. Identifica bottlenecks com root cause. Gera forecasts de conclusão com intervalo de confiança. Produz health score 0–100 do workspace.

workspace-migrator (Tier 2) Migração de Trello (JSON), Asana (CSV) e Notion (CSV) para ClickUp. Protocolo: Validate → Map → DryRun → Execute → Verify. Nunca executa sem dry run aprovado. Preserva IDs originais como custom field para rastreabilidade.

clickup-integrator (Transport) Camada de abstração entre os agentes de negócio e o ClickUp. Detecta MCP vs API na inicialização, faz fallback silencioso, controla rate limiting (80 req/min) e retorna respostas brutas da API para o agente chamador.

Pipeline — Fluxo Principal

User Input
    ↓
clickup-chief (valida inputs, identifica intenção, roteia)
    ↓
workspace-architect (Tier 0 — design de estrutura)
    ↓               ↓               ↓
task-creator    task-engine    sprint-master    (Tier 1 — execução em paralelo)
    ↓               ↓               ↓
        data-analyst       workspace-migrator   (Tier 2 — análise/migração)
    ↓
clickup-chief (consolida output final)
    ↓ [todos os agentes passam por]
clickup-integrator (Transport — invisível para o usuário)
    ↓               ↓
  MCP           REST API

Workflows Disponíveis

Workflow	Entrada	Saída	Duração típica
`new-project-kickoff`	Briefing do projeto	Workspace completo + backlog inicial + Sprint 1	~20 min
`sprint-cycle`	Backlog + capacidade do time	Sprint configurado → daily digests → review → retrospectiva	Por sprint
`workspace-health-audit`	`workspace_id`	Health score + top 3 problemas + plano de ação	~15 min

Comandos Rápidos

Comando	Agente	Descrição
`*setup [briefing]`	workspace-architect	Cria workspace completo a partir do briefing
`*create-task [spec]`	task-creator	Cria task individual com contrato completo
`*bulk-create [file.csv]`	task-engine	Cria tasks em lote a partir de CSV
`*plan [team, capacity, dates]`	sprint-master	Planeja sprint com base em velocity histórica
`*daily`	sprint-master	Gera daily standup digest
`*metrics [workspace_id]`	data-analyst	Analisa métricas do workspace
`*bottleneck [list_id]`	data-analyst	Identifica gargalos com root cause
`*forecast [list_id]`	data-analyst	Projeta data de conclusão com intervalos de confiança
`*migrate-trello [file.json]`	workspace-migrator	Migra export do Trello
`*migrate-asana [file.csv]`	workspace-migrator	Migra export do Asana
`*migrate-notion [file.csv]`	workspace-migrator	Migra database do Notion
`*health-audit`	data-analyst	Auditoria completa do workspace

Inputs Obrigatórios por Operação

Setup de Workspace

Campo	Tipo	Obrigatório
Briefing do projeto	texto livre	Sim
Nome dos spaces/áreas	lista	Sim
Membros do time	lista de emails ou IDs	Não
Tipo de fluxo (kanban / scrum / custom)	enum	Não

Sprint Planning

Campo	Tipo	Obrigatório
`backlog_list_id`	string	Sim
`sprint_duration_days`	number	Sim
`team_capacity`	mapa membro → horas	Sim
`sprint_name`	string	Não (gerado automaticamente)

Bulk Create de Tasks

Campo	Tipo	Obrigatório
Arquivo CSV ou JSON	file	Sim
`target_list_id`	string	Sim
`field_mapping`	objeto	Não (inferido automaticamente)

Migração

Campo	Tipo	Obrigatório
Arquivo export da ferramenta	file	Sim
`target_workspace_id`	string	Sim
`dry_run`	boolean	Não (default: true)

Output Entregue

Setup completo:

Estrutura de spaces/folders/lists criada
Views configuradas por tipo de lista
Custom fields e status sets aplicados
IDs de todas as entidades criadas (referência para operações futuras)

Sprint:

Sprint criado com tasks selecionadas até 85% da capacidade
Daily digest com tasks por status, blockers e burndown
Review report com completion rate e velocity
Retrospectiva com ações atribuídas a owners

Analytics:

Health score 0–100 com pesos por dimensão
Métricas benchmarkadas contra referências do setor
Top 3 findings com root cause e recomendação + impacto esperado quantificado
Forecast com cenários otimista/realista/pessimista e premissas documentadas

Migração:

Dry run com preview de todas as entidades a criar antes de executar
Integrity check: source_count = created_count
IDs originais preservados como custom field (trello_id, asana_id, notion_id)
Relatório com warnings sobre dados não migráveis

Mapeamento de Campos — Migração

Trello → ClickUp

Trello	ClickUp
Board	Space
List	List
Card	Task
Checklist	Task Checklist
Label	Tag
Members	Assignees
Comments	Task Comments

Asana → ClickUp

Asana	ClickUp
Project	List
Section	Folder
Task	Task
Subtask	Subtask
Custom Fields	Custom Fields (mapeamento manual)
Dependencies	Dependencies (blocking/waiting)

Notion → ClickUp

Notion	ClickUp
Database	List
Page	Task
Properties	Custom Fields
Sub-pages	Subtasks
Multi-select	Tags
Person property	Assignee

Instalação

bash

squads add clickup-commander

Configuração de Integração

MCP (recomendado — zero configuração): O squad detecta mcp__clickup__* automaticamente se o MCP server do ClickUp estiver ativo no Claude Code.

REST API (fallback):

bash

export CLICKUP_API_KEY="pk_xxxxx"

Obtenha a chave em: ClickUp → Settings → Apps → API Token.

Estrutura do Squad

squad-clickup/
├── squad.yaml
├── config.yaml
├── README.md
│
├── agents/
│   ├── clickup-chief.md           # Orchestrator
│   ├── workspace-architect.md     # Tier 0 — Design de estrutura
│   ├── task-creator.md            # Tier 1 — Qualidade de tasks individuais
│   ├── task-engine.md             # Tier 1 — Bulk operations
│   ├── sprint-master.md           # Tier 1 — Ciclo de sprint
│   ├── data-analyst.md            # Tier 2 — Métricas e insights
│   ├── workspace-migrator.md      # Tier 2 — Migração de ferramentas
│   └── clickup-integrator.md      # Transport — MCP vs REST API
│
├── tasks/
│   ├── # Integração / Transport
│   ├── detect-integration-method.md
│   ├── authenticate-api.md
│   ├── validate-permissions.md
│   ├── # Setup
│   ├── setup-workspace-from-scratch.md
│   ├── create-space-structure.md
│   ├── configure-custom-fields.md
│   ├── configure-views.md
│   ├── configure-automation.md
│   ├── configure-webhook.md
│   ├── # Task Creator
│   ├── create-single-task.md
│   ├── create-task-from-template.md
│   ├── create-task-with-dependencies.md
│   ├── create-subtask-tree.md
│   ├── create-recurring-task.md
│   ├── assign-and-prioritize.md
│   ├── # Task Engine
│   ├── bulk-create-tasks.md
│   ├── bulk-update-tasks.md
│   ├── create-task-template.md
│   ├── generate-batch-checklists.md
│   ├── setup-automation-rule.md
│   ├── # Sprint
│   ├── sprint-planning.md
│   ├── daily-standup-digest.md
│   ├── sprint-review-report.md
│   ├── retrospective-template.md
│   ├── velocity-tracker.md
│   ├── # Analytics
│   ├── analyze-workspace-metrics.md
│   ├── generate-bottleneck-report.md
│   ├── forecast-completion.md
│   ├── # Migração
│   ├── migrate-from-trello.md
│   ├── migrate-from-asana.md
│   └── migrate-from-notion.md
│
├── workflows/
│   ├── new-project-kickoff.md
│   ├── sprint-cycle.md
│   └── workspace-health-audit.md
│
├── templates/
│   ├── workspace-output.md
│   ├── task-output.md
│   └── report-output.md
│
└── config/
    ├── clickup-api-rules.md
    ├── clickup-mcp-rules.md
    └── workspace-standards.md

Pré-requisitos

Requisito	Versão	Obrigatório
AIOS CLI	2.1.0+	Sim
ClickUp account	qualquer plano	Sim
ClickUp MCP server	qualquer	Condicional (ou API key)
`CLICKUP_API_KEY`	—	Condicional (se sem MCP)

Licença

MIT

ClickUp Commander v1.0.0

clickup commander