Runs and the project kit

How the project kit sets up a plan, and how a bounded run claims tasks, records decisions and stops at its budgets.

The project kit is a plan in your repository (.overlane/plan/), plus instruction blocks and CI, that lets an agent work through tasks unattended. A run is one bounded pass: it checks the run policy, claims a task, and ends with a record.

Set up the kit

overlane connect --kit existing --dry-run
overlane connect --kit new --goal "Build a link shortener" --yes

With --kit existing|new, overlane connect also drafts the plan files, CI and a pull request. --goal is required with --kit new. Preview first; nothing is written under --dry-run.

The agent loop

overlane run next
# do the work the task describes, then commit it
overlane run next

run next is one step of the loop, the same for Claude Code, Codex or a scheduled cloud run:

It starts a run when this working copy has none.
If this working copy holds a task, it runs each of the task’s verification commands on the committed work. A failure stops here and the task stays yours: fix it, commit, run run next again.
When every command passes, it submits the task, records each result as evidence, pushes the branch (overlane/<task> when you are on the default branch) and opens the pull request through the project’s GitHub App. The task closes only when that evidence verifies it; a check that needs CI keeps it open until CI passes.
It claims the next runnable task in one step and prints its contract and verification commands.

Two agents running run next at the same moment never get the same task, and a task whose dependencies are not verified is never handed out: claiming it by name is refused too. When nothing is left, or a budget is spent, it exits 6 with the run end command to finish with.

A run, step by step

overlane run start --trigger schedule
overlane run claim
overlane run decide --question "Which test runner?" --decision "Vitest" --evidence "package.json"
overlane run end --reason nothing_runnable

run start checks the run policy and starts one run, recorded in .overlane/state/run.json. A stop (policy paused, a budget spent, nothing runnable) exits 6, with the reason in the error code and the exact run end command as the hint.
run claim claims the next runnable task, or a named one, and prints its contract and verification commands.
run decide records a question, the decision taken and its evidence, so the run continues without waiting for an answer.
run end ends the run and releases its leases. Run it even when stopping early.

Look and control

overlane run status
overlane run pause
overlane run resume

run status reports the policy, this working copy’s budgets and the next runnable task. run pause stops every run at its next check, and run resume undoes it. Loops that start runs on a schedule or an event are in Loops.