workflow-engine
**UTILITY SKILL** — Machine-readable workflow DAG for the multi-step agent pipeline. Defines node types, edge conditions, gates, and fan-out patterns. WHEN: "orchestrator step routing", "resume from graph", "workflow validation", "workflow DAG", "workflow gate", "fan-out pattern". USE FOR: orchestrator step routing, resume-from-graph, workflow validation. DO NOT USE FOR: Azure infrastructure, code generation, troubleshooting.
git clone --depth 1 https://github.com/jonathan-vella/apex /tmp/workflow-engine && cp -r /tmp/workflow-engine/.github/skills/workflow-engine ~/.claude/skills/workflow-engineSKILL.md
# 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 - **DAG only** — the workflow is a Directed Acyclic Graph; no cycles, no back-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 is conditional on `decisions.iac_tool`** — Step 3 → Step 4 / 5 / 6 routes to `*-b` (Bicep) or `*-t` (Terraform) - **Fan-out children execute in parallel** — Step 7 docs is the canonical example; do not serialize parallel children - **Edge conditions** — use exactly one of `on_complete`, `on_skip`, `on_fail` per edge; ambiguity is a validation error - **Schema evolution** — bump `metadata.version` and follow `references/schema-evolution.md` rollback rules when changing the graph - **Validation is enforced at three points** — graph shape (`validate-workflow-graph.mjs`), handoff buttons (`validate-agents.mjs --only=workflow-handoffs`), and gate-companion H2 sync (`validate-artifacts.mjs`) ## Steps Orchestrator protocol for routing the next step: 1. **Load** `templates/workflow-graph.json` 2. **Read current state** — `apex-recall show <project> --json` → `current_step` 3. **Find the matching node** in the graph 4. **Check node status**: - `complete` → follow `on_complete` edges → find next node - `in_progress` → resume from `sub_step` checkpoint - `pending` → execute this node - `skipped` → follow `on_skip` edges 5. **Apply IaC routing** when present — read `decisions.iac_tool` and pick the `*-b` or `*-t` branch 6. **If next is a `gate`** — present to user, wait for approval, record decision in session state 7. **If next is a `subagent-fan-out`** — dispatch all children in parallel; collect results before continuing 8. **Repeat** until all nodes are complete or blocked ## Core Concepts The workflow is a Directed Acyclic Graph (DAG): **nodes** (agent-step, gate, subagent-fan-out, validation), **edges** with conditions (`on_complete`, `on_skip`, `on_fail`), **gates** (human approvals), and **fan-out** (parallel sub-steps such as Step 7 doc generation). IaC routing edges from Step 3 forward conditionally branch on `decisions.iac_tool` (Bicep → `step-4b`, Terraform → `step-4t`); the pattern repeats for Steps 5 and 6. Full node-type table, edge-condition matrix, and IaC routing rules in [`references/dag-concepts.md`](references/dag-concepts.md). ## Workflow Graph The full machine-readable DAG is in: `templates/workflow-graph.json` ### Reading the Graph (Orchestrator Protocol) ```text 1. Load workflow-graph.json 2. Run `apex-recall show <project> --json` → current_step 3. Find the node matching current_step in the graph 4. Check node status: - complete → follow on_complete edges → find next node - in_progress → resume from sub_step checkpoint - pending → execute this node - skipped → follow on_skip edges 5. If next node is a gate → present to user, wait for approval 6. If next node is a fan-out → execute children in parallel 7. Repeat until all nodes are complete or blocked ``` ## Reference Index | Reference | File | Content | | ------------------------ | ------------------------------------------ | ------------------------------------------------------- | | Workflow Graph | `templates/workflow-graph.json` | Full DAG for the multi-step workflow | | Orchestrator Handoff | `references/orchestrator-handoff-guide.md` | Gate templates, IaC routing, delegation rules | | Subagent Integration | `references/subagent-integration.md` | Subagent matrix, pricing accuracy, review protocols | | Handoff Validation Rules | `references/handoff-validation-rules.md` | B1a–B5 rule reference (`workflow-handoffs` PART) | | Track Parity Spec | `references/track-parity-spec.md` | B4 normalization spec for Bicep/Terraform parity | | Schema Evolution | `references/schema-evolution.md` | D1 versioning policy + D2 rollback (`metadata.version`) | ## Validation Surfaces The workflow graph is enforced at three points: | Validator | Rule registry | Scope | | ------------------------------------------------------------ | ------------------------------------ | --------------------------------------------- | | `tools/scripts/validate-workflow-graph.mjs` | inline | Graph shape + schema | | `tools/scripts/validate-agents.mjs --only=workflow-handoffs` | `WORKFLOW_HANDOFF_RULES` | `handoffs[]` UI buttons + `agents[]` dispatch | | `tools/scripts/validate-artifacts.mjs` | `ARTIFACT_HEADINGS["00-handoff.md"]` | Gate-companion file H2 sync | Run all three together via `npm run validate:_node` (CI) or `npm run lint:workflow-handoffs` (focused).
Guidance for instrumenting webapps with Azure Application Insights. Provides telemetry patterns, SDK setup, and configuration references. WHEN: how to instrument app, App Insights SDK, telemetry patterns, what is App Insights, Application Insights guidance, instrumentation examples, APM best practices.
Use for Azure AI: Search, Speech, OpenAI, Document Intelligence. Helps with search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR. WHEN: AI Search, query search, vector search, hybrid search, semantic search, speech-to-text, text-to-speech, transcribe, OCR, convert text to speech.
Configure Azure API Management as an AI Gateway for AI models, MCP tools, and agents. WHEN: semantic caching, token limit, content safety, load balancing, AI model governance, MCP rate limiting, jailbreak detection, add Azure OpenAI backend, add AI Foundry model, test AI gateway, LLM policies, configure AI backend, token metrics, AI cost control, convert API to MCP, import OpenAPI to gateway.
ROUTING SKILL — delegates to specialized diagram skills. USE FOR: any diagram request when the caller does not know which tool to use. Routes to drawio, python-diagrams, or mermaid based on diagram type.
Build and deploy GitHub Copilot SDK apps to Azure. WHEN: build copilot app, create copilot app, copilot SDK, @github/copilot-sdk, scaffold copilot project, copilot-powered app, deploy copilot app, host on azure, azure model, BYOM, bring your own model, use my own model, azure openai model, DefaultAzureCredential, self-hosted model, copilot SDK service, chat app with copilot, copilot-sdk-service template, azd init copilot, CopilotClient, createSession, sendAndWait, GitHub Models API.
Troubleshoot and resolve issues with Azure Messaging SDKs for Event Hubs and Service Bus. Covers connection failures, authentication errors, message processing issues, and SDK configuration problems. WHEN: event hub SDK error, service bus SDK issue, messaging connection failure, AMQP error, event processor host issue, message lock lost, send timeout, receiver disconnected, SDK troubleshooting, azure messaging SDK, event hub consumer, service bus queue issue, topic subscription error, enable logging event hub, service bus logging, eventhub python, servicebus java, eventhub javascript, servicebus dotnet, event hub checkpoint, event hub not receiving messages, service bus dead letter.
Authoritative reference for VS Code Copilot customization mechanisms: instructions, prompt files, custom agents, agent skills, MCP servers, hooks, and plugins. Use when deciding which customization type to use, creating new .instructions.md/.prompt.md/.agent.md/SKILL.md/mcp.json files from scratch, or debugging why a customization is not loading. DO NOT USE FOR: routine file edits where the format is already known.
Provides canonical entity counts from count-manifest.json. Use when agents need to reference how many agents, skills, instructions, or validators exist. Prevents hard-coded counts. WHEN: agent count, skill count, how many agents, how many skills, entity inventory, project statistics.