jonathan-vella/apex/apex-workflow-engine

Workflow Engine Skill

Provides a declarative, machine-readable workflow graph that the Orchestrator reads instead of relying on hardcoded step logic.

When to Use

• Orchestrator determining the next step after a gate
• Resuming a workflow via apex-recall show <project> --json
• Validating that all steps have proper dependencies and outputs
• Understanding fan-out (parallel sub-steps) and conditional routing

Rules

• Forward DAG — edges must be acyclic; refinement routes are declared separately in return_edges.
• Source of truth is `templates/workflow-graph.json` — the orchestrator reads this directly; do not encode workflow logic in agent prose
• Gates are blocking — a gate node halts downstream execution until human approval is recorded in session state
• IaC routing — step-4 is the shared planner; select CodeGen and Deploy nodes using decisions.iac_tool.
• Fan-out is logical work structure, not permission to invoke main agents or unavailable workers.

The owning main agent handles its outputs; parallelize only independent, authorized work.

• Edge conditions — follow the graph's declared conditions, including refinement returns; the schema allows a string or array.
• Schema evolution — bump metadata.version and follow references/schema-evolution.md rollback rules when changing the graph

Prerequisites

Graph 3.0 adds the practical contract for new projects; known 2.x project semantics remain readable until explicit owner adoption. Specialists and stage approvals are unchanged. Preliminary policy feasibility is collection before Architecture approval, not early completion of Governance.

Use the graph and apex-recall show <project> --json together. If the returned session is empty, initialize or recover the project within the active owner's scope before routing. The already selected Orchestrator continues explicit new-project requests into Requirements; initialization is not an additional user-selection or approval gate.

Steps

Orchestrator protocol for routing the next step:

1. Load templates/workflow-graph.json
2. Read current state — use session.current_step, session.steps, and session.decisions in the response.
3. Resolve the node — use the per-step status map to distinguish Design (3) from Governance (3_5);

use decisions.iac_tool for the CodeGen and Deploy tracks. Do not derive a node ID from the numeric pointer alone.

1. Check node status:

• complete → follow on_complete edges → find next node
• in_progress → resume from sub_step checkpoint
• pending → verify graph prerequisites, human approval and owner readiness before dispatch
• skipped → follow on_skip edges
• failed or blocked → stop and follow the applicable declared recovery or refinement route

1. Apply edge and node conditions — honor optional Design selection and the IaC track;

do not execute every outgoing edge when alternatives are present.

1. If next is a `gate` — check its preconditions, present to the user, wait for approval, and record the decision.
2. If next is a `subagent-fan-out` — use the owning agent's actual role/tool contract;

never infer callable workers from graph children. Collect required outputs before continuing.

1. Repeat until all nodes are complete or blocked

Core Concepts

Forward execution and declared refinement returns are distinct. A shared step-4 plan feeds step-5b / step-5t, then step-6b / step-6t. Approval gates remain blocking on both tracks.

Full node-type table, edge-condition matrix, and IaC routing rules in `references/dag-concepts.md`.

Workflow Graph

The full machine-readable DAG is in: templates/workflow-graph.json

Reading the Graph (Orchestrator Protocol)

Use Steps as the routing protocol. Response fields are documented in `show-schema.md`.

Reference Index

VS Code Copilot SDK entrypoints share workflow-entry.md. For parent-to-worker calls, read native worker lifecycle, then execution-subagent.md. Manual Host workflow entry uses apex-workflow-start, including resume [project]. This skill requires explicit owner selection; it does not bind models/tools.

Other operations load only their requested procedure: imported IaC, existing Azure as-built, project review. Published documentation maintenance belongs to the separate jonathan-vella/apex-docs repository. Do not load retired documentation tooling when advancing infrastructure steps. For their shared execution boundary, read operational-safety.md.

Validation Surfaces

The workflow graph is enforced at three points:

npm run validate:_node includes these checks. For focused graph and handoff checks, use npm run validate:workflow-graph and npm run lint:workflow-handoffs. Artifact Markdown validation remains owned by the existing hooks and challenger review.