Workflow Builder

Use this skill to turn workflow descriptions or drafts into a semantic workflow contract, then render an SVG diagram from that contract.

Core Rules

• Treat the workflow contract as the only semantic source of truth.
• Never draw directly from the prompt.
• Never change, merge, delete, or reorder workflow meaning to improve layout.
• Treat human-reviewed relationship corrections as contract updates first; never retarget an edge for renderer convenience.
• Treat human-reviewed layout corrections as route-quality evidence first; classify the underlying failure before adding durable guidance.
• Never introduce parallel_split / parallel_join gateways unless the source explicitly contains or states parallel synchronization semantics.
• Keep QA gates mandatory: semantic QA, contract QA, diagram QA.
• Keep style selection out of the workflow contract. Style is a render concern only.
• Use the style registry in assets/styles/index.json; the current default style is engineering-basic / Basic Style.

Style Selection Gate

Before rendering, resolve the requested style:

• If the user specifies a known style id or display name, use it directly.
• If the user does not specify a style, list the available registry styles and ask which one to use.
• If the user specifies an unknown style, stop before rendering and list the available styles. Do not silently fall back to the default.
• Do not add style, preset, color, or theme fields to the workflow contract.

Current available styles:

• engineering-basic / Basic Style: restrained engineering workflow style with deterministic layout and fixed semantic mappings.
• modern-tech / Modern Tech Style: bright SaaS/R&D workflow style with white cards, light swimlanes, blue connectors, cyan decisions, soft shadows, and subtle line icons.

User Work Files

For non-technical users who want to edit diagrams themselves, use the Markdown work-file toolchain:

• workflow_builder.cmd / 流程图编辑器.cmd starts the local browser editor for files under work/.
• workflow_tool.cmd / 流程图工具.cmd is the menu-based command-line tool that creates and regenerates files under work/.
• templates/workflow.template.md is the starting template.
• work/<name>.md is the editable source.
• work/<name>.svg is the generated diagram.
• The workflow contract is a runtime semantic model parsed from work/<name>.md; do not introduce a second user-maintained contract source for this workflow.
• The browser editor must default to chart-facing fields only: title, summary, participants, optional stages, steps, and connections.
• The browser editor includes an in-page Help dialog for workflow, file, field, direction, and safety guidance; Help text must not change workflow semantics.
• The browser editor should load existing Markdown and legacy YAML/JSON contracts through a file picker. The server may parse posted source text, but must not accept arbitrary filesystem paths.
• The browser editor may offer Save As for a separate Markdown source copy only. Do not offer Save As for SVG, JSON, YAML, or a second user-maintained contract source.
• The browser editor must protect mutating POST requests with its per-session token plus localhost Host/Origin checks.
• Rendered SVG files are not editable semantic sources. Do not promise reliable SVG-to-workflow editing; use matching Markdown or contract files instead.
• The browser editor must preview SVG through an iframe-backed HTML preview endpoint, not by injecting raw SVG text into the builder DOM. Zoom controls must update the preview endpoint zoom parameter, not scale the iframe shell.
• Keep scope, artifacts, read-only technical ids, constraints, assumptions, and open questions in an advanced folded area. Preserve them on save, but do not require ordinary users to edit them.
• Preserve non-phase semantic constraints in Markdown using a ## Constraints section with - constraint-id [applies=node-id|edge-id]: Label text.
• Flow direction is a render concern only: top-to-bottom, left-to-right, and snake choices must not be written into the contract or Markdown. Stages are optional and must not be required for rendering.
• For actor + phase matrix diagrams, top-to-bottom means a true vertical matrix: participants are columns, stages are rows, and workflow layers advance downward. Do not implement this by rewriting the contract into pseudo actor/phase semantics.
• Vertical actor + phase matrix rendering should use compact, content-sized workflow layers and reserve enough side-route gutter around participant lanes for side-anchor feedback or cross-lane routes. Do not reuse horizontal-matrix row spacing or let side anchors press against node/lane boundaries.
• Snake flow is a compact render option for long ordinary workflows: it packs four semantic ranks per alternating row without changing node order, edge endpoints, types, or labels.
• When snake flow has actors, use its style-token-controlled light Morandi card fills plus a legend instead of swimlanes. When stages exist, draw them as vertically stacked layers. If both exist, actor colors and stage layers are complementary, not competing encodings.
• Snake flow does not support parallel_split or parallel_join; report a clear render error and direct the user to an existing layout. Do not serialize parallel semantics for compactness.
• In branch-heavy snake flows, build sibling obstacles and route families before routing edges. A direct branch route that intersects a sibling card must move to its stable preferred outer-corridor lane.
• For vertically stacked sibling targets, assign same-anchor source slots in target order so upper/middle/lower branches remain visually monotonic and never cross each other near the decision.
• When at least three unlabeled edges connect one source to a vertically stacked target family, or a vertically stacked source family to one target, render one local shared trunk and tag every member with the same data-edge-bundle. Shared bundle anchors are intentional; unrelated exact-anchor reuse remains a failure.
• For non-exception feedback, score collision-free local return paths before allocating an outer-canvas loop. A distant loop fails when a shorter clear orthogonal path exists. Exception/rework edges may retain a labeled outer lane when that is required for label ownership.
• A positive lane_offset on explicit mixed anchors widens the local dogleg before its first turn; use this to place a route in the nearest clear card-to-card gap without sending it to an outer corridor.
• When one branch of a same-rank stack is the sole predecessor of an adjacent end card, align the end card to that predecessor when row height can be expanded safely. This removes decorative bends without changing workflow semantics.
• For automatic multi-source convergence, assign target slots in source spatial order. Use the perpendicular axis as a stable tie-break for same-column or same-row sources. Explicit route hints retain their declared lane ordering and must not be rewritten by automatic sorting.
• Treat optional edge anchor/corridor hints as hard render constraints. Preserve them in contract files and expose them as SVG metadata; fail clearly when a forced route collides instead of silently choosing another anchor.
• Run scripts/validate_snake_svg.py for snake outputs with complex branches, convergence, or feedback. Card crossings, hidden arrow endpoints, long unexplained route overlap, label collisions, congested target anchors, escaped corridors, unnecessary U-turns, missing dense-stack bundle metadata, and distant detours despite a clear local route are failures.
• When a snake outer corridor extends left of the canvas, expand and translate the complete diagram body so every route stays within bounds. Do not repair this by clipping, moving only the edge, or changing its semantic endpoints.
• Future natural-language, example-image, or contract-driven user-facing diagram generation should create or update work/<name>.md alongside work/<name>.svg so the browser editor can reopen it.
• Work names must be simple safe stems: lowercase letters, numbers, hyphen, or underscore only.
• The CMD and browser workflows must not accept arbitrary paths; they are intentionally limited to work/.
• CMD style and flow direction selection should be menu-based, not a raw memory test; offer known styles, a custom style-id fallback, and top-to-bottom / left-to-right / snake render choices.

When the user asks to edit an existing chart without saying 沉淀到 skill / SKILL FIX, treat it as an instance edit: update the current work Markdown or contract and regenerate the SVG. Do not modify skill docs, renderer, fixtures, or snapshots unless the output violates existing QA or the user explicitly asks to upgrade the skill.

Required Workflow

1. Ingest the user input or draft.
2. Choose the intake path:
   • For prose, SOPs, step lists, and agent/tool sketches, use references/natural-language-extraction.md.
   • For image or existing-flowchart inputs, use arrow-first interpretation from references/workflow-method.md.
3. Extract semantic candidates before drafting: scope, actors, artifacts, nodes, decisions, branches, exceptions, parallel semantics, constraints, inputs, and outputs.
4. For natural-language input, keep a semantic candidate table or internal equivalent so every node and edge can be traced to source text or an explicit assumption.
5. Ask only about ambiguity that would change workflow meaning. Put safe assumptions in assumptions.
6. Draft the workflow contract before any diagram. Never generate SVG directly from natural language or an image.
7. Run semantic QA.
8. Run contract QA with scripts/validate_contract.py when a contract file exists or can be created.
   • Treat parallel gateway validation failures as semantic-model failures; revise the contract instead of hiding or restyling the gateways.
9. Resolve the style through the Style Selection Gate.
10. Render SVG from the validated contract with scripts/render_workflow_svg.py.
11. Run diagram QA.
12. Return the contract, diagram path, selected style, assumptions, warnings, and open questions.

References

• Read references/natural-language-extraction.md for prose, SOP, step-list, and agent/tool sketch inputs.
• Read references/workflow-method.md for semantic extraction, ambiguity handling, and semantic QA.
• Read references/contract-schema.md before drafting or validating contracts.
• Read references/visual-style.md before rendering or reviewing SVG output.
• Read references/modern-tech-style.md when the user chooses or requests Modern Tech Style.
• Read references/examples.md when examples or forward tests are useful.
• Read references/issue-checklist.md when a user reports a semantic, renderer, or style bug.
• Read references/style-benchmark.md before tuning the default visual style.
• Read references/roadmap.md before expanding the skill or changing Phase 1 scope.

Script Usage

Validate a contract:

python scripts/validate_contract.py path/to/workflow.yaml

Render a contract to SVG:

python scripts/render_workflow_svg.py --style engineering-basic path/to/workflow.yaml path/to/workflow.svg

Render with Modern Tech Style:

python scripts/render_workflow_svg.py --style modern-tech path/to/workflow.yaml path/to/workflow.svg

Create a non-technical editable workflow work file:

python scripts/new_workflow.py my-flow --style modern-tech

Regenerate a work SVG after editing work/my-flow.md:

python scripts/render_work.py my-flow --style modern-tech

Render a matrix with stages as rows and participants as columns:

python scripts/render_work.py my-flow --style modern-tech --matrix-axis phases-rows

Render a compact four-rank snake flow:

python scripts/render_work.py my-flow --style engineering-basic --layout-orientation snake

Start the local browser editor:

python scripts/workflow_builder_server.py

Verify Markdown work-file fixtures:

python scripts/verify_workflow_markdown.py

List available styles:

python scripts/render_workflow_svg.py --list-styles

Run fixture regressions:

python scripts/run_regression.py

Validate one rendered snake SVG:

python scripts/validate_snake_svg.py path/to/workflow.yaml path/to/workflow.svg --style engineering-basic

Check natural-language fixture traceability:

python scripts/check_fixture_traceability.py

Refresh SVG snapshots after an intentional renderer or style change:

python scripts/run_regression.py --update

The scripts support JSON and a small YAML subset used by this skill. If PyYAML is installed, full YAML parsing is attempted first.

Output Discipline

When presenting results, keep the contract and diagram relationship explicit:

• State that the diagram was derived from the contract.
• List any semantic assumptions or unresolved open questions.
• Mention validation warnings that could affect interpretation.
• Do not present a diagram as final if contract or diagram QA failed.