Tasks and markers

Tasks track the work; markers track the open questions.

The tasks document is indexed line by line. A task line has a checkbox, an ID such as T13, an optional [P] flag for tasks that can run in parallel, the requirements it covers in parentheses, a description and a Done when check. The phase is the ## heading above the line.

tasks.md
## Phase 2: Refunds - [ ] T13 [P] (FR-18) Migrate the refunds table — Done when: the migration test passes on a copy of production - [x] T12 (FR-17, FR-19) Add the refund endpoint — Done when: the endpoint test passes · commit: 4f2a9c1

Write (FR: —) when a task covers no requirement. Lines that look like tasks but do not follow this form are reported apart as malformed. list_tasks returns the parsed tasks with the active claim of each pending one, and pending_only hides the finished ones.

Claiming and finishing

An agent calls claim_task before it starts, so no other agent takes the same task. The claim is a lease (ten minutes by default) that every request of the agent to the project extends, and it ends with release_task, when the task is marked done or when the lease runs out. A task held by someone else is refused with claimed, naming the holder.

mark_task_done ticks the task and adds · commit: with the 7 to 40 lowercase hexadecimal characters of the commit that completed it, as a new revision.

Markers

Open questions are written inline as [NEEDS CLARIFICATION: …] or [NEEDS RESEARCH: …].

spec.md
[NEEDS CLARIFICATION: should refunds above 500 EUR need a second approval?]

list_markers lists them across the documents of a spec, and the app shows them in the spec's Markers tab, so none is forgotten. A spec cannot be approved while it has open markers: the approval is refused over MCP, the API and the app alike, with the number of markers to answer first.