Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

Let shorthand workflows wrap long processes into phase lanes

tt-a1ibadbc384a277
diff --git a/archify/explainer/diagrams.mjs b/archify/explainer/diagrams.mjs
index 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 = 1
duplicateCheck(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 = 1
spec.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.md
index 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.mjs
index 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, mismat
await 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)));
+});