| name | diagram-driven-execution |
| description | Use this skill when the user supplies a mermaid diagram that represents a process the agent must follow step-by-step with deterministic tracking. Two modes via session SQL todos table (both produce the Copilot visual plan widget): simple (mode="simple"; up to 15 nodes, agent reads diagram from context, inserts todos+todo_deps, no parse script, no gates/loops) and advanced (default mode="advanced"; gates with multi-way routing and escalation, bounded loops via pre-expansion, deterministic parse via parse-diagram.py). Activate on: "follow this diagram", "execute this workflow", "enforce these steps", "track against this state machine", "drive this process", "run this mermaid as a plan", "step me through this flowchart", or any moment a diagram is the source of truth for a procedure. Does NOT execute node bodies; node work is delegated to subagents, tools, or the calling thread. |
Execute a mermaid diagram step-by-step with deterministic SQL-backed
tracking. The diagram is the process contract. The driver enforces
transition order and halts on stuck states. Node bodies are delegated;
this interface owns cursor management only.
Validate the operator's mermaid diagram against the supported v1 grammar
(references/diagram-grammar.md). Reject loudly with line/column
diagnostics on any unsupported syntax. In simple mode: also assert
absence of type=gate and type=loop nodes, and node count <= 15.
Initialise the execution plan in the session SQL store. INSERT one todos
row per diagram node and one todo_deps row per edge. Check for design_id
collisions before inserting. The node list is frozen after this step.
Drive diagram nodes to completion. Each turn: query ready nodes (pending
with all deps done or skipped), pick one, mark in_progress, execute body,
mark done or blocked. Repeat until no ready nodes remain or stuck state.
Evaluate a gate node's condition and route execution. Mark false-branch
root nodes as skipped (resolving their deps for downstream nodes). On no
matching branch: escalate to parent session if available, else emit B10.
Pre-expand a type=loop|max_iter=N node into N sequential iteration todos
at plan-init time. Wire predecessor -> iter_1 -> ... -> iter_N -> successor
via todo_deps. No runtime plan mutation after expansion.
Optional per-node behavioural annotation supplied in the AML invocation
block (not in the mermaid diagram). Maps a diagram node ID to a friendly
label, a natural-language description of the work to perform, and an
optional tool-permission scope.
Syntax:
<step node="<node_id>" type="prompt" label="Friendly display name" tools="sql,bash">
Natural-language description of what this step must accomplish.
</step>
Attributes:
node — REQUIRED. Must match exactly one node ID in the diagram.
type — OPTIONAL. Execution dispatch type. One of:
prompt — (default) executed by the current thread.
subagent — delegated to a background subagent.
session — delegated to another project session via
send_session_message. Requires a target
session ID in the step description or context.
tool — executed as a direct tool call.
manual — requires human input; the driver emits
B10 HUMAN CHECKPOINT and waits.
gate — multi-way conditional routing (advanced mode
only; B10 in simple mode).
loop — bounded pre-expansion (advanced mode only;
B10 in simple mode). Requires max_iter in the
diagram annotation or step description.
When both the diagram inline annotation (e.g.
A[Label|type=subagent]) and the <step type="..."> declare
a type, the <step> type wins. This allows the step
definition to override the diagram-level default.
label — OPTIONAL. Friendly display name; overrides the diagram label
in todos.title when present.
tools — OPTIONAL. Comma-separated list of tool names the agent may
use during this step. Effective permissions are the
INTERSECTION of the enclosing agent-level <tool allow> and
the step-level tools list. A step cannot widen permissions
beyond the parent scope. Omitting tools inherits the parent
scope. NOTE: tools is an attribute on <step>, not a child
<tool> element — this avoids AML parsing conflicts since
<step> is opaque text to the AML parser while <tool> is a
recognised AML directive.
Body text is the step description — stored in todos.description JSON
as "step_description". The driver reads it before executing the node
and uses it as the execution brief.
Validation (at plan-init):
- Every <step node="X"> must match exactly one diagram node ID.
Unmatched steps → B10 before any SQL writes.
- Duplicate <step> definitions for the same node → B10.
- Step tool lists that reference tools outside the parent scope → B10.
- type=gate and type=loop in simple mode → B10 (same as diagram
inline annotation).
- For type=loop nodes, a single <step> applies to every expanded
iteration (the description is inherited by each iter_N todo).
Nodes without a matching <step> use default behaviour: type-based
dispatch from the diagram inline annotation (or prompt if unset),
diagram label as title, no step description.
Confirm all plan nodes have reached a terminal status. Query for any rows
not in (done, skipped); zero rows = complete. Non-zero rows emit B10
with the incomplete node list.
Lightweight path. Agent reads diagram from context; no subprocess.
Nodes: dde/grammar-check (assert no gate/loop, count<=15),
dde/step (validate step definitions), dde/plan-init (context
extraction + step metadata merge), dde/execution-loop (rowid order
as tiebreak, step-type dispatch), dde/verify. Does not instantiate
dde/gate-router or dde/loop-expander. Protocol:
references/simple-protocol.md
Full path. Deterministic parse via parse-diagram.py.
Nodes: dde/grammar-check (parse-diagram.py), dde/step (validate
step definitions against parsed IDs), dde/loop-expander (pre-expand
at init, inherit step metadata to iterations), dde/plan-init
(todos + todo_deps + dde_gates + step metadata merge),
dde/execution-loop (skipped counts as resolved; step-type dispatch;
delegates to dde/gate-router on gate nodes), dde/verify. Protocol:
references/advanced-protocol.md
diagram-driven-execution
This skill turns a mermaid diagram into a tracked execution plan.
Two AML implementations share the same todos + todo_deps SQL store
and both produce the Copilot visual plan widget.
Embedding DDE in a skill (AML invocation)
<skill impl="dde-simple" mode="simple" role="enforcement">
</skill>
<skill impl="dde-advanced" mode="advanced" role="enforcement">
</skill>
<agent name="diagram-driver" mode="sync">
<skill impl="dde-advanced" mode="advanced">
flowchart LR
A[Fetch] --> B[Transform] --> C[Load]
</skill>
</agent>
<agent name="diagram-driver" mode="sync">
<tool allow="sql,bash">
<skill impl="dde-simple" mode="simple">
flowchart LR
A[Fetch data] --> B[Transform] --> C[Load]
<step node="A" type="tool" label="Fetch upstream data" tools="bash">
Pull the latest CSV from the SFTP server using rsync.
Verify the file hash matches the manifest.
</step>
<step node="B" label="Transform and validate" tools="sql">
Parse the CSV into the staging table. Run the validation
query and reject rows with null primary keys.
</step>
<step node="C" label="Load into warehouse" tools="sql">
INSERT validated rows into the production table.
Log the row count for the run report.
</step>
</skill>
</tool>
</agent>
<agent name="diagram-driver" mode="sync">
<tool allow="sql,bash">
<skill impl="dde-advanced" mode="advanced">
flowchart LR
A[Design] --> B[Implement] --> C[Review] --> D[Merge]
<step node="B" type="session" label="Implement feature">
Delegate implementation to the dev session. Send the spec
from node A as context via send_session_message.
</step>
<step node="C" type="manual" label="Human code review">
Pause for human review. The reviewer inspects the PR and
approves or requests changes.
</step>
</skill>
</tool>
</agent>
Execution modes
| dde-simple | dde-advanced (default) |
|---|
| Visual plan widget | yes | yes |
| Parser | agent reads context | parse-diagram.py subprocess |
| Gates | B10 if detected | multi-way + escalation |
| Loops | B10 if detected | bounded pre-expansion |
| Multi-agent | no | yes |
| Token cost | lower | higher |
When to activate
Reach for dde when: plan > 3 nodes, fan-out or parallelism, topological
ordering matters, work spans sessions (B4/B8 re-grounding), or "done"
must be a deterministic SQL gate rather than an LLM assertion.
Skip dde for: single-node tasks, <=3-step throwaway work, exploratory
work where steps aren't known upfront, advisory/Q&A turns.
Which implementation?
Has type=gate or type=loop? -> dde-advanced
Node count > 15 or complex mermaid syntax? -> dde-advanced
Otherwise -> dde-simple
Process
dde-simple execution
Read diagram from context. Assert no type=gate or type=loop nodes.
Assert node count <= 15. Emit B10 on violation before any SQL writes.
Validate step definitions: every step node attribute must match a
diagram node ID; no duplicates; step tool lists must be subsets of
the enclosing tool scope.
Extract nodes and edges from context. INSERT todos + todo_deps in
one batch. design_id collision check first. Merge step metadata
(step_label, step_description, step_tools) into todos.description
JSON for nodes with matching step definitions.
SELECT ready nodes (dep-aware, skipped=resolved), ORDER BY rowid.
Per node: read step metadata from todos.description; use
step_description as execution brief and respect step_tools
constraint. UPDATE in_progress -> execute body -> UPDATE done
or blocked. B10 on stuck state.
SELECT WHERE status NOT IN ('done','skipped'). Zero rows = complete.
dde-advanced execution
python3 scripts/parse-diagram.py --input <file> [--design-id <id>]
Exit 2 = grammar violation; return diagnostic and stop.
Validate step definitions against parsed node IDs. Unmatched or
duplicate steps → B10 before any SQL writes. Step tool lists must
be subsets of the enclosing tool scope.
Detect type=loop|max_iter=N nodes in parsed JSON. Pre-expand each
into N iteration todos chained via todo_deps. Wire predecessor and
successor edges. For loop nodes with a matching <step>, the step
description is inherited by every expanded iteration todo.
No further plan mutation permitted after this step.
INSERT todos + todo_deps from parsed JSON. If gate nodes present:
CREATE TABLE IF NOT EXISTS dde_gates and INSERT routing rows.
Merge step metadata into todos.description JSON for nodes with
matching step definitions.
SELECT ready nodes (skipped counts as resolved). Per node:
read step metadata from todos.description; use step_description
as execution brief and respect step_tools constraint.
UPDATE in_progress -> dispatch by type -> UPDATE done or blocked.
Read gate result from description JSON. Look up dde_gates for
matching label. Mark non-matching branch roots skipped (walk
todo_deps for subtrees). Mark gate done. On no match: escalate
via send_session_message if parent session present, else B10 +
mark gate waiting.
SELECT status, COUNT(*) GROUP BY status WHERE id LIKE design_id::.
All done or skipped = complete. Else B10.
Platform and runtime
common-only. Advanced mode requires Python 3 on PATH (one call at
plan-init only). Simple mode: no external tools. Parser uses stdlib only.
Bundled assets
scripts/parse-diagram.py - deterministic mermaid parser (stdlib-only)agents/diagram-driver.agent.md - process-execution personareferences/diagram-grammar.md - v1 supported grammar subsetreferences/advanced-protocol.md - dde-advanced contractreferences/simple-protocol.md - dde-simple contract
Limitations (declared)
- Discipline-based enforcement only - no script-level transition gate.
dde-simple rejects gate/loop nodes at grammar-check time (B10).- v1 grammar excludes subgraphs, composite states, classDefs, click
handlers (see references/diagram-grammar.md).
- Diagram cycles rejected. Loops expressed via type=loop|max_iter=N.
- Re-planning is a B10 event - start a new design_id for a new diagram.
- Condition-based loops (iterate until condition) not in v0.5.
