ClickUp Continuous Integration

Overview

Keep ordinary pull-request checks deterministic and secretless while retaining a separately protected probe for provider-contract drift.

Prerequisites

• The repository's test runner, ClickUp transport boundary, and CI platform
• Sanitized fixtures for v2 and any selected v3 response shapes
• A protected non-production credential and strict request ceiling for the optional live lane

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, adapters, configuration names, tests, and evidence. Use WebFetch only for current official ClickUp documentation. Use Write or Edit after confirming the target file, Workspace boundary, and requested mode.

Current Contract

• Pin the official v2 and v3 OpenAPI inputs separately; do not model v3 as a complete replacement.
• Offline tests cover authentication, plan denial, pagination, rate headers, webhook typing, and redaction.
• The live lane uses GET /api/v2/user or GET /api/v2/team; it does not create or update work.
• Fork code never receives ClickUp credentials.

Authentication

Use a personal token only for accountable individual/testing work or OAuth Authorization Code for a user-facing integration. Inject the token server-side through a governed secret reference, send it in Authorization, verify authorized Workspace IDs, and never print the token, OAuth client secret, or webhook secret.

Instructions

1. Inventory every endpoint, version, fixture, secret reference, and network-bearing test.
2. Generate or validate transport types against pinned official OpenAPI inputs.
3. Add fixtures for success, common OAuth errors, 429 responses, null webhook fields, and page boundaries.
4. Test redaction, retry eligibility, version routing, and workspace allow-list enforcement.
5. Place the bounded live probe behind a trusted event and protected environment.
6. Publish status, schema versions, request count, and redacted drift evidence.

Approval Boundaries

Do not expose credentials to fork code or let CI create tasks, webhooks, members, ACLs, or hierarchy objects without a separate environment approval and cleanup plan.

Output

Return offline coverage, pinned schema digests, live-lane eligibility/result, workspace boundary, request count, and any provider drift.

Error Handling

ClickUp Error Diagnosis

Overview

Classify the failure before changing code so authentication, workspace scope, plan gates, schema drift, and transient provider faults receive different remedies.

Prerequisites

• A redacted status code, ClickUp error code/message, endpoint version, and request shape
• The authorized Workspace ID, auth mode, and current plan facts from an owner
• Access to current ClickUp docs and status information

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, adapters, configuration names, tests, and evidence. Use WebFetch only for current official ClickUp documentation. Use Write or Edit after confirming the target file, Workspace boundary, and requested mode.

Current Contract

• OAUTH_017 can indicate a missing Authorization header; workspace authorization and revoked-token families have distinct codes.
• Browser-side CORS failures require a server-side boundary, not a permissive token-bearing frontend workaround.
• A 429 is per token; inspect X-RateLimit-Limit, X-RateLimit-Remaining, and Unix X-RateLimit-Reset.
• Retry only bounded transient failures; do not retry malformed requests or permission denials.

Authentication

Use a personal token only for accountable individual/testing work or OAuth Authorization Code for a user-facing integration. Inject the token server-side through a governed secret reference, send it in Authorization, verify authorized Workspace IDs, and never print the token, OAuth client secret, or webhook secret.

Instructions

1. Capture the method, versioned path, status, ClickUp error code, response type, and sanitized headers.
2. Confirm whether the caller uses a personal token or OAuth and whether the Workspace was authorized.
3. Validate path parameters, JSON content type, endpoint version, pagination cursor/page, and plan eligibility.
4. Separate 401/403, 404, 409-style state conflicts, 429, timeout, and 5xx classes.
5. Reproduce with the smallest read-only request and compare against the official reference.
6. Recommend the narrowest correction and record the post-fix probe.

Approval Boundaries

Do not regenerate credentials, reauthorize Workspaces, upgrade a plan, replay writes, or disclose task content merely to diagnose an error.

Output

Return failure class, evidence, likely cause, safe correction, retry decision, owner action, and verification result.

Error Handling

ClickUp Task Lifecycle

Overview

Operate the v2 task surface without duplicate creation, silent field loss, or unsafe deletion. Preserve a durable reconciliation trail for every attempted change.

Prerequisites

• An allow-listed Workspace and destination List with a confirmed status/assignee model
• A personal or OAuth token authorized for the target hierarchy
• A durable external source key, reconciliation store, and rollback policy

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, adapters, configuration names, tests, and evidence. Use WebFetch only for current official ClickUp documentation. Use Write or Edit after confirming the target file, Workspace boundary, and requested mode.

Current Contract

• Task creation uses POST /api/v2/list/LIST_ID/task; update and delete use the task resource path.
• Priorities are 1 urgent, 2 high, 3 normal, and 4 low.
• Existing Custom Fields are changed through Set/Remove Custom Field Value, not Update Task.
• Get Tasks returns 100 tasks per zero-based page and normally includes only home-List tasks; request Tasks in Multiple Lists explicitly with include_timl.

Authentication

Use a personal token only for accountable individual/testing work or OAuth Authorization Code for a user-facing integration. Inject the token server-side through a governed secret reference, send it in Authorization, verify authorized Workspace IDs, and never print the token, OAuth client secret, or webhook secret.

Instructions

1. Read the destination List, statuses, members, and accessible Custom Fields.
2. Normalize source records and validate names, dates in milliseconds, priorities, assignees, and field option IDs.
3. Search the reconciliation store before creating; never assume an undocumented idempotency header.
4. Render a dry-run of creates, updates, Custom Field calls, skips, and proposed removals.
5. Apply bounded writes, persist returned task IDs immediately, and stop on permission or schema drift.
6. Re-read affected tasks and reconcile values, counts, errors, and rollback handles.

Approval Boundaries

Require explicit approval before deletes, bulk status changes, reassignment, date shifts, cross-List moves, or Custom Field writes that consume plan-limited uses.

Output

Return dry-run/apply mode, created/updated/skipped/deleted counts, external-to-ClickUp ID map, verification result, and rollback handles. Identify every rejected or quarantined record with its safe remediation.

Error Handling

ClickUp Hierarchy and Views

Overview

Manage structural objects only after resolving their actual parent chain and downstream task impact. Keep discovery, planning, and mutation as separately reviewable phases.

Prerequisites

• An allow-listed Workspace and authorized hierarchy administrator
• A current inventory of Spaces, optional Folders, Lists, tags, views, and referenced tasks
• A reviewed desired-state plan and rollback or recreation evidence

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, adapters, configuration names, tests, and evidence. Use WebFetch only for current official ClickUp documentation. Use Write or Edit after confirming the target file, Workspace boundary, and requested mode.

Current Contract

• In v2, team_id is a Workspace ID; user groups are separate group resources.
• Lists may be folderless under a Space or nested under a Folder, so the parent endpoint matters.
• Views can exist at Workspace, Space, Folder, or List scope; use the matching endpoint.
• Hierarchy deletion can orphan assumptions in integrations even when the API accepts it.

Authentication

Use a personal token only for accountable individual/testing work or OAuth Authorization Code for a user-facing integration. Inject the token server-side through a governed secret reference, send it in Authorization, verify authorized Workspace IDs, and never print the token, OAuth client secret, or webhook secret.

Instructions

1. Inventory Workspace, Space, Folder, List, tag, and view IDs with parent relationships.
2. Map every desired change to its exact v2 endpoint and current object version.
3. Check task counts, automations, webhooks, views, and external references affected by the change.
4. Produce a create/update/delete plan with dependency order and rollback evidence.
5. Apply creates before dependent updates; isolate destructive actions behind approval.
6. Re-read the hierarchy and verify names, parents, privacy, views, and downstream references.

Approval Boundaries

Do not delete or privatize Spaces, Folders, Lists, views, or tags, or move production work across parents, without owner approval and an impact inventory.

Output

Return the before/after hierarchy graph, planned/applied operations, affected-task counts, unresolved references, and rollback evidence. Record the authorizer and exact Workspace scope.

Error Handling

ClickUp Integration Cost and Request Tuning

Overview

Optimize from observed request and feature usage without inventing prices or treating a plan upgrade as the default remedy.

Prerequisites

• Per-endpoint request counts, latency, 429s, page depth, polling intervals, and cache hit rates
• Current Workspace plan and feature-use facts supplied by an authorized owner
• Freshness objectives and an approved data-retention policy

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, adapters, configuration names, tests, and evidence. Use WebFetch only for current official ClickUp documentation. Use Write or Edit after confirming the target file, Workspace boundary, and requested mode.

Current Contract

• Rate limits are per token and currently vary by Workspace plan.
• Get Tasks returns at most 100 tasks per page; wasteful full scans multiply requests.
• Webhook delivery can replace polling but requires secure, durable event processing.
• Some features and parameters are plan-gated; current commercial price must come from the account owner.

Authentication

Use a personal token only for accountable individual/testing work or OAuth Authorization Code for a user-facing integration. Inject the token server-side through a governed secret reference, send it in Authorization, verify authorized Workspace IDs, and never print the token, OAuth client secret, or webhook secret.

Instructions

1. Measure requests by endpoint, token boundary, caller, result size, and business operation.
2. Identify duplicate reads, empty pages, overbroad polling, retry storms, and unnecessary writes.
3. Model pagination, conditional caching, webhook invalidation, and schedule consolidation.
4. Quantify custom-field uses and plan-gated operations separately from API request volume.
5. Compare alternatives against freshness, failure recovery, security, and owner-provided commercial facts.
6. Implement one bounded change and verify request, latency, error, and staleness deltas.

Approval Boundaries

Do not change a paid plan, reduce required audit/data controls, create broad webhooks, or accept stale work data without owner approval.

Output

Return baseline and projected request volume, feature-use facts, optimization decisions, measured savings, freshness impact, and residual risk.

Error Handling

ClickUp Work-Data Governance

Overview

Treat ClickUp content as potentially sensitive and keep compliance obligations separate from unsupported API assumptions.

Prerequisites

• A data-flow inventory covering tasks, descriptions, comments, attachments, members, webhooks, logs, and backups
• Authorized legal/security retention, deletion, residency, and access rules
• A scoped credential plus test fixtures that contain no real personal or confidential data

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, adapters, configuration names, tests, and evidence. Use WebFetch only for current official ClickUp documentation. Use Write or Edit after confirming the target file, Workspace boundary, and requested mode.

Current Contract

• API responses reflect what the authenticated user can access; access is not proof that downstream storage is permitted.
• Webhook payloads can include user and before/after data and must be classified before persistence.
• Do not invent a universal ClickUp GDPR export/delete endpoint; map each application copy and authorized API action.
• Evidence can retain counts, hashes, classifications, and deletion receipts without retaining work content.

Authentication

Use a personal token only for accountable individual/testing work or OAuth Authorization Code for a user-facing integration. Inject the token server-side through a governed secret reference, send it in Authorization, verify authorized Workspace IDs, and never print the token, OAuth client secret, or webhook secret.

Instructions

1. Trace every ClickUp field from collection through processing, storage, logs, analytics, backups, and deletion.
2. Classify direct identifiers, free text, attachments, secrets, regulated content, and business metadata.
3. Minimize fields and scopes, redact telemetry, encrypt approved storage, and set retention by class.
4. Define subject/access/deletion workflows across ClickUp and each downstream copy with legal ownership.
5. Test export and deletion on synthetic records, including backups, queues, and failed jobs.
6. Produce a gap register and implement only owner-approved remediation.

Approval Boundaries

Do not export, bulk delete, alter retention, scan private content, or claim legal compliance without the data owner and applicable legal/security approval.

Output

Return the data map, field classifications, auth boundary, retention/deletion controls, test receipts, gaps, and accountable owners.

Error Handling

ClickUp Redacted Diagnostic Bundle

Overview

Create supportable evidence while preventing a troubleshooting artifact from becoming a second sensitive-data store. Make every included field explainable to the named reviewer.

Prerequisites

• An incident identifier, approved output directory, retention deadline, and named reviewer
• A scoped credential stored outside command history and artifact content
• An allow-list of read-only probes and fields

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, adapters, configuration names, tests, and evidence. Use WebFetch only for current official ClickUp documentation. Use Write or Edit after confirming the target file, Workspace boundary, and requested mode.

Current Contract

• Useful evidence includes status, endpoint version, latency, response type, sanitized error code, and rate headers.
• GET /api/v2/user and GET /api/v2/team can prove identity and authorized Workspaces without reading task content.
• Provider status is separate from tenant authorization and application behavior.
• Authorization headers, response bodies, user emails, task names, comments, attachments, and webhook secrets are excluded.

Authentication

Use a personal token only for accountable individual/testing work or OAuth Authorization Code for a user-facing integration. Inject the token server-side through a governed secret reference, send it in Authorization, verify authorized Workspace IDs, and never print the token, OAuth client secret, or webhook secret.

Instructions

1. Confirm incident scope, collection owner, field allow-list, output path, and deletion deadline.
2. Inspect local configuration names and versions without printing values.
3. Run bounded read-only identity/workspace and status probes; capture only approved metadata.
4. Record sanitized rate headers, status codes, timings, schema digests, and local adapter versions.
5. Scan the bundle for credential and content patterns; require human review before sharing.
6. Hash, transfer through the approved channel, and delete or retain on schedule.

Approval Boundaries

Do not add raw headers, full environment dumps, task payloads, member records, or attachments to make the bundle more convenient.

Output

Return bundle path, SHA-256, included field classes, excluded classes, scan result, reviewer, sharing decision, and deletion deadline.

Error Handling

Deploy a ClickUp Integration

Overview

Release the integration as a reversible server-side boundary that keeps credentials out of clients and acknowledges webhooks quickly.

Prerequisites

• A tested server-side adapter, environment inventory, and rollback artifact
• Environment-scoped secret references and authorized Workspace allow-lists
• HTTPS webhook ingress, raw-body signature verification, durable queueing, and observability

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, adapters, configuration names, tests, and evidence. Use WebFetch only for current official ClickUp documentation. Use Write or Edit after confirming the target file, Workspace boundary, and requested mode.

Current Contract

• ClickUp tokens belong on the server; browser CORS errors are not solved by exposing a token.
• Webhook verification uses the raw request body, the webhook secret, HMAC-SHA256, and X-Signature.
• Webhook handlers should acknowledge within ClickUp's seven-second health boundary and process asynchronously.
• v2 and v3 base paths remain explicit per operation.

Authentication

Use a personal token only for accountable individual/testing work or OAuth Authorization Code for a user-facing integration. Inject the token server-side through a governed secret reference, send it in Authorization, verify authorized Workspace IDs, and never print the token, OAuth client secret, or webhook secret.

Instructions

1. Inventory deploy target, endpoint/version matrix, callback URLs, secret references, and Workspace allow-lists.
2. Build and test offline contracts, raw-body signature handling, queue idempotency, and redaction.
3. Deploy dark with outbound writes disabled and webhook registration unchanged.
4. Run bounded identity, Workspace, health, and synthetic signed-event probes.
5. Canary trusted traffic, watch rate/error/webhook-health metrics, and verify durable side effects.
6. Promote or roll back; then reconcile secrets, callbacks, queues, and deployment evidence.

Approval Boundaries

Require explicit approval before production traffic, webhook registration changes, task mutations, ACL changes, or irreversible infrastructure teardown.

Output

Return artifact digest, environment, version matrix, secret references, probe/canary result, webhook health, promotion decision, and rollback target.

Error Handling

ClickUp Enterprise Access Governance

Overview

Use API role and ACL evidence as inputs to authorization decisions without assuming a numeric role alone proves effective access.

Prerequisites

• An Enterprise-plan and owner/admin capability check for the intended endpoint
• An authorized Workspace inventory of users, guests, groups, custom roles, and protected objects
• A ticketed desired-state change with separation of duties and rollback

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, adapters, configuration names, tests, and evidence. Use WebFetch only for current official ClickUp documentation. Use Write or Edit after confirming the target file, Workspace boundary, and requested mode.

Current Contract

• The v2 member role field uses 1 owner, 2 admin, 3 member, and 4 guest; custom roles require their own endpoint.
• Groups are user groups, while v2 team_id means Workspace.
• User/guest management is Enterprise-only; v3 audit-log queries are Enterprise-only and owner-only.
• v3 ACL changes can alter privacy and sharing and may incur charges; effective access can inherit from hierarchy.

Authentication

Use a personal token only for accountable individual/testing work or OAuth Authorization Code for a user-facing integration. Inject the token server-side through a governed secret reference, send it in Authorization, verify authorized Workspace IDs, and never print the token, OAuth client secret, or webhook secret.

Instructions

1. Identify the Workspace, plan, caller role, endpoint version, and approved authorization objective.
2. Inventory direct and inherited access, groups, custom roles, guests, and application tokens.
3. Compare effective access to policy; do not collapse custom roles into the four base role codes.
4. Build a least-privilege plan with additions, removals, charge impact, and rollback.
5. Require a second reviewer for owner/admin, guest, group, or ACL changes; apply bounded changes.
6. Re-read effective access and, where authorized, query audit evidence for the change.

Approval Boundaries

Never self-approve privilege elevation, owner/admin changes, broad sharing, guest expansion, paid ACL effects, or user removal.

Output

Return plan/endpoint eligibility, before/after access matrix, inherited-access caveats, approvals, applied changes, audit evidence, and rollback.

Error Handling

ClickUp Verified First Read

Overview

Verify authentication, JSON parsing, and Workspace scope before enabling any task or webhook mutation. Keep this first probe read-only and narrowly scoped.

Prerequisites

• A personal token for individual/testing use or an OAuth token for a user-facing app
• An expected authorized Workspace ID supplied through a safe channel
• A server-side runtime that will not expose the token

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, adapters, configuration names, tests, and evidence. Use WebFetch only for current official ClickUp documentation. Use Write or Edit after confirming the target file, Workspace boundary, and requested mode.

Current Contract

• Send the token in the Authorization header; OAuth examples may use the Bearer form documented by ClickUp.
• Use GET /api/v2/user to confirm caller identity and GET /api/v2/team for authorized Workspaces.
• In v2, returned teams are Workspaces.
• The probe performs zero writes and logs no names, emails, or tokens.

Authentication

Use a personal token only for accountable individual/testing work or OAuth Authorization Code for a user-facing integration. Inject the token server-side through a governed secret reference, send it in Authorization, verify authorized Workspace IDs, and never print the token, OAuth client secret, or webhook secret.

Instructions

1. Confirm the auth mode, secret reference, expected Workspace, timeout, and zero-write boundary.
2. Inspect the local client and ensure the base URL is https://api.clickup.com/api/v2.
3. Request the authorized user and validate a JSON user object without logging personal fields.
4. Request authorized teams and compare IDs to the expected Workspace allow-list.
5. Record status, latency, response schema, and redacted Workspace match.
6. Keep mutation disabled until the caller explicitly selects a bounded workflow.

Approval Boundaries

Do not create a test task, regenerate a token, or broaden OAuth Workspace authorization as part of this read-only proof.

Output

Return auth mode, user-probe result, authorized Workspace count, expected-ID match, latency, and writes performed. A successful result must explicitly report zero writes.

Error Handling

ClickUp Integration Incident Response

Overview

Separate provider health, credential scope, rate exhaustion, webhook suspension, data drift, and application faults before taking recovery action.

Prerequisites

• An incident commander, severity model, affected service/Workspace inventory, and communication channel
• Read-only diagnostic capability plus audited break-glass procedures
• Known last-good deployment, queue checkpoints, and rollback targets

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, adapters, configuration names, tests, and evidence. Use WebFetch only for current official ClickUp documentation. Use Write or Edit after confirming the target file, Workspace boundary, and requested mode.

Current Contract

• ClickUp status, API reachability, tenant authorization, and application side effects are independent signals.
• A webhook is failing after unsuccessful or over-seven-second responses; failed events are not resent after their delivery attempts.
• At fail_count=100 a webhook is suspended; returning 401 suspends it immediately.
• 429 recovery follows the per-token reset header rather than a guessed delay.

Authentication

Use a personal token only for accountable individual/testing work or OAuth Authorization Code for a user-facing integration. Inject the token server-side through a governed secret reference, send it in Authorization, verify authorized Workspace IDs, and never print the token, OAuth client secret, or webhook secret.

Instructions

1. Declare scope, commander, severity, affected Workspaces, write freeze, and evidence-retention boundary.
2. Check provider status and run metadata-only identity/rate probes.
3. Classify auth, plan/permission, rate, webhook health, schema, queue, deployment, or data-consistency failure.
4. Contain with write disablement, circuit breaking, queue pause, or rollback before rotating credentials.
5. Recover one lane at a time and reconcile missed or duplicate business operations from durable records.
6. Close only after verification, stakeholder communication, evidence capture, and assigned follow-up.

Approval Boundaries

Do not rotate shared tokens, reactivate webhooks, replay queues, mutate tasks, or suppress evidence without commander and owner approval.

Output

Return timeline, failure class, containment, affected Workspaces/operations, recovery evidence, reconciliation result, and follow-up owners. Include unresolved risk and the next decision deadline.

Error Handling

ClickUp Authentication Setup

Overview

Choose the authentication mode by tenancy and ownership, then prove the authorized Workspace boundary without exposing credentials.

Prerequisites

• A server-side application boundary and governed secret manager
• For personal use/testing, an accountable ClickUp user; for public use, an owner/admin-created OAuth app
• Exact redirect URIs, state storage, and an expected Workspace allow-list

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, adapters, configuration names, tests, and evidence. Use WebFetch only for current official ClickUp documentation. Use Write or Edit after confirming the target file, Workspace boundary, and requested mode.

Current Contract

• Personal tokens begin with pk_, are intended for individual/testing use, and do not expire unless regenerated or revoked.
• User-facing integrations use OAuth Authorization Code at https://app.clickup.com/api and exchange at https://api.clickup.com/api/v2/oauth/token.
• OAuth access tokens currently do not expire, but ClickUp marks that behavior subject to change.
• Every API request includes the token in Authorization; authorized Workspaces are verified through the teams endpoint.

Authentication

Use a personal token only for accountable individual/testing work or OAuth Authorization Code for a user-facing integration. Inject the token server-side through a governed secret reference, send it in Authorization, verify authorized Workspace IDs, and never print the token, OAuth client secret, or webhook secret.

Instructions

1. Choose personal or OAuth mode and record credential owner, environment, and intended Workspaces.
2. Store token/client secret only in a secret manager and inject by reference at runtime.
3. For OAuth, register exact HTTPS redirects, generate/validate state, and exchange each code server-side once.
4. Call GET /api/v2/user and GET /api/v2/team with bounded timeouts.
5. Compare authorized Workspace IDs with the allow-list and reject cross-tenant ambiguity.
6. Document revocation/rotation, reauthorization, incident, and ownership-transfer procedures.

Approval Boundaries

Do not print tokens, put a client secret in frontend code, accept unvalidated state, silently expand Workspace authorization, or regenerate a shared token without owner approval.

Output

Return auth mode, secret-reference name, redirect/state result, authorized Workspace IDs in redacted form, verification status, and rotation owner.

Error Handling

ClickUp Deterministic Local Development

Overview

Keep the fast loop offline while preserving exact provider shapes and a deliberate path to detect real API drift.

Prerequisites

• A transport interface around all ClickUp HTTP calls
• Sanitized fixtures derived from documented v2/v3 schemas, including nulls and errors
• A deterministic clock, fake queue, and optional isolated Workspace for a live read

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, adapters, configuration names, tests, and evidence. Use WebFetch only for current official ClickUp documentation. Use Write or Edit after confirming the target file, Workspace boundary, and requested mode.

Current Contract

• Fixtures preserve string/number/null differences in task and webhook payloads.
• Separate base paths and schemas for v2 and selected v3 operations.
• Mock 429 headers, zero-based task pages, comment cursors, auth codes, and webhook delivery retries.
• No ordinary unit test reads a developer token or creates a ClickUp object.

Authentication

Use a personal token only for accountable individual/testing work or OAuth Authorization Code for a user-facing integration. Inject the token server-side through a governed secret reference, send it in Authorization, verify authorized Workspace IDs, and never print the token, OAuth client secret, or webhook secret.

Instructions

1. Inventory direct HTTP calls and route them through an injectable transport.
2. Create fixtures for identity, Workspace, tasks, pages, Custom Fields, webhooks, errors, and rate headers.
3. Freeze time and IDs; make request order, retry jitter, and queue outcomes deterministic.
4. Test raw-body HMAC verification, redaction, Workspace guards, and partial-write recovery.
5. Add an explicit live-probe command limited to read-only identity/Workspace calls.
6. Run offline tests by default and record any provider drift found by the live probe.

Approval Boundaries

Do not record production responses, use personal work data as fixtures, or enable writes in the default local/test path.

Output

Return fixture provenance, offline coverage, direct-call violations, deterministic test result, live-probe result, and drift. Distinguish simulated success from provider-confirmed evidence.

Error Handling

ClickUp Migration and Reconciliation

Overview

Treat migration as a versioned data program rather than a one-shot task-creation loop. Make each batch resumable, reconcilable, and safe to stop.

Prerequisites

• Source export/API ownership and a destination Workspace/List allow-list
• Approved field, user, status, date, attachment, comment, and dependency mappings
• A durable reconciliation database, pilot cohort, rate budget, and rollback policy

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, adapters, configuration names, tests, and evidence. Use WebFetch only for current official ClickUp documentation. Use Write or Edit after confirming the target file, Workspace boundary, and requested mode.

Current Contract

• Get Tasks returns 100 records per zero-based page; decide explicitly about closed tasks, subtasks, and Tasks in Multiple Lists.
• Task priorities and dates require ClickUp's documented values and millisecond timestamps.
• Custom Field definitions/options must be resolved first; existing task fields use their separate value endpoints.
• ClickUp does not document a general transactional bulk-create endpoint, so partial progress must be durable and resumable.

Authentication

Use a personal token only for accountable individual/testing work or OAuth Authorization Code for a user-facing integration. Inject the token server-side through a governed secret reference, send it in Authorization, verify authorized Workspace IDs, and never print the token, OAuth client secret, or webhook secret.

Instructions

1. Inventory source entities, destination hierarchy, volume, sensitivity, identities, and unsupported concepts.
2. Define mapping versions and validate status, assignee, priority, Custom Field, relationship, and attachment rules.
3. Extract with complete pagination and persist immutable source IDs plus content hashes.
4. Run a no-write transform report, then migrate a representative pilot with strict ceilings.
5. Persist every destination ID before dependent writes and retry only idempotent/transient work.
6. Reconcile counts and sampled field hashes; quarantine exceptions and obtain cutover approval.

Approval Boundaries

Require explicit approval for production cutover, identity reassignment, attachment transfer, private-content expansion, deletion, or rollback that changes user-visible work.

Output

Return mapping version, extracted/transformed/migrated/skipped/quarantined counts, ID map, reconciliation results, cutover decision, and rollback state. Name every unresolved owner and deadline.

Error Handling

ClickUp Multi-Environment Isolation

Overview

Prevent a development process or callback from crossing into production merely because a shared token can access multiple Workspaces.

Prerequisites

• An environment matrix of OAuth apps or personal tokens, allowed Workspace IDs, callback URLs, queues, and secret references
• Separate non-production data and synthetic verification records
• Deployment and incident owners for every environment

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, adapters, configuration names, tests, and evidence. Use WebFetch only for current official ClickUp documentation. Use Write or Edit after confirming the target file, Workspace boundary, and requested mode.

Current Contract

• OAuth users can authorize one or more Workspaces, so the application must enforce its own environment allow-list.
• Redirect URIs and webhook endpoints are environment-specific and HTTPS.
• Rate limits are per token; sharing a token also shares its budget and blast radius.
• v2 team IDs and v3 Workspace IDs must resolve to the same intended environment boundary.

Authentication

Use a personal token only for accountable individual/testing work or OAuth Authorization Code for a user-facing integration. Inject the token server-side through a governed secret reference, send it in Authorization, verify authorized Workspace IDs, and never print the token, OAuth client secret, or webhook secret.

Instructions

1. Inventory every environment's credentials, app IDs, redirects, webhooks, queues, storage, and Workspace IDs.
2. Remove shared credentials and assign an accountable owner and rotation path to each secret.
3. Implement startup and per-request guards that compare environment and Workspace allow-lists.
4. Namespace reconciliation keys, queues, metrics, and callback secrets by environment.
5. Run offline cross-environment denial tests and bounded live identity/Workspace probes.
6. Publish the matrix and fail deployment if any production boundary is ambiguous.

Approval Boundaries

Do not reuse production credentials or data in lower environments, authorize extra Workspaces silently, or copy production webhook secrets.

Output

Return the environment matrix, shared-boundary findings, guard/test results, live Workspace matches, and unresolved isolation risks.

Error Handling

ClickUp Integration Observability

Overview

Expose reliability, rate pressure, delivery health, and business reconciliation without exporting task or member content.

Prerequisites

• A typed ClickUp transport and durable webhook/job queues
• Approved telemetry fields, retention, access, sampling, and alert ownership
• Service-level objectives for request success, latency, queue age, freshness, and reconciliation

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, adapters, configuration names, tests, and evidence. Use WebFetch only for current official ClickUp documentation. Use Write or Edit after confirming the target file, Workspace boundary, and requested mode.

Current Contract

• Capture X-RateLimit-* values as bounded numeric telemetry without capturing the Authorization header.
• Webhook objects expose health/failure state; over-seven-second or unsuccessful delivery contributes to failure behavior.
• ClickUp retries an event up to five times, but failed events are not later resent after those attempts.
• Task names, descriptions, comments, attachments, emails, raw bodies, tokens, and webhook secrets are not telemetry.

Authentication

Use a personal token only for accountable individual/testing work or OAuth Authorization Code for a user-facing integration. Inject the token server-side through a governed secret reference, send it in Authorization, verify authorized Workspace IDs, and never print the token, OAuth client secret, or webhook secret.

Instructions

1. Inventory request, queue, webhook, reconciliation, and deployment signals plus current data exposure.
2. Define low-cardinality metrics by endpoint family, version, status class, environment, and Workspace alias.
3. Add trace spans around the transport and queue without request/response content.
4. Monitor rate remaining/reset, 429s, webhook latency/status/fail count, queue age, and duplicate suppression.
5. Create actionable alerts with runbook links, owners, and tested thresholds from baseline data.
6. Validate dashboards and alerts with synthetic failures and record redaction checks.

Approval Boundaries

Do not add user/task IDs as unbounded labels, export payloads for debugging, or reactivate a failing webhook automatically without policy.

Output

Return signal inventory, SLOs, dashboards, alert tests, redaction results, cardinality risks, and runbook links. Separate measured evidence from proposed instrumentation.

Error Handling

ClickUp Throughput and Freshness Tuning

Overview

Tune measured bottlenecks while preserving completeness, ordering, freshness, and rate safety. Reject optimizations that improve speed by dropping provider records.

Prerequisites

• A baseline of request volume, p50/p95 latency, page counts, payload sizes, 429s, queue age, and reconciliation
• Completeness and freshness assertions plus synthetic load fixtures
• Known endpoint-specific pagination and current token limit

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, adapters, configuration names, tests, and evidence. Use WebFetch only for current official ClickUp documentation. Use Write or Edit after confirming the target file, Workspace boundary, and requested mode.

Current Contract

• Get Tasks returns 100 tasks per zero-based page and has explicit filters for closed tasks and subtasks; use include_timl for Tasks in Multiple Lists.
• Task comments use start plus start_id after the first 25 newest comments.
• The v2 task surface does not offer a general fields-selection parameter; do not invent one.
• Webhook invalidation can reduce polling, but delivery must be signed, idempotent, and reconciled.

Authentication

Use a personal token only for accountable individual/testing work or OAuth Authorization Code for a user-facing integration. Inject the token server-side through a governed secret reference, send it in Authorization, verify authorized Workspace IDs, and never print the token, OAuth client secret, or webhook secret.

Instructions

1. Measure each endpoint and business operation before changing caching or concurrency.
2. Verify pagination termination, ordering, filters, and reconciliation on boundary fixtures.
3. Coalesce duplicate reads and cache stable hierarchy metadata with explicit invalidation.
4. Set concurrency from the token's current remaining/reset headers and downstream queue capacity.
5. Use webhooks to invalidate or enqueue targeted reads while retaining a reconciliation sweep.
6. Benchmark the same cohort and reject improvements that lose records or violate freshness.

Approval Boundaries

Do not raise concurrency, lengthen freshness windows, omit pages, or replace reconciliation with webhooks without owner-approved SLOs.

Output

Return baseline/after latency and requests, completeness, freshness, cache hit rate, concurrency, 429s, and rollback decision.

Error Handling

ClickUp Production Readiness Review

Overview

Turn launch readiness into verifiable controls and named blockers rather than a generic checkbox list.

Prerequisites

• A release candidate, endpoint/version inventory, Workspace/environment matrix, and rollback artifact
• Current plan/feature facts, auth ownership, data policy, SLOs, and incident runbook
• Offline and bounded live test receipts

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, adapters, configuration names, tests, and evidence. Use WebFetch only for current official ClickUp documentation. Use Write or Edit after confirming the target file, Workspace boundary, and requested mode.

Current Contract

• v2/v3 routes are reviewed individually; auth and plan success in one endpoint does not prove another.
• Rate behavior is tested using per-token headers and bounded retry policy.
• Webhook readiness includes HTTPS, raw-body HMAC, idempotency, queue durability, health monitoring, and reconciliation.
• No launch is approved with unresolved cross-Workspace writes or secret/content leakage.

Authentication

Use a personal token only for accountable individual/testing work or OAuth Authorization Code for a user-facing integration. Inject the token server-side through a governed secret reference, send it in Authorization, verify authorized Workspace IDs, and never print the token, OAuth client secret, or webhook secret.

Instructions

1. Verify artifact provenance, dependency locks, endpoint versions, schema fixtures, and rollback.
2. Verify personal/OAuth ownership, redirect/state controls, secret injection, rotation, and Workspace guards.
3. Review data minimization, logging, retention, deletion, backup, and incident access.
4. Exercise rate, pagination, timeout, 5xx, webhook retry/suspension, queue replay, and partial-write paths.
5. Run a bounded read-only live probe and any separately approved synthetic canary.
6. Record PASS/FAIL/NA evidence, owners, expiry dates, blockers, and final decision.

Approval Boundaries

The skill may recommend but not self-approve launch, paid plan changes, production writes, ACL changes, or acceptance of a security/data exception.

Output

Return go/no-go, control results with evidence, blocker owners/dates, canary result, rollback target, and approval record.

Error Handling

ClickUp Rate-Limit Control

Overview

Size traffic from the token's observed budget and workload rather than hard-coded optimistic concurrency. Preserve headroom for every caller sharing that token.

Prerequisites

• Sanitized X-RateLimit-Limit, Remaining, and Unix Reset values plus 429 history
• The Workspace plan hosting the token and inventory of all callers sharing it
• Queue, freshness, retry, and priority requirements

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, adapters, configuration names, tests, and evidence. Use WebFetch only for current official ClickUp documentation. Use Write or Edit after confirming the target file, Workspace boundary, and requested mode.

Current Contract

• Limits apply per personal or OAuth token and vary by the hosting Workspace plan.
• Current published limits are 100 requests/minute for Free Forever, Unlimited, and Business; 1,000 for Business Plus; 10,000 for Enterprise.
• A 429 response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset; reset is a Unix timestamp.
• Plan values are ceilings, not target throughput; leave headroom for interactive and recovery traffic.

Authentication

Use a personal token only for accountable individual/testing work or OAuth Authorization Code for a user-facing integration. Inject the token server-side through a governed secret reference, send it in Authorization, verify authorized Workspace IDs, and never print the token, OAuth client secret, or webhook secret.

Instructions

1. Inventory tokens, Workspaces, plans, callers, endpoints, request bursts, and retry loops.
2. Capture current headers from bounded calls and convert reset timestamps safely.
3. Allocate budgets by priority and reserve explicit headroom for user and recovery operations.
4. Implement a bounded queue/token bucket with jitter and a maximum elapsed retry time.
5. Pause at 429 until reset; do not fan out retries or switch tokens to bypass policy.
6. Load-test with synthetic work and verify throughput, fairness, queue age, and zero lost operations.

Approval Boundaries

Do not upgrade a plan, add tokens to multiply limits, or starve interactive traffic without account and service-owner approval.

Output

Return observed limit/reset, caller inventory, concurrency and queue policy, headroom, test results, 429 rate, and alternatives.

Error Handling

ClickUp Integration Reference Architecture

Overview

Separate provider transport, tenancy policy, business mapping, durable execution, and evidence so API evolution or partial failure does not corrupt work.

Prerequisites

• System boundaries, source-of-truth decision, data classes, latency/freshness SLOs, and ownership
• Endpoint/version and plan inventory for required ClickUp capabilities
• Failure, reconciliation, rollback, and incident requirements

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, adapters, configuration names, tests, and evidence. Use WebFetch only for current official ClickUp documentation. Use Write or Edit after confirming the target file, Workspace boundary, and requested mode.

Current Contract

• Use explicit v2 and v3 clients because ClickUp exposes only selected v3 surfaces today.
• Resolve v2 team_id to the application Workspace tenant boundary before every operation.
• Treat webhooks as signed change signals processed through a durable idempotent queue, not as a complete event log.
• Writes require stable source identity, reconciliation, and compensating/rollback policy.

Authentication

Use a personal token only for accountable individual/testing work or OAuth Authorization Code for a user-facing integration. Inject the token server-side through a governed secret reference, send it in Authorization, verify authorized Workspace IDs, and never print the token, OAuth client secret, or webhook secret.

Instructions

1. Define source of truth and field-level ownership for every one-way or two-way mapping.
2. Place auth and Workspace authorization in a policy layer above versioned transports.
3. Model commands and events with durable IDs, mapping versions, and idempotency records.
4. Add rate-aware queues, webhook ingress, reconciliation sweeps, and dead-letter review.
5. Separate content-free telemetry/evidence from sensitive payload storage and retention.
6. Exercise auth, plan, rate, webhook-gap, partial-write, schema-drift, and rollback scenarios.

Approval Boundaries

Do not permit autonomous destructive writes, cross-Workspace routing, ACL changes, or conflict resolution without explicit product-owner policy.

Output

Return component/data-flow design, version matrix, trust and tenant boundaries, failure modes, SLOs, reconciliation, approvals, and rollback.

Error Handling

ClickUp Typed Client Patterns

Overview

Keep application code independent of transport details without presenting an ungoverned third-party wrapper as an official SDK.

Prerequisites

• Pinned official v2 and v3 OpenAPI documents or reviewed endpoint schemas
• A server-side HTTP runtime, validation library, and test framework
• Auth, Workspace, timeout, retry, redaction, and observability policies

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, adapters, configuration names, tests, and evidence. Use WebFetch only for current official ClickUp documentation. Use Write or Edit after confirming the target file, Workspace boundary, and requested mode.

Current Contract

• ClickUp publishes v2 and v3 OpenAPI specifications suitable for generation.
• Route every operation to an explicit version/base path and preserve ClickUp field types, including nullable webhook fields.
• Inject personal or OAuth tokens at call time and never store them in client objects serialized to logs.
• Retry only idempotent transient operations by default; writes need durable application idempotency.

Authentication

Use a personal token only for accountable individual/testing work or OAuth Authorization Code for a user-facing integration. Inject the token server-side through a governed secret reference, send it in Authorization, verify authorized Workspace IDs, and never print the token, OAuth client secret, or webhook secret.

Instructions

1. Inventory required operations and pin the matching official schema/version digest.
2. Generate or hand-write a narrow transport and wrap it behind domain-oriented interfaces.
3. Inject auth, Workspace allow-list, timeouts, content type, and redacted telemetry centrally.
4. Create endpoint-specific pagination helpers instead of one incorrect universal iterator.
5. Map statuses/error codes into typed retryable, authorization, plan, validation, and unknown classes.
6. Test fixtures, schema drift, cancellation, retry ceilings, partial writes, and version migration seams.

Approval Boundaries

Do not auto-generate broad production access, silently fall back between API versions, or retry writes without a durable source key and owner policy.

Output

Return schema pins, supported operations, version routing, auth boundary, error/pagination policies, test coverage, and unsupported surfaces.

Error Handling

ClickUp Integration Security

Overview

Protect long-lived credentials and sensitive work content across outbound API calls, inbound webhooks, queues, logs, and operator tooling.

Prerequisites

• A data-flow and trust-boundary diagram plus credential/Workspace inventory
• Named security, service, data, and ClickUp Workspace owners
• Synthetic fixtures and an incident/rotation runbook

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, adapters, configuration names, tests, and evidence. Use WebFetch only for current official ClickUp documentation. Use Write or Edit after confirming the target file, Workspace boundary, and requested mode.

Current Contract

• Personal tokens do not expire; OAuth tokens currently do not expire but that behavior is subject to change.
• OAuth Authorization Code callbacks require exact redirects, state validation, and server-side client-secret handling.
• Webhook requests use per-webhook secrets and raw-body HMAC-SHA256 in X-Signature; ClickUp has no fixed webhook source IP.
• API authorization reflects the user and authorized Workspaces, so the app must enforce its own tenant policy.

Authentication

Use a personal token only for accountable individual/testing work or OAuth Authorization Code for a user-facing integration. Inject the token server-side through a governed secret reference, send it in Authorization, verify authorized Workspace IDs, and never print the token, OAuth client secret, or webhook secret.

Instructions

1. Inventory credentials, callbacks, Workspaces, scopes/capabilities, webhooks, queues, stores, logs, and operator access.
2. Remove client-side or repository secrets; inject environment-specific references at runtime.
3. Enforce OAuth state, exact redirect handling, Workspace allow-lists, and deny-by-default write policies.
4. Verify webhook signatures with constant-time comparison before JSON processing; apply replay/idempotency controls.
5. Redact content and secrets from errors, traces, bundles, analytics, and CI artifacts.
6. Exercise leak, revocation, cross-tenant, forged/replayed webhook, partial-write, and incident recovery scenarios.

Approval Boundaries

Do not rotate shared credentials, reauthorize Workspaces, change ACLs, or inspect private content without accountable owner approval.

Output

Return threats, controls, credential/tenant map, webhook findings, data exposures, tested incident paths, residual risk, and owners.

Error Handling

ClickUp API Evolution Migration

Overview

Evolve endpoint-by-endpoint because ClickUp v2 remains the primary surface while selected capabilities use v3. Never infer a platform-wide cutover from one migrated endpoint.

Prerequisites

• An inventory of every endpoint, version, field assumption, pagination loop, and webhook dependency
• Pinned current/target OpenAPI schemas and representative sanitized fixtures
• Feature flags, canary environment, reconciliation, and rollback ownership

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, adapters, configuration names, tests, and evidence. Use WebFetch only for current official ClickUp documentation. Use Write or Edit after confirming the target file, Workspace boundary, and requested mode.

Current Contract

• There is no general v2-to-v3 cutover contract; preserve explicit version routing for unchanged v2 operations.
• v2 uses Team for Workspace while v3 uses Workspace; Groups remain user groups.
• Different endpoints can have different pagination and response types, so a base-path swap is unsafe.
• Preview or experimental surfaces require tighter pins and rollback.

Authentication

Use a personal token only for accountable individual/testing work or OAuth Authorization Code for a user-facing integration. Inject the token server-side through a governed secret reference, send it in Authorization, verify authorized Workspace IDs, and never print the token, OAuth client secret, or webhook secret.

Instructions

1. Inventory current operations and label each v2, v3, deprecated, preview, or unknown.
2. Diff official schemas and docs for path, auth, plan, parameter, field, pagination, and error changes.
3. Update typed adapters behind a feature flag while preserving the current path.
4. Run offline dual-contract fixtures and migration tests, including nulls and partial failures.
5. Canary read-only traffic, then separately approved synthetic writes, and compare normalized results.
6. Promote endpoint-by-endpoint or roll back; update evidence and remove old code only after stability.

Approval Boundaries

Do not globally replace /api/v2, silently coerce fields, auto-fallback writes, or remove the rollback path before the stability window.

Output

Return operation inventory, schema delta, compatibility decisions, test/canary results, rollout state, rollback, and unresolved risks.

Error Handling

ClickUp Signed Webhook Operations

Overview

Treat webhooks as signed, user-owned change signals that need durable processing and reconciliation. Assume delivery can duplicate, arrive late, or stop after ownership changes.

Prerequisites

• A public HTTPS endpoint capable of retaining raw request bytes
• A secret manager, durable queue/idempotency store, and Workspace allow-list
• An authorized user owner for the webhook plus monitoring and reconciliation

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, adapters, configuration names, tests, and evidence. Use WebFetch only for current official ClickUp documentation. Use Write or Edit after confirming the target file, Workspace boundary, and requested mode.

Current Contract

• Webhook creation returns a unique secret; verify raw-body HMAC-SHA256 against hexadecimal X-Signature.
• Registrations are tied to the creating user and can stop triggering when that user is disabled or loses hierarchy access.
• Use webhook_id:history_item_id as the documented idempotency key when a history item exists; handle events without one deliberately.
• Responses over seven seconds or unsuccessful responses are failures; ClickUp attempts delivery up to five times, does not resend the failed event later, suspends at fail_count=100, and a 401 suspends immediately.

Authentication

Use a personal token only for accountable individual/testing work or OAuth Authorization Code for a user-facing integration. Inject the token server-side through a governed secret reference, send it in Authorization, verify authorized Workspace IDs, and never print the token, OAuth client secret, or webhook secret.

Instructions

1. Choose the narrowest location and explicit event set; inventory duplicate registrations before creation.
2. Register only after endpoint ownership, HTTPS, secret storage, and rollback approval are confirmed.
3. Capture raw bytes, look up the per-webhook secret, verify HMAC in constant time, then parse/validate JSON.
4. Persist idempotency and enqueue before a fast success response; process business effects asynchronously.
5. Monitor status/fail count, latency, duplicates, dead letters, and owner eligibility.
6. Run reconciliation reads for delivery gaps and rotate/re-register safely when ownership changes.

Approval Boundaries

Require approval before creating, broadening, suspending/reactivating, rotating, or deleting production webhooks and before replaying business effects.

Output

Return the registered scope, credential-storage identifier, HMAC verification and idempotency test results, delivery health, queue result, reconciliation status, and ro…