The pattern gallery

The six pattern files under config/patterns/, what each does, and where a fork changes it. A fork is a copied file: dropping a patterns/<name>.toml on a higher tier is the whole registration, and it shadows the same-named bundled pattern.

How a pattern is selected (see docs/agents/drivers.md): build carries default = true in its header and is what a flagless gantry <plan> runs; a pattern with a [[header.cli_flags]] table is bound to a flag (--map <source>, --until <goal.md>); everything else, including forks, is reached by --pattern <name|file.toml>, whose entry parameters bind positionally or with --param <name> <value>.

The build family — build.toml, milestone.toml, sprint.toml

One pipeline composed from three files via include: build.toml includes milestone.toml, which includes sprint.toml, so all three share one definition namespace. All three declare an entry, but only build declares a declared_plan_source parameter, so it is the only one a plan argument can select (src/engine/run/pattern.rs:1825); milestone and sprint are included, never run on their own.

build.toml

For: the default milestone build — what a flagless gantry <plan> runs, and what until calls to build one cycle's gap plan.

Structure: the entry pattern build runs plan_milestones (an agent step on the write-milestones prompt) which writes the milestones/ directory and a one-word plan_scope output; write_about writes about.md, with a failed session routed to nothing so it cannot stop the run; an if on plan_scope routes work to prepare_project_gate and none to stop_no_milestones. prepare_project_gate runs author_project_gate (prompt write-project-gate, read_only), whose run-scoped project_gate output is bin/gate, then project_baseline proves it green before any milestone runs. build_milestones runs the milestones for over the milestones output, calling build_milestone once per brief; build_milestone calls milestone, then runs milestone_boundary_gate on project_gate. A red milestone_boundary_gate calls troubleshoot once, then repaired_milestone_boundary_gate decides whether the run continues or stops. The directory is re-read before every iteration, so briefs written mid-run are built too, and done-ness comes from the ledger, so a finished milestone is not rebuilt. After the for, project_final_gate runs the run-scoped gate again. A red project_final_gate also calls troubleshoot once before repaired_project_final_gate decides whether the run continues or stops. The authored stops are a plan with no work, an absent plan_scope, and the run-scoped gate red on the baseline, after one milestone repair, or after the final repair.

To fork: the planner, at prompt = "write-milestones" on plan_milestones; the run-scoped gate author, at prompt = "write-project-gate" on author_project_gate; what a milestone failure means, by adding fail = "continue" to the for (it is left at its default, stop); the for body, at body = "build_milestone"; and the stop hook, at on_stop = "write_handover" in the header.

milestone.toml

For: one milestone — briefed, planned into task briefs, gated, built, and reviewed. Called by build's for body build_milestone, once per brief.

Structure: brief_environment (prompt write-environment, failure routed to nothing), then plan_sprints (prompt write-sprints) writes the sprints/ task directory, then author_gate (prompt write-milestone-gate, read_only) writes the invocation-scoped gate_script, then the baseline gate proves the fresh milestone gate green on the clean tree — red routes to stop_baseline_red. The run_sprints for over that directory calls sprint per brief, passing the three prompt ids, gate_script as declared_gate_command, protected_check and attempt_ceiling. milestone_review then judges the built milestone with diff = "iteration-start" — the enclosing iteration is build's for, so the reviewer sees the whole milestone as one change — and its milestone_verdict routes complete to verify_milestone_review_edits (a gate on the reviewer's own edits, with one troubleshoot call and repaired_milestone_review_gate on red) and blocked to stop_milestone_blocked.

To fork: the three prompt-id parameters (execute_prompt, review_prompt, troubleshoot_prompt) have defaults on their declarations and a caller can override each with one line; the EXTRA_JUDGMENT text on milestone_review is prose a fork rewrites in place; and a caller that wants no baseline declares its own milestone-level pattern without the baseline step and its if, which is what the file's own comment prescribes.

sprint.toml

For: one gated task — executed, gated, recovered, reviewed, and committed. Called by milestone's for; includes troubleshoot.toml for red-gate repair, plan-change review, and the write_handover stop hook.

Structure: execute's declared executor_blocked output routes through examine_executor_blocked, which calls troubleshoot for a handover before the final stop. Then the build_gate gate runs: red routes to recover_build, green to review_and_commit. recover_build is one call of troubleshoot followed by recovery_gate; a still-red gate routes to route_troubleshoot_verdict, where the troubleshoot pass's declared troubleshoot_verdict maps retry through check_attempt_ceiling to either retry_sprint or stop_attempt_ceiling, and handover maps to stop_handover. retry_sprint is a tail self-call of sprint with restore = "iteration-start", the format's task retry recursion. review_and_commit runs review with diff = "iteration-start"; its review_verdict maps complete to verify_review_edits, retry to the same check_attempt_ceiling, blocked to examine_review_blocked, again calling troubleshoot before the stop. verify_review_edits gates the reviewer's own edits; red goes through repair_review, whose troubleshoot pass may declare troubleshoot_revert = "revert" — then revert_review_edits re-gates with restore = { before = "review" } — or fix forward through regate_after_review_repair. A restored boundary that is still red routes through examine_restored_red, which calls troubleshoot before stopping; a rejected plan change routes through the shared examine_plan_change_rejected, which declares its own troubleshooter and no on_plan_change, so the handler cannot recurse. Green falls off the end of the whole tail-call chain and the enclosing for records the task done; no commit step is declared, because every session's work is already committed at its own boundary. sprint declares attempt_ceiling with the default unbounded; the build entry passes 2.

troubleshoot.toml

For: shared troubleshoot infrastructure. Included by build, milestone, sprint, and map, and runnable by name for one troubleshoot pass.

Structure: troubleshoot is one troubleshoot-stage agent step using troubleshoot_prompt, declared_gate_command, protected_check, and a position briefing. It declares troubleshoot_verdict, troubleshoot_revert, troubleshoot_note, and handover_document. review_plan_change runs review-plan-change; accepted routes to nothing, rejected routes through examine_plan_change_rejected, which writes plan_change_rejected_handover_document before stop_plan_change_rejected. write_handover is the shared on_stop hook and writes engine_stop_handover_document.

To fork: the default troubleshoot_prompt, position, declared_gate_command, and protected_check parameters on troubleshoot; the literal troubleshoot prompt on examine_plan_change_rejected; and the stop hook at write_handover.

map.toml

For: a roster of independent tasks, each built and gated on its own; bound to --map <source> via [[header.cli_flags]]. Two consecutive failed tasks stop the run.

Structure: write_roster (prompt write-map-roster) writes state/roster/, an ordered directory of task files each carrying TOML front matter with a gate = command and a prose body that becomes the worker prompt. check_roster is a command step that writes roster_check and a roster_complaint; no routes through rewrite_roster into map_with_complaint, whose rewrite agent reads the complaint and whose own failed check tail-calls map_with_complaint again. run_roster is a for — the step named run_tasks — with fail = "continue" over the roster; it runs map_task per file: build_task on {{task.prompt}}, the task_gate gate on {{task.gate}}, one repair agent on red, repaired_gate, then record_done or record_failed — command steps writing verdict files under run/verdicts/. A rejected plan-file edit routes through the shared examine_plan_change_rejected handover before stopping. check_streak counts .failed among the last two verdict files by name and routes stop to stop_streak. map declares no run-scoped gate; each task's own gate judges that task.

To fork: the streak threshold — the tail -n 2 / -ge 2 pair in check_streak; the repair depth, by adding or removing repair/gate step pairs in repair_task; the roster checks, by editing the check_roster shell and the check_rewritten_roster copy of it; or fail = "continue" on run_tasks, whose removal makes any failed task stop the map at the for itself.

until.toml

For: work until an acceptance check goes green; bound to --until <goal.md> via [[header.cli_flags]]. It includes build.toml, so each cycle's plan is built by the full build family.

Structure: probe_check (a command step) tests whether the check script — bin/goal-check by default, a path parameter — is executable; absent routes to author_check, a read_only agent on the write-goal-check prompt. run_check runs the check, capturing gap_report; a failed outcome routes to decide_cycle, and success falls off the end. decide_cycle is a command step and an if on its cycle_decision output: with the default max_cycles = "unbounded" it writes continue, while --param max_cycles <n> stops through stop_cycle_ceiling once <n> build cycles have completed and the check is still red. close_the_gap runs plan_the_gap (prompt write-gap-plan, with the check path in protected so no agent can rewrite the acceptance check) whose gap_plan_scope maps work to run_cycle and none to stop_no_gap_left. run_cycle calls build with plan_source = "{{gap_plan}}" and protected_check = "{{check}}" in build_the_plan, then tail-calls until_loop in next_cycle, passing until_source, check, max_cycles, and next_completed_cycles as completed_cycles.

To fork: the check parameter's default = "bin/goal-check"; the check author's prompt write-goal-check and the gap planner's write-gap-plan; or the pattern = "build" line in run_cycle.