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.
Efforts and sub-issues
Section titled “Efforts and sub-issues”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.
Slug handles
Section titled “Slug handles”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:
cckit effort new "Slug handles for efforts" --slug slug-handles # optional explicit handlecckit effort start slug-handles # identical to: cckit effort start 93cckit effort pr slug-handlescckit effort close slug-handlesA 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.
The lifecycle: start → pr → close
Section titled “The lifecycle: start → pr → close”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 apar:label on the parent. The--flowvalues (the[Flow]title tags) come from a controlled vocabulary your project sets once aseffort.flowsincckit.config.json/.claude/kit.config.json— e.g."effort": { "flows": ["Growth", "Checkout"] }. Unset, it defaults toCore UI API Docs Infra Auth Data Web App; an explicitEFFORT_FLOWSenv var still overrides both for one invocation.cckit effort startgives the effort’s worktree the same full setup ascckit 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 withKIT_WT_INSTALL=0; see worktree bootstrap). The worktree lives at.claude/worktrees/effort+<N>-<slug>, a namecckit gcrecognizes 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 prand the/kit-effort-prskill 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 closeis the single close implementation — the/kit-effort-closeskill 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 withKIT_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.jsonlsays it is complete. The snapshot writes<git-common-dir>/traces/effort-<N>/<seq>-<shortsha>.{diff,meta}— one pair per commit — plus anindex.jsonlholding 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.
Only so many efforts at once
Section titled “Only so many efforts at once”Three half-finished efforts finish nothing. cckit effort start refuses to start a new effort
once the WIP limit is reached:
$ cckit effort start 244effort_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 says | Reality | Gate with the cache |
|---|---|---|
| nothing (branch pushed since your last fetch) | origin has it | undercounts — lets you exceed the limit |
origin/effort/<N>-… still there (branch deleted on origin, not yet pruned) | origin dropped it | overcounts — 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:
| Situation | What happens |
|---|---|
| Fewer efforts in progress than the limit | Starts. |
| 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 progress | Always allowed — it adds no WIP, so the verb stays safe to re-run. |
--force, or KIT_FORCE=1 in the environment | Starts anyway, and says so on stderr. |
effort.wipLimit set to 0 | Every ordinary start is refused (a deliberate freeze) — --force / KIT_FORCE=1 still start. |
effort.wipLimit unset | The built-in default, 2. |
effort.wipLimit not a non-negative integer | Ignored 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:
- Wave 0 — every sub-issue that nothing is blocking. These can all run at the same time.
- Wave 1 — sub-issues whose blockers were all in wave 0. They start once wave 0 merges.
- …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:
cckit effort chain 241 242 243 # 242 blocked_by 241 · 243 blocked_by 242Every 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 online 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 1revisits 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.
Worktrees keep parallel work apart
Section titled “Worktrees keep parallel work apart”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