Workflow Server

Technique and resource resolution

Context windows are precious, so definitions arrive at the granularity of need — workflow metadata at get_workflow, one activity at get_activity, one technique per step at get_technique, resources only when a technique cites them. All behaviour is composed from techniques (markdown capability definitions referenced by ::-paths), resolved workflow-first with a shared meta fallback, delivered as bundles, and backed by reference material that loads only on demand.

Canonical source: docs/resolution.md. The normative file anatomy is the technique protocol specification.

Reference resolution A technique reference is resolved by first looking in the current workflow's techniques folder, then falling back to the shared meta layer. The resolved technique's body is delivered with its own rules, its ancestors' rules riding contracts, grouped into a bundle of techniques, contracts, rules, and unresolved references. Resources linked from a technique are rewritten to get-resource references and fetched lazily. [wf::]technique[::sub] a technique reference current workflow corpus/<wf>/techniques/ meta shared layer corpus/meta/techniques/ technique body, own rules ancestor rules ride contracts delivery bundle techniques · contracts · rules · unresolved resources get_resource — lazy, on demand 1. look here first 2. fallback grouped into links rewritten into fetchable refs
Reference resolution. A reference tries the current workflow's techniques first, then the shared meta layer (a same-named local technique shadows the meta one). The resolved body arrives with its own rules, its ancestors' rules riding contracts, grouped into a techniques / contracts / rules / unresolved bundle; resource links inside it are rewritten into get_resource refs and fetched lazily.

One kind of technique

A technique is a markdown file whose slug is its canonical id. There is one kind of technique — standalone files and grouped folders use the same published shape on the wire.

Technique file layouts A standalone technique is a single markdown file. A grouped technique is a folder with TECHNIQUE.md and nested sub-technique files. standalone techniques/plan.md slug = filename grouped review-engine/TECHNIQUE.md review-engine/collect.md nested ref: review-engine::collect
Two on-disk layouts, one delivery model. A nested {sub}.md is a full technique in its own right — not a fragment of the parent file.

References

Activities and workflows compose behaviour by listing ::-delimited references. The path has up to three parts:

A group is a rule-name prefix on a technique: checklist::tidy expands to every tidy-* rule of checklist. Anything that matches nothing lands in the unresolved bucket — never silently dropped.

Reference path anatomy Optional workflow prefix, technique name, optional nested or rule segment, separated by double colons. [workflow::] :: technique :: [nested…] cross-workflow required sub-technique or rule
The general reference form. Slashes in a path are normalised to :: at resolution time.
Example technique references Three example references: bare name, nested sub-technique, and cross-workflow prefixed path. plan review-engine::collect meta::conduct::file-care same workflow nested sub-technique explicit workflow prefix Inline invocations in step text resolve to the same bodies
Example: bare names resolve workflow-first with a meta fallback; nested segments address sub-techniques; a leading workflow segment reaches shared layers explicitly.

Borrowed activities and source-workflow scoping

A workflow may reuse an activity file authored in another workflow — a borrowed cross-workflow activity. Bare technique refs inside that activity (including activity-group shorthand like activity-id::op) resolve against the source workflow the activity file was authored in, not the borrowing session's workflow. Explicit workflow:: prefixes still reach named workflows directly. The same scoping applies to routine references and to binding-provenance producer scans on step-bound get_technique fetches. A workflow's own activities take the session workflow as their source.

Routines

Beyond technique refs, a workflow can declare a run of steps once under routines/ and refer to it from an activity with a kind:routine step. A routine declares what it takes, what it produces and what its own steps pass between themselves, so its body is checked against that signature with no host activity involved. A gate shared on its own is a one-step routine.

Resolution follows the same scoping as technique refs: workflow::name resolves only in that workflow's routines; a bare name tries the declaring workflow first, then meta. A routine may refer to another. A routine file that fails to load excludes only the activities that refer to it, with an error naming the file. The loader materializes references at load and delivery time, so agents always receive ordinary steps and never a reference to resolve — with every identifier the run contributes prefixed from the referring step, so two sites cannot collide on a step id or a replay key. The check:routines guard holds each signature against its body and each routine against the home its referrers compute.

Delivery at workflow and activity granularity

Agents never chain resolution calls at runtime. The server pre-resolves reference lists into bundles when you call:

Some techniques ride only when the loaded definitions show the workflow needs them: the checkpoint pairs for presenting, answering, pausing and continuing when an activity of the workflow declares a checkpoint, the loop rules when one has a loop step, and the fan techniques and rules when the graph fans an exit. Held-back techniques stay reachable by name.

Each bundle groups resolved content into four buckets. Each ancestor container's rules and shared inputs and outputs arrive once under contracts, a technique names those scopes in inherits, and its protocol arrives as authored. In persistent-context mode, reference-not-repeat delivery replaces already-delivered content with { delivery: "unchanged", content_hash } markers; fetch recording warns when a manifested step was never loaded.

Eager step-technique bundling

The lazy per-step model above is complemented by automatic eager bundling on every get_activity call. The worker passes context_tokens — its context window size in tokens — and the server derives a cumulative per-activity character budget:

context_tokens × headroomFraction × charsPerToken (defaults 0.80 × 4; env-overridable). The worker bundle — role rules, contract techniques and their markers — is counted first, and step techniques spend what remains. Step-bound techniques with no gate, or a gate that answers true, are inlined in document order under step_techniques until what remains would overflow; a step whose gate answers false or has no answer at delivery, and a technique over the per-activity bundleTechniques.maxChars cap, stay lazy. maxChars: 0 opts the activity out entirely. Each inlined entry is byte-identical to a step-bound get_technique fetch, including provenance annotations; under reference delivery the bodies of resources the inlined techniques link ride a resources map, and otherwise their ids ride resource_refs for get_resource. Bundled steps are recorded as technique_bundled events and satisfy manifest fidelity checks. Protocol details are in Protocol.

Delivery bundle buckets Resolved references are grouped into techniques, contracts, rules, and unresolved buckets. techniques path → technique body contracts scope → shared block rules role-wide invariants unresolved explicit misses Empty buckets are omitted from the wire response
What a resolved bundle contains. Technique bodies carry their own fields and name their ancestors in inherits; each ancestor's rules and shared inputs and outputs arrive once under contracts; rules that govern the role rather than one technique arrive under rules; unresolved refs are surfaced plainly.
Where each bundle comes from get_workflow and get_activity each union declared references with a core auto-included set, then resolve into the same four buckets. get_workflow workflow techniques.workflow core orchestrator set get_activity activity techniques[] workflow techniques.activity core worker set resolved bundle techniques · contracts rules · unresolved
Two entry points, one bundle shape. Orchestrator and worker each receive the union of what their YAML declares and what the server always includes for that role. Duplicates are deduplicated before resolution.

Resources: lazy by design

Large reference material — CLI guides, templates, API notes — stays out of technique bodies. At delivery time the server rewrites markdown hyperlinks inside a technique into fetchable get_resource refs. Under reference delivery, the bodies of resources that eagerly bundled steps link ride a sibling resources map on get_activity, within the window budget; otherwise their ids ride resource_refs, and the agent calls get_resource only when the running technique needs the linked material.

Resource ids support:

In persistent context mode, or with bundle: "reference" in any session, a byte-identical refetch of the same exact resource_id (bare or sectioned) collapses to an unchanged marker — see reference delivery. Pass full: true to force the full body. A fresh session that does not ask for reference delivery receives the full body.

From markdown link to fetchable ref A technique contains a markdown hyperlink; delivery rewrites it; the agent calls get_resource when needed. technique body markdown hyperlink delivery rewrite callable resource ref agent needs content get_resource corpus/<wf>/resources/<slug>.md on demand
Resources stay out of technique bodies. The technique carries a ref; the agent fetches the markdown file when execution reaches the link.
Example resource fetch A cross-workflow resource id with an optional section anchor. meta/style-guide#headings Loads from meta/resources/ and returns only the headings section
Example: prefixed ids reach shared libraries; #section narrows a large resource to the template the technique actually needs.

How techniques declare inputs/outputs and how binding works is the technique protocol specification; what the resolved bundles look like on the wire is in the tool reference.