# Ordo Ordo is a set of agent skills for Claude Code that run a multi-step change as a plan. The skills carry no project name and no path. Everything specific to a repository comes from that repository's `.agents/plan.yaml`. The same skills therefore run a C++ engine, a TypeScript tool or a research project. One roadmap entry becomes a plan, kept in a ledger folder. Each step of the plan gets a brief, its written specification, and is built in its own git worktree. A fresh reviewer that changes nothing reviews the step. The step is cherry-picked onto `main` only after its checks pass there. Around that loop, `repo-setup` and `ordo-init` set a repository up for it. `roadmap` keeps the entries the plans open, `grill` settles an entry's design decisions before its plan opens, `diagnose` finds the cause of a defect, inside a plan's loop or on its own, and `plan-retro` turns what the reviewers keep finding into rules. `session-retro` reads the transcripts of Claude Code sessions and proposes a change to a named rule, skill or brief for what went well and for what went wrong. ## The skills | Skill | What it does | |---|---| | `repo-setup` | Sets up a new repository and then runs `/ordo-init`. It writes `CLAUDE.md` with the shared rules, the change and prose standards, the standards pages, a roadmap, a glossary, an ADR folder, `.gitignore` and `LICENSE`, and installs the project skills. `sync` keeps an existing repository's shared rules and its glossary's plan terms equal to their templates | | `ordo-init` | Sets a repository up for the other skills. It drafts `.agents/plan.yaml` from the repository, offers the pages it lacks and fixes the ignore rules. On an existing file, it checks the file | | `roadmap` | Keeps the roadmap that `/plan` opens entries from. It shows the open entries in order and the entries not yet specified. It adds an entry with its goal, a gate that could not pass without the goal being reached, and its place, or puts work whose gate cannot yet be named under "Not yet specified". It moves an entry, marks one done with the gate's output, and drops one. It learns the file's own format, including an ordered build plan over a capability map | | `grill` | Interviews the user about one roadmap entry, in rounds. Each round asks every decision whose prerequisites are settled, each with its options, their pros and cons, a reference line for the configured design bar, one recommendation and the lazy option named, while agents look up the facts. It writes each answer as it settles into the plan's Rulings or the entry's rulings file, each lookup agent it starts as a bullet of the Agents section of that file, the roadmap entry and the glossary, and a proposed ADR on the user's yes or, under `--self-rule`, on the orchestrator's recommendation | | `plan` | Opens a plan for one roadmap entry: the ledger folder, `plan.md` with a drafted step list for approval, the gate and each step's check asked whether it could pass without the goal being reached, `orchestrator-state.md`. It refuses an entry not yet specified | | `spec` | Prepares one step. It checks the step's authority, the user's approval or a ruling, and checks the step's premises against the tree. It writes the brief and checks the paths it writes against the steps in flight. For a full step, a fresh read-only agent checks the brief against the tree, and each finding is closed in the brief. It creates the worktree and stages the base binaries | | `refute` | Reviews a built step without changing it: reruns the checks the brief's "Verify before you report" names and every command the builder's report quotes, never the plan's whole verify list, writes a verdict per item of the brief and per case, and findings each with its failure scenario | | `diagnose` | Finds the cause of a defect before anything is changed. It runs one command red on the exact symptom, shrinks the case, ranks three to five hypotheses, makes one change per probe, and writes the fix with its test and a diagnosis record. Inside a plan, with no person present, it runs in a fresh agent, probes on a scratch copy and leaves the step's worktree unchanged; run by a person it waits for the reply to the hypotheses | | `land` | Cherry-picks a reviewed step onto `main`, runs the checks there, books the step, commits the paths it names, removes the worktree | | `plan-orchestration` | Runs every open plan unattended in one session, or the plan named, step by step, and stops only where a decision belongs to the user. Under `self_rule: on` and `next_entry: on` it goes on to the next roadmap entry after a closing | | `ordo-help` | Prints the command sequence and the position of each open plan, and for a named plan its position and the command that comes next. For `skills` it prints the name and the Quick start block of every skill instead | | `plan-retro` | Reads every refuter report and groups the findings by kind. For each kind that recurs, it proposes the rule sentence, the change to the text that should have prevented it, or the standards page that stops it, and a check only for a fact a machine computes, which the user approves | | `session-retro` | Reads the transcripts of a plan's Claude Code sessions, of one session or of a time window. It reports what went well, to keep, and what went wrong, to change. Each point quotes its place and proposes a change to a rule, skill or brief, which the user decides on | | `writing` | Reviews the prose of a draft with a script and four fresh agents that change nothing: a `.tex` file with its input files, a `.md`, a `.txt` or a `.docx`. It reports each break of a named rule with its place, the quoted passage and what the rule asks for, grouped by rule and numbered, and proposes no replacement | | `code-comments` | Reviews the comments a git diff adds or changes, the uncommitted changes or a range, with a finding agent and a checking agent that change nothing. It reports each comment that breaks a named rule with its place, the quoted comment and what the rule asks for, the false comments first, and proposes no replacement. On `apply ` or `apply all` a fresh agent rewrites the picked comments in C, C++ and CMake files, and a rewrite is kept only when `templates/strip_comments.py` finds the code unchanged | | `paper` | Writes, revises and checks a LaTeX manuscript in nine modes (full, outline-only, revision, abstract-only, lit-review, citation-check, disclosure, plan and format-convert) and two calls, `/paper draft-review` and `/paper figures`. Fresh agents each hold one role: literature strategist, planner, draft writer, visualization, peer reviewer, citation compliance, Socratic mentor and formatter. A plain request such as `/paper improve section 3` picks the mode, which intake shows for you to confirm. Plan mode guides you chapter by chapter with the Socratic mentor to a chapter plan, and format-convert converts a manuscript to DOCX, PDF, Markdown or LaTeX, to another citation style or to a venue's template, and makes the reference list of a `.bib` in a citation style, with `pandoc`, `latexmk`, `pdftocairo`, `pdftotext` and, for a `.bib`, `latex` and `bibtex` when they are installed. Every change to the manuscript is a patch applied by script. Full, revision and citation-check runs judge each cited claim against a passage read from the source in the run. A lit-review run checks every entry of `refs.bib` against an index with the session's own run of `lookup.py resolve --entry` before any patch, and its final message states how many entries that run confirmed and names each entry taken out. Full and revision runs check the cited sentences of each later patch, check each number the manuscript states against its result file, and stop when the materials give no result for a part of the research question. The run's records stay in `paper-runs/` beside the manuscript's folder. Full and revision runs end with `/writing`, and you reply with the findings to apply as patches or ask for an autonomous writer pass | The order of use, shortened from what `/ordo-help` prints: ``` /repo-setup once, for a new repository: the tree, the shared rules, the standards, then /ordo-init /ordo-init once per existing repository: writes .agents/plan.yaml, or checks the one there /roadmap add an entry with its goal, gate and place in the order /roadmap add for an entry not yet specified: its gate and place in the order, before /plan opens it /grill optional: an interview in rounds that settles the entry's design decisions, written as they settle /plan once per entry: opens the plan, shows the step list for approval for every step: /spec writes the brief, has a fresh agent check it against the tree once per full step (the brief check; a small text step has none) and closes its findings in the brief, makes the worktree, stages the base binaries "build it" the session writes the code in the worktree, runs the checks, writes the report /refute a fresh reviewer reads the diff and reruns the checks, writes verdicts and findings /diagnose optional: when a finding's cause is not known, finds it before "close them" "close them" a repair round, up to repair_rounds times; a small text step has none /land onto main, checks on main, the booking, the commit C Agree under self-rule: you agree with a choice the orchestrator took C => under self-rule: you replace a choice with your ruling /plan-orchestration instead of the step lines: runs them for every step of every open plan unattended, and under self_rule: on and next_entry: on goes on to the next entry after a closing /plan-orchestration the same for the plan of that entry alone /plan-retro after plans have run: the findings that recur, and the rule sentence, text change or page that stops each, a check only for a fact /session-retro for a plan, open or closed: what went well and what went wrong in its Claude Code sessions, each with a proposed change /diagnose at any time, outside a plan: the cause of a defect, from a command red on it, before any fix ``` `/ordo-help` prints the full sequence, including what to do when a command stops. The figures below draw each run in the same way. A solid box is an agent start that always runs, and a dashed box is an agent start that runs only when needed. An orange box is a stop where the run waits on you. A dotted arrow is a cycle with its cap, and a dotted loop on one agent is a check it repeats inside its own start, with its cap. Scripts and the session's own steps are left out. A stop waits on you each time, unless the run is under a quoted ruling that states the change. Under `self_rule: on` a stop waits only when `plan-orchestration` leaves it open: an item of one of its six kinds, or a stop of `/roadmap` (except an `add` of work a finding of a running plan names), `/ordo-init` or `/repo-setup`, which take only your ruling. ![The pipeline of one roadmap entry, command by command: /repo-setup and /ordo-init for setting a repository up, then /roadmap add, /grill, /plan, every step, /roadmap done, and beside them /plan-retro, /session-retro and /diagnose. Each command is a lane that holds the agent starts it makes and the stops where you are asked. /repo-setup: The questions; The draft; A hunk to rule on; The drafted sync change; A file sync cannot use; The check still fails; No commit allowed. /ordo-init: The draft; Several roadmaps; Worker, reviewer and libraries; A failing command; A fix in the check; No commit allowed. /roadmap add: The change; No gate; The level; The insertion form; A missing dependency. /grill: Lookup agent, when a fact needs it; A round; The end; A lookup agent served another model. /plan: A gate with no count; The drafted step list. Every step: the loop of the next figure. /roadmap done: The change. /plan-retro: The proposals. /session-retro: A large output; The proposals. /diagnose: Diagnosis agent, when run in a plan's loop; The hypotheses; No red command; A red command a person drives; Not enough output after redaction; The cause not found.](docs/figures/pipeline.svg) The loop of one step draws the commands in order, each with the agent starts it makes and its stops, with the lane that runs the loop unattended below it. ![The loop of one step, command by command: /spec, build it, /refute, close them, /refute over the round, with a return for a further round, and /land, with the /plan-orchestration lane below. /spec: Brief-check agent, for a full step; Diagnosis agent, for a part that asks for a cause; A false premise the plan cannot absorb; A rule clash with an ADR; A user-visible choice; A brief check finding the brief cannot absorb; A cause not found; A model other than the configured one; A step that does not converge. Build it: Builder agent, unless the executor is inline or academic-paper. /refute: Reviewer agent; A model other than the configured one. Close them: Builder agent, a repair round of a full step; Diagnosis agent, for a finding whose cause is not known. /refute over the round: Reviewer agent, when refute_after_repair is yes; A model other than the configured one. /land: A red line for the user; A rule clash; A lock held; A worktree that cannot be removed. /plan-orchestration: A shape nobody named; A wrong premise; A red check; A rule clash; A finding that is the user's; The roadmap diff; A model other than the configured one.](docs/figures/plan-loop.svg) The skills that launch agents each have a figure of their own. `grill` starts lookup agents, `writing` three finding agents and a checking agent, and `code-comments` a finding agent, a checking agent and a rewrite agent. ![The grill skill: Lookup agent, when a decision needs a fact a file read does not give, dashed; A lookup agent served another model, a stop; A round, a stop that repeats until no decision is open; The end, a stop.](docs/figures/grill.svg) ![The writing skill: Sentence agent, Section agent and Whole-draft agent start at once; Checking agent starts after them; The end: the numbered report; A model other than the configured one, for any of the four, a stop.](docs/figures/writing.svg) ![The code-comments skill: Finding agent; Checking agent; The end: the report of the comments that break a rule; Rewrite agent, when you type apply, dashed; A model other than the configured one, for any of the three, a stop.](docs/figures/code-comments.svg) Each mode of `paper` has its figure. In every mode, at every agent start a model of another family than the configured one stops the run, while a newer model of the same family goes on and is named in the final message, and at every patch a structural patch, a patch that does not apply or a failed script stops it. ![The full mode of paper: Intake: you confirm, a stop; Literature strategist, unless you skip it, dashed, with each entry checked against an index and its search passes, ending at 3 of 5 conditions with the one on new sources among them, or after pass 4 when none holds, at most 8, for a request with one search theme; for two search themes or more, Literature strategist, theme runs, one per search theme, all at once, dashed, each with its search passes and its target count to reach; Literature strategist, merge run, after the theme runs, dashed, which removes the duplicates, searches across the search themes with chaining rounds until the citation loop closes, at most 8, and writes the one review, and which sends a theme run whose report numbers the parts of the research question otherwise back once; You review the sources, optional, a stop; Planner; A research question the materials do not answer, when a part has no result, a stop, with a fresh planner start after your answer; Literature strategist: the sections with no source, dashed, with its search passes, ending at 3 of 5 conditions with the one on new sources among them, or after pass 4 when none holds, at most 8; Planner: assigns what was found, dashed; Planner, fresh: rewrites each argument with two or more weak-argument signs, dashed; Outline approval: each rewritten argument before and after, a stop, with changes or another structure and no cap; Draft writer; Draft writer once more: the model identifier, when the model list gave none or the served one differs, dashed; Visualization, with data, dashed, with its rendered-figure check, up to 2 fixes; Citation compliance; Citation compliance once more, when a check fails, dashed; A claim the run cannot support, or a reference that cannot be confirmed, a stop, reached after every claim is judged; The citation style to confirm, when more than half the entries fail the same check, a stop, with a fresh citation compliance start after your answer, once; Peer reviewer; Draft writer: a patch, in round 2, once; Citation compliance for each later patch with a cited sentence, dashed, checking those sentences only; The draft review rejects the draft: each Critical issue classed, a roadmap, a stop, reached on a Reject in round 1, with a Major Revision pass for a fixable issue, the outline for a structural one and intake for a fundamental one, each after you confirm; The draft review does not pass: no answer recommended, a stop, reached after round 2 on a score under 6.5 with a Critical issue open, with accept going on to the reference fix, a hand revision or a lower venue back to a fresh review, and an expanded revision back to the step the cause names only when you choose it; Draft writer: reference fix, dashed; A reference that cannot be confirmed, a stop; Draft writer: compile fix, dashed; /writing: 4 agents, unless you said no at intake, dashed, with an arrow from the compile fix to the end around it; End: the final message, with the /writing report and your reply, optional; Draft writer: applies what you pick, dashed; Citation compliance: the sentences of the findings pass, dashed; Peer reviewer: reads the findings pass, dashed; Draft writer: compile fix, dashed; Draft writer: the anonymous copy, for a double-blind venue, dashed; Formatter: the DOCX and Markdown targets you named, dashed.](docs/figures/paper/full.svg) ![The revision mode of paper: Intake: you confirm, a stop; Peer reviewer: the instructions as items, or, with none, a review of the manuscript; A research question the materials do not answer, when an item names a part with no result, a stop, whose answer goes to the approval of the items when there are no instructions; You approve the items, with no instructions, a stop; Literature strategist, for a new reference, dashed, with its search passes, ending at 3 of 5 conditions with the one on new sources among them, or after pass 4 when none holds, at most 8; Visualization, for a figure, dashed, with its rendered-figure check, up to 2 fixes; Draft writer: a patch per item; Citation compliance; Citation compliance once more, when a check fails, dashed; A claim the run cannot support, or a reference that cannot be confirmed, a stop, reached after every claim is judged; The citation style to confirm, when more than half the entries fail the same check, a stop, with a fresh citation compliance start after your answer, once; Peer reviewer: reading; Draft writer: one pass, when items are not resolved, once; Citation compliance for each later patch with a cited sentence, dashed, checking those sentences only; Draft writer: reference fix, dashed; A reference that cannot be confirmed, a stop; Draft writer: compile fix, dashed; /writing: 4 agents, unless you said no at intake, dashed, with an arrow from the compile fix to the end around it; End: the final message, with the /writing report and your reply, optional; Draft writer: applies what you pick, dashed; Citation compliance: the sentences of the findings pass, dashed; Peer reviewer: reads the findings pass, dashed; Draft writer: compile fix, dashed; Draft writer: the anonymous copy, for a double-blind venue, dashed.](docs/figures/paper/revision.svg) ![The lit-review mode of paper: Intake: you confirm, a stop; Literature strategist, dashed, with each entry checked against an index and its search passes, ending at 3 of 5 conditions with the one on new sources among them, or after pass 4 when none holds, at most 8, for a request with one search theme; for two search themes or more, Literature strategist, theme runs, one per search theme, all at once, dashed, each with its search passes and its target count to reach; Literature strategist, merge run, after the theme runs, dashed, which removes the duplicates, searches across the search themes with chaining rounds until the citation loop closes, at most 8, and writes the one review, and which sends a theme run whose report numbers the parts of the research question otherwise back once; You review the sources, optional, a stop; Session: each entry of refs.bib checked against an index again, a script, with an entry not confirmed sent back to the literature strategist once, or after theme runs to the merge run's strategist, to be corrected or taken out; Draft writer: reference fix, when a .tex is given, dashed; A reference that cannot be confirmed, a stop.](docs/figures/paper/lit-review.svg) ![The outline-only mode of paper: Intake: you confirm, a stop; Literature strategist, dashed, with each entry checked against an index and its search passes, ending at 3 of 5 conditions with the one on new sources among them, or after pass 4 when none holds, at most 8, for a request with one search theme; for two search themes or more, Literature strategist, theme runs, one per search theme, all at once, dashed, each with its search passes and its target count to reach; Literature strategist, merge run, after the theme runs, dashed, which removes the duplicates, searches across the search themes with chaining rounds until the citation loop closes, at most 8, and writes the one review, and which sends a theme run whose report numbers the parts of the research question otherwise back once; You review the sources, optional, a stop; Planner: outline and argument map; Literature strategist: the sections with no source, dashed, with its search passes, ending at 3 of 5 conditions with the one on new sources among them, or after pass 4 when none holds, at most 8; Planner: assigns what was found, dashed; Outline approval, a stop, with changes or another structure and no cap.](docs/figures/paper/outline-only.svg) ![The abstract-only mode of paper: Intake: you confirm, a stop; Draft writer: the abstract.](docs/figures/paper/abstract-only.svg) ![The citation-check mode of paper: Intake: you confirm, a stop; Citation compliance; A claim the run cannot support, or a reference that cannot be confirmed, a stop; The citation style to confirm, when more than half the entries fail the same check, a stop, with a fresh citation compliance start after your answer, once; Citation compliance once more, when a check fails, dashed; Citation report.](docs/figures/paper/citation-check.svg) ![The disclosure mode of paper: Intake: the venue or the policy anchor, the policy of a venue not listed, the kinds of AI use the records leave uncertain; you confirm, a stop; Draft writer: the statements; Draft writer once more: the model identifier, when the model list gave none or the served one differs, dashed.](docs/figures/paper/disclosure.svg) ![The plan mode of paper: Intake: you confirm, a stop; Socratic mentor: given each answer, resumed or started fresh; The mentor's question: each answer; offers after 8 rounds on a chapter and 30 in all, a stop, with a return to the mentor for each answer; Planner: the outline from the chapter summaries, with a return to the mentor's question for your confirmation of the last summary; Mentor, Step 2.5: contribution sharpening, one round or more, with a return to the mentor's question for its questions to you; Planner: evaluates each stress-test answer, with a return to the mentor for each rating; Planner: the chapter plan, when every sub-argument is Moderate or above or you end the stress test; The plan's handoff, a stop, with a return to the mentor when a condition of the gate is not met.](docs/figures/paper/plan.svg) ![The format-convert mode of paper: Intake: you confirm, a stop; Formatter: the patches and the report; Formatter again, for the conversion patch, when the citation style changes, dashed.](docs/figures/paper/format-convert.svg) ## Requirements - git, POSIX `sh`, and `python3` with PyYAML. The verify runner, `skills/land/templates/checks.sh`, also needs `bash`. - `perl`, for the ASCII check of `docs/dev/building.md` and for `sync_rules.test.sh`. - `node` and `npx` on `PATH`, for the skills CLI only. Both the CLI install and `repo-setup`'s project skills use that CLI. - Claude Code. ## Install The skills call each other and read each other's templates, so install all of them. Claude Code reads skills from `~/.claude/skills` (or `$CLAUDE_CONFIG_DIR/skills` for a second account). Remove any copy of these skills under a repository's `.agents/skills` or `.claude/skills`, so that the installed copy is the only one loaded. The plan skills, `grill`, `writing`, `code-comments` and `paper` launch their agents through five agent definitions, `agents/ordo-low.md` to `agents/ordo-max.md`, which Claude Code reads from `~/.claude/agents` (or `$CLAUDE_CONFIG_DIR/agents`). For the plan skills, `grill` and `code-comments`, `CLAUDE_CODE_EFFORT_LEVEL` must be unset, since it overrides the effort each definition sets. `paper` and `writing` start their agents as `ordo-medium` when it is listed and the variable is unset, and otherwise run them on the runner's default agent with the Agent tool's `effort` set to `medium`, at the variable's value when it is set. ### With the skills CLI ```sh npx skills add TheAxeC/ordo --skill '*' -g -a claude-code ``` This copies each skill folder into `~/.agents/skills` and links it from `$CLAUDE_CONFIG_DIR/skills`, or `~/.claude/skills` when that variable is unset. For a second Claude Code account, run it again with that account's `CLAUDE_CONFIG_DIR` set. Updating is `npx skills update -g`. After an update, `npx skills ls -g` lists the installed skills, and `npx skills remove --global ` removes a skill a newer version of Ordo no longer ships. The CLI installs and updates skills only. After `npx skills add`, and after each `npx skills update -g`, copy the agents from a clone: ```sh rm -rf /tmp/ordo && git clone --depth 1 https://github.com/TheAxeC/ordo.git /tmp/ordo mkdir -p ~/.claude/agents rm -f ~/.claude/agents/ordo-*.md cp /tmp/ordo/agents/*.md ~/.claude/agents/ ``` For a second Claude Code account, run the last three commands again with `$CLAUDE_CONFIG_DIR/agents` in place of `~/.claude/agents`. ### By copying the folders ```sh rm -rf /tmp/ordo && git clone --depth 1 https://github.com/TheAxeC/ordo.git /tmp/ordo for dir in ~/.claude/skills; do mkdir -p "$dir" for skill in code-comments diagnose grill land ordo-help ordo-init paper plan plan-orchestration plan-retro refute repo-setup roadmap session-retro spec writing; do rm -rf "$dir/$skill" && cp -R /tmp/ordo/skills/$skill "$dir/" done agents=$(dirname "$dir")/agents mkdir -p "$agents" rm -f "$agents"/ordo-*.md && cp /tmp/ordo/agents/*.md "$agents/" done ``` The loop copies the agents into the `agents` folder beside each skill folder. For a second Claude Code account, add that account's `$CLAUDE_CONFIG_DIR/skills` to the list of folders, and its agents go to `$CLAUDE_CONFIG_DIR/agents`. Updating is the same commands again: each skill folder is replaced whole, and the agents are replaced the same way, the old `ordo-*.md` removed first, so a file a newer version removes does not linger. The loop replaces only the skill folders it copies. Remove a skill a newer version of Ordo no longer ships from each folder of the list by hand: `rm -rf ~/.claude/skills/`, and for a second account `rm -rf "$CLAUDE_CONFIG_DIR/skills/"`. ## Configuring a repository A new repository is set up with `/repo-setup` from an empty folder. It asks for the name, the kind, the license, the commit rule, the standards pages, whether the repository has a user interface, and the project skills. It then shows the whole tree and every file's text. After your approval it writes `CLAUDE.md`, the change and prose standards, the standards pages (by default the design principles, the coding standards for its languages and, with a user interface, the UI standard), a roadmap, a glossary, an ADR folder, `.gitignore`, `LICENSE` and `README.md`. It then installs the project skills, which writes `skills-lock.json`, and runs `/ordo-init`. It writes no Claude Code settings file. The shared rules in `CLAUDE.md` sit between `` and ``. They are a copy of `skills/repo-setup/templates/shared-rules.md`. The plan terms in `docs/glossary.md` sit between `` and ``. They are a copy of `skills/repo-setup/templates/plan-terms.md`, and the project's own terms follow them. `/repo-setup sync` compares both blocks with their templates, shows the diff of each block that differs and rewrites it after approval. On a repository with no block yet, it drafts where the block goes and which existing rules or glossary entries it replaces. The same comparison runs on its own (`` is `~/.claude/skills`, or `skills/` in a clone), and `--only glossary` compares the plan-terms block alone, for a repository whose `CLAUDE.md` has no shared-rules block: ```sh python3 /repo-setup/templates/sync_rules.py python3 /repo-setup/templates/sync_rules.py --only glossary ``` An existing repository opts in with `.agents/plan.yaml` at its root. Run `/ordo-init` from the repository root. It drafts the file from the repository and shows it, with any page it would create and the `.gitignore` lines it would add. It writes after you approve. On a repository that already has the file, `/ordo-init` checks it. The same check runs on its own: ```sh python3 /ordo-init/templates/check_config.py ``` To write the file by hand, start from one of the two example files in the plan skill's `templates/` folder: ```sh cp /plan/templates/plan.yaml .agents/plan.yaml # one project cp /plan/templates/plan.projects.yaml .agents/plan.yaml # several projects; a plan is then named / ``` The example `plan.yaml` describes every key. Nine are required: `roadmap`, `verification`, `rules`, `ledger_root`, `archive_root`, `worktree_root`, `worker`, `reviewer` and `libraries`. A skill that needs a missing required key stops and names it. Every other key is optional. A key left out takes the default the comment beside it in the example `plan.yaml` gives. For example, a missing `worktree_paths` means the whole tree, and a missing `look` means that no changed view is opened at landing. Git must ignore `worktree_root` and must not ignore `.agents/plan.yaml`. A plan's verify list is the `verify:` key of the first `yaml` or `yml` block of its `orchestrator-state.md`. It runs through `sh /templates/checks.sh `, from the root of the repository it checks. Each command runs through `bash -o pipefail -c` and passes when it exits 0. Every command runs; each failure is printed after its command's output, and a run with a failure ends with the count of failures. Commands that depend on each other are written as one item joined with `&&`, so the later one runs only when the earlier one passes. Each command in the list exits non-zero when it fails, as written, and a command with long output uses its tool's quiet mode or a filter under `pipefail`. The head comment of `skills/land/templates/checks.sh` states what it prints and its exit statuses. When a plan started an agent, its closing step runs the cost script, which prices the usage of each agent role. It takes each response's counts from the response body Claude Code keeps when `CLAUDE_CODE_ENABLE_TELEMETRY=1` and `OTEL_LOG_RAW_API_BODIES=file:` are set in its settings. Where it kept no body, the script takes the counts from the agents' transcripts and marks the cost as a lower bound. The folder grows with every request and holds each request's prompt. The script takes the folder from `OTEL_LOG_RAW_API_BODIES` in its environment, and otherwise from the `env` key of Claude Code's settings files, the repository's `.claude/settings.local.json` and `.claude/settings.json` and then `~/.claude/settings.json`. A Claude Code tool's shell does not receive the variable, so the closing finds it in the settings. The script runs on its own on any ledger folder, open or archived, with `` defaulting to `~/.claude/projects`: ```sh python3 /plan-orchestration/templates/plan_cost.py [] ``` ## The landing script `skills/land/templates/land.sh` does the cherry-pick and the checks on `main` as one command, run from the repository root as `sh /templates/land.sh - `, `` being the name of the plan's ledger folder. It runs from the `land` skill itself, and nothing is copied into the ledger. `land.sh` reads `worktree_root` and `ledger_root` from `.agents/plan.yaml`, and refuses with exit 64 when either is missing. In the `projects:` form it reads those of the project whose `ledger_root` holds the state file. After main's cherry-pick it runs the verify list through the `checks.sh` in its own folder. It then prints the data for the step's booking in the plan: the diff stat against the base and the staged paths. A ledger file left uncommitted in the worktree, such as a builder's report, never reaches `main`, while one that a commit of the step holds does. `land.test.sh` proves `land.sh` on scratch repositories. The land skill's section "The landing script" in `skills/land/SKILL.md` states the rest, including the refusals and the exit statuses. ## Working on Ordo While Ordo is being changed, the installed skills and agents must not change with it: the plan skills run the change, so they stay at a fixed version until the change is done. The installed skills and agents are links into a pinned checkout, a detached git worktree of the clone at a tag, and the clone's `main` is where the work happens. ```sh git clone https://github.com/TheAxeC/ordo.git ~/workspace/ordo cd ~/workspace/ordo utils/pin.sh v1.1.0 # the worktree ~/.local/share/ordo-stable at v1.1.0, every skill and every agent linked from it utils/pin.sh # checks that every link points into the pinned worktree; changes nothing ``` `pin.sh` links the skills into `~/.claude/skills`, into the `skills` folder of each `~/.claude-*` folder that holds one, and, when `CLAUDE_CONFIG_DIR` is set, into `$CLAUDE_CONFIG_DIR/skills`, each folder once. Each entry in those folders is a link into the pinned worktree, and no folder is linked to another. `ORDO_SKILL_DIRS` replaces that list of folders. `pin.sh` links the agents into these `agents` folders, each once: `~/.claude/agents`, the `agents` folder of each `~/.claude-*` folder that holds a `skills` folder (one whose `skills` folder is a link to another skills folder included), and `$CLAUDE_CONFIG_DIR/agents` when that variable is set. With `ORDO_SKILL_DIRS` set it links the `agents` folder beside each folder the variable names instead. A `~/.claude-*` folder with no `skills` folder gets no `agents` folder. `ORDO_STABLE` moves the pinned worktree to another path. Check mode, `utils/pin.sh` with no tag, changes nothing and fails on each link into the clone and on each link into the pinned worktree for a skill or an agent the pinned tag lacks. Pin mode, `utils/pin.sh `, checks the links first and refuses, changing nothing, a link into the clone for a skill or an agent the tag lacks. It then links every skill and every agent of the tag, replaces each link into the clone, and removes each link into the pinned worktree for a skill or an agent the tag lacks. Moving to a new version is a tag on `main` and `utils/pin.sh `; going back is `utils/pin.sh `. The pinned worktree is never edited, and `pin.sh` refuses to move one that has local changes. A pinned worktree deleted by hand is created again at the next `utils/pin.sh `, through `git worktree add --force`, which leaves the registration of every other worktree of the clone as it is. `pin.sh` also removes the links into Ordo that it finds in `~/.agents/skills`. The head comment of `utils/pin.sh` states the rest: the format of `ORDO_SKILL_DIRS`, what an agent of a tag is, the refusals, the rules for `~/.agents/skills` and the lines each mode prints. `docs/dev/building.md` lists the tests and checks to run before a change is committed. ## License MIT. See `LICENSE`.