orchestration-envelope
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.
How do I install this agent skill?
npx skills add https://github.com/gtrabanco/agentic-workflow --skill orchestration-envelopeIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill defines an internal machine-result contract and protocol for agentic workflows. It provides a structured turn contract for git operations and schema-based output profiles. No malicious behavior, obfuscation, or safety bypasses were identified.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
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 remains here for the executor and review skills that load it.
The executable source of truth is
@gtrabanco/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-statusalways returns the strict Envelope v2 sensor result. Its envelope includes the detailed project view underdetail.- 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
- Read the profile and append
renderOutputInstruction(skill)only for a driven invocation. - Pass the final response to
parseTurn({skill, text, context}). Keep the returned source and diagnostics with the run journal. - On an absent, malformed, or invalid machine result, re-invoke the same
session once with:
Emit only the machine result for the turn above. - 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.
detailis required (usuallynull) and skill-specific extensions live inside it;design_candidates, for example, isdetail.design_candidates, never a root key. workflow-statusretains Envelope v2 for existing sensor consumers.parseEnvelope()remains the legacy-compatible package API; new consumers useparseEnvelopeV2Strict()orparseTurn().SkillOutcome v1andWorkflowSnapshot v1are 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.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/gtrabanco/agentic-workflow/orchestration-envelope">View orchestration-envelope on skillZs</a>