Plan orchestration

The unattended loop that runs the steps of every open plan, or of the one plan named, one after another, until a pause of every plan it runs or until none has an unblocked step left; a stop blocks only its own step. It leaves behind each landed step on main, its landing report in its plan's ledger, and a state file per plan that says where that plan stands. Under self_rule: on and next_entry: on, the orchestrator goes on after a closing to the next roadmap entry (references/self-rule.md, "Next-entry mode").

Quick start

/plan-orchestration                  run the steps of every open plan unattended until a pause of every open plan, or until no open plan has an unblocked step; with no plan open, under self_rule: on and next_entry: on, take the next roadmap entry
/plan-orchestration <entry>          the same for the plan of that entry alone
/plan-orchestration <entry> inline   the same, with the orchestrating session building every code step itself
continue the plan                    the same as /plan-orchestration with no entry, resuming from the state files after a compaction or in another session

Use instead

What it reads

1. .agents/plan.yaml and the ledger folder of each plan the invocation runs: every project specific comes from them.
   • /plan-orchestration with no entry and continue the plan run every open plan.
   • /plan-orchestration <entry> runs that plan alone.
   • An open plan is a folder under <ledger_root>/ (in the projects: form, under a project's ledger_root), outside <archive_root>/, whose plan.md opens with # Plan: <entry>.
     • A folder without such a plan.md is no plan.
2. The state file orchestrator-state.md of each of those plans first, then its plan.md, then the tail of the transcript when there is one: the reading order after any compaction, and for a new orchestrator.
3. The dispatch block in the state file of every open plan, which "Resuming, and handing the plan over" reads.
4. The builder's report, the diff since the step's base, and the refuter reports of the step.
5. For the recurring-findings pass of a plan, the refuter reports of that plan written since its last pass.
6. Under self_rule: on, and for the review of a choice, the choices file <ledger_root>/choices.md.
7. Under self_rule: on and next_entry: on, after a closing: the roadmap file and the ledger folders under <ledger_root>/ and <archive_root>/, for the next entry and its plan.

Steps

The loop runs over the plans that /plan opened. Each step goes through the same skills a person runs by hand (/spec, /refute, /land, with /ordo-help printing the sequence); this skill adds what running unattended needs: picking the next step, dispatching and resuming a builder, sending a reviewer's findings back, the cadence of the review, two steps in flight, the stops and the reports.

1. Read the inputs in the order "What it reads" gives them.
   • Read the dispatch block of every open plan and resolve those of the plans the invocation runs before anything else, as "Resuming, and handing the plan over" says.
   • Before any dispatch, check that the runner lists the effort agents each plan the run runs names in its configuration block, ordo-<worker_effort> and ordo-<reviewer_effort>, among its agent types, each level high when that block has no such key.
   • Before any dispatch, check that CLAUDE_CODE_EFFORT_LEVEL is unset: printenv CLAUDE_CODE_EFFORT_LEVEL exits 1.
   • Either check failing is the refusal "The configured effort cannot apply" ("Stops"), and the loop dispatches nothing.
2. Pick the next step that nothing blocks, for each free slot under the limit of "Two steps in flight".
   • Each free slot takes the next unblocked step of the earliest plan in the roadmap's order that has one.
     • In the projects: form, the projects stand in the order .agents/plan.yaml lists them, and each project's plans in its roadmap's order.
   • Each pair of the picked step with the steps in flight is judged under "Two steps in flight".
   • A step that waits because its shared file is not simple to merge is blocked, and the slot goes to the next pick.
   • A step that must run alone ("Two steps in flight"), when it is the next pick, holds the loop: no further step is dispatched until nothing else is in flight and it has been dispatched.
   • The closing step is the last step of a plan, which /plan writes itself.
     • It runs without /spec and without a dispatch entry.
     • It takes no slot under the limit.
     • It starts only when every other step of its plan has landed.
     • It makes its commits outside any landing.
     • Another step marked "orchestrator, no agent" is not a closing step and is not covered by these bullets.
   • /plan-orchestration <entry> picks from that plan alone.
   • With no open plan, /plan-orchestration with no entry and continue the plan take the next roadmap entry under self_rule: on and next_entry: on, as references/self-rule.md, "Next-entry mode", says.
     • Otherwise they say that no plan is open and name /plan <entry>.
   • Done when a step is picked for each free slot, or none of the plans the invocation runs has an unblocked step.
3. Invoke /spec <entry> <step>, which writes the step's dispatch entry at the end of its preflight, checks the premises, writes the brief, runs for a full step the brief check before the preparation commit (the spec skill's "Steps / The brief check"), makes the worktree and fills the dispatch entry.
   • Before dispatching the builder of a full step, read the brief check's report and the changes to the brief its "Closed" heading names.
   • A stop it raises goes to the user by "Stops".
     • Under self_rule: on, the orchestrator closes it instead, as references/self-rule.md, "Closing an open item", says, unless it is of a kind its "The six kinds left open" names.
   • A stop, here or at any later step, blocks its own step.
     • The loop moves on to the next unblocked step.
   • Its refusal of a step without its authority (the spec skill's Steps 1) is raised as a stop of the kind "A finding that is the user's", since a step enters the plan only as "What earns a step of its own" says.
   • Done when /spec has written the brief and filled the dispatch entry and, for a full step, the brief check's report is read, or the step has stopped.
4. Choose the step's executor.
   • Write it into the dispatch block.
   • Then build by that choice.
   • Choice. academic-paper for a step whose deliverable is manuscript content, always; otherwise what the invocation named (/plan-orchestration <entry> inline runs every code step inline); else the configuration block's executor:, which is agent by default and inline when the plan chose it.
   • agent. Dispatch one builder with the worktree path and the brief, by the recipe under "Launching a builder".
     • The moment it is launched, write its agent id into the dispatch block under session_id.
   • The launch commit. Under every executor, the dispatch entry is committed once its builder's identity is in it, and the commit is a resume point.
     • Under agent it comes right after the launch and the model check of "Launching a builder", since the builder's agent id exists only once it is launched.
     • Under inline and academic-paper it comes before the build starts.
     • The commit is made in the form "Resuming, and handing the plan over" states, with the state file and the session's own records of the step's plan since the last resume point.
       • The brief and the brief-check report of a /spec waiting on its brief check are not among those records (the spec skill's "Steps / The brief check" 1).
   • The prompt. It states, in its own words:
     • The worktree, and that it is the only place to work.
     • That the builder runs no git command that changes state (no add, commit, stash, checkout, mv, restore), that reading with git status, git diff and git show is fine, and that a file is moved with mv.
     • What is never touched: the ledger beyond the builder's report, the main checkout, the user's data.
     • The reading order: the rules file, the brief, the standards, the ADRs the brief names.
     • Every requirement the step is judged on.
     • That a shortcut is a finding, a narrower reading of an item and work inside the step called outside it among them, and that such work is done or handed back with the reason before the report.
     • That a sentence the brief or a round gives word for word about how a script behaves is run before it is written, and one the run shows false is left unwritten and handed back with the run.
     • That the builder runs the checks the brief names for the files the step changes, and that the lines they print are what the report quotes.
     • The report path and shape.
   • The builder. It runs no git command that changes state (no add, commit, stash, checkout, mv, restore); reading with git status, git diff and git show is fine; it moves a file with mv.
     • In the ledger it writes only its report, at the path the brief names in the worktree's copy of the ledger.
   • inline. The orchestrating session writes inline as the builder's identity under session_id.
     • It makes the launch commit.
     • It then builds the step itself in the worktree under the brief and the rules file.
     • Steps 5 and 8 read "the builder" as itself.
   • academic-paper. The session writes academic-paper as the builder's identity under session_id.
     • It makes the launch commit.
     • The step is then built through that skill with the brief as its input.
     • That skill's output is the step's report.
5. While the builder runs, or a /spec waits on its brief check, do ledger work and the skills of other steps: the next step's premise checks, the bookings, and /spec, /refute and /land for other steps, as "Two steps in flight" says.
   • Never dispatch beyond the limit "Two steps in flight" states.
   • Never dispatch a step of a plan a pause holds ("Stops").
6. On the report, save it into the main ledger at the dispatch block's report path, on disk and not committed on its own.
   • Then read the whole diff.
   • The orchestrator copies the report from where Steps 4 ("The builder") says the builder writes it.
   • When the builder wrote no report file, the orchestrator takes the report from the final message its completion notification carries, into the report path.
   • The saved report is checked with the character-set check before it is read.
     • A character outside the set is written in place by its name in angle brackets, such as <tab> or <em dash>.
   • The orchestrator writes the builder's tokens, tool uses and time, from its completion notice, into the dispatch entry under builder_usage, beside report, on disk.
   • The next resume-point commit of its plan carries them.
   • The report is a lead, not a fact.
   • A builder whose first run of the brief's "Cases" finds a case the brief's rules get wrong stops before changing any code and hands back the first run and that case, with the rule and the result.
     • Read that hand-back the same way as a report.
   • Rule on such a case when the fix stays inside the step's part.
     • Write the ruling into the ledger as the round-0 ruling file agents/briefs/<step>-cases.md.
     • Hold the text the ruling gives the builder word for word as Steps 8's "Dictated text" says, before it is committed.
     • Commit it as a round sent, in the form "Resuming, and handing the plan over" states.
     • Copy that file into the worktree's copy of the ledger at the same path before the resume.
       • The message that resumes the builder names that path.
   • Then resume the same builder with it, by Steps 8's "How" and "Before the resume" with round: 0.
     • The builder's final report carries the ruling.
   • Such a case whose fix changes a public shape or an established decision is a stop of the kind "A finding that is the user's", by "Stops".
   • Such a case whose fix lies outside the step's part goes where "What earns a step of its own" sends it.
   • Done when the report is saved at the report path, builder_usage is written and the whole diff is read.
7. Invoke /refute <entry> <step> when the block's review: calls for it on this step (every; or earned, by "The review, earned").
   • A small text step is reviewed once under every and earned alike.
   • Read the diff yourself while it runs.
   • Save its report.
     • Write its path, with the reviewer's agent id, its served model and its tokens, tool uses and time from its completion notice, into the dispatch entry under reviewer_report in the form of the refute skill's Steps 7, on disk.
     • The next resume-point commit of its plan carries them.
   • Done when the refuter report is saved and its record is under reviewer_report.
8. Send the findings back to the same builder, as a numbered list with a ruling per finding that stays inside the step's part and the written rules.
   • A small text step. It has no repair round, so no finding of its review is sent back.
     • Each finding is fixed at landing when it is small and inside the brief, or raised to the user as an open item, as the refute skill's "Finding dispositions" says.
     • A review that finds the step is not a small text step (the refute skill's "The four headings", Spec) makes it a full step, and the bullets below apply.
   • How. The builder is resumed by the runner's message tool on its agent id in session_id, the numbered list as the message.
   • Dictated text. Text a round's brief or a cases ruling gives the builder word for word is held line by line before the round's brief or the ruling is committed, as the spec skill's "Steps / The brief check" 2 "Dictated text" holds a brief's, since the brief check never reads those files.
     • A dictated sentence that says how a script behaves is run on the script before the round is committed, and the run is quoted in the round's brief.
   • Before the resume. Write round: n into the dispatch block.
     • Copy the round's brief into the worktree's copy of the ledger at the path it has in the main ledger.
       • The message that resumes the builder names that path.
     • For a repair round, snapshot the step's change as the round is sent.
       • git status --porcelain --untracked-files=all, run from inside the step's worktree, lists every changed path.
       • Each listed path outside the ledger root is copied into <worktree_root>/<slug>-<step>-round-<n>/ at the same relative path.
       • The session writes the list itself, the lines git status printed for those paths, into that folder as files.txt.
       • A deleted path is named in files.txt and not copied.
       • The folder lies under the worktree root, which git ignores, so no check reads it and no commit carries it.
     • Commit the dispatch block as a resume point, in the form "Resuming, and handing the plan over" states, with the round's brief and the session's own records of the step's plan since the last resume point.
       • The brief and the brief-check report of a /spec waiting on its brief check are not among those records (the spec skill's "Steps / The brief check" 1).
   • Only known fixes. Each ruling says what to change.
     • A finding whose cause is not known (a failure that does not reproduce, a slow case, a fault seen once) is diagnosed, before the round is sent, with /diagnose <entry> <step> <finding> (round <n> before the name for a finding of the run over repair round <n>).
       • The diagnosis runs in a diagnosis agent, as the diagnose skill's "Rules" say.
       • It probes read-only on a scratch copy.
       • It leaves the step's worktree unchanged.
     • The orchestrator saves the diagnosis agent's final message as the record and reads it as a builder's report is read, as a lead and not a fact.
     • The orchestrator then rules on the round.
     • The round carries the found cause's fix.
     • A cause not found is not sent.
     • Such a cause is noted at landing, as the land skill's Steps 9 says.
     • Such a cause is raised to the user as an open item, the row "A finding that is the user's" of "Stops".
     • A round never asks the builder to find a cause, to reproduce a fault, or to measure until a condition holds.
   • Sent back. A finding inside the step's part goes back in the repair rounds, whatever files it reaches.
     • The round's brief widens the path list to those files.
   • Not sent back. A finding that changes a public shape or an established decision is raised as a stop, by "Stops".
   • Outside the part. A finding outside the step's part goes where "What earns a step of its own" sends it.
   • After each reply. Read the whole delta.
     • Add the builder's tokens, tool uses and time for the round, from its completion notice, to builder_usage in the dispatch block, on disk.
     • When the block says refute_after_repair: yes, invoke /refute <entry> <step> again over the round, a fresh reviewer on the model "The two tiers, and the models" gives the run over a repair round, its run recorded under reviewer_report beside the first as the refute skill's "Steps / Over a repair round" 6 says.
   • The end of the rounds. A refutation that finds nothing, or the last round the round cap allows ("Rules"), ends the rounds, and the loop goes to step 9.
   • Done when each finding is closed in a round, left to landing or raised as a stop.
9. Invoke /land <entry> <step>, whose refusals are its own.
   • A red line the orchestrator cannot fix at landing takes the step back out of main.
     • Its failure is recorded in the step's Step 0 in plan.md.
   • The step keeps its line and its tag.
     • It is worked again as that step, with no new ruling, once.
   • The failure goes to the user as an open item only when what to do is a decision for the user, by "Stops".
   • A second failure of the step's landing always goes to the user, as the land skill's Steps 6 says.
   • A red line whose cause is not known is diagnosed with /diagnose <entry> <step> red line, once the step is out of main and before /spec prepares it again.
     • The diagnosis runs in a diagnosis agent, as the diagnose skill's "Rules" say.
   • The orchestrator writes the diagnosis's cause into the step's Step 0 for /spec, as the diagnose skill's Steps 20 says.
   • /spec then saves the step's work as a patch and prepares it again from main's head, as the spec skill's "Steps / A step taken back out of main" says.
   • At the landing of a step whose tag or Step 0 names a bullet ending "(self-rule, replaced by <name>).", for any name, the orchestrator adds its fix step, as references/self-rule.md, "The review of a choice", says.
   • Done when the step is on main with its booking, or is taken back out of main.
10. Continue with step 2.
    • The landing report is on disk at agents/reviews/<step>-landing.md, committed with the step, so the loop never ends its turn for a report.
    • Under self_rule: on and next_entry: on, the orchestrator goes on after the closing step as references/self-rule.md, "Next-entry mode", says.
    • The loop ends only at a pause of every plan the invocation runs or when none of them has an unblocked step.
    • Step 3 says what a stop does to the loop.
    • Under self_rule: on and next_entry: on, the run after a closing step ends in one of the cases references/self-rule.md, "Next-entry mode", lists.
    • The final message is the orchestrator's report as "Reports" says.
      • After a closing step, it also names the path of the closing report.
      • Under self_rule: on, it also says the choices are reviewed in <ledger_root>/choices.md with C<n> Agree or C<n> => <ruling>.
    • Done when the final message is written, or the loop is at step 2.

The two tiers, and the models

• Two tiers take part: the orchestrator, and the agents it starts (the builders, the reviewers, the brief-check agents and the diagnosis agents).
• Default. The orchestrator and every agent run on Claude Opus.
• Orchestrator. It may also run on Claude Fable.
  • It reads, decides, invokes the skills, lands and books.
  • It never writes step code itself beyond a fix at landing, unless the step's executor is inline.
• Agents. A builder, a reviewer, a brief-check agent or a diagnosis agent runs on a Claude model, and never on Claude Fable.
• Builder. One per step, in the step's worktree, under the brief and the rules file, on the model the configuration block's worker: names, at the effort worker_effort names, launched as "Launching a builder" says.
• Reviewer. The model is set per run of /refute.
  • The first run of a step runs on the model the configuration block's reviewer: names.
  • Each run over a repair round runs on the model the configuration block's repair_reviewer: names, or on the reviewer: value when the block has no repair_reviewer: key.
  • Every run is at the effort reviewer_effort names, launched as the refute and spec skills say.
• Brief-check agent. One per full step, in the /spec run that first reaches the spec skill's "Steps / The brief check", read-only, on the model the configuration block's reviewer: names, at the effort reviewer_effort names, launched as the refute and spec skills say.
• Diagnosis agent. One per diagnosis run with no person present, started by the orchestrator or by the /spec session as the diagnose skill's "Rules" say, on the model the configuration block's reviewer: names, at the effort reviewer_effort names.
  • It changes no file of the main checkout or of the step's worktree.
• Runner. Both tiers run under Claude Code.
• Any allowed combination is chosen per step.
• A new combination is booked in the rulings with what decides it.
  • It is measured by the landing reports of the steps it ran: each agent's tokens, tool uses and time, whether the first report passed its bar, and the fixes at landing.
• The same skill runs a code tool, a research project or a manuscript.

Resuming, and handing the plan over

The ledger is the whole handoff. An orchestrator may stop after any step, and another Claude Code session continues from the files alone, under these rules:

• Nothing needed to continue lives only in a runner's memory, its transcript, its scratch folder or a machine-local temp file: every decision, ruling, path a step depends on, sharp edge and landing report is in the ledger folder of its plan in the main checkout.
• A step's commits are only the points another session resumes from: a stop (its open item and Step 0), the preparation commit, the dispatch entry once the builder's identity is in it, a repair round sent (its round brief and the round's entry), a step taken back out of main at its landing (its entry and Step 0), a choice taken under self-rule, a review of a choice, the landing, and a handover.
• Every other ledger record (a builder's report saved, the builder's usage under builder_usage, a refuter report saved, a reviewer recorded, a ruling booked) is written to disk in the main checkout.
  • It is carried by the next of those commits of its plan.
• The form of a commit. Every commit the session makes on main names its paths, so that it records only what it names, whatever another skill has staged.
  • Each new or changed path is staged with git add -- <path> ....
  • The commit is git commit -m <message> -- <path> ..., naming every path the commit records, a deleted path included.
• A resume-point commit carries the session's own records under its own plan's ledger folder, and the choices file when a choice of that plan changed it.
  • It holds only the paths the session itself wrote since the last one.
    • The brief and the brief-check report of a /spec waiting on its brief check are not among them (the spec skill's "Steps / The brief check" 1).
  • Another plan's records wait for that plan's next resume point.
  • A commit that names the choices file records the whole file, every plan's changes to it included, since the file is one for every plan.
• A ledger change the session did not make is listed by path.
  • It is left alone.
  • One on the plan.md or the state file of the plan a /spec run prepares a step of is a refusal of /spec (the spec skill's Steps 1).
    • The records of an interrupted /spec of that step are no such change: the run takes them over (the spec skill's "Steps / A /spec taken over").
• A session taking over reads the ledger in the working tree as well as at main's head, since a record not yet committed is on disk in the main checkout.
• Handing the plan over is a resume point.
• A session that stops, for a handover, a pause or its end, first commits the records it wrote since the last resume point, of every open plan, in the form above.
• A stop of one step blocks its own step and does not stop the session, so its resume-point commit carries the records of its own plan only.
• So a session taking over finds no uncommitted record of the session before it, other than the brief and the brief-check report of a waiting /spec (the spec skill's "Steps / The brief check" 1).
  • A ledger change it did not make is listed, as the bullets above say.
    • It is left alone, as the bullets above say.
• A plan's state file is rewritten before every step commit of that plan, so it describes that plan as of its own last resume point.
• A commit of one plan rewrites no other plan's state file.
• A dispatch in flight is recorded in the state file of its plan before the builder starts, so a new orchestrator can tell whether a builder is still running, finished, or died, before it does anything.

On resumption, the dispatch blocks are read this way:

• Every open plan's dispatch block is read for the count and the path comparison.
• Only the steps of the plans the invocation runs are resolved and worked.
• Another plan's running builder is left to the session that runs that plan.

For each step, a resolved block holds:

• The builder is checked first, in the runner's own agent listing, by its agent id in session_id.
• A builder still running is waited for.
• A finished builder resumes at the read of its report.
• A step at landing: cherry-picking is checked on main (git status, git diff --cached) before anything is applied again.
• A step at landing: preparing whose brief_check reads "running: <agent id>" and whose agent the runner still lists is a live /spec waiting on its brief check, and is waited for.
  • When that agent ends, its report is saved from its completion notice, and the agent is never booked as dead, as the spec skill's "Steps / The brief check" 3 says.
  • When no /spec of the session is waiting on it, as after a compaction, the session then runs /spec <entry> <step> again, which takes the entry over (the spec skill's "Steps / A /spec taken over" 1).
• Any other step at landing: preparing is an interrupted /spec, one stopped by a compaction in the same session or one a session handed over after its handover commit.
  • It is resolved by running /spec <entry> <step> again, which takes over its dispatch entry.
  • The run goes on from where the interrupted run stopped, as the spec skill's "Steps / A /spec taken over" says.
• A step at landing: backed-out was taken back out of main by a red line at its landing.
  • Its worktree and its branches are kept.
  • It stays unticked in plan.md.
  • It is worked again as that step, its line keeping its tag, with no new ruling, unless its Step 0 records a second landing failure.
  • Its failure is in its Step 0 in plan.md.
• /spec of such a step saves its work as a patch and prepares it again from main's head, as the spec skill's "Steps / A step taken back out of main" says.
• A builder is dead when the runner's agent listing no longer shows it and no completion notification with a report arrived.
• A builder is also dead when a later session does not find its agent id in its own listing and no report is at the dispatch block's report path in the worktree.
• A dead builder is reported to the user with the worktree's git status --short and the builder's last message when there is one.
• A fresh continuation builder takes over a dead builder's worktree when the user says so.
• The dead builder's record moves to builders_before: as "Launching a builder" says.

On every resumption, with a dispatch block or without one:

• A booking present in the working tree but not committed, with the step's files staged, is a landing interrupted before its commit, and is finished before anything else.
• A landed step whose worktree or branches are still there is named by its open item (the land skill's Stops row "A worktree that cannot be removed").
• The removal is run from that open item, on the worktree and branches it names, each only when it still exists.
  • The open item is then closed.
• After a compaction the next skill is invoked through the runner, as "Rules" says, and the compaction's summary of a skill's text never stands in for the skill.

The review, earned

• Under review: earned the reviewer stage is decided per step from the landing reports of the builder's earlier steps and the diff, never from the builder's name.
• A small text step is reviewed once, as Steps 7 says.
• The reviewer runs on a builder's first step under this rule, and when any of the builder's last three landing reports shows a first report that did not pass the bar with at most one fix at landing.
• Whatever the record, the reviewer runs when the step's brief touches a public surface, a server module, a state layer or a wire shape.
• A failed bar puts the reviewer back for the builder's next three steps.
• The runs over the repair rounds follow refute_after_repair.
• Under earned, the runs over the repair rounds run only on a step whose first review ran.
• The landing report records which branch each step took.

The recurring-findings pass

• The pass runs per plan: every tenth landed step of a plan, and at any pause of it, the orchestrator reads that plan's refuter reports written since that plan's last pass and groups their findings by cause.
• A cause that appears in three or more steps of that plan is booked in the open items, since the user rules on it unless references/self-rule.md, "Closing an open item", closes it, with the smallest change that would end it: a rule sentence in the rules file, or a change to the text that should have prevented it (a brief's wording, a skill's step, a standards page).
• For a rule already written that keeps being broken, what is proposed is a sharper sentence for the rule or a change to the text that should have prevented it.
• A check (a command in the verification list, or a script) is proposed under these limits:
  • It is proposed only for a fact a machine computes.
  • It comes after the rule sentence or the text change.
  • The proposal states what it computes.
  • The user's ruling on the proposal approves what it computes, before it is written.
• The user rules on each proposal whose change is a rule sentence in the rules file, a standards page or the shared rules, or a check (a command in the verification list, or a script), since such a proposal is kind 3 of references/self-rule.md, "The six kinds left open".
  • Under self_rule: on, any other proposal is closed as references/self-rule.md, "Closing an open item", says.

Self-rule

• Scope. The section applies under self_rule: on in the configuration block, and to next-entry mode and to /grill and /plan run with --self-rule, where .agents/plan.yaml holds the keys, as references/self-rule.md, "Next-entry mode", says.
  • Otherwise, with self_rule: off or the key absent, every open item waits for the user, as "Stops" says.
• The reference. Under self_rule: on, and for the review of a choice, the session reads references/self-rule.md, which says which open items stay with the user, how the others are closed, how the choices file is kept and reviewed, and how next-entry mode runs.

Two steps in flight

The orchestrator, still one, may have as many steps running at once as the limit allows, each through steps 3 to 9 on its own, across every open plan, under these rules:

• The limit. .agents/plan.yaml's workers_at_once is the most steps in flight at once, read at each pick and counted over the dispatch blocks of every open plan.
  • A step is in flight from the start of its /spec: its dispatch entry at landing: preparing counts toward the limit (the spec skill's Steps 1).
  • In the projects: form, the limit is the smallest workers_at_once among the projects that have an open plan.
  • A configuration block that holds a workers_at_once line is read as if the line were not there.
• Every rule below holds for a pair of steps from two plans as for a pair from one plan.
• Whether two steps can run at once is decided by how simply the second one's change lands on the first's, not by their paths alone.
• For each pair the orchestrator states what each changes in code the other reads or changes, and how the later landing takes it: nothing to merge, a mechanical rerun (a converter, a formatter, a generator), a hand merge of named functions, or a dependency that forces an order.
• A pair whose later landing needs more than a mechanical rerun or a hand merge of a few named functions runs in sequence.
• Each brief lists the paths its step writes under "Paths this step writes".
  • /spec compares the list with the briefs of the steps in flight of every open plan by reading them (the spec skill's Steps 5).
  • A step at landing: preparing is compared once its brief is written.
• While a /spec waits on its brief check, the session may run /land, /refute and another /spec for other steps, under the rules of the spec skill's "Steps / The brief check" 1.
• Two steps in flight may name the same file if and only if the orchestrator judges that merging them at landing is simple.
  • The orchestrator writes that judgment in the later step's dispatch entry as shared_paths:, naming each shared file, the other step's plan and step, and why the merge is simple.
  • With no shared file the key is left out.
• When the merge is not simple, the later step waits until the earlier one lands.
• No script checks that judgment.
• A step that touches a configuration file or a rule file runs alone across all plans.
• Each step has its own worktree, base, builder, reviewer, rounds and dispatch entry.
• Each step is prepared, built and reviewed under its own plan's configuration block: worker, reviewer, efforts, review cadence and repair rounds.
• A later step is dispatched only after the earlier one's launch commit (Steps 4), whichever plan each belongs to, so its base holds the earlier brief and dispatch entry.
• Landings are one at a time across all plans, in the order the steps are verified.
  • A later one lands on the head the earlier left, its whole diff read again there.
  • A landing runs from its cherry-pick to its commit before any other commit or skill, as the land skill's Rules say.
• A file both steps changed means the later step goes back through step 6 on the new head before it lands.

Launching a builder

• A builder (claude:<model>) is dispatched with the runner's Agent tool, with subagent_type: ordo-<worker_effort>, the effort agent of the configuration block's worker_effort (high when the block has no such key), the model named and the prompt of Steps 4.
• Right after the launch, and before the launch commit (Steps 4), the orchestrator reads the model the runner served the builder from the runner's own record of the agent: under Claude Code, the model field of the assistant entries of the agent's transcript, subagents/agent-<agent id>.jsonl in the session's folder under ~/.claude/projects/, or under $CLAUDE_CONFIG_DIR/projects/ when that variable is set.
• The orchestrator writes that model beside session_id in the dispatch entry, as session_id: <agent id> (<served model>).
• The same check runs when the builder is resumed for a repair round.
• A served model that is not the configured one is the stop "A model other than the configured one" ("Stops"): the agent is stopped through the runner's stop tool, and nothing it wrote is used.
• A builder that is replaced keeps its record: its agent id and served model move to the dispatch entry's builders_before: key, one after another.
  • A builder stopped for another model is recorded as <agent id> (<served model>, stopped).
  • A dead builder is recorded as <agent id> (<served model>, dead).
  • session_id takes the new builder.
• It runs in the background.
  • The runner tracks it and reports when it ends.
• A repair round resumes it with the runner's message tool on its agent id in session_id, as Steps 8 says.
• Its completion notification carries its final message, which Steps 6 reads.
• It works under the runner's own permission settings.

What earns a step of its own

• A step is a part of the entry, as the plan skill's Steps 2 says.
• New work goes by its reason, listed below.
• A finding inside the step's part. It is sent back in the step's repair rounds, as Steps 8 says.
• A fix in a file another step holds. It is made at that step's landing.
• The work the last round leaves undone inside the part.
  • Small work is fixed at landing.
  • Other work is an open item, and a new step for it needs a reason of this list.
• A ruling on a part not yet built. It rewrites that step's line and brief, the line ending with (ruling <name>), and adds no step.
• A fix of what a run or a review of a step found, followed by that check again. It is a repair round of that step, counted against the round cap ("Rules"), and never a new step.
  • When the cap is spent, the failure goes to the user as an open item on the approach, by "Stops".
  • No option of that open item offers more rounds, or a step that fixes and runs the check again.
• A part the entry needs that no step builds, or a landed part found wrong or short. It is a new step, a line ending with (ruling <name>).
• Work outside the entry's goal. It is a new roadmap entry through /roadmap add and never a step of this plan.
• A finding that changes a public shape or an established decision. It is an open item, by "Stops".
• A new step and a new roadmap entry each need a ruling of the user or, under self_rule: on, a choice references/self-rule.md, "Closing an open item", books.
• /spec refuses a step line without its tag.
• A report that asks for a step names the reason of this list that applies.

Reports

• A position line belongs to one plan: the roadmap entry with its title, the plan step being worked as "step n of m" with its name, and the next step, in the form "Roadmap entry <n> (<title>). Plan step <k> of <m>: <step name>. Next: step <k+1>, <step name>."
  • A plan a pause holds ends its position line with "Next: PAUSED, until <the user> says otherwise." in place of the next step.
  • A plan whose step being worked is the closing takes the form "Roadmap entry <n> (<title>). Plan step <m> of <m>: the closing. Next: <the closing's next part>."
    • <the closing's next part> is one of:
      • the closing report;
      • the roadmap diff of /roadmap done <n>, for the user's approval;
      • the tag and the pin, for the user's approval, where the plan's rulings set them;
      • the move of the folder to <archive_root>/.
  • A plan whose folder has moved to <archive_root>/ is not open and has no position line.
• The orchestrator's report opens with a line naming anything NOT DONE, or saying that everything is done.
  • Then come one position line per open plan, in the roadmap's order, each followed by that plan's open items verbatim.
  • Then come the steps landed since the loop began, grouped by plan, each with the path of its landing report.
  • Under self_rule: on, then come the choices taken since the loop began, by C<n> and heading.
• The landing report stays one per step, in its plan's ledger, and opens with its own plan's position line, in the order the land skill's Steps 11 gives.
• A builder's report keeps the shape of the repository's change standard.
• In the landing report, the state file's open items follow the position line, verbatim.
• The open items hold only what the user must rule on: a stop, and a proposal of the recurring-findings pass.
• A finding that is neither closed in the repair rounds nor fixed at landing is an open item, which goes where "What earns a step of its own" says.
• The other list, the closed one, is the log of what was raised and how it ended.
  • No report carries it.
• The orchestrator's report ends with a DONE / NOT DONE table, one row per step landed or stopped since the loop began.
  • Each row names the landing report and the command it quotes, or the open item that proves it.

Usage

• The landing report states each agent's tokens, tool uses and time, from its completion notice.
• The closing report holds the cost script's output, or the sentence that the plan started no agent, as the plan skill's Steps 2 says.
• A person runs the cost script by hand on any ledger folder, open or archived, as python3 <this skill's folder>/templates/plan_cost.py <ledger folder> [<transcript root>].
• The script finds the response bodies in the folder OTEL_LOG_RAW_API_BODIES names, from its environment or else from the env key of Claude Code's settings files, as its head comment says.
• With no such folder, the script prices from the transcripts and marks every cost as a lower bound.

The pace when a deadline is set

When the user sets a time by which no agent may run, the loop keeps a night rule and writes it into the state file of every open plan:

• The cut-off holds every agent of the session, whichever plan it works for.
• A builder is dispatched only while the longest step so far still fits before the cut-off.
• A reviewer or a repair round is dispatched only while its usual length fits before the cut-off.
• At the cut-off anything still running is stopped.
  • Its worktree is kept.
  • Each open plan's state file is rewritten with what was in flight.
  • Every open plan is paused.
• A one-shot wake-up at the cut-off does the stopping when the runner offers one.

Stops

The table holds seven kinds of stop, each for a decision for the user, and one refusal, the last row, which names its cause and leaves no open item:

• Fixing a defect in what the user asked for is never a stop, whatever the fix makes visible.
• A stop is booked in the state file's open items the moment it is raised, and under the step's Step 0 in plan.md.
  • Under self_rule: on, a stop of a kind that references/self-rule.md, "The six kinds left open", does not name, and that is not one of the stops its "The counts" names, is then closed as its "Closing an open item" says.
• The ledger files of the step's plan that the session wrote are then committed as a resume point, in the form "Resuming, and handing the plan over" states, so the stop survives the session.
• A ruling that adds or splits a step is booked as the spec skill's "Steps / A ruling" says: the new line in the step list ends with (ruling <name>), naming the ruling's line in the Rulings section.
• A stop is repeated in every report until the user has ruled, or, under self_rule: on, until the orchestrator closes it as references/self-rule.md, "Closing an open item", says.
• The stop message is plain text in the report: an open item with its options inside the written rules, the pros and cons of each, and one recommendation with its reasons.
  • It never goes through a question-box or multiple-choice tool.
  • Each option states in full every approval it would need later whose content exists when the option is written, such as what a new script computes or a change to the configuration or the verification list.
  • The user's ruling on the item then approves those approvals too, with no second stop.
  • An approval of work not yet done when the option is written, such as the user's reading of a page a step will write, stays a stop of its own.
  • The option names that stop.
  • An option that runs a skill with an approval stop (/plan, /roadmap, /ordo-init, /repo-setup or /grill) states the change in full, as that skill's text says a quoted ruling must state it, or names that skill's approval stop as a stop of its own.
  • After the user's ruling on an option that states the change, the session books the ruling as the spec skill's "Steps / A ruling" says.
  • It then runs the skill with --ruling <ledger file> "<name>".
• A pause the user asks for holds every open plan unless the user names the plans it holds.
  • It holds until the user lifts it.
  • It is written in the position line of each plan it holds ("Reports").

Anti-patterns

Rules

• The skill carries no project name, since that is in .agents/plan.yaml and the ledger.
  • The models it names are those in "The two tiers, and the models".
• A fix of a defect in delivered work needs no yes.
• The round cap: a step gets at most repair_rounds repair rounds, and one more only when the delta leaves a verification command red or an acceptance item of the brief unbuilt and the fix is too large for landing.
  • A new finding of a review never earns that round.
  • The user's yes never extends the cap.
  • No ruling adds a step that does what a repair round does: a fix of what a run or a review of a step found, followed by that check again.
• Nothing in the loop repeats without a count:
  • a full step gets one brief check (the spec skill's "Steps / The brief check" 4), the repair rounds of the round cap, one refutation before the first round and one over each round;
  • a small text step gets one refutation, no brief check and no repair round;
  • every step gets two stops before its build (the spec skill's "Steps / A stop" 3) and one return out of main (the land skill's Steps 6).
• A step that cannot go on within those counts stops for the user by "Stops", and the loop moves to the next step.
• After its last round a step lands.
  • Its small findings, the last review's included, are fixed at landing.
• Everything else that the rounds left undone, or that lies outside the step's part, is raised to the user as an open item, by "Stops".
  • It is never sent back to the builder.
  • It goes where "What earns a step of its own" says.
• Every skill the orchestrator invokes (/spec, /refute, /land, academic-paper for manuscript content, /roadmap at the closing, /grill <entry> --self-rule and /plan <entry> --self-rule in next-entry mode, and /plan, /roadmap, /ordo-init, /repo-setup or /grill run under a quoted ruling) is invoked through the runner every time, after a compaction too, and never carried out from remembered text.