Run a playbook from plan to commit

A playbook is a sequence of workers and code steps that the fleet runs for you. The builtin sdlc playbook plans, builds, tests with a bounded fix loop, reviews with a bounded revise loop, and documents, with three commits along the way. This guide runs it on one task and reads what it committed on your branch.

1. 01

   See what is available

   Shell

   clio-coder playbook list

   sdlc shows as setup until the project declares the two commands it runs, test and commit.

2. 02

   Declare the commands it runs

   Shell

   clio-coder playbook commands init

   This drafts .clio-coder/playbooks/commands.yaml from your project's declarations, fully commented out, because uncommenting an entry confirms its exact command. Edit it to name what this project runs:

   .clio-coder/playbooks/commands.yaml

   version: 1
   commands:
     test:
       argv: ["npm", "run", "test"]
     commit:
       argv: ["git", "commit", "-m", "{{commitMessage}}"]

3. 03

   Check before you run

   Shell

   clio-coder playbook validate sdlc --var task="Add empty-input handling to the parser"
   clio-coder playbook graph sdlc --var task="Add empty-input handling to the parser"

   validate runs the execution preflight and graph prints the compiled waves, loops, scopes, and write boundaries, both without side effects. It resolves agents, targets, and profiles, and checks the session budget and write boundaries. A failed preflight during a real run exits 2 before anything dispatches.

4. 04

   Run it

   Shell

   clio-coder fleet run sdlc --var task="Add empty-input handling to the parser"

   The first line, on stderr, names the fleet root and plan hash. Each settled step prints one line. In another terminal, clio-coder fleet status shows the board and clio-coder fleet events <root> --follow follows the journal.

   The steps work in your checkout, one after another, not in separate worktrees. The suite loop runs your test command inside the sandbox, rooted at the checkout, up to three times, and hands each of the first two failures back to the coder.

   The command exits 0 only when every required step succeeded, no step was skipped, and every loop resolved. Any other finished run exits 1. A failed preflight, or an error in the scheduler itself, exits 2.

5. 05

   Read what it committed

   Shell

   git log --oneline -3
   git show --stat HEAD~2 HEAD~1 HEAD

   The three commit steps commit the plan, the code, and the docs on the branch you have checked out, so there is nothing to merge or land afterwards. If you do not want the result, reset the branch to where it was before the run.

   clio-coder fleet land is for something else: the task branch a worker dispatched with its own worktree keeps when its change was not merged.

Make it yours

clio-coder playbook new parser-fix --from sdlc

This copies the builtin to .clio-coder/playbooks/parser-fix.md, where you can change steps, agents, and limits. A resumed run replays a completed prefix of the same plan: clio-coder fleet run <name> --resume <runId>.