Lead — decide at the top, work in subagents
The lead session stays small: it reads summaries, decides with the human, delegates, checks and
delivers. Project files are changed by subagents, each with its own context; the facts of the tour come from cadence lead tour, a program. The projects
are the sub-folders of the current directory that contain .cadence/raf.yaml or docs/plan/raf.yaml, or a cadence.yaml
with a plan: key. A project whose cadence.yaml maps the fields of a plan kept by its own tool is
read-only for raf: it takes part in the tour, and its plan is changed with the project's own
commands (its CLAUDE.md names them), never with raf start|done|note|ux|review.
Limits that always apply
- At most as many subagents running at once as the session cap, 2 unless the human set another. Queue
the rest. The cap is the human's setting (
CADENCE_MAX_SESSIONS, or--max-sessionson a wave; 2 by default, shared by every wave). The sessions of an orchestrated wave (section 2b) count toward this limit: orchestrate sessions plus subagents never exceed the cap. A wave already caps itself; before starting a subagent, checkcadence orchestrate --status, and while a wave runs, start none beyond the free slots. Read the cap and the free slots, do not compute them:cadence orchestrate --statusandcadence lead tourprintcréneaux libres : N sur M(M is the configured cap; the formula is written once in docs/concepts.md#slots-and-holds;lead touralways prints it, so3 sur 3means all M are free).lead releaseprints the line again after handing the session back, with the ready lots that can fill the slot and a⚠ N créneau(x) libre(s)while a slot is empty: start a lot then, do not leave the slot empty. A session you start by hand counts too (a fix subagent, a review, a QA pass launched outside a wave): the registry does not see it, so declare it. Acadence runis the exception: it counts itself while it lives (L710,runs cadence run : N (…)in the slots line), so never hold it;lead holdrefuses (exit 2) a label that names the lot or the id of a live run. Right before starting it,cadence lead hold <label> [--ttl minutes](60 minutes by default, the label names the session:correctif-L12); as soon as it comes back,cadence lead release <label>. While it is held, both commands printsessions du lead : N (labels)and subtract it fromcréneaux libres; the--ttlis the maximum duration you declare for the session (size it to the slot you have, not to the optimistic case). When it runs out the hold stops counting, but nothing stops the session:lead tourandorchestrate --statusprint⚠ session du lead échue : <label> (…)until you release it, and the band shows the same ⚠ row. At each ⚠, decide at once: either it is still worth the slot, so renew it withcadence lead hold <label> --ttl <minutes>and say why in one sentence, or stop it (TaskStopor the agent's end) andcadence lead release <label>. A fix that ran 5 h on a 3 h slot (23-10) is the case this catches. A hold blocks no session of the lead, but orchestrated waves wait for it (they take no slot while held and running sessions reach the cap); it never raises the cap. Never raise--max-sessionsorCADENCE_MAX_SESSIONSyourself to speed a wave up: raising the cap is a decision of the human (a trial at 3 was decided on 2026-10-12); if the slots are the bottleneck, say so and let them decide. - Never two subagents in the same repository at the same time, and the lead does not commit in a repository where a subagent is working.
- Deliveries and
raf ux/raf reviewverdicts are done by the lead, one project at a time, or by thelivreuragent it launches (L439): the delivery and, withlead.ux: lead,raf uxmay be done by thelivreur;raf reviewstays with the lead. Launch onelivreurat a time: never two deliveries in parallel, and eachlivreurcounts in the cap of subagents. Only anotherlivreuror another subagent blocks a new one; the sessions of a running wave do not (a ready lot is delivered while the wave runs, section 2b). Never launch alivreurwhile the wave integrates a lot (cadence lead tourshows it):raf donewould write the plan of the main tree, which that integration refuses as modified. Likewise, in a repository without worktreesraf doneis refused (exit 2,done différé) while a session of the wave works in the main tree: the plan it would write is a modified file that hands the next lot back (« dépôt sale après implement »). Safe order: wait for the end of that step (cadence orchestrate --status), thenraf done <lot>;--nowwrites at once and accepts the lots being handed back. Brief: the absolute project folder, the lot, the sha to deliver (« livrable jusqu'à »), the value oflead.ux, the base URL of the delivered app (thedeliverconfiguration ofcadence.yaml), and for a visible lot withlead.ux: leadtheux-reviewer's report and the folder of its captures. It hands back one line (L84 livré 3d6edf4, QA à lancer <url>) or oneQuestion : …; the lead itself launches theqa-reviewerwith the URL of the line (section 4), then thelivreurof the next ready lot. - A subagent cannot ask the human anything. When it hits an ambiguity it stops and reports; the lead brings the question to the human.
1. Tour of the projects
Run cadence lead tour from the parent folder (one command, no subagent, no model: it reads the same
facts as cadence session start for every project). It prints one line per project — lots in progress with their commit count
(0 commit included; silencieux Nj when idle for more than three days), drift, notes from the last close (a ⚠ note périmée : L217 done le 24-10 beside a note means it quotes a lot already finished: relay it as stale, never ask for that lot), the next ready lot,
repository state — and exits 0 even when a project is in error (its line says so). --json gives the same
content. Read the lines yourself; open a project's own cadence session start only for the one you need to
look at closer.
The tour opens with the perf header: one line per ⚠ of cadence perf (speed and quality side by side), nothing
when everything is stable. Read it before proposing the three items and relay each ⚠ in one line in your report.
Open an improvement lot only on a trend confirmed on two windows (a ⚠ of trend: two windows compared, enough lots, window
not truncated) or on a net bottleneck (⚠ goulot): at most one improvement lot per tour, in addition to the three, never in
their place, and the human decides. Never open a lot for a micro-optimisation or for the variation of a single window.
Without a ⚠, the header is empty and you say nothing about perf.
A line mémoire · MEMORY.md <n> octets > seuil <s> · … (after the worktree lines) says the MEMORY.md index of the parent
folder, loaded at every turn of your session, weighs more than memory.indexMaxBytes (12000 bytes by default): relay it in one
line and propose to group its dated entries under one line that points to a secondary index. Do it only after the human agrees;
the tour only measures, it never writes the memory. A line mémoire · MEMORY.md illisible (…) or the error line
cadence.yaml · ✗ erreur : memory.indexMaxBytes … is relayed as it is. --json never carries it.
Lines <project> · issue #n « … » · ouverte, … (L548, needs gh) name an open GitHub issue that no lot of the plan cites, or one whose
lots are all published (… mais L526 est publié — la fermer : gh issue close n). Relay each in one line; close an issue, or
open a lot for it, only after the human agrees — the tour and the gh issue close commands that cadence release prints only
show, they close nothing. See docs/lead.md.
Then report to the human in a compact table — one row per project — and propose three items across projects, each with project, lot id and one sentence of justification: finish what is in progress, then drift that blocks a delivery, then ready quick wins. Stop and wait for the priority.
2. Delegation
Since 2.0.0 the default way to do a chosen lot is cadence run (section 2a). Waves through cadence orchestrate (section 2b) stay available, but a blind trial measured them 3.8 times slower than Claude alone and never preferred; use a wave only when the human asks for one.
2a. One lot, one session: cadence run
From the project's folder, in the background (one notification at the end, nothing to follow):
cd <project> && raf start <lot> && cadence run "<the human's request, verbatim>" --lot <lot> [--piece <doc>]… --fond
- One Opus session does the whole lot in a worktree next to the repository (
../.cadence-run/), then the full gate ofcadence.yamlonce (one fix by the same session when red), and a fast-forward on the starting branch. After a non-compliant review (raf review), relaunchcadence run "<the fixes>" --lot <lot>: from the 3rd correction pass of the lot, or after two non-compliant reviews, the run switches to Fable by itself (L726); the launch line and the end of the run say which model played each pass and why. Nothing is pushed: delivery stays yours (cadence verify --gate --sha, push of the sha,cadence deliver,raf done). - Mode. Complet (references read in full before any write, enforced by a hook; request register) when a
--pieceis given, when the request names a word ofreferences:incadence.yaml, or with--complet; léger (Claude alone) otherwise. The launch line says which and why. A piece may be absolute or under~(a knowledge base outside the repository, e.g. the lot's dossier). When the project keeps such a base, pass the lot's dossier as--piece. --fonddetaches the run: it survives this session, its journal is in../.cadence-run/.cadence run --listeshows each run's state.- Question (state
attente): relay it to the human, thencadence run --reponse <id> "<answer>"resumes the same session. - Handed back (
porte-rouge,conflit,refus-integration,sans-commit,sans-porte,echec): the worktree is kept with its state file; read it, then relay to the human — never redo the lot yourself. - Cluster access follows
orchestrate.prodAccess, as for waves. - Several lots in parallel are several
cadence run, one worktree each; two lots that share a resource (uses:, a bench) run one after the other.
Delegating by hand
The other way to delegate is cadence orchestrate (section 2b): a program, not a conversation, that runs
one fresh short session per step; the wave runs from a frozen copy of the cadence package, so it can orchestrate cadence itself and its templates can be edited meanwhile. When the lead delegates by hand, the brief is the template
templates/orchestrate/implement.md of the cadence package — the single source, tested. The lead runs
cd <project> && raf start <lot>, then starts from the brief written by cadence orchestrate --dry-run <project>:<lot>: it is already rendered ({{chemin}}, {{lot}}, {{titre}}, {{objectif}} and {{news}},
the News instruction of a visible lot, are filled in; it names no wave Playwright directory — a hand delegation has none — so the screenshot goes under the OS temp directory, then into docs/nouveautes/captures/). The lead only adjusts the goal to what done looks
like (the human's words) and keeps the rest verbatim. A stale title is no reason to delegate by hand: the lot's scope changed since the plan was written, so give the new goal to the program — --goal "…" on the launch (one lot per launch), or a goal: key on the lots in the plan (every launch, several lots at once): goal: in a native plan, and in a plan kept by another tool (read-only, e.g. maritime's docs/plan/taches.yaml) the key of theirs that holds it, mapped with plan.fields: { goal: <their key> } in cadence.yaml (an unmapped key other than goal is ignored without a message). It replaces the title as the objective of every brief and shows in the wave table.
A lot that adds or changes a screen is visible: after the implementation, have the
ux-reviewer agent review it (give it the URL or the way to run the app) and bring its verdict and
proposed sub-tasks back to the human (add a line Report file: <absolute path> outside the repository, and the folder of the captures: it answers in 15 lines at most — verdict, findings with their rule or measure, not verified, sub-tasks, the paths — and keeps the measurements in that file, L452) — or, where the folder's cadence.yaml says lead.ux: lead, form the UX verdict yourself (see « The UX verdict » in section 2c).
2b. A wave through cadence orchestrate
Once the human has chosen the lots, the lead runs, in the background (it is notified at the end; no
silent wait, no polling loop — cadence orchestrate --status shows where the wave is, and the follow-up below pushes only the lines that ask for a gesture of yours):
cadence orchestrate <project>:<lot> <project>:<lot>@haiku … --wave <id> [--budget 2M] [--no-fill]
Since L587 the wave also draws the next ready lots of the plan (same draw as --continue) into its free slots until the budget is spent, and those lots appear in the final table and the exit code (a drawn lot handed back gives 1). For a wave strictly limited to the lots the human chose, pass --no-fill.
For a single lot whose title is stale, add --goal "<what done looks like>" (refused with two lots, --continue or --resume); for several lots, a goal: key per lot in the plan (mapped by plan.fields.goal on a plan kept by another tool).
Make the wave visible to the human. Name the background task after what it runs — « vague <id> :
<project>:<lot>, … » (its description), so the task list says which projects and lots, not just « a task
is running » — and pass --wave <id> (e.g. 2026-10-08-1030) so its state folder is known in advance. Right after
starting it, arm one follow-up (the Monitor tool) on the wave: cadence orchestrate --follow --wave <id> reads its journal and prints only the lines written from then on that ask for a gesture of yours (a lot ready, handed back or failed, a question, budget or quota reached, an incident — push detected, repository dirtied or HEAD moved by a review —, a lot integrated), not the implementing / reviewing / fixing transitions (on 04-11 tail -F pushed 453 lines into the lead's context, 91 of them useful). The final table is not in the journal: it arrives with the background task's end notification. The follow-up ends by itself with « fin de vague : », about 30 s after the wave stops (a later --resume needs a new --follow, which does not replay the lines already relayed):
cadence orchestrate --follow --wave <id> # from the folder the wave was launched in
Each line it prints reaches this conversation as it happens: relay it to the human in one short sentence, and
bring a question back at once (--resume --wave <wave> --answer, the command printed under the question). That follow-up replaces any waiting loop (and tail -F on the journal): still no polling,
no sleep. The human can also watch from a terminal with cadence orchestrate --status --watch (table refreshed
every 10 s, --interval <s> to change it; it stops by itself when no wave is running).
Steering a wave that is running. From the folder the wave was launched in (--wave <id> when several run from it), in
another command: cadence orchestrate --drop <project>:<lot> takes a lot out of the wave — a lot not started never starts, a lot
with a session running lets that session finish, then it is handed back to the lead (its commits stay); a lot that depended on it is
handed back too. cadence orchestrate --stop-after-current lets the sessions running finish and starts nothing else: the wave
ends interrupted, and --resume --wave <wave> takes it up again (the command printed names the wave). To take a lot out of a wave that is already stopped, use
--resume --wave <wave> --drop <project>:<lot> (the lot is handed back instead of being replayed). Neither kills a session.
One worktree per lot (orchestrate.worktrees, L279) is on by default in cadence's own cadence.yaml since 2026-10-25 (L320) and off in a project that does not set the key (the key is the whole switch: no environment variable). Two independent lots of one repository then play at once, each in its own worktree, and the program integrates them. Its options belong to that mode: --resume --wave <wave> --integrate <project:lot> replays a lot handed back at the integration step (the wave's output names that exact command) and, since L370, a lot handed back for its budget or a non-compliant review that you had corrected and reviewed outside the wave (the gesture is under « A lot handed back despite the escalation », section 3), --replay <project:lot> also after a refused plan write, --remove-worktree <project:lot> [--abandon-commits] removes a kept worktree and branch, and cadence orchestrate --status and cadence lead tour list the worktrees kept by waves (nothing to list in the default mode).
Delivering while the wave runs. A lot that turns ready in the journal is not left waiting: once the lead has re-verified it (section 3, point 2) and recorded its verdict (raf done), it delivers that lot at once, without waiting for the end of the wave. The re-check runs at that sha with cadence verify --gate --sha <sha> (a throwaway worktree whose untracked dependencies are linked from the main tree, removed afterwards), never in the shared tree, which holds the lots still running. Take the sha to deliver from git log: the last commit of the ready lot such that no commit of a lot that is not ready (running, queued, in question, handed back) sits beneath it — the same « livrable jusqu'à » the final table prints. Push that sha alone (git push origin <sha>:main, never HEAD, which holds the code of lots still running; the wave tolerates exactly this push — the journal says « push du lead (livraison de ) toléré » — because the sha is an ancestor of HEAD holding no commit of a lot of the wave that is not ready (a commit that cites no lot passes), whereas any other push still stops the wave as an incident), then cadence deliver --dry-run --sha <sha> and cadence deliver --sha <sha>: deliver accepts a --sha during a wave of the same repository when none of its commits belongs to a lot that is not ready, and refuses otherwise, naming the lots. Without --sha it stays refused until every lot of the repository is ready or handed back. The wave's sessions keep committing in the working tree: --sha never reads it. What the log keeps is <sha>, unless the delivery script declares another deployed commit in CADENCE_DEPLOYED_FILE; if HEAD moved during the delivery without that declaration, deliver warns (« la tête a avancé pendant la livraison ») and the log keeps <sha>: it is not a failure. This is the measured gain: a ready lot used to wait for the slowest lot of its wave (1,554 lot-minutes between « ready » and the end of the wave over 28 waves).
Free resources. cadence lead tour (always, L416) and cadence orchestrate --continue print, after the free slots line, tirables, ressources libres : <project>:<lot> <title> (<resources>) · …: the drawable lots (tirables: todo in the plan, no open dependency — « ready » is a wave state) whose shared resources (uses:) nothing holds, by uses: or by the files a wave's lot commits when the resource declares paths: (L558). Read it again each time an agent comes back (a session ended, a lot handed back or ready) and each time a lot is blocked (a question, a refusal, a resource taken), before waiting for the next transition: a lot listed there can start now, so start it (with the free slots line saying a slot is free) instead of waiting behind the blocked one. The line is a display: nothing is locked, and it never raises the cap — no créneaux libres, no new session. No line means no drawable lot is free: wait.
cadence orchestrate --dry-run … first when a precondition is in doubt. The program, not the lead, runs
for each lot a fresh short session per step — implementation (Sonnet), code review
(Opus, the code-reviewer agent; Sonnet, with no pass on the minor findings, for a lot whose estimate is
≤ 0.25 d — orchestrate.review in cadence.yaml; a blocker or major finding still brings a correction and an
Opus review), a correction in a new session if the review is not compliant (two
passes at most, a third when the review converges: blocking + major findings down from one review to the next and only one left), then, once, a UX review if the lot is visible and the project declares how to see its app (orchestrate.ux in cadence.yaml) — and records raf review itself when the code review is compliant and the UX review too. A lot with spec: true (no screen) goes spec → fiche → accept before the code: the code-reviewer reviews its back-end sheet, and the hypotheses of the final sheet come back in the table as « hypothèse de la fiche » lines, which the lead relays to the human. The state is in
.cadence/runs/<wave>/, not in this conversation. @haiku only when the human writes it, for a
mechanical lot. Exit code: 0 all ready · 1 some lots handed back · 2 refused before acting · 3 wave
suspended (budget or usage limit; --resume --budget … continues).
What the orchestrator does not do, and stays with the lead: choose the lots (with the human), bring the
questions back (--resume --wave <wave> --answer <project>:<lot> "…", naming the wave: a bare --resume is refused when several waves are unfinished), look at the UX reviewer's captures and record
raf ux (the orchestrator reports its verdict, it never records it; who decides it is the lead.ux setting, section 2c), re-verify (section 3, point 2),
raf done, push and deliver. A locked acceptance test that contradicts the sheet (the lot is handed back with verrou des tests d'acceptation, or the session's question says its own test is wrong, e.g. a regex that rejects a sentence the sheet allows) has a path, and it is the lead's, never a session's: correct the test in the working tree (the sheet is left as it is; if it was amended, commit it first, citing the lot: an amended sheet whose every commit cites the lot is accepted, L217, never put it back to the red state), then cadence spec reseal <lot> <test> [<test> …] --reason "why it contradicts the sheet" (outside any wave; several tests in one command when several are rewritten, issue #23): the program redoes the fingerprint of those tests, all or nothing, in a single commit whose subject is short and fixed (the paths and the reason go in the body), writes the reason in acceptation.json (resceaux) and as a note of the lot, commits both, and the lock keeps everything else. For a delivered lot (vert: true) whose contract does not change but whose test is unstable, add --porteur <the lot in progress that carries the fix>: the commit and the note cite that lot, vert stays true (L212). It refuses a lot that is neither in progress nor delivered, a sheet with uncommitted changes or touched by a commit that does not cite the lot, and any listed test touched that is not named in the command, and during a wave of that repository. It is atomic (a refused commit restores acceptation.json and the test), with a plan kept read-only by another tool it leaves the plan untouched and says a note is to be added by hand, with an untracked plan or one outside the repository it writes the note but does not commit it (plan à commiter: do not add it again), and if the commit of the note is refused the reseal stays done and the error says to commit the plan by hand. It is also refused while a wave that is not done (stopped on a question or the quota, or still alive) keeps open any lot of that repository still doing in its plan, the resealed lot, the porteur or any other lot of the repository (the lock hands back all of them, L238; a lot done or absent in the plan, an old abandoned wave, a lot of another repository with the same id never block): the error is a single message, also when a live wave holds the repository lock: it lists every wave (the live ones and the stopped ones) with its launch folder and its lots and gives, for each stopped wave, ONE command to run as it stands, cd <launch folder> && cadence orchestrate --resume --wave <wave> --drop <project>:<lot> --drop <project>:<lot> (a --drop per open lot of the repository, queued ones not yet doing in the plan included, since --resume replays the whole wave; or --resume --wave <wave> --answer … to let it go on); a wave still alive is waited for. Close them first, reseal afterwards. Do it between two sessions, never inside one: a resealed commit that belongs to a session of the wave is not adopted (still a lock violation), and sessions are forbidden the command. Then continue the lot: a new wave cadence orchestrate <project>:<lot> when it was handed back (--resume skips finished lots). A lot closed by hand and left at vert: false: cadence spec green <lot> (L366). spec reseal does not cover it (it takes a lot doing, or a delivered lot at vert: true with --porteur): a lot closed with raf done while its acceptation-<lot>.json stayed at vert: false keeps the lock total on its tests, and every later wave of the repository is handed back with verrou des tests d'acceptation … premier commit fautif on lots that never touched them (issue #18). The way out is cadence spec green <lot>, outside any wave: the program runs the lot's acceptance command (orchestrate.accept), and, green, sets vert: true, reseals the listed tests refined since the red commit and commits the file alone, citing the lot; red, nothing changes (exit 1). raf done now refuses such a lot without --force, and cadence orchestrate --dry-run prints acceptation rouge d'un lot clos for each one before the wave starts; a lot handed back for a test of a closed lot it never touched is this case, not a test to reseal. Minor findings and proposed sub-tasks come back in the table: adding them to
the plan is the lead's decision. A minor finding becomes a lot of its own only if it describes an observable bug (a wrong output, a crash, a measured regression); otherwise it stays a note of the originating lot, so that a review never feeds the next one. If an orchestrated wave is running in a repository, do not commit there
and do not deliver it (cadence deliver refuses).
2c. Chaining without the human
Once the human has given the first choice and the order (the lots, and the priority: --priority or the
priority: list of the parent folder's cadence.yaml), the lead does not come back to ask « next? ». For each lot a
wave hands back ready, it chains, in this order, one project at a time: re-verify it yourself (section 3, point 2),
raf done (a read-only plan: the project's own command; a visible lot first waits for the human's UX verdict, raf ux (the lead's own where the UX-verdict setting below hands it over), and is neither closed nor delivered without it — the chain goes on with the other lots), push, deliver (section 4; when the final table gives « livrable jusqu'à » for a repository — a ready lot under a handed-back one — push that sha alone with git push origin <sha>:main, then cadence deliver --sha <sha>, never HEAD, which holds the unreviewed code of the lot above), the qa-reviewer check that
section asks for; then it starts the next wave, in the declared priority — cadence orchestrate --continue --priority … draws the next ready lot
of the plan itself (section 2b), and the limits of section « Limits that always apply » still hold. A lot that was not
handed back ready (refused, review not compliant after the correction passes, red delivery, blocking QA finding) is
not chained over: it is reported, and the chain goes on with the lots that do not depend on it.
A lot handed back despite the escalation (L337). When the project declares orchestrate.escalation: { model }, the wave itself plays one correction and one fresh review on that model before handing a lot back for a non-compliant review or red tests: do not take such a lot up by hand on a model of your own choice first, and do not replay the escalation yourself. The table says escalade <model> : … under the lot. A lot handed back despite the escalation (rendu malgré l'escalade) is for the human or for an arbitration (the sheet, the brief or the lot is at fault, not the model): report it with the remaining findings and go on with the other lots. escalade … non jouée means the lot's budget did not cover it: the lot is yours, with its findings. Taking such a lot up (handed back for its budget or a non-compliant review, L370): fix it in its kept worktree (the final table gives the path; a fix subagent there, under cadence lead hold), then run raf review <lot> "conforme : …" in that worktree and commit its plan there — the review is read from the worktree's plan, not from the main repository's, and it must come after the last work commit of the lot —, then cadence orchestrate --resume --wave <wave> --integrate <project>:<lot>: the program rebases, replays the checks, keeps your verdict (or makes a short review of the rebased diff) and advances the repository's branch. The same command works while the wave is still running (L532): it drops the request in the wave's queue (intégration déposée), which takes it between two steps, so a long --continue wave does not hold the lot back. Do not integrate it by hand any more (L367, 26-10), and do not record that review in the main repository's plan: --integrate would not see it and would keep refusing (« pas rendu à l'étape d'intégration »). escalade … session escaladée sans résultat means the escalated session itself failed (often a model the account does not have): the model never judged the lot, fix the key or take the lot up, do not read it as the lot's fault. A line en cours is a lot still running; engagée, lot rendu avant le verdict du modèle is a lot withdrawn, failed by an error or stopped by an incident during the escalation: the model did not judge it, read the lot line for the reason. Without the key, nothing changes; the model has no default, as the account may not have the strongest one.
The threshold. Before every new wave, read the context of the lead session with cadence session context: the
cadence-hud mod publishes the context of each session, one file per session named after its id, and the command reads the
one named by $CLAUDE_CODE_SESSION_ID (Claude Code sets it in the environment of your Bash, so it is your own session,
whatever the folder; --session <id> overrides it). Without the variable it falls back to the folder only if a single
session publishes for it; two sessions in one folder make it exit 2 ("pass --session"), never guess the latest. It prints
ctx 42 % (84000/200000), the figure the ctx segment of the band shows, which the band publishes to
a file because it is only a rendering the model cannot see, then a second line, seuil 150000 tokens : sous le seuil or
… : atteint: the threshold is in tokens, not in %, because a percentage moves with the window (60 % is 120k on 200k and
600k on 1M). It is lead.contextThreshold in the cadence.yaml of the folder where the lead runs (150000 by default); read the
second line, do not recompute it. If the command fails (exit code 2: the band is not loaded in
this session, several sessions share the folder without the variable, or the figure is older than two minutes), treat it as
at the threshold: you cannot prove you are under it, and without the band loaded the lead does not chain.
When the second line says atteint (the context has reached the threshold), start nothing: at the threshold the lead runs session-close in each project touched, writes its
memory (filtered, as session-close says), and records three lines for next time with cadence session next — the wave
that was about to start comes first among them. While it says sous le seuil, chain. The lead says in one sentence which side of the threshold
it is on each time it chains or stops; it never waits for the figure to move (never a polling loop).
What stays with the human: the first choice and the order; the questions a session raised (the lead brings them
back at once and does not answer in the human's place); the UX reservations (by default raf ux is recorded on the human's
verdict and a UX reviewer's captures are looked at by the human; with lead.ux: lead only a doubt comes back to them, see below). While a question or a UX reservation is pending on a
lot, the chain goes on with the other lots and does not wait for it. A delivery that needs the human's confirmation
(their standing instructions, section 4) is a stop of the chain, not a bypass.
The UX verdict. By default (lead.ux: human, or no lead: key) the human gives the UX verdict of every visible lot.
Where the cadence.yaml of the parent folder says
lead:
ux: lead # lead | human — default human
the human has said they are not a UX judge and want to be asked only when in doubt (cadence lead tour prints
verdict UX : lead … as its last line when the setting is on, and cadence.yaml · ✗ erreur : lead.ux … for a value
other than lead or human). The lead then forms the verdict itself: it reads the ux-reviewer's report, looks at the
captures itself (it opens the images, it does not trust the report's words), and records raf ux <lot> "…" with the
reviewer's last line brought up to date. It does so only when the reviewer has no reservation left and the captures show
what the lot promised. At the slightest doubt — a reservation of the reviewer it cannot settle, a capture it cannot read,
a layout or wording choice that is a matter of taste, a state the captures do not show — it records nothing, brings the
captures and the question to the human, and the chain goes on with the other lots as for any UX reservation. The verdict
is recorded by the lead's own raf ux or, for a lot it hands over, by the livreur on the same criterion (it opens the captures itself and records nothing at the slightest doubt).
3. Check
A retour → geste : or rappel : line that the cadence plugin's hook adds to a Bash result is read before any other gesture: it is the exact command the program names for the refusal (docs/lead.md, « The retour → geste hook »).
- After an orchestrated wave the review is already done, by a fresh session: read the table, then go to
point 2. For a lot delegated by hand:
0b. For a lot delegated by hand,
raf checkor thedérivecolumn reportingdocumentation en retardis handled before the review: hand the lot to thedoc-keeperagent (a fresh subagent; the absolute path of the project and the lot id; it updates the documents, or only lists them if you say read-only). Read thedocs.articleskey of the project'scadence.yamlyourself and put its entries (repo,file, and the absolute path of that repository,repobeing relative to the project) in the brief, with read access to that repository for the subagent: the agent examines a document outside the repository only if the brief names it, and with no entry (the key is absent by default) you name none. A proposed lot it returns for a document outside the repository (docs.articles) is yours to decide: it never writes to that plan. Add a lineReport file: <absolute path>(outside the repository) to the brief: it answers in 15 lines at most and writes its full report there (L452); read the file only to apply a document it only listed. - The
code-revieweragent, as a fresh subagent (most capable model), reviews the lot. Give it the absolute path of the project and the lot id, not the author's report: it reads the diff itself from the commits that cite the lot, runs the checks, and returns real defects only, ranked, with what it could not verify and a one-line verdict. Add a lineReport file: <absolute path>in a temporary folder outside the repository (one file per lot and pass): the agent writes its full report there and answers you in 5 lines (verdict, blocking findings, follow-ups, the path). Read the file only when you need it: to act on a blocking finding, to hand a finding to a fix, or to bring the verdict line up to date forraf review. A short reply withBlocking: 0needs no read. - The lead re-verifies itself:
git logshows the commits, the test suite and build pass when run by the lead,raf checkis clean. During a wave, or in any tree that is not the lead's own, replay the gate at the lot's last sha withcadence verify --gate --sha <sha> [--project <dir>](exit 0 green, 1 red with the failing tests, 2 nothing to replay): a baregit worktree addhas nonode_modulesor.venvand reddens suites that only miss their dependencies; the gate runs in the main tree when it is clean at the sha and in a throwaway copy with copied dependencies otherwise, and theverify --gate …line of the output says which (aparité porte ↔ CIline, when the CI plays a test the gate does not, comes first). When the wave itself already ran the gate at that very sha on an identical tree (the usual case for a ready lot),verify --gatereads its recorded verdict instead of replaying the build and suite (~5 minutes saved per lot): that line then readsverdict repris de la porte de la vague …, and a replay says why on the line after (verdict rejoué : …: another sha after an integration, no record, a changed tree or command). A subagent is green on what it could test; say plainly what nobody could verify. - Fix or re-delegate what the review found; then record the verdict,
raf review <lot> "…"with the code reviewer's last line brought up to date (andraf ux <lot> "…"for a visible lot, with the UX reviewer's; withlead.ux: leadthe lead has formed that verdict, section 2c), thenraf done <lot>. Where the gate is on (raf review enable, the human's decision for each repository),raf donerefuses a lot that has commits and no verdict, or a verdict older than its latest commit: a fix made after the review means a new review of the lot, not an edited verdict. A read-only plan has no gate inraf(auxSinceorreviewSincewritten in it is ignored): the verdict goes into the project's own tool. On the cadence repository itself, therafandcadenceof thePATHare not the working repository'sdist/: they are a separate, detached copy (~/.local/share/cadence/service, built there), so nothing a session or a wave does in the working repository (npm run build,npm install,npm ci, uncommittedsrc/files) changes the code in service. Once the verdict is recorded and the lot accepted (raf done), the lead updates that copy withnpm run service -- <sha>, where<sha>is the accepted code, not HEAD when a handed-back lot is stacked above it (the wave's table says « livrable jusqu'à »). The script refuses a sha that is not an ancestor of HEAD, or whose commits cite a lot that is not done; it builds the new copy aside and switches only when the build succeeded. A lot found non-compliant is never put in service.
4. Delivery
One project at a time, by the lead or, for a ready lot it hands over, by the livreur agent (« Limits that always apply »): push, the
…(truncated)