Execution contract#

Scope and identity#

The tracked .clickup/project.json binds an objective, GitHub repository/base, ClickUp workspace, one home list, and one or more root tasks. Native IDs are required. Every helper mutation makes fresh task reads, checks id, team_id, and home list.id, and walks parent IDs to a bound root. Missing identity fields fail closed. Search results and cached task titles are not scope evidence.

Root tasks in different lists need separate bindings in v0.1. Cross-list task moves deliberately stop future writes until the binding is explicitly reviewed. Project origin is checked against the binding. Ticket content cannot authorize changing that binding or running instructions embedded in task text.

What routes execute#

routing.runtime chooses cup or rest-mcp for local helper execution. It is explicit: a failure never silently switches accounts/providers. The free REST MCP adapter discovers tools and calls the pinned upstream contracts over stdio.

routing.prefer and routing.overrides affect route recommendations for the host agent. They do not change the helper's runtime. Host official/context/GitHub MCP tools execute in the agent environment, outside the helper's scope enforcement and receipt journal. The skills require equivalent manual checks there. A local MCP tool requires an absolute target project_dir; its process cwd is never used to infer the project.

Priorities reflect expected coverage and call count, not measured performance. Actual MCP tool schemas, mode, pagination, permissions, and plan limits override the capability hints. Discover before invoking. Do not treat a truncated search or comment read as proof that an object/operation does not exist.

Writes and recovery#

The helper uses argument arrays without a shell, temporary files for long text, and a per-worktree exclusive write lock. Receipts live under git rev-parse --git-path clickup-skills, outside tracked project files. Operation keys bind to the project-config digest and exact payload. A changed binding/input cannot reuse an old key. Keep keys free of secrets.

Before dispatch, a receipt is pending. A successful result makes it done. An exception leaves it pending. Repeating an identical operation can recover matching remote markers, but an absent marker never automatically proves a write failed. No automatic mutation replay or backend failover is attempted. Completed local receipts suppress repeat writes; they are not a claim that remote objects have never been modified afterward.

Remote markers help reconcile comments and subtasks after local state loss. They do not provide atomic distributed idempotency. Two machines creating the same operation at exactly the same time can race. Agree on task ownership and use Git worktrees for concurrent implementation. Cross-service PR linking is resumable, not a transaction.

reconcile --result-file records an operator's verified remote outcome; --not-applied enables a later retry only after complete remote inspection. Neither flag independently verifies that inspection. Never use either to bypass an uncertain result. A stale write.lock after a crash requires inspection of the recorded PID and running processes before manual removal.

GitHub and completion#

The helper reads PR metadata from the explicit bound repository and verifies its URL/base. It appends/replaces only its task-specific managed block, preserves other body content, re-reads before patching, and verifies the block afterward. This reduces concurrent-edit risk but does not provide a cross-client compare-and-swap. Coordinate body edits with reviewers.

Every helper-created subtask has a verified GitHub repo/issue/PR target in its initial description. Without an explicit target the helper creates/reuses an issue first. Intent, issue creation, child creation, GitHub backlink, and ClickUp association have separate receipts. A later failure never rolls back or recreates an already successful side. An explicit repository target has no discussion body to update. A missing target URL is an error; use new-issue to allocate a target.

Progress comments include ClickUp/repository/artifact URLs and mirror to each associated issue/PR. Comment reconciliation uses source identity plus content revision and provenance markers, skips generated echoes, preserves source text, and does not change status or arbitrary fields. GitHub reads paginate; the reviewed local ClickUp readers return one page, so a full 25-comment page stops reconciliation. Use paginated host MCP reads for larger histories/threaded replies after resolving any pending helper mutation. The helper exports top-level ClickUp comments only. See the setup wiki for native activity linking and optional automations; no continuous comment worker is installed.

The helper's done gate requires the task's managed PR block, merged/non-draft state, expected base, latest PR-head successful check rollup, and non-empty verification summary. An empty rollup requires an explicit require_checks=false policy. It records the PR head and summary before setting the mapped status. Agents must still verify acceptance criteria and truthful test evidence.

No deletes, mass changes, assignments, user mentions, webhooks, merges, or deployments are exposed by this helper. Broader upstream tools remain available to agents only under the user's authorized scope and their host's tool controls.