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
Let shorthand workflows wrap long processes into phase lanes
tt-a1ibadbc384a277
diff --git a/archify/explainer/diagrams.mjs b/archify/explainer/diagrams.mjsindex 74e4031d..dad42d33 100644--- a/archify/explainer/diagrams.mjs+++ b/archify/explainer/diagrams.mjs@@ -148,17 +148,25 @@ export function compileExplainerDiagram(diagramType, rows, { title, id, line = 1duplicateCheck(spec.participants, context, 'actor');if (!spec.messages.length) fail(context, 'diagram-rows', 'Sequence shorthand needs a message.', 'client | api | 请求记录');} else if (diagramType === 'architecture' || diagramType === 'workflow') {- const nodes = [], edges = [];+ const nodes = [], edges = [], lanes = new Map(), nodeLanes = new Map();for (const entry of entries) {const route = entry.parts[0].match(/^([a-zA-Z][a-zA-Z0-9_-]*)\s*>\s*([a-zA-Z][a-zA-Z0-9_-]*)$/);- if (route) {+ if (diagramType === 'workflow' && entry.parts[0].startsWith('lane ')) {+ expect(entry, 2, 2, 'lane locate | Locate the cause');+ const laneId = safeId(entry.parts[0].slice(5).trim(), entry.context);+ if (lanes.has(laneId)) fail(entry.context, 'diagram-id-duplicate', 'Workflow lane ids must be unique.', 'lane locate | Locate the cause');+ lanes.set(laneId, { id: laneId, label: entry.parts[1] });+ } else if (route) {if (entry.parts.length > 3) fail(entry.context, 'diagram-row', 'An edge supports a label and optional native variant.', 'api > redis | 查询 | dashed');context.rowMap[`/${diagramType === 'architecture' ? 'connections' : 'edges'}/${edges.length}`] = entry.context.line;edges.push({ id: edgeId(route[1], route[2]), from: route[1], to: route[2], ...(entry.parts[1] ? { label: entry.parts[1] } : {}), ...(entry.parts[2] ? { variant: entry.parts[2] } : {}) });} else {- expect(entry, 2, 3, 'api | API | backend');+ if (diagramType === 'workflow') expect(entry, 2, 4, 'trace | Compare slow traces | backend | locate');+ else expect(entry, 2, 3, 'api | API | backend');context.rowMap[`/${diagramType === 'architecture' ? 'components' : 'nodes'}/${nodes.length}`] = entry.context.line;- nodes.push({ id: safeId(entry.parts[0], entry.context), label: entry.parts[1], type: entry.parts[2] || 'backend' });+ const node = { id: safeId(entry.parts[0], entry.context), label: entry.parts[1], type: entry.parts[2] || 'backend' };+ if (entry.parts[3]) nodeLanes.set(node.id, { lane: safeId(entry.parts[3], entry.context), context: entry.context });+ nodes.push(node);}}duplicateCheck(nodes, context, 'node');@@ -169,8 +177,21 @@ export function compileExplainerDiagram(diagramType, rows, { title, id, line = 1spec.layout = { mode: 'grid', cols, cellW: 176, cellH: 76, gapX: 100, gapY: 110 };spec.components = placed;spec.connections = edges;+ } else if (lanes.size) {+ for (const [id, { lane, context: ctx }] of nodeLanes) if (!lanes.has(lane)) fail(ctx, 'diagram-lane', `Node ${id} names an undeclared lane.`, 'lane locate | Locate the cause');+ const first = lanes.keys().next().value;+ const nextCol = new Map();+ spec.lanes = [...lanes.values()];+ spec.nodes = [...placed].sort((a, b) => a.col - b.col || a.row - b.row).map(({ row, col, ...node }) => {+ const lane = nodeLanes.get(node.id)?.lane || first;+ const laneCol = nextCol.get(lane) || 0;+ nextCol.set(lane, laneCol + 1);+ return { ...node, lane, col: laneCol };+ });+ if (spec.nodes.some(node => node.col > 5)) fail(context, 'diagram-shorthand-limit', 'A workflow lane holds at most six nodes.', 'Split the process into another lane.');+ spec.edges = edges;} else {- if (placed.some(node => node.col > 5)) fail(context, 'diagram-shorthand-limit', 'Native workflow columns are limited to 0–5.', 'Use native workflow JSON with branches distributed across lanes.');+ if (placed.some(node => node.col > 5)) fail(context, 'diagram-shorthand-limit', 'Native workflow columns are limited to 0–5.', 'Declare phase lanes with "lane <id> | label" rows and assign nodes to them.');spec.lanes = Array.from({ length: Math.max(1, ...placed.map(node => node.row + 1)) }, (_, row) => ({ id: `lane-${row}`, label: row ? `分支 ${row}` : spec.meta.title }));spec.nodes = placed.map(({ row, ...node }) => ({ ...node, lane: `lane-${row}` }));spec.edges = edges;diff --git a/archify/references/explainer-authoring.md b/archify/references/explainer-authoring.mdindex 4f865858..12a9eb54 100644--- a/archify/references/explainer-authoring.md+++ b/archify/references/explainer-authoring.md@@ -111,7 +111,24 @@ Actor rows: `actor <id> | label | type`. Message rows: `from | to | label | vari| trace > fix | cause found | emphasis |```-Node rows: `id | label | type?`. Edge rows: `from > to | label? | variant?`. Nodes widen to fit their labels. Keep a workflow to five nodes along its longest path and edge labels to one or two words: a longer chain shrinks its text below the readable size; use `@steps` for long sequences. Architecture allows twelve columns. Use `@architecture` for components that talk to each other and `@workflow` for steps a reader follows.+Node rows: `id | label | type?`. Edge rows: `from > to | label? | variant?`. Nodes widen to fit their labels. Keep edge labels to one or two words.++A workflow row reads well with up to three or four nodes. Split a longer process into phase lanes: declare `lane <id> | label` rows, then give each workflow node its lane as a fourth cell. Each lane becomes one row in reading order; edges between lanes connect the rows.++```md+@workflow id=p99-flow title="P99 triage"+| lane confirm | Confirm the symptom |+| lane locate | Locate the cause |+| alert | P99 up, mean flat | external | confirm |+| window | Align window and percentiles | backend | confirm |+| sample | Sample slow requests | backend | locate |+| fix | Fix and verify | backend | locate |+| alert > window | |+| window > sample | tail grew |+| sample > fix | cause | emphasis |+```++Architecture allows twelve columns. Use `@architecture` for components that talk to each other and `@workflow` for steps a reader follows.**`@tree`**: one row per node, `id | label | parent`; the root's parent is `-`.diff --git a/test/explainer-diagrams.test.mjs b/test/explainer-diagrams.test.mjsindex 40b99957..9a934a0d 100644--- a/test/explainer-diagrams.test.mjs+++ b/test/explainer-diagrams.test.mjs@@ -185,3 +185,14 @@ test('explainer diagrams: source containment rejects traversal, symlinks, mismatawait assert.rejects(read('mismatch.json'), error => error.archifyDiagnostics[0].code === 'explainer/diagram-type-mismatch');} finally { fs.rmSync(directory, { recursive: true, force: true }); }});++test('explainer diagrams: workflow phase lanes restart columns per lane and reject undeclared lanes', () => {+ const spec = compileExplainerDiagram('workflow', ['lane confirm | Confirm', 'lane locate | Locate',+ 'alert | Alert | external | confirm', 'window | Window | backend | confirm', 'sample | Sample | backend | locate', 'fix | Fix | backend | locate',+ 'alert > window', 'window > sample | tail', 'sample > fix'], { id: 'phases' });+ assert.deepEqual(spec.lanes, [{ id: 'confirm', label: 'Confirm' }, { id: 'locate', label: 'Locate' }]);+ assert.deepEqual(spec.nodes.map(node => [node.id, node.lane, node.col]), [['alert', 'confirm', 0], ['window', 'confirm', 1], ['sample', 'locate', 0], ['fix', 'locate', 1]]);+ assert.ok(spec.nodes.every(node => node.width === undefined));+ assert.throws(() => compileExplainerDiagram('workflow', ['lane confirm | Confirm', 'alert | Alert | external | missing'], { id: 'phases' }),+ error => (error.archifyDiagnostics || error.diagnostics || []).some(item => /undeclared lane/.test(item.message)));+});