# Orchflows: Build self-improving loops in one sentence > Source: > Published: 2026-07-18 17:49:59+00:00 Build a self-improving agent loop in one sentence: ``` Build me a workflow that loops over each project in my GitHub and saves a summary of its open issues. After the loop is done, the workflow runs self-improve on itself. ``` Or don't do that — just ask Claude or Codex for any one-off task of any size, like you normally would. Every request autoroutes to the smallest subagent-driven workflow that can prove it's done: a one-line answer stays a one-line answer; a product-sized build gets a frozen spec, tickets, parallel subagents, and a verification gate. 37 composable skills. Claude Code and Codex, Windows and POSIX. By default the planner/reviewer subagent is Fable 5 on high effort on Claude Code and GPT-5.6 Sol on ultra on Codex; workers are Sonnet 5 on xhigh and GPT-5.6 Sol on high. Think of it as an upgraded, cross-harness Dynamic Workflows. Skill libraries break the same four ways: **Overly specific, handcrafted prompts.** As models get smarter, overprescription degrades output quality.**Manual chaining by the user.** First run`/brainstorm` , then run`/to-prd` , then run... blah blah blah.**Domain-specific.** The workflow for writing a blog is basically the workflow for shipping a feature: outline the goal, build each section in parallel, review the output for cohesion and consistency. You don't need a`/write-blog` skill and a`/build-feature` skill.**Static.** Run 100 hits the same snags as run 1. orchflows answers each in structure: **Tiny, composable skills.** Every word of every skill has to fight for its life. Heavily avoids context rot.**Workflows, not prompts.** Every request autoroutes to the smallest workflow. No more memorizing skill names or chains.**Domain-blind.** Smart model outlines the task → cheaper parallel subagents deliver → smart model reviews. The same shape works for blogs, code, or research.**Self-improving.**`orch-self-improve` can run at any time to mine the logs for friction points in agent behavior and reasoning, and improve the workflows over time.`orch-evolve` is its sibling: a tournament-style improvement loop over any artifact, runnable or static. **One brick, one job.**`orch-deliver` ships,`orch-critique` attacks,`orch-judge` scores blind,`orch-loop` iterates,`orch-fix` proves the cause before repairing it.**One stud pattern.** Six frozen contracts — spec, work-item, delegation, verdict, worklog, pack-signature — are the only interfaces. Anything that emits one plugs into anything that takes one.**Swappable baseplates.** Workflows are domain-blind; a pack (code | content | research | design) is pure data that retargets the whole tower. The pipeline that ships a feature also ships a research report — swap one pack, change zero control flow. You snap bricks by naming them; the agent snaps them by routing. Same bricks either way. ``` git clone https://github.com/DanMcInerney/orchflows cd orchflows ./install.sh # install.cmd on Windows ``` The wrapper resolves an interpreter (uv → python3 → python; any Python 3 works) and auto-detects your harnesses — Claude Code (`~/.claude` ), Codex (`~/.codex` ) — configuring whichever exists. Update: `git pull` , rerun. Committable per-project routing block: `python install.py --project PATH` . Uninstall: `python install.py --user --uninstall` removes only what it generated; `--dry-run` previews either. Just talk. Routing reads the request and picks the smallest shape: ``` > fix the flaky login test # orch-fix: reproduce it, prove the cause, guard the repair > why did memory double last release? # orch-investigate: one read-only lane, answer cited from primary evidence > ship dark mode # orch-spec → orch-deliver: frozen spec, tickets, parallel subagents # on a rolling frontier, one review gate, final verification > build me a custom workflow that reads all the documentation, then researches similar projects, then builds a spec doc to copy their best features and implements them # orch-build: the chain is admitted as a project-local skill, # callable by name from then on ``` Or name the bricks yourself: ``` > orch-loop orch-deliver until `pytest -q` exits 0 > orch-panel these three cache designs — blind judges, pick one > orch-critique src/auth under the security lens ``` Or build your own custom workflow: ``` > build me a workflow that does spec > deliver, then always updates the documentation afterwards (favoring edits and deletions over additions), and automatically PRs and merges it ``` Custom workflows are project-local. In the example above, if you were working in `my-personal-site/` you'd get a workflow named something like `/site-work-and-merge` , callable only when you're working in `my-personal-site/` . Routing too eager? `orch-off` stands it down for the session. The routing law is `rules/topology.md` §2, installed as `~/.orchflows/host-block.md` . Chain any bricks and put `orch-self-improve` last: ``` > my release workflow: orch-investigate what merged since the last tag → orch-deliver the release notes under the content pack → orch-self-improve ``` Every run auto-logs its friction — retries, missing inputs, workarounds — under an always-on law, and `trace.py` logs every session's agent reasoning and secret-redacted tool calls. `orch-self-improve` mines the logs into single-owner proposals you accept or reject. Proposals I've seen in my own usage: - Offload a repeated piece of agent reasoning to a deterministic script - A tiny AGENTS.md addition telling agents to use the packaged Python interpreter instead of whatever `python` is on`$PATH` - Remove overlapping `orch-verify` steps from a workflow to speed it up - Add a documentation-update step to a workflow because the user kept asking for it manually The coolest part of `orch-self-improve` is that you can run it on itself. I run `orch-self-improve` across all sessions in a project, then point a second `orch-self-improve` run at the first one. `orch-visualize` renders anything you hand it as a verified Mermaid diagram — a workflow, your session trace, a codebase, a website, a process from a doc. Every diagram is syntax-verified against a real Mermaid renderer before it comes back, and on request it emits a self-contained HTML page. This is its drawing of the delivery pipeline that ships every orchflows run: ``` php flowchart TD spec["orch-spec — freeze exactly what should be made"] --> pack{"pack: code | content | research | design"} pack --> ws["orch-workspace — clean, isolated working area"] ws --> dec["orch-decompose — cut the spec into ordered tickets"] dec --> frontier["orch-frontier — dispatch every ready ticket"] frontier --> task["orch-task"] task --> del["orch-delegate — hand the ticket to the right agent"] del --> exec["executor: orch-tdd | orch-draft / orch-edit | orch-investigate / orch-synthesize | orch-render"] exec -.-> chk["orch-check — fresh agent double-checks (when needed)"] exec --> integ["orch-integrate — accept or reject the returned work"] chk --> integ integ -.->|rejected| frontier integ --> ver1["orch-verify — run any remaining checks"] ver1 --> frontier frontier --> gate["orch-review-fix — critique, repair confirmed defects, re-verify"] gate --> final["orch-verify — final result matches the original request"] orchflows │ ├── Layer 0 · contracts/ — Shared forms that keep every part of the system speaking the same language │ ├── delegation — Says what another agent should do, use, avoid, and return │ ├── pack-signature — Lists what every project-type setup must provide │ ├── spec — Records exactly what the user wants made │ ├── verdict — Records whether a check passed and what proves it │ ├── work-item — Describes and tracks one piece of work │ └── worklog — Records the progress and current state of a larger job │ ├── Layer 1 · skills/ — Things the agents know how to do │ │ │ ├── kernel/ — Basic building blocks used by the rest of the system │ │ ├── orch-check — Has a fresh agent double-check the work and correct problems │ │ ├── orch-critique — Reviews something and lists the most important problems │ │ ├── orch-decompose — Breaks a large job into smaller pieces in the right order │ │ ├── orch-delegate — Hands one clearly defined task to another agent │ │ ├── orch-elicit — Asks the user when a decision cannot safely be made for them │ │ ├── orch-integrate — Decides whether returned work is acceptable and can be used │ │ ├── orch-investigate — Researches one focused question using reliable evidence │ │ ├── orch-judge — Rates one option using standards agreed on beforehand │ │ ├── orch-mechanize — Turns a repeatedly performed step into a reusable script │ │ ├── orch-synthesize — Combines findings from several sources into one answer │ │ ├── orch-verify — Runs the agreed checks to see whether the work passes │ │ ├── orch-worklog — Updates the job's progress record │ │ └── orch-workspace — Prepares a clean and safe place in which to work │ │ │ ├── engines/ — Reusable ways of organizing work │ │ ├── orch-task — Takes one ready piece of work from start to acceptance │ │ ├── orch-frontier — Starts each piece of work as soon as the work it needs is finished │ │ ├── orch-loop — Repeats work until an agreed check says it is done │ │ └── orch-panel — Uses several independent reviewers to compare choices fairly │ │ │ ├── workflows/ — Complete processes made from the smaller building blocks │ │ ├── orch-spec — Turns a request into a clear, agreed plan │ │ ├── orch-deliver — Runs a project from the agreed plan to a checked final result │ │ ├── orch-goal — Runs the delivery process again to improve the result further │ │ ├── orch-bench — Sets the rules and tests before different options are compared │ │ ├── orch-evolve — Creates and compares improved versions over several rounds │ │ ├── orch-diagnose — Reproduces a problem and finds what is actually causing it │ │ ├── orch-fix — Finds the cause of a problem, repairs it, and proves it stays fixed │ │ ├── orch-repair — Applies the smallest change that fixes a known problem │ │ ├── orch-review-fix — Reviews the result once, fixes valid problems, and checks it again │ │ ├── orch-build — Creates or changes a reusable part of the orchflows library │ │ ├── orch-fixture — Saves a finished task as an example that can be run again later │ │ ├── orch-self-improve — Studies past difficulties and proposes improvements to the system │ │ └── orch-triage — Sorts a list of work into what is ready, blocked, or needs a person │ │ │ ├── instances/ — Skills that perform a particular kind of hands-on work │ │ ├── orch-tdd — Writes software in small steps and checks each step with tests │ │ ├── orch-resolve-conflicts — Decides how to combine two sets of changes that clash │ │ ├── orch-draft — Writes one section using only the supplied information │ │ ├── orch-edit — Combines separate sections into one consistent document │ │ └── orch-render — Builds a screen and checks how it actually looks and behaves │ │ │ └── utilities/ — Small optional helpers │ ├── orch-visualize — Turns supplied information into a diagram │ └── orch-off — Stops orchflows from automatically choosing skills │ ├── Layer 2 · packs/ — Setups for different kinds of projects │ ├── orch-code-pack — Tells the system how to organize, save, and check software work │ ├── orch-content-pack — Tells the system how to organize and review written documents │ ├── orch-research-pack — Tells the system how to answer questions using trustworthy sources │ └── orch-design-pack — Tells the system how to build and visually check interfaces │ └── Layer 3 · compositions/ — Example playbooks showing how the parts can be combined ├── delivery-loop — Repeats delivery until a chosen measurement says to stop ├── drift-canary — Reruns known examples to detect changes in agent behavior ├── evidence-to-document — Researches a subject first, then turns the findings into a document ├── evolve — Produces several versions and selects the strongest one ├── feature-plus-docs — Builds a software feature and then documents what was built ├── improvement-delivery — Turns an approved process improvement into a tested change ├── renovate — Reviews an existing project and completes selected improvements └── skill-tournament — Tests competing versions of a skill to see which works best ``` Four layers, dependencies pointing one way. `contracts/` is the narrow waist: six hash-pinned data shapes that are the only interfaces between skills. `skills/` is everything callable — kernel primitives that call no other skill, engines that add control flow, workflows assembled from both, instances that do the domain's hands-on work, and a couple of utilities. `packs/` is per-domain data, never control flow. `compositions/` is non-normative worked examples, free to churn. ``` UNITS OF WORK — the orchflows ladder │ ├── (floor) Tested script │ no model, no ticket — a unit of certainty, not of work │ orch-mechanize keeps pushing repetition down here │ ├── U0 — Direct answer │ question answered from context already in hand │ no deliverable change → no record, no ticket │ ├── U1 — Verified ad-hoc ticket │ one ticket + one execution + one external verdict │ U1×N: a small ticket graph with edges, run on the frontier │ ├── U2 — The run (spec → delivery) │ a frozen spec governs a ticket graph → rolling frontier → │ one review gate → final verification │ └── U3 — Composition control flow OVER units: chained runs, goal loops ``` Every request lands on the cheapest rung that can still prove it's done. A question you can answer from context costs nothing; a small fix gets one ticket and one external verdict; only work that genuinely needs a frozen spec pays for one; and repetition keeps getting pushed below the floor into tested scripts that need no model at all. ``` packs/ ├── orch-code-pack — delivers code · deterministic oracles · executor orch-tdd │ workspace: git, one worktree per work item ├── orch-content-pack — delivers documents · judged oracles · executor orch-draft, assembly orch-edit │ workspace: document tree with outline slots ├── orch-design-pack — delivers rendered UI · capture oracles · executor orch-render │ workspace: git plus render (view × breakpoint × state) └── orch-research-pack — delivers answers · evidence oracles · executor orch-investigate, assembly orch-synthesize workspace: evidence store of lane packets ``` A pack is pure data — no control flow. It supplies the domain's vocabulary, oracle classes, executors, workspace rules, and design principles, all satisfying one frozen pack-signature, so everything the library builds inside a domain stays cohesive. Stamp a different pack on the spec and the identical pipeline ships code, documents, research, or UI. **Cross-harness.** One library drives both Claude Code and Codex, on Windows and POSIX.**Workflows persist.** A custom workflow is admitted as a project-local skill — versioned, callable by name, improvable — not regenerated from scratch each session.**Verification is structural.** Named oracles, fresh-context checkers, and one review gate stand between an executor's claim and "done" — the agent never grades its own homework.**Self-improving.** Friction and full session traces are always logged;`orch-self-improve` mines them into concrete fixes to the workflows themselves — including to itself.**Survives session death.** Specs, tickets, and worklogs are files in`.orch/` , so any fresh context can resume a run mid-flight.**Smallest-first routing.** One intake for everything: a one-line question never pays workflow ceremony, and a launch never gets typo-fix rigor.