Orchestration Envelope

Machine envelope (internal contract)

Every user-invocable skill in this pack ends its turn with one fenced json block — the envelope — printed after the closing → Next: block, as the absolute last output of the turn. Internal skills (the review pack, the plan-feature steps, this one) do NOT emit it: they return their fixed completion reports to the composing caller, and only the outermost user-facing skill emits the single envelope for the whole turn.

Parse contract for orchestrators: take the last fenced ```json block of the final assistant message. Exactly one envelope per turn.

Schema (all top-level keys ALWAYS present — use null / [] / 0 when n/a)

{
  "skill": "",
  "state": "OK | CONTINUE | READY_FOR_REVIEW | READY_FOR_AUDIT | MERGE_READY | MERGED | NEEDS_FIXES | BLOCKED | NEEDS_INPUT | FAILED | HALT",
  "summary": "",
  "unit": {"type": "feature | fix | docs | none", "id": "", "issue": null, "branch": ""},
  "phase": {"current": "", "total": null, "completed": null},
  "pr": {"number": null, "url": null, "state": "open | merged | none", "head_sha": null, "merge_ready": null, "ci": "green | red | pending | none | null"},
  "gates": {"verification": "green | red | not-run | null", "review_pending": null, "audit_pending": null},
  "findings": {"fix_now": [], "issues_filed": [], "untriaged": 0, "decisions_recorded": 0},
  "blockers": [],
  "dependencies": {"unmet": [], "build_order": []},
  "recommendations": {"product_audit": false, "reason": null},
  "needs_input": null,
  "next": {"recommended": "", "alternatives": [], "tier": "strong | cheap"},
  "detail": null
}

Field rules — checkable, no interpretation:

• state (the orchestrator's routing key — exactly one of the 11):
• OK — the skill's job finished; nothing pending from it. Follow next.
• CONTINUE — same unit has more of the same work (next phase, next loop

iteration). Re-invoke per next.recommended.

• READY_FOR_REVIEW — implementation checkpoint or unit end; review-change

is the mandatory next step (gates.review_pending: true).

• READY_FOR_AUDIT — review clean; audit-pr is next.
• MERGE_READY — audit passed; the human (or the documented auto-merge

policy) merges. pr.merge_ready: true.

• MERGED — an authorized auto-merge was executed this turn.
• NEEDS_FIXES — findings/blockers exist that fold into the CURRENT branch

(findings.fix_now non-empty); fold, then re-run the gate that sent them.

• BLOCKED — cannot proceed; blockers says why and dependencies gives

the build order when the cause is an unmet dependency.

• NEEDS_INPUT — a decision only the human can make; needs_input.question
• needs_input.options filled. Nothing was guessed.
• FAILED — an error the in-skill retries didn't clear (red gate past its

cap, unrunnable substrate). A human looks before anything continues.

• HALT — stop-the-world: a discovery that invalidates continuing ANY

unit (critical security hole in merged code, broken substrate invariant, data-loss risk). Every blockers[] entry carries "scope": "run". The orchestrator must stop the whole run and surface it, not just park a unit.

• findings — fix_now is an array of objects

{"ref": "F1", "title": "…", "file": "path:line"} (they have no issue numbers yet); issues_filed is an array of issue numbers (integers) created/updated this turn; untriaged counts findings still without a destination (must be 0 when the skill's own contract requires routing all).

• blockers[] — objects

{"kind": "dependency | issue | gate | merge-conflict | substrate | input", "id": "", "scope": "unit | run", "detail": ""}.

• dependencies — unmet: roadmap ids / #issue refs whose merge must

land first; build_order: deepest-first order to unblock (mirrors execute-phase's dependency-gate output).

• next.tier — strong when the recommended command is judgment work

(plan / review / audit / triage), cheap when it is mechanical execution. This is the model-routing hint for the orchestrator.

• detail — optional skill-specific payload (object), documented in the

emitting skill's ## Machine envelope section; null otherwise.

• Truthfulness: every value reflects what actually happened — sha/PR/issue

numbers pasted from real command output, never invented. A value you did not verify is null, not a guess.

• Placement: fenced ```json, ONE object, absolute last output — nothing

after it, not even a sign-off line.

Companion npm package (keep it in sync)

The schema ships as @gtrabanco/agentic-workflow-schema (packages/agentic-workflow-schema/ in this repo): TypeScript types, a JSON Schema, and parseEnvelope() implementing the last-fenced-json parse contract. Any change to the schema in this file changes the package in the same PR — update src/index.ts + envelope.schema.json + tests, and bump the package version by the contract's own semver (key/state removed or renamed → major; additive key/state → minor; fixes → patch). CI (.github/workflows/publish-schema.yml) publishes to npm automatically on merge when the version is new. A schema change that skips the package is an incomplete change.

Relationship to other skills

• Every user-invocable: true skill of the pack carries a `## Machine

envelope section stating which states it can emit and what it puts in detail`; this file is the single source of truth for the shared schema.

• workflow-status is the read-only sensor that emits the richest envelope

(full feature/fix dependency tree in detail).

• docs/workflow/ORCHESTRATION.md documents the external driver loop

(state → next command → model tier) that replaces Claude Code's /loop and subagents on any agent.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: gtrabanco
• Source: gtrabanco/agentic-workflow
• License: MIT

Install and usage instructions live in the source repository linked above.