skip to content

The sprint pattern

One sprint task: execute the brief, gate it, recover a red, review the result, gate the reviewer's own edits, repair or revert them, and commit. Included by `milestone` and called once per sprint task.

sprint — one gated task, executed, reviewed, and committed

milestone's for over its sprints output calls this once per task file; it is not run on its own.

Retrying is recursion: a red gate's troubleshoot verdict and the reviewer's own retry both route to check_attempt_ceiling, which calls sprint one invocation deeper until attempt_ceiling is reached. A troubleshoot pass that cannot verify a repair and sees no point in a clean rerun declares handover, which stops the task with its document.

sprint 
[header]
pattern_language_compatibility = "3"
entry = "sprint"
include = ["troubleshoot.toml", "merge.toml"]
merge = "merge"
on_stop = "write_handover"
description = """
One sprint task: execute the brief, gate it, recover a red, review the result, gate the reviewer's own
edits, repair or revert them, and commit. Included by `milestone` and called once per sprint task.
"""

[patterns.sprint]

[[patterns.sprint.parameters]]
name = "execute_prompt"
kind = "prompt-id"
default = "execute"
description = "The executor's prompt; a pass that wants its own names it in full."

[[patterns.sprint.parameters]]
name = "review_prompt"
kind = "prompt-id"
default = "review"
description = "The reviewer's prompt; a pass that wants its own names it in full."

[[patterns.sprint.parameters]]
name = "troubleshoot_prompt"
kind = "prompt-id"
default = "troubleshoot"
description = "The troubleshoot pass's prompt, passed whole into the troubleshoot pattern."

[[patterns.sprint.parameters]]
name = "merge_attempt_ceiling"
kind = "text"
default = "2"
description = "The finish-time merge repair ceiling passed to the bundled merge pattern."

[[patterns.sprint.parameters]]
name = "declared_gate_command"
kind = "path"
description = "The gate command that judges this task."

[[patterns.sprint.parameters]]
name = "protected_check"
kind = "path"
default = ".gantry/no-protected-check"
description = "An optional record-path check an enclosing recursive goal run freezes."

[[patterns.sprint.parameters]]
name = "attempt_ceiling"
kind = "text"
default = "unbounded"
description = "The remaining attempts for this task; `unbounded` means no ceiling."

The pipeline

The gate judges the executor's work, so the step's only declared verdict is the one the gate cannot give: that the agent could not proceed at all.

sprint 
[[patterns.sprint.steps]]
name = "execute"
title = "Implementing"
type = "agent"
prompt = "{{execute_prompt}}"
judging_gate = "{{declared_gate_command}}"
protected = ["PROGRESS.md", ".preamble.sys.md", "bin", "{{protected_check}}"]
confine = true
on_plan_change = "review_plan_change"
outputs = [
  { name = "executor_blocked", path = "state/executor-blocked.txt", values = ["blocked"] },
  { name = "executor_note", path = "state/executor-note.md" },
]

A blocked executor routes to a troubleshoot pass that writes the handover, then to a stop; the arm never returns.

sprint 
[[patterns.sprint.steps]]
if = { executor_blocked = "blocked" }
then = "examine_executor_blocked"

milestone's author_gate wrote this command once, and its baseline step proved it green before the for began.

sprint 
[[patterns.sprint.steps]]
name = "build_gate"
title = "Testing"
type = "gate"
command = "{{declared_gate_command}}"

The last step of sprint: neither arm returns here, which is what makes every self-call below a tail call. A session that committed nothing ends ok all the same and proceeds to a review handed an empty diff.

sprint 
[[patterns.sprint.steps]]
if = { build_gate = "red" }
then = "recover_build"
else = "review_and_commit"

A red gate

One troubleshoot pass against the intact failed tree, then the gate decides again. Green rejoins the pipeline at the review; red asks the troubleshoot pass what it declared.

sprint 
[[patterns.recover_build.steps]]
name = "build_recovery"
type = "call"
pattern = "troubleshoot"

[patterns.recover_build.steps.parameters]
troubleshoot_prompt = "{{troubleshoot_prompt}}"
declared_gate_command = "{{declared_gate_command}}"
protected_check = "{{protected_check}}"
position = """
You are the first troubleshoot pass on a fresh red gate. Repair rather than diagnose at length: make
the smallest defensible verified repair you can. If you cannot verify a repair, declare `retry` when
a clean rerun briefed by your note is the right next move — Gantry starts the task over from a clean
tree. Declare `handover` only when another attempt has no point: it ends the task with your
document.
"""

[[patterns.recover_build.steps]]
name = "recovery_gate"
title = "Testing"
type = "gate"
command = "{{declared_gate_command}}"

[[patterns.recover_build.steps]]
if = { recovery_gate = "red" }
then = "route_troubleshoot_verdict"
else = "review_and_commit"

retry starts the task over from a clean tree; handover stops with the document the troubleshoot pass wrote. An absent verdict routes to the same retry: the troubleshoot prompt tells a pass that verified its own repair to write nothing further, so a troubleshoot pass whose gate run disagreed with this one arrives silent.

sprint 
[[patterns.route_troubleshoot_verdict.steps]]
if = "troubleshoot_verdict"
then = { retry = "check_attempt_ceiling", handover = "stop_handover" }
else = "check_attempt_ceiling"

The ceiling counts full task attempts: 2 permits the first failed attempt and one clean retry.

sprint 
[[patterns.check_attempt_ceiling.steps]]
name = "attempt_ceiling_check"
title = "Check Attempt Ceiling"
type = "command"
run = """
mkdir -p "$(dirname "$attempt_ceiling_decision")" "$(dirname "$next_attempt_ceiling")"
case "$attempt_ceiling" in
  unbounded)
    printf 'retry' > "$attempt_ceiling_decision"
    printf 'unbounded' > "$next_attempt_ceiling"
    ;;
  ''|*[!0-9]*)
    printf 'invalid' > "$attempt_ceiling_decision"
    printf '%s' "$attempt_ceiling" > "$next_attempt_ceiling"
    ;;
  0|1)
    printf 'ceiling' > "$attempt_ceiling_decision"
    printf '0' > "$next_attempt_ceiling"
    ;;
  *)
    printf 'retry' > "$attempt_ceiling_decision"
    printf '%s' "$((attempt_ceiling - 1))" > "$next_attempt_ceiling"
    ;;
esac
"""
outputs = [
  { name = "attempt_ceiling_decision", path = "state/attempt-ceiling-decision.txt", values = ["retry", "ceiling", "invalid"] },
  { name = "next_attempt_ceiling", path = "state/next-attempt-ceiling.txt" },
]

[[patterns.check_attempt_ceiling.steps]]
if = "attempt_ceiling_decision"
then = { retry = "retry_sprint", ceiling = "stop_attempt_ceiling", invalid = "stop_invalid_attempt_ceiling" }
else = "stop_attempt_ceiling_absent"

The only place the recursion depth grows; the restore discards the failed attempt whole.

sprint 
[[patterns.retry_sprint.steps]]
name = "retry_sprint"
type = "call"
pattern = "sprint"
restore = "iteration-start"

[patterns.retry_sprint.steps.parameters]
execute_prompt = "{{execute_prompt}}"
review_prompt = "{{review_prompt}}"
troubleshoot_prompt = "{{troubleshoot_prompt}}"
declared_gate_command = "{{declared_gate_command}}"
protected_check = "{{protected_check}}"
attempt_ceiling = "{{next_attempt_ceiling}}"

Review

The reviewer judges the task and may edit the tree. diff = "iteration-start" spans the enclosing iteration, so it sees the executor's work and every repair as one change.

sprint 
[[patterns.review_and_commit.steps]]
name = "review"
title = "Review Task Implementation"
type = "agent"
stage = "review"
summarize = true
prompt = "{{review_prompt}}"
diff = "iteration-start"
protected = ["PROGRESS.md", ".preamble.sys.md", "bin", "{{protected_check}}"]
confine = true
on_plan_change = "review_plan_change"
outputs = [
  { name = "review_verdict", path = "state/review-verdict.txt", values = ["complete", "retry", "blocked"] },
  { name = "review_note", path = "state/review-note.md" },
]

review.md states the task-level contract in full, so a task review adds nothing to it.

sprint 
[patterns.review_and_commit.steps.text]
REVIEW_SUBJECT = "task"
EXTRA_JUDGMENT = ""

The second retry site; it routes to the same check_attempt_ceiling as the red-gate site, so one ceiling covers both.

sprint 
[[patterns.review_and_commit.steps]]
if = "review_verdict"
then = { complete = "verify_review_edits", retry = "check_attempt_ceiling", blocked = "examine_review_blocked" }
else = "stop_review_verdict_absent"

The tree was green before the reviewer touched it, so this gate asks only about the review's own edits. Green falls off the end of the pattern and 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 
[[patterns.verify_review_edits.steps]]
name = "review_gate"
title = "Testing"
type = "gate"
command = "{{declared_gate_command}}"

[[patterns.verify_review_edits.steps]]
if = { review_gate = "red" }
then = "repair_review"

A gate the review broke

The same troubleshoot pattern, briefed differently: a genuine finding is fixed forward, cosmetic breakage is reverted. A troubleshoot pass that declares revert stops rather than half-fixing, so the revert happens before any re-gate.

sprint 
[[patterns.repair_review.steps]]
name = "review_recovery"
type = "call"
pattern = "troubleshoot"

[patterns.repair_review.steps.parameters]
troubleshoot_prompt = "{{troubleshoot_prompt}}"
declared_gate_command = "{{declared_gate_command}}"
protected_check = "{{protected_check}}"
position = """
You are the first troubleshoot pass on a fresh post-review red gate. The gate was green before a
review agent edited this tree, so the review's own edits are the sole cause of the red. Decide which
kind of edit broke it. If the breaking edits are cosmetic, refactoring, or style changes, do not
repair them: declare `revert` and stop — Gantry restores the tree to the boundary before the review
ran, keeping the executor's work and any verified repairs. If an edit strengthened a check,
corrected a wrong assertion, or surfaced a genuine defect, the red is information rather than
damage: fix it forward. The review's own written rationale is in the diff.
"""

[[patterns.repair_review.steps]]
if = { troubleshoot_revert = "revert" }
then = "revert_review_edits"
else = "regate_after_review_repair"

restore puts the tree back before the step runs, so this gate judges the restored boundary. A red here is a real fault rather than a review artifact.

sprint 
[[patterns.revert_review_edits.steps]]
name = "restored_gate"
title = "Testing"
type = "gate"
command = "{{declared_gate_command}}"
restore = { before = "review" }

Not route_troubleshoot_verdict: a troubleshoot pass that declared revert wrote no troubleshoot_verdict, so routing there would fall through to check_attempt_ceiling and retry a task whose fault predates the review.

sprint 
[[patterns.revert_review_edits.steps]]
if = { restored_gate = "red" }
then = "examine_restored_red"

The fix-forward path's re-gate. Green completes the task; red asks the troubleshoot pass what it declared.

sprint 
[[patterns.regate_after_review_repair.steps]]
name = "repaired_review_gate"
title = "Testing"
type = "gate"
command = "{{declared_gate_command}}"

[[patterns.regate_after_review_repair.steps]]
if = { repaired_review_gate = "red" }
then = "route_troubleshoot_verdict"

The endings

Each ends in a stop carrying one note. Three call troubleshoot first to write a handover; the shared plan-change rejection route declares its own troubleshooter, which needs no gate. The stop record carries declared-output content, resolved references, and absent-output evidence.

sprint 
[[patterns.examine_executor_blocked.steps]]
name = "executor_blocked_handover"
type = "call"
pattern = "troubleshoot"

[patterns.examine_executor_blocked.steps.parameters]
troubleshoot_prompt = "{{troubleshoot_prompt}}"
declared_gate_command = "{{declared_gate_command}}"
protected_check = "{{protected_check}}"
position = """
The executor declared itself blocked before the gate could judge project work. Examine the
executor_note evidence and write the handover document. Do not attempt a repair in this session: the
final stop follows this troubleshoot pass.
"""

[[patterns.examine_executor_blocked.steps]]
type = "call"
pattern = "stop_executor_blocked"

[[patterns.stop_executor_blocked.steps]]
type = "stop"
note = "The executor declared itself blocked."

[[patterns.examine_review_blocked.steps]]
name = "review_blocked_handover"
type = "call"
pattern = "troubleshoot"

[patterns.examine_review_blocked.steps.parameters]
troubleshoot_prompt = "{{troubleshoot_prompt}}"
declared_gate_command = "{{declared_gate_command}}"
protected_check = "{{protected_check}}"
position = """
The reviewer declared the task blocked after examining the task result. Examine the review_note
evidence and write the handover document. Do not attempt a repair in this session: the final stop
follows this troubleshoot pass.
"""

[[patterns.examine_review_blocked.steps]]
type = "call"
pattern = "stop_review_blocked"

[[patterns.stop_review_blocked.steps]]
type = "stop"
note = "The reviewer's verdict was blocked."

[[patterns.stop_review_verdict_absent.steps]]
type = "stop"
note = "The reviewer did not write review_verdict, so the task cannot be accepted."

[[patterns.stop_handover.steps]]
type = "stop"
note = "The troubleshoot pass ended without a verified repair and declared a handover; the document is at state/handover.md."

[[patterns.stop_attempt_ceiling.steps]]
type = "stop"
note = "The task reached the declared attempt ceiling."

[[patterns.stop_invalid_attempt_ceiling.steps]]
type = "stop"
note = "The task cannot retry because attempt_ceiling was `{{attempt_ceiling}}`, which is neither `unbounded` nor a non-negative integer."

[[patterns.stop_attempt_ceiling_absent.steps]]
type = "stop"
note = "The attempt ceiling check did not write attempt_ceiling_decision, so the task cannot decide whether to retry."

[[patterns.examine_restored_red.steps]]
name = "restored_red_handover"
type = "call"
pattern = "troubleshoot"

[patterns.examine_restored_red.steps.parameters]
troubleshoot_prompt = "{{troubleshoot_prompt}}"
declared_gate_command = "{{declared_gate_command}}"
protected_check = "{{protected_check}}"
position = """
The review's edits were reverted, but the restored boundary is still red. Examine the gate output and
the troubleshoot_note evidence, then write the handover document. Do not attempt a second repair in
this session: the final stop follows this troubleshoot pass.
"""

[[patterns.examine_restored_red.steps]]
type = "call"
pattern = "stop_restored_red"

[[patterns.stop_restored_red.steps]]
type = "stop"
note = "The review's edits were reverted and the restored boundary is still red, so the fault predates the review."