Cards, batches and tasks

A card is the unit of intent and work. It is a Markdown fact in Git, but you usually do not edit it directly: your agent creates and moves it for you.

Three kinds

Kind	What it represents	Typical states
Idea	A spark, refinement or pitch	spark, refine, pitch, rejected, canceled
Batch	An accepted idea in delivery	accepted, roadmap, breakdown, doing, handover, completed, blocked, canceled
Task	One implementation unit under a batch	pending, working, done, error, canceled

A batch is the unit you review. A task is the unit the agent implements.

From spark to batch

spark → refine → pitch → accepted → roadmap

spark — a rough intention. One sentence is enough.
refine — you and the agent shape it. The agent may edit content only here.
pitch — the frozen proposal for the consortium.
accepted — the consortium approved it; the card becomes a batch.
roadmap — the batch is committed and estimated.

The agent may create a spark on your instruction. It may not accept or reject the idea; that is a human decision.

From roadmap to completion

roadmap → breakdown → doing → handover → completed

breakdown — the agent decomposes the batch into tasks and asks clarifying questions.
doing — the human has authorised implementation; the agent works the tasks one at a time.
handover — all tasks are done; the batch is waiting for human review.
completed — an owner accepted the review; the report and changelog are written.

If the review finds issues, the batch returns to doing with a rework task. If work is blocked externally, the batch goes to blocked; if the agent fails a task, the task goes to error.

The task queue

Tasks are created during breakdown. They are an ordered, dependency-aware sequence:

#0007-01 streamed export endpoint
#0007-02 permission and filter tests
#0007-03 API and operator docs

The agent works them in order, subject to dependencies. Only one task is working at a time. Each done task has a commit.

Relations

A card is more than its text:

Relation	Meaning
`parent`	The batch a task belongs to.
`depends_on`	Tasks that must be done before this task.
`source_review`	The review artifact that created a rework task.
`report`	The completed batch’s report.

The relation is what makes traceability work: the report links back to the batch, its tasks, the reviews and the commits.

IDs

IDs are stable:

an idea or batch: #0007;
a task: #0007-01;
a review artifact: RV-0007-01-01.

The ID never changes when the card changes kind (idea → batch).

Estimates

A batch carries:

tokens — expected token volume;
agent_hours — expected agent execution time.

The estimate is required before the batch enters the roadmap. The roadmap total is the sum of batch estimates. See Estimation and cost.

Review artifacts are not cards

A review artifact is the human verdict on a batch round. It contains:

the reviewer and author;
the provenance (transcribed_by when the agent writes it down);
the verdict;
findings with stable ids.

Findings that require code changes become rework tasks. Do not create a card per finding.

What you actually say

You do not need to know the schema. You say:

Human: Spark an idea for CSV export.
Human: Refine it and ask me the open questions.
Human: Pitch it.
Human: The consortium accepts it; put it on the roadmap.
Human: Break it down and ask me everything before starting.
Human: Start the batch.
Human: I accept the review; complete it.

The agent translates those into the right card kinds and states. The full field reference is in Card format.