Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
HTML agent-skillsai-agentsarchitecture-diagramclaude-codeclaude-skillscodexcoding-agentsdeepseek-harnessdeveloper-toolsdiagramsdiagrams-as-codedsh-pluginflowchartllmmermaidopencodesequence-diagramsoftware-architecturesystem-designvisualization
feat(skill): add plan-first mode for manual edge routing
sanpatricky6b1fdf26873b
diff --git a/archify/SKILL.md b/archify/SKILL.mdindex 4011ba54..f60c32a9 100644--- a/archify/SKILL.md+++ b/archify/SKILL.md@@ -18,7 +18,7 @@ Use this bounded path for ordinary generation. Do not read the optional Viewer R1. Choose `architecture`, `workflow`, `sequence`, `dataflow`, or `lifecycle` from the question.2. Read one matching schema in `schemas/`, `schemas/common.schema.json`, and one matching JSON example in `examples/`. Read only those files. Fresh authorship means new stable IDs, domain wording, and layout; use the example for field shape, not facts. New workflow sources use `schema_version: 2` and its readable layout contract; keep `schema_version: 1` only when preserving an existing workflow's fixed geometry. When real product identity matters, query `node bin/archify.mjs brands "<name>" --json`; read `references/brand-marks.md` only for an unknown brand with a user-provided URL.-3. Artifact first: the next tool action must write the candidate. Write the candidate before inspecting renderer internals. Do not plan exact coordinates in prose. Start with one clear main path, short side branches, sparse labels, and at most 12 primary nodes. Set `meta.quality_profile` to `"showcase"` unless the user explicitly requests a dense `standard` map. Start with automatic routes and labels. Do not add `via`, `channelX`, `channelY`, or `labelAt` before a diagnostic calls for one; apply at most one diagnosed geometry control per repair.+3. Artifact first: the next tool action must write the candidate. Write the candidate before inspecting renderer internals. Do not plan exact coordinates in prose. Start with one clear main path, short side branches, sparse labels, and at most 12 primary nodes. Set `meta.quality_profile` to `"showcase"` unless the user explicitly requests a dense `standard` map. Start with automatic routes and labels. Do not add `via`, `channelX`, `channelY`, or `labelAt` before a diagnostic calls for one; apply at most one diagnosed geometry control per repair. **Plan-first mode for manual routing:** when validation reports geometry errors or visual inspection reveals edge overlaps, switch workflow before attempting fixes: (a) run `validate <type> <candidate.json> --layout-json` to obtain exact node rects and resolved edge polylines; (b) **prefer automatic over manual** — when edges overlap on the same node side, first check whether port spread is disabled for any of them by `route` presets, `via`, `channelX/Y`, or `labelAt`; if so, evaluate whether removing the disabling control lets spread resolve the overlap automatically — only proceed to manual `via` if spread cannot help; (c) read the route-preset behaviors and port-spread rules in `references/authoring-contract.md` (§ Executable geometry rules, § Spacing and labels) to understand what each route mode produces — do not trial-and-error route modes; (d) for each affected edge, calculate whether the planned route has sufficient channel width for labels (`mask width + 8px`) and clearance from adjacent segments (`≥4px`); (e) implement all spatially coupled geometry controls together as a batch, then validate once.4. Validate after every candidate edit and immediately before handoff:```bash@@ -43,7 +43,7 @@ After the first candidate exists, run the packaged checker `scripts/check-updateThe notice is information, not permission. Keep the installed version unchanged; this v0.1 workflow never downloads, installs, or executes an update, and silence is never consent.-Do not read `renderers/shared/geometry.mjs`, renderer source, validator source, tests, or benchmarks before the first candidate. Inspect implementation only for an unsupported internal diagnostic or after two focused repairs fail.+Do not read `renderers/shared/geometry.mjs`, renderer source, validator source, tests, or benchmarks before the first candidate. Inspect implementation only for an unsupported internal diagnostic or after two focused repairs fail. **Exception — plan-first mode:** when validation reports geometry errors requiring manual routing (non-auto `route`, `via`, or `fromSide`/`toSide` changes), read the route-preset and port-spread sections of `references/authoring-contract.md` and run `--layout-json` BEFORE attempting fixes. Understanding route-mode behavior first prevents blind trial-and-error.Workflow note: use schema v2 for new workflows; preserve schema v1 when anexisting source needs fixed legacy geometry. Keep semantic edge labels and act