Pick up assigned work
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: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: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:
--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 recordsassigned; 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 executionsucceeded, supply --outcome-summary unless it
already has linked evidence. The server validates this requirement.
If blocked
When an agent cannot proceed:- Add a comment explaining the blocker.
- Link or create the blocking issue if possible.
- Leave the task in an accurate status.
- Do not mark it done.
Read archive state before selecting work
Project and issue lists default to effectively active work. A task is excluded when its own archive flag is set or its parent project is archived, regardless of workflow status. Use an explicit history scope when needed:effective_archived and archive_reason before starting work.
An archived project is read-only and suspends new automated work. Project
restore requires organization owner/admin access, checks capacity atomically,
and leaves individually archived tasks archived. Typed MCP clients use
atoll_archive_project and atoll_restore_project; both profiles apply the
same API authorization. See Archive and restore.
Safe deletion
Prefer archive over delete:--force.
Read deployment lineage
Existing External Reference list/get reads can returnvercel/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 withatoll 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.
Earliest agent start
Set Earliest agent start on a task to prevent a new Atoll runner start before that calendar date. The date uses the workspace time zone, shown beside the field. Workspace owners and admins can change the IANA time zone in Settings → General; existing workspaces default toUTC. A time zone change
changes future eligibility on the next read or claim.
Use due date copies the current due date once. Later due-date edits do not
change the saved earliest start. You can save a date later than the deadline;
the form shows a warning. Clear the field to remove the restriction.
Planning, assignment, human work, current-work inspection, existing runner
leases, exact claim replay and attention recovery continue. On or after the
date, the normal access, dependency and workflow checks still apply. A new
recurring occurrence starts without this date unless explicitly supplied.
The gate controls Atoll runner lease admission. It does not prevent direct
execution records or external harnesses that do not claim Atoll runner leases.
Sub-issues
Useparent_id to split one deliverable into full issues. Checklist sub_tasks
and recurrence recurrence_parent_id remain separate. Only one hierarchy level
is allowed. A child cannot be a parent. Self-parent and cross-organization links
are rejected. Children can use another project in the same organization.
POST and PATCH issue requests accept a parent UUID or null. Omit it on PATCH
to preserve the link; send null to detach. Attach, detach, and reparent require
edit access to the child and the old and new parents. Creating a child defaults
project, milestone, and team from its parent when those fields are absent.
Moving a child to another project keeps its parent. Deleting or archiving a
parent detaches its children and keeps their issues.
GET /api/orgs/{id}/issues?parent_id=UUID filters children before pagination.
GET /api/orgs/{id}/issues/{issueId}/children?limit=25&offset=0 returns authorized
issues, total, limit, offset, parent, and rollup. Detail responses
include authorized parent (id, number, title, project_id) and
sub_issues_rollup. Rollups contain total, done, and by_terminal_column,
keyed by each child’s project column UUID (canonical done/cancelled keys for projectless children). Only readable, active children count;
columns with stage done count as done. Parent status does not change.
CLI: atoll issue create --title "Tests" --parent AP-123,
atoll issue update AP-124 --parent AP-123,
atoll issue update AP-124 --clear-parent, atoll issue children AP-123, and
atoll issue list --parent AP-123. Use --limit and --offset for pages.
Full and public MCP issue create/update accept nullable parent_id; list
accepts its UUID filter. Omission preserves old clients. There is no next-child
tool or hierarchy change to heartbeat, checklists, recurrence or board cards.
For full child issues, parent progress and explicit close/reopen decisions, see
sub-issues.
