llm-kanban schema standard

Version 1 · adopted 2026-10-03. This is the canonical schema for the in-repo Markdown kanban ("llm-kanban") used by fleet projects. The working procedure is the llm-kanban runbook. Each project repo carries a kanban/AGENTS.md with the safety-critical rules embedded locally; this standard is the reference of record. If a local file and this standard disagree, agents stop and flag it to the project manager.

The story lifecycle at a glance (the prose below governs):

Layout

PROJECT_CHARTER.md
kanban/
  schema.yaml     machine config (statuses, types, claim defaults)
  schema.md       human summary
  AGENTS.md       local contract — sufficient on its own
  index.md        board home
  backlog.md      one-line intake captures
  board.md        generated — never hand-edited
  status.md       generated — sprint, blockers, stale claims
  agents.yaml     fleet registry copy (claim validation)
  kanban.py       the CLI
  stories/        one file per story, named by permanent ID
  sprints/        one file per sprint
  retros/         one file per retrospective

Story frontmatter

One story is one Markdown file; its path never changes with status. Frontmatter is the database:

Field	Rule
`schema_version`	Schema version that wrote the file (currently 1)
`id`	Permanent, project-prefixed (`WB-001`); never reused, even if the story is abandoned
`title`	Short outcome title
`type`	`epic` \| `story` \| `task` \| `bug` \| `spike`
`status`	`backlog` \| `ready` \| `in-progress` \| `in-review` \| `done`
`blocked`	Boolean overlay — blocked is not a status; the underlying status is preserved
`blocked_owner`	Who must act (`justin` or an agent ID); required when blocked
`blocked_since`	Date the blocker was recorded; required when blocked
`action_needed`	The exact input or decision required; required when blocked
`sprint`	Sprint ID (e.g. `2026-S01`) or null
`points`	Fibonacci only: 1, 2, 3, 5, 8, 13. Ready requires 8 or fewer — split anything bigger. Backlog stories may be unestimated; an estimate is required at ready
`priority`	`P0`–`P3`
`owner`	Accountable agent or person
`acceptance_owner`	Who accepts deliverable-facing work (usually `justin`)
`requires_acceptance`	When true, only the acceptance owner may move the story to done
`accepted_by`	Set by the acceptance owner at acceptance
`superseded_by`	Story ID that supersedes this one, recorded at a superseded close (`kanban.py move --to done --superseded-by <ID>`); null otherwise. A story closed this way needs no estimate, shows as superseded in the renders, and never counts toward velocity. On an acceptance-gated story the acceptance owner performs the close and `accepted_by` stamps the closer — the disposition of record is `superseded_by`, never the stamp
`epic`	Parent epic ID or null
`depends_on`	Story IDs that must be done before this story can be claimed
`created`, `updated`, `completed`	Dates (`completed` required when done)
`claimed_by`, `claim_id`, `claimed_at`, `heartbeat_at`, `lease_until`	The claim (the lock)
`claim_generation`	Fencing counter; increments on every claim and reclaim

Body sections, in order: the user story ("As a… I want… so that…"), Acceptance criteria (checklist), Implementation notes, Evidence, Activity (timestamped, attributed, append-only).

Claims and fencing

The lock is a commit of the story file alone, pushed immediately; the first successful push wins. A claim sets status to in-progress and fills all claim fields. Defaults in schema.yaml: claims and reclaims are born on a 1-hour first lease (first_lease_hours); the first heartbeat promotes the claim to the full 4-hour lease (lease_hours) and later heartbeats extend at the full lease; one active claim per agent. An expired claim may only be taken over through an explicit reclaim, which records the previous holder in the activity log and increments claim_generation — the generation is the fencing token: work presented under an older generation than the story's current generation is stale and must not be integrated.

Definitions

Ready: outcome stated, acceptance criteria written, points 8 or fewer, dependencies identified, not blocked.
Done: acceptance criteria met, evidence recorded, docs updated, deployment verified where applicable, and stakeholder acceptance when requires_acceptance is set. Velocity counts accepted points only.

Sprints and retros

A sprint file records goal, dates, capacity in points and stakeholder actions (the stakeholder is the bottleneck, not agent output), committed story IDs, scope changes, and at close: completed, accepted, and carried points, plus a link to the retrospective. A retrospective records what shipped, what the evidence shows, what slowed the work, and action items — each action item becomes a backlog capture or a story before the retro is filed.

Versioning

Schema changes increment schema_version, are proposed to the project manager, and land as an update to this standard plus a migration of the affected boards in the same change. Story files carry the version that wrote them; tooling must refuse unknown future versions rather than guess.

Published by Muse · 2026-10-03.

Layout​

Story frontmatter​

Claims and fencing​

Definitions​

Sprints and retros​

Versioning​