ObneyAI/orc / orc-skills/orc-compose-specialists
orc-compose-specialists
VerifiedImplement or review hand-assembled ORC workflows with reusable specialist sheets, bounded revisits, semantic routing, retained parallel work and explicit typed delegate seams.
Compose ORC specialists
Use this once the tree's goals and specialist boundaries are clear. Read specialist design for goal-based boundaries, recursive composition and the research reading route; return to orc-design-tree if those choices are unresolved. Read ORC’s tracked agent instructions and principles, then inspect the current orc-service public interface and DSL implementation. Check branch/revision; older app examples and guides can contain stale signatures.
For repeated goal solving, read the authored controller. It gives the executable child repetition structure, inherited tick ceiling, fresh-invocation reconciliation and terminal business outcome contract. Use context flow when one specialist requests information and another must answer before the original obligation resumes.
Make control boundaries observable
Code leaves own bounded policy, transforms and effect capabilities. When work needs independently durable progress, an eligible alternative, a focused revisit or an observable recovery execution, expose that control boundary in ORC rather than hiding the entire controller inside one code leaf or the host. Several calls needed for one guarded effect can still be one capability; this is not a node-count target.
Read control boundaries when hardening a workflow. It distinguishes ORC parallelism from futures inside a leaf, per-check event progress from a post-join snapshot, semantic agreement from method readiness, and recovered application state from an ORC recovery trace. Retrieve missing sections after a truncated relevant read before relying on it.
Build from the leaves upward
Use orc-tools when specialists expose tool capabilities, models prepare dynamic arguments, or later actions depend on earlier tool observations. Its catalog and caller guidance complements the delegate seams here.
- Give each specialist a stable, versioned workflow name, its own typed blackboard, a useful output contract, and local failure/recovery behavior. Make a child runnable by itself before its parent uses it. Identify its preconditions, supported outcome/evidence, partial and unavailable cases, effect authority, freshness and recovery budget. Its result must be useful independently of the next parent node; pass purpose/source criteria as typed runtime inputs rather than embedding one caller’s vertical taxonomy in the reusable method.
- A child may itself delegate: construct the dependency graph and build grandchildren, then children, then the root. Build each dependency once and pass its returned sheet ID to parent
delegatenodes through:target-sheet-id. This is nested composition, not proof of arbitrary self-referential delegate cycles. Build definitions at startup, reuse stable definitions during runs, and avoid rebuilding a sheet name with differing content while ticks are active. ORC derives stable identities and unchanged builds are no-ops; a changed definition under one name can replace node content. - At each delegate seam, enumerate exact
:readscopied into the isolated child blackboard and exact:writescopied from child outputs into the parent. The seam does not provide arbitrary renaming or coercion. Input transfer uses key names, so qualified keywords may collide; current builds reject colliding delegate reads rather than silently accepting them. Verify actual transferred keys and prefer explicit shared vocabulary. If parent and child vocabularies differ, add an explicit transform or align the contract. Use structured Malli schemas for LLM-produced maps and assert that the parent projection receives a parsed map. - Route a typed semantic assessment through exact guards to the selected code tool or delegate. Use
llm-decisionfor boolean/enums,llm-conditionfor predicate eligibility, or ordinaryllmfor dynamic structured outputs. Registered native providers select the supported decision protocol; custom code clients remain for unsupported primitives. For bounded choices, consult orc-decision-models. Model-calling code capabilities need explicit client model configuration and accounting. Put effects in named, injected capabilities; treat tool calls as actions that need observable outcomes. Never match words or phrases in human or AI messages to infer intent or quality, and never use canned response templates to supply the specialist’s knowledge work or hide failure. Use semantic judgments; deterministic parsing needs a concrete literal protocol contract.repl-researchertool injection is for its open-ended exploration, not a prerequisite for hand-assembled action routing. - Own parallel writes: siblings must not write the same shared key, including reasoning fields. For parallel
map-each, use a primitivellmorcodeleaf with explicit:writes. A failed item can yield:partialand a compacted result vector; locate the missing item through event/trace evidence, and never present the vector as complete by index alone.
Same-state question batching is distinct from ORC parallel specialists and concurrent effects. A batch may precompute finite arguments for every hypothetical tool; consume only the selected tool's heads and validate the combination before dispatch. A checker needs the actual artifact it judges, or explicit hypothetical candidate context. Refresh state after dependent effects, keep write ownership separate, and revalidate queued work. Put tool-failure recovery inside the selected method or an explicit recovery route so a failed tool does not accidentally dispatch a different unrelated tool. See decision patterns.
Make dispatch and recovery eligibility explicit. A guarded specialist route is not a general alternative-method policy; a failure must stay within that capability’s declared recovery unless another method demonstrably satisfies the same goal. Guard clarification/no-tool branches so a failed selected effect cannot produce false success.
For one planned revision, adapt the two-attempt repair example. For repeated known-specialist selection, use an isolated controller child ending with :check {:key :settled? :op :equals :value true :on-fail :running}. A code return supplies writes; the condition supplies the Running status. Stop with an honest business outcome before the effective engine cap, and give every ancestor enough remaining iterations. See the controller reference for exact DSL and budgets.
After a selected subtree or parallel join, reassess the full goal from actual artifacts, qualified evidence and projected effects. A finite semantic choice can select satisfied, revise-owner, consult-known-specialist, wait or handoff; generate feedback only when the next action needs it. Revisit with a fresh invocation ID and the original obligation, relevant prior draft, matched new answer and current feedback. Merge only that invocation's outputs. Keep healthy independent work outside the repeat boundary, or guard completed obligations inside it; reconcile stable effect identities before repeating mutations.
A valid typed recommendation can precede the authority needed to apply it. At a planning boundary, preserve that recommendation and return an owned missing-precondition status before any effect; let the semantic controller arrange consultation and revisit the same specialist with matched authority. Distinguish wholly absent planning authority from partial or mismatched returned authority, which must still be refused. Do not repair stage ordering by rewriting model output or weakening effect guards. Read planning-stage authority when analysis and action application share a child boundary.
At every composite, write the parent's postcondition and check that a successful child actually establishes it. In ORC, a :partial child stops a fallback and allows a sequence to continue, so specify partial-data contracts explicitly. A negative llm-condition result and a provider error both become node :failure; use a typed decision with an inspectable reason when those cases need different routes. For parallel, select :success-policy and :failure-policy deliberately and verify what already-started siblings may still do after the parent completes. Classical BT design patterns and ORC's execution differences are summarized in behavior tree assembly.
Delegates inherit execution capabilities and share the root family call budget and remaining deadline; child iteration caps are bounded by the parent's remaining iterations. Verify the effective absolute deadline when strict expiry matters: the local, unmerged deadline repair (historical local experiment; private archive not bundled) prevents dispatch delay from renewing the parent cap. That cap bounds provider admission, not arbitrary-code execution or blocking caller wait. Use get-family-usage and verify descendant effects. A successful fallback can still violate grounding: preserve an unavailable source's actual reason and verify the recovery postcondition.
For configured model failover on merged ORC 4966c8e35e3bb5939570bfc645eac52a8d18eb6e, use :fallback-models and :fallback-policy on existing llm, llm-condition, llm-decision and repl-researcher nodes. Read configured model fallback for provider registrations, researcher-role inheritance, durable selection, retry accounting and the first-visible-output stream boundary. No separate fallback node or application parser is required. Keep completed tools outside model-request retries and switch only the same typed task after an exact owned eligible failure. A valid false answer is success, and schema failure or ineffective tool selection is not an outage. The scoped alternative reference remains historical consumer evidence, including concurrency, no fixture-tool replay and budget exhaustion; it is not the recommended new-node configuration API.
At code/delegate boundaries, handle absent values explicitly, return all declared code writes on every successful branch, and obtain injected capabilities from the received execution context. A branch-dependent receipt is better represented inside a typed outcome than as an unconditional non-null write. See boundary errors.
Verify the assembled tree
Apply the repo's Allium and TDD loop for observable behavior. Prove one child through its public execution boundary, then parent-to-child input transfer and output return, then a real model and real Grain/event-store run with projection read-back. Induce a child failure and verify status, parent fallback behavior, lineage, and persisted inputs/outputs. Check actual node and tick events rather than trusting execute's return map alone. For recursive delegation verify every parent/child/grandchild lineage and read/write boundary, child blackboard isolation, and reuse by a second caller. Induce a grandchild failure and prove which recovery is eligible and that no unrelated effect ran. Keep bounded live runs and report unavailable external verification plainly.
For revisits, prove A → B → A with the second A's actual fresh inputs, stable obligation identity, unaffected sibling execution count and matching projected effects. Distinguish a useful unresolved business result from node failure and goal achievement. Source pins and implementation proof limits are in the controller reference.
Compose reusable judges
Use orc-judges when a specialist is itself an evaluator or needs monitoring. A custom judge can sequence evidence tools, delegate to criterion specialists and parallelize independent audits before choosing a band. Declare each audit's outputs and pass actual artifacts/effects, not self-reported success. Distinguish ordinary nested judge behavior from attaching a judge to judge executions; the latter needs durable origin/recursion prevention and is unsafe to assume from transient context depth.
Verify adverse family completion
Verify all started root/child/grandchild terminal facts and traces under the application's relevant failure or cancellation path. A timeout is not proof of the promised cancellation outcome. Consult revision-specific proof limits rather than assuming an old defect persists or a happy-path run proves recovery.
Compose an adaptive child stage
A specialist may contain a recursive researcher while exposing a stable typed output contract to callers. Use orc-repl-researcher for generated work, tool contracts, completion checks and focused repair. Authored delegation remains the reusable composition seam; emitted delegate/nested-researcher tags are unsupported at the inspected pin. Use pattern reuse for design guidance, then separately review/register a generated method if it should become a callable specialist.
For instruction improvement, an explicit metric may invoke the composed judge with a fixed goal and exact execution evidence. Read judge/GEPA readiness before consuming its band and feedback; working judge composition does not prove optimizer attribution or failure handling.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |