Your first conversation

::: tip What you will do Install mdBoard, connect one agent, and take a single idea from a spark to an accepted roadmap batch. You will talk to the agent; the agent will use mdBoard. :::

This is a collaboration quickstart, not a CLI tutorial. You need Git, mdBoard on PATH, and a coding agent that can run commands in your repository.

1. Install mdBoard

Use a release binary, Docker, or build from source. The short version:

# one option: build from a checkout
cargo install --path crates/mdboard-cli --locked --root "$HOME/.local"
export PATH="$HOME/.local/bin:$PATH"
mdboard --version

Full options are in Install and connect.

2. Create the board

From the root of an existing Git repository:

mdboard init

init asks for:

the upstream branch that holds the working truth;
the subscription or payment model and the blended EUR cost per 1 million tokens used for estimates.

The roadmap limit is --roadmap-limit (default 5).

Let the agent look up your costs

The default cost model is a planning placeholder. After initialization, ask the agent to research the concrete model and subscription:

Human: Look up the current DeepSeek-V4.1-Flash pricing for our off-peak usage
       and adapt the cost estimates.
Agent: I checked the provider pricing on 2026-10-25. For this subscription
          the blended rate is €0.21 per 1M tokens at our 80/20 input/output mix.
          I will update [costs] and refresh the roadmap if you approve.

The agent states its source, date and assumptions, and updates [costs] only with owner approval. See Estimation and cost.

It writes mdboard.toml, the board directories, the actor registry and a short AGENTS.md pointer. Commit the result so the starting point is clean.

::: details What the agent will see

AGENTS.md
BOARD.md
ROADMAP.md
mdboard.toml
.mdboard/
  actors.toml
  cards/
  events/
  meetings/
  reviews/
  reports/

AGENTS.md does not contain a long prompt. It points the agent at mdboard runbook, which is the stable, normative instruction set shipped with the binary. :::

3. Connect the agent

Open your coding agent in the repository and say:

Read AGENTS.md, then run `mdboard runbook` and `mdboard context`.
You are the agent for this repository. Follow the runbook.
Do not change state or merge without the authorisation it requires.
Introduce yourself and tell me what needs my attention.

The agent should reply with the current upstream iteration, the active batch if any, the roadmap count, pending meetings and the legal next actions. If it cannot run mdboard, stop and fix the installation first.

4. Start the upstream iteration

Human: Open the working iteration.

Agent: Iteration 1 is open from main. I hold the writer lease.
          The board is ready for a spark.

The agent runs mdboard upstream start. Card actions require an open iteration.

5. Spark an idea

You do not need a template. State the intention:

Human: I want CSV export for the report table. Keep it small:
       current filters, streamed response, owner-only for now.

Agent: I created #0007 as a spark with that intent.
          I have not refined it yet, because content edits belong in refine.
          Do you want to shape the acceptance criteria with me?

What happened: mdBoard created an idea card in spark. The agent is allowed to create it on your instruction, but not to silently invent scope.

6. Refine it

Human: Yes. Ask me about the open questions, then write the acceptance criteria.

Agent: Three questions:
          1. Should the export include hidden columns?
          2. What is the maximum row count before we stream?
          3. Is this available to members or only the owner?

Answer them. The agent updates the card only while it is in refine. When you are happy:

Human: That is the intent. Pitch it at the next consortium review.

The card moves to pitch. Its content is frozen for the consortium.

7. Accept it

At the consortium review, the humans decide. When the decision is made:

Human: The consortium accepts #0007. Put it on the roadmap and show me the estimate.

Agent: I recorded the accept decision and promoted #0007 to a batch.
          Estimate: 12,667 weighted tokens, 1.0 agent hour, about €0.06 at
          the current blended rate.
          Roadmap: 1 of 5 slots. Shall I commit it to the roadmap?

The agent records the human authorisation in the event journal. The batch moves accepted → roadmap.

8. Break it down and start

Human: Break it down. Ask me everything you need before starting.

Agent: I created three tasks:
          #0007-01 streamed export endpoint
          #0007-02 permission and filter tests
          #0007-03 API and operator docs
          One clarification meeting is pending: two questions about the
          streaming boundary. I will not start until you accept it.

After you resolve the questions and say start, the batch moves to doing. The agent works the tasks one at a time and commits each finished task.

9. Watch the board

You have three human views:

BOARD.md — the state overview and open work;
ROADMAP.md — committed batches, estimates and the roadmap total;
the HTML board — the review and consortium surface, launched with mdboard serve.

The HTML board reads the new records; sign in with mdboard serve --actor owner for review and meeting actions.

You do not need to run these commands; ask your agent for a brief. A good brief is:

Agent: #0007 is doing. #0007-01 and #0007-02 are done.
          #0007-03 is working. No blockers.
          One handover review will be ready after #0007-03.
          No pending meetings for you right now.

10. Review and complete

When the batch enters handover, the agent opens the handover review. You read the batch, the tasks, the tests and the report draft. You can:

accept and let the owner complete the batch;
request changes, which returns the batch to doing and creates rework tasks;
block it if an external decision is missing.

Completion writes .mdboard/reports/R0007.md and a dated bullet in CHANGELOG.md.

11. Merge — you, not the agent

Human: Prepare the merge. I will run it.

Agent: I committed the final report and changelog with
          `mdboard commit`. The worktree is clean, and the merge check
          passes. I prepared the summary.
          You can run `mdboard upstream merge` as owner.

Only a human owner executes the merge into nightly and the release into stable. The agent may prepare and verify, never merge.

What just happened

You expressed intent, refined it and made the human decisions.
The agent translated your intent into legal mdBoard actions.
mdBoard recorded the states, authorisations, review and evidence in Git.
You never had to learn the full CLI.

::: info Alpha This guide describes the 1.0 collaboration model. The named CLI actions, the runbook, the board records, the generated views, the HTML board and the branch merge/release gates are implemented. The process model is normative when prose and code disagree. :::