@llodev/pm-tasks-clickup 0.0.0-pr-130-7078a2a

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +196 -0
  3. package/SKILL.md +258 -0
  4. package/anti-patterns/clickup.md +73 -0
  5. package/dist/adapter.d.ts +39 -0
  6. package/dist/adapter.d.ts.map +1 -0
  7. package/dist/adapter.js +83 -0
  8. package/dist/adapter.js.map +1 -0
  9. package/dist/bin/init.d.ts +3 -0
  10. package/dist/bin/init.d.ts.map +1 -0
  11. package/dist/bin/init.js +20 -0
  12. package/dist/bin/init.js.map +1 -0
  13. package/dist/doctor-cli.d.ts +27 -0
  14. package/dist/doctor-cli.d.ts.map +1 -0
  15. package/dist/doctor-cli.js +315 -0
  16. package/dist/doctor-cli.js.map +1 -0
  17. package/dist/env.d.ts +6 -0
  18. package/dist/env.d.ts.map +1 -0
  19. package/dist/env.js +11 -0
  20. package/dist/env.js.map +1 -0
  21. package/dist/envelope.d.ts +44 -0
  22. package/dist/envelope.d.ts.map +1 -0
  23. package/dist/envelope.js +95 -0
  24. package/dist/envelope.js.map +1 -0
  25. package/dist/errors.d.ts +30 -0
  26. package/dist/errors.d.ts.map +1 -0
  27. package/dist/errors.js +60 -0
  28. package/dist/errors.js.map +1 -0
  29. package/dist/estimation.d.ts +20 -0
  30. package/dist/estimation.d.ts.map +1 -0
  31. package/dist/estimation.js +40 -0
  32. package/dist/estimation.js.map +1 -0
  33. package/dist/index.d.ts +5 -0
  34. package/dist/index.d.ts.map +1 -0
  35. package/dist/index.js +3 -0
  36. package/dist/index.js.map +1 -0
  37. package/dist/init-api.d.ts +67 -0
  38. package/dist/init-api.d.ts.map +1 -0
  39. package/dist/init-api.js +271 -0
  40. package/dist/init-api.js.map +1 -0
  41. package/dist/init-flow.d.ts +27 -0
  42. package/dist/init-flow.d.ts.map +1 -0
  43. package/dist/init-flow.js +206 -0
  44. package/dist/init-flow.js.map +1 -0
  45. package/dist/status-map.d.ts +31 -0
  46. package/dist/status-map.d.ts.map +1 -0
  47. package/dist/status-map.js +38 -0
  48. package/dist/status-map.js.map +1 -0
  49. package/dist/status.d.ts +17 -0
  50. package/dist/status.d.ts.map +1 -0
  51. package/dist/status.js +21 -0
  52. package/dist/status.js.map +1 -0
  53. package/dist/transport-clickup.d.ts +99 -0
  54. package/dist/transport-clickup.d.ts.map +1 -0
  55. package/dist/transport-clickup.js +676 -0
  56. package/dist/transport-clickup.js.map +1 -0
  57. package/docs/i18n/README.es-ES.md +196 -0
  58. package/docs/i18n/README.pt-BR.md +196 -0
  59. package/i18n/en-US.json +62 -0
  60. package/i18n/es-ES.json +62 -0
  61. package/i18n/pt-BR.json +62 -0
  62. package/manifest.json +14 -0
  63. package/package.json +64 -0
  64. package/references/autonomous.md +85 -0
  65. package/references/estimation.md +115 -0
  66. package/references/operations.md +128 -0
  67. package/schemas/config.json +140 -0
@@ -0,0 +1,62 @@
1
+ {
2
+ "header": "pm-tasks-clickup init",
3
+ "workspacePrompt": "Selecione o espaço de trabalho do ClickUp:",
4
+ "noWorkspace": "Nenhum espaço de trabalho selecionado. Saindo.",
5
+ "listsPrompt": "Selecione as listas do ClickUp que serão usadas:",
6
+ "noList": "Nenhuma lista selecionada. Saindo.",
7
+ "wipStatusPrompt": "Selecione o status de trabalho em andamento da lista {list}:",
8
+ "noWipStatus": "A lista {list} não tem um status para trabalho em andamento, então wip fica sem valor. task.move para wip falha nas tarefas dela até você criar um status e executar init novamente.",
9
+ "membersPrompt": "Guardar os membros do espaço de trabalho na configuração? (opcional; a atribuição funciona sem isso)",
10
+ "strategyPrompt": "Selecione a estratégia de estimativa:",
11
+ "targetPromptTime": "O ClickUp suporta estimativas de tempo nativas. Destino de escrita:",
12
+ "targetTime": "time — estimativa de tempo nativa (recomendado para ideal_hours / ideal_days)",
13
+ "targetNone": "none — guardar apenas como tag est:",
14
+ "noEstimation": "none — sem estimativa (task.estimate.set responde NOT_APPLICABLE)",
15
+ "autonomousPrompt": "Habilitar modo autônomo? (o agente pode escrever no ClickUp sem confirmação por ação)",
16
+ "nextDoctor": "Próximo: pm-tasks-clickup init --doctor",
17
+ "noCredentials": "O pm-tasks-clickup init precisa de acesso ao ClickUp. Defina CLICKUP_API_TOKEN com um token de API pessoal (ClickUp → Settings → Apps → API Token) e execute init novamente, ou execute init em uma sessão de agente com o MCP do ClickUp conectado.",
18
+ "noWorkspaceFound": "Estas credenciais não veem nenhum espaço de trabalho do ClickUp. Verifique o token e execute init novamente.",
19
+ "noListsFound": "O espaço de trabalho {workspace} não tem listas. Crie uma lista no ClickUp e execute init novamente.",
20
+ "listSkippedNoOpen": "A lista {list} foi ignorada: ela não tem status do tipo open. Crie um no ClickUp e execute init novamente para usá-la.",
21
+ "listSkippedNoDone": "A lista {list} foi ignorada: ela não tem status do tipo done nem closed. Crie um no ClickUp e execute init novamente para usá-la.",
22
+ "noUsableList": "Nenhuma das listas escolhidas pode ser fixada: cada uma precisa de um status aberto e de um status concluído ou fechado. Nada foi gravado.",
23
+ "configWritten": "Configuração gravada em {path}",
24
+ "nextAutonomous": "O modo autônomo foi gravado com enabled: false. Defina autonomous.enabled como true na configuração quando quiser que o agente escreva sem pedir confirmação.",
25
+ "initErrorAuth": "O token de API do ClickUp foi recusado (malformado, inválido ou sem acesso). Defina CLICKUP_API_TOKEN com um token de API pessoal válido (ClickUp → Settings → Apps → API Token) e execute init novamente.",
26
+ "initErrorRateLimit": "O limite de requisições do ClickUp foi atingido. Aguarde um minuto e execute init novamente.",
27
+ "initErrorHttp": "O ClickUp respondeu com HTTP {status}. Tente novamente mais tarde.",
28
+ "initErrorNetwork": "Não foi possível acessar o ClickUp (erro de rede ou tempo esgotado). Verifique a conexão e execute init novamente.",
29
+ "initErrorResponse": "O ClickUp enviou uma resposta que o init não conseguiu ler. Execute init novamente; se continuar falhando, relate o problema.",
30
+ "initErrorWorkspace": "O espaço de trabalho não está entre os que estas credenciais podem acessar.",
31
+ "attributionCommentPrefix": "🤖 Criado via pm-tasks-clickup",
32
+ "attributionAutoPrefix": "🤖 [auto] Criado via pm-tasks-clickup",
33
+ "errorNotFound": "Tarefa do ClickUp não encontrada: {ref}",
34
+ "errorNotApplicable": "Operação não aplicável: {reason}",
35
+ "errorInvalidRequest": "Requisição inválida: {message}",
36
+ "errorListNotConfigured": "A lista {listId} não está no .clickup.json. Execute pm-tasks-clickup init para registrá-la.",
37
+ "errorRoleNotConfigured": "A lista {list} não tem status fixado para o papel {role}. Execute pm-tasks-clickup init novamente para fixar um.",
38
+ "errorDetachUnsupported": "O MCP do ClickUp não permite desvincular uma subtarefa da tarefa-mãe.",
39
+ "errorPartial": "Escrita parcial: {applied} aplicado, depois {failedStep} falhou.",
40
+ "errorMissingConfig": "Nenhum .clickup.json encontrado. Execute: npx @llodev/pm-tasks-clickup init",
41
+ "doctorOk": "Configuração do ClickUp OK",
42
+ "doctorNoConfig": "Nenhum .clickup.json encontrado. Execute: npx @llodev/pm-tasks-clickup init",
43
+ "doctorNoLists": "Nenhuma lista encontrada na configuração. Execute init novamente.",
44
+ "doctorNoDone": "A lista {list} não tem status de concluído fixado. Execute init novamente.",
45
+ "doctorStatusDrift": "Lista {list}: o status fixado \"{status}\" ({role}) não existe mais no ClickUp. Execute init novamente para fixar os status atuais.",
46
+ "doctorNoProbe": "Verificações ao vivo do ClickUp (C-CLK-7, C-CLK-8) ignoradas: defina CLICKUP_API_TOKEN para executá-las.",
47
+ "doctorEstimationMismatch": "estimation.clickupTarget é 'time', mas a estratégia não é baseada em tempo (ideal_hours ou ideal_days). Execute init novamente.",
48
+ "doctorAutonomousDisabled": "autonomous.enabled não é true — o modo autônomo está desativado.",
49
+ "doctorConfigInvalid": "A configuração em {path} está vazia, não é um JSON válido ou não tem o campo version. Corrija-a ou execute init novamente.",
50
+ "doctorNoWorkspace": "workspace.id não está no .clickup.json. Execute init novamente.",
51
+ "doctorNoOpen": "A lista {list} não tem status de aberto fixado. Execute init novamente.",
52
+ "doctorHoursPerDay": "estimation.hoursPerDay deve ser um número de 1 a 24.",
53
+ "doctorEstimationOff": "A estimativa está desativada: task.estimate.set responde NOT_APPLICABLE.",
54
+ "doctorScopeUnknownList": "autonomous.scope.lists cita a lista {list}, que não está em lists[].",
55
+ "doctorAliasUnresolved": "defaults.{field} \"{alias}\" não corresponde a nenhum alias de membro e não é \"me\".",
56
+ "doctorUnreachable": "Não foi possível acessar o ClickUp: {reason}",
57
+ "doctorWorkspaceHidden": "O workspace {workspace} não está entre os workspaces que esta credencial pode acessar.",
58
+ "doctorLiveSkipped": "Verificação de status ignorada porque C-CLK-7 falhou (veja a mensagem dele).",
59
+ "doctorListUnreadable": "Não foi possível ler a lista {list} no ClickUp: {reason}",
60
+ "doctorListInaccessible": "Lista {list}: o ClickUp recusou a leitura (HTTP {status}), embora o espaço de trabalho esteja acessível; a lista foi excluída, movida ou esta conta perdeu o acesso. Remova-a de lists[] ou execute o init de novo.",
61
+ "doctorListsNotChecked": "Listas restantes não verificadas após esse erro: {count}."
62
+ }
package/manifest.json ADDED
@@ -0,0 +1,14 @@
1
+ {
2
+ "tool": "clickup",
3
+ "verbs": [
4
+ "task.create",
5
+ "task.move",
6
+ "checklist.check",
7
+ "task.close",
8
+ "task.due-date.set",
9
+ "task.assignee.add",
10
+ "task.comment.add",
11
+ "task.parent.set",
12
+ "task.estimate.set"
13
+ ]
14
+ }
package/package.json ADDED
@@ -0,0 +1,64 @@
1
+ {
2
+ "name": "@llodev/pm-tasks-clickup",
3
+ "version": "0.0.0-pr-130-7078a2a",
4
+ "description": "ClickUp adapter for the @llodev/pm-tasks-* family. Use when the user mentions ClickUp, asks to create a ClickUp task, publish to ClickUp, post to ClickUp, change a task's status, add a comment in ClickUp, or uses --publish-clickup; OR for CRUD on existing tasks (move status, check subtask, close task, change due-date, assign person, comment, set parent, set estimate); OR when invoked autonomously by another agent with [autonomous] / --auto sentinel. Implements 9 CRUD verbs (task.create, task.move, checklist.check, task.close, task.due-date.set, task.assignee.add, task.comment.add, task.parent.set, task.estimate.set) via the ClickUp MCP server. Requires @llodev/pm-tasks-core installed.",
5
+ "license": "MIT",
6
+ "homepage": "https://github.com/llodev/skills/tree/main/skills/pm-tasks-clickup",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "https://github.com/llodev/skills.git",
10
+ "directory": "skills/pm-tasks-clickup"
11
+ },
12
+ "main": "./dist/index.js",
13
+ "types": "./dist/index.d.ts",
14
+ "files": [
15
+ "SKILL.md",
16
+ "README.md",
17
+ "LICENSE",
18
+ "CHANGELOG.md",
19
+ "docs",
20
+ "anti-patterns",
21
+ "references",
22
+ "i18n",
23
+ "schemas",
24
+ "manifest.json",
25
+ "dist"
26
+ ],
27
+ "keywords": [
28
+ "agent-skill",
29
+ "clickup",
30
+ "plan-to-tasks",
31
+ "pm-tools",
32
+ "clickup-mcp"
33
+ ],
34
+ "type": "module",
35
+ "exports": {
36
+ ".": {
37
+ "types": "./dist/index.d.ts",
38
+ "import": "./dist/index.js"
39
+ },
40
+ "./adapter": {
41
+ "types": "./dist/adapter.d.ts",
42
+ "import": "./dist/adapter.js"
43
+ },
44
+ "./schemas/*.json": "./schemas/*.json",
45
+ "./manifest.json": "./manifest.json"
46
+ },
47
+ "bin": {
48
+ "pm-tasks-clickup": "./dist/bin/init.js"
49
+ },
50
+ "dependencies": {
51
+ "@llodev/pm-tasks-core": "^0.0.0-pr-130-7078a2a"
52
+ },
53
+ "publishConfig": {
54
+ "access": "public"
55
+ },
56
+ "engines": {
57
+ "node": ">=24"
58
+ },
59
+ "scripts": {
60
+ "build": "tsc -p tsconfig.json && chmod +x dist/bin/init.js",
61
+ "typecheck": "tsc -p tsconfig.json --noEmit",
62
+ "test": "pnpm build && vitest run --passWithNoTests"
63
+ }
64
+ }
@@ -0,0 +1,85 @@
1
+ # ClickUp autonomous mode overlay
2
+
3
+ ClickUp-specific overlay on the core autonomous-mode contract. Base contract: [`../../pm-tasks-core/references/autonomous-mode.md`](../../pm-tasks-core/references/autonomous-mode.md).
4
+
5
+ ## The block
6
+
7
+ ```jsonc
8
+ {
9
+ "autonomous": {
10
+ "enabled": false, // init writes false on purpose; must be explicitly true to activate
11
+ "allow": [
12
+ // verb allowlist: a subset of the nine manifest verbs
13
+ "task.create",
14
+ "task.move",
15
+ "checklist.check",
16
+ "task.close",
17
+ "task.due-date.set",
18
+ "task.assignee.add",
19
+ "task.comment.add",
20
+ "task.parent.set",
21
+ "task.estimate.set",
22
+ ],
23
+ "scope": {
24
+ "lists": ["<listId>"], // writes allowed only in these list ids (each must be in lists[])
25
+ },
26
+ "rateLimit": { "writesPerMinute": 30, "commentsPerMinute": 10 },
27
+ "auditLog": "./logs/clickup/audit.log",
28
+ },
29
+ }
30
+ ```
31
+
32
+ `init` writes this block only when the user asks for it, with `allow` = every manifest verb, `scope.lists` = the chosen lists and `enabled: false`.
33
+
34
+ ## Activation
35
+
36
+ Autonomous mode needs **both**:
37
+
38
+ 1. A signal: the `[autonomous]` sentinel or the `--auto` flag in the request (or `LLODEV_PM_TASKS_AUTONOMOUS=1` for CI and cron).
39
+ 2. `autonomous.enabled === true` in `.clickup.json`.
40
+
41
+ Block missing or `enabled` not `true` → do not write; report `INVALID_CONFIG` and ask the human. Never infer autonomous mode.
42
+
43
+ ## Who enforces what
44
+
45
+ The transport cannot know whether a call is autonomous, so it enforces none of the policy. You do, before every write:
46
+
47
+ | Rule | Enforced by | Checked statically by |
48
+ | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------ |
49
+ | Verb in `autonomous.allow` | You → `ALLOWLIST_VIOLATION` | doctor C-CFG-2 (`allow` ⊆ manifest verbs) |
50
+ | Home list in `scope.lists` | You → `OUT_OF_SCOPE` | doctor C-CFG-3, C-CLK-6 (scope ids in `lists[]`) |
51
+ | Home list in `lists[]` at all | The transport, for `task.move` / `checklist.check` / `task.close` (`list_not_configured`) | none (a task's list is known only at runtime) |
52
+ | `rateLimit` | You → `RATE_LIMITED` | none |
53
+ | Forbidden verbs (delete, archive, rename, description replace, assignee remove) | Not in this adapter's manifest at all | n/a |
54
+
55
+ ## Knowing a task's home list
56
+
57
+ Scope is about the list a task lives in, and only `clickup_get_task` tells you that (`list.id`). Skip the extra read only when the list is already known from a scoped source:
58
+
59
+ - you created the task in a scoped list in this run;
60
+ - the plan-execution lister returned it (it scans only `scope.lists`, else `lists[]`);
61
+ - you just read it with `clickup_get_task`.
62
+
63
+ Watch the verbs that change the home list: `task.move` with a list id and `task.parent.set` (ClickUp moves the child into the parent's list). The destination must be in `scope.lists` too, or the next verb on that task is out of scope.
64
+
65
+ ## Identity
66
+
67
+ The adapter behaves the same whether the MCP is authenticated as a person or as an AI-agent account: `"me"` is whoever is authenticated. A dedicated agent account makes autonomous writes easy to tell apart in ClickUp's activity, but it is an option, not a requirement.
68
+
69
+ ## Escalation
70
+
71
+ On failure or a blocker: `task.comment.add` with the failure mode, then `task.assignee.add` with the member that `defaults.escalateToAlias` names (`"me"` or a `members[].alias`; map the alias to `members[].id` first). The union write keeps the current assignees. Leave the task in `wip`: no `task.move(_, "done")`, no `task.close`.
72
+
73
+ ## Audit log
74
+
75
+ When verbs go through the runtime (`createAdapter`), core appends one JSONL entry per verb to `$LLODEV_PM_TASKS_LOG_DIR/clickup/audit.log`, else `$XDG_DATA_HOME/llodev/pm-tasks/clickup/audit.log`, else `~/.local/share/llodev/pm-tasks/clickup/audit.log`. `autonomous.auditLog` does not change that path. Direct MCP calls you make yourself (subtasks in Phase 5, start dates, lookups) are not logged by the runtime: log them per [`../../pm-tasks-core/references/audit-log-format.md`](../../pm-tasks-core/references/audit-log-format.md).
76
+
77
+ ## Write-through flow
78
+
79
+ 1. Skip the Phase 5 preview and approval.
80
+ 2. Check activation, allowlist, scope and rate limit (before any MCP call).
81
+ 3. Call the verb.
82
+ 4. Treat `ALREADY_IN_STATE` as done, not as a failure.
83
+ 5. Return the core result envelope (JSON) to the calling agent.
84
+
85
+ Attribution, when enabled, uses `autonomousCommentPrefix` instead of `commentPrefix`; see [`../../pm-tasks-core/references/attribution.md`](../../pm-tasks-core/references/attribution.md).
@@ -0,0 +1,115 @@
1
+ # ClickUp estimation
2
+
3
+ How `task.estimate.set` works in `@llodev/pm-tasks-clickup`. Estimation records **effort**, never a calendar deadline. All verbs return the core result envelope; see [`../../pm-tasks-core/references/contract.md`](../../pm-tasks-core/references/contract.md).
4
+
5
+ ## Pass the config yourself
6
+
7
+ The core runtime passes the request through and does **not** read `.clickup.json` for you. The request is `{ taskId, input, config }`, and `config` must be the `estimation` block of `.clickup.json` (in TypeScript, cast it to core's `EstimationConfig`: the ClickUp block carries `clickupTarget` instead of `jiraTarget`).
8
+
9
+ ```ts
10
+ const { estimation } = JSON.parse(await readFile(".clickup.json", "utf8"));
11
+ await runtime.taskEstimateSet({ taskId, input: 2, config: estimation as EstimationConfig });
12
+ ```
13
+
14
+ On/off, checked before anything else:
15
+
16
+ - `.clickup.json` has no `estimation` block, or it says `enabled: false`, or the request `config` says `enabled: false` → `NOT_APPLICABLE`, `reason: "estimation_disabled"`.
17
+ - Estimation on but no request `config` → `INVALID_REQUEST`, `reason: "estimation_config_required"`.
18
+
19
+ ## Strategies
20
+
21
+ | Strategy | Input | Native `time_estimate` | `est:` tag (example) |
22
+ | ---------------- | ----------------------------------------------------------------------------------------- | --------------------------------- | ---------------------------- |
23
+ | `story_points` | number (points snap to `scale` when set; `init` writes one) | never | `3` → `est:3` |
24
+ | `fibonacci` | number (points snap to `scale` when set; `init` writes one) | never | `5` → `est:5` |
25
+ | `planning_poker` | number (points snap to `scale` when set; `init` writes one) | never | `8` → `est:8` |
26
+ | `affinity` | number (points snap to `scale` when set; `init` writes none) | never | `3` → `est:3` |
27
+ | `t_shirt` | a key of `sizeMap` | never | `M` → `est:m` |
28
+ | `three_point` | `{ optimistic, likely, pessimistic }` (PERT value snaps to `scale` when set, else rounds) | never | → `est:o-1-m-2-p-4` |
29
+ | `ideal_hours` | number | hours × 60 minutes | `2` → `est:2-ideal-hours` |
30
+ | `ideal_days` | number | days × `hoursPerDay` × 60 minutes | `1.5` → `est:1-5-ideal-days` |
31
+
32
+ The tag records the value as given. For point strategies, `normalized.points` (snapped to `scale` when one is set) comes back in the result, but the adapter writes no native points field: ClickUp's native estimate is a duration. An input of the wrong kind for the strategy is `INVALID_REQUEST`, `reason: "invalid_estimate"`.
33
+
34
+ ## `clickupTarget`
35
+
36
+ | `clickupTarget` | Writes |
37
+ | --------------- | ---------------------------------------------------------------------------------- |
38
+ | `time` | `time_estimate` for `ideal_hours` / `ideal_days`, on leaf tasks only, plus the tag |
39
+ | `none` | the tag only |
40
+
41
+ `init` proposes `time` for the time strategies (the user may pick `none`) and writes `none` for every other strategy. `time` with a point strategy is harmless (only the tag is written) but the doctor's C-CLK-4 warns about it. Switching from `time` to `none` stops future native writes; it does not clear an estimate already on a task.
42
+
43
+ ## Leaf-only native estimate
44
+
45
+ `time_estimate` is written only when the task has no subtasks (`subtasks_count === 0` on a plain `clickup_get_task`). A task with subtasks gets the tag only, and the result says `fieldWritten: null`.
46
+
47
+ Why: ClickUp keeps a parent's own `time_estimate` when children are added (the API field does not roll up), while spaces with time-estimate roll-up show the parent's own estimate plus its children's in views. Writing both double counts.
48
+
49
+ Consequences:
50
+
51
+ - In Phase 5, create the subtasks **before** estimating, or the parent is still a leaf and receives a native estimate.
52
+ - A leaf estimated earlier keeps its estimate after it gains children. Remove it in the ClickUp UI if the roll-up view double counts.
53
+
54
+ ## The `est:<slug>` tag
55
+
56
+ `slug` = the readable value lowercased, every run of characters outside `[a-z0-9]` turned into one `-`, leading and trailing `-` removed. A value with no letter or digit is `invalid_estimate`.
57
+
58
+ Write sequence (each step only when needed):
59
+
60
+ 1. Read the task once: tags, `subtasks_count`, `space.id`, current `time_estimate`.
61
+ 2. Native estimate (time target, time strategy, leaf, value differs) → `clickup_update_task {task_id, time_estimate: "<whole minutes>"}`.
62
+ 3. Every other `est:*` tag → `clickup_remove_tag_from_task` (ClickUp matches tag names case-insensitively).
63
+ 4. Tag missing → `clickup_create_space_tag {space_id, name}` (returns `created: false` when the tag already exists in the space; ClickUp lowercases the name), then `clickup_add_tag_to_task {task_id, tag_name}`.
64
+
65
+ Exactly one `est:*` tag remains. Re-running with the same input writes nothing. `fieldWritten` is `"time_estimate"` whenever the native estimate applies, even when it already matched and no write was needed.
66
+
67
+ ## `hoursPerDay`
68
+
69
+ Hours in one ideal day for `ideal_days`. Default **6** (core's focused day). Must be a number from 1 to 24, else `INVALID_REQUEST`, `reason: "invalid_hours_per_day"`. Minutes are rounded to a whole minute and must be at least 1 (`invalid_estimate` for zero or a negative input).
70
+
71
+ ## Partial failure
72
+
73
+ When a step fails after an earlier step wrote something, the result names what landed:
74
+
75
+ ```json
76
+ {
77
+ "ok": false,
78
+ "code": "MCP_ERROR",
79
+ "details": {
80
+ "message": "<server message>",
81
+ "verb": "task.estimate.set",
82
+ "partial": true,
83
+ "applied": ["time_estimate", "tag_remove", "tag_create"],
84
+ "failedStep": "tag_add"
85
+ }
86
+ }
87
+ ```
88
+
89
+ Steps are `time_estimate`, `tag_remove`, `tag_create`, `tag_add`, in that order; `tag_create` always runs right before `tag_add`, so a failed `tag_add` always lists `tag_create` in `applied`. `AUTH_ERROR` and `RATE_LIMITED` keep their code (still with `partial: true`) so you know to reconnect or wait. A failure before any write is the plain classified failure, without `partial`. Recovery: re-run the same call; it is idempotent and completes only what is missing.
90
+
91
+ ## `.clickup.json` estimation block
92
+
93
+ ```jsonc
94
+ {
95
+ "estimation": {
96
+ "enabled": true, // written by init; false (or no block) → NOT_APPLICABLE
97
+ "strategy": "ideal_hours", // one of the strategies above
98
+ "clickupTarget": "time", // "time" | "none"
99
+ "hoursPerDay": 6, // optional, 1–24, used by ideal_days
100
+ "scale": [1, 2, 3, 5, 8, 13], // optional; init writes it for story_points, fibonacci, planning_poker
101
+ "sizeMap": { "XS": 1, "S": 2, "M": 3, "L": 5, "XL": 8 }, // t_shirt only
102
+ },
103
+ }
104
+ ```
105
+
106
+ ## Errors
107
+
108
+ | Code / `reason` | When |
109
+ | ------------------------------------------------ | --------------------------------------------------------------------------- |
110
+ | `NOT_APPLICABLE` / `estimation_disabled` | No `estimation` block, or `enabled: false` (config or request) |
111
+ | `INVALID_REQUEST` / `estimation_config_required` | Estimation on, request without `config` |
112
+ | `INVALID_REQUEST` / `invalid_hours_per_day` | `hoursPerDay` outside 1–24 or not a number |
113
+ | `INVALID_REQUEST` / `invalid_estimate` | Input does not fit the strategy, rounds to zero minutes, or has no tag slug |
114
+ | `INVALID_REQUEST` / `id_required` | Blank `taskId` |
115
+ | `MCP_ERROR` with `partial: true` | A step failed after an earlier write (above) |
@@ -0,0 +1,128 @@
1
+ # ClickUp CRUD operations
2
+
3
+ Verb → MCP tool mapping for `@llodev/pm-tasks-clickup`. Every verb returns the core result envelope; see [`../../pm-tasks-core/references/contract.md`](../../pm-tasks-core/references/contract.md) § Result envelope. Tool names omit your agent's server prefix. Every call also carries `workspace_id` from `.clickup.json`.
4
+
5
+ ## Verb → MCP tool
6
+
7
+ | Core verb | ClickUp MCP tool(s) | Request → parameters | Result `data` |
8
+ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
9
+ | `task.create` | `clickup_create_task` | `boardOrProjectId` → `list_id`; `listOrSectionId` → `status` (omitted when empty); `name`; `description` (+ `[ct:<token>]` footer) → `markdown_description`; `labels` → `tags`; `priority`; `dueDate` → `due_date` | `{ id, url }` |
10
+ | `task.move` | `clickup_get_task`, then `clickup_update_task {status}` or `clickup_move_task {list_id}` | `targetListOrSectionId`: `open` / `wip` / `done` (any case) or a list id of six or more digits | `{ previousListOrSectionId, newListOrSectionId }` |
11
+ | `checklist.check` | `clickup_get_task`, `clickup_update_task {status}` | `itemId` = subtask id, `checklistId` = parent task id, `targetState` `complete` / `incomplete` | `{ previousState, newState }` |
12
+ | `task.close` | `clickup_get_task`, `clickup_update_task {status}` | `taskId`; `closeListOrSectionId` is ignored (closing never changes the list) | `{ closed: true }` |
13
+ | `task.due-date.set` | `clickup_get_task`, `clickup_get_user` (only when a due date is stored; cached on success), `clickup_update_task {due_date}` | `dueAt` must start with a real `YYYY-MM-DD`; only that date is sent | `{ previousDueAt, newDueAt }` |
14
+ | `task.assignee.add` | `clickup_resolve_assignees` (non-numeric only), `clickup_get_task`, `clickup_update_task {assignees}` | `userId`: numeric id, `"me"`, email or username | `{ added, currentAssigneeIds }` |
15
+ | `task.comment.add` | `clickup_get_task_comments` (with a token), `clickup_create_comment` | `entity_type: "task"`, `entity_id: taskId`, `comment_text: "[ct:<token>] " + text` (marker only with `clientToken`) | `{ commentId, postedAt }` |
16
+ | `task.parent.set` | `clickup_get_task`, `clickup_update_task {parent}` | `parentId` (trimmed); empty or `null` → `NOT_APPLICABLE` | `{ previousParentId, newParentId }` |
17
+ | `task.estimate.set` | `clickup_get_task`, `clickup_update_task {time_estimate}`, `clickup_remove_tag_from_task`, `clickup_create_space_tag`, `clickup_add_tag_to_task` | `{ taskId, input, config }`, where `config` is the `.clickup.json` `estimation` block; see [`estimation.md`](estimation.md) | `{ normalized, fieldWritten }` |
18
+
19
+ Every verb except `task.create` rejects a blank id before any call (`task.estimate.set` after its on/off check): `INVALID_REQUEST`, `reason: "id_required"`, `details.field` names it.
20
+
21
+ ## Reads before writes
22
+
23
+ All verbs but `task.create` and `task.comment.add` read the task first with one compact `clickup_get_task {task_id}` (no `include`); `task.assignee.add` resolves a non-numeric user before that read. The read is the only trusted source of the task's status, home list and parent: a response without `list.id`, a status name or a `parent` key is a shape error (`MCP_ERROR`), never a default. Write responses are envelopes (`{success, task_id, custom_id, task_url}`; `clickup_move_task` returns `new_list_id` and no URL) and are never read as a task.
24
+
25
+ ## Per-verb notes
26
+
27
+ **`task.create`.** `boardOrProjectId` is required (`list_required`). The list may be any list, but if it is not in `lists[]` every later status verb on the task fails `list_not_configured`. `listOrSectionId` is a status **name** sent as is; role words are not resolved here, and a name the list lacks is rejected by ClickUp. Priority: `urgent`, `high`, `normal`, `low`, with `medium` → `normal`, case-insensitive; anything else is omitted. `dueDate` must start with a real calendar date (`invalid_due_date`; `null` counts as absent). `estimate` is ignored: call `task.estimate.set` afterwards. The `[ct:<token>]` footer is appended once, as its own paragraph. The transport does **not** look for an existing task: the duplicate lookup is the caller's (below). `url` falls back to `https://app.clickup.com/t/<task_id>`.
28
+
29
+ **`task.move`.** A role word resolves to the status pinned for that role in the task's **home list**. A target that is neither a role word nor six or more digits is `invalid_target`. Same status (trimmed, case-insensitive) → `ALREADY_IN_STATE` with `details.status`. A list id calls `clickup_move_task`: same list → `ALREADY_IN_STATE` with `details.listId`; a task with a parent → `subtask_cannot_move`. ClickUp requires the task's current status name to exist in the destination list. A status move returns status names in `previousListOrSectionId` / `newListOrSectionId`; a list move returns list ids. The transport never writes `start_date` (see Temporal handling).
30
+
31
+ **`checklist.check`.** `itemId` must be a subtask whose `parent` is `checklistId` (`not_a_checklist_item` otherwise). The item is complete when its status equals the pinned `done`; `complete` writes the pinned `done`, `incomplete` writes the pinned `open`. The list must pin `done` even to uncheck. Already in the requested state → `ALREADY_IN_STATE` with `details.state`.
32
+
33
+ **`task.close`.** Target = the pinned `done` status. A task already at the pinned `done` **or** at the pinned `closed` status (for example "cancelled") is left alone and returns `{ closed: true }` without a write: a cancelled task is not turned into a done one. Closing a parent does not close its open subtasks (ClickUp leaves them as they are).
34
+
35
+ **`task.due-date.set`.** Date-only: the time of day in `dueAt` is dropped, and `newDueAt` is the `YYYY-MM-DD` sent. ClickUp stores it as 04:00 in the account's timezone. `previousDueAt` is the ISO instant of the stored value (or `null`). The write is skipped when the stored instant's **local** date, computed with `utc_offset` from `clickup_get_user`, equals the requested date. `clickup_get_user` is read lazily, only when the task already has a due date, and cached on success; a failed read is retried on the next call, and this call writes anyway. Clearing a due date is not supported: `null` or any non-date is `invalid_due_date`. Relative dates ("tomorrow") must be computed from `clickup_get_user.current_time` before the call.
36
+
37
+ **`task.assignee.add`.** A non-numeric `userId` (`"me"`, an email, a username) is resolved first with `clickup_resolve_assignees {assignees: [userId]}`; anything but exactly one numeric id is `assignee_unresolved` (an auth or rate-limit failure keeps its own code). `members[].alias` values are not accepted: map an alias to its `members[].id` first. Already assigned → `{ added: false, currentAssigneeIds }` with no write. Otherwise the write is the **union** of the assignees just read and the new id, because `assignees` replaces the whole set. `"me"` is whoever the MCP is authenticated as, person or agent account.
38
+
39
+ **`task.comment.add`.** `text` must be non-empty (`text_required`) and at most 40,000 characters including the marker (`text_too_long`). With a `clientToken`, the transport first reads the **first page** of `clickup_get_task_comments {task_id}`; a comment whose text contains `[ct:<token>]` (ClickUp keeps the marker verbatim) is returned with its own date instead of posting again. Without a token, every call posts. The attribution prefix, when enabled, must already be in `text`. Use `clickup_create_comment`; `clickup_create_task_comment` is deprecated.
40
+
41
+ **`task.parent.set`.** ClickUp also **moves the task into the parent's list**; the result does not report the new list (the response type has no field for it). If that list is not in `lists[]`, status verbs on the task then fail `list_not_configured`. The MCP cannot clear a parent: an empty or `null` `parentId` is `NOT_APPLICABLE`, `reason: "detach_unsupported"` (detach in the ClickUp UI). A task cannot be its own parent (`self_parent`); there is no deeper cycle guard: ClickUp decides. Already under that parent → no write.
42
+
43
+ **`task.estimate.set`.** See [`estimation.md`](estimation.md).
44
+
45
+ ## Duplicate lookup for `task.create`
46
+
47
+ The transport only embeds the marker; the caller looks first:
48
+
49
+ 1. `clickup_search {keywords: "ct:<token>"}`. Search without brackets: ClickUp stores `markdown_description` with them escaped (`\[ct:<token>\]`), while `text_content` keeps them plain.
50
+ 2. For each `results[]` entry with `type: "task"`, confirm with `clickup_get_task {task_id}` that `text_content` contains `[ct:<token>]`.
51
+ 3. Found → return that task's ref and create only what is missing (subtasks by name, from `include: ["subtasks"]`). Not found → `task.create`.
52
+
53
+ ## Status resolution and drift
54
+
55
+ `task.move`, `checklist.check` and `task.close` resolve statuses from config only, with no live lookup:
56
+
57
+ | Situation | Result | Fix |
58
+ | ------------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------- |
59
+ | Home list not in `lists[]` | `INVALID_REQUEST`, `list_not_configured`, `details.listId` | Re-run `init` and select the list |
60
+ | Role not pinned (no `wip`, or a hand-edited list) | `INVALID_REQUEST`, `role_not_configured`, `details.role` | Re-run `init` and pick the status |
61
+ | Pinned status renamed or deleted in ClickUp | `INVALID_REQUEST`, `status_rejected`, `details.status` | Run the doctor (C-CLK-8 names list and role), then re-run `init` |
62
+ | Uncheck while the pinned `done` was renamed | `ALREADY_IN_STATE` (the item no longer matches `done`) | Run the doctor |
63
+
64
+ `wip` is the user's choice at `init` because ClickUp has no status type for "in progress" and several `custom` statuses usually compete. A list with no `custom` status gets no `wip`; `task.move` to `wip` then fails `role_not_configured` on its tasks.
65
+
66
+ ## Idempotency
67
+
68
+ | Verb | Rule |
69
+ | ------------------- | -------------------------------------------------------------------------------- |
70
+ | `task.create` | Caller's lookup above; the `[ct:<token>]` footer is the key |
71
+ | `task.move` | Same status or same list → `ALREADY_IN_STATE`, no write |
72
+ | `checklist.check` | Already complete / incomplete → `ALREADY_IN_STATE`, no write |
73
+ | `task.close` | At pinned `done` or `closed` → `ok: true`, no write |
74
+ | `task.due-date.set` | Same local date → `ok: true`, no write |
75
+ | `task.assignee.add` | Already assigned → `ok: true`, `added: false`, no write |
76
+ | `task.comment.add` | Token already on the first comments page → `ok: true` with that comment, no post |
77
+ | `task.parent.set` | Same parent → `ok: true`, no write |
78
+ | `task.estimate.set` | Same estimate and tag → `ok: true`, zero writes |
79
+
80
+ `ALREADY_IN_STATE` is a no-op signal, not a failure: core's plan-execution hooks put the verb in `skipped` and keep `ok: true`.
81
+
82
+ ## Temporal handling (lifecycle fidelity)
83
+
84
+ Applies [`../../pm-tasks-core/references/lifecycle-fidelity.md`](../../pm-tasks-core/references/lifecycle-fidelity.md) to ClickUp:
85
+
86
+ - **Create:** `dueDate` → `due_date` (typed). Estimate through `task.estimate.set`.
87
+ - **Start (move → `wip`):** ClickUp stamps nothing. When the list or team tracks start dates, the agent follows the move with `clickup_update_task {task_id, start_date: "YYYY-MM-DD"}` for today (from `clickup_get_user.current_time`). Writing `start_date` alone leaves `due_date` unchanged.
88
+ - **Close:** `due_date` stays = the plan; never overwrite it. ClickUp leaves `date_closed` null for a `done`-type status, so completion is detected by the status, not by `date_closed`.
89
+
90
+ ## Error codes
91
+
92
+ | Code | When |
93
+ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
94
+ | `INVALID_REQUEST` | Bad input or unusable config; `details.reason` is stable (`id_required`, `list_required`, `invalid_target`, `invalid_target_state`, `invalid_due_date`, `list_not_configured`, `role_not_configured`, `status_rejected`, `subtask_cannot_move`, `not_a_checklist_item`, `assignee_unresolved`, `text_required`, `text_too_long`, `self_parent`, estimation reasons) |
95
+ | `NOT_APPLICABLE` | `task.parent.set` detach (`detach_unsupported`); `task.estimate.set` with estimation off (`estimation_disabled`) |
96
+ | `ALREADY_IN_STATE` | `task.move` / `checklist.check` with nothing to change |
97
+ | `NOT_FOUND` | The server said 404 or "not found" (task, list or comment) |
98
+ | `AUTH_ERROR` | 401/403, "unauthorized", "forbidden", "not authorized", an OAuth error: reconnect the ClickUp MCP. ClickUp's API also answers 401 for an id this account cannot read; if reconnecting does not help, check the task id. |
99
+ | `RATE_LIMITED` | 429 or "rate limit": wait and retry. Limits depend on the ClickUp plan |
100
+ | `MCP_ERROR` | Any other server error (`details.message` is the server's text), an unexpected response shape, or a partial estimate |
101
+ | `UNSUPPORTED_VERB` | A verb not in the manifest (see Known limitations) |
102
+
103
+ In autonomous mode the agent itself reports the core contract codes `INVALID_CONFIG`, `ALLOWLIST_VIOLATION`, `OUT_OF_SCOPE` and `FORBIDDEN_VERB` (see [`autonomous.md`](autonomous.md)). Error details carry the server message, never request arguments.
104
+
105
+ ## Result envelope: ClickUp `details`
106
+
107
+ | Verb | `details` fields |
108
+ | ------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
109
+ | `task.create` | `{ id: "<task_id>", url: "https://app.clickup.com/t/<task_id>" }` |
110
+ | `task.move` | `{ previousListOrSectionId: "<previous status name>", newListOrSectionId: "<pinned status name>" }`, or list ids for a list move |
111
+ | `checklist.check` | `{ previousState: "incomplete" or "complete", newState: "complete" or "incomplete" }` |
112
+ | `task.close` | `{ closed: true }` |
113
+ | `task.due-date.set` | `{ previousDueAt: "<ISO instant>" or null, newDueAt: "YYYY-MM-DD" }` |
114
+ | `task.assignee.add` | `{ added: true or false, currentAssigneeIds: ["<userId>", ...] }` |
115
+ | `task.comment.add` | `{ commentId: "<id>", postedAt: "<ISO 8601>" }` |
116
+ | `task.parent.set` | `{ previousParentId: "<task_id>" or null, newParentId: "<task_id>" }` |
117
+ | `task.estimate.set` | `{ normalized: NormalizedEstimate, fieldWritten: "time_estimate" or null }` |
118
+
119
+ ## Known limitations
120
+
121
+ - **No sprint verb.** `task.sprint.set` answers `UNSUPPORTED_VERB`. ClickUp Sprints are lists: `task.move` with the destination list id moves a root task between lists, but the task then leaves its home list, so later status verbs fail `list_not_configured` unless `init` registers the destination list. Keeping a task in several lists needs the _Tasks in Multiple Lists_ ClickApp, which is plan-limited; the adapter does not use it.
122
+ - **Native checklists are not writable** through the MCP: checklist items are subtasks.
123
+ - **Renamed `done` status:** unchecking a subtask whose pinned `done` status was renamed in ClickUp reports `ALREADY_IN_STATE`; run the doctor.
124
+ - **Races:** read-then-write is not guarded; ClickUp has no conditional update.
125
+ - **Comments:** idempotency scans only the first page of comments.
126
+ - **Discovery:** `init` offers only non-archived workspaces, spaces, folders and lists.
127
+ - **Rate limit:** plan-dependent; do not assume a number.
128
+ - **Custom task ids** (`DEV-1234`) are not supported: pass native ids.
@@ -0,0 +1,140 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://llodev.github.io/skills/schemas/pm-tasks-clickup.json",
4
+ "title": "pm-tasks-clickup config",
5
+ "type": "object",
6
+ "required": ["version", "workspace", "lists"],
7
+ "additionalProperties": false,
8
+ "properties": {
9
+ "version": { "type": "string", "enum": ["1"] },
10
+ "locale": {
11
+ "type": "string",
12
+ "enum": ["en-US", "pt-BR", "es-ES"]
13
+ },
14
+ "workspace": {
15
+ "type": "object",
16
+ "required": ["id", "name"],
17
+ "additionalProperties": false,
18
+ "properties": {
19
+ "id": { "type": "string" },
20
+ "name": { "type": "string" }
21
+ }
22
+ },
23
+ "lists": {
24
+ "type": "array",
25
+ "minItems": 1,
26
+ "items": {
27
+ "type": "object",
28
+ "required": ["id", "name", "statuses"],
29
+ "additionalProperties": false,
30
+ "properties": {
31
+ "id": { "type": "string" },
32
+ "name": { "type": "string" },
33
+ "space": { "type": "string" },
34
+ "folder": { "type": "string" },
35
+ "statuses": {
36
+ "type": "object",
37
+ "required": ["open", "done"],
38
+ "additionalProperties": false,
39
+ "properties": {
40
+ "open": { "type": "string" },
41
+ "wip": { "type": "string" },
42
+ "done": { "type": "string" },
43
+ "closed": { "type": "string" }
44
+ }
45
+ }
46
+ }
47
+ }
48
+ },
49
+ "defaultListId": { "type": "string" },
50
+ "members": {
51
+ "type": "array",
52
+ "items": {
53
+ "type": "object",
54
+ "required": ["id", "name"],
55
+ "additionalProperties": false,
56
+ "properties": {
57
+ "id": { "type": "string" },
58
+ "name": { "type": "string" },
59
+ "email": { "type": "string", "format": "email" },
60
+ "alias": { "type": "string" }
61
+ }
62
+ }
63
+ },
64
+ "estimation": {
65
+ "type": "object",
66
+ "required": ["strategy", "clickupTarget"],
67
+ "additionalProperties": false,
68
+ "properties": {
69
+ "enabled": { "type": "boolean" },
70
+ "strategy": {
71
+ "type": "string",
72
+ "enum": [
73
+ "story_points",
74
+ "fibonacci",
75
+ "planning_poker",
76
+ "affinity",
77
+ "t_shirt",
78
+ "ideal_days",
79
+ "ideal_hours",
80
+ "three_point"
81
+ ]
82
+ },
83
+ "clickupTarget": { "type": "string", "enum": ["time", "none"] },
84
+ "hoursPerDay": { "type": "number", "minimum": 1, "maximum": 24 },
85
+ "scale": { "type": "array", "items": { "type": "number" } },
86
+ "sizeMap": { "type": "object", "additionalProperties": { "type": "number" } }
87
+ }
88
+ },
89
+ "defaults": {
90
+ "type": "object",
91
+ "additionalProperties": false,
92
+ "properties": {
93
+ "assigneeAlias": { "type": "string" },
94
+ "escalateToAlias": { "type": "string" }
95
+ }
96
+ },
97
+ "autonomous": {
98
+ "type": "object",
99
+ "required": ["enabled", "allow"],
100
+ "additionalProperties": false,
101
+ "properties": {
102
+ "enabled": { "type": "boolean" },
103
+ "allow": {
104
+ "type": "array",
105
+ "items": {
106
+ "type": "string",
107
+ "enum": [
108
+ "task.create",
109
+ "task.move",
110
+ "checklist.check",
111
+ "task.close",
112
+ "task.due-date.set",
113
+ "task.assignee.add",
114
+ "task.comment.add",
115
+ "task.parent.set",
116
+ "task.estimate.set"
117
+ ]
118
+ }
119
+ },
120
+ "scope": {
121
+ "type": "object",
122
+ "additionalProperties": false,
123
+ "properties": {
124
+ "lists": { "type": "array", "items": { "type": "string" } }
125
+ }
126
+ },
127
+ "rateLimit": {
128
+ "type": "object",
129
+ "additionalProperties": false,
130
+ "properties": {
131
+ "writesPerMinute": { "type": "number" },
132
+ "commentsPerMinute": { "type": "number" }
133
+ }
134
+ },
135
+ "auditLog": { "type": "string" }
136
+ }
137
+ },
138
+ "attribution": { "$ref": "https://llodev.com/pm-tasks/attribution.schema.json" }
139
+ }
140
+ }