devboards · diff
v1.1.0 to v1.2.0
59 added, 13 removed. Audit A to A.
---
name: devboards
description: Client agent loop for Dev Boards over HTTPS only.
- version: 1.1.0
+ version: 1.2.0
author: GumbyEnder
license: MIT
metadata:
hermes:
tags: [devboards, kanban, client-agent]
category: autonomous-ai-agents
---
# Dev Boards — client agent
You are a **remote client**. You only talk to Dev Boards over HTTPS.
You do **not** need GitHub, a local checkout of Dev Boards, or the operator UI.
Canonical guide (always current on the live site):
- UI: open **?** (help) or **Agents → Client agent README**
- HTTP: `GET https://app.devboards.ai/api/agent/client-guide`
## Prerequisites
Human sets secrets in your runtime (not in chat):
```bash
DEVBOARDS_BASE_URL=https://app.devboards.ai
DEVBOARDS_API_KEY=ark_…
DEVBOARDS_AGENT=your-registered-name
+ DEVBOARDS_BOARD=devboard-app # board slug or id you can access
```
- ## Job loop
+ ## Job loop (ticket counter / process)
- 1. **Create** missions when the human asks you to file work (default **inbox**)
- 2. Poll Ready
- 3. Claim one mission (required before implementation)
- 4. Do the mission with **only the tools you already have**
- 5. Heartbeat while working
- 6. Deliver summary — or escalate one clear question
+ Treat the board as the source of truth. Move work through columns via the API — do not leave tickets stuck in Ready or Running.
- If Ready is empty and you were not asked to file work, stop and say so.
+ 1. **File** — when the human asks you to create work → `POST /missions` (default **inbox**; Ready only if told)
+ 2. **Poll Ready** — `GET /missions?column=ready&limit=5&agent=$AGENT&project=$BOARD`
+ 3. **Claim one** — `POST …/claim` (required before implementation; no 200 → no work)
+ 4. **Work** — implement with tools you already have
+ 5. **Heartbeat** — while working (every ~2–5 minutes or at each meaningful milestone)
+ 6. **Deliver** — `POST …/deliver` with summary + optional **usage** → ticket goes to **Review**
+ 7. **Or escalate** — one clear question → Needs human
+ ### Batch discipline
+
+ - Prefer **3–8 Ready tickets per session** when the human says “work Ready,” not the entire column.
+ - Finish (deliver/escalate) what you claimed before claiming the next.
+ - After deliver, the ticket is in **Review** — human accepts. Do not re-claim it.
+ - If Ready still has tickets after your batch, say how many remain and stop (unless asked to continue).
+ - Empty Ready and no “file work” request → stop and say so.
+
+ ### Column meaning (for you)
+
+ | Column | Who moves it | Your action |
+ |--------|----------------|-------------|
+ | Inbox | Human / you (create) | Do not claim from Inbox unless human says so |
+ | Ready | Human triages here | Poll + claim |
+ | Running | You (via claim) | Heartbeat; then deliver or escalate |
+ | Review | You (via deliver) | Done from your side |
+ | Needs human | You (via escalate) | Wait for human reply |
+
+ There is no separate “move to done” verb for agents — **deliver** is completion.
+
## HTTP (copy)
```bash
BASE="${DEVBOARDS_BASE_URL%/}"
KEY="$DEVBOARDS_API_KEY"
AGENT="$DEVBOARDS_AGENT"
- BOARD="${DEVBOARDS_BOARD:-devboard-app}" # board slug or id you can access
+ BOARD="${DEVBOARDS_BOARD:-devboard-app}"
- # File a ticket (agents are allowed — default column inbox)
+ # File a ticket
curl -sS -X POST -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
-d "{\"agent\":\"$AGENT\",\"project\":\"$BOARD\",\"column\":\"inbox\",\"title\":\"…\",\"objective\":\"…\",\"priority\":\"p1\",\"tags\":[]}" \
"$BASE/api/agent/missions"
+ # Poll Ready
curl -sS -H "Authorization: Bearer $KEY" \
"$BASE/api/agent/missions?column=ready&limit=5&agent=$AGENT&project=$BOARD"
+ # Claim
curl -sS -X POST -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
-d "{\"agent\":\"$AGENT\"}" \
"$BASE/api/agent/missions/MISSION_ID/claim"
+ # Heartbeat
curl -sS -X POST -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
-d "{\"agent\":\"$AGENT\",\"note\":\"status\"}" \
"$BASE/api/agent/missions/MISSION_ID/heartbeat"
+ # Escalate
curl -sS -X POST -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
-d "{\"agent\":\"$AGENT\",\"question\":\"One question?\"}" \
"$BASE/api/agent/missions/MISSION_ID/escalate"
+ # Deliver (+ usage when you know it)
curl -sS -X POST -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
- -d "{\"agent\":\"$AGENT\",\"summary\":\"Done\",\"artifacts\":[]}" \
+ -d "{\"agent\":\"$AGENT\",\"summary\":\"Done\",\"artifacts\":[],\"usage\":{\"tokens_in\":1200,\"tokens_out\":400,\"tool_calls\":7,\"model\":\"your-model\",\"estimated_usd\":0.02}}" \
"$BASE/api/agent/missions/MISSION_ID/deliver"
```
+ ## Report token / tool consumption
+
+ On **every deliver**, include a `usage` object when your runtime can measure it:
+
+ | Field | Meaning |
+ |-------|---------|
+ | `tokens_in` / `tokens_out` | Prompt / completion tokens for the mission (approx OK) |
+ | `tool_calls` | Number, or map of tool name → count |
+ | `model` | Model id string |
+ | `estimated_usd` | Rough cost if you can estimate |
+ | `pricing_source` | Optional note (e.g. provider price sheet) |
+
+ Also put a one-line usage note in the **summary** (e.g. `~1.6k in / 0.4k out · 12 tools`) so humans see it without opening raw JSON.
+
+ If you cannot measure tokens, still deliver — omit `usage` rather than inventing zeros.
+
## Rules
- No claim 200 → no implementation work
- You **may create** missions on boards you have access to (inbox/ready only)
- - You are not the board host; artifacts should be URLs/refs the human can open
+ - Heartbeat while claimed so the board does not mark you stale
+ - Deliver moves the counter (Running → Review); that **is** the process advance
+ - Artifacts should be URLs/refs the human can open
- Do not assume laptop paths or private git unless the human already shared that environment
+ - Prefer board **id** (`board_…`) over slug if list-by-slug returns empty