Task boards
A task board is a page of its own with columns and tickets. People work it in the browser. Agents work it over MCP with six tools. Both see the same tickets, and every change says who made it: a person, or an agent and whose agent it is.
Task boards are being turned on one organisation at a time. If the new-page dialog does not offer Task board, they are not on for your organisation yet.
Why a board and not a markdown table
A task list kept as a page grows with every task. An agent has to read the
whole page to find its work and rewrite the page to change one line, and two
writers editing it at once collide. On a board each ticket is a record of its
own. board_get returns one short row per open ticket and leaves finished
ones out, so reading the open work costs an agent a small fraction of reading
the same tasks as a page. A move or a comment is one small call, and it never
touches the page's text or its version.
Making a board
In the browser, choose New page, then Task board under What to make.
Give it a path, a title and a Ticket prefix: two to five capital letters,
such as HL, which start every ticket's identifier (HL-1, HL-2). The
prefix is suggested from the title and cannot be changed later, so a link to a
ticket never breaks.
An agent makes one with board_create. A new board has the columns Backlog,
Todo, In progress, In review, Done and Cancelled, unless the agent names its
own. Each column has a kind: open, started, done or cancelled. Tickets
in done and cancelled columns count as finished.
The page's own text is the board's introduction. The board shows in the page list like any other page.
Board and list
Every board has two views, Board and List, switched in the toolbar under the title. The board shows the columns side by side. The list shows the same tickets in rows, with Group by (Status, Assignee or No grouping) and Sort by (Board order, Priority, Due date, Last updated or Newest). Your browser remembers which view you last used on each board.
Finished tickets stay on screen for 14 days. After that a column says how many older tickets it holds, with Show to bring them back.
Anyone can collapse a column for themselves from its menu. That changes only their own view.
Tickets
A ticket has a title, details in markdown (where [[wikilinks]] work) and
these properties:
| Property | What it holds |
|---|---|
| Status | The column it is in |
| Priority | None, Urgent, High, Medium or Low |
| Assignee | One person or one agent, or no one. An agent is assigned by its API key's label |
| Labels | Any number. Naming a new label makes it |
| Estimate | Whole points, 0 to 100 |
| Due date | A day |
| Parent | The ticket it is a sub-ticket of |
| Sprint | The sprint it is in, or none (see Sprints) |
To make a ticket, press New ticket or C, or use Add ticket at the foot of a column. A field opens at the top of the column; type a title. The field stays open for the next one.
Sub-tickets. A ticket can have sub-tickets, one level deep. A ticket with sub-tickets is what a team calls an epic. Add one with Add sub-ticket on the parent, or give a ticket a parent. A sub-ticket is on the same board as its parent, and cannot have sub-tickets of its own. The parent shows how many of its sub-tickets are done.
Opening a ticket. Click a card or a row. On a wide screen the ticket opens
in a panel over the board; under 900px it opens on a page of its own. The
open ticket is in the address (?ticket=HL-12), so you can link to it.
Comments and the record of changes. Anyone who can edit can comment. Under the details, the ticket lists its comments and every change to it, oldest first: who made it, what changed, and when. A change an agent made reads as the agent's and names the person it acts for. You can edit or delete your own comments. An agent's comments cannot be edited or deleted.
Details are versioned. If someone else changed a ticket's details while you were editing them, your save is refused and your edit stays in the editor. Details changed while you were editing shows who changed them and what changed, with Keep editing and Reload theirs. Other properties take the last write.
Relating tickets
A ticket's Related tickets section lists how it relates to other tickets.
Each relation reads from the ticket you are looking at, and shows on both. One
relation between HL-4 and HL-9, seen from each side:
| HL-4 shows | HL-9 shows |
|---|---|
| Blocks HL-9 | Blocked by HL-4 |
| Duplicate of HL-9 | Duplicated by HL-4 |
| Related to HL-9 | Related to HL-4 |
A related ticket on another board shows only its identifier, which opens it.
A ticket that is blocked shows Blocked on its card, in the list and on the ticket, for as long as a ticket blocking it is not in a done or cancelled column. Finishing the blocker clears it; nobody has to touch the blocked ticket. Nothing else moves by itself: marking a ticket as a duplicate does not cancel it, and you move it yourself if you want it gone.
To add one, choose Add relation, pick the kind under Relation, then
choose the ticket from this board, or type the identifier of a ticket on
another board of the project, such as OPS-12. Choosing saves it. Two
tickets cannot block, or duplicate, each other. Remove takes a relation off
at once and offers Undo for a few seconds.
Links
A ticket's Links section holds web addresses: a pull request, a design, a
document. Choose Add link, paste the Address and, if you like, a
Title; left empty, the title is the address's host and path. Only
addresses that start with http:// or https:// are taken. Each link
says who added it.
A GitHub pull request, issue or commit is recognised by its address and shown
as one, with its repository and number, such as harbourlight/site#12.
Nothing is fetched from GitHub or from any address, so a link shows no open or
merged state; it is the address and its title. Remove takes a link off at
once and offers Undo.
Sprints
A sprint is a name and a stretch of dates on one board, such as Sprint 7, Nov 10 to Nov 23. The end date is the sprint's last day, and a board's sprints never overlap. A ticket is in one sprint or in none.
Anyone who can edit manages sprints from Board options, beside the board's title, then Manage sprints (it is also the last choice in the sprint filter). The dialog lists the board's sprints with their dates and progress. New sprint opens a form filled in after the last sprint: the next number, starting the day after it ends, as long as it ran. Edit renames or re-dates a sprint. Delete removes one; a sprint that holds tickets asks first, and its tickets stay on the board and leave the sprint. A sprint cannot be named Current, Next or None.
Put a ticket in a sprint from its Sprint row. A ticket made while the board shows one sprint lands in that sprint.
The sprint filter. On a board with sprints, the toolbar has a Sprint
choice: All tickets, the current sprint, the next, the others by start, or
No sprint. It travels in the address like the other filters:
?sprint=current always means the sprint that includes today's date in UTC,
?sprint=next the next one, and a sprint's name that sprint. On a day with no
current sprint (or no next one), the address drops it and the board shows all
its tickets. Opened with no sprint in the
address, a board shows the sprint you last chose on it in this browser. Under
the toolbar a line
describes the sprint shown, or the current one when all tickets are shown:
its dates, how many days are left, and how much is done, for example
Nov 10 to Nov 23 · 6 days left · 12 of 20 done, 31 of 50 points. The counts
are the whole sprint's, whatever else is filtered.
When a sprint ends. If the latest sprint that is over still has unfinished tickets, anyone who can edit sees an offer above the line to move them into the current sprint, or the next one. With no sprint after it, the offer is Plan the next sprint. Not now puts the offer away in this browser. The same move is in Manage sprints. Nothing moves until someone presses it.
No agent tool makes, renames or deletes a sprint. An agent reads a board's
sprints with board_get and puts a ticket in one with ticket_create or
ticket_update.
Moving a ticket
A member moves a ticket in any of three ways:
- Drag the card to another place or column. A click still opens it.
- Keyboard. With a card focused, press Space to pick it up, the arrow keys to move it, Space to drop it and Escape to cancel.
- Move to. Press M on a focused card and choose a column.
A move shows at once. If the server refuses it, for example because someone moved the ticket since you last saw it, the card goes back and the reason is shown.
Filters
The toolbar has a box that narrows the tickets by title or identifier as you type, and three lists to tick: Assignee (Me, Agents, No one, or a person), Label and Priority. While any filter is on, the toolbar says how many tickets show of how many, with Clear filters.
Filters are kept in the address, so a link carries them and a reload keeps
them: ?q=login&assignee=me,agents&priority=urgent,high, with one
label= for each label, and sprint= for the sprint filter.
Filters change what is drawn, never the column counts.
Live updates
A board open in your browser changes when someone else, or an agent, changes it. You see who else has the board open in the toolbar. While you hold a card, other changes wait until you drop it. If the connection drops, the toolbar says Live updates paused. Reconnecting…, and after ten seconds offers Reload.
On a phone
Under 640px a board is shown as its list, with no Board and List switch. There is no dragging on a phone: each row has a Status button that opens Move to. A ticket opens on its own page.
Who can do what
Boards follow the same roles as pages (see Inviting your team).
| Who | Can |
|---|---|
viewer | Read boards and tickets, their relations, links and sprints; filter, switch views, collapse columns for themselves. Changes nothing |
member | Everything a viewer can, and make boards, make and change tickets, move them, relate them, add and remove links, manage sprints, comment, and edit or delete their own comments |
admin, owner | Everything a member can, and change columns, delete a ticket, and delete a board |
An admin changes columns from each column's menu: rename it, change its kind, move it, or add one. A column can be deleted only when it is empty, and a board always keeps at least one. An admin deletes the open ticket from Ticket options; its comments and record go with it, and its sub-tickets stay with no parent. An admin deletes a whole board from Board options beside its title, by typing the board's title to confirm. That deletes every ticket on it and cannot be undone.
What an agent can do over MCP: list and read boards and tickets, make a
board, make tickets, change and move them, and comment. What an agent cannot
do: no tool deletes a ticket, a comment or a board, and no tool changes a
board's columns after board_create. To drop a ticket, an agent moves it to
a cancelled column. A page delete of a board that holds tickets is refused
with BOARD_NOT_EMPTY, by wiki_deletePage and by the REST API's page
delete alike.
The board routes of the REST API are for people signed in to WitWiki. They
are in no scope, so an API key or a connected app with scopes gets 403 with
SCOPE_DENIED, and a key with no scopes gets 403 with PEOPLE_ONLY.
Agents use the MCP tools.
Setting up an agent
The board tools arrive with the rest of the server's tools; there is nothing
to install. For an organisation with boards on, the server's opening
instructions and wiki_guide each add one line telling the agent to use a
board for tasks, not a markdown table. A line in your CLAUDE.md or
AGENTS.md makes it a habit:
### Tasks
Open work is on the task board at team/board. Read it with board_get
({path: "team/board", assignee: "me"}), then ticket_get for the ticket you
pick. Move a ticket with ticket_update and send from, the column you saw it in.
Comment with ticket_comment. Never keep tasks in a markdown table.
Every tool call counts as one MCP call toward your plan, like any other (see
Limits and plans). board_get and ticket_get
need the wiki:read scope; the other four need wiki:write. A key without
the scope is refused with SCOPE_DENIED.
Names, not ids
Columns, labels and assignees are named in and out, in any case: "in progress" names In progress, and a label "bug" reuses Bug. Tickets are
named by identifier: HL-42, and hl-42 or HL-042 find it too. As an
assignee, me is the caller: the key, for an agent on an API key, or the
person it acts for, for an agent connected over OAuth.
Every change made over MCP is recorded as an agent's, even when the agent acts
for a person through OAuth. An agent on a key is shown by the key's label and
its owner, for example claude-code for maya@harbourlight.test.
Refusals
A refused call says what was wrong and what to send instead. The text starts
with a code, then a sentence, then what to send, then the refusal as JSON; the
code is also in _meta.error_code. An unknown column, sprint, relation or
link comes back with the names that would match (choices); an unknown
assignee points at board_get's assignable:
MOVED_SINCE: HL-1 is in Backlog now: ci-bot moved it since you read it
from as "Backlog" to move it from where it is now, or leave it there
{"error": "MOVED_SINCE", "message": "…", "send": "…", "id": "HL-1", "column": "Backlog", "from": "Todo", "moved_by": {…}, "moved_at": "…"}
The six tools
board_create
Makes a board: a new page at path with columns.
| Parameter | Type | Required | What it is |
|---|---|---|---|
path | string | yes | The page path for the board; no page may be there yet |
title | string | yes | The board's title |
key | string | no | Two to five capital letters that start every identifier; suggested from the title when left out; fixed once made |
columns | array | no | [{name, kind}] in order, kind one of open, started, done, cancelled. The six default columns when left out |
Returns the board: path, title, key, columns (each with its
kind and ticket count), labels and created_by.
Refusals: PAGE_EXISTS, KEY_TAKEN, INVALID_KEY, INVALID_COLUMNS,
INVALID_FIELD.
{"path": "team/board", "title": "Harbourlight", "key": "HL"}
board_get
With no path, lists the project's boards. With a path, reads one board
and its tickets.
| Parameter | Type | Required | What it is |
|---|---|---|---|
path | string | no | A board's page path; leave out to list the boards |
column | string | no | Only tickets in this column, finished ones included |
assignee | string | no | me, an email, a key label, or none |
label | string | no | Only tickets with this label |
text | string | no | Words to find in titles and details |
include_finished | boolean | no | Include tickets in done and cancelled columns |
sprint | string | no | current, next, a sprint's name, or none for tickets in no sprint |
Returns, with no path, {boards}: each board's path, title,
key, and how many tickets are open of the total. With a path,
{board, assignable, tickets, total}: the board's columns with counts, its
labels and sprints; who can be assigned (members by email, keys by label);
the tickets as short rows (id, title, column, assignee,
priority, parent, sub-ticket counts, estimate, sprint, and
blocked: true while a ticket blocking it is unfinished), in board order,
finished ones left out, at most 200; and total, how many matched.
Refusals: BOARD_NOT_FOUND, UNKNOWN_COLUMN, UNKNOWN_ASSIGNEE,
AMBIGUOUS_ASSIGNEE, UNKNOWN_SPRINT, and FILTER_NEEDS_BOARD for a
filter sent without a path.
{"path": "team/board", "assignee": "me"}
ticket_create
Makes a ticket on a board, at the top of its column.
| Parameter | Type | Required | What it is |
|---|---|---|---|
board | string | yes | The board's page path |
title | string | yes | One line |
details | string | no | Markdown; [[wikilinks]] allowed |
column | string | no | A column name; the first column when left out |
priority | string | no | none, urgent, high, medium or low |
assignee | string | no | me, a member's email, or an API key's label |
labels | string[] | no | Label names; a new name makes the label |
estimate | integer | no | Whole points, 0 to 100 |
due | string | no | YYYY-MM-DD |
parent | string | no | The identifier of the ticket it is a sub-ticket of |
relations | array | no | Relations to add, as in ticket_update's add_relations |
sprint | string | no | current, next or a sprint's name on this board |
links | array | no | Links to add, as in ticket_update's add_links |
Returns the ticket in full, as ticket_get does, with its identifier.
Refusals: BOARD_NOT_FOUND, UNKNOWN_COLUMN, UNKNOWN_ASSIGNEE,
AMBIGUOUS_ASSIGNEE (two keys share the label), INVALID_PARENT,
INVALID_RELATION, UNKNOWN_SPRINT, INVALID_LINK, INVALID_FIELD.
{"board": "team/board", "title": "Fix the signup form", "column": "Todo", "assignee": "me", "labels": ["Bug"], "parent": "HL-4"}
ticket_get
Reads one ticket in full.
| Parameter | Type | Required | What it is |
|---|---|---|---|
id | string | yes | The identifier, such as HL-42 |
Returns the title, details and details_version, column, priority,
assignee, labels, estimate, due date, parent, sub-tickets with how many are
done, relations, blocked, sprint, links, comments oldest first, and the
newest 50 entries of its record of changes, each saying who and when.
Refusals: TICKET_NOT_FOUND, also for a ticket in another project.
ticket_update
Changes a ticket. Send its id and only the fields to change; a field left
out is left alone.
| Parameter | Type | Required | What it is |
|---|---|---|---|
id | string | yes | The identifier |
column | string | no | Move it to this column, at the top unless before or after is sent |
from | string | no | The column you saw it in; refused with MOVED_SINCE if it has moved since |
before | string | no | Place it directly above this ticket in the target column |
after | string | no | Place it directly below this ticket in the target column |
title | string | no | One line |
details | string | no | Replaces the details; needs details_version |
details_version | string | no | From ticket_get; a stale one is refused with VERSION_CONFLICT and a diff |
priority | string | no | none, urgent, high, medium or low |
assignee | string | no | me, an email, or a key label |
labels | string[] | no | Replaces the ticket's labels |
estimate | integer | no | Whole points, 0 to 100 |
due | string | no | YYYY-MM-DD |
parent | string | no | The parent's identifier |
sprint | string | no | current, next or a sprint's name; none takes it out |
clear | string[] | no | Fields to empty: assignee, estimate, due, parent, labels, sprint. Sending one of them as null does the same |
add_relations | array | no | [{kind, id}], at most 20 |
remove_relations | array | no | [{kind, id}] as ticket_get lists them, at most 20 |
add_links | array | no | [{url, title}], at most 20 |
remove_links | string[] | no | Addresses as ticket_get lists them |
before or after with no column reorders the ticket within its column.
Send from with every move: if someone moved the ticket since you read it,
the move is refused with MOVED_SINCE, saying where it is now and who moved
it, and nothing changes.
Relations link two tickets in the same project, on any of its boards.
kind is blocks, blocked_by, duplicates, duplicated_by or
relates, read from the ticket you send it on: HL-1 blocks HL-9 is the
same relation as HL-9 blocked_by HL-1. A ticket reads blocked while a
ticket blocking it is not in a done or cancelled column. Nothing moves
because of a relation. Two tickets cannot block or duplicate each other.
Sprints belong to a board. board_get lists a board's sprints by start
date, each with its dates, its state (over, current, next or
later, judged by today's date in UTC) and how many of its tickets and
points are done. No tool makes, renames or deletes a sprint: a person does
that from Manage sprints. A board with none lists sprints: [], and
naming a sprint on it is refused with UNKNOWN_SPRINT.
Links are addresses with titles. An agent that opens a pull request puts it
on the ticket with add_links. A pull request is not linked by itself:
someone, or an agent, has to add it. Nothing is ever fetched from a link. A GitHub
pull request, issue or commit address is recognised by its form alone and kept
in one spelling, with its repository and number.
People see and change relations, links and sprints on the ticket and the board (see Relating tickets, Links and Sprints).
Returns the ticket in full.
Refusals: TICKET_NOT_FOUND, UNKNOWN_COLUMN, UNKNOWN_NEIGHBOUR
(a before or after not in the target column), MOVED_SINCE,
DETAILS_VERSION_REQUIRED, VERSION_CONFLICT, UNKNOWN_ASSIGNEE,
AMBIGUOUS_ASSIGNEE, INVALID_PARENT, INVALID_RELATION,
UNKNOWN_RELATION, UNKNOWN_SPRINT, INVALID_LINK, UNKNOWN_LINK,
INVALID_FIELD, and NOTHING_TO_CHANGE when no field to change was sent.
{"id": "HL-12", "column": "In review", "from": "In progress", "add_links": [{"url": "https://github.com/harbourlight/site/pull/12"}]}
ticket_comment
Adds a comment to a ticket. Nothing over MCP edits or deletes a comment.
| Parameter | Type | Required | What it is |
|---|---|---|---|
id | string | yes | The identifier |
body | string | yes | Markdown |
Returns the ticket's identifier and the comment with its author and time.
Refusals: TICKET_NOT_FOUND, INVALID_FIELD for an empty body.
Reading a board's page
wiki_getPage on a board's page returns the introduction as the page's
content, and adds a board field: the key, the columns with a ticket count
each, and a sentence pointing at board_get. Tickets are not pages: they are
not in the page list, the search box, the brief or the link graph.
Related
- Teaching your agent: the habits to put in
CLAUDE.md. - MCP tool reference: the wiki, source and project tools.
- Teams, roles, and what an agent is allowed to do: scopes and roles.