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(lifecycle): route and label first drafts with the shared planner
tt-a1i733691008770
diff --git a/archify.zip b/archify.zipindex 0fccd10d..eee267c7 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/SKILL.md b/archify/SKILL.mdindex 131e5db5..06eda4e1 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, and sparse labels. Use roughly 12 primary nodes as an initial readability budget. Preserve every node and relationship required by the user's question; for larger diagrams, group related content where the selected schema supports it. 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; test one repair hypothesis per round. When geometry fails or repeats, read the repair order in `references/authoring-contract.md` and inspect measured layout before manual routing: use `validate <type> <candidate.json> --layout-json` for architecture/workflow; for other types, use validation diagnostics and the rendered SVG geometry. Check whether unnecessary agent-added controls disable automatic port spread; preserve user-required route intent. If several edges share a constrained channel, compare a small node-layout change with adding route controls; validate the coupled change together while preserving required nodes, relationships, labels, and boundary membership.+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, and sparse labels. Use roughly 12 primary nodes as an initial readability budget. Preserve every node and relationship required by the user's question; for larger diagrams, group related content where the selected schema supports it. 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`, `route`, `fromSide`, `toSide`, `channelX`, `channelY`, or `labelAt` before a diagnostic calls for one; test one repair hypothesis per round. When geometry fails or repeats, read the repair order in `references/authoring-contract.md` and inspect measured layout before manual routing: use `validate <type> <candidate.json> --layout-json` for architecture/workflow; for other types, use validation diagnostics and the rendered SVG geometry. Check whether unnecessary agent-added controls disable automatic port spread; preserve user-required route intent. If several edges share a constrained channel, compare a small node-layout change with adding route controls; validate the coupled change together while preserving required nodes, relationships, labels, and boundary membership.4. Validate after every candidate edit and immediately before handoff:```bashdiff --git a/archify/renderers/lifecycle/render-lifecycle.mjs b/archify/renderers/lifecycle/render-lifecycle.mjsindex 12ed5e51..9d830c67 100644--- a/archify/renderers/lifecycle/render-lifecycle.mjs+++ b/archify/renderers/lifecycle/render-lifecycle.mjs@@ -3,6 +3,8 @@ import { fileURLToPath } from 'node:url';import { esc, renderDefinitions, renderSemanticSigil, textUnits } from '../shared/utils.mjs';import { animateAttr, focusEdgeAttrs, focusNodeAttrs, focusNodeTitle, loadDiagramWithBrandMarks, writeDiagram, svgAccessibleText, svgRootAttrs } from '../shared/cli.mjs';import { throwDiagnosticProblems } from '../shared/diagnostics.mjs';+import { createRouter } from '../architecture/routing.mjs';+import { placeAutomaticLabels } from '../architecture/labels.mjs';import { resolveLegend, renderLegend as renderResolvedLegend } from '../shared/legend.mjs';import { availableNodeTextWidth, fittedNodeFontSize, minimumNodeTextWidth, nodeLabelLayout } from '../shared/text-fit.mjs';import { brandLabelFitWidth, brandMarkFor, brandMetadataFor, brandTopRailProblem, renderBrandMark } from '../shared/brand-marks.mjs';@@ -255,6 +257,8 @@ function validateLifecycle() {diagramType: 'lifecycle',relationCollection: 'transitions',profile: lifecycle.meta?.quality_profile,+ // Planner routes render with the opaque crossover halo, like architecture.+ crossingResolved: (left, right) => plannerRouted(left) && plannerRouted(right),routeHint: 'adjust route/via or channelX/channelY so the transitions use separate lifecycle corridors'}));problems.push(...cleanAmbiguousCorridorProblems({@@ -288,15 +292,7 @@ function validateLifecycle() {routeHint: 'move route/via or channel coordinates so each lifecycle turn has a readable run-up'}));- const labelRects = [];- for (const [transitionIndex, transition] of asArray(lifecycle.transitions).entries()) {- if (!transition.label || !states.has(transition.from) || !states.has(transition.to)) continue;- const [lx, ly] = labelPoint(transition, pathFor(transition).points);- const longestLine = Math.max(textUnits(transition.label), textUnits(transition.note || ''));- const width = Math.max(32, longestLine * 4.9 + 12);- const height = transition.note ? 27 : 16;- labelRects.push({ relation: transition, relationIndex: transitionIndex, label: transition.label, x: lx - width / 2, y: ly - 11, width, height, lx, ly });- }+ const labelRects = transitionLabelRects();for (const rect of labelRects) {for (const state of states.values()) {if (rectsOverlap(rect, state, -2)) {@@ -380,7 +376,22 @@ function routeVia(transition, from, to, start, end, fromSide, toSide) {const pathCache = new Map();+// A transition without via, channel, or a lifecycle route preset is routed by+// the obstacle-aware planner shared with architecture, so a first draft that+// leaves routing to the renderer does not cross unrelated states or produce+// micro jogs. Authored via/route/channel geometry keeps the lifecycle presets.+function plannerRouted(transition) {+ return !transition.via+ && (!transition.route || transition.route === 'auto')+ && transition.channelX === undefined+ && transition.channelY === undefined;+}++const plannedTransitions = asArray(lifecycle.transitions).filter(plannerRouted);+const planner = createRouter(states, plannedTransitions);+function transitionSides(transition) {+ if (plannerRouted(transition)) return planner.connectionSides(transition);const from = states.get(transition.from);const to = states.get(transition.to);return {@@ -389,12 +400,19 @@ function transitionSides(transition) {};}-const automaticPorts = automaticPortSpread(lifecycle.transitions, states, {- sideFor: (transition, endpoint) => transitionSides(transition)[endpoint === 'source' ? 'fromSide' : 'toSide'],-});+const automaticPorts = automaticPortSpread(+ asArray(lifecycle.transitions).filter((transition) => !plannerRouted(transition)),+ states,+ { sideFor: (transition, endpoint) => transitionSides(transition)[endpoint === 'source' ? 'fromSide' : 'toSide'] },+);function pathFor(transition) {if (pathCache.has(transition)) return pathCache.get(transition);+ if (plannerRouted(transition)) {+ const routed = planner.pathFor(transition);+ pathCache.set(transition, routed);+ return routed;+ }const from = states.get(transition.from);const to = states.get(transition.to);const ports = automaticPorts.get(transition);@@ -415,6 +433,42 @@ function pathFor(transition) {return routed;}+const resolvedLabelPoints = new Map();++function transitionLabelBox(transition) {+ const [lx, ly] = resolvedLabelPoints.get(transition) || labelPoint(transition, pathFor(transition).points);+ const longestLine = Math.max(textUnits(transition.label), textUnits(transition.note || ''));+ const width = Math.max(32, longestLine * 4.9 + 12);+ const height = transition.note ? 27 : 16;+ return { x: lx - width / 2, y: ly - 11, width, height, lx, ly };+}++function transitionLabelRects() {+ const rects = [];+ for (const [relationIndex, transition] of asArray(lifecycle.transitions).entries()) {+ if (!transition.label || !states.has(transition.from) || !states.has(transition.to)) continue;+ rects.push({ relation: transition, relationIndex, label: transition.label, ...transitionLabelBox(transition) });+ }+ return rects;+}++// Showcase drafts leave label positions to the renderer too: move an unpinned+// label off other routes and states instead of reporting a clearance defect.+if (lifecycle.meta?.quality_profile === 'showcase') {+ const placed = placeAutomaticLabels({+ labels: transitionLabelRects(),+ routes: asArray(lifecycle.transitions).flatMap((transition, relationIndex) => (+ states.has(transition.from) && states.has(transition.to)+ ? [{ relationIndex, points: pathFor(transition).points }] : []+ )),+ components: [...states.values()],+ titles: [],+ viewBox,+ placementBottom: lifecycleAreaBottom(),+ });+ for (const rect of placed) resolvedLabelPoints.set(rect.relation, [rect.lx, rect.ly]);+}+function bandTitles() {const lanes = asArray(lifecycle.lanes);const mainLane = lanes.find((lane) => lane.id === 'main');@@ -481,16 +535,19 @@ function renderTransitionPath(transition, index) {const [cls, marker] = arrowClassMap[transition.variant || 'default'] || arrowClassMap.default;const routed = pathFor(transition);const strokeWidth = transition.width || (transition.variant === 'emphasis' ? 2 : 1.1);- return ` <path ${focusEdgeAttrs(transition.from, transition.to, transition.label, index, transition.id)} data-composition-points="${routePointsValue(routed.points)}"${authoredStraightRouteAttrs(transition, routed.points)} d="${routed.d}" class="${cls}"${animateAttr(lifecycle.meta, 'edge', index)} stroke-width="${strokeWidth}" marker-end="url(#${marker})"/>`;+ const automaticRoute = plannerRouted(transition);+ const crossover = automaticRoute ? ' data-composition-crossover="halo"' : '';+ const edge = ` <path ${focusEdgeAttrs(transition.from, transition.to, transition.label, index, transition.id)} data-composition-points="${routePointsValue(routed.points)}"${crossover}${authoredStraightRouteAttrs(transition, routed.points)} d="${routed.d}" class="${cls}"${animateAttr(lifecycle.meta, 'edge', index)} stroke-width="${strokeWidth}" marker-end="url(#${marker})"/>`;+ if (!automaticRoute) return edge;+ // Same presentation-only wrapper as architecture: the mask underlay lets two+ // planner routes cross legibly while the viewer still sees one semantic edge.+ const underlay = ` <path data-graph-role="automatic-crossover-underlay" d="${routed.d}" fill="none" stroke="var(--mask)" stroke-width="${strokeWidth + 4}" stroke-linecap="round" stroke-linejoin="round" pointer-events="none"/>\n`;+ return ` <g data-graph-role="automatic-crossover" style="--step:${index}">\n${underlay}${edge.replace(/^ /, ' ')}\n </g>`;}function renderTransitionLabel(transition, index) {if (!transition.label) return '';- const routed = pathFor(transition);- const [lx, ly] = labelPoint(transition, routed.points);- const longestLine = Math.max(textUnits(transition.label), textUnits(transition.note || ''));- const labelW = Math.max(32, longestLine * 4.9 + 12);- const labelH = transition.note ? 27 : 16;+ const { lx, ly, width: labelW, height: labelH } = transitionLabelBox(transition);const note = transition.note? `\n <text data-detail="fine" x="${lx}" y="${ly + 11}" class="t-dim" font-size="7" text-anchor="middle">${esc(transition.note)}</text>`: '';@@ -539,7 +596,12 @@ function renderLifecycleRail() {}function renderSvg() {- return ` <svg viewBox="0 0 ${viewBox[0]} ${viewBox[1]}" ${svgRootAttrs(lifecycle.meta)}>+ // A renderer-sized canvas declares the intrinsic-height fit exactly like+ // architecture: the default 980x660 band layout is below the 1.55 wide+ // ratio, so without this the desktop Reader could neither narrow it nor+ // scroll it and every default lifecycle failed the browser gate.+ const readerFit = lifecycle.meta?.viewBox ? '' : ' data-reader-fit="intrinsic-height"';+ return ` <svg viewBox="0 0 ${viewBox[0]} ${viewBox[1]}"${readerFit} ${svgRootAttrs(lifecycle.meta)}>${svgAccessibleText(lifecycle.meta, 'lifecycle')}${renderDefinitions()}diff --git a/archify/renderers/shared/route-quality.mjs b/archify/renderers/shared/route-quality.mjsindex fb813f8e..5ae761ca 100644--- a/archify/renderers/shared/route-quality.mjs+++ b/archify/renderers/shared/route-quality.mjs@@ -250,6 +250,7 @@ export function shortestOrthogonalGridRoute({avoidedSegments = [],minimumAvoidedOverlapPx = 8,routeSeparationPx = 8,+ minimumSegmentPx = 8,metrics,}) {writeGridMetrics(metrics, {@@ -311,8 +312,14 @@ export function shortestOrthogonalGridRoute({ys.add(segmentStart[1] + routeSeparationPx);}}- const orderedX = [...xs].sort((a, b) => a - b);- const orderedY = [...ys].sort((a, b) => a - b);+ // Grid lines closer than a readable segment would let the search emit a+ // micro jog between two obstacle edges; keep the endpoint stubs and coalesce+ // the rest so every turn the route can take is at least one segment long.+ const coalesce = (values, keep) => values.sort((a, b) => a - b).filter((value, index, sorted) => (+ index === 0 || keep.has(value) || value - sorted[index - 1] >= minimumSegmentPx+ ));+ const orderedX = coalesce([...xs], new Set([startStub[0], endStub[0]]));+ const orderedY = coalesce([...ys], new Set([startStub[1], endStub[1]]));const candidateNodeCount = orderedX.length * orderedY.length;writeGridMetrics(metrics, {coordinateCount: orderedX.length + orderedY.length,diff --git a/archify/test/fixtures/lifecycle-planner/review-hub.lifecycle.json b/archify/test/fixtures/lifecycle-planner/review-hub.lifecycle.jsonnew file mode 100644index 00000000..2924a63d--- /dev/null+++ b/archify/test/fixtures/lifecycle-planner/review-hub.lifecycle.json@@ -0,0 +1,28 @@+{+ "schema_version": 1,+ "diagram_type": "lifecycle",+ "meta": { "title": "Review hub fan-out", "output": "review-hub.html", "quality_profile": "showcase" },+ "lanes": [+ { "id": "main", "label": "Main" },+ { "id": "side", "label": "Side" },+ { "id": "terminal", "label": "Terminal" }+ ],+ "states": [+ { "id": "draft", "lane": "main", "col": 0, "type": "start", "label": "Draft" },+ { "id": "submitted", "lane": "main", "col": 1, "type": "active", "label": "Submitted" },+ { "id": "review", "lane": "main", "col": 2, "type": "active", "label": "Under review" },+ { "id": "approved", "lane": "main", "col": 3, "type": "success", "label": "Approved" },+ { "id": "sla", "lane": "side", "col": 0, "type": "waiting", "label": "SLA wait", "yOffset": -6 },+ { "id": "changes", "lane": "side", "col": 0, "type": "decision", "label": "Changes requested", "yOffset": 72 },+ { "id": "rejected", "lane": "terminal", "col": 1, "type": "failure", "label": "Rejected" }+ ],+ "transitions": [+ { "id": "submit", "from": "draft", "to": "submitted", "label": "submit" },+ { "id": "assign", "from": "submitted", "to": "review", "label": "assign" },+ { "id": "approve", "from": "review", "to": "approved", "label": "approve" },+ { "id": "wait", "from": "review", "to": "sla", "label": "clock" },+ { "id": "request", "from": "review", "to": "changes", "label": "request changes" },+ { "id": "reject", "from": "review", "to": "rejected", "label": "reject" },+ { "id": "reopen", "from": "changes", "to": "draft", "label": "reopen", "variant": "dashed" }+ ]+}diff --git a/archify/test/lifecycle-planner.test.mjs b/archify/test/lifecycle-planner.test.mjsnew file mode 100644index 00000000..e1750da8--- /dev/null+++ b/archify/test/lifecycle-planner.test.mjs@@ -0,0 +1,56 @@+import { test } from 'node:test';+import assert from 'node:assert/strict';+import { execFileSync, spawnSync } from 'node:child_process';+import fs from 'node:fs';+import os from 'node:os';+import path from 'node:path';+import { fileURLToPath } from 'node:url';++const skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+const cli = path.join(skillRoot, 'bin/archify.mjs');+const renderer = path.join(skillRoot, 'renderers/lifecycle/render-lifecycle.mjs');+const fixture = path.join(skillRoot, 'test/fixtures/lifecycle-planner/review-hub.lifecycle.json');++function validate(input) {+ const result = spawnSync(process.execPath, [cli, 'validate', 'lifecycle', input, '--quality', 'showcase', '--json'], { encoding: 'utf8' });+ return { status: result.status, receipt: JSON.parse(result.stdout) };+}++// Before the planner, this hub fan-out produced two edge-through-node, four+// micro-segment and several label-clearance diagnostics from a candidate that+// declared no route controls at all; the author had nothing to repair except+// hand-routing every transition.+test('lifecycle: a first draft without route controls validates for showcase', () => {+ const { status, receipt } = validate(fixture);+ assert.equal(status, 0, JSON.stringify(receipt.diagnostics, null, 2));+ assert.equal(receipt.ok, true);+ assert.equal(receipt.composition.summary.errors, 0);+ assert.equal(receipt.composition.metrics.viewportHeightIssues, 0, 'the renderer-sized canvas declares its Reader fit');+});++test('lifecycle: planner routes render as one semantic edge with a crossover mask, presets keep their own path', () => {+ const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-lifecycle-planner-'));+ try {+ const output = path.join(tmp, 'review-hub.html');+ execFileSync(process.execPath, [renderer, fixture, output]);+ const html = fs.readFileSync(output, 'utf8');+ assert.match(html, /<svg viewBox="0 0 980 660" data-reader-fit="intrinsic-height"/);+ const wrappers = html.match(/<g data-graph-role="automatic-crossover"/g) || [];+ assert.equal(wrappers.length, 7, 'every automatic transition is planner routed');+ assert.equal((html.match(/data-composition-crossover="halo"/g) || []).length, 7);+ assert.equal((html.match(/data-edge-from="review"/g) || []).length >= 4, true);++ const authored = JSON.parse(fs.readFileSync(fixture, 'utf8'));+ authored.meta.viewBox = [1100, 660];+ authored.transitions[0].route = 'drop';+ const authoredInput = path.join(tmp, 'authored.lifecycle.json');+ fs.writeFileSync(authoredInput, JSON.stringify(authored));+ const authoredOutput = path.join(tmp, 'authored.html');+ execFileSync(process.execPath, [renderer, authoredInput, authoredOutput]);+ const authoredHtml = fs.readFileSync(authoredOutput, 'utf8');+ assert.doesNotMatch(authoredHtml, /data-reader-fit=/, 'an authored viewBox keeps the authored fit contract');+ assert.equal((authoredHtml.match(/<g data-graph-role="automatic-crossover"/g) || []).length, 6, 'the drop preset is not planner routed');+ } finally {+ fs.rmSync(tmp, { recursive: true, force: true });+ }+});diff --git a/archify/test/ordinary-model-floor.test.mjs b/archify/test/ordinary-model-floor.test.mjsindex d438a1db..162e7c5b 100644--- a/archify/test/ordinary-model-floor.test.mjs+++ b/archify/test/ordinary-model-floor.test.mjs@@ -914,7 +914,7 @@ test('packaged skill puts a bounded ordinary-model path before progressive featu'Fresh authorship means new stable IDs, domain wording, and layout','Write the candidate before inspecting renderer internals','Start with automatic routes and labels',- 'Do not add `via`, `channelX`, `channelY`, or `labelAt` before a diagnostic',+ 'Do not add `via`, `route`, `fromSide`, `toSide`, `channelX`, `channelY`, or `labelAt` before a diagnostic','Set `meta.quality_profile` to `"showcase"`','A recoverable state uses `type: "failure"` plus a real transition back to the active state','after every candidate edit',