Card format

A card is Markdown with YAML front matter. mdBoard uses three kinds: idea, batch and task. The parser rejects unknown fields.

This reference describes the 1.0 alpha format.

Minimal idea

---
id: "#0007"
kind: idea
state: spark
title: "CSV export for the report table"
created_by: owner
intent_owner: owner
created_at: 2026-10-24T09:00:00Z
updated_at: 2026-10-24T09:00:00Z
---

## Intent

Add owner-only CSV export for the current report filters.

Batch example

---
id: "#0007"
kind: batch
state: roadmap
title: "CSV export for the report table"
created_by: owner
intent_owner: owner
estimate:
  tokens:
    optimistic: 8000.0
    realistic: 12000.0
    pessimistic: 20000.0
    weighted: 12667.0
  agent_hours:
    optimistic: 0.5
    realistic: 1.0
    pessimistic: 1.5
    weighted: 1.0
created_at: 2026-10-24T09:00:00Z
updated_at: 2026-10-24T10:00:00Z
---

## Intent

Owner-only CSV export for the current report filters.

Task example

---
id: "#0007-01"
kind: task
state: pending
title: "Streamed export endpoint"
created_by: agent
intent_owner: owner
parent: "#0007"
depends_on: []
source_review: null
created_at: 2026-10-24T10:30:00Z
updated_at: 2026-10-24T10:30:00Z
---

Field reference

Field	Type	Notes
`id`	string	`#0007` for idea/batch; `#0007-01` for task
`kind`	enum	`idea`, `batch`, `task`
`state`	enum	Must be valid for the kind
`title`	string	Required
`body`	Markdown	The text after the front matter
`created_by`	actor	Who created the card
`intent_owner`	actor	Human accountable for the intent
`parent`	card id?	Required for tasks; forbidden for idea/batch
`depends_on`	card ids	Task dependencies only
`source_review`	review id?	Set on rework tasks
`estimate`	object?	Batch estimate; required before roadmap
`report`	path?	Set on a completed batch only
`blocked_from`	state?	Set on a blocked batch
`blocked_reason`	string?	Set on a blocked batch
`created_at` / `updated_at`	timestamp	RFC 3339

States by kind

Kind	States
Idea	`spark`, `refine`, `pitch`, `rejected`, `canceled`
Batch	`accepted`, `roadmap`, `breakdown`, `doing`, `handover`, `completed`, `blocked`, `canceled`
Task	`pending`, `working`, `done`, `error`, `canceled`

canceled is shared. blocked is batch-only. error is task-only.

Estimate

The estimate contains two PERT objects:

estimate:
  tokens:
    optimistic: 8000.0
    realistic: 12000.0
    pessimistic: 20000.0
    weighted: 12667.0
  agent_hours:
    optimistic: 0.5
    realistic: 1.0
    pessimistic: 1.5
    weighted: 1.0

weighted = (optimistic + 4 × realistic + pessimistic) / 6. The batch estimate is authoritative for cost; task estimates are optional.

Review artifact

Review artifacts are not cards. They live under the batch’s review records:

id: RV-0007-01-01
batch: "#0007"
round: 1
reviewer: reviewer
authored_by: reviewer
transcribed_by: agent
verdict: changes-required
findings:
  - id: F1
    text: "The stream closes before the final row."
created_at: 2026-10-24T15:00:00Z

authored_by is the human whose verdict it is.
transcribed_by is set when the agent writes a chat review.
Findings that require code changes become rework tasks with source_review set to this artifact.

Event record

Every action produces one event file under .mdboard/events/:

id: E-20261024T141500-0007-work
at: 2026-10-24T14:15:00Z
action: work
card: "#0007-01"
from: pending
to: working
actor: agent
executor: agent
authorised_by: null
authorization: null
reason: null
commit: null

Events are append-only. They are evidence, not the current card state.

Meeting record

id: M-0007-01
kind: breakdown-clarification
status: pending
trigger: "Two questions about the streaming boundary"
linked_cards: ["#0007"]
questions:
  - id: Q1
    text: "Include headers when the result is empty?"
    resolved: false
created_at: 2026-10-24T10:45:00Z
updated_at: 2026-10-24T10:45:00Z

Upstream record

.mdboard/upstream.md:

iteration: 7
status: open
base: 1a2b3c4
writer: agent
lease_expires: 2026-10-24T18:00:00Z
started_at: 2026-10-24T09:00:00Z
merged_at: null