Move an issue to another status (board drag = this call). Scrum + AI agent: only for issues in a sprint a person has started, else 409 `sprint_not_started` (D79). AI agent: a move out of another role's lane still happens but the result carries `warnings` (D136) — stop and tell the user.
transition_issueMove an issue to another status (board drag = this call). Scrum + AI agent: only for issues in a sprint a person has started, else 409 sprint_not_started (D79). AI agent: a move out of another role's lane still happens but the result carries warnings (D136) — stop and tell the user.
status must be a status id from get_project (never one marked removing: true — 409 column_removing). For several field changes at once use update_issue instead. A status with requires_comment: true (Feedback template: Declined, D143) needs comment — the reason, written as a comment — in the SAME call, else 400 comment_required (details.status); the same rule holds for update_issue with status. Move to Declined only when the user asks. On a pipeline board an issue moves Backlog → To Do → Developing → Dev Done → then, for each environment in environments order, Testing (env) testing_<id> → Passed (env) passed_<id> → … → Done. When testing fails in an environment, move it to Test Rejected (test_rejected) and it goes back to development. "Deployed to UAT" / "testing on UAT" means testing_<id of UAT>; "passed UAT" means passed_<id> — look the id up in get_project environments. Scrum boards (spec D79): you may change the status only of issues in a sprint a PERSON has started (list_sprints state active); otherwise 409 sprint_not_started — do not retry, ask the user to start the sprint in BoardMark. Backlog planning (create_issue, update_issue fields other than status, move_to_sprint, comments) is always fine. Move only the part of the flow that belongs to your role (developer: To Do → In Progress/Developing → In Review/Dev Done; QA: → Done/Passed (env) or Test Rejected; BA: up to To Do), unless the project's docs or the user say otherwise. Lanes (spec D136): each status belongs to a role (get_docs_context shows the Lane column). Pass as_role (e.g. Developer, QA) when the user told you your role; otherwise your token's role is used. The move always happens, but when it leaves another role's lane the result carries warnings (role_lane, skip_lane, self_review): stop there, tell the user what you did, and hand off with a comment — undo it (transition back to from) if the user did not want it. transition_issue also takes working, touches and if_unassigned (D179), so moving a card to in progress and claiming it is one call. Agent work context (D179): working = what you are doing on this card, how and why (markdown, ≤ 600 characters) and touches = the files, modules or APIs you change (≤ 10 entries ≤ 120) — the next agent or person on a linked card reads them before changing the same things. When you START a card, do it in ONE call: status (the in-progress status), working, touches and if_unassigned: true — an unassigned card becomes yours in the same commit; 409 already_assigned (details.assignee) means someone else holds it: nothing was written, pick another card or ask the user. Update working again only when your approach changes — not every step (comments are for decisions people should be emailed about). null clears; entering a done status clears both. working_at / working_by / working_by_agent are set by BoardMark. A result warnings[] item with code: unresolved_blocker means this card is blocked_by a card that is not done (blocker: key, title, status, its working): the move is done — read that card (get_issue_context) and agree the order before you change what it touches. code: touch_overlap (D180) means another in-progress card touches the same files / folders (overlap: key, title, assignee, its touch, yours, its working): the move is done — read its working and agree who changes what first.
WRITE: version = from your latest read (get_issue, list_comments, list_sprints, get_doc, read_file). 409 version_conflict (details.current, details.current_version): re-read, re-apply your change, retry — never overwrite blindly; when the changes disagree, ask the user.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | Spec D144: why you make this change (≤ 200 characters). Optional, but give it when you act as an agent account — it is shown in the agent's run log ("moved KJ-12 To Do → In Progress because <reason>"). board-mcp records it in `agent.run`; board-core / board-files accept it and ignore it (it never changes the file, the version or the history). | |
| status | Yes | Status id; must exist in the project's `project.md` statuses. | |
| as_role | No | AI agents (spec D136): the role you work as in this session (e.g. Developer, QA, BA, DevOps) when the user told you one; else your token's role is used. Only changes lane warnings, never what you may do. Ignored for people. | |
| comment | No | Spec D143 (6): a comment written in the same commit as the move (a normal comment by the actor; watchers are notified once). Required when the target status has `requires_comment: true` (Feedback template: Declined) — missing or empty → 400 `comment_required` (`details.status`). Optional for every other status. | |
| touches | No | Spec D179: the files, modules or APIs your work changes (≤ 10 entries of ≤ 120 characters, e.g. `board-core/internal/engine/`), the complete list. `null` or [] clears it. | |
| version | Yes | Optimistic-lock version of the file; +1 on every write. Every write must send the version it read. | |
| working | No | Spec D179: what you are doing on this card, how and why (markdown, ≤ 600 characters) — read by the next agent or person on a linked card. Write it when you start and again only when your approach changes, not every step. `null` or "" clears it. Stamps `working_at` / `working_by`; cleared by board-core when the issue enters a done status. | |
| issue_key | Yes | Issue key `{PROJECT}-{n}`, e.g. `KJ-101`. | |
| project_key | Yes | Project key, e.g. `KJ`. 2–10 chars, uppercase letters and digits, starts with a letter. | |
| if_unassigned | No | Spec D179: claim the issue atomically. true → if someone else holds it (`assignee` set and not you) nothing is written and the answer is `409 already_assigned` (`details.assignee`); otherwise the write goes ahead and, when the issue has no assignee and the request names none, you become the assignee in the same commit. "You" = your agent account `agt_…` (D144), else your user. Use it with `status`, `working` and `touches` in one call when you start a card. |