diagram-driven-execution

<!-- ========================================================= AML INTERFACE DEFINITIONS Top-level capability contract and sub-capability nodes. ========================================================= --> <skill define="interface" name="diagram-driven-execution"> 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. </skill> <skill define="interface" name="dde/grammar-check"> 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. </skill> <skill define="interface" name="dde/plan-init"> 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. </skill> <skill define="interface" name="dde/execution-loop"> 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. </skill> <skill define="interface" name="dde/gate-router"> 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. </skill> <skill define="interface" name="dde/loop-expander"> 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. </skill> <skill define="interface" name="dde/step"> 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. </skill>

<skill define="interface" name="dde/verify"> 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. </skill> <!-- ========================================================= AML INTERFACE DEFINITIONS - MODE CONTRACTS ========================================================= --> <skill define="interface" name="dde-simple" extends="diagram-driven-execution"> 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 </skill> <skill define="interface" name="dde-advanced" extends="diagram-driven-execution"> 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 </skill>

---

diagram-driven-execution

• Driver persona
• Grammar rule
• Advanced mode protocol
• Simple mode protocol

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)

<!-- Lightweight: <=15 nodes, no gates/loops, no parse script -->
<skill impl="dde-simple" mode="simple" role="enforcement">
  <!-- mermaid diagram or reference -->
</skill>

<!-- Full: gates, loops, parallel branches, deterministic parse -->
<skill impl="dde-advanced" mode="advanced" role="enforcement">
  <!-- mermaid diagram or reference -->
</skill>

<!-- Delegate the entire run to a subagent -->
<agent name="diagram-driver" mode="sync">
  <skill impl="dde-advanced" mode="advanced">
    flowchart LR
      A[Fetch] --> B[Transform] --> C[Load]
  </skill>
</agent>

<!-- Per-node behavioural annotations via <step> -->
<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>

<!-- type=session delegates work to another project session -->
<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 o

---

Content truncated.