Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/xantorres/repokernel/llms.txt

Use this file to discover all available pages before exploring further.

Parallel wave execution lets multiple sprints in an epic run at the same time — each in its own isolated Git worktree — when they touch different parts of the codebase and have no data dependencies on each other. RepoKernel’s wave scheduler groups sprints by their dependency graph, checks path overlap before starting each wave, and merges results back into the epic branch once reviews are accepted. The result is faster wall-clock time on large epics without risking scope collisions or merge chaos.

​
When to use parallel execution

Use parallel execution when:
  • Sprints touch non-overlapping parts of the codebase
  • Sprints have no data or code dependencies on each other
  • You want to reduce wall-clock time for large epics
Do not use parallel execution when sprints share files or depend on each other’s output — sequential mode is the correct choice there.

​
Enabling parallel execution

Set execution_strategy: parallel in the epic frontmatter: 
# .repokernel/plan/epics/E-001.md
---
id: E-001
title: "Authentication system"
status: active
execution_strategy: parallel
sprints:
  - S-001
  - S-002
  - S-003
---
This is exactly how the parallel-epic example is configured: 
---
id: "E-001"
title: "Parallel Epic Example"
status: "planned"
execution_strategy: "parallel"
sprints:
  - "S-001"
  - "S-002"
  - "S-003"
  - "S-004"
---

​
allowed_paths is required for parallel sprints

Every sprint in a parallel epic must declare allowed_paths. An empty allowed_paths means “could touch anything,” which makes path-conflict detection impossible. The validator blocks parallel waves that contain sprints without allowed_paths — you will see a P0 finding until every sprint in the wave is scoped.
Each sprint declares the paths it is allowed to modify: 
# .repokernel/plan/sprints/S-001.md
---
id: S-001
epic_id: E-001
title: "Auth module"
status: queued
lane: main
review_required: false
allowed_paths:
  - src/auth
---
Paths must not overlap between sprints in the same wave. If they do, the validator raises a conflict and blocks execution unless --allow-overlap is explicitly passed (see below).

​
How waves are built

The run loop groups sprints into dependency waves:
  • Wave 1 — sprints with no depends_on, or whose dependencies are already shipped
  • Wave 2 — sprints whose depends_on entries were all in wave 1
  • And so on
Within each wave, sprints with non-overlapping allowed_paths run concurrently. The parallel-epic example has two waves: 
Wave 1: S-001 + S-002   (no dependencies — run concurrently)
Wave 2: S-003 + S-004   (depend on S-001 and S-002 respectively)
After all sprints in a wave complete and their reviews are accepted, their branches are merged into the epic worktree and the next wave starts.

​
Previewing with --dry-run

Always preview the wave plan before executing. Dry-run is free — no Git state is modified — and it surfaces path conflicts before any worktrees are created.
rk run E-001 --dry-run
Dry-run output includes:
  • Resolved worktree paths for each sprint
  • Branch names (rk/sprint/<epic-id>/<sprint-id>)
  • Wave groupings
  • Any path conflicts detected
You can also preview dependency order interactively with rk wave: 
rk wave E-001
When you’re happy with the plan, queue eligible work and run it: 
rk wave E-001 --apply --enqueue
rk run E-001 --parallel --agent claude

​
Running a parallel epic

rk run E-001 --agent claude
With a per-invocation concurrency cap: 
rk run E-001 --agent fake --concurrency 2
--concurrency 2 caps sprints per wave. If a wave has 5 sprints and --concurrency 2 is set, the first 2 run, then the next 2, then the last 1.

​
Concurrency configuration

Set global concurrency limits in repokernel.config.yaml. The parallel-epic example uses: 
parallel:
  maxConcurrentSprints: 4
  conflictStrategy: block
maxConcurrentSprints is a hard upper bound on how many sprints may run within a single wave. Set it to match your agent budget and machine capacity. To temporarily cap concurrency for a single invocation without changing config, use --concurrency N on the command line.

​
What happens during a wave

For each sprint in the wave:
  1. A sprint worktree is created at <worktrees.root>/<repo-directory-name>/<epic-id>-sprints/<sprint-id>/ on branch rk/sprint/<epic-id>/<sprint-id>.
  2. The sprint is transitioned to active and the agent is invoked.
  3. Agent results are validated — changed files are checked against allowed_paths.
  4. The sprint is transitioned to review.
After all sprints in the wave finish:
  1. The run pauses with halt reason awaiting_reviews.
  2. You review and accept each sprint’s review.
  3. On resume, each sprint’s branch is merged into the epic worktree (rk/epic/<epic-id>).
  4. The sprints are closed (shipped).
  5. Sprint worktrees are removed.
  6. The next wave starts.

​
Reviewing a parallel wave

The run pauses after a wave completes and all sprints are in review. Set verdicts for each: 
rk review-verdict R-001 accepted
rk review-verdict R-002 accepted
Then resume the run: 
rk run --resume RUN-001

​
The --allow-overlap flag

By default, sprints with overlapping allowed_paths are blocked from running in the same wave. To allow overlap explicitly — useful when you know two sprints touch the same file in non-conflicting ways — first enable the override in config: 
parallel:
  allowOverlapFlag: true
Then pass the flag at runtime: 
rk run E-001 --allow-overlap
--allow-overlap means you accept responsibility for any merge conflicts that arise. If two sprint branches conflict during merge into the epic worktree, the run halts with merge_conflict:<sprint-id> and cannot be resumed — you must resolve the conflict manually in the epic worktree and start a fresh run.

​
How merge works after parallel waves

RepoKernel uses a custom Git merge driver for .repokernel/registry.json. When two branches both modify the registry (the common case in a parallel run), the driver:
  • Unions sprints, epics, and reviews by id
  • Picks the more-progressed status symmetrically (shipped > review > active > ...)
  • Surfaces real conflicts (diverged sprint title, lane, gate) as machine-readable MergeConflict[] rather than leaving JSON conflict markers
  • Re-derives health.blocked from the merged finding set
The driver is installed per-clone by rk init via a .gitattributes entry and local git config. Hosted web merges (GitHub’s UI merge button, GitLab merge) do not execute the local driver — for those, prefer local merges or run rk validate in CI to catch any registry drift.

​
Review gates between waves

You can declare a gate field on sprints to create checkpoints within an epic. All sprints sharing the same gate value must be accepted before any downstream sprint can run: 
rk gate add qa-sign-off --sprint S-003 --sprint S-004
rk gate resolve qa-sign-off --epic E-001
See the CLI reference for the full rk gate subcommand surface.

Build docs developers (and LLMs) love

Get started for freeTalk to us