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.

Hosted ClickUp mode (default): onboard configures official ClickUp MCP and portable skills, and reuses/checks GitHub CLI sign-in. --github hosted selects an existing approved hosted GitHub connection instead. Strict --mode remote-only (and legacy --mode oauth) permits only hosted GitHub. Missing/incompatible or organization-banned selected backends mean STOP; do not install a ClickUp CLI/helper or bridge as fallback, or change GitHub backends after an uncertain write. See mode setup. Browser OAuth belongs to the agent, not the local helper, and no personal ClickUp API token is requested or read. Direct host writes must follow the guarded issue-first protocol, including an exact user-approved scope and write budget, complete reads, text_content markers, GitHub-first targets, safe read-back and no uncertain mutation replay. This is agent-enforced, not equivalent to the local helper's private journal, concurrency lock or completion gate.

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 repository-wide OS-held write lock shared by linked worktrees. 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. OS locks release on process exit; their files remain and must not be unlinked while processes are using them. A legacy write.lock still requires inspecting its recorded PID/process before manual removal. Stop old helper versions before upgrading; they do not participate in the new lock.

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 default local ClickUp readers return one page, so a full 25-comment page stops reconciliation. Explicit routing.comment_reader=clickup-api selects the narrow GET-only cursor reader with private environment credentials. All writes keep using the selected upstream runtime; failed reads never silently fall back. Use host MCP reads for threaded replies after resolving pending helper writes. The helper exports top-level ClickUp comments only. See the setup wiki for native activity linking and optional automations. The optional worker polls only explicitly listed tasks, defaults to a read-only preview, preflights every task before writes, bounds new mirrors per pass, and stops on binding changes, incomplete reads, or uncertain outcomes. With the default reader it refuses batches that would reach the 25-comment limit; the explicit complete-history reader removes that boundary. One worker owner per local repository is enforced; separate clones/machines still require coordinated task ownership. Setup and CI do not start or deploy it.

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.