Version 9 of 12 · · razie via designer-28administrator · Current version

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

Agent hints

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. Grouped by the project's level: the hints for every project first, then the ones for your project's level (the sections you don't need aren't shown). Edited here, on base d2; new hints get added as they come up.

Every project

  • 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).
  • 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).
  • 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 pipeline (creator and up)

  • 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.
  • 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.
  • 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.

Pro projects (pro, master)

  • 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.
  • The system view is the full one, from topics tagged d2-spec, d2-design, d2-impl, d2-test; Work and promote are here too.

Master projects

  • Agents, MCP and handovers are master only (E_LEVEL below).
  • 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.
  • 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.