orchflows

Delete your skill libraries. You only need two skills.

Compose these skills into infinitely complex, task-specific workflows, including self-improving loops.

Work makes a result. Review independently judges it. Everything else is composition.

Why

Skill libraries keep growing around a model's current limitations. gstack packages a prescribed engineering sprint and specialist roles. Matt Pocock's skills encode practices such as grilling sessions, test-first development and debugging gates. Superpowers specifies a mandatory development process, down to task size and review stages.

Our objection is overprescription. Too much of the agent's judgment has already been made for it: how to investigate, how small to divide the work, when to stop and ask, which sequence to follow. That makes a workflow inflexible and its execution less adaptive to the task. These libraries offer customization, and some already separate model overrides; the problem is how much procedure remains embedded in the skills themselves.

Overprescription also ages badly. A workaround for one model can become unnecessary ceremony for the next. A model that can now reason through a whole change still gets marched through steps written for one that could not. When those corrections are scattered across skills, every model release invites another round of workflow rewrites.

Orchflows abstracts prescription into guidance and guidance extension documents. The two skills handle making and reviewing. Workflows describe the relationships between those operations. Separate, modular documents hold domain preferences, task specializations and corrections for model weaknesses.

When a new model no longer needs a correction, delete it from the guidance or extension document. Keep the preferences you still care about. The two skills and your workflow structures stay unchanged across model upgrades; model-related churn belongs in these modular guidance documents.

Install

Requires Python 3.11+ and Codex or Claude Code with native subagents.

git clone https://github.com/DanMcInerney/orchflows.git
cd orchflows
python scripts/orchflows.py setup

Run the two commands for your host:

# Codex
codex plugin marketplace add ~/.orchflows
codex plugin add orchflows@orchflows-home

# Claude Code
claude plugin marketplace add ~/.orchflows
claude plugin install orchflows@orchflows-home --scope user

Start a new session. Setup options · Host registration and invocation.

Usage

Describe the task. If you do not supply a workflow, Orchflows prefers a specific match when one fits; otherwise /orch-dynamic-workflow composes the smallest useful workflow for the task.

Simple task. The coordinator makes and verifies an already-clear change directly. One independent child reviews it. This is the smallest dynamic workflow, shown with no repairs needed:

flowchart LR
    W["Coordinator<br/>Make and verify"] --> R["orch-review<br/>Independent review"]
    R --> D([Deliver])
    classDef work fill:#ecfdf5,stroke:#059669,color:#064e3b,stroke-width:2px;
    classDef review fill:#f5f3ff,stroke:#8b5cf6,color:#4c1d95,stroke-width:2px;
    classDef result fill:#f8fafc,stroke:#94a3b8,color:#0f172a;
    class W work;
    class R review;
    class D result;

Larger task. Independent workers run in parallel, their results join, and one reviewer assesses the combined work. When fixes are needed, an existing or new worker can implement them:

flowchart TD
    T([Task]) --> A["orch-work<br/>Worker A"]
    T --> B["orch-work<br/>Worker B"]
    T --> C["orch-work<br/>Worker C"]
    A --> J[Join and verify]
    B --> J
    C --> J
    J --> R["orch-review<br/>Review joined result"]
    R -->|Fixes needed| F["Worker<br/>Implement fixes"]
    R -->|No fixes| D([Verify and deliver])
    F --> D
    classDef work fill:#ecfdf5,stroke:#059669,color:#064e3b,stroke-width:2px;
    classDef review fill:#f5f3ff,stroke:#8b5cf6,color:#4c1d95,stroke-width:2px;
    classDef coordinate fill:#eff6ff,stroke:#3b82f6,color:#1e3a8a;
    classDef result fill:#f8fafc,stroke:#94a3b8,color:#0f172a;
    class A,B,C,F work;
    class R review;
    class J coordinate;
    class T,D result;

There is one repair pass with verification, without another review. The coordinator can also make clear fixes directly. Calling orch-work alone creates just one worker; the dynamic workflow includes independent review.

Custom workflows. Use /orch-build-workflow to turn a recurring task into a reusable workflow. It drafts the composition, tries it on real work, and refines it before independent review:

flowchart LR
    A([Recurring task]) --> W[Draft workflow]
    W --> T[Run a real trial]
    T -->|Refine| W
    T -->|Ready| R[Independent review]
    R --> D([Fix, verify and save])
    classDef work fill:#ecfdf5,stroke:#059669,color:#064e3b,stroke-width:2px;
    classDef review fill:#f5f3ff,stroke:#8b5cf6,color:#4c1d95,stroke-width:2px;
    classDef coordinate fill:#eff6ff,stroke:#3b82f6,color:#1e3a8a;
    classDef result fill:#f8fafc,stroke:#94a3b8,color:#0f172a;
    class W work;
    class R review;
    class T coordinate;
    class A,D result;

Register the saved library with your host to invoke its workflows by name.

Models and effort. Give Work and Review optional defaults, then override any named assignment—even the final fixer:

Work: gpt-5.6-sol at medium. Review: gpt-6-astra at high. Worker B: high. Final fixer: gpt-6-astra at xhigh.

Use models and effort levels supported by your host. This works for dynamic and saved workflows. To save these preferences, ask /orch-build-workflow to keep them beside the assignments in SKILL.md. Your current request overrides saved preferences field by field; settings absent from both use native defaults. A worker with different settings runs separately when the host cannot change an existing agent. Resolution and host controls.

Design

Start with work and independent judgment

Give an agent a result to produce, then give another agent the result to assess. Keep the assignment specific and let the model choose how to do the work. Add instructions where you have a deliberate preference or an observed failure to correct.

A reviewer can inspect code, judge a film, rank evidence or compare competing designs. The subject changes; the two operations do not.

Compose the task

A workflow is a SKILL.md that connects these operations: what can run in parallel, what depends on what, what gets reviewed, and whether the result feeds another round. It supplies assignments, context and outputs. The same primitives support a single review, a research team, a production pipeline or an improvement loop.

The package includes three ready-made compositions: dynamic work, workflow building and self-improvement from agent history. They compose the two primitives and show how to write your own. A workflow declares its agent count and any repetition; loops are part of the requested workflow.

Codex or Claude Code runs the agents. Orchflows adds no agent runtime, scheduler or workflow language. Loading a workflow applies its instructions in the current context; calling a primitive launches a child.

Supply guidance separately

Guidance describes what good work means in a domain. Each document has a Make section for production and a Review section for assessment. For example, code guidance can require independently runnable tests; visual guidance can require inspection of the rendered result.

Select only the domains the task needs. A film might use writing, visual-design and short-video. A coding task might use code and code.api. The workflow's structure stays the same when its selected guidance changes.

Extend only the differences

Guidance extension documents specialize a domain. code.api.md extends code.md; short-video.marketing.md adds marketing preferences to short-video.md. A brand can add short-video.marketing.<brand>.md. Each extension states what it adds or changes, without copying its parents.

Your libraries can also extend an existing domain with a guidance/code.md of their own. Keep corrections for a particular model separately removable in such a library. When the correction stops helping, remove the instruction or deselect that library. Model names do not become new domain names.

The outer workflow resolves guidance once, from general to specific. At each level it reads core guidance, then selected libraries in the supplied order. More specific guidance takes precedence within its domain; independent domains combine. Resolved paths and request context pass through to the workers and reviewers. See guidance selection for the complete contract.

Example workflows

These examples show parallel collection, creative production and improvement using the same two skills. Social search, Short video and Evolve are optional libraries: add one with python scripts/orchflows.py setup --example <name>, then install it through your host. Each library documents its tool dependencies. Self-improve is included in the core installation.

Social search

Research how developers are using coding agents. Search GitHub, Hacker News and Reddit, then rank the strongest evidence.

Social search tackles the same kind of research as last30days, which bundles source integrations, parallel search and engagement scoring into a dedicated research engine. Social search builds collection and independent assessment from smaller, reusable workflows. Your prompt sets the sources, dates and bounds.

Each source search is itself a workflow. The reusable search-site workflow composes orch-work, source guidance and an evidence handoff. It can run alone or become one branch of social-search. The current library supplies guidance for Reddit, Hacker News, GitHub, X, YouTube, Lemmy, web search, and RSS/Atom feeds; other accessible sources use general guidance. These are instances of the same workflow with different guidance.

social-search composes the selected searches in parallel, gathers their evidence and gaps, then calls the separate rank-evidence workflow, which composes orch-review:

flowchart TD
    Q(["social-search<br/>Question and source scope"]) --> G["search-site<br/>GitHub"]
    Q --> H["search-site<br/>Hacker News"]
    Q --> R["search-site<br/>Reddit"]
    Q --> S["search-site<br/>Other selected sources"]
    G --> E[Gather evidence and gaps]
    H --> E
    R --> E
    S --> E
    E --> J["rank-evidence<br/>orch-review"]
    J --> O([Ranked, cited assessment])
    classDef work fill:#ecfdf5,stroke:#059669,color:#064e3b,stroke-width:2px;
    classDef review fill:#f5f3ff,stroke:#8b5cf6,color:#4c1d95,stroke-width:2px;
    classDef coordinate fill:#eff6ff,stroke:#3b82f6,color:#1e3a8a;
    classDef result fill:#f8fafc,stroke:#94a3b8,color:#0f172a;
    class G,H,R,S work;
    class J review;
    class E coordinate;
    class Q,O result;

N collection assignments use N workers and one reviewer. Shared original sources have one owner; missing or failed collection stays visible as a gap. Source-specific guidance shapes collection; shared research and writing guidance shapes the final assessment.

Short video

Make a 30-second launch film for this product. Deliver the editable project and the finished video.

Short video gives one maker the brief, then sends the actual rendered exports to a fresh reviewer. Genre, placement and brand requirements come from the brief and selected guidance.

flowchart LR
    B([Brief and selected guidance]) --> M["orch-work<br/>Make film"]
    M --> E[Editable project and exports]
    E --> R["orch-review<br/>Inspect exports"]
    R --> D([Deliver film, source and findings])
    classDef work fill:#ecfdf5,stroke:#059669,color:#064e3b,stroke-width:2px;
    classDef review fill:#f5f3ff,stroke:#8b5cf6,color:#4c1d95,stroke-width:2px;
    classDef result fill:#f8fafc,stroke:#94a3b8,color:#0f172a;
    class M work;
    class R review;
    class B,E,D result;

One film uses one maker and one reviewer, including its placement versions. Additional films can run in parallel. The composition ends after review; a repair round is a separate requested step.

Evolve

Improve this game's performance for an hour while preserving gameplay. Also improve how you search for optimizations.

Evolve starts with an artifact or creation brief. It designs an evaluation when none is supplied, makes a challenger, independently compares it with the current best, and retains only confirmed improvements. Every experiment saves evidence and a checkpoint.

flowchart TD
    S([Artifact or creation brief]) --> E["Establish evaluation<br/>and current best"]
    E --> C[Choose experiment]
    C -->|Artifact| M["orch-work<br/>Make challenger"]
    M --> R["orch-review<br/>Compare artifacts"]
    R --> K["Retain best<br/>and checkpoint"]
    C -->|Harness| H["orch-work<br/>Propose harness change"]
    H --> T["orch-work<br/>Separate makers test each harness"]
    T --> J["orch-review<br/>Compare outputs"]
    J --> K
    K --> B{Continue?}
    B -->|Yes| C
    B -->|No| O(["Best artifact, evidence<br/>and resume path"])
    classDef work fill:#ecfdf5,stroke:#059669,color:#064e3b,stroke-width:2px;
    classDef review fill:#f5f3ff,stroke:#8b5cf6,color:#4c1d95,stroke-width:2px;
    classDef coordinate fill:#eff6ff,stroke:#3b82f6,color:#1e3a8a;
    classDef result fill:#f8fafc,stroke:#94a3b8,color:#0f172a;
    class M,H,T work;
    class R,J review;
    class E,C,K,B coordinate;
    class S,O result;

The working harness is the maker instructions, tools and search strategy used by the run. Evolve can test a change to that harness against its predecessor, then use the verified revision in later rounds. Its coordinating evaluation and promotion rules stay fixed during that comparison. Harness experiments use one proposer and two fresh makers per test case, with independent review of their outputs. A subjective winner requires confirmation from a second fresh reviewer.

The default is three rounds with one challenger per round. A continuous request removes the round cap; the host must keep executing or resume the checkpoint. A plateau changes the search strategy. It does not prove the artifact cannot improve.

Self-improve

/orch-self-improve Review this session and improve the workflows and guidance behind the problems you find.

orch-self-improve learns from native agent history. Scope it to a session, period or project; by default it uses the current session. It checks whether an observed problem still exists in the current source or environment, then makes the smallest useful correction to local setup, custom workflows, guidance or Orchflows itself.

flowchart TD
    H[Inspect selected agent history] --> C[Check current source and environment]
    C --> W["orch-work<br/>Make a focused correction"]
    W --> T[Try it on bounded real work]
    T --> R["orch-review<br/>Independent review"]
    R --> D([Changes, checks and evidence])
    classDef work fill:#ecfdf5,stroke:#059669,color:#064e3b,stroke-width:2px;
    classDef review fill:#f5f3ff,stroke:#8b5cf6,color:#4c1d95,stroke-width:2px;
    classDef coordinate fill:#eff6ff,stroke:#3b82f6,color:#1e3a8a;
    classDef result fill:#f8fafc,stroke:#94a3b8,color:#0f172a;
    class W work;
    class R review;
    class H,C,T coordinate;
    class D result;

Ask for a report only to stop after inspecting history. An improvement pass includes a bounded trial and independent review, with findings tied to agent and event references. Missing history stays visible as a gap. Corrections go into the owning checkout or user library.

Structure

One concept, one owner. Put each instruction, fact or mechanism in one place and reference it everywhere else.

The repository follows those boundaries:

skills/             two primitives and three built-in compositions
guidance/           domain preferences and extension documents
docs/               shared architecture and operating contracts
scripts/ + tests/   core setup, resolution and history tools
example-workflows/  optional libraries and runnable examples
plugin.json         package identity

The core checkout is for library development. Your editable libraries live in ~/.orchflows/libraries/, with personal as the default for new workflows. Setup maintains the installed core under ~/.orchflows/.local/. Edit the checkout or your libraries; keep task outputs in the project workspace.

The examples directory also includes research-acquire for public-source acquisition, 3d-browser-game for Three.js game development, and the complete Nightbind game with editable Blender sources.

Architecture · Home and updates · Host integration · Agent history · Authoring guidance