Sprint Chains

Execute a workflow multiple times in batch using Sprint Chains - a phased execution mechanism that tracks per-sprint PRs and supports resuming from any sprint.

9 min read
workflowssprint chainsbatch execution

Sprint Chains are a batch execution mechanism that runs the same workflow multiple times in sequence - once per sprint. Each sprint executes the full workflow pipeline against the project repository and produces its own pull request. Sprint chains are designed for phased development work: when a large task is naturally divided into sequential phases that each deserve their own implementation cycle, review, and merge.

Sprint Chains vs. Work Chains

CodeCourier provides two chain mechanisms, and the distinction matters:

  • Sprint Chains - Execute the same workflow multiple times. Each execution is called a sprint. Sprint 1 runs the workflow, sprint 2 runs the same workflow again on the next task, and so on. Used when you want to push a workflow through several phases of work, each yielding a separate PR.
  • Work Chains - Execute different issues through a single workflow. Each item in the work chain is a different task, all processed through the same pipeline. Used for batch-processing a backlog of issues via an automated queue.

Key Distinction

Sprint chains iterate over phases of a single project goal. Work chains iterate over a list of separate issues. Use sprint chains when each phase builds on the previous one; use work chains when tasks are independent.

Sprint Chain Data Model

A sprint chain record captures the full configuration and runtime state of the batch execution:

Sprint chain fields
{
  userId: string,               // Owner who created the chain
  projectId: string,            // Project the chain belongs to
  workflowId: string,           // Workflow blueprint to execute each sprint
  status: "pending"             // Chain lifecycle state
        | "running"
        | "completed"
        | "failed"
        | "cancelled",
  sprintRange: number,          // Total number of sprints (e.g., 5)
  currentSprintIndex: number,   // Zero-based index of the in-progress sprint
  resumeFromSprint: number,     // Sprint index to restart from (for recovery)
  sprintPrUrls: string[],       // PR URL created per sprint (index-aligned)
}

The sprintPrUrls array is index-aligned to the sprint sequence. sprintPrUrls[0] holds the PR from sprint 1, sprintPrUrls[1] from sprint 2, and so on. Sprints that have not yet completed have undefined at their index.

Creating a Sprint Chain

Sprint chains are created and managed from the Runs page (/p/[id]/runs) using the sprint chain launcher.

1

Open the Sprint Chain Launcher

On the project’s Runs page, click "New Sprint Chain". The launcher panel appears on the right side of the screen.

2

Select a Workflow

Choose the workflow blueprint that will be executed for every sprint. The workflow must already exist in your project. All sprints use this same blueprint, so select the one most appropriate for the phased work you’re planning.

3

Configure the Sprint Range

Set the sprint range - the total number of sprints to execute. For example, a sprint range of 5 means the workflow will run 5 times in sequence. Each sprint is numbered from 1 to N(displayed as "Sprint 1 of 5", "Sprint 2 of 5", etc.).

Plan Your Sprint Count Carefully

Sprint chains do not pause for manual review between sprints. Once started, all sprints execute automatically in sequence. Plan your sprint count based on how many distinct phases your work requires, and use the resume capability if you need to interrupt mid-chain.
4

Write Per-Sprint Prompts (Optional)

You can provide a single base prompt or configure individual prompts for each sprint. If a single prompt is provided, every sprint receives the same task description. For phased work where each sprint has a distinct objective, supply per-sprint prompts to guide each execution.

5

Launch the Chain

Click "Start Sprint Chain". CodeCourier creates the sprint chain record with status pending and immediately begins executing sprint 1. The chain entry appears in the Runs list with source sprint so it can be filtered separately from direct workflow runs.

Execution Lifecycle

The sprint chain orchestrator manages execution across all sprints. The lifecycle follows a strict sequential pattern:

Chain Status Transitions

  • pending - The chain has been created but the first sprint has not started. This is a brief transitional state.
  • running - A sprint is actively executing. The currentSprintIndex field reflects which sprint is in progress.
  • completed - All sprints finished successfully. Every sprint produced a run and (if code was changed) a pull request.
  • failed - A sprint encountered an unrecoverable error that prevented the chain from continuing. The chain record captures which sprint failed.
  • cancelled - The user manually stopped the chain before all sprints completed.

Per-Sprint Run Creation

For each sprint, the orchestrator creates a standard workflow run record with:

Run fields set by the sprint chain orchestrator
{
  source: "sprint",            // Identifies the run as sprint-originated
  workflowId: chain.workflowId,
  prompt: sprintPrompt,        // The sprint's prompt (base or per-sprint)
  // ... standard run configuration
}

When the sprint’s run completes and a PR is created, the chain orchestrator captures the PR URL into sprintPrUrlsat the current sprint’s index, then advances currentSprintIndex and begins the next sprint.

Sprint Sequencing

Sprints are strictly sequential - sprint 2 does not start until sprint 1’s run has fully completed (status completedor failed). This ensures that each sprint can build on the code changes committed by the previous sprint. The branch used across sprints is typically the same feature branch, so each sprint’s commits stack on top of prior sprints’ work.

Per-Sprint PR Tracking

One of the key features of sprint chains is per-sprint pull request tracking. Each sprint that produces code changes creates its own pull request. The sprintPrUrls array records these URLs, giving you a complete audit trail of what was delivered in each sprint phase.

Example sprintPrUrls after 3 of 5 sprints
sprintPrUrls: [
  "https://github.com/org/repo/pull/42",  // Sprint 1 PR
  "https://github.com/org/repo/pull/43",  // Sprint 2 PR
  "https://github.com/org/repo/pull/44",  // Sprint 3 PR
  undefined,                               // Sprint 4 (not yet run)
  undefined,                               // Sprint 5 (not yet run)
]

The PR URLs in sprintPrUrlsare displayed on the sprint chain detail view, giving you direct links to review each sprint’s output without navigating through the full runs list.

Resume from Sprint

Sprint chains support a resume from sprint capability. If a chain fails or is cancelled before completing, you can restart it from any specific sprint rather than rerunning the entire sequence.

The resumeFromSprint field on the sprint chain record controls which sprint index the orchestrator starts from when the chain is resumed. Setting resumeFromSprint = 2 (zero-indexed) means the chain begins at sprint 3, skipping sprints 1 and 2.

1

Identify the Failure Point

Check currentSprintIndexon the failed chain to see which sprint was in progress when the failure occurred. Review that sprint’s run detail page to understand the root cause.

2

Set the Resume Index

From the sprint chain detail view, click "Resume from Sprint" and enter the sprint number you want to restart from. CodeCourier setsresumeFromSprintaccordingly. You can resume from the failed sprint itself (to retry it) or from the next sprint (if the failed sprint’s work was committed and you want to continue forward).

3

Restart the Chain

Click "Resume". The orchestrator sets the chain status back to running and begins execution at the specified sprint. Previously completed sprints are not re-executed, and their PR URLs in sprintPrUrls are preserved.

Resume After Partial Progress

Because each sprint commits to the Git branch, resuming from a sprint preserves all code changes from earlier sprints. The resumed sprint’s agents see the full history of prior sprint commits and can build on them correctly.

Cancelling a Sprint Chain

You can cancel a running sprint chain at any time from the sprint chain detail view. Cancellation:

  1. Sets the chain status to cancelled.
  2. Cancels the currently running sprint’s workflow run if it is still in progress.
  3. Prevents subsequent sprints from starting.

All sprint PRs created before cancellation remain open in GitHub. Work committed to the branch is preserved and can be resumed using the resume capability.

Use Cases

  • Iterative feature development - Sprint 1 scaffolds the data model and API, sprint 2 builds the UI, sprint 3 adds tests, sprint 4 handles edge cases. Each sprint produces a reviewable PR.
  • Phased migrations - Sprint 1 migrates component library A, sprint 2 migrates library B, sprint 3 updates all consumers. Each sprint is a safe, independent unit of change.
  • Batch code quality improvements - Each sprint runs the same quality workflow against a different module of the codebase, with per-sprint prompts targeting specific directories.
  • Incremental test coverage - Sprint by sprint, a workflow adds test coverage to different areas, with each sprint targeting a different package or feature domain.
  • Rolling dependency updates - Sprint 1 updates one set of dependencies, sprint 2 updates the next, avoiding one massive PR with hundreds of conflicts.

Monitoring Sprint Chains

Sprint chains are visible in two places:

  • Runs list - Individual sprint runs appear with source sprint. Use the source filter to isolate them.
  • Sprint chain detail view- Shows the chain status, current sprint index, all sprint PR URLs, and a timeline of sprint executions. Accessible from the chain’s entry in the Runs page navigation.

Notifications are sent when the chain completes (sprint_completed) or fails (sprint_failed), so you don’t need to actively monitor execution.

Running Workflows

Understand individual run lifecycle and status tracking.

Recurring Tasks

Schedule workflows to run automatically on a recurring basis.

Monitoring

Track sprint chain progress and interpret execution metrics.

Workflow Steps

Configure the step types that execute within each sprint.