mdBoard
Menu
GuideDocsOfferingsWhy mdBoardGitHubGet a licence

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

Next