WitWiki

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:

PropertyWhat it holds
StatusThe column it is in
PriorityNone, Urgent, High, Medium or Low
AssigneeOne person or one agent, or no one. An agent is assigned by its API key's label
LabelsAny number. Naming a new label makes it
EstimateWhole points, 0 to 100
Due dateA day
ParentThe ticket it is a sub-ticket of
SprintThe 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 showsHL-9 shows
Blocks HL-9Blocked by HL-4
Duplicate of HL-9Duplicated by HL-4
Related to HL-9Related 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.

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

WhoCan
viewerRead boards and tickets, their relations, links and sprints; filter, switch views, collapse columns for themselves. Changes nothing
memberEverything 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, ownerEverything 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.

ParameterTypeRequiredWhat it is
pathstringyesThe page path for the board; no page may be there yet
titlestringyesThe board's title
keystringnoTwo to five capital letters that start every identifier; suggested from the title when left out; fixed once made
columnsarrayno[{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.

ParameterTypeRequiredWhat it is
pathstringnoA board's page path; leave out to list the boards
columnstringnoOnly tickets in this column, finished ones included
assigneestringnome, an email, a key label, or none
labelstringnoOnly tickets with this label
textstringnoWords to find in titles and details
include_finishedbooleannoInclude tickets in done and cancelled columns
sprintstringnocurrent, 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.

ParameterTypeRequiredWhat it is
boardstringyesThe board's page path
titlestringyesOne line
detailsstringnoMarkdown; [[wikilinks]] allowed
columnstringnoA column name; the first column when left out
prioritystringnonone, urgent, high, medium or low
assigneestringnome, a member's email, or an API key's label
labelsstring[]noLabel names; a new name makes the label
estimateintegernoWhole points, 0 to 100
duestringnoYYYY-MM-DD
parentstringnoThe identifier of the ticket it is a sub-ticket of
relationsarraynoRelations to add, as in ticket_update's add_relations
sprintstringnocurrent, next or a sprint's name on this board
linksarraynoLinks 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.

ParameterTypeRequiredWhat it is
idstringyesThe 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.

ParameterTypeRequiredWhat it is
idstringyesThe identifier
columnstringnoMove it to this column, at the top unless before or after is sent
fromstringnoThe column you saw it in; refused with MOVED_SINCE if it has moved since
beforestringnoPlace it directly above this ticket in the target column
afterstringnoPlace it directly below this ticket in the target column
titlestringnoOne line
detailsstringnoReplaces the details; needs details_version
details_versionstringnoFrom ticket_get; a stale one is refused with VERSION_CONFLICT and a diff
prioritystringnonone, urgent, high, medium or low
assigneestringnome, an email, or a key label
labelsstring[]noReplaces the ticket's labels
estimateintegernoWhole points, 0 to 100
duestringnoYYYY-MM-DD
parentstringnoThe parent's identifier
sprintstringnocurrent, next or a sprint's name; none takes it out
clearstring[]noFields to empty: assignee, estimate, due, parent, labels, sprint. Sending one of them as null does the same
add_relationsarrayno[{kind, id}], at most 20
remove_relationsarrayno[{kind, id}] as ticket_get lists them, at most 20
add_linksarrayno[{url, title}], at most 20
remove_linksstring[]noAddresses 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.

ParameterTypeRequiredWhat it is
idstringyesThe identifier
bodystringyesMarkdown

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.