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/resource_resolution_model.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 rules auto-included, grouped into a bundle of techniques, 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 workflows/<wf>/techniques/ meta shared layer workflows/meta/techniques/ technique body + rules remaining rules auto-included delivery bundle techniques · 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 rules auto-included, grouped into a techniques / 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-assumptions/TECHNIQUE.md review-assumptions/collect.md nested ref: review-assumptions::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 prefix like agent-conduct can expand to every agent-conduct-* rule. 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-assumptions::collect meta::agent-conduct::file-sensitivity 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 checkpoint fragment refs and to binding-provenance producer scans on step-bound get_technique fetches. Non-borrowed activities keep source scope equal to the session workflow, so behaviour is unchanged outside the borrowed-activity case.

Workflow fragments

Beyond technique refs, a workflow can declare reusable content once under fragments in workflow.yaml and import it by reference:

Resolution follows the same scoping as technique refs: workflow::name resolves only in that workflow's fragments; a bare name tries the declaring workflow first, then meta. Fragment bodies are plain content — a fragment cannot itself contain a reference. The loader materializes refs at load and delivery time, so agents always receive full content, never a ref to resolve. The check:fragments guard rejects inline copies that duplicate a declared fragment.

Delivery at workflow and activity granularity

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

Each bundle groups resolved content into three buckets. When a single technique is delivered, ancestor Initial / Final protocol blocks wrap the technique body recursively and the server renumbers the combined sequence. 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). Ungated step-bound techniques are inlined in document order under step_techniques until the budget would overflow; gated steps and per-activity bundleTechniques.maxChars oversize caps 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; resources referenced inside inlined techniques are never inlined. 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, rules, and unresolved buckets. techniques path → composed body rules auto-included invariants unresolved explicit misses Empty buckets are omitted from the wire response
What a resolved bundle contains. Technique bodies arrive composed; remaining rules ride along; 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 three buckets. get_workflow workflow techniques.workflow core orchestrator set get_activity activity techniques[] workflow techniques.activity core worker set resolved bundle techniques · 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 — never rides along in technique bundles. At delivery time the server rewrites markdown hyperlinks inside a technique into fetchable get_resource refs. The agent calls get_resource only when the running technique actually needs the linked material.

Resource ids support:

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 workflows/<wf>/resources/<slug>.md on demand
Resources stay out of bundles. 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/activity-worker-prompt#worker-brief Loads from meta/resources/ and returns only the worker-brief 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.