Work with the planning board

The planning board is a set of Markdown documents in the repository. Stories live in docs/stories/; epics, decisions, designs, and glossary terms use sibling directories. Git history is part of the record: it is how autodev derives planning lifetimes.

Read an existing board

All read commands accept --root when you are not running from the repository root, and --output json for automation.

autodev board check --root /path/to/repository
autodev board list --root /path/to/repository
autodev board list --status ready --output json
autodev board get APP-42

board check validates source files, status vocabulary, dispatchable story contracts, and referential integrity. It exits 1 for blocking findings. Backlog ambiguity and some historical or migration debt may be reported without blocking; read the report rather than treating every count as a failure.

Create a dispatchable story

board create requires a title plus either an explicit --id or an allocating --prefix. A new story starts in backlog.

autodev board create \
  --id APP-42 \
  --title "Bound uploaded file size" \
  --kind feature \
  --complexity medium \
  --goal "Uploads over the configured limit are refused before storage." \
  --criterion "An upload over the limit receives a size-limit error." \
  --criterion "An upload at the limit succeeds." \
  --area src/uploads \
  --depends-on APP-39 \
  --priority 70

Repeat --criterion, --area, --depends-on, and --term as needed. Valid kinds are feature, bugfix, chore, and spike; complexity is low, medium, or high.

--impact is the separate, optional half of that judgement: low, medium, high, or critical. Complexity says what the work costs and routes it to a model; impact says what landing it is worth, and the two are independent. Impact is not yet wired into scheduling, and an unstated impact means nobody has assessed it — which is deliberately not the same as an impact assessed as low.

If goal or criteria are omitted, the command writes explicit clarification markers. That makes drafting possible, but the result cannot pass the ready gate until the contract is completed.

Use --epic <id> or --design <id-or-path> only when the referenced entity exists, or board check will report the dangling reference.

Explain and perform transitions

Ask for live gate verdicts before changing status:

autodev board explain APP-42
autodev board explain APP-42 --to ready --output json
autodev board transition APP-42 ready

The transition command evaluates check gates itself. Evidence and judge gates cannot be manufactured by this command, and neither can a human gate — a human gate is satisfied by recording the decision separately:

autodev board approve APP-42 \
  --gate release-sign-off \
  --note "Reviewed with the on-call owner"

That writes an approvals entry into the story's frontmatter carrying the gate, the actor, and the note. The approval is durable, and it is spent by the transition that crosses the edge carrying that gate — one approval crosses one edge. Re-approving the same gate replaces the standing entry; the superseded one stays in git history. board explain names the exact board approve command an unmet human gate is waiting for.

An approval binds to a declared gate by name, and only to a human one: naming a check, evidence, or judge gate is refused, because proof cannot be manufactured by a signature. No built-in workflow declares a human gate, so this applies to repositories that configure one in .autodev/workflows.toml.

If an operator deliberately waives a gate instead, both the gate ID and reason must be recorded:

autodev board transition APP-42 ready \
  --waive criteria-lint \
  --reason "Imported contract; cleanup tracked separately"

Waivers are exceptional records, not a way to make an ambiguous story safe. Prefer correcting the contract.

Update story metadata

The supported update surface is intentionally narrower than creation:

autodev board update APP-42 \
  --priority 90 \
  --complexity high \
  --note "Escalated after a production incident"

You can update title, complexity, impact, priority, epic, design, note, and declared terms. Repeated --term values replace the existing term list. The command does not expose goal, criteria, area, dependency, kind, or status edits; edit the Markdown contract carefully or use the appropriate transition command, then run board check.

All board mutations commit by default. --no-commit leaves the mutation in the working tree.

Organize work with epics

Create an epic and associate stories with it:

autodev board epic create upload-safety \
  --title "Upload safety" \
  --problem "Unbounded uploads can exhaust storage." \
  --scope "Request validation and storage admission" \
  --non-goal "Changing storage vendors"

autodev board update APP-42 --epic upload-safety
autodev board epic show upload-safety
autodev board epic list

The epic's child story list is derived from stories that name the epic; it is not a second list to maintain.

Record decisions and language

Decision records have an explicit lifecycle:

autodev board decision propose \
  --title "Reject before buffering" \
  --context "Buffering consumes storage before policy runs." \
  --decision "Enforce the limit while streaming the request." \
  --consequence "Clients receive an early refusal."

autodev board decision list
autodev board decision accept 0001

Accepted decisions can later be superseded with decision supersede <id> --by <new-id>; proposed decisions can be rejected. Use decision show <id> to inspect one.

The glossary makes domain terms queryable:

autodev board glossary define upload-limit \
  --definition "The maximum accepted request body size." \
  --alias max-upload-size \
  --area src/uploads

autodev board glossary show upload-limit
autodev board glossary where upload-limit
autodev board glossary unused

Repair legacy frontmatter

Run the doctor in report-only mode first:

autodev board doctor
autodev board doctor --fix

--fix repairs supported legacy frontmatter in one commit and preserves Markdown bodies byte-for-byte. Before using it, back up and inspect multiline frontmatter notes: a current edge case can rewrite a line ending in : null. Review the repair commit like any migration; see Current limitations.

See the CLI reference for the complete command inventory.