4 · Driving the Projects engine
What you will have done: taken a piece of work from nothing to parked in review without opening a browser, and understood the one door you cannot walk through.
An agent on the board is an ordinary assignee. It reads the same board, moves cards through the same door, and is refused by the same rules, with one addition: an agent does not finish its own work.
The loop
sequenceDiagram
participant A as Your agent
participant W as work_* tools
participant B as The board
participant P as A person
A->>W: work_ready
W-->>A: unclaimed, unblocked, priority order
A->>W: work_get
W-->>A: fields, comments, relations, revision
A->>W: work_claim (item, revision)
B-->>A: in progress, assigned to you
Note over A: it does the work
A->>W: work_comment — what it found
A->>W: work_link — the merge request
A->>W: work_move → done
B-->>A: parked in review, approval id, NOT done
B->>P: it appears in their review queue
P->>B: approve
Note over B: only now is it done
The walkthrough
1. Find the project
work_projects lists the projects the token can reach, with the metadata each one carries. Project ids are opaque strings rather than uuids, so read one rather than composing one.
2. File the work
work_create opens an item in a project the token can reach. Give it a title, a kind, a description and, where the work has a shape you can state, acceptance criteria. An item under an epic names its parent_id.
An item worth filing is one somebody else could pick up from its description alone. That is the same bar a person’s issue is held to.
3. Write a plan, where the work needs one
A plan is the thing a set of epics hangs under, and it is decided rather than written. The tools follow the screen’s own sequence. work_plan_create drafts it. work_plan_submit puts it up for a decision. work_plan_decide accepts a submitted plan or returns it to its author, along with the note it was decided on, so the reasoning lives with the decision rather than in somebody’s memory. work_plan_signoff opens the signoff gate on an accepted plan, and the answer carries the approval id. work_plan_complete closes a plan once the work has landed, and is refused with the open ids while any item the plan minted is still open.
The gate is the same gate the screen enforces: the author may not decide. An agent that drafted a plan cannot approve it, and neither can the person who wrote one.
work_plan_signoff opens the gate and hands back the approval id. Anyone who may write on the board may ask for it. Who may then sign is the project’s owners, admins and pms, minus the plan’s author, and they decide it in the approvals inbox. The epics are minted when that approval is decided, not when the tool is called. There is no tool that clears it.4. Claim what is ready
work_ready is work that is ready, assigned to nobody, and blocked by nothing, in the order to do it. work_claim takes one, with the revision read from work_get.
Two workers cannot hold one card. The second attempt is refused and names who holds it, which is an answer rather than an error.
5. Move it
work_move takes the item, the column and the current revision. A stale revision is refused rather than merged.
The transition matrix decides whether a move is legal. It is the same matrix a drag on the board meets, so a move a person could not make is a move the tool will not make either.
6. Link the code
work_code_link attaches a code-host link to an item and detaches one. The item’s status is then written onto that issue as a label. Nothing comes back the other way: Neutron is the tracker of record, and there is no second copy to keep in step.
work_report reads what a project has done in one call, and work_sprints reads its weeks. Both are read-only.
7. Close it, or rather, ask to
work_move to done is where the loop ends and does not end.
Every move to done an agent makes parks in review. Not only the items somebody ticked Needs review on. Every one. The item lands in In review, the answer carries the approval id, and the agent is told plainly that it is waiting on a person and is not done until they approve it.
The person who decides is not the item’s author, and an agent is never that person. A worker does not get to decide that its own work is finished.
Reordering a card already in Done is not entering it, so an agent tidying that column un-finishes nothing.
Know what comes back to you
| You call | What actually happens |
|---|---|
work_claim on an item somebody holds | Refused, naming who holds it. |
work_update with a stale expected_revision | Refused. Read the item again and retry against the revision it gives you. |
work_update with a status | Refused. Status moves through work_move, which is where the gate is. |
work_move to done, as an agent | Parked in review, with an approval id. Not done. |
work_move along an illegal transition | Refused by the same matrix a drag meets. |
work_link to an item in another project | Refused. Relations are within a project; cross-project work is linked, not related. |
work_create in a project the token cannot reach | Refused. Membership decides what a token sees, for an agent exactly as for a person. |
work_plan_decide on a plan you wrote | Refused. The author may not decide, whether the author is a person or an agent. |
What this does not reach
admin_request reaches no work route at all. The two surfaces are gated separately and deliberately, so widening the admin allowlist can never quietly widen the board. api_request does reach /api/work/*, as the person the token is bound to and with every gate on this page still standing, but composing those routes by hand buys nothing the twenty tools above do not already do.