Best practices
Every rule names the failure it prevents. A rule with no consequence attached is an opinion, and you can ignore those.
Writing a card
One card, one outcome you can check. Prevents the worker declaring success on the easy half. Delegation works on tasks that are easy to verify; ambiguity is where people pull work back.
Put the acceptance test in the body. Prevents a summary that says done and gives you nothing to check it against.
Always name the assignee. A card with no assignee, or one naming a profile that does not exist, sits in Todo silently. This is the most common beginner failure on this board.
Write the boundary into the card. Prevents scope drift. Say which files, which directory, which service, and say what is out of bounds.
Summarise, do not paste. A pasted transcript is context you pay for on every step. The handoff is a summary for a reason.
Wiring work together
Express order with --parents, never in prose. A sentence saying do this after the other one is invisible to the dispatcher. A parent link is enforced.
Let the engine promote cards. Moving a card out of Todo by hand can start it before its parent is done.
Keep fan-out narrow. auto_decompose_per_tick is 3. The cap exists because one vague card can otherwise fill a board with work nobody asked for.
One board per project. Cross-project cards on one board make the run history unreadable exactly when you need it.
Running the board
Read the runs, not the card. The card shows where work is. The run shows what happened, including the error text of every attempt.
Do not raise --max-retries to paper over an error. Two spawn_failed rows with the same message are an environment fault. Retrying a missing key three times gives you three identical failures.
Subscribe to endings only. completed, gave_up, timed_out. Everything else is a stream you will mute.
Archive finished work. Done is a record. Archived keeps the record and gives you back the screen.
Watch what it costs. Every card is a real model call in a real process. A board is a spending decision as much as a scheduling one.
Knowing when to stop
Try one agent first. Add a second only when the first cannot do the job. Coordination is not free and often buys very little accuracy.
Delegate what you can verify. Developers report using AI across most of their work while fully handing over only a small slice of it. Verifiability is the line, not ambition.
Keep a human on anything irreversible. Deploys, deletions, payments, anything that sends mail. Route them through Review by default.
Delete cards that stopped mattering. A board full of stale intentions stops being something you trust, and an untrusted board gets ignored.
Screen 5 of 7.