gilde

← All craftbooks

Diagram from Text

Media: imagesevalv1.0.0released 2026-06-05workflow: build-loop

Render a clear technical diagram — flowchart, architecture, sequence, ER, or org chart — from a plain-language description, as code-defined (Mermaid/Graphviz/SVG) so it is editable and version-controllable rather than a flat picture. Spec FIRST the diagram type, the exact nodes and edges, and the layout direction, because diagrams fail when relationships are wrong or the graph is an unreadable tangle; then build the diagram so it renders, with every described entity and relationship present and labeled. Covers flowcharts, architecture diagrams, sequence diagrams, ER diagrams, org charts, mind maps, and diagram-as-code.

Steps

Entry step: spec. Each step names the specialist role it wants; the full working prompt is expandable.

  1. Spec the diagramplannerentry

    lock type, nodes, edges, labels, and layout

    Show working prompt
    1) Parse the description and choose the right diagram TYPE (flowchart, sequence, ER, class, state, org chart, mind map). 2) Enumerate the exact NODES (entities/steps/actors) with their labels and the exact EDGES (relationships/transitions/messages) with their labels and direction — list them explicitly so nothing is dropped or invented. 3) Decide layout direction (top-down vs left-right) and any grouping/subgraphs. 4) Pick the rendering format (Mermaid is the default for editability; Graphviz/SVG if requested). 5) Write an acceptance-criteria checklist: 'every entity in the description is a node', 'every stated relationship is an edge with correct direction', 'labels match the description', 'the diagram renders without syntax errors', 'layout is readable (no needless crossings)'. 6) Record the node/edge list + checklist via write_task_note AND to notes/spec.md.
  2. Build the diagramdeveloper

    author the renderable diagram to the spec

    Show working prompt
    1) Read spec.md's node/edge list. 2) Author the diagram in the chosen format (e.g. a Mermaid graph in an index.html that loads mermaid.js and renders it, so it actually displays). 3) Add EVERY node and EVERY edge from the spec with the correct labels and direction — do not add entities that weren't described and do not omit any. 4) Set the layout direction and use subgraphs/grouping for clarity; choose an arrangement that minimizes edge crossings. 5) Verify the syntax parses (the diagram renders, no error box). 6) On a loop-back, fix only the named gaps (missing edge, wrong arrow direction, syntax error). 7) write_task_note the file path and node/edge counts. The deliverable is index.html that renders the diagram.
  3. Evaluatereviewer

    Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.

    Show working prompt
    1) Open index.html and confirm the diagram actually RENDERS with no syntax/error box (PASS/FAIL). 2) Cross-check against spec.md: every described entity appears as a node and every stated relationship appears as an edge with the correct DIRECTION and label (PASS/FAIL — this is the core check). 3) Confirm no invented nodes/edges. 4) Judge readability — is the layout legible or a tangle? 5) Write PASS/FAIL per criterion. Missing/wrong relationships or a non-rendering diagram → loop back to build.

Then route — this is the whole point of the loop:

- **Every criterion PASSES →** call `advance_task_step({ ref, stepId: "evaluate", next: "finish" })`.
- **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: "evaluate", next: "build" })` to loop back. The builder fixes exactly those gaps.

Never route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in.
  4. Finishdeveloper

    All acceptance criteria met. Stamp a short summary and report DONE.

    Show working prompt
    Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.

Triggers

Phrases that suggest this craftbook to a crew.

Source

View this craftbook on GitHub · MIT license