tada

Docs

Stories

Beyond its title, type, and column, a Story can carry a due date, tags, and a description, and duplicates can be merged into one. Each works the same whether you do it on the board or your agent does it through MCP.

Due dates

A Story can have a due date, and so can each of its Tasks. A due date is a calendar day, not a moment in time: a Story due on the 28th reads as the 28th for everyone, wherever they open the board.

The due chip

A dated Story shows a chip on its card and in the Story Detail View. The chip has three states, judged against your calendar day:

Due 2 OctUpcomingMore than two days away
Due tomorrowDue soonToday, or within two days
Overdue by 3dOverdueBefore today, and not Done
Task due in 2dFrom a TaskThe Story has no date, but one of its Tasks does
The app's own due chips, as they read on 14 September. Overdue pulses slowly; a chip taken from a Task has a dashed outline.

Close to today the chip counts down (“Due in 3d”). More than a week out it shows the date instead, which is more useful at that distance. Hover a chip to see the exact day.

A Done Story is never overdue. Finishing late is history, not a warning. If every Story that shipped late kept a red chip, the Done lane would fill with them and red would stop meaning anything.

Task dates on the Story card

A deadline that belongs to one piece of work can go on that Task instead of the whole Story. A Story card still shows one chip at most:

“Most urgent” goes by state first, then date. An overdue Task beats one due tomorrow, because it is the one that has already slipped. Done Tasks are skipped. A Task due after its Story is allowed on purpose: that is exactly what the board should point out.

Setting a date

On the board: open a Story and choose Set due date… in the header of the Story Detail View. With a mouse you get a calendar; on a touch screen, your device's own date picker. The ✕ beside a date removes it. Task dates are set through MCP for now.

Through MCP: add_story and update_story take a due_date as YYYY-MM-DD, and so do add_subtask and edit_subtask for a Task. An empty string removes the date. Relative dates like “next Friday” are refused, because what they mean depends on where the server runs. view_board prints each Story's date and marks the overdue ones.

Filtering by due date

The Board View's Filters menu has a Due slider anchored at today. Overdue sits to the left. Today, Week, Month, and Any sit to the right and mean “due by then”, so they include work that has already slipped. A planning view that hid slipped work would defeat its purpose. No date is a separate choice beside the slider.

The filter matches what the cards show: a Story dated only through a Task appears under that Task's date, and a Done Story counts as undated. The number on each notch counts the whole board, not just what your other filters leave, so you can see whether a view is worth opening.

Tags

A tag is a label on a Story, shown as an emoji. A Story can carry any number of them, drawn from one fixed set:

ai-generated

Created or edited by an AI agent. Added for you.

ui

Touches the user interface.

testing

About tests.

api

Touches the API or the MCP tools.

awaiting-release

Finished and waiting to ship. It stays In Progress until it's released.

On a card, a Story's tags sit under its id and cycle one at a time when there are several. Hover them, or tap on a phone, to see them all with their names. The Story Detail View shows them in its header.

Setting tags

On the board: open a card's ⋯ menu, or the ⋮ menu in the Story Detail View, and choose Tags. Each applied tag has a ✓. Click a tag to add or remove it. The menu stays open, so you can change several at once.

Through MCP: add_story and update_story take a tags list. On update_story the list replaces the Story's tags, and an empty list clears them. A tag outside the set above is refused.

ai-generated is automatic. Any agent write that creates, edits, or merges a Story adds it, so it records that an agent touched the Story. Moving a Story or Task between columns doesn't count as an edit and adds nothing. Your own edits on the board neither add nor remove it.

Filtering by tag

The Filters menu has a Tags section with an Any / All switch. Any, the default, shows Stories with at least one of the checked tags; All shows only Stories that have every one. Tags, Type, and Due filters combine, and the ✕ that appears beside Filters clears them.

Descriptions and Markdown

A Story's description is written in a small, deliberate subset of Markdown. Click Edit in the Description header of the Story Detail View to edit it (or click an empty description); click away to save. Clicking the text itself only selects it. Here is the same text as typed and as the board shows it:

**Expected:** the tag filter survives a reload.

**Observed:** it resets to *Any*. To reproduce:

- pick a tag under `Filters`
- reload the board

Same on the [live board](https://app.tada-ai.app/).

```ts
new URLSearchParams(location.search)
```

Expected: the tag filter survives a reload.

Observed: it resets to Any. To reproduce:

  • pick a tag under Filters
  • reload the board

Same on the live board.

new URLSearchParams(location.search)
Left, the description as typed. Right, the app's own renderer, styled as the Story Detail View styles it.
WriteTo getWorks in
**bold**BoldDescriptions and Task titles
*italic*ItalicDescriptions and Task titles
`code`Inline codeDescriptions and Task titles
[text](https://…)A link, opening in a new tabDescriptions and Task titles
tada-96 or tada-131.2A link to that Story or Task on this board, opened in placeDescriptions
# Heading, ## Smaller, down to ######A headingDescriptions
- item or * itemA bulleted listDescriptions
Lines between ``` fencesA code blockDescriptions
A blank lineA new paragraphDescriptions

Everything else shows as the literal characters you typed: numbered lists, quotes, tables, images, and HTML. Links must start with https://, http://, or mailto:; anything else is disabled.

Story and Task ids link themselves. Type a Story's id, or a Task's, and the board links it for you: the whole id, including a Task's .2. A Task link opens its Story with that Task's lane open and the Task marked. Only ids from the board you're on link, and an id inside a code span or a code block stays plain text.

Bug templates. A new Bug starts with Expected: and Observed: headings in its description, on the board and when an agent creates one without a description. The template only fills an empty description; it never replaces text you've written.

Merging Stories

When two or more Stories turn out to be the same piece of work, merge them into one. One Story, the primary, survives; the others fold into it and leave the board.

Starting a merge

Tick the Stories to fold in. A bar shows the primary and how many you've picked; choose Merge… there to review, or Cancel (or press Esc) to leave without changing anything. Opening a Story or another view also ends the picking. The board merges active Stories and the Changelog merges shipped ones, so a merge stays within the view you started it from.

What a merge does

A confirm dialog lists exactly this before anything happens. The primary keeps its title, type, lane, and dates, and gains from each merged Story:

A relationship that would make a Story depend on itself, through a loop of blocks links, is dropped rather than kept. The success toast names each one it dropped, so the loss isn't silent.

The primary keeps its lane. On the Board View you can pick Stories from any lane, and each one ends up wherever the primary is: merge a Planned Story into an In Progress one and its work is now In Progress. The confirm dialog names every pick that leaves its lane, so a status change never happens unannounced.

Through MCP: agents merge with merge_stories, which follows the same rules. See the Story tools.

The Changelog

A Story that has been Done for 30 days is filed to the Changelog, and you can file one sooner with Archive to changelog in the Story's ⋮ menu. Nothing is lost by filing: the Story keeps its description and Tasks, and Restore to In Progress brings it back to the board.

The Changelog reads as a timeline, newest first. Rows are grouped under a heading for each period, by Month or Quarter, and each heading shows how many Stories shipped in it and their mix of types. Click a heading to fold its rows away. A Story sits under the period it reached Done in.

Consolidating old Stories

Over time a feature leaves a trail of Stories: the one that introduced it, then its fixes and follow-ups. Consolidating folds a group of shipped Stories into one, with a written summary in place of their descriptions, so the timeline shows the feature rather than every step toward it.

A consolidated Story's row shows the span of dates it covers, its summary, and how many Stories it stands for. Click that count to list the ids it absorbed; each of them still opens the consolidated Story. It sits under the period its span ends in, and it counts as one shipped Story, so consolidating lowers the totals in the period headings and on the dashboard.

Consolidating discards for good. Unlike a merge, which keeps everything, a consolidation throws away the absorbed Stories' descriptions and, if asked, their Tasks. There is no undo and no copy. Move anything still worth keeping into your project's own documentation first.

Through MCP: consolidating is an agent's job, since it takes reading the old Stories and writing the summary. The agent lists what shipped long ago with view_changelog, shows you what it proposes to fold together and exactly what would be lost, and, once you approve, calls merge_stories with a summary. Only Stories already in the Changelog can be consolidated. See the Story tools.