The cycle

The cycle is rafa's default workflow, the one every other builds on: set up, write a spec, make a plan, run it, land it. You type each step yourself, and most commands end by naming the next one; rafa next runs the same steps for you, one question at a time.

The cycle, from spec to release, in its default order.−100%+FitClose

The subject actions it runs, in order:

1. rafa init and rafa doctor, once per project.
2. A spec: a file under .rafa/specs/, or an issue marked ready with rafa issue ready.
3. rafa plan create, then rafa plan show to read it.
4. rafa loop start.
5. rafa pr merge, after rafa pr current or rafa pr triage when it is red.
6. rafa release settle, when the project releases (The release flow).

Your first project covers set-up, the spec and the plan. The rest of this page runs the plan and lands it. The commands below start Claude Code sessions and need a GitHub repository with gh signed in (Prerequisites), so their output is not shown here.

Run the plan

rafa loop start --plan=.rafa/plans/PLAN-my-feature.md

On main, the loop offers to create the branch feat/my-feature from the latest base and run there; naming.branch in Configuration changes the name. Then, for each task, it starts one Claude Code session, stores the task's report and makes one commit. The tests run around each task and stage are the ones the checks section names; in 0.47.0 it names none by default, so set it, or adopt templates: [escalation], before a first real run (Configuration).

A task that reports blocked stops the run with the reason. Fix what it names and start again with the same line: the blocked task goes first.

After the last task, a wrap-up session syncs with the base branch. The loop then writes the release fragment (see The release flow), pushes, opens the pull request and waits for CI, spending repair sessions while CI is red.

Inside rafa loop start, in its default order.−100%+FitClose

From another terminal you can follow and steer it:

rafa loop status   # the running loop, its task and its phase
rafa loop pause    # stop after the running task
rafa loop stop     # stop now

Keep working while it runs

A loop guards its checkout. Every turn it watches the branch and the commit it is on, and it halts if either changes from outside, for example a git checkout main in another terminal. The work stays committed and nothing is lost.

The guard exists because of a real run on 2026-09-29: a loop had switched the main checkout to its branch, and 48 seconds later a git checkout main and git pull in another terminal moved it back, and the loop's edits followed. With the guard, the loop halts instead.

To keep using your checkout while a loop runs, start the loop in its own git worktree, a second working folder on the same repository with its own branch:

rafa loop start --plan=.rafa/plans/PLAN-my-feature.md --as-worktree

You stay on main and can pull, review or merge other pull requests while the loop runs beside you. The worktree is created under .rafa/worktrees/ (or where loop.worktreeDir says), and the same line started again reuses it. Two plans can run as two loops in two worktrees on one machine, sharing one .rafa/ folder.

Land it

rafa pr current        # number, title, checks, URL
rafa pr triage         # why is it red, and is the fix simple
rafa pr merge          # asks y/N, merges, switches to the base, pulls, deletes branches
rafa release settle    # folds the waiting release fragments into a version and pushes it

rafa pr triage spends nothing; rafa pr triage --resolve runs a small fixed plan through the loop to fix it. A repository with no CI merges with rafa pr merge --skip-checks.

While a loop of the project is running, rafa pr merge does not offer rafa self-update: the running loop starts its sessions from the installed rafa, and swapping it mid-run would change the engine while it drives. Update after the loop stops.

Then again

Write the next spec and plan it, or let rafa next take you through merge, settle, plan and start, one step at a time. It asks before each step, and it spends whatever that step spends.

To see what the run cost:

rafa effort collect
rafa effort report

collect reads the Claude Code session logs and git commits into the project's effort store, and report shows per plan its sessions, tasks and costs.