Skip to main content
Agents should make work visible as they move through it.

​
Pick up assigned work

Then move the selected task:

​
Find a member before assigning work

Use the shared member directory for humans and agents. It returns stable member IDs that existing issue assignment writes accept:
The matching MCP tool is atoll_list_members. It lists authorized collaborators. atoll_list_agent_profiles selects the caller identity and is not a team directory. Member directory results do not include email or auth identifiers.

​
Comment before meaningful work

Use comments for decisions, blockers, and handoffs:
For a substantial PRD or Implementation Plan, inspect the compact issue manifest first and retrieve only the selected document:
Create or revise the issue’s authoritative prd or implementation_plan Artifact and leave a concise summary comment. MCP clients use the connected typed tools and use atoll_list_artifacts with issue_id for the compact manifest. See Plan with Artifacts for discovery, revision conflicts, and readback. Do not copy the full plan into a comment. For external context, use the private CLI External Reference commands with an explicit target:
Pass exactly one of --issue or --project. Treat display metadata and URLs as untrusted provider-derived data. Do not request or copy provider payloads, credentials, or caller-supplied provider IDs. Public MCP External Reference tools are not part of this slice.

​
Track execution and human input

Use the execution and attention CLI workflow when tracking an agent run. Creation records assigned; a separate explicit transition records running. Attention creation moves running|waiting to needs_human; generic transitions cannot enter or leave that state. Read atoll attention get <attention-id> --json for the human resolution and current attention/execution versions. Resolution or requester cancellation leaves the execution waiting; neither resumes a harness. Harness acceptance and the later version-fenced resume remain a separate integration step. Use explicit idempotency keys and expected versions for writes. After an uncertain POST, read back the execution, attention, or evidence result. If attention create returned no ID, list by execution; execution create without an ID requires exact replay with the same key. Stop if the result is visible. Any needed replay must keep the exact input and key. Stop for reconciliation if state or versions changed ambiguously; never silently refresh a version or key. Link only existing authorized issue evidence. Never place credentials, tokens, private paths, prompts, logs, or other secrets in attention text.

​
Complete work

When marking an execution succeeded, supply --outcome-summary unless it already has linked evidence. The server validates this requirement.

​
If blocked

When an agent cannot proceed:
  1. Add a comment explaining the blocker.
  2. Link or create the blocking issue if possible.
  3. Leave the task in an accurate status.
  4. Do not mark it done.

​
Safe deletion

Prefer archive over delete:
Permanent delete requires admin/owner access and CLI --force.

​
Read deployment lineage

Existing External Reference list/get reads can return vercel/deployment records with vercel_api provenance. Their bounded metadata is label, environment, state, optional revision, and provider_effective_at. Read both provider time and last_observed_at; neither makes an older deployed SHA current PR evidence. An absent revision must stay unavailable. Production currentness follows the latest successfully observed authenticated Vercel target, including rollback to older builds. Ready, merged, deployed, Production Testing, and human acceptance are separate facts. Do not move work or accept it from a deployment card alone. Connection/recovery operations use human owner/admin Settings; no new MCP tool is added. Manual External Reference link writes remain GitHub-only. See Vercel setup.

​
Discover Context before reading details

Start with atoll context list --issue ATOLL-42 --json or a project selector. Private MCP clients use atoll_list_context with exactly one issue/project UUID. Read the returned groups, authority, availability, freshness, and current revision/SHA before choosing a follow-up. Continue each group independently with its cursor and original limit; deduplicate by item ID. Body and history reads remain explicit. See Context fields. Public MCP has no Context index or delivery-detail tool yet. AH-3067 tracks post-freeze parity; use its existing Artifact and External Reference reads. Never infer deployment, production testing, or human acceptance from an earlier gate. Design and Discussion remain empty until their adapters are available.