Deliverables
Current state — 2026-08-29
Part of this framework is not connected today, and the pages below still describe some of it as if it were. Read this first.
What exists: deliverable specs and their kinds, the targetSlot workspace
contract, and the xema/validate-deliverables action (a real server-side
verdict over artifact ids you supply).
What does not: the automatic harvest of workspace files into artifacts. The
harvester was deleted on 2026-08-29, so no file an agent writes into its
workspace becomes an artifact. The xema/agent job output deliverables went
with it — xema/[email protected] no longer declares it, and there is no singular
deliverable output either. An expression naming either one resolves against a
field the action does not have.
What a workflow agent job produces today is its structured handoff —
structuredOutput, the JSON the session posts to the handoff endpoint. It is
promoted to a json_payload artifact carrying artifactId, versionId,
version, hash and type. That is the one artifact the job emits. The
response output is declared but is always null, because the handoff path
produces no closing message.
There is no agent-job → KB-page path today. xema/publish-kb resolves an
artifactId by reading payload.body from the artifact version and refuses
other shapes; a json_payload handoff artifact carries no body. Its inline
markdown input still works for content the workflow supplies itself.
Any YAML below that reads outputs.deliverables or outputs.deliverable is
stale and will not resolve to what the surrounding prose claims.
A deliverable spec describes what an agent must produce on a given workflow step: a multi-page document, a JSON payload, a direct response, code emitted into a working repo, or anything else with a typed contract. The deliverables framework owns the contract surface that ties workflow YAML, agent runtime, and downstream consumers together — one envelope for every kind, one canonical access path, and one server-side validator every workflow can branch on.
Quick Links
| Page | What it covers |
|---|---|
| 01 Concepts | The seven deliverable kinds, the targetSlot choice, response-only vs file-emitting |
| 02 Authoring | Declaring with.deliverableSpecRef in a workflow; literal vs expression form; matrix fan-out for variable count |
| 03 Output Envelope | The canonical agentResult.deliverable shape and how downstream YAML expressions read it |
| 04 Validation | Harvest-time discovery, the xema/validate-deliverables action, issue codes, and branching on the verdict |
| Reviewer Output | The review-verdict deliverable shape and how the reviewer kernel emits it |
| Examples | End-to-end YAML for each kind plus a mixed-kind matrix dispatch |
Getting Started
Read in order if you're new to the framework:
- Concepts — what a deliverable spec is and which kind fits your job.
- Authoring — how to wire it up in a workflow YAML.
- Output Envelope — how downstream jobs consume it.
- Validation — how a produced deliverable is checked against its spec, and how a workflow reacts.
FAQ
Q: My job needs to produce N deliverables of different shapes (e.g. five microservices + one frontend). How?
A: Matrix fan-out. The upstream step (typically a clarification agent) emits a typed array of build targets, and the downstream matrix job iterates one job per entry. Each iteration resolves its own deliverableSpecRef from the matrix entry. See 02 Authoring and Examples · Matrix mixed kinds.
Q: How do I know if validation failed?
A: Add an xema/validate-deliverables job downstream of the producing job. It returns verdict: pass | warn | fail plus an issues[] array, and both are ordinary job outputs — read them from an if: gate, publish them, or forward them. See 04 Validation.
Q: What happens when the agent produces the wrong thing?
A: Nothing terminates on its own. The harvester records warnings and returns no structured value; xema/validate-deliverables returns verdict: fail and the job still succeeds. What a failing verdict means is a decision the workflow author writes — publish an issues report, gate the next job, or run a second producing job with issues[] as input.
Q: Can I produce code (files) into a working repo?
A: Yes — set targetSlot: { kind: 'repos', repoSlug: '<your-repo>' } on the spec. The harvester writes into repos/<slug>/ instead of the default deliverables/ slot. Use the custom kind for arbitrary file lists or document for templated docs.