Skip to content

Efforts, waves & worktrees

How cckit runs many issues at once without the changes colliding.

A big piece of work is an effort. cckit breaks it into sub-issues, then sorts them into waves so the ones that don’t depend on each other run together, and the ones that do wait their turn.

An effort is one goal that’s too big for a single issue. It becomes a parent issue with sub-issues under it — each sub-issue is one shippable step. cckit effort new creates the effort and its subs: it fills the parent’s four-section plan body (Goal / Scope / For agents / Verification), applies the ctx/kind/priority/role/flow labels, and lints every title. The /kit-effort-new skill produces the identical effort — both call one shared core, so there is no drift between the verb and the skill.

The GitHub issue number is the canonical key for an effort — the sub-issue links, PRs, labels, and dependencies all reference it. But a bare number is hard to remember, so every effort also has a memorable slug handle: the one that already lives in its effort/<N>-<slug> branch.

cckit effort start, pr, and close accept the slug or the number interchangeably:

Terminal window
cckit effort new "Slug handles for efforts" --slug slug-handles # optional explicit handle
cckit effort start slug-handles # identical to: cckit effort start 93
cckit effort pr slug-handles
cckit effort close slug-handles

A pure-digits argument is always treated as a number; anything else is resolved to the canonical number by matching the effort/* branches (local and remote), then the slug:<slug> label, then the titles of open efforts. An unknown or ambiguous slug fails with a clear error instead of guessing the wrong effort. Listings and titles render efforts as slug #N.

  • cckit effort new — flags (--flow, --role, --priority, --par, …) may appear in any position, before or after the name and sub specs. --par seq | wide | <N> records how the effort’s subs are meant to run as a par: label on the parent. The --flow values (the [Flow] title tags) come from a controlled vocabulary your project sets once as effort.flows in cckit.config.json / .claude/kit.config.json — e.g. "effort": { "flows": ["Growth", "Checkout"] }. Unset, it defaults to Core UI API Docs Infra Auth Data Web App; an explicit EFFORT_FLOWS env var still overrides both for one invocation.
  • cckit effort start gives the effort’s worktree the same full setup as cckit start: it copies your gitignored env files, assigns a per-worktree dev port, and installs dependencies where the project actually declares any (opt out entirely with KIT_WT_INSTALL=0; see worktree bootstrap). The worktree lives at .claude/worktrees/effort+<N>-<slug>, a name cckit gc recognizes so it is never pruned while the effort issue is open. It is also WIP-limited — see Only so many efforts at once below.
  • cckit effort pr and the /kit-effort-pr skill compose the PR title from one shared composer, and both refuse to open a PR whose title lacks the mandatory [#N] effort id.
  • cckit effort close is the single close implementation — the /kit-effort-close skill is a thin caller of the same function, so the two can never drift apart. It snapshots each sub-issue’s diff and captures effort metrics before the squash, refuses to squash-merge when no work trace was captured (the squash is irreversible — override with KIT_FORCE=1), squash-merges, closes the parent and every sub and sets the board Status=Done for each, garbage-collects the worktree/branch, runs an optional, config-gated knowledge-ingest hook (effort.knowledgeIngestHook), and finishes with an advisory kit-sync drift check that flags any kit-managed files the effort touched (they belong upstream via /kit-contribute).
  • The work trace is a directory, and index.jsonl says it is complete. The snapshot writes <git-common-dir>/traces/effort-<N>/<seq>-<shortsha>.{diff,meta} — one pair per commit — plus an index.jsonl holding one JSON record per line pairing each commit to its sub-issue. The index is built beside the real one and moved into place only after every record is written, so its presence means the whole trace is there; that is what the refuse-to-squash check reads. A partial run leaves the previous trace intact rather than half-overwriting it.
  • Wave-driven efforts close too. A wave run ships each sub as its own task PR squash-merged straight to the base branch, so no effort/<N> integration branch ever exists. cckit effort close <N> detects that (no such branch locally or on origin) and closes wave-style: it verifies every sub is closed with a merged PR (refusing and listing the stragglers otherwise), snapshots the work trace from the merged sub PR diffs instead of branch commits, and then runs the same close tail — metrics judge/sync, parent close, board Status=Done for parent and subs, the knowledge-ingest hook, and the kit-sync drift check. If the integration branch does exist, the close still asks you to run from it.

Three half-finished efforts finish nothing. cckit effort start refuses to start a new effort once the WIP limit is reached:

Terminal window
$ cckit effort start 244
effort_start: 2 effort(s) already in progress and the WIP limit is 2.
· order-and-cadence #241 (effort/241-order-and-cadence)
· release-gates #257 (effort/257-release-gates)
→ refusing to start #244 — nothing was created.
Close one with 'cckit effort close <N>', or start anyway with --force (or KIT_FORCE=1).
The limit is effort.wipLimit in the project config (default 2); EFFORT_WIP_LIMIT overrides it.

What counts as in progress: an effort whose effort/<N>-<slug> branch exists — a local head or a branch on origin, so an effort a teammate (or another machine) started counts too. cckit effort start creates that branch and cckit effort close deletes it, so the counted set is exactly “started and not yet closed”. There is no second definition and no board lookup involved.

The origin half is read with git ls-remote by default — not from your cached refs/remotes. (EFFORT_WIP_REMOTE=0 opts out; see Working offline below.) The cache is wrong in both directions, and a WIP gate is wrong with it:

Cached refs/remotes saysRealityGate with the cache
nothing (branch pushed since your last fetch)origin has itundercounts — lets you exceed the limit
origin/effort/<N>-… still there (branch deleted on origin, not yet pruned)origin dropped itovercounts — blocks a start it should allow

git ls-remote sees the branch pushed a second ago and does not see the one deleted a second ago, and it writes nothing: no fetch, no prune, no ref touched. effort_slug_resolve still reads the cached refs, because resolving a slug handle sits on the hot path of every effort verb — that cached-ref lookup is network-free. Resolution as a whole is not: when no branch matches the slug it falls through to gh (see below), which is why a WIP refusal on a slug input can still make a GitHub read.

The rules, exactly:

SituationWhat happens
Fewer efforts in progress than the limitStarts.
At the limit (2 in progress, limit 2)Refused. The limit is a ceiling on concurrent efforts.
Above the limit (after a --force)Refused.
Re-running start on an effort already in progressAlways allowed — it adds no WIP, so the verb stays safe to re-run.
--force, or KIT_FORCE=1 in the environmentStarts anyway, and says so on stderr.
effort.wipLimit set to 0Every ordinary start is refused (a deliberate freeze) — --force / KIT_FORCE=1 still start.
effort.wipLimit unsetThe built-in default, 2.
effort.wipLimit not a non-negative integerIgnored with a warning on stderr; the default 2 is used.

Set the limit in cckit.config.json / .claude/kit.config.json:

{
"effort": {
"wipLimit": 3
}
}

EFFORT_WIP_LIMIT in the environment overrides the config for one invocation.

Some sub-issues depend on others: sub #4 can’t start until sub #1 is merged. cckit reads those blocked-by links and groups the work into waves:

  1. Wave 0 — every sub-issue that nothing is blocking. These can all run at the same time.
  2. Wave 1 — sub-issues whose blockers were all in wave 0. They start once wave 0 merges.
  3. …and so on, until everything is merged.

cckit plan shows the waves. Each wave is exactly “what can run in parallel right now”.

Inside a wave, the most urgent work comes first

Section titled “Inside a wave, the most urgent work comes first”

A wave can hold a dozen issues, and they are not equally urgent. Within one wave cckit plan orders them by their priority:pN label — p0 → p1 → p2 → p3, with unlabeled issues last. Issues that share a priority keep the order they already had, and the batch packing follows that order, so the p0 work lands in the first batch rather than wherever it happened to fall.

Dependencies still win. Priority never overrides a blocked-by link. Two issues only share a wave when there is no dependency between them — a blocker is always placed in a strictly earlier wave than the issue it blocks. So a p3 issue that blocks a p0 issue still runs first: they are in different waves, and the priority sort only ever reorders work that dependencies have already declared startable at the same time.

Declaring the order — cckit effort chain

Section titled “Declaring the order — cckit effort chain”

Waves are only as good as the blocked-by links they read, and setting those links by hand is tedious. cckit effort chain declares a whole running order in one command:

Terminal window
cckit effort chain 241 242 243 # 242 blocked_by 241 · 243 blocked_by 242

Every issue after the first gets two things: the native GitHub blocked_by edge on its predecessor — the edge cckit plan reads to layer the waves — and a - Depends on #<predecessor> line in its ## Relations section, the human-readable mirror. It is the same line cckit effort new --depends-on writes, produced by the same formatter, so the two never drift. A chained set therefore lands one issue per wave, in the order you gave.

What it does and does not do:

  • Idempotent. An edge or a Depends on line that is already there is reported and skipped, so running the same chain twice changes nothing — no duplicate line, no duplicate edge.
  • Additive. It only ever adds its edge. An issue already blocked by something else keeps that blocker and ends up with both.
  • Validated before anything is written. A refused chain leaves the board completely untouched. It refuses fewer than two numbers, an argument that is not an issue number, an issue that does not exist in the repo, a number that appears twice in the list (chain 1 2 1 revisits a node), and an edge that would close a cycle through dependencies GitHub already holds. A cycle is refused rather than written because the wave layering cannot order a cyclic graph.

Running several issues at once raises one question: how do the changes not overwrite each other? The answer is a worktree — a separate working copy of the repo on disk, on its own branch.

Each issue gets its own branch and worktree, so each piece of work edits its own copy. The changes only meet again when their pull requests merge into main — and because the issues in a wave touch different files, they merge cleanly.

Independent, educational project — not affiliated with or endorsed by Anthropic. Claude and Claude Code are trademarks of Anthropic PBC.Disclaimer & trademarks ·

From Mexico withloveby josegtz