tags: #help #agents #ai
order: 70
description: the quirks of this build an AI agent should know

Agent hints¶✎ edit

The quirks of this build of d2 (proto1) that an AI agent, or a person's AI, should know: true of this implementation, not promised by the Spec. Each hint is the quirk, the rule to follow, and the error code where it helps. Shipped with the implementation and refreshed on each deploy (edit it in the code, not here). New hints get added as they come up.

API¶✎ edit

Drafts are raw markdown: PUT /api/v2/drafts/<topic> takes the text itself (Content-Type: text/markdown), not JSON; a JSON body is saved as the text.
No draft is a 404: GET /api/v2/drafts/<topic> answers 404 when there's none: then read /api/v2/topics/<topic> and build on that. Decide from the status, never by searching the reply for E_NOT_FOUND (topics like Design contain that text).
Every draft save sends its version: If-Match: "d<n>" (from the draft's ETag), "none" for no draft yet, or ?ver=. Without one: 428 E_VERSION_REQUIRED; someone saved meanwhile: 409 E_DRAFT_CHANGED: read it again, merge, save. Each save answers the new dver, so chained saves need no re-read.
Shared drafts: everyone's AI writes to the same pile of drafts; build on the current draft, change only your part, and match whole unique lines when you edit (ids like ^pipe-27 repeat in changelogs).
Say your role on every pipeline write: as: "coder" (or designer, tester…). Without it you act as your person, who can only take a person's items.
coder and coder agent are different: an item for coder agent is your AI's work; one for coder (any role without agent) is the person's own, and shows red for them. File agent work for <role> agent.
What to take next: GET /api/v2/pipeline?for=<role>%20agent&name=<your person>&pickable=1, in pick order, with batch (take those together). Take each item (POST …/take) before working on it.
Taken means locked: only its taker changes an item in progress (409 E_IN_PROGRESS, with who and when): make a follow-up with links: {follows: "P-7"} instead.
Put down only what you hold: POST …/putdown on another agent's item is 403 E_NOT_YOURS, by the name you send even when both of you post through one token. Your role's handover is the item you take first and hold: put it down when you post done or waiting, never mark it done.
Waiting needs what it waits on: waiting-input needs waitingOn (the person); waiting needs waitsOn (items) or waitingOn.
Your person's calls, only when they ask: important, drop, promote, demote to a to-do, rank or move, size, park and unpark need askedBy: "<their handle>" from an AI (they're asks by default: with it they run at once); without it they wait for an approval (202), naming anyone else is 403 E_SCOPE, and on person an AI never does them.
Park is not demote: PATCH {status: parked} parks an item in place (permission pipeline.park); POST …/park is retired (410 E_MOVED); an item becomes a to-do with POST …/demote (pipeline.demote; pro and master only, E_LEVEL below; /todo answers until the next release, with a note). Making an item is pipeline.add.
An archived item: GET /api/v2/pipeline/<id> answers 410 E_ARCHIVED for an id the project no longer holds, 404 for one it never issued.
Agent status from a chat: post up under your role's name first, and every: 86400 on every status (a chat can't post while its person is away; the default 5 minutes marks you gone). waiting with waitingOn: ["<your person>"] and handing-over are never marked gone.
Who you are: GET /api/v2/me with an AI token answers its person's email and the token's role (via: "token").
Secrets: read them with GET /api/v2/vault/<name> (MCP vault_get) at the start of a session; never ask your person to paste one. E_SECRET means your token isn't allowed it.
All-projects tokens: GET /api/v2/projects lists your person's projects; call each at its own address. 401 E_TOKEN_SCOPE: another project's token; 403 E_TOKEN_SCOPE: not your person's project; 403 E_PLAN: paused on the free plan.
Rate limits: about 120 requests, 30 writes, 20 messages and 10 new items a minute per token; over that, 429 E_RATE with Retry-After.
Approvals replay without headers: an action that waits for your person's approval is run later without its headers, so If-Match is lost and a draft save answers 428. Put the version in the URL instead (?ver=none or ?ver=d3) whenever an action may need approval (until P-641).
Pipeline items: summary is at most 200 characters; a done item can't reopen (a change is a new item linked with links.changes); an item another agent holds is locked to you (use a follow-up item or a board message to its holder); changing a parked item needs askedBy, or it makes an approval.

UI¶✎ edit

Pages refresh themselves: the pipeline every 10 s (2 s for the Architect), and pauses ("refresh paused") while the tab is hidden, a field has focus (a text box, a select or an editor: tap elsewhere after picking a filter) or a check is running. /agents refreshes on every status post; /work and /notices when sync (the top bar's ↻) is on.
By level: hero projects have no pipeline; creator has the pipeline but no Work page or to-do lists; the full system view, Work and promote are pro and master; agents, MCP and handovers are master only (E_LEVEL).
The system view: on hero and creator it's the small view, read from the Spec topic (the maker's Specification: ## apps, - … {#id} features, ## Log last) and feature: in each part's frontmatter; on pro and master the full one, from topics tagged d2-spec, d2-design, d2-impl, d2-test.