AcceptedFebruary 2026

Workflow System

YAML-defined execution plans with schema validation, graph safety guarantees, routing reliability controls, and template reference integrity.

Context

As workflows became the core product surface, confidence requirements moved beyond basic schema validation. Failure handling needed deterministic retry metadata, workflow safety needed graph-level guarantees, routing needed regression fixtures, and template references needed static validation.

Core Decisions

1. YAML + Schema as the Structural Contract

Workflow files remain in YAML, validated by a JSON schema. Schema hardening includes strict onFailure shape, required retry metadata (retryStrategy, initialDelayMs, maxDelayMs, jitter), and conditional action constraints.

2. Policy-as-Code for Semantic Governance

A policy file governs workflow classes, retry guardrails, review-step requirements for mutating flows, verification requirements with explicit exemptions, and compaction thresholds.

3. Graph Safety Guarantees

Graph tests enforce:

  • At least one root step
  • No dependency cycles
  • At least one terminal step
  • Every step can reach a terminal node
  • goto cannot self-target
  • Conditional goto paths must include retriesExhausted -> abort guard

4. Routing Reliability Controls

Deterministic routing engine fixture tests, a corpus of expected prompt-to-workflow mappings, overlap-risk checks, and an explicit allowlist for known acceptable ambiguities.

5. Template Reference Integrity

Template reference tests validate that {{context.*}} references map to declared context keys, {{step.field}} references map to declared step outputs, and guarded support for match.* references in pre-check prompts.

Workflow Assurance Stack

1

Workflow YAML

Source of truth for execution plans, authored by workflow contributors.

2

Schema Validation

Structural correctness enforced by workflow.schema.json.

3

Policy Validation

Semantic governance checked against workflow.policies.json.

4

Graph & Routing Tests

Safety guarantees, routing corpus, and overlap detection.

5

CI Gate

All checks must pass before merge via yarn test:agents.

Key References

.github/agents/resources/workflow.schema.json.github/agents/resources/workflow.policies.json.github/agents/workflows/*.yaml.github/tests/workflow-graph.test.ts.github/tests/workflow-policies.test.ts

Trade-offs

Fewer silent runtime failures, higher confidence in workflow edits, better routing stability, clear governance separation between structure (schema) and semantics (policy).
Workflow authoring requires more metadata. Policy exemptions need active maintenance. Strict tests may block urgent edits.

Related Documentation