orchestrating-work-end-to-end
UpdatedUse when a request will take more than one edit and nothing has decided yet how much process it needs — a feature, a bug with no known cause, a migration, an audit, a review, a production incident, a document someone will rely on; when several skills each cover one stretch of the work and nothing is sequencing them; when a run has to survive compaction, a handoff, or a fresh session picking it up mid-flight; when nobody will be there to answer a gate, or the change is small enough that the full ceremony would be a defect; or when it is unclear which phase the work is in, what would prove that phase finished, or which phase a new finding sends it back to. Covers routing a request to the lightest track that fits, naming the envelope the run executes in, the phase order each track runs, the evidence that opens each gate, what a gate becomes when its answerer is absent, one run record that outlives the context that wrote it, and where the rest of the library plugs in.
Overview
A library of skills is not a method. Each one is sharp about its own stretch of the work and silent about what comes before and after it, which is why an agent holding all of them can still run a build in the wrong order: implementing before anyone agreed what to build, reviewing a diff against criteria nobody wrote down, calling it done because the last thing tried finally worked. Every individual step looks defensible. The run is still wrong.
This skill is the spine those skills hang off. It answers five questions continuously — which track this work is on, what envelope the run executes in, which phase it is in, what has to be true before the next phase starts, and where that is written down — and it treats the answers as gates rather than as suggestions. The failure it exists to prevent is not chaos. It is a plausible-looking run that skipped a gate nobody noticed was there.
Track and envelope are two axes, not one. The track says what shape the work is; the envelope says what the run may assume about the world it executes in — who answers a gate, how much run this is worth, what a wrong turn costs, who else is writing. The spine's gates are written for one setting of that second axis, and that setting is right often enough to be dangerous.
When to use
- A request will take more than a single edit, and how much process it needs is still open.
- Several skills each cover one stretch of the work and nothing is putting them in order.
- Mid-flight, and which phase this is — or what would prove it finished — has gone fuzzy.
- The run has to survive compaction, a handoff, or a different session picking it up.
- A finding has just arrived that might belong to an earlier phase than the current one.
- Nobody will be there to answer a gate, or nobody has answered the last one.
- The change looks small enough that running the whole spine would itself be the defect.
- The conditions changed underneath a run that is already going.
- Not for: judging whether some specific skill applies to the response you are about to write.
using-tbaguetteowns that gate, it runs on every single turn, and it keeps running inside every phase of this one. - Not for: a genuine one-liner with a known cause and a test that already covers it. Fix it, prove it, say so.
Before the route: the library itself
Everything below this line gets decided by skills from one library, so the first question is not about the work. It is whether the copy of that library about to run the work is the published one. A whole spine executed against stale guidance is not a run with a version problem — it is a run orchestrated by decisions somebody already replaced, and nothing in the phase log will say so.
keeping-tbaguette-current owns the check, and usually it does not need running here. A harness that injects the library's start-of-session notice has already run it and attached the answer; read that answer rather than paying for the same network round trip twice. Where nothing is attached — a fresh harness, a session that began before the check existed, a run resumed from a transcript — run it now, before the track is named.
| Result | What the run does |
|---|---|
| Current | Nothing, and say nothing. Carry on to the route |
| Behind, updated cleanly | Record the new version on the run record's first line, then route — a skill changed underneath this run and that is worth being able to see later |
| Behind, could not update — local changes, no network, a conflict | Say so once, name what is stale, and route anyway |
That last row is the point: this gate reports, it does not block. A library that cannot be updated is worth knowing about and is not worth refusing to start a run over.
Then, immediately after it and still before the track is named, tending-tbaguette runs. The two are one loop seen from both ends: the currency check pulls the library's improvements in, and tending is what pushes this run's improvements back out. It goes here rather than at phase 8 because it has to be watching from the first turn — a correction generalizes at the moment it lands, and a watcher started once the work is finished has already missed everything worth catching.
| Its state | What the run does |
|---|---|
| Nothing queued | Nothing, and say nothing. It is now watching for the rest of the run |
| Candidates already queued | Contribute at the next natural lull — never mid-phase, and never without its own approval gate |
| A candidate lands mid-run | Two sentences into the queue file, then straight back into the open phase |
The third row of the table above and this one are the same fact seen twice. A library that could not update because the install carries local changes is a library with an uncontributed change sitting inside it, and tending-tbaguette owns getting that change out of the working tree and into a pull request — where the licence, and everyone else running these skills, needs it to go.
Route before you run
Say the track out loud before the first action, the way scoping-before-building requires the size to be said out loud — a track chosen silently is a track nobody can correct.
digraph track_selection {
"What does this request want?" [shape=diamond];
"Harm happening right now?" [shape=diamond];
"Cause known?" [shape=diamond];
"Deliverable is an answer,\nnot a change?" [shape=diamond];
"A document someone\nwill read later?" [shape=diamond];
"Build" [shape=box];
"Respond" [shape=box];
"Diagnose" [shape=box];
"Investigate" [shape=box];
"Author" [shape=box];
"Review" [shape=box];
"Change in place" [shape=box];
"What does this request want?" -> "Build" [label="something that\ndoes not exist yet"];
"What does this request want?" -> "Harm happening right now?" [label="something is\nbehaving wrong"];
"Harm happening right now?" -> "Respond" [label="yes — users, data,\nor money exposed"];
"Harm happening right now?" -> "Cause known?" [label="no"];
"Cause known?" -> "Build" [label="yes — it is a\nchange now"];
"Cause known?" -> "Diagnose" [label="no"];
"What does this request want?" -> "Review" [label="a judgment on work\nsomeone else wrote"];
"What does this request want?" -> "Deliverable is an answer,\nnot a change?" [label="a question about\nwhat is already there"];
"Deliverable is an answer,\nnot a change?" -> "A document someone\nwill read later?" [label="yes"];
"A document someone\nwill read later?" -> "Author" [label="yes"];
"A document someone\nwill read later?" -> "Investigate" [label="no"];
"Deliverable is an answer,\nnot a change?" -> "Build" [label="no — it became\na change"];
"What does this request want?" -> "Change in place" [label="move, upgrade, or remove\nsomething already live"];
}
| Track | The request | Runs |
|---|---|---|
| Build | Something that does not exist yet, or behavior nobody has signed off on changing | The full spine below |
| Diagnose | Something is wrong and the cause is not known | Reproduce, locate, fix, pin — then rejoins Build at review |
| Respond | Something is broken now, with a clock and an audience | Declare, assess, preserve, mitigate, stabilize — then hands back to Diagnose |
| Investigate | A question, an audit, a feasibility check; the deliverable is an answer, not a diff | Orient, gather, conclude, report — no branch to land |
| Review | A judgment on work you did not write; the deliverable is findings someone else acts on | Orient, cover, judge, deliver — no branch of your own to land |
| Author | The deliverable is a document people will read long after this run | Frame the reader, gather, draft, verify, land |
| Change in place | An upgrade, a migration, a deletion, a live-system operation | Reversibility first, then the specific skill — then rejoins Build at prove |
Two rules govern the choice, both inherited from scoping-before-building because a track and a size are the same kind of judgment: torn between two tracks, take the heavier one, and the classification only moves one way. A Diagnose run that turns out to need a new subsystem becomes a Build run and picks up the design gate it skipped. Nothing downgrades mid-run, however trivial the remainder looks in hindsight.
Then name the envelope
The track is only half the route. Every gate below is answered by someone, at some size, against something that can or cannot be undone, in a tree that may have another writer in it — and the spine is written for exactly one setting of those: a human replying within a turn or two, a change worth eight phases, a mistake that can be walked back, one writer. Each of those is load-bearing on a gate, none of them is stated, and a default that is usually right is a default nobody notices being wrong.
Read all five dials, say them out loud alongside the track, and put them on the run record's first line. reference/envelopes.md has how to read each one, what each changes, and which combinations carry a rule that no single dial carries alone.
| Dial | Values | Decides |
|---|---|---|
| Presence | paired · async · autonomous · unattended | Who answers a gate |
| Amplitude | express · standard · campaign | How much run the work is worth |
| Blast radius | sandbox · repo · live | What a wrong turn costs |
| Crew | solo · fanned · shared tree | Who else is writing to this tree, driving a shared instrument, or holding the same request |
| Register | trimmed · clipped · telegraphic | What the run spends reading it and saying it |
Four settings route somewhere specific, before the first action rather than after:
autonomousorunattended→bounding-autonomous-work. Every gate that was a question becomes a written self-answer carrying a stop condition, and the door bound stands in every envelope.express→ reference/express.md. Four beats rather than eight, behind entry conditions that get checked rather than hoped.campaign→checkpointing-long-runs. The record stops being scaffolding and becomes the run's only memory.- any register →
crouton. It binds what the run pulls in, not only what it writes, and that is the half with the money in it: every turn re-sends the conversation, so a file read costs roughly three times its own size. Enough of it to act on without opening that skill — read the range rather than the file, outline anything long before opening it, cap what a command can hand back (| head,--stat,-q), never re-read what is already in context, and say the background once. Read here, because by phase 8 every read has already been paid for.
Amplitude obeys the same rule as the track and for the same reason: it only ratchets up. Express promotes to standard the instant an entry condition turns out false; standard promotes to campaign the instant the context holding the run gets close to full. Nothing demotes on your own judgment, because the judgment that says "this got smaller" is made by the part of the run that most wants to be finished.
And set the register in the same breath
The track says which phases run and the envelope says who answers their gates. Neither says what the run spends getting there, and the spine's unstated default is the most expensive setting available: pull the whole file, narrate the call, restate the background, close each phase with a summary of what the reader just watched happen. A Build run charges that eight times, and every track reusing the spine charges it again.
Register is read here, beside the other four, rather than at phase 8 when the report is written and every read has already been paid for. crouton's own ordering is the reason: prose is the smallest of the four spends it names, and the three above it — whole files pulled into context, tool calls fired on a guess, background re-pasted each phase — are the ones that multiply by phase count. Tightening the closing summary while re-reading the same file at every boundary changes the run's accent, not its cost.
Three things here sit outside it, per that skill's own gate, and shortening any of them is a defect rather than a saving: the run record — ledger, phase log, rulings — and every artifact phase 8 lands, because both are read by someone who was not here; and any warning before something irreversible, which the door bound already requires in full. Compress the run, never the record, and never the warning.
A gate whose answerer is missing is substituted, not skipped
This is the single most common way an unsupervised run goes wrong, and it never looks like a shortcut at the time. A question gets asked, nothing answers it, and the run continues — having quietly settled the question itself, without recording that it did. Six hours of competent work then rest on an answer nobody chose.
bounding-autonomous-work owns the substitutions in full. The shape of all of them: the gate keeps its job and changes its mechanism. An approval becomes a written design carrying the approach that lost, a reversibility bound, and a stop condition that fires if it turns out wrong. A clarifying question becomes an answer taken from the code, or a ruling naming the reading that lost — never a fact. A second pair of eyes becomes red-teaming-your-own-work and karen-and-the-manager run as hard gates rather than as a courtesy.
One gate has no substitute in any envelope: an irreversible action gets a human. An autonomous run may prepare it completely and may not take it. Reaching that point is not the run failing — it is the run ending correctly, with one step left for someone who can own it.
The build spine
Each phase names what lets you in, who owns it, and the evidence that opens the next gate. The evidence column is the point: a phase ends when something outside your own confidence says it did.
| # | Phase | Enter when | Owner skill | Gate — what opens the next phase |
|---|---|---|---|---|
| 1 | Frame | The request has arrived | scoping-before-building, finishing-what-you-started | Track and envelope said out loud; the acceptance ledger exists as a file, each line derived from the request's own words and watched failing once |
| 2 | Design | The work is understood well enough to propose a shape | clairvoyance, then scoping-before-building | An explicit yes from your human partner. Architectural work has a written spec; bounded work has a few sentences in chat. The gate itself never shrinks — with nobody there to say yes it is substituted, per bounding-autonomous-work, not skipped |
| 3 | Isolate | The design is approved | isolating-work-with-worktrees | Work is off the shared trunk, and the test suite was run once, before any change, so the baseline is measured rather than assumed |
| 4 | Plan | An approved design exists and the work is more than a couple of tasks | structuring-an-implementation-plan | Every task bite-sized, individually verifiable, no placeholders, - [ ] on each |
| 5 | Implement | A plan exists, or the change is small enough not to need one | delegating-tasks-with-review-gates, working-a-plan-task-by-task, fanning-out-independent-work | Every task closed with its own verification actually run — writing-the-failing-test-first governs the order inside each task |
| 6 | Review | Every task is closed | handing-off-for-review, reviewing-code-deeply, verifying-review-feedback | Every finding fixed, refuted with a reason, or parked with a ruling. None dropped in silence |
| 7 | Prove | The tree is believed finished | confirming-before-claiming-done, finishing-what-you-started | Every acceptance line carries evidence measured now, not recalled. Surrendered lines are marked surrendered, not deleted. Findings parked at phase 6 are triaged here, not inherited in silence |
| 8 | Land | The proof holds | landing-a-finished-branch, atomic-commits, writing-commit-messages, offering-the-next-move | The branch is where it belongs, the workspace is cleaned up, anything left undone is named to whoever owns it next, and the run closes by offering the next move as a choice rather than describing it in a paragraph |
Phases 6 and 7 are separate on purpose, and collapsing them is the most common way a run ends badly. Review asks whether the work is any good. Prove asks whether the thing that was actually asked for is actually there. A clean review of the wrong deliverable passes phase 6 every time.
Phase 2's owner column gained a skill in front of it, and the order is the point. Everything in this spine executes the request; nothing in it asks whether the request is the right one, and the frame that decides that arrives in the first message and is never named again. clairvoyance is the one move that looks outward instead of forward, and the frame-to-design boundary is where it is nearly free — a reframe costs a paragraph there, the plan at phase 4, and the implementation at phase 6, which is why a brilliant reframe at review is usually declined and should be. It has a seat in every track below, different in each and twice a prohibition. What it produces is sight, never work: every observation routes back to a gate, into the ledger, into the record for offering-the-next-move, or to a discard with a reason — and managing-scope-drift still governs everything it makes you want to do.
The other tracks reuse this spine rather than replacing it:
- Diagnose keeps phases 1 and 3 — a bug still gets a ledger and still gets off the trunk — and runs reproduce → locate → fix → pin in place of phases 2, 4, and 5, under
diagnosing-before-fixing. It rejoins at phase 6. Its gate before any fix is a reproduction that fails on demand; its gate after is a regression test that failed before the fix and passes after (regression-test-from-bug). When the hypothesis list empties or a third fix does not hold,clairvoyanceruns on the reproduction rather than on the patch: three correct fixes that did not hold are one wrong model applied three times, not three bad patches. - Respond is the one track that does not open with a ledger — there is no request to derive one from. Its equivalent is the impact statement: who is affected, how badly, and whether it is growing, written in user terms, and the first gate is that the harm stopped rather than that it is understood.
responding-to-incidentsowns declare → assess → preserve → mitigate → stabilize, and inverts the usual order deliberately: mitigate before you diagnose. The moment users are safe it hands back to Diagnose, which picks up the spine normally. Its close-out iswriting-postmortems, and skipping that because the cause turned out obvious in hindsight is how the same incident returns next quarter.clairvoyancehas a seat here and it is a late one — never during mitigation, where a frame question is the "let me understand this properly first" red flag exactly, but at stabilize, on what the crude mitigation has now committed you to, and again in the postmortem, on whether an incident of this shape has been here before under another name. - Investigate runs orient → gather → conclude → report. It reaches phase 8 only if it produced an artifact that has to land — a doc, an ADR, a spec. Its close-out gate is
calibrating-confidence: every claim in the report marked verified, inferred, or assumed, with the unknowns named rather than smoothed over. Before the conclusion is written,clairvoyanceasks whether the question commissioned is the question that matters — and both get answered, the second marked as inference, because substituting it for the first is not a reframe but a failure to answer. - Review runs orient → cover → judge → deliver, under
handing-off-for-reviewandreviewing-code-deeply. Its gate is coverage of the diff, not confidence in a conclusion: every changed file actually seen, and what is absent from the change weighed alongside what is in it —clairvoyance's absence pass is how that second half gets found, since a diff cannot announce the caller nobody updated or the state nobody modelled. It ends at delivery rather than at landing, because the branch belongs to whoever wrote it, andverifying-review-feedbackgoverns the return leg when the findings come back argued. - Author runs frame the reader → gather → draft → verify → land. The phase that gets skipped is verify, every time: a document's claims are checked against the thing they describe, the same way code's are, rather than against the memory of it.
writing-durable-docsdecides what will still be true in a year,explaining-technical-worksets the altitude, and the specific form —writing-adrs,writing-release-notes,writing-postmortems— owns the shape.clairvoyanceruns twice here, at frame the reader and again before verify: who else reads this, and what this document makes impossible to say later. - Change in place opens with
clairvoyanceand thendeciding-reversibility— in that order, because reversibility is a question about a chosen operation and asking it first quietly accepts that the operation is the right one, when the cheapest migration is the one that does not happen because the thing can be deleted. A one-way door is then a different piece of work from a two-way one. It runs its own skill from the routing reference, and rejoins at phase 6. An upgrade or a migration is reviewed like any other diff; arriving with no new code of its own is not a reason to skip the seat.
When there is no repository
Phases 3 and 8 name git — a worktree to isolate in, a branch to land. Plenty of real work has neither: operations against a live system, reverse engineering, data analysis, research, an incident on infrastructure nobody version-controls. The phases still apply. Only their instruments change.
Isolate means the change cannot reach the thing you would be sorry to break, and a worktree is one implementation of that. Off-repo it is a copy, a snapshot, a scratch database, a staging host, an exported archive — whatever makes the original recoverable. The other half of that gate travels unchanged, and is the half more often dropped: measure the baseline before touching anything. Where there is no suite, the baseline is whatever measurement the change is meant to move. Without one, "it is better now" has nothing to be better than.
Land means the artifact reached its durable home and the next person can find it — the report filed where someone will look, the configuration in the place that survives a rebuild, the finding written into the record rather than left in a transcript that scrolls. The cleanup half is unchanged too: the scratch copy removed or deliberately kept, and anything unfinished named to whoever owns it next.
The failure this exists to prevent is the plausible one. A run reads two phases it cannot enter, concludes the spine is for somebody else's kind of work, and abandons the track entirely — rather than entering those phases and skipping them with a logged reason, which is what the phase log is for. A phase with no counterpart is skipped and recorded. It is never a reason to drop the track.
The floor: what survives every envelope
Six things do not scale down. Not with amplitude, not with presence, not with how obviously correct the work is. An envelope that cannot afford one of these owes a cheaper mechanism for it, never a shrug — the same way a sixteen-color terminal still owes the contrast guarantee.
- The track and the envelope are said out loud before the first action, and both land on the record. A route chosen silently is a route nobody can correct.
- Something outside your own confidence closes the run. A person, or a command whose output you read. Re-reading the diff is not proof of anything except that you read it.
- What would prove this done is written down before the work, in the request's own words, and backed by a check that was watched failing once. Express gets one line; a campaign gets many; Respond writes an impact statement instead, because there is no request to quote. Zero is not an amplitude.
- A one-way door gets a human. No envelope, no confidence level, and no deadline converts this into a self-answer.
- What was not done is named to whoever owns it next. Silence is not a report, and it reads as completeness to everyone who was not there.
- The record is written when the thing happens. A record assembled at the end was written by whatever survived, which is exactly the memory it existed to guard against.
Pull in the specialists
The spine names one owner per phase. It is not the only skill that phase needs, and treating it as the whole answer is how a library this size gets used like a library of eight.
At each phase boundary, check what the content of this work calls for, not just its stage: an API in the design phase pulls designing-apis and drawing-boundaries; anything parsing input someone else controls pulls handling-untrusted-input and threat-modeling before implementation rather than after review; a slow endpoint pulls performance-profiling before anyone optimizes anything. reference/phase-routing.md indexes every skill in the library against the phase where it earns its place, so the check is a lookup rather than a memory exercise. Consult the phase you are entering, not the whole file.
Three of those pulls are load-bearing enough to name here. Before phase 1 on any inherited or unfamiliar work, recovering-agent-context and orienting-in-unfamiliar-code come first — a run framed against a codebase you have not looked at frames the wrong thing. Between phase 1 and phase 2, clairvoyance, which is the only pull in the library that questions the request rather than serving it, and the only one whose value collapses if it is deferred. And after phase 7 believes it is finished, red-teaming-your-own-work and then karen-and-the-manager are this library's standard adversarial close, most warranted exactly when the ordinary review came back clean.
One run record, from frame to land
Conversation memory does not survive compaction; a file does. Keep one record for the whole run, in the same file the acceptance ledger already lives in — finishing-what-you-started owns that ledger's contents and its LEDGER.md default, and a second file competing with it is two accounts of progress that will disagree by phase 5.
Add four things to it that the acceptance ledger alone does not carry:
Track: build | diagnose | respond | investigate | review | author | change-in-place
Envelope: presence=paired | amplitude=standard | radius=repo | crew=solo | register=trimmed
Phase: <name> — entered <when>, gate: <what will prove it>
## Phase log (append only; never rewrite a line)
- frame: complete — 6 acceptance lines, all watched failing
- design: complete — approved in chat 14:20; spec at docs/specs/foo.md
- isolate: skipped — already on a feature branch, baseline green (48/48)
- plan: complete — docs/plans/foo.md, 7 tasks
- implement: task 3/7 complete (a1b2c3d..d4e5f6a, review clean)
## Rulings (every decision that could be questioned later)
- task 2: reviewer flagged the retry cap as magic; plan mandates 5 — plan governs, recorded
## Stop conditions (autonomous and unattended runs; written before the work)
- budget: three failed attempts at one green test
- surprise: anything outside src/api/ or its tests
- door: any push, deploy, or write to real data
- drift: any edit to an acceptance line
Four rules make it worth keeping. Append, never rewrite — a rewritten log is a log that agrees with whatever you now believe. Every skipped phase gets a line saying why, because that is what makes a skip a decision instead of an omission. Every ruling gets a line, because a finding dropped with nothing written down resurfaces later with no memory of why it was let go. And every envelope change gets a line, because a run whose conditions moved silently is running a process nobody chose.
After a compaction, the record and git log outrank your own recollection, and it is not close. A controller that trusts its memory re-dispatches work that is already committed — the single most expensive mistake this loop can make, and the one it is most confident about while making it. checkpointing-long-runs owns what goes into the record, when, and in what order of value; its headline is that the cheap half gets written and the expensive half — the dead ends — gets lost.
The artifacts that outlive the run
The run record is scaffolding. A run also produces things meant to be read long after the branch is gone, and the two get confused in one specific direction: the durable artifact is maintained like scaffolding — written once, never revisited — while the scaffolding is kept like an artifact, sitting in the repo for a year because nobody decided it was finished.
| Artifact | Written at | Lifespan | Owner skill |
|---|---|---|---|
| Spec — what is being built and why this shape | Phase 2, before the yes | Outlives the branch | scoping-before-building writes it, writing-durable-docs decides what keeps |
| Plan — the tasks, in order | Phase 4 | Dies when its last box is ticked | structuring-an-implementation-plan |
| ADR — one decision, its forces, and what would reopen it | Whenever a decision gets made that a later reader will have to re-judge | Longest-lived thing here | writing-adrs |
| Run record / ledger | Phase 1, appended throughout | Dies with the run | finishing-what-you-started |
Three rules, and each exists because its absence has a recognisable symptom.
One location, stated once. "Where is the spec for X" must have an answer that does not depend on who wrote it. Pick whichever directory the repository already uses and put it there; the failure worth checking for first is a repository that uses two, since design documents split across a served directory and an internal one accumulate by whichever the author happened to know about, and the honest answer to the question becomes "look in both". A phase-log line naming the path is what makes the artifact findable from the run that produced it; a spec nobody can locate was written for nobody.
The artifact changes when the decision does. Routing backward to phase 2 means the spec is now describing an approach that lost, and leaving it is worse than never having written it: the next reader gets a confident description of the wrong design, with no marker saying so. Update it in the same move that reopens the phase, and say what changed rather than silently overwriting — the rejected approach and the reason it was rejected are the parts writing-adrs says a future reader most needs, and the parts most often deleted as obsolete.
Decide what happens to the scaffolding at phase 8. The plan and the run record have done their job the moment the work lands. Deliberately delete them, or deliberately keep them and say why; what is not allowed is leaving them because nobody looked. A repository accumulating half-ticked plans from finished work is one where nobody can tell an abandoned run from a completed one, which is exactly the question recovering-agent-context will be asking six months from now.
Whichever way that goes, one thing precedes it. The record's surrendered lines and its rulings are what offering-the-next-move harvests the run's closing choice from, so the offer gets assembled while the record still exists. Tear it down first and that choice is reconstructed from memory, which reliably yields the obvious next step and nothing that was actually learned.
Resume before you restart
Work arriving mid-flight gets the record read before anything else happens: the ledger file, the plan's checkboxes, git log on the branch. recovering-agent-context covers the wider sweep — other sessions, other agents, other tools that touched this repo and paid for dead ends you would otherwise pay for again.
Resuming means entering at the first phase whose gate is not yet met, not at the first phase. A run whose plan is written and whose tasks 1-3 are committed resumes at task 4, not at design. And a phase log whose last line is a task mid-fix-loop resumes inside that loop, not at the top of the task.
Resume the envelope too, and do not inherit it. The dials that were true when the record was written may not be true now — the human who was answering has gone, the tree has acquired a second writer, the small change is now a campaign. Re-read all four before entering the phase, the same way the track gets re-read.
When a gate fails, route backward
A failed gate is information about which phase was wrong, and it is almost never the one currently open.
| What the failure says | Where it goes back to |
|---|---|
| A task cannot be implemented as written | Phase 4 — the plan, not the implementer |
| Review finds the approach wrong, not the code | Phase 2 — the design, the yes it was given under, and the spec that still describes the approach that lost |
| Proof finds an acceptance line nothing satisfies | Phase 4 or 5, depending on whether the plan omitted it or the work did |
| A finding indicts an already-closed task | The task that owns it, surfaced by name, with what has been built on top of it since |
| The request itself changed | Phase 1, and the ledger changes visibly rather than quietly |
Pushing forward through a failed gate is the failure mode this whole skill exists against. It always looks cheaper in the moment, because the cost lands on whichever phase is unlucky enough to be open when the problem finally becomes undeniable.
When the envelope changes mid-run
The track rarely moves. The envelope moves constantly, usually without anyone noticing, and every one of these is a decision that belongs on the record.
| What you notice | The dial that moved | What the run does |
|---|---|---|
| The replies have stopped | presence: paired → async | Batch the open questions into one message; continue on everything that does not depend on the answers, park what does |
| You are about to answer your own question | presence: async → autonomous | Stop here. bounding-autonomous-work first — the substitutions and the stop conditions get written now, not at the end |
| The small change reached a second subsystem | amplitude: express → standard | Pick up the gates express skipped, design gate first |
| The context is filling and the work is not close to done | amplitude: standard → campaign | Write the record now, while the memory writing it is still good |
| The next command pushes, deploys, sends, or writes real data | radius: → live | Re-read reversibility before that command, not after it |
| The diff shows files you never opened | crew: solo → shared tree | Nothing destructive, nothing stashed, nothing reset. Stage by hunk and re-read before writing |
| A device, profile, or box the run needs has a foreground you did not start | crew: solo → shared tree | Do not take it. Use the next-best evidence and name it on the deliverable; ask for the instrument when you actually need it |
| A peer session is working the same request | crew: solo → shared tree | Settle one owner by message before building further; the other reviews or stands down, and only one build reaches the target |
| The owner sets, tightens, lifts, or replaces a run-wide bound — a pause until told to continue, a cap on parallel agents, a spending ceiling | none of the five: a bound set from outside that all five now run inside | Append it to the rulings: the value, who set it, when, and what lifts it. Older lines stay as written; the new one names which it replaces. Say which running work it touches. If the owner meant it for sibling sessions too, tell each of them in the message that acknowledges it |
| Users started being affected while you investigated | track: diagnose → respond | The only upward track move that is urgent rather than procedural. Declare it out loud, then responding-to-incidents |
A pause is lifted by what it names, not by the clock. A pause set while a quota is exhausted ends when the owner says so, unless the ruling names another condition; the quota resetting is a fact about the quota, and a run that resumes at the reset has swapped its own condition for the owner's. The first line written on resuming says which ruling it resumed under. The newest ruling is the whole bound: a run still honouring a replaced one, or missing the newest, is working to a rule nobody holds.
Commands
Invoked directly, this skill takes a verb. With none, it runs as the spine: route, name the envelope, and enter at the first phase whose gate is not yet met.
| Command | Does |
|---|---|
route [request] | Name the track and the five dials, and stop there. Useful before committing to a run, and as a second opinion on one already going |
resume | Read the record, the plan's boxes, and git log, then enter at the first gate not yet met — never at the first phase |
gate | Name the evidence that would open the phase currently blocking, and say plainly whether it exists yet |
record | Write or refresh the run record — track, envelope, phase log, rulings, stop conditions — from what is actually on disk rather than from memory |
handoff | Produce the brief a successor needs to take the next action without reading the run, per checkpointing-long-runs |
abort | Stop cleanly: tree recoverable, record current, and a report naming what fired, what was done, and what remains |
What this skill does not decide
It sequences; it does not overrule. The owner skill for a phase governs how that phase runs, and where the two appear to disagree, the owner wins — this file is a map, not a second opinion about territory it does not cover.
Two boundaries in particular. using-tbaguette still governs every individual turn, including turns inside a phase this skill opened. And nothing here licenses skipping the approval gate at phase 2: an orchestrated run that never got a yes is a faster way to build the wrong thing, not a substitute for asking.
Your human partner can move the track or the envelope in either direction, including down — they own the scope, and "just make the edit, skip the ceremony" is an instruction, not a rationalization to argue with. You cannot. A downgrade you chose yourself is the doubt talking; a downgrade they asked for is a decision, and it goes in the record as one, named and attributed, so the run still says what process it actually ran.
Refuse
Category defaults, not bans. Any of these can be right in a specific run — but reaching for one when the axis was free means you were performing process rather than routing.
- A plan document for a change with two tasks.
- A clarifying question you could have answered by reading one file.
pairedmakes questions cheap, not free. - An acceptance line that restates the request instead of naming what would prove it.
- A worktree for a run that was never going to leave the branch it is already on.
- A subagent fan-out for work that is two edits in one file.
- A design gate performed at a partner who already said "just do it" — they moved the amplitude down, and re-asking is not rigor.
- A phase log written at the end, from memory, in one pass.
- A track named after the first three edits, describing what already happened.
- Narrating the phases to a reader who wanted the finding.
- Ceremony offered as evidence. "I ran the full spine" is not a claim about the work.
Common mistakes
| Symptom | Real cause |
|---|---|
| A perfect implementation of something nobody asked for | Phase 2 approved a design the ledger at phase 1 was never checked against |
| The run is "basically done" for three more hours | Phases 6 and 7 collapsed into each other; the review passed, so the proof was assumed |
| A second session redoes committed work | No run record, or a record trusted less than the context that had already lost the thread |
| Every phase ran, on a two-line change | Amplitude never read. standard was taken as the default rather than as a judgment, and express was available |
| A question was asked into a silence and then answered by the asker | Presence never read. The gate had no answerer, so it was skipped rather than substituted |
| A careful six-hour run that was reckless in its final command | Blast radius read once at the start, when nothing was irreversible yet |
| An unsupervised run finished confidently and built the wrong thing | No stop condition named drift, so the ledger got edited to match the build |
| A production outage worked from the top of the Diagnose track | Wrong track: Respond mitigates before it reproduces, and every minute spent reproducing was spent on users |
| Two agents' work landed and one of them silently vanished | Crew read as solo because the tree happened to look quiet when it was read |
| A phase was skipped and nobody can say why | Skipped silently instead of recorded as skipped with a reason |
| A finding from phase 6 gets fixed inside phase 5's task | Routed forward into whatever was open instead of backward to the phase that owns it |
| The spine named an owner and nothing else in the library came up | The owner skill was treated as the phase's whole answer rather than its first move |
| The plan's checkboxes are all empty at task six | Progress lived in context rather than in the record; a compaction now costs the whole run |
Red flags
- "I know what they want, I'll design it as I build it."
- "The review was clean, so it must be what they asked for."
- "I'll write the acceptance criteria once I see how it turns out."
- "This phase is basically done, I'll start the next one while it finishes."
- "The ledger is overhead, I'm holding it all fine" — said by a context that is about to be compacted.
- "It's faster to fix this myself than to send it back to the phase that owns it."
- "We're past that phase now" — offered as a reason not to go back to it.
- "Nobody's around, so I'll use my judgment" — said instead of writing the judgment down.
- "It's technically irreversible, but it's obviously fine."
- "This is small, I'll skip the ledger" — the floor is one line, not zero.
- "I'll promote it to a real run if it turns out bigger" — said for the fourth time.
- "Let me understand this properly first" — with users currently broken.
Reference
The track says what shape the work is. The envelope says what the run may assume about the world it executes in. Both get read at the same moment and neither substitutes for the other: an autonomous express run in a sandbox and an autonomous campaign against live data share a track and nothing else.
Read all five dials before the first action, and write them on the run record's first line. Each has a default that is right often enough to be dangerous — a default that is usually right is a default nobody notices being wrong.
Contents
- Presence — who answers a gate
- Amplitude — how much run this is worth
- Blast radius — what a wrong turn costs
- Crew — who else is writing
- Register — what the run spends
- Reading the five together
- Failure modes
Presence — who answers a gate
| Value | You know it by | What it does to the run |
|---|---|---|
| paired | The human answered the last thing you said, within a turn or two | Gates are asked, one question at a time. Questions are cheap here and nowhere else |
| async | A human exists and answers in hours — a review comment, a ticket, a chat that goes quiet overnight | Gates batch into one message; the run continues on everything that does not depend on the answer, and parks what does |
| autonomous | The run will finish before anyone reads a word of it — a delegated task, a plan handed over whole, a goal with a leash | Every gate that was a question becomes a written self-answer carrying a stop condition. See bounding-autonomous-work |
| unattended | Nobody is reading the output live at all — a hook, a cron, a loop, a CI step | Autonomous, plus: the run must be idempotent, must leave a trail a stranger can act on, and must not depend on state it did not itself create |
The line between async and autonomous is not how long the wait is. It is whether the answer arrives before this run ends. A question that will be answered tomorrow is async if the run can park and wait, and autonomous if the run must finish tonight — the same question, two different pieces of work.
Presence is the dial that changes underneath you. A paired run becomes async the moment the replies stop, and async becomes autonomous the moment you decide to finish rather than wait. Both transitions are decisions and both belong on the record; see the envelope-change table in SKILL.md.
Amplitude — how much run this is worth
| Value | The work | The run |
|---|---|---|
| express | The target is already known, the change fits one reviewable diff, and a test either exists or can be written in the same breath | Four beats, not eight. See express.md |
| standard | A feature, a bug, a migration — days at most, one context window at a time | The spine as written |
| campaign | The work outlives the context that started it: many sessions, many hands, or a plan long enough that nobody holds it | The spine, plus checkpoint discipline and a record that is the only memory. See checkpointing-long-runs |
Amplitude only ratchets up. Express promotes to standard the instant an entry condition turns out false; standard promotes to campaign the instant the context that holds the run gets close to full. Nothing demotes, however small the remainder looks in hindsight — the reason is the same one the track rule gives: the judgment that says "this got smaller" is made by the part of the run that most wants to be finished.
The exception, and it is the only one: your human partner can demote. "Just make the edit, skip the ceremony" is an instruction. It goes on the record named and attributed, so the run still says what process it actually ran.
Blast radius — what a wrong turn costs
| Value | Where the work lands | Gate it adds |
|---|---|---|
| sandbox | A throwaway worktree, a scratch branch, a local database, a dry run | None. This is what isolation is for — spend the freedom |
| repo | Commits, branches, a pull request. Everything is recoverable by someone with the history | Nothing lands without its own verification actually run |
| live | A deploy, a migration against real data, an outbound message, a published artifact, a rotated credential, a package release | deciding-reversibility before the action, not after. One-way doors get a human — in every envelope, including autonomous ones |
Blast radius is a property of the action, not of the run. A run that has been sandbox for six phases becomes live at the single step that pushes, and it is exactly then — one command from the end, with everything green — that the check gets skipped. Radius is re-read before every irreversible action, not once at the start.
Two undercountings are worth naming because both feel like repo and are not: a push to a branch that something deploys from, and any write to a checkout another agent or person is also holding.
Crew — who else is writing
| Value | Situation | What it changes |
|---|---|---|
| solo | You are the only writer in this tree | Nothing |
| fanned | You dispatched subagents that write in parallel | fanning-out-independent-work owns the split; every task's boundary is a file boundary, and the merge is yours, not theirs |
| shared tree | Another agent, another session, or a person is editing the same checkout | Never stash, never reset, never assume the tree you read is the tree you are about to commit. Stage by hunk, re-read before writing, and prefer a worktree of your own |
The tell for shared tree that gets missed most: a diff far larger than the work you did. A checkout that suddenly reports changes across files you never opened is not a broken tool, it is a second writer, and the next destructive git command is about to cost someone else their afternoon.
Read shared tree for an instrument the run shares rather than a tree, too — a test device, a browser profile, a serial port, a staging box, a terminal session, anything with one foreground. Reachable, connected, unlocked — whatever the checklist's preconditions are — say the run is permitted to use it and nothing about whether it is free; what settles that is one read-only look at what is in front, and a second look to see whether it moved without you. A foreground the run did not start, or one that changed between the two looks, is another run's state, and launching on top of it breaks that run and captures a surface nobody was testing. Do not take it: drop to the next-best evidence and say so on the deliverable, and ask for the instrument when the run actually needs it. For a UI surface, formidable's elevate reference names the rungs — running it, a recording, a still, a description.
Read shared tree for a peer holding the same request, too, even when no file is shared. A requester can hand one request to two sessions without saying so — sent twice, retried in a fresh window, given to a second agent to compare. When each works in a checkout of its own, both read solo, and two whole builds of one request diverge wherever it left a choice open: the storage shape, the names on the wire. Nothing in either tree shows the other, so the first place they meet is often the live target both were told to deploy to, where whichever deploys second strands the first's data and clients, at the step that is hardest to take back. Where the harness can list peer sessions, read what each is working on at the route, and again before the first live step, since a peer can start after you did. Settle a match by message, to the peer or the requester, before design: one owner, and the other session reviews or stands down while its work is still a plan. If the requester wanted both builds to compare, the same message settles that neither deploys until one is chosen. This is the exchange landing-a-finished-branch has before landing, made hours earlier, when it saves a build instead of choosing which one to throw away. Where peers cannot be listed and someone can answer, ask the requester whether anyone else has this request: one line, and owed whenever the radius is live.
Register — what the run spends
Set once, at the route, and held for the whole run. crouton owns it; this names the setting so it lands on the record with the other four instead of being rediscovered at every phase boundary.
| Value | Read it as | What it changes |
|---|---|---|
| trimmed | Full grammar, preamble and closing recaps gone | The default. Anything read once and carefully, or quoted later |
| clipped | Fragments and dropped articles, facts still joined into sentences | Someone is watching the run live and can ask a follow-up cheaply |
| telegraphic | One line per fact, nothing joining them | Status during a long run; findings a reader will scan and pick from |
The value names the prose, but the dial binds the larger half: ranges rather than whole files, grep and sed -n over cat, no re-read to confirm an edit that already reported success, background said once. That half is where a multi-phase run's tokens actually go, and it does not vary with the value — every turn re-sends the conversation, so content pulled in costs around three times its own size, against low single digits of a run for the prose.
Three things never move with this dial, per crouton's own gate: the run record, every artifact the run lands, and any warning before something irreversible. Compress the run, never the record, and never the warning.
Reading the five together
Some combinations carry a rule that neither dial carries alone.
| Combination | The rule it creates |
|---|---|
| autonomous × live | The strictest cell on the board. The run may prepare the irreversible action in full and may not take it. It stops, leaves the command written down, and reports |
| autonomous × express | Legal and common — this is most delegated small work. The floor still applies: the change is still proven by something run, not by reading it |
| unattended × anything | The report is the entire deliverable. Nobody will ask a follow-up question, so nothing may be left implicit |
| campaign × shared tree | The record is contended too. One writer owns it, appends only, and every other writer adds rather than edits |
| unattended × telegraphic | Not a combination — a contradiction. Unattended means the report is the deliverable and nothing may be left implicit; the tightest register is the one setting that guarantees something will be. Compress the run, not the handover |
| express × campaign | Not a combination — a contradiction. Something has been misread; re-derive the amplitude before continuing |
Failure modes
| Symptom | Real cause |
|---|---|
| A question asked into a silence, then answered by you anyway, unrecorded | Presence read as paired when it was autonomous; the substitution bounding-autonomous-work owns never happened |
| An eight-phase run on a one-line change | Amplitude never read; standard taken as the default rather than as a judgment |
| The run was careful for hours and reckless in its last command | Blast radius read once at the start instead of before the irreversible step |
| Two agents' work landed and one of them silently lost | Crew read as solo because the tree looked quiet at the moment it was read |
| A scripted pass drove another session's app off a shared device | Crew read from permission — connected, unlocked — instead of from occupancy: what was in front, and whether it moved between two looks |
| Two complete builds of one request, with incompatible schemas, met for the first time at the deploy | Crew read from the checkout alone; a peer holding the same request in a tree of its own never shows in yours |
| Every phase re-read a file the run already had | Register never read, so only the closing prose was ever tightened and the reads — the larger spend — were not |
| An express run that ran for a day | Promotion refused because the work was "nearly done" — which it was, four times |
| A perfect report nobody could act on | unattended treated as autonomous: written for a reader who could ask a follow-up question, to a channel where nobody can |
Eight phases on a two-line change is a defect, not diligence. It burns the budget that the next real decision needed, and it teaches everyone watching that the process is theater — which is how the gates get skipped on the change that actually needed them.
Express is the answer to that, and it is a different process, not an absent one. Four beats, each with a gate that something outside your own confidence closes. The floor is lower than the spine's. It is not zero, and the reason is the same one that governs a sixteen-color terminal: a tight envelope still owes the guarantee, just by a cheaper mechanism.
Entry conditions — all of them, or it is not express
Check these before the first edit, not after. Any one false and the run is standard.
- The target is already known. You can name the file and the change. No diagnosis is pending, no design is open, no "let me look around first."
- It fits one reviewable diff. One logical change, in one place, that a reviewer holds in their head at once.
- Proof is already available or one line away. A test covers this, or a test can be written in the same breath as the change, or a command exists whose output settles it.
- The blast radius is
sandboxorrepo. Nothing live, nothing irreversible, nothing that leaves the machine. - Nothing about it is new. No new dependency, no new interface, no new category of input, no new file that other code will have to know about.
Condition 5 catches the case the other four miss: a genuinely tiny change that introduces a decision the rest of the codebase inherits. A three-line function with a new public name is not express work — naming-things and designing-apis both have a seat, and the change is small only in characters.
The four beats
| # | Beat | What it is | Gate |
|---|---|---|---|
| 1 | Frame | One line: what will be true when this is done, in the requester's terms | The line is written down and does not merely restate the request. If it cannot be written in one line, this is not express |
| 2 | Change | The edit, with its test — writing-the-failing-test-first still governs the order | The test was watched failing for the right reason before the change existed |
| 3 | Prove | Run the thing that settles it, now, fresh | The command ran, its output was read, and the frame line is true. Not "it should work" |
| 4 | Land | Commit with a message that says why, and say what was done | atomic-commits if the tree grew more than one change; writing-commit-messages for the message |
No design gate, no plan, no isolation, no separate review phase. Each of those was skipped for a reason recorded by the entry conditions, and that is what makes it a decision rather than an omission.
The floor express still owes
These do not scale down. They are the same non-negotiables the spine carries, and their cost at this size is seconds.
- The frame line exists before the edit. Written, not held.
- The register is still named. Express is a smaller run, not a licence to re-read a file it already has.
croutonbinds the reads here exactly as it does in the full spine. - Something outside your own confidence closes it. A run command, a test, a build. Reading the diff again is not proof.
- A one-way door still gets a human. Express does not change the door bound; see
bounding-autonomous-work. - What you did not do is named. "Fixed the off-by-one; the same pattern appears in two other callers and I left them" is a complete report. "Fixed" is not.
Promotion, and why it only goes one way
The moment any entry condition turns out false, the run is standard from that point — pick up the gates express skipped, starting with the design gate if condition 1 or 5 is what broke.
| What you notice | Promote because |
|---|---|
| The change needs a second file to make sense | Condition 2 is false; there is a shape decision here |
| The test is hard to write | Condition 3 is false, and difficulty writing it is usually the design talking |
| "While I'm in here…" | Condition 2 is false. This is scope drift with an alibi — managing-scope-drift |
| The fix does not hold and you are on the second attempt | Condition 1 was false: the target was not actually known. This is a diagnose run |
| It touches config, a credential, a migration, or a deploy | Condition 4 is false, and it was probably false from the start |
Promotion is not a penalty and not an admission. It is the mechanism working: express is a bet that the work is small, and the bet is designed to be cheap to lose. What is not allowed is the reverse — a standard run quietly finishing as an express one because the remainder started to look small. That judgment is made by the part of the run that most wants to be done.
Failure modes
| Symptom | Real cause |
|---|---|
| A one-line fix that broke something else | Beat 3 skipped: the diff was read instead of the suite being run |
| An express run that lasted all afternoon | A condition went false hours ago and promotion was refused four times |
| A tiny change that a reviewer could not follow | Condition 5: it introduced a name or an interface, and nothing decided either |
| The commit says "fix" | Beat 4 treated as a formality rather than as the beat where why gets recorded |
| The requester asked for something adjacent and got exactly the literal thing | The frame line restated the request instead of naming what would be true after |
| Everything is express | The conditions are being read as a description of the hope rather than as a test |
The spine in SKILL.md names one owner per phase. This file names everything else — every skill in the library, indexed against the phase where it earns its place, so checking "what else does this phase call for" is a lookup rather than a memory exercise.
Read the section for the phase you are entering, and the track sections when picking a track. Reading it end to end is only worth doing once, to learn its shape.
A skill appearing under two phases is not a mistake. judging-duplication decides a design question and catches a review finding, and the reason to reach for it differs each time. What matters is the "reach for it when" column, not the placement.
Contents
- Before the run — the library itself
- Before the run — naming the envelope
- Before phase 1 — arriving cold
- Phase 1 — Frame
- Phase 2 — Design
- Phase 3 — Isolate
- Phase 4 — Plan
- Phase 5 — Implement
- Inside phase 5 — when implementation stalls
- Phase 6 — Review
- Phase 7 — Prove
- Phase 8 — Land
- Diagnose track
- Respond track
- Review track
- Author track
- Investigate track
- Change-in-place track
- Outside the spine
Before the run — the library itself
Ahead of orienting, ahead of framing, ahead of naming the track.
| Skill | Reach for it when |
|---|---|
keeping-tbaguette-current | Always — first, before anything else. Usually already answered by the start-of-session check, in which case read that answer instead of re-fetching. Reports and moves on; never blocks the run |
tending-tbaguette | Always — immediately after the currency check, and then continuously for the rest of the run. It is the outbound half of the same loop: what this run learns that generalizes goes back upstream as a pull request rather than staying in one install. Capture never interrupts a phase; contributing waits for a lull and for its approval gate |
Before the run — naming the envelope
The track is half the route. These are pulled by the other half — the dials in reference/envelopes.md — and each is read before the first action, not once the run is already in trouble.
| Skill | Reach for it when |
|---|---|
bounding-autonomous-work | Presence is autonomous or unattended — nobody will answer a gate before the run ends. Also the moment a question has been asked into a silence and the run is about to continue anyway |
designing-verifiable-goals | Presence is autonomous or unattended and the run is handed a goal to iterate toward rather than a plan: a loop, "until it passes", "until it is twice as fast". Build the check it will measure itself against before it starts, beside the stop conditions |
checkpointing-long-runs | Amplitude is campaign — the work will outlive the context holding it. Also the moment a compaction becomes plausible in a run that started as standard |
deciding-reversibility | Blast radius is live, or is about to become live at one specific command |
isolating-work-with-worktrees | Crew is shared tree, or the run wants a radius of sandbox it does not currently have |
fanning-out-independent-work | Crew is fanned — the split has to be by file boundary and the merge is yours |
crouton | Always — the fifth dial. It sets the register the run's reads and its reports both hold, and it is read here rather than at the report, when every read has already been paid for |
Before phase 1 — arriving cold
| Skill | Reach for it when |
|---|---|
recovering-agent-context | Anything here was touched by a prior session or another agent — their dead ends are already paid for |
checkpointing-long-runs | What you leave behind will be somebody's cold arrival — read it before framing, and start writing it from the first phase |
orienting-in-unfamiliar-code | Nobody present wrote this code and the request assumes you know where things are |
code-archaeology | The current shape only makes sense as the result of decisions nobody wrote down |
reading-specifications | A ticket, RFC, or standard is the input, and it has to become testable requirements before it can be framed |
routing-around-capability-gaps | The work needs something this model or harness cannot do; find that out before promising the run, not during it |
clairvoyance (orbit) | The work is inherited or the project unfamiliar, and orientation has just said what the code is — one bounded pass on what the project is, before the first request is framed inside it |
Phase 1 — Frame
| Skill | Reach for it when |
|---|---|
scoping-before-building | Always — it classifies the request and says the size out loud |
finishing-what-you-started | Always — the acceptance ledger is this phase's deliverable, written before the work, each line watched failing |
reading-specifications | The request's own words contain MUST/SHOULD, or edge cases it never addresses |
managing-scope-drift | The request is already growing between restatements |
estimating-effort | Someone needs a range before committing, and a point estimate would be false precision |
deciding-reversibility | The work has a one-way door in it — the framing changes if a mistake cannot be walked back |
steelmanning-alternatives | The first idea arrived with the request and nothing else has been considered |
clairvoyance | On the way out of this phase, always. The ledger you just wrote is a list of the request's own mechanisms, and this is the last moment before one of them becomes the design |
Phase 2 — Design
| Skill | Reach for it when |
|---|---|
clairvoyance | First, before an approach is proposed. It is the only skill here that questions the request rather than serving it, and a reframe costs a paragraph now, the plan at phase 4, and the implementation at phase 6. Its imagine pass sits here too, after the sweep: at most five candidates, each with the check that would test it, for steelmanning-alternatives to work on |
scoping-before-building | Always — this phase is its sectioned-design gate, ending in an explicit yes |
steelmanning-alternatives | A single approach is about to be presented as the approach |
deciding-reversibility | Choosing how much design rigor this decision actually deserves |
revalidating-decisions | An existing decision constrains this one, and its premises may have expired |
writing-durable-docs | The design is being written down rather than said — this phase's gate depends on that document being readable months later, not just today |
writing-adrs | A choice made here will look wrong to a competent newcomer, or has already been argued twice |
reading-specifications | A spec, ticket or standard is the input to this design rather than its output |
Shape and structure
| Skill | Reach for it when |
|---|---|
designing-apis | The change adds or alters an interface other code will depend on |
drawing-boundaries | Deciding what belongs in which module, or whether to split at all |
modeling-errors | Failure modes need classifying before a mechanism gets picked for them |
modeling-state-machines | Booleans are multiplying and illegal combinations are becoming representable |
choosing-concurrency-model | Anything concurrent — pick by workload shape, before code |
designing-for-idempotency | Anything that can be delivered, retried, or replayed more than once |
caching-strategy | Latency is being bought with correctness, and invalidation needs a plan |
rate-limiting-and-backpressure | The system can be given more work than it can do |
schema-evolution | A contract already in production has to change |
configuration-management | Deciding what is config, what is code, and what is a secret |
instrumenting-for-observability | Choosing what to emit — done at design time or not at all |
tracking-data-provenance | Values arrive observed, imported, inferred, or defaulted, and downstream will not be able to tell |
building-llm-features | The design calls a language model at runtime — the model pin, the outcomes beyond success and error, what its output may reach, and the budget are all decided here |
Security, decided here or not at all
| Skill | Reach for it when |
|---|---|
threat-modeling | The design has an attacker in it, and the model has to fit in a design review |
least-privilege-design | Deciding what this component is allowed to reach |
handling-untrusted-input | Anything parses input someone else controls — a design-phase concern, not a review-phase one |
Where it goes and what it is called
| Skill | Reach for it when |
|---|---|
mapping-dependencies | The blast radius of the change is not yet known |
finding-the-seam | Several places could hold the change and one of them is much cheaper |
judging-duplication | The design either repeats something or couples two things to avoid repeating it |
keeping-copies-in-sync | The design records a fact in a second place, and something other than memory has to keep the two agreeing |
naming-things | The design introduces vocabulary the rest of the work will inherit |
formidable | Anything with a user interface, on any stack |
writing-adrs | The decision is one a future reader will need to re-judge against its premises |
Phase 3 — Isolate
| Skill | Reach for it when |
|---|---|
isolating-work-with-worktrees | Always — including to decide the isolation is not worth its cost |
reproducible-environments | The baseline suite fails and it is not clear whether that is the code or the machine |
designing-ci-pipelines | The work changes what runs on every commit, or the baseline takes long enough to matter |
feature-flagging | The change will land before it is meant to be reachable |
Phase 4 — Plan
| Skill | Reach for it when |
|---|---|
structuring-an-implementation-plan | Always — bite-sized tasks, exact paths, no placeholders |
choosing-test-scope | Deciding which level each task's verification belongs at |
designing-test-data | Tasks need fixtures or builders, and the plan should say which |
fanning-out-independent-work | Two or more tasks are genuinely independent and could run at once |
incremental-migration | The plan's shape is expand–migrate–contract rather than a sequence of features |
estimating-effort | The task breakdown is about to imply a schedule |
automating-repetition | The same manual sequence appears in three or more tasks |
Phase 5 — Implement
| Skill | Reach for it when |
|---|---|
delegating-tasks-with-review-gates | A fresh subagent per task, gated by a two-stage review — the default for a multi-task plan |
working-a-plan-task-by-task | The plan runs inline in this session, no subagent per task |
fanning-out-independent-work | Tasks that truly do not touch each other, dispatched at once |
writing-the-failing-test-first | Always, inside every task that changes behavior |
designing-test-data | Building the inputs those tests run on |
grounding-test-doubles | A test double stands in for something real and could drift from it |
testing-the-untestable | Time, randomness, network, filesystem, identifiers, or concurrency are in the way |
property-based-testing | The behavior has invariants worth generating cases against |
evaluating-llm-output | The task changes a prompt, a model, a retrieval step, or a tool definition, and the failing eval case gets written before the change |
characterization-testing | Existing behavior has to be pinned before it can safely change |
auditing-new-input-categories | The change teaches the system a new category of input, not another instance of an old one |
validating-numeric-input | Numbers cross a boundary — NaN, infinity, overflow, and locale all defeat naive comparison |
handling-untrusted-input | Implementing the parse boundary the design placed |
secrets-hygiene | A key, token, or credential is anywhere near the diff |
redacting-sensitive-output | Logs, errors, or reports could carry data that must not appear in them |
naming-things | Every identifier the task introduces |
refactoring-safely | Behavior must be preserved exactly while structure changes |
judging-duplication | The third occurrence of something has just appeared |
keeping-copies-in-sync | The task changes a value that is also recorded somewhere else, and the other copy is the one nobody will be looking at |
finding-the-seam | The obvious insertion point turns out to be the expensive one |
configuration-management | New knobs, defaults, or environment-dependent values appear |
feature-flagging | The task lands behind a flag |
formidable | The task touches any user-facing surface |
portable-shell-scripting | The task writes shell that has to run somewhere other than this machine |
atomic-commits | The task's tree has grown more than one logical change |
resolving-merge-conflicts | The branch has diverged from its base far enough to need integrating mid-run |
automating-repetition | The same edit is being repeated by hand across many files |
checkpointing-long-runs | The task list is longer than the context holding it, or a compaction happened mid-task |
bounding-autonomous-work | The tasks are being executed with nobody available to answer what they raise |
crouton | Always — this is the phase where reads dominate: ranges over whole files, and no re-read to confirm an edit that already reported success |
Inside phase 5 — when implementation stalls
| Skill | Reach for it when |
|---|---|
diagnosing-before-fixing | Anything is failing and the cause is not known — before any fix is attempted |
reading-stack-traces | There is a trace, and which frame actually identifies the defect is not obvious |
reproducing-bugs | The failure is not yet available on demand |
bisecting-failures | It worked at some point and the change that broke it is unknown |
debugging-concurrency | The failure moves when you look at it |
finding-resource-leaks | Something grows over time rather than failing outright |
performance-profiling | Something is slow and the hot path is being guessed at |
flaky-test-triage | A test fails intermittently and retrying is being mistaken for a fix |
tracing-data-flow | A wrong value arrives somewhere and its origin is unclear |
mapping-dependencies | The fix's blast radius is larger than the file it lives in |
Phase 6 — Review
| Skill | Reach for it when |
|---|---|
handing-off-for-review | Always — composing what the reviewer needs before it is asked for |
reviewing-code-deeply | Reviewing it yourself, in priority order, including what is absent |
verifying-review-feedback | Feedback has arrived and each item needs verifying before it is acted on |
red-teaming-your-own-work | Nothing looks wrong, and nothing has been tried to make it look wrong |
karen-and-the-manager | The review came back clean — which is exactly when this is most warranted |
auditing-dependencies | The diff added, bumped, or replaced a third-party package |
secrets-hygiene | Before anything is published, as a scan of what the diff actually contains |
judging-duplication | The review found repetition and it needs deciding, not just noting |
keeping-copies-in-sync | The diff changes one copy of a fact that lives in several places and leaves the others as they were |
calibrating-confidence | Findings are being reported with more certainty than the evidence supports |
Phase 7 — Prove
| Skill | Reach for it when |
|---|---|
confirming-before-claiming-done | Always — name the command that would prove it, run it fresh, read what it printed |
finishing-what-you-started | Always — every ledger line re-measured now, surrenders marked, nothing quietly narrowed |
regression-test-from-bug | The work fixed a defect; the test that failed before it must pass after it |
choosing-test-scope | The proof runs at a level that cannot actually observe the claim |
evaluating-llm-output | The claim is about output a model produces — proven as a rate on the feature's evals, with its uncertainty, not by one green run |
flaky-test-triage | The suite is green only sometimes, and that is being read as green |
red-teaming-your-own-work | A last adversarial pass before anyone acts on this |
karen-and-the-manager | The finishing pass, right before knowing-when-to-stop bounds it |
knowing-when-to-stop | The findings are shrinking and the next pass would be polish |
calibrating-confidence | Marking what is verified against what is still inferred in the final report |
Phase 8 — Land
| Skill | Reach for it when |
|---|---|
landing-a-finished-branch | Always — merge, PR, or leave it, plus worktree and branch cleanup |
atomic-commits | History should be bisectable by whoever comes next |
writing-commit-messages | Every commit that lands |
resolving-merge-conflicts | The base moved while the work was in flight |
writing-release-notes | Someone downstream has to decide whether to take this |
writing-adrs | A decision made during the run should outlive the branch |
writing-durable-docs | Behavior changed in a way the existing docs now describe wrongly |
writing-agent-instructions | A lesson from the run is about to be added to the repository's instruction file — only if it passes that file's test, and only if no tool could enforce it instead |
explaining-technical-work | Reporting the run to whoever asked for it |
crouton | The report has to fit somewhere small without losing what decides things |
deleting-code | The old path a migration replaced is now genuinely dead |
feature-flagging | A flag introduced during the run now needs a removal date |
knowing-when-to-stop | Naming what is deliberately left undone, rather than drifting into it |
offering-the-next-move | Always — the last beat: the run closes with the next move offered as a choice, not described |
clairvoyance | Before the record is torn down, restricted to ahead and beside. Its rulings and surrendered lines are what the closing offer is harvested from; reconstructed from memory afterwards it yields the obvious next step and nothing that was learned |
Diagnose track
| Skill | Reach for it when |
|---|---|
diagnosing-before-fixing | Always — this track's owner, from symptom to actual origin |
reproducing-bugs | The gate before any fix: a failure available on demand |
reading-stack-traces | A trace exists and may be pointing at the wrong frame |
bisecting-failures | Binary search over commits, inputs, configs, or versions |
debugging-concurrency | Races, deadlocks, and bugs that vanish under observation |
finding-resource-leaks | Degradation over time rather than a clean failure |
performance-profiling | The complaint is slowness, with no measured baseline yet |
flaky-test-triage | The symptom is intermittent and the cause taxonomy has to be worked |
tracing-data-flow | Following one wrong value back to where it was born |
observing-production-safely | The only reproduction is live, and diagnosis must not become the incident |
regression-test-from-bug | The gate after the fix: named for the defect, failing before, passing after |
writing-postmortems | The failure reached users, or would have |
crouton | The register the hunt holds: log and trace excerpts scoped to the failing case, rather than whole files pulled in fresh per hypothesis |
clairvoyance | The hypothesis list is empty, or a third fix did not hold. The assumption is in the reproduction, not in the patch |
Respond track
Something is broken now. This track inverts the Diagnose order on purpose: mitigate first, understand second. Everything here runs against a clock.
| Skill | Reach for it when |
|---|---|
responding-to-incidents | Always — this track's owner, from declaring it out loud to handing back |
observing-production-safely | Any look at the live system, which is most of this track. An investigation that becomes a second incident is its own category |
deciding-reversibility | Every mitigation is ranked by how easily it comes back out, not by how right it is |
feature-flagging | The fastest reversible mitigation available, when one exists |
instrumenting-for-observability | The incident cannot be assessed because nothing emits what would answer the question |
redacting-sensitive-output | The timeline, the logs, and the status updates are about to be shared more widely than usual |
diagnosing-before-fixing | The handback: users are safe, so this is now an ordinary defect |
regression-test-from-bug | What turns "we rolled back" into "this cannot happen again" |
writing-postmortems | Always — including when the cause turned out obvious in hindsight |
explaining-technical-work | Every status update during, and the summary after |
crouton | The register those status updates hold — never the warning before a mitigation that cannot be walked back, which stays full prose |
clairvoyance | At stabilize and in the postmortem — never during mitigation, where a frame question is the "let me understand this properly first" red flag exactly |
Review track
You did not write this. The deliverable is findings someone else will act on, and the gate is coverage of the diff rather than confidence in a conclusion.
| Skill | Reach for it when |
|---|---|
reviewing-code-deeply | Always — in priority order, including what is absent from the change |
handing-off-for-review | Read backwards: it says what a reviewer needs, which is what to ask for when it was not supplied |
verifying-review-feedback | The return leg — findings came back argued, and each needs verifying before it is conceded or held |
orienting-in-unfamiliar-code | The diff is in code nobody present wrote, and the change cannot be judged without the shape around it |
mapping-dependencies | The diff's blast radius is larger than the files it touches |
auditing-dependencies | The change added, bumped, or replaced a third-party package |
secrets-hygiene | Always, as a scan of what the diff actually contains |
handling-untrusted-input | The diff parses anything from outside its own trust boundary |
judging-duplication | The review found repetition and it needs deciding rather than noting |
keeping-copies-in-sync | The diff changes one copy of a fact recorded in several places; the copies it left alone are exactly what a diff cannot show |
calibrating-confidence | Findings are being reported with more certainty than the reading behind them supports |
red-teaming-your-own-work | The review came back clean and nothing was tried to make it look otherwise |
explaining-technical-work | Delivering the findings to someone who has to act on them |
crouton | Findings compressed to what decides them, with every path, symbol, and quoted error left byte-exact |
offering-the-next-move | Always — the review closes with the choice it implies |
clairvoyance | During coverage, before judgment. The absence pass: the caller nobody updated, the state nobody handled, the migration nobody wrote |
Author track
The deliverable is a document. Its verify phase is the one that gets skipped: a document's claims are checked against the thing they describe, not against the memory of it.
| Skill | Reach for it when |
|---|---|
writing-durable-docs | Always — it decides what will still be true in a year and what should never have been written down |
explaining-technical-work | Always — the altitude is set by what the reader will do next |
writing-adrs | The document is one decision, its forces, and what would reopen it |
writing-agent-instructions | The reader is an agent — an instruction file, a rules file, a skill — and every line is paid for on every turn |
writing-release-notes | Someone downstream has to decide whether to take this |
writing-postmortems | The document is about a failure, and blame would make it useless |
crouton | The document has a length budget it is about to lose to completeness |
reading-specifications | A spec, standard, or ticket is the source, and the document must not quietly change what it requires |
code-archaeology | The document explains why, and the why is in the history rather than in anyone's memory |
calibrating-confidence | Claims are going in that are inferred, and the reader will treat every sentence as verified |
naming-things | The document introduces vocabulary the codebase will inherit from it |
confirming-before-claiming-done | The verify phase: every command, path, and count in the document run and read now |
offering-the-next-move | Always — the document lands with the choice it implies |
clairvoyance | At frame the reader, and again before verify — who else reads this, and what it makes impossible to say later |
Investigate track
| Skill | Reach for it when |
|---|---|
orienting-in-unfamiliar-code | The question is about code nobody present wrote |
recovering-agent-context | Prior sessions already explored this and their findings are recoverable |
mapping-dependencies | The question is about coupling, layering, or blast radius |
tracing-data-flow | The question follows a value from source to sink |
code-archaeology | The question is why, and the answer is in the history |
reading-specifications | The question is what a spec actually requires |
auditing-dependencies | The question is about code that ships without having been reviewed |
estimating-effort | The deliverable is a range, and precision would be false |
revalidating-decisions | The question is whether an old decision still holds |
calibrating-confidence | Always — the close-out gate: verified, inferred, or assumed, marked per claim |
explaining-technical-work | Always — conclusion first, altitude set by what the reader will do next |
crouton | The answer has a length budget |
offering-the-next-move | Always — the report closes with the choice it implies, assembled rather than left to the reader |
clairvoyance | After gathering, before the conclusion. The question commissioned may not be the question that matters; answer both and mark the second as inference |
Change-in-place track
| Skill | Reach for it when |
|---|---|
deciding-reversibility | Always — the opening gate; a one-way door is a different job |
upgrading-dependencies | Versions have fallen behind, or an advisory names something in use |
incremental-migration | Anything big enough that a big-bang cutover is being considered |
data-migrations | Data has to be backfilled, batched, resumable, and verified |
schema-evolution | A live contract changes shape |
deleting-code | Something appears unused and has to be proven dead first |
refactoring-safely | Structure changes while behavior must not |
characterization-testing | Legacy behavior needs pinning before it moves |
feature-flagging | The cutover needs a switch and a way back |
observing-production-safely | The change is being watched live |
configuration-management | The change is a config or environment change wearing a code change's clothes |
secrets-hygiene | A credential is being rotated, revoked, or moved |
reproducible-environments | The change only reproduces on one machine |
auditing-dependencies | The upgrade pulls transitive changes nobody asked for |
resolving-merge-conflicts | A long-lived branch has to be integrated as part of the change |
crouton | The register a long mechanical sweep holds — never the reversibility warning, which stays full prose |
clairvoyance | Before deciding-reversibility, not after. The cheapest migration is the one that does not happen because the thing can be deleted |
Outside the spine
These do not belong to a phase. They govern the run itself, or the library.
| Skill | Reach for it when |
|---|---|
using-tbaguette | Every turn, in every phase — the per-response skill check this file does not replace |
routing-around-capability-gaps | Any phase where the harness or model cannot do what the phase needs |
crouton | Any phase whose output has a length budget |
calibrating-confidence | Any phase reporting something as known that is inferred |
knowing-when-to-stop | Any phase whose returns have started shrinking |
managing-scope-drift | Any phase where the work is quietly widening or narrowing |
writing-postmortems | The run itself failed in a way worth learning from |
bounding-autonomous-work | Any phase entered with nobody available to answer its gate |
checkpointing-long-runs | Any phase whose progress would be lost if the context ended here |