/orchestration-envelope

name: orchestration-envelope
user-invocable: false
version: 4.10.0
author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
license: MIT
description: >
  Internal machine-result contract for headless agentic-workflow drivers. The
  executable source is @gtrabanco/agentic-workflow-schema: strict Envelope v2
  for workflow-status, compact SkillOutcome v1 for driven work, compatibility
  parsing, and deterministic document snapshots. Not a menu entry.

Machine result contract (internal)

Interactive skills remain text-first. A headless driver obtains a compact, validated result at the boundary; it does not add a repeated JSON section to every user-facing skill.

The canonical [Turn contract](references/TURN_CONTRACT.md) remains here for the executor and review skills that load it. The workflow's portability preamble has its owner here too: [Portability](references/PORTABILITY.md) — skills cite it instead of copying the preamble.

The executable source of truth is [`@gtrabanco/agentic-workflow-schema`](../../packages/agentic-workflow-schema/): types, JSON Schemas, `renderOutputInstruction(skill)`, `parseTurn(input)`, and `compileWorkflowSnapshot(input)`. This document states the policy only; do not copy a second schema here.

Output profiles

`WORKFLOW_SKILL_PROFILES` is the authoritative inventory.

• `workflow-status` always returns the strict **Envelope v2** sensor result.

Its envelope includes the detailed project view under `detail`.

• The other driver-invoked skills return **SkillOutcome v1** only when the

driver appends `renderOutputInstruction(skill)` to that invocation. It has the small model-owned fields: outcome, next intent/targets, blockers, questions, discoveries, and evidence references.

• `advance` (the companion pi package command) is the conductor, not a worker

profile: it runs as deterministic code over the sensor envelope and never emits a worker SkillOutcome.

• Interactive invocations emit their normal human-readable reports; no driver

result is required.

Both results are one final fenced `json` block. The package rejects unknown keys at the routing boundary. Repository facts are never reconstructed from model prose: the driver compiles `WorkflowSnapshot v1` from its selected, versioned documents and caller-supplied repository facts.

Driver protocol

1. Read the profile and append `renderOutputInstruction(skill)` only for a driven invocation. 2. Pass the final response to `parseTurn({skill, text, context})`. Keep the returned source and diagnostics with the run journal. 3. On an absent, malformed, or invalid machine result, re-invoke the same session once with: `Emit only the machine result for the turn above.` 4. Parse the repair reply. A second failure is driver-level `FAILED`; never retry indefinitely and never turn arbitrary prose into workflow facts.

Compatibility is deliberately narrow: it can repair documented legacy v2 shapes only when the missing value is mechanically knowable. A nonzero issue count without issue identities, an unmatched numeric unit id, or unrelated prose remains invalid and is surfaced to the driver.

Contract evolution

• Envelope v2 is strict for new drivers. `detail` is required (usually `null`)

and skill-specific extensions live inside it; `design_candidates`, for example, is `detail.design_candidates`, never a root key.

• `workflow-status` retains Envelope v2 for existing sensor consumers.

`parseEnvelope()` remains the legacy-compatible package API; new consumers use `parseEnvelopeV2Strict()` or `parseTurn()`.

• `SkillOutcome v1` and `WorkflowSnapshot v1` are separate, versioned JSON

Schemas. A breaking change to any published contract is a package major.

Normalized Repository State

Drivers call `discover-repository-state` before planning and retain the frozen `docs/workflow/REPOSITORY_STATE.md` reference. `WorkflowSnapshot v1` preserves unknowns, provenance, and declared contradictions; a driver routes a contradiction to `resolve-repository-state` rather than silently replacing it.