@llodev/pm-tasks-clickup 0.0.0-stage → 1.0.0
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.
- package/LICENSE +21 -0
- package/README.md +195 -2
- package/SKILL.md +258 -0
- package/anti-patterns/clickup.md +73 -0
- package/dist/adapter.d.ts +39 -0
- package/dist/adapter.d.ts.map +1 -0
- package/dist/adapter.js +83 -0
- package/dist/adapter.js.map +1 -0
- package/dist/bin/init.d.ts +3 -0
- package/dist/bin/init.d.ts.map +1 -0
- package/dist/bin/init.js +20 -0
- package/dist/bin/init.js.map +1 -0
- package/dist/doctor-cli.d.ts +27 -0
- package/dist/doctor-cli.d.ts.map +1 -0
- package/dist/doctor-cli.js +315 -0
- package/dist/doctor-cli.js.map +1 -0
- package/dist/env.d.ts +6 -0
- package/dist/env.d.ts.map +1 -0
- package/dist/env.js +11 -0
- package/dist/env.js.map +1 -0
- package/dist/envelope.d.ts +44 -0
- package/dist/envelope.d.ts.map +1 -0
- package/dist/envelope.js +95 -0
- package/dist/envelope.js.map +1 -0
- package/dist/errors.d.ts +30 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +60 -0
- package/dist/errors.js.map +1 -0
- package/dist/estimation.d.ts +20 -0
- package/dist/estimation.d.ts.map +1 -0
- package/dist/estimation.js +40 -0
- package/dist/estimation.js.map +1 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +3 -0
- package/dist/index.js.map +1 -0
- package/dist/init-api.d.ts +67 -0
- package/dist/init-api.d.ts.map +1 -0
- package/dist/init-api.js +271 -0
- package/dist/init-api.js.map +1 -0
- package/dist/init-flow.d.ts +27 -0
- package/dist/init-flow.d.ts.map +1 -0
- package/dist/init-flow.js +206 -0
- package/dist/init-flow.js.map +1 -0
- package/dist/status-map.d.ts +31 -0
- package/dist/status-map.d.ts.map +1 -0
- package/dist/status-map.js +38 -0
- package/dist/status-map.js.map +1 -0
- package/dist/status.d.ts +17 -0
- package/dist/status.d.ts.map +1 -0
- package/dist/status.js +21 -0
- package/dist/status.js.map +1 -0
- package/dist/transport-clickup.d.ts +99 -0
- package/dist/transport-clickup.d.ts.map +1 -0
- package/dist/transport-clickup.js +676 -0
- package/dist/transport-clickup.js.map +1 -0
- package/docs/i18n/README.es-ES.md +196 -0
- package/docs/i18n/README.pt-BR.md +196 -0
- package/i18n/en-US.json +62 -0
- package/i18n/es-ES.json +62 -0
- package/i18n/pt-BR.json +62 -0
- package/manifest.json +14 -0
- package/package.json +63 -4
- package/references/autonomous.md +85 -0
- package/references/estimation.md +115 -0
- package/references/operations.md +128 -0
- package/schemas/config.json +140 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 LLDev Information Solutions
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,196 @@
|
|
|
1
|
-
|
|
1
|
+
<!-- readme-selector:start -->
|
|
2
|
+
<p align="center">
|
|
3
|
+
<a href="https://github.com/llodev/skills/blob/main/skills/pm-tasks-clickup/README.md"><img src="https://raw.githubusercontent.com/lloliveiradev/public-assets/main/images/usa.svg" width="30" alt="English"></a>
|
|
4
|
+
<a href="https://github.com/llodev/skills/blob/main/skills/pm-tasks-clickup/docs/i18n/README.pt-BR.md"><img src="https://raw.githubusercontent.com/lloliveiradev/public-assets/main/images/brazil.svg" width="30" alt="Português"></a>
|
|
5
|
+
<a href="https://github.com/llodev/skills/blob/main/skills/pm-tasks-clickup/docs/i18n/README.es-ES.md"><img src="https://raw.githubusercontent.com/lloliveiradev/public-assets/main/images/spain.svg" width="30" alt="Español"></a>
|
|
6
|
+
</p>
|
|
7
|
+
<!-- readme-selector:end -->
|
|
2
8
|
|
|
3
|
-
|
|
9
|
+
# @llodev/pm-tasks-clickup
|
|
10
|
+
|
|
11
|
+
[](https://www.npmjs.com/package/@llodev/pm-tasks-clickup)
|
|
12
|
+
[](LICENSE)
|
|
13
|
+
|
|
14
|
+
ClickUp adapter for the `@llodev/pm-tasks-*` family. Publishes plans as ClickUp tasks with subtasks and runs nine CRUD verbs on existing tasks through the ClickUp MCP. It works for a manager publishing a plan, a team member publishing or updating tasks, and an AI agent executing a plan autonomously, with the same verbs.
|
|
15
|
+
|
|
16
|
+
## Install
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
npm install @llodev/pm-tasks-clickup @llodev/pm-tasks-core
|
|
20
|
+
# or
|
|
21
|
+
pnpm add @llodev/pm-tasks-clickup @llodev/pm-tasks-core
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## Set up the MCP
|
|
25
|
+
|
|
26
|
+
The runtime verbs go through the ClickUp MCP server at `https://mcp.clickup.com/mcp`. The MCP handles OAuth: the adapter never sees a credential for the verbs.
|
|
27
|
+
|
|
28
|
+
- Agents that accept a remote MCP URL (Cursor, Windsurf, Cline, Roo Code and others): add an MCP entry named `clickup` pointing at `https://mcp.clickup.com/mcp`, then approve the OAuth flow in your browser.
|
|
29
|
+
- Agents that run MCP servers as local commands: bridge it with `mcp-remote`:
|
|
30
|
+
|
|
31
|
+
```json
|
|
32
|
+
{
|
|
33
|
+
"mcpServers": {
|
|
34
|
+
"clickup": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.clickup.com/mcp"] }
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
The tools appear as `clickup_*` (your agent may add a server prefix).
|
|
40
|
+
|
|
41
|
+
## Set up the config
|
|
42
|
+
|
|
43
|
+
`init` discovers your workspace, lists and statuses, and writes `.clickup.json`. Discovery is read-only: nothing is written to ClickUp. There are two ways to run it.
|
|
44
|
+
|
|
45
|
+
**(a) In a terminal, with a personal API token.** Create the token in ClickUp → Settings → Apps → API Token, put it in your environment, then run init:
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
export CLICKUP_API_TOKEN=<your personal token>
|
|
49
|
+
npx @llodev/pm-tasks-clickup init
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
The prompts pick the narration locale, the workspace (only when you have several), the lists to use, the in-progress (`wip`) status of each list, an optional member cache, an estimation strategy and an optional autonomous block. The file goes to `./.clickup.json`, or to `--output <path>`. If the file exists, you are asked before it is overwritten.
|
|
53
|
+
|
|
54
|
+
**(b) Inside an agent session with the ClickUp MCP connected.** Without a token the CLI stops and asks you to run init inside an agent session. That means: ask the agent to set up `.clickup.json`. The agent reads the hierarchy, each list's statuses and the members through the MCP, asks you to pick the lists and each list's `wip` status, writes the file following `schemas/config.json`, then runs the doctor.
|
|
55
|
+
|
|
56
|
+
## Verbs
|
|
57
|
+
|
|
58
|
+
| Verb | What it does in ClickUp |
|
|
59
|
+
| ------------------- | --------------------------------------------------------------------------------------------------------------- |
|
|
60
|
+
| `task.create` | Creates a task in a list (name, Markdown description, tags, priority, due date, initial status by name) |
|
|
61
|
+
| `task.move` | Changes the status to the list's pinned `open`, `wip` or `done`; or moves a root task to another list by its id |
|
|
62
|
+
| `checklist.check` | Completes or reopens a checklist item, which is a subtask (`done` / `open` status) |
|
|
63
|
+
| `task.close` | Sets the list's pinned `done` status; a task already done or cancelled is left alone |
|
|
64
|
+
| `task.due-date.set` | Sets the due date (a calendar day, `YYYY-MM-DD`) |
|
|
65
|
+
| `task.assignee.add` | Adds an assignee (id, `"me"`, email or username) and keeps the current ones |
|
|
66
|
+
| `task.comment.add` | Posts a comment; with an idempotency token it is posted once |
|
|
67
|
+
| `task.parent.set` | Makes the task a subtask of another task (ClickUp moves it into the parent's list) |
|
|
68
|
+
| `task.estimate.set` | Records effort: native time estimate on leaf tasks, plus an `est:` tag |
|
|
69
|
+
|
|
70
|
+
When nothing needs to change, `task.move` and `checklist.check` answer `ALREADY_IN_STATE`, which means "nothing to do", not an error. The other verbs answer `ok: true` without writing.
|
|
71
|
+
|
|
72
|
+
## Modes
|
|
73
|
+
|
|
74
|
+
| Mode | When | What happens |
|
|
75
|
+
| -------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
|
|
76
|
+
| Paste-ready | No MCP connected | A Markdown description with the checklist as `- [ ]` lines, ready to paste into ClickUp |
|
|
77
|
+
| MCP publish | MCP connected and `.clickup.json` present | Preview, approval, then the task and one subtask per checklist item |
|
|
78
|
+
| Autonomous | `[autonomous]` / `--auto` and `autonomous.enabled: true` | Writes without per-action approval, within `autonomous.allow` and `autonomous.scope.lists` |
|
|
79
|
+
| Plan-execution | A plan file or slug plus `.clickup.json` | Finds the plan's open tasks in the configured lists and keeps their status in sync as work goes on |
|
|
80
|
+
|
|
81
|
+
## Use
|
|
82
|
+
|
|
83
|
+
| Prompt example | What the agent does |
|
|
84
|
+
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
|
|
85
|
+
| `"publish this plan to ClickUp"` | MCP publish: task plus subtasks, after your approval |
|
|
86
|
+
| `"move the login task to in progress"` | `task.move` to the list's pinned `wip` status |
|
|
87
|
+
| `"check the 'write tests' subtask"` | `checklist.check` on that subtask |
|
|
88
|
+
| `"close the login task"` | `task.close` (pinned `done` status) |
|
|
89
|
+
| `"due date of the login task: next Friday"` | `task.due-date.set`, with "next Friday" taken from ClickUp's clock |
|
|
90
|
+
| `"assign me to the login task"` | `task.assignee.add` with `"me"` |
|
|
91
|
+
| `"estimate the login task at 3 ideal hours"` | `task.estimate.set` (`ideal_hours`, task without subtasks: `time_estimate` 180 minutes + `est:3-ideal-hours`) |
|
|
92
|
+
| `"[autonomous] execute docs/plans/X.md and keep ClickUp in sync"` | Autonomous plan execution (requires `autonomous.enabled: true`) |
|
|
93
|
+
|
|
94
|
+
## Config reference
|
|
95
|
+
|
|
96
|
+
```jsonc
|
|
97
|
+
{
|
|
98
|
+
"version": "1",
|
|
99
|
+
"locale": "en-US", // narration language: en-US, pt-BR or es-ES
|
|
100
|
+
"workspace": { "id": "<workspace_id>", "name": "<workspace name>" },
|
|
101
|
+
"lists": [
|
|
102
|
+
{
|
|
103
|
+
"id": "<list_id>",
|
|
104
|
+
"name": "Backlog",
|
|
105
|
+
"space": "<space name>",
|
|
106
|
+
"statuses": {
|
|
107
|
+
"open": "to do",
|
|
108
|
+
"wip": "in progress",
|
|
109
|
+
"done": "complete",
|
|
110
|
+
"closed": "cancelled",
|
|
111
|
+
},
|
|
112
|
+
},
|
|
113
|
+
],
|
|
114
|
+
"defaultListId": "<list_id>",
|
|
115
|
+
"members": [{ "id": "<user_id>", "name": "<name>", "alias": "<alias>" }], // optional cache
|
|
116
|
+
"estimation": {
|
|
117
|
+
"enabled": true,
|
|
118
|
+
"strategy": "ideal_hours",
|
|
119
|
+
"clickupTarget": "time",
|
|
120
|
+
"hoursPerDay": 6,
|
|
121
|
+
},
|
|
122
|
+
"defaults": { "assigneeAlias": "me", "escalateToAlias": "<alias>" },
|
|
123
|
+
"autonomous": {
|
|
124
|
+
"enabled": false,
|
|
125
|
+
"allow": ["task.create", "task.move", "checklist.check", "task.close", "task.comment.add"],
|
|
126
|
+
"scope": { "lists": ["<list_id>"] },
|
|
127
|
+
"rateLimit": { "writesPerMinute": 30, "commentsPerMinute": 10 },
|
|
128
|
+
"auditLog": "./logs/clickup/audit.log",
|
|
129
|
+
},
|
|
130
|
+
}
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
| Field | Meaning |
|
|
134
|
+
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
135
|
+
| `lists[].statuses` | Status names pinned per list by role. `open` and `done` are required; `wip` is your pick; `closed` is the `closed`-type status when it differs from `done` |
|
|
136
|
+
| `defaultListId` | Where new tasks go when no list is named |
|
|
137
|
+
| `members` | Optional cache with unique `alias` values; assignment also works without it |
|
|
138
|
+
| `estimation` | Optional. Absent or `enabled: false` → `task.estimate.set` is not applicable |
|
|
139
|
+
| `defaults` | `"me"` or a `members[].alias` |
|
|
140
|
+
| `autonomous` | `init` writes `enabled: false`; set it to `true` yourself when you want the agent to write without asking |
|
|
141
|
+
| `attribution` | Optional opt-in block from `@llodev/pm-tasks-core` that stamps agent identity on descriptions and comments |
|
|
142
|
+
|
|
143
|
+
No credential is ever stored in this file.
|
|
144
|
+
|
|
145
|
+
## Doctor
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
npx @llodev/pm-tasks-clickup init --doctor
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Runs the shared pm-tasks checks plus the ClickUp checks: config present, workspace id, every list pins `open` and `done`, estimation coherent, autonomous scope and default aliases resolve. With `CLICKUP_API_TOKEN` set it also checks live that the workspace is reachable and that every pinned status still exists in its list (a status renamed or deleted in ClickUp shows up here, with the list and role to fix). Without a token the live checks are skipped with a note. Flags: `--json`, `--fix-hints-only`, `--config <path>`.
|
|
152
|
+
|
|
153
|
+
## ClickUp-specific notes
|
|
154
|
+
|
|
155
|
+
**Statuses are pinned, not guessed.** ClickUp statuses belong to each list and carry a type (`open`, `custom`, `done`, `closed`), but no type means "in progress", so you choose `wip` per list at `init`. Localized and custom names work. If you rename a status later, run the doctor, then `init` again.
|
|
156
|
+
|
|
157
|
+
**Checklist items are subtasks.** The ClickUp MCP cannot write native checklists, so each checklist item becomes a subtask, and checking an item sets the subtask's `done` status.
|
|
158
|
+
|
|
159
|
+
**Assignees are added, never replaced.** ClickUp's update replaces the whole assignee list; the adapter reads the current assignees and writes them back together with the new one.
|
|
160
|
+
|
|
161
|
+
**Estimates do not double count.** The native time estimate is written only on tasks without subtasks, because ClickUp can roll subtask estimates up into the parent. The `est:` tag is always written, and exactly one remains.
|
|
162
|
+
|
|
163
|
+
**Dates are calendar days in the account's timezone.** Relative dates are computed from ClickUp's clock, not the agent's. The due date stays the plan at close; completion is the `done` status.
|
|
164
|
+
|
|
165
|
+
**Person or agent account, same behavior.** `"me"` is whoever the MCP is signed in as. A dedicated agent account for autonomous runs is an option, not a requirement.
|
|
166
|
+
|
|
167
|
+
**Plan limits come from ClickUp, not from the adapter.** ClickUp limits some features by plan: usage caps per feature, and ClickApps (such as Tasks in Multiple Lists or Sprints) that a workspace admin must enable. The adapter does not know your plan's limits, and they can change, so check them for your plan before relying on a verb. When ClickUp refuses a call for plan reasons, the verb fails with ClickUp's own error text (for example `Your plan is limited to … usages of feature`). The cause is the account, not your config.
|
|
168
|
+
|
|
169
|
+
## Known limitations
|
|
170
|
+
|
|
171
|
+
- No sprint verb. The ClickUp MCP has no sprint action. A sprint is a list, and the only way to place a task in a second list is the MCP's `clickup_add_task_to_list`, which needs the Tasks in Multiple Lists ClickApp and a plan that allows it. The MCP's task read also has no field for a task's extra lists, so an assignment could not be read back. `task.move` with the sprint list id moves a root task there, but the task leaves its home list, and status changes on it fail until you register that list with `init`.
|
|
172
|
+
- Native ClickUp checklists can be read but not written.
|
|
173
|
+
- A due date cannot be cleared through the adapter.
|
|
174
|
+
- A subtask cannot be detached from its parent through the MCP.
|
|
175
|
+
- If a pinned `done` status was renamed in ClickUp, unchecking a subtask reports "nothing to do"; run the doctor.
|
|
176
|
+
- ClickUp has no conditional update, so a change made between the adapter's read and its write is not detected.
|
|
177
|
+
- Comment idempotency looks at the first page of comments only.
|
|
178
|
+
- `init` discovers only non-archived spaces, folders and lists.
|
|
179
|
+
- Rate limits depend on your ClickUp plan.
|
|
180
|
+
|
|
181
|
+
## Security
|
|
182
|
+
|
|
183
|
+
`CLICKUP_API_TOKEN` is used only by `init` and the doctor, read only from the environment, and only for read-only discovery. Never paste it into a chat, an issue, a commit or `.clickup.json`. The verbs use the MCP's OAuth, not the token.
|
|
184
|
+
|
|
185
|
+
## Documentation
|
|
186
|
+
|
|
187
|
+
- [`SKILL.md`](SKILL.md): the full skill (routing, ClickUp model, all phases, verbs, result envelope)
|
|
188
|
+
- [`references/operations.md`](references/operations.md): verb → MCP tool mapping, results, error reasons, idempotency
|
|
189
|
+
- [`references/estimation.md`](references/estimation.md): strategies, leaf-only estimate, `est:` tag
|
|
190
|
+
- [`references/autonomous.md`](references/autonomous.md): autonomous allowlist, scope and audit log
|
|
191
|
+
- [`anti-patterns/clickup.md`](anti-patterns/clickup.md): NEVER rules for ClickUp
|
|
192
|
+
- [`schemas/config.json`](schemas/config.json): the `.clickup.json` schema
|
|
193
|
+
|
|
194
|
+
## License
|
|
195
|
+
|
|
196
|
+
MIT
|
package/SKILL.md
ADDED
|
@@ -0,0 +1,258 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: pm-tasks-clickup
|
|
3
|
+
description: >-
|
|
4
|
+
ClickUp adapter for the @llodev/pm-tasks-* family. Use when the user mentions
|
|
5
|
+
ClickUp, asks to "create a ClickUp task", "publish to ClickUp", "post to
|
|
6
|
+
ClickUp", "move the task to in progress", "check the subtask", "close the
|
|
7
|
+
ClickUp task", or uses --publish-clickup; OR for CRUD on existing ClickUp
|
|
8
|
+
tasks (status move, check subtask, close, due date, assign, comment, parent,
|
|
9
|
+
time estimate); OR when an agent invokes it autonomously ([autonomous] /
|
|
10
|
+
--auto sentinel) or for plan-execution sync.
|
|
11
|
+
ClickUp model: workspace > space > folder > list > task > nested subtasks;
|
|
12
|
+
statuses are defined per list with a type (open/custom/done/closed) and pinned
|
|
13
|
+
by role (open/wip/done/closed) in .clickup.json at init, never by name;
|
|
14
|
+
checklist items are subtasks; multi-assignee (assignees replace, so writes
|
|
15
|
+
send the union); native time_estimate on leaf tasks plus est: tags. MCP:
|
|
16
|
+
ClickUp MCP (clickup_* tools). Modes: paste-ready, MCP publish, autonomous
|
|
17
|
+
(write-through with allowlist), plan-execution. Implements 9 verbs
|
|
18
|
+
(task.create, task.move, checklist.check, task.close, task.due-date.set,
|
|
19
|
+
task.assignee.add, task.comment.add, task.parent.set, task.estimate.set).
|
|
20
|
+
Requires @llodev/pm-tasks-core.
|
|
21
|
+
license: MIT
|
|
22
|
+
metadata:
|
|
23
|
+
version: 1.0.0
|
|
24
|
+
tags:
|
|
25
|
+
- agent-skill
|
|
26
|
+
- clickup
|
|
27
|
+
- plan-to-tasks
|
|
28
|
+
- pm-tools
|
|
29
|
+
- clickup-mcp
|
|
30
|
+
family: pm-tasks
|
|
31
|
+
role: adapter
|
|
32
|
+
tool: clickup
|
|
33
|
+
compatibility:
|
|
34
|
+
agents:
|
|
35
|
+
- claude-code
|
|
36
|
+
- cursor
|
|
37
|
+
- codex
|
|
38
|
+
- windsurf
|
|
39
|
+
- cline
|
|
40
|
+
- roo-code
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
# pm-tasks-clickup
|
|
44
|
+
|
|
45
|
+
ClickUp adapter for the `@llodev/pm-tasks-*` family. Publishes generic cards as ClickUp tasks with subtasks and dispatches the nine CRUD verbs through the ClickUp MCP. Tool names below omit the server prefix your agent adds (for example `mcp__clickup__`). Every call carries `workspace_id` from `.clickup.json`.
|
|
46
|
+
|
|
47
|
+
## Routing
|
|
48
|
+
|
|
49
|
+
| Trigger | Signal | Path |
|
|
50
|
+
| -------------- | ---------------------------------------------------------------------- | --------------------------------------------- |
|
|
51
|
+
| Paste-only | No ClickUp MCP connected | Phase 4 only: Markdown description |
|
|
52
|
+
| MCP publish | ClickUp MCP connected + `.clickup.json` present | Phase 4 → 5 (task, then one subtask per item) |
|
|
53
|
+
| Autonomous | `[autonomous]` / `--auto` sentinel **and** `autonomous.enabled: true` | Phase 5b (write-through, no preview) |
|
|
54
|
+
| CRUD ops | Verb on an existing task (id or `https://app.clickup.com/t/<task_id>`) | Phase 6: jump directly |
|
|
55
|
+
| Plan-execution | Plan file path, plan slug or title list, with `.clickup.json` | Phase 7 (discover + dispatch) |
|
|
56
|
+
| No config | MCP connected, no `.clickup.json` | § Init, path (b), before anything else |
|
|
57
|
+
|
|
58
|
+
## ClickUp model
|
|
59
|
+
|
|
60
|
+
- **Hierarchy:** workspace → space → folder (optional) → list → task → subtasks (nested, any depth). Work lives in lists; a list id is a digit string.
|
|
61
|
+
- **Statuses are per list** (inherited from the folder or space unless the list overrides them). Each has a `type`: exactly one `open`, one `closed`, an optional `done`, any number of `custom`. No type means "in progress", so the user picks `wip` at `init`. The `closed` type is often a cancellation ("cancelled"), not a success.
|
|
62
|
+
- **Roles pinned per list** in `.clickup.json` → `lists[].statuses`: `open`, `wip` (optional), `done` (the `done`-type status, else the `closed` one), `closed` (only when distinct from `done`). Verbs resolve a role to the pinned name, compare names trimmed and case-insensitively, and send the pinned name verbatim, so localized names work.
|
|
63
|
+
- **Checklist items are subtasks.** The MCP can read native checklists (`clickup_get_task` with `include: ["checklists"]`) but has no tool that creates or ticks them. `checklist.check` takes the subtask id as `itemId` and the parent task id as `checklistId`.
|
|
64
|
+
- **Multi-assignee, replace semantics:** `clickup_update_task.assignees` replaces the whole set. `task.assignee.add` reads the task and writes the union; it never removes anyone.
|
|
65
|
+
- **Writes return an envelope, not a task:** `{success, task_id, custom_id, task_url}` (`clickup_move_task`: `new_list_id`, no URL). Only `clickup_get_task` returns a task (bare and flat). Errors are `{"error": "<text>"}`.
|
|
66
|
+
- **Dates are calendar days:** a `YYYY-MM-DD` value is stored as 04:00 in the account's timezone. Compute "today", "tomorrow" or "next Friday" from `clickup_get_user.current_time`, never from your own clock.
|
|
67
|
+
- **Identity:** `"me"` resolves to whoever the MCP is authenticated as, a person or an AI-agent account. Nothing branches on which. A separate agent account for autonomous runs is an option, not a requirement; a manager publishing, a team member publishing and an agent executing all use the same verbs.
|
|
68
|
+
|
|
69
|
+
**Before any write, ask:**
|
|
70
|
+
|
|
71
|
+
- **Which list is home?** Status verbs resolve against the task's home list; a list missing from `lists[]` (or from `autonomous.scope.lists`) is a stop, not a guess.
|
|
72
|
+
- **Role or place?** `open`/`wip`/`done` change the status; a list id moves the task. Re-parenting moves it too.
|
|
73
|
+
- **Does this field replace?** Assignees and the `est:` tag set are rewritten whole: read first, write the result.
|
|
74
|
+
- **Whose clock?** Any relative date comes from `clickup_get_user.current_time`.
|
|
75
|
+
- **Did it already happen?** `ALREADY_IN_STATE` and `ok: true` without a write are success; a re-run with the same `clientToken` must not duplicate.
|
|
76
|
+
|
|
77
|
+
## Phase 4: ClickUp formatting
|
|
78
|
+
|
|
79
|
+
Apply the generic card from [`../pm-tasks-core/references/generic-card.md`](../pm-tasks-core/references/generic-card.md), then map:
|
|
80
|
+
|
|
81
|
+
- Title → `name`. Sections → Markdown headings in `markdown_description` (literal newlines).
|
|
82
|
+
- Labels → `tags` (ClickUp stores tag names lowercased). Priority → `urgent`, `high`, `normal` or `low` (`medium` becomes `normal`; anything else is dropped). Due date → `due_date` (`YYYY-MM-DD`).
|
|
83
|
+
- Initial status → `listOrSectionId` is a status **name** that exists on the target list (usually its pinned `open`), or empty for the list default. Never `open`/`wip`/`done`: `task.create` does not resolve roles, and ClickUp rejects a name the list lacks.
|
|
84
|
+
- Estimate → not at create time: call `task.estimate.set` after the task (and its subtasks) exist, because the leaf rule depends on whether it has subtasks.
|
|
85
|
+
- Publishing from a plan file → put `[plan:<slug>]` in the description so Phase 7 can find the task by slug.
|
|
86
|
+
- **Checklists:** paste-ready renders each item as a Markdown task list line (`- [ ] item`); ClickUp keeps that text verbatim in the description and shows checkboxes, which is fine for a human. MCP publish creates **subtasks** instead (Phase 5), because only subtasks are addressable by `checklist.check`.
|
|
87
|
+
|
|
88
|
+
## Phase 5: MCP publish
|
|
89
|
+
|
|
90
|
+
**Prerequisite:** the ClickUp MCP connected in your agent (remote server `https://mcp.clickup.com/mcp`; it handles OAuth, so the adapter never sees a credential), and `.clickup.json`.
|
|
91
|
+
|
|
92
|
+
Strict order: 1 config → 2 duplicate lookup → 3 preview & approval → 4 publish → 5 follow-ups → 6 confirm; 7 covers errors.
|
|
93
|
+
|
|
94
|
+
1. **Config:** target list = the requested list or `defaultListId`. It must be in `lists[]`: a task created elsewhere works, but every later status verb on it fails `list_not_configured`.
|
|
95
|
+
2. **Duplicate lookup** (when you pass a `clientToken`): `clickup_search {keywords: "ct:<token>"}` without brackets, because ClickUp stores the description with the brackets escaped (`\[ct:…\]`). For a `type: "task"` hit, confirm with `clickup_get_task` that `text_content` contains `[ct:<token>]`, then reuse that task: skip `task.create` in step 4 and create only the missing subtasks.
|
|
96
|
+
3. **Preview & approval:** name, list, initial status, tags, priority, due date, assignees, subtasks, estimate.
|
|
97
|
+
4. **Publish:** `task.create` with the `clientToken` (the transport appends the `[ct:<token>]` footer). Then one `clickup_create_task {list_id, name, parent: <parent id>}` per checklist item, in the parent's list. On a re-run, read `clickup_get_task {task_id, include: ["subtasks"]}` first and skip item names already present.
|
|
98
|
+
5. **Follow-ups:** `task.assignee.add`, then `task.estimate.set` on the parent and, if the plan estimates items, on the subtasks.
|
|
99
|
+
6. **Confirm:** write each task as a link with its name as the text, `[Task name](https://app.clickup.com/t/<task_id>)`; never a bare URL.
|
|
100
|
+
7. **Errors:** surface the server message. There is no rollback: subtasks created before a failure stay. Re-run with the same `clientToken`; steps 2 and 4 resume without duplicates.
|
|
101
|
+
|
|
102
|
+
### Attribution (opt-in)
|
|
103
|
+
|
|
104
|
+
Read `config.attribution`. If `enabled === true`, append the `descriptionFooter` from `getAttribution()` to the description and start comments with `commentPrefix` (`autonomousCommentPrefix` in autonomous mode). The transport sends text verbatim and adds nothing. See [`../pm-tasks-core/references/attribution.md`](../pm-tasks-core/references/attribution.md).
|
|
105
|
+
|
|
106
|
+
## Phase 5b: Autonomous
|
|
107
|
+
|
|
108
|
+
Skip Phase 5 step 3 (preview & approval). Apply [`../pm-tasks-core/references/autonomous-mode.md`](../pm-tasks-core/references/autonomous-mode.md). `init` writes `autonomous.enabled: false` on purpose: if it is not explicitly `true`, stop and ask the human.
|
|
109
|
+
|
|
110
|
+
**You are the gate.** The transport cannot tell autonomous from interactive calls and checks none of `allow`, `scope.lists` or `rateLimit`. Before every write, check the verb is in `autonomous.allow` and the task's home list is in `autonomous.scope.lists` (all `lists[]` when scope is absent). The doctor validates the shape (C-CFG-2, C-CFG-3, C-CLK-6); only the status verbs fail closed on their own, with `list_not_configured`.
|
|
111
|
+
|
|
112
|
+
> **MANDATORY READ before the first autonomous write:** [`references/autonomous.md`](references/autonomous.md) (scope rules, how to learn a task's home list, escalation, audit log).
|
|
113
|
+
|
|
114
|
+
### Continuous operation in multi-task loops
|
|
115
|
+
|
|
116
|
+
Mirror each task transition in ClickUp as it happens; NEVER batch at the end of the loop.
|
|
117
|
+
|
|
118
|
+
| Transition | Canonical verb → ClickUp call |
|
|
119
|
+
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
120
|
+
| Task started | `task.move` (`wip`) → `clickup_update_task {status: <pinned wip>}`; then stamp the start date if the team uses it (below) |
|
|
121
|
+
| Subtask checked | `checklist.check` → `clickup_update_task {status: <pinned done>}` on the subtask |
|
|
122
|
+
| Task completed | `task.move` (`done`), `task.comment.add` with the commit SHA and `clientToken: <sha>`, then `task.close` (a no-op after the move) |
|
|
123
|
+
| Task failed | `task.comment.add` with the failure mode, `task.assignee.add` of the `defaults.escalateToAlias` member. Do NOT call `task.move(_, "done")` or `task.close`. |
|
|
124
|
+
|
|
125
|
+
**Lifecycle fidelity:** ClickUp stamps no start date. When the list or team tracks start dates, follow the `wip` move with `clickup_update_task {task_id, start_date: <today from clickup_get_user.current_time>}`; writing `start_date` alone leaves `due_date` untouched. At close, `due_date` stays = the plan: never overwrite it. ClickUp leaves `date_closed` null for a `done`-type status, so completion is read from the status, not from `date_closed`. See [`../pm-tasks-core/references/lifecycle-fidelity.md`](../pm-tasks-core/references/lifecycle-fidelity.md).
|
|
126
|
+
|
|
127
|
+
## Phase 6: CRUD operations (existing tasks)
|
|
128
|
+
|
|
129
|
+
> **MANDATORY READ:** [`references/operations.md`](references/operations.md) before the first CRUD verb of a session: exact parameters, result shapes, every `reason` token and its fix. **Do NOT load** [`references/estimation.md`](references/estimation.md) unless the verb is `task.estimate.set`.
|
|
130
|
+
|
|
131
|
+
| Core verb | ClickUp calls | Input that matters | When nothing changes |
|
|
132
|
+
| ------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------- |
|
|
133
|
+
| `task.create` | `clickup_create_task` | `boardOrProjectId` = list id; `listOrSectionId` = status name or empty | n/a (duplicate lookup is yours) |
|
|
134
|
+
| `task.move` | `clickup_get_task` → `clickup_update_task {status}` or `clickup_move_task` | `open` / `wip` / `done`, or a numeric list id (root tasks only) | `ALREADY_IN_STATE` |
|
|
135
|
+
| `checklist.check` | `clickup_get_task` → `clickup_update_task {status}` | `itemId` = subtask id, `checklistId` = parent task id | `ALREADY_IN_STATE` |
|
|
136
|
+
| `task.close` | `clickup_get_task` → `clickup_update_task {status: <pinned done>}` | Already at the pinned `done` **or** `closed` status → no write | `ok: true` |
|
|
137
|
+
| `task.due-date.set` | `clickup_get_task` (+ `clickup_get_user` once) → `clickup_update_task {due_date}` | `YYYY-MM-DD`; clearing is not supported | `ok: true` |
|
|
138
|
+
| `task.assignee.add` | (`clickup_resolve_assignees`) → `clickup_get_task` → `clickup_update_task {assignees}` | Numeric id, `"me"`, email or username; writes current ∪ new | `ok: true`, `added: false` |
|
|
139
|
+
| `task.comment.add` | (`clickup_get_task_comments`) → `clickup_create_comment` | `clientToken` → `[ct:<token>] ` prefix, first comments page scanned first | `ok: true`, the existing comment |
|
|
140
|
+
| `task.parent.set` | `clickup_get_task` → `clickup_update_task {parent}` | Moves the task into the parent's list; cannot detach | `ok: true` |
|
|
141
|
+
| `task.estimate.set` | `clickup_get_task` → `clickup_update_task {time_estimate}` + tag tools | Pass the `.clickup.json` `estimation` block as `config` | `ok: true`, zero writes |
|
|
142
|
+
|
|
143
|
+
**`ALREADY_IN_STATE` means "nothing to do", not a failure.** Report it as done; plan-execution hooks count it as skipped without failing the run.
|
|
144
|
+
|
|
145
|
+
**Choosing a `task.move` target:** a status change inside the list → a role word. A different list → its numeric id, and only for a root task (a subtask answers `subtask_cannot_move`: move its parent). ClickUp requires the task's current status name to exist in the destination list, and if the destination is not in `lists[]`, every later status verb on that task fails `list_not_configured` until `init` registers it.
|
|
146
|
+
|
|
147
|
+
**When a verb fails with `INVALID_REQUEST`, read `details.reason`:**
|
|
148
|
+
|
|
149
|
+
| `reason` | Meaning → next step |
|
|
150
|
+
| ---------------------- | ----------------------------------------------------------------------------------------------------------- |
|
|
151
|
+
| `list_not_configured` | The task's home list is not in `lists[]` (hand-made task, list move, re-parenting) → re-run `init` |
|
|
152
|
+
| `role_not_configured` | No status pinned for that role (often `wip`) → re-run `init` and pick one |
|
|
153
|
+
| `status_rejected` | The pinned status was renamed or deleted in ClickUp → run the doctor (C-CLK-8 names list and role), re-init |
|
|
154
|
+
| `subtask_cannot_move` | List moves are root-only → move the parent |
|
|
155
|
+
| `not_a_checklist_item` | `itemId`'s parent is not `checklistId` → re-read the parent's subtasks |
|
|
156
|
+
| `assignee_unresolved` | The user did not resolve to exactly one id → pass the numeric id or a unique email |
|
|
157
|
+
| `invalid_due_date` | Not a real `YYYY-MM-DD` date (also what `null` gets: clearing is unsupported) |
|
|
158
|
+
|
|
159
|
+
`task.parent.set` with an empty `parentId` is `NOT_APPLICABLE` (`detach_unsupported`): detach in the ClickUp UI. Beyond refusing a task as its own parent (`self_parent`), it has no cycle guard; ClickUp decides.
|
|
160
|
+
|
|
161
|
+
**`<task-ref>` resolution:** task URL `https://app.clickup.com/t/<task_id>` (last segment) → native task id → `[ct:<token>]` lookup (Phase 5 step 2) or the audit log → otherwise `REF_NOT_RESOLVED` with candidates. Custom task ids (`DEV-1234`) are not supported: pass the native id.
|
|
162
|
+
|
|
163
|
+
**Members and aliases:** `init` can cache `members[]` with unique `alias` values. Resolve an alias to its `members[].id` yourself before `task.assignee.add`: the transport accepts ids, `"me"`, emails and usernames, not aliases.
|
|
164
|
+
|
|
165
|
+
### Estimation (`task.estimate.set`)
|
|
166
|
+
|
|
167
|
+
> **MANDATORY READ:** [`references/estimation.md`](references/estimation.md) before the first estimate.
|
|
168
|
+
|
|
169
|
+
The core runtime does not read `.clickup.json` for you: pass its `estimation` block as the request `config`. No block, or `enabled: false` → `NOT_APPLICABLE`. Time strategies with `clickupTarget: "time"` write `time_estimate` (minutes) **only on a leaf task**; a task with subtasks gets the tag only, because ClickUp views roll subtask estimates up into the parent. The `est:<slug>` tag (`ideal_hours` 2 → `est:2-ideal-hours`) replaces any other `est:*` tag; a re-run writes nothing. A failure after a write returns `ok: false`, `details.partial: true` with `applied[]` and `failedStep`: re-run the same call.
|
|
170
|
+
|
|
171
|
+
## Phase 7: Plan-execution mode
|
|
172
|
+
|
|
173
|
+
Load `.clickup.json` with `requireConfig`, then call `discoverPlanTasks` (both from `@llodev/pm-tasks-core`) with this lister:
|
|
174
|
+
|
|
175
|
+
```text
|
|
176
|
+
clickup_filter_tasks {
|
|
177
|
+
list_ids: autonomous.scope.lists, else every lists[].id,
|
|
178
|
+
subtasks: false, // subtasks are checklist items, not plan tasks
|
|
179
|
+
statuses: [every open- and custom-type status name of those lists],
|
|
180
|
+
page: 0, then the response's next_page while has_more is true
|
|
181
|
+
}
|
|
182
|
+
→ [{ id, title: name }] // titles or a .md plan
|
|
183
|
+
→ [{ id, title: name, description }] // bare slug: description = text_content
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
Read the status names at the start of each discovery, with one `clickup_get_list {list_id}` per scoped list: pass every name whose `type` is not `done` or `closed`, and never a `done`- or `closed`-type name. Filtering on the pinned open and wip names alone misses tasks parked in another custom status (`on hold`, `planning`, `at risk`): they come back `missing`, and creating them duplicates them in ClickUp.
|
|
187
|
+
|
|
188
|
+
Each page answers `{tasks[], count, page, has_more, next_page}`. Follow `next_page` while `has_more` is true; if `has_more` is true without a `next_page`, stop and report instead of returning a partial list.
|
|
189
|
+
|
|
190
|
+
NEVER use `include_closed: false` as the done filter: it does not drop `done`-type tasks. The summary has no description, and core's `discoverPlanTasks` matches a bare-slug `planRef` against each returned task's `description` (it must contain `[plan:<slug>]`). So in bare-slug mode the lister reads each candidate with `clickup_get_task` and returns `description: text_content`; `markdown_description` escapes the brackets and would never match. Without a `description`, bare-slug discovery returns `found: []`.
|
|
191
|
+
|
|
192
|
+
The skill returns `{ found, missing, ambiguous }`; the calling agent decides (create missing via Phase 4 + 5, disambiguate, proceed). Record progress with the standard verbs. With core's `onTaskStart` / `onTaskComplete` hooks, pass the **role words** `listsWipId: "wip"` and `listsDoneId: "done"` (a numeric value would move the task to another list), `checklistId` = parent task id and `checklistItemId` = subtask id. Full contract: [`../pm-tasks-core/references/plan-execution.md`](../pm-tasks-core/references/plan-execution.md).
|
|
193
|
+
|
|
194
|
+
## Result envelope
|
|
195
|
+
|
|
196
|
+
The runtime returns `{ ok: true, data }` or `{ ok: false, code, details }`. Report it in the core contract shape ([`../pm-tasks-core/references/contract.md`](../pm-tasks-core/references/contract.md) § Result envelope):
|
|
197
|
+
|
|
198
|
+
```json
|
|
199
|
+
{
|
|
200
|
+
"ok": true,
|
|
201
|
+
"verb": "task.create",
|
|
202
|
+
"tool": "clickup",
|
|
203
|
+
"ref": { "id": "<task_id>", "url": "https://app.clickup.com/t/<task_id>", "alias": null },
|
|
204
|
+
"details": {}
|
|
205
|
+
}
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
Per-verb `data` (into `details`) and the failure codes are in [`references/operations.md`](references/operations.md) § Result envelope. Failures carry `details.verb`, `details.message` and, for `INVALID_REQUEST`/`NOT_APPLICABLE`, a stable `details.reason`.
|
|
209
|
+
|
|
210
|
+
## Known limitations
|
|
211
|
+
|
|
212
|
+
- No sprint verb: `task.sprint.set` answers `UNSUPPORTED_VERB`. ClickUp Sprints are lists; `task.move` with the sprint list id moves a root task there, but the task then leaves its home list, so later status verbs fail `list_not_configured` unless `init` registers the sprint list (multi-list membership is plan-limited and not used).
|
|
213
|
+
- Native checklists are read-only; unchecking a subtask whose pinned `done` status was renamed in ClickUp reports `ALREADY_IN_STATE` (run the doctor).
|
|
214
|
+
- No conditional update in ClickUp: read-then-write races are not guarded. Comment idempotency scans only the first comments page.
|
|
215
|
+
|
|
216
|
+
## Anti-patterns
|
|
217
|
+
|
|
218
|
+
> **MANDATORY READ before Phase 5 or 5b:** [`anti-patterns/clickup.md`](anti-patterns/clickup.md)
|
|
219
|
+
|
|
220
|
+
- NEVER hard-code a status name: names are per list, user-defined and often localized; use the pinned role.
|
|
221
|
+
- NEVER call `clickup_create_task_comment` (deprecated): use `clickup_create_comment`.
|
|
222
|
+
- NEVER send `assignees` without the current set: it replaces, silently unassigning people.
|
|
223
|
+
- NEVER put `- [ ]` checklists in the description on MCP publish: they cannot be checked by `checklist.check`.
|
|
224
|
+
- NEVER write a native estimate on a parent and its children: roll-up views count it twice.
|
|
225
|
+
- NEVER read a write response as a task: it is `{success, task_id, ...}` with no status, list or assignees.
|
|
226
|
+
|
|
227
|
+
## Standalone fallback
|
|
228
|
+
|
|
229
|
+
If `@llodev/pm-tasks-core` is not installed: ask for the minimum (title + checklist items) and produce a paste-ready ClickUp description with a `- [ ]` task list. Quality is degraded (no scope, audience or fidelity inference). Print: _"Install `@llodev/pm-tasks-core` for the full flow."_
|
|
230
|
+
|
|
231
|
+
## Config
|
|
232
|
+
|
|
233
|
+
`init` writes `./.clickup.json` (or `--output <path>`); the doctor reads `./.clickup.json` (or `--config <path>`); `createAdapter({ configPath })` takes the path you give. Schema: [`schemas/config.json`](schemas/config.json). No credential is ever stored in it.
|
|
234
|
+
|
|
235
|
+
> **Narration language.** When `.clickup.json` sets `locale`, agent-authored narration — comments the agent writes, autonomous commit/PR copy, code comments — MUST use it. The plan's language still governs task name, description and subtask text. The doctor's `C-LANG-1` warns if it is unset or has no installed i18n bundle. See pm-tasks-core § Narration language.
|
|
236
|
+
|
|
237
|
+
Key fields:
|
|
238
|
+
|
|
239
|
+
- `workspace` `{ id, name }`; `lists[]` `{ id, name, space?, folder?, statuses: { open, wip?, done, closed? } }`; `defaultListId`.
|
|
240
|
+
- `members[]` `{ id, name, email?, alias? }` (optional cache; `init` always writes an alias). `defaults.assigneeAlias` / `escalateToAlias` must be `"me"` or a member alias.
|
|
241
|
+
- `estimation` `{ strategy, clickupTarget: "time" | "none", enabled?, hoursPerDay?, scale?, sizeMap? }` (optional; `init` writes `enabled: true`).
|
|
242
|
+
- `autonomous` `{ enabled, allow[], scope: { lists[] }, rateLimit, auditLog }`; `attribution` (core block); `locale`.
|
|
243
|
+
|
|
244
|
+
## Init
|
|
245
|
+
|
|
246
|
+
See [`../pm-tasks-core/references/init-ux.md`](../pm-tasks-core/references/init-ux.md). Discovery is read-only; nothing is written to ClickUp. Two paths:
|
|
247
|
+
|
|
248
|
+
**(a) Terminal, with a token.** Set `CLICKUP_API_TOKEN` to a personal API token (ClickUp → Settings → Apps → API Token) in the environment, then run `npx @llodev/pm-tasks-clickup init`. It picks the workspace (asked only when there are several), the lists, then `wip` per list among its `custom` statuses. The token is read only from the environment: never paste it into chat, an issue or a config file.
|
|
249
|
+
|
|
250
|
+
**(b) Inside an agent session with the ClickUp MCP.** The CLI cannot reach your session's MCP, so its "run init inside an agent session" message means: you do the discovery and write the file.
|
|
251
|
+
|
|
252
|
+
1. `clickup_get_workspace_hierarchy {max_depth: "2"}` → the root is the workspace; spaces → folders → lists (pass the response's `next_cursor` back as `cursor` until there is none). Ask which lists to use.
|
|
253
|
+
2. Per list, `clickup_get_list {list_id}` → `statuses[]`. Pin `open` = first `open`-type by `orderindex`; `done` = first `done`-type, else the `closed`-type; `closed` = the `closed`-type when it differs from `done`. Ask the user to pick `wip` among the `custom` statuses (or leave it unset). Skip a list with no `open` or no `done`/`closed` status.
|
|
254
|
+
3. Optional: `clickup_get_workspace_members {workspace_id}` → `members[]` with unique lowercase aliases (not `"me"`, not digits only; ids as strings).
|
|
255
|
+
4. Write `.clickup.json` per the schema with `version: "1"`, `locale`, `defaultListId` = first list. Write the `autonomous` block only if the user wants it, as `{enabled: false, allow: [the nine verbs of manifest.json], scope: {lists: [the chosen list ids]}}` (the schema requires `allow`).
|
|
256
|
+
5. Run `npx @llodev/pm-tasks-clickup init --doctor`. Without `CLICKUP_API_TOKEN` its live checks (C-CLK-7, C-CLK-8) are skipped: in the session, compare each list's pinned statuses with the `statuses[]` of `clickup_get_list {list_id}` yourself, and re-pin any that no longer exists.
|
|
257
|
+
|
|
258
|
+
**Doctor:** `npx @llodev/pm-tasks-clickup init --doctor [--json] [--fix-hints-only] [--config <path>]` runs core's shared checks plus C-CLK-1…4 and 6 (config, workspace id, pinned `open`/`done`, estimation coherence, scope and aliases). With `CLICKUP_API_TOKEN` set it also runs the live checks: C-CLK-7 (workspace reachable) and C-CLK-8 (each pinned status still exists in its list). Without a token they are skipped with an advisory.
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# ClickUp ingestion anti-patterns
|
|
2
|
+
|
|
3
|
+
Apply when Phase 4, 5, 5b, 6 or 7 targets ClickUp. Formatting and publish detail live in [`../SKILL.md`](../SKILL.md); verb detail in [`../references/operations.md`](../references/operations.md).
|
|
4
|
+
|
|
5
|
+
## Paste health and fallbacks
|
|
6
|
+
|
|
7
|
+
- Generic card title → `name`; if absent, take the first non-empty heading.
|
|
8
|
+
- Descriptions are Markdown with literal newlines, sent as `markdown_description`.
|
|
9
|
+
- No `.clickup.json` → produce the paste-ready description and point to `init`. Do not guess list ids or status names to publish anyway.
|
|
10
|
+
|
|
11
|
+
## ClickUp
|
|
12
|
+
|
|
13
|
+
**NEVER hard-code a status name.**
|
|
14
|
+
Statuses are defined per list, named by each team and often localized ("to do", "a fazer", "pendiente"). Two lists in one workspace can disagree. Always go through the role pinned in `lists[].statuses` (`open`, `wip`, `done`, `closed`). A name that does not exist on the task's list is rejected (`Status does not exist`).
|
|
15
|
+
|
|
16
|
+
**NEVER pass `open`, `wip` or `done` as the `task.create` status.**
|
|
17
|
+
`listOrSectionId` is sent to ClickUp as a status name; role words are resolved only by `task.move`, `checklist.check` and `task.close`. Pass the list's pinned `open` name, or leave it empty for the list default.
|
|
18
|
+
|
|
19
|
+
**NEVER pass a list id where you mean a status.**
|
|
20
|
+
`task.move` treats six or more digits as a destination list: the task leaves its list, and if that list is not in `lists[]`, every later status verb on it fails `list_not_configured`. The same holds for core's plan-execution hooks: `listsWipId` / `listsDoneId` are `"wip"` / `"done"`, not ids.
|
|
21
|
+
|
|
22
|
+
**NEVER call `clickup_create_task_comment`.**
|
|
23
|
+
It is deprecated. Use `clickup_create_comment {entity_type: "task", entity_id, comment_text}`.
|
|
24
|
+
|
|
25
|
+
**NEVER assume `update_task.assignees` adds.**
|
|
26
|
+
It replaces the whole set: sending one id silently unassigns everyone else, including the human who owns the task. `task.assignee.add` reads the task and writes the union; if you call `clickup_update_task` yourself, do the same.
|
|
27
|
+
|
|
28
|
+
**NEVER pass a `members[].alias` as the assignee.**
|
|
29
|
+
The transport resolves ids, `"me"`, emails and usernames; an alias is none of these, so it fails closed (`assignee_unresolved`) or, worse, may match someone else's username. Map the alias to `members[].id` first.
|
|
30
|
+
|
|
31
|
+
**NEVER fake checklists with `- [ ]` in the description on MCP publish.**
|
|
32
|
+
ClickUp renders the task list, but nothing can address those boxes: `checklist.check` works on subtasks only, and the MCP cannot write native checklists either. Task-list lines are for paste-ready output, where a human ticks them by hand.
|
|
33
|
+
|
|
34
|
+
**NEVER write a native estimate on a parent and on its children.**
|
|
35
|
+
ClickUp keeps a parent's own `time_estimate`, and spaces with time-estimate roll-up show parent plus children in views: the effort is counted twice. Native estimates go on leaves; the parent gets the `est:` tag only. Create subtasks before estimating the parent.
|
|
36
|
+
|
|
37
|
+
**NEVER use `include_closed: false` as the "not done" filter.**
|
|
38
|
+
`clickup_filter_tasks` still returns `done`-type tasks with it. Filter with `statuses: [<every open- and custom-type status name of the scoped lists>]`, read with one `clickup_get_list` per list, and `subtasks: false`.
|
|
39
|
+
|
|
40
|
+
**NEVER filter plan tasks on the pinned open and wip names alone.**
|
|
41
|
+
A task parked in another custom status (`on hold`, `planning`, `at risk`) drops out of the result, comes back `missing`, and gets created a second time. Pass every status name whose type is not `done` or `closed`.
|
|
42
|
+
|
|
43
|
+
**NEVER read a write response as a task.**
|
|
44
|
+
`clickup_create_task` / `clickup_update_task` return `{success, task_id, custom_id, task_url}`; `clickup_move_task` returns `new_list_id` and no URL. There is no status, list, parent or assignee in them: read `clickup_get_task` when you need state.
|
|
45
|
+
|
|
46
|
+
**NEVER search for `[ct:<token>]` with the brackets.**
|
|
47
|
+
ClickUp stores the description with escaped brackets (`\[ct:…\]`). Search `clickup_search {keywords: "ct:<token>"}` and confirm against `text_content`.
|
|
48
|
+
|
|
49
|
+
**NEVER compute a relative date from your own clock.**
|
|
50
|
+
"Today" or "tomorrow" depends on the ClickUp account's timezone, and date-only values are stored at 04:00 local time. Read `clickup_get_user.current_time` first, then send `YYYY-MM-DD`.
|
|
51
|
+
|
|
52
|
+
**NEVER overwrite `due_date` at close, or wait for `date_closed`.**
|
|
53
|
+
`due_date` is the plan. ClickUp leaves `date_closed` null for `done`-type statuses: completion is the status itself.
|
|
54
|
+
|
|
55
|
+
**NEVER report `ALREADY_IN_STATE` as a failure.**
|
|
56
|
+
`task.move` and `checklist.check` use it to say "nothing to do". Retrying or escalating on it creates noise and, in loops, duplicate comments.
|
|
57
|
+
|
|
58
|
+
**NEVER expect `task.parent.set` to leave the task where it was.**
|
|
59
|
+
ClickUp moves the child into the parent's list. Check that list is configured (and in autonomous scope) before re-parenting across lists. Detaching is not possible through the MCP.
|
|
60
|
+
|
|
61
|
+
**NEVER delete or archive from this skill.**
|
|
62
|
+
The MCP exposes `clickup_delete_task`, but deletion, archiving and renaming are forbidden autonomous verbs and outside this adapter. Ask the human to clean up in the ClickUp UI.
|
|
63
|
+
|
|
64
|
+
**NEVER put the API token anywhere but the environment.**
|
|
65
|
+
`CLICKUP_API_TOKEN` is read only from the environment, by `init` and the doctor, for read-only discovery. Never paste it into chat, an issue, a commit or `.clickup.json`; the MCP uses its own OAuth.
|
|
66
|
+
|
|
67
|
+
## Cross-tool
|
|
68
|
+
|
|
69
|
+
**NEVER** carry ClickUp's quirks (per-list statuses, union assignee writes, list moves by id, leaf-only estimates) to another adapter after switching targets mid-chat, or bring another adapter's rules here (Linear's single assignee, Trello's due-date overwrite at close). Re-load that adapter's SKILL.md.
|
|
70
|
+
|
|
71
|
+
## The ClickUp UI is the human's audit trail
|
|
72
|
+
|
|
73
|
+
`clickup_get_task` returns current values, not history. When auditing an autonomous run, check the task's activity in ClickUp, alongside the runtime audit log.
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
import { type Runtime } from "@llodev/pm-tasks-core/runtime";
|
|
2
|
+
import { type McpCaller } from "./transport-clickup.js";
|
|
3
|
+
export type { McpCaller };
|
|
4
|
+
export interface CreateAdapterOptions {
|
|
5
|
+
/** Absolute or cwd-relative path to the .clickup.json config file. */
|
|
6
|
+
configPath: string;
|
|
7
|
+
/** Caller-supplied MCP dispatcher (proxies to the `clickup_*` tools, no server prefix). */
|
|
8
|
+
mcp: McpCaller;
|
|
9
|
+
/** Optional session id for audit-log correlation. Defaults to generateSession() when omitted. */
|
|
10
|
+
session?: string;
|
|
11
|
+
/** Optional locale hint (forwarded from the .clickup.json locale field for narration). */
|
|
12
|
+
language?: string;
|
|
13
|
+
}
|
|
14
|
+
/**
|
|
15
|
+
* Construct a ready-to-use ClickUp adapter Runtime. Reads and parses the config
|
|
16
|
+
* from configPath, wires the ClickUp MCP transport to the caller-supplied
|
|
17
|
+
* McpCaller, and returns the same Runtime shape as createCoreRuntime. No MCP
|
|
18
|
+
* call is made here.
|
|
19
|
+
*
|
|
20
|
+
* The config is read twice (here for the transport, again by createCoreRuntime
|
|
21
|
+
* for the handler layer). Construction rejects only a config that is not an
|
|
22
|
+
* object, has no non-empty string `workspace.id`, has a `lists` that is not an
|
|
23
|
+
* array, or has an `estimation` that is not an object. Everything else is left
|
|
24
|
+
* to `init` and `doctor`, and each verb fails closed on what it needs (a list
|
|
25
|
+
* without pinned statuses makes the status verbs INVALID_REQUEST).
|
|
26
|
+
*
|
|
27
|
+
* task.estimate.set: the runtime passes the request through unchanged and does
|
|
28
|
+
* not read the config's `estimation` block, so the caller passes that block as
|
|
29
|
+
* `req.config` (cast to core's `EstimationConfig`: ClickUp's block carries
|
|
30
|
+
* `clickupTarget` instead of `jiraTarget`). The request config drives strategy,
|
|
31
|
+
* target, scale, sizeMap and hoursPerDay. The block in .clickup.json is the on/off
|
|
32
|
+
* switch: when it is absent or says `enabled: false` (or the request config does),
|
|
33
|
+
* the verb is NOT_APPLICABLE; a request without `config` is INVALID_REQUEST.
|
|
34
|
+
*
|
|
35
|
+
* task.sprint.set is not in the manifest: the transport has no taskSprintSet, so
|
|
36
|
+
* the runtime answers UNSUPPORTED_VERB without an MCP call.
|
|
37
|
+
*/
|
|
38
|
+
export declare function createAdapter(opts: CreateAdapterOptions): Promise<Runtime>;
|
|
39
|
+
//# sourceMappingURL=adapter.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,KAAK,OAAO,EAAkB,MAAM,+BAA+B,CAAC;AAEhG,OAAO,EAA8C,KAAK,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAEpG,YAAY,EAAE,SAAS,EAAE,CAAC;AAE1B,MAAM,WAAW,oBAAoB;IACnC,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;IACnB,2FAA2F;IAC3F,GAAG,EAAE,SAAS,CAAC;IACf,iGAAiG;IACjG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0FAA0F;IAC1F,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAgDD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC,CAahF"}
|