# Workflow Coordination > Generic workflow-coordinator framework — operating model, DAG introspection patterns, verdict.json schema, brief-plumbing meta-pattern, and authoring guidance for strategy skills - **Type:** Skill - **Install:** `agentstack add skill-glyphs-ai-glyph-workflow-coordination` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [glyphs-ai](https://agentstack.voostack.com/s/glyphs-ai) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [glyphs-ai](https://github.com/glyphs-ai) - **Source:** https://github.com/glyphs-ai/glyph/tree/main/first-party/skills/workflow-coordination ## Install ```sh agentstack add skill-glyphs-ai-glyph-workflow-coordination ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Glyph Workflow Coordination Skill The framework every workflow coordinator wake-up loads: how to read the DAG, what schema reviewer workers emit in `verdict.json`, how to plumb context into worker briefs, and how to author a sibling strategy skill. The case bank, brief templates, and stop condition for any given workflow live in a sibling **strategy skill**; the scaffolding here is strategy-agnostic. CLI invocations cited below (`workflow show`, `dag`, `node-show`, `add-subgraph`, `prune-subgraph`, `update-spec`, `finish`, `task list`, `task show`) are stable command names — consult your catalog's CLI skill for exact flags. --- ## §A — Operating model ``` 1. Read own node id from the task spec / env 2. Read workflow header: glyph workflow show $WF --json 3. Read full DAG: glyph workflow dag $WF --json 4. Identify own parents: edges where to == own node id 5. Identify selected strategy: - read workflow.metadata.strategy if set - else read workflow.brief for an explicit hint - else fall back to the only strategy declared in the coord agent's deps 6. Load the corresponding strategy skill's case bank (see §B in that skill) 7. Match own parents against the case bank, execute the matching case 8. Log decision + reasoning to $GLYPH_WORKFLOW_DIR/coord-decisions/-$GLYPH_NODE_ID.md (auto-named so concurrent / out-of-order wake-ups never collide; colons in the ISO timestamp are replaced with dashes for cross-platform filename safety — e.g. 2026-06-09T15-34-58Z-node_abc123.md) 9. Exit (coord run terminates; substrate detects task terminal; next coord wake-up only happens when its own future parents complete) ``` - One wake-up = one decision = one mutation. Use `add-subgraph` OR `finish`. Never loop waiting for parents — the substrate re-wakes coord when its parents land terminal. - Re-read every identifier from the DAG snapshot every wake-up. Do not cache parent ids, task ids, or branch names across wake-ups. The DAG IS the state. - The strategy skill owns the case bank; the scaffolding here is universal. Do not look for concrete cases in this skill. ### Reading prior decisions Past wake-ups' decision files live alongside mine under `$GLYPH_WORKFLOW_DIR/coord-decisions/`; I can `ls` the directory to enumerate them. Filenames are timestamp-prefixed so chronological order is the directory's natural sort — no separate index file is needed. Strategy-specific patterns commonly want this: iteration counters ("how many times have I taken case X so far?"), backoff ("did I just try this and fail on the previous wake-up?"), or audit-trail reconstruction. Prior decision files are read-only from a strategy-discipline standpoint — consult them, never mutate them; the directory is append-only across the workflow's lifetime. ### Strategy selection details Resolve step 5 in priority order: 1. `workflow.metadata.strategy` — explicit strategy FQN set by the workflow creator (e.g. `"/"`). 2. An explicit hint inside `workflow.brief` (e.g. `strategy: acme/research-synth`). 3. The sole strategy among the coord agent's `dependencies.skills` when exactly one is declared. If none of the three yields a strategy, terminate: `workflow finish --outcome failed --message "coord could not select a strategy: no metadata, no brief hint, and the coord agent declares multiple strategy skills"`. --- ## §B — DAG introspection patterns Snippets below assume `$DAG` and `$WF` hold the JSON fetched per §A steps 2–3. Parent order is not significant; downstream classification keys on `(kind, agent, status)`. ### Find own parents ``` SELF=$OWN_NODE_ID PARENT_IDS=$(jq -r --arg self "$SELF" \ '.edges[] | select(.to == $self) | .from' `. List them — newest-first — with the origin filter; the head of the list is the latest run (empty until the node has been dispatched): ``` TASKS=$(glyph task list --origin workflow --origin-id "$PID" --json) LATEST_TASK_ID=$(jq -r '.[0].id // empty' ", "kind": "worker", "existingParents": [""], "spec": { "agent": "", "brief": "", "details": null } }, { "tempId": "", "kind": "worker", "existingParents": [""], "spec": { "agent": "", "brief": "", "details": null } }, { "tempId": "coord", "kind": "coordinator", "existingParents": [""], // REQUIRED: chain the new coord onto self (see rule 3 below) "spec": { "agent": "" } } ], "edges": [ { "from": { "tempId": "" }, "to": { "tempId": "coord" } }, { "from": { "tempId": "" }, "to": { "tempId": "coord" } } ] } ``` The substrate resolves the `tempId`s within the transaction and returns the assigned node ids in `insertedNodes[].nodeId`. Three universal rules: 1. Every fan-out MUST end in a `next-coord` whose parents are the newly-inserted workers (otherwise the branch dead-ends). 2. Exactly one `add-subgraph` per wake-up (splitting a fan-out across two CLI calls leaves a half-formed DAG and may re-wake the wrong coord). 3. The `next-coord` MUST list the currently-running coord's node-id in its `existingParents`. An intra-batch edge from a worker into `next-coord` is NOT enough on its own — the substrate enforces a coord-to-coord chain (a new coord must have at least one coord parent) to keep the DAG frontier connected. The `next-coord` ends up with mixed parents: `[, ...worker-tempIds-via-edges]`, and its phase is `max(parent-phases) + 1`. ### Common `add-subgraph` rejections When `glyph workflow add-subgraph` fails, the error `type` names the family and `reason.kind` names the specific invariant. Read both before retrying; guessing burns wake-ups. **`WorkflowDagConflict` — the DAG shape is legal on its own but violates a coord-chain / parent-state rule:** | `reason.kind` | What tripped it | Forward fix | |---|---|---| | `orphanCoordInsert` | New coord node has no coord parent (workers-only in `existingParents` + edges). | Add `existingParents: [""]` to the `next-coord` node. | | `successorCoordExists` | Self already has a coord-kind child in the DAG. | The wake-up is racing an earlier decision. Re-read the DAG (`glyph workflow dag`) and finish or observe instead of re-inserting. | | `parentState` | A referenced existing parent is `failed` or `cancelled`; workers/humans can't attach to non-successful parents. | Route to the strategy's failure/cancellation case (typically `workflow finish --outcome failed`). | | `invariant` | Post-insert the DAG would have zero, or non-coord, or multiple leaves. | The subgraph must leave the DAG with exactly one leaf and it must be a coord. Add the missing `next-coord` (or fix its wiring). | **`WorkflowSubgraphInvalid` — the subgraph payload itself is malformed:** | `reason.kind` | What tripped it | Forward fix | |---|---|---| | `empty` | Neither nodes nor edges submitted. | Compose a real subgraph; empty mutations are not valid wake-up actions. | | `tempIdInvalid` | A `tempId` is empty, duplicated, or otherwise malformed. | Use unique, non-empty `tempId`s within the payload. | | `tempParentless` | A temp node has no incoming edge from any parent (existing or temp). | Give the temp node an `existingParents` entry or an edge from another temp. | | `nodeRefUnresolved` | An edge or `existingParents` entry references a `tempId` or existing node id that isn't in the payload / DAG. Look at `reason.refKind` (`"temp"` or `"existing"`) to see which side. | Fix the reference; make sure the referenced node id is present in `nodes` (for temp refs) or already in the workflow DAG (for existing refs). | | `cyclic` | An edge would create a cycle in the resulting DAG. | Rework the subgraph so new nodes strictly extend the frontier downstream. | | `multipleCoordTemps` | Payload contains more than one coord-kind temp node. | Exactly one `next-coord` per `add-subgraph`; split additional coords into future wake-ups. | **`WorkflowNodeNotMutable` — the target of an `edges[].to` pointing at an existing node has already started (only `not_started` nodes accept new incoming edges):** Don't rewrite in-flight nodes; insert a fresh temp node and connect the new work through it. ### Retract a mis-planned fan-out via prune-subgraph `add-subgraph`'s structural inverse. When a wake-up realizes a batch it queued is wrong — but the nodes haven't started yet — retract them instead of letting dead work dispatch. Use `glyph workflow prune-subgraph --spec-file ` with a body naming the node ids to remove: ```jsonc { "nodeIds": ["", ""] } ``` The substrate removes those nodes **and every edge touching them** in one transaction and returns `{ prunedNodeIds, prunedEdges }`. It is all-or-nothing: if any check below trips, nothing is removed. Three constraints follow from keeping the surviving DAG connected and coord-anchored: - Only `not_started` nodes are prunable (a node that already dispatched is real work — cancel it via `cancel-node`, don't prune it). - The phase-0 bootstrap coordinator can never be pruned. - After removal, every surviving non-root node must still have a parent, and every surviving non-root coordinator must still have a coordinator parent. **`WorkflowPruneRejected` — the prune batch was refused; `reason.kind` names why:** | `reason.kind` | What tripped it | Forward fix | |---|---|---| | `nodeNotFound` | A requested id isn't in this workflow. | Re-read the DAG (`glyph workflow dag`); prune only ids that exist. | | `nodeNotStarted` | A target has already started (`ready` / `running` / terminal). `reason.status` shows which. | Leave started nodes alone; `cancel-node` an in-flight worker instead. | | `rootCoordProtected` | A target is the phase-0 bootstrap coordinator. | Never prune the root; it anchors the whole DAG. | | `orphan` | Removing the batch would strand a surviving node with no parents. `reason.nodeId` is the would-be orphan. | Include the orphan in the same prune batch, or keep the parent it depends on. | | `coordChainBroken` | A surviving coordinator would keep only worker parents (its coord parent was pruned). `reason.nodeId` is that coord. | Prune the dependent coord in the same batch, or keep a coord parent for it. | ### Correct a not_started node's spec via update-spec Not every mistake needs a retract-and-rebuild. When a queued `not_started` node is structurally right but its **spec** is wrong — a typo in a brief, a brief that needs tightening, the wrong worker `agent`, a human `prompt`/`choices` tweak — patch it in place with `workflow update-spec` instead of pruning and re-adding. Patching preserves the node's id and all its edges; prune+re-add churns both and can re-wake the wrong coord. Decide by what's changing: - **Spec only, same kind, same edges → `update-spec`.** A partial overlay: name only the fields that change; the rest keep their prior value. - **Kind change, or any edge/parent restructure → prune + re-add.** `update-spec` cannot change a node's `kind` and never touches edges. Retract via `prune-subgraph` and re-queue the corrected shape via `add-subgraph`. - **Node already dispatched (`ready`/`running`/terminal) → neither.** A started node is real work; its spec is frozen. `cancel-node` the worker and queue a replacement if the plan changed. One hard rule: - **Never patch a coordinator node.** Coordinator specs are system-owned — the substrate rejects a coord `update-spec`. A wrong coordinator is a graph-structure problem: prune the coord (and its dependents) and re-plan, don't try to edit it. Exact flags and body shape live in the `official/cli` skill (`workflow update-spec`); this section is *when*, not *how*. --- ## §C — verdict.json schema (universal) Reviewer workers (any worker whose output a coord parses to decide "continue or finish") write a `verdict.json` to `/artifact/verdict.json` (the substrate auto-harvests files under `/artifact/` into the task's `success.artifacts`, which is what makes them visible to coord wake-ups and to the dashboard Artifacts tab). Every strategy that uses reviewer parents consumes the verdict via this schema. ``` verdict.json schema: { "verdict": "APPROVE" | "REQUEST_CHANGES", "findings": [ { "id": string, // unique within this verdict "severity": "blocker" | "major" | "minor", "summary": string, // ≤200 chars, single line "detail": string // free-form, any length } ] } ``` Parse rules for coord: - `verdict == "APPROVE"` ⇒ findings MAY be `[]` OR contain only `"minor"` items - `verdict == "REQUEST_CHANGES"` ⇒ findings MUST contain ≥1 `"blocker"` or `"major"` - `findings[].id` must be unique within this verdict - Missing severity on a finding ⇒ treat as `"major"` (conservative: do not silently skip) - Treat missing `findings` array as `[]` - On parse failure: `workflow finish --outcome failed --message "reviewer did not produce valid verdict.json"` and exit Strategy skills SHOULD re-quote this schema (verbatim, or as a worked example with concrete sample values) inside their reviewer brief templates so the worker receives the schema in its brief and need not load this skill. --- ## §D — Brief assembly Treat workers as pure specialists: they MUST NOT depend on any workflow-specific skill or know they are inside a workflow. All workflow context reaches them via the task brief coord writes when dispatching them. ### How coord assembles briefs Coord reads the full workflow context — the creator's brief and details, the current DAG state, parent outputs, iteration history — and assembles a brief tailored to the worker's specific task and the current situation. This is NOT rigid template substitution; coord uses judgment about emphasis, ordering, and what context is most relevant given why this worker is being dispatched. ### What a good brief contains - **The workflow's original goal** — from `workflow.brief` and `workflow.details`. Workers need to understand the big picture to do their job well. - **What the worker needs to do THIS iteration specifically** — first implementation? Fixing reviewer blockers? Fixing CI failures? Acting on human feedback? The brief's framing should match the reason for dispatch. - **Where to find prior outputs** — concrete fetch instructions (task ids, artifact paths) so the worker can read raw verdicts, prior reviews, or CI logs itself. Workers do their own fetching; coord does not pre-digest. - **The output protocol the worker must follow** — for reviewer workers, the §C `verdict.json` schema (verbatim or as a worked example) plus validation rules. For implementer workers, the expected branch / PR convention. ### What coord MUST NOT put in briefs - **Technical opinions** — code quality judgments, design choices, fix suggestions. Workers own those domains. - **Pre-digested findings** — the worker reads the raw `verdict.json` or CI logs itself. Coord points to where the data lives, not what it says. - **Instructions that belong in the worker's own agent body / skills** — if the agent's AGENTS.md or its depended-on skills already cover a behavior, don't restate it in the brief. - **Hints about future coord wake-ups** — workers are workflow-unaware. ### Adapting emphasis by dispatch reason - **First iteration** — emphasize the workflow goal and output expectations. Keep it clean and forward-looking. - **Fixing reviewer blockers** — lead with the fact that reviewers found issues, point to where findings are, note the branch to continue on. - **Fixing CI failures** — lead with the CI failure, instruct worker to check `gh pr checks`, note the branch. - **Post-human-feedback** — include the human's response text as additional direction, frame what the human decided or requested. - **Post-human-approval** — (coord handles this internally; no worker dispatch needed for approval) ### Pre-flight validation Before writing the `add-subgraph` payload, SKIM each dispatched agent's `AGENTS.md` (sections: "Required output protocol" / equivalent, "Bound … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [glyphs-ai](https://github.com/glyphs-ai) - **Source:** [glyphs-ai/glyph](https://github.com/glyphs-ai/glyph) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-glyphs-ai-glyph-workflow-coordination - Seller: https://agentstack.voostack.com/s/glyphs-ai - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.