Skip to content

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

Rework lifecycle diagram as phase map

tt-a1icaeb610fb78c
diff --git a/archify.zip b/archify.zip
index 99c62bc6..8b75086a 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/examples/agent-run.lifecycle.json b/archify/examples/agent-run.lifecycle.json
index ab202fd5..74c7d329 100644
--- a/archify/examples/agent-run.lifecycle.json
+++ b/archify/examples/agent-run.lifecycle.json
@@ -5,35 +5,30 @@
"title": "Agent Run Lifecycle",
"subtitle": "State machine for planning, tool execution, human approval, retries, and terminal outcomes",
"output": "examples/lifecycle-agent-run.html",
- "viewBox": [980, 610]
+ "viewBox": [980, 660]
},
"lanes": [
- { "id": "main", "label": "Active lifecycle" },
- { "id": "waiting", "label": "Suspended states" },
+ { "id": "main", "label": "Lifecycle phases" },
+ { "id": "waiting", "label": "Interruptions" },
{ "id": "exceptions", "label": "Recovery loop" },
- { "id": "terminal", "label": "Terminal outcomes" }
+ { "id": "terminal", "label": "Terminal exits" }
],
"states": [
- { "id": "queued", "type": "start", "label": "Queued", "sublabel": "request accepted", "lane": "main", "col": 0, "tag": "entry" },
- { "id": "planning", "type": "active", "label": "Planning", "sublabel": "build task graph", "lane": "main", "col": 1, "tag": "model" },
- { "id": "executing", "type": "active", "label": "Executing", "sublabel": "tool calls", "lane": "main", "col": 2, "tag": "work" },
- { "id": "reviewing", "type": "decision", "label": "Reviewing", "sublabel": "quality gate", "lane": "main", "col": 3, "tag": "check" },
- { "id": "approval", "type": "waiting", "label": "Needs Approval", "sublabel": "human gate", "lane": "waiting", "col": 2, "tag": "pause" },
- { "id": "blocked", "type": "waiting", "label": "Blocked", "sublabel": "missing input", "lane": "waiting", "col": 4, "tag": "wait" },
- { "id": "failed", "type": "failure", "label": "Failed", "sublabel": "recoverable error", "lane": "exceptions", "col": 1, "tag": "retryable" },
- { "id": "cancelled", "type": "failure", "label": "Cancelled", "sublabel": "user stopped", "lane": "terminal", "col": 2, "tag": "terminal" },
- { "id": "completed", "type": "success", "label": "Completed", "sublabel": "final response", "lane": "terminal", "col": 3, "tag": "success" },
- { "id": "expired", "type": "failure", "label": "Expired", "sublabel": "timeout", "lane": "terminal", "col": 4, "tag": "terminal" }
+ { "id": "queued", "type": "start", "label": "Queued", "sublabel": "request accepted", "lane": "main", "col": 0, "step": "01", "tag": "entry" },
+ { "id": "planning", "type": "active", "label": "Planning", "sublabel": "build task graph", "lane": "main", "col": 1, "step": "02", "tag": "model" },
+ { "id": "executing", "type": "active", "label": "Executing", "sublabel": "tool calls", "lane": "main", "col": 2, "step": "03", "tag": "work" },
+ { "id": "reviewing", "type": "decision", "label": "Reviewing", "sublabel": "quality gate", "lane": "main", "col": 3, "step": "04", "tag": "check" },
+ { "id": "completed", "type": "success", "label": "Completed", "sublabel": "final response", "lane": "main", "col": 4, "step": "05", "tag": "done" },
+ { "id": "approval", "type": "waiting", "label": "Needs Approval", "sublabel": "human gate", "lane": "waiting", "col": 0, "tag": "pause" },
+ { "id": "blocked", "type": "waiting", "label": "Blocked", "sublabel": "missing input", "lane": "waiting", "col": 1, "tag": "wait" },
+ { "id": "failed", "type": "failure", "label": "Failed", "sublabel": "recoverable error", "lane": "exceptions", "col": 0, "yOffset": 78, "tag": "retryable" },
+ { "id": "cancelled", "type": "failure", "label": "Cancelled", "sublabel": "user stopped", "lane": "terminal", "col": 0, "tag": "terminal" },
+ { "id": "expired", "type": "failure", "label": "Expired", "sublabel": "timeout", "lane": "terminal", "col": 1, "tag": "terminal" }
],
"transitions": [
- { "from": "queued", "to": "planning", "variant": "emphasis", "route": "straight" },
- { "from": "planning", "to": "executing", "variant": "emphasis", "route": "straight" },
- { "from": "executing", "to": "reviewing", "variant": "emphasis", "route": "straight" },
- { "from": "reviewing", "to": "completed", "variant": "emphasis", "fromSide": "bottom", "toSide": "top", "route": "straight" },
{ "from": "executing", "to": "approval", "variant": "security", "fromSide": "bottom", "toSide": "top", "route": "straight" },
{ "from": "reviewing", "to": "blocked", "variant": "default", "route": "drop" },
- { "from": "executing", "to": "failed", "variant": "security", "fromSide": "left", "toSide": "top", "via": [[340, 304], [246, 304]] },
- { "from": "failed", "to": "planning", "variant": "dashed", "fromSide": "top", "toSide": "bottom", "route": "straight" },
+ { "from": "executing", "to": "failed", "variant": "security", "fromSide": "left", "toSide": "top", "via": [[340, 342], [402, 342]] },
{ "from": "blocked", "to": "expired", "variant": "security", "fromSide": "bottom", "toSide": "top", "route": "straight" },
{ "from": "approval", "to": "cancelled", "variant": "security", "fromSide": "bottom", "toSide": "top", "route": "straight" }
],
@@ -42,9 +37,9 @@
"dot": "emerald",
"title": "Main Path",
"items": [
- "Queued, Planning, Executing, and Reviewing are active run states",
- "A clean run reads left to right before exiting to an outcome",
- "A successful review exits into the terminal outcome lane"
+ "The run has five ordered phases from queue to completion",
+ "The primary lifecycle is carried by one horizontal rail",
+ "Completion is a phase, not a detached side box"
]
},
{
@@ -61,8 +56,8 @@
"title": "Terminal + Recovery",
"items": [
"Failed loops back while retry budget remains",
- "Completed, Cancelled, and Expired are visually grouped as outcomes",
- "Terminal states do not point back into active execution"
+ "Cancelled and Expired are exits from the lifecycle",
+ "Terminal exits do not point back into active execution"
]
}
]
diff --git a/archify/renderers/lifecycle/README.md b/archify/renderers/lifecycle/README.md
index c0e294ce..20745912 100644
--- a/archify/renderers/lifecycle/README.md
+++ b/archify/renderers/lifecycle/README.md
@@ -20,8 +20,8 @@ Lifecycle JSON files must set:
"diagram_type": "lifecycle",
"meta": {
"title": "Agent Run Lifecycle",
- "subtitle": "State machine for planning, execution, waits, retries, and terminal outcomes",
- "viewBox": [980, 720]
+ "subtitle": "Lifecycle phases, interruptions, recovery, and terminal exits",
+ "viewBox": [980, 660]
},
"lanes": [],
"states": [],
@@ -38,18 +38,16 @@ archify/schemas/lifecycle.schema.json
## Design Rules
-- Use lanes for lifecycle layers: active run states, suspended states,
- recovery loops, and terminal outcomes.
-- Place states with lane IDs and column indexes.
-- Keep the active path left-to-right, then exit into a distinct terminal
- outcome when the lifecycle ends.
-- Use `success` for terminal success, `failure` for failure/terminal error,
- `waiting` for pauses, and `decision` for gates.
-- Use `emphasis` for the main transition path.
-- Use `security` for cancellation, timeout, failure, policy, and blocked paths.
-- Use `dashed` for retry, resume, async, or non-primary transitions.
-- Keep transition labels short: `start`, `plan ready`, `needs approval`,
- `retry`, `timeout`, `cancel`.
+- Treat lifecycle diagrams as a phase map, not a dense state-transition graph.
+- Put the primary lifecycle on one horizontal rail using the `main` lane.
+- Use `step` labels for ordered phases, such as `01`, `02`, and `03`.
+- Use lower lanes only for interruptions, recovery, and terminal exits.
+- Keep transition labels out of the main SVG unless the label is essential;
+ prefer node labels, tags, legend entries, and summary cards.
+- Avoid diagonal and crossing lines. Terminal exits should drop vertically from
+ their source event whenever possible.
+- Use `success` for completion, `failure` for failure/terminal exits,
+ `waiting` for pauses, and `decision` for quality gates.
The renderer fails when it can detect layout problems, including duplicate state
IDs, unknown lanes, unknown transition endpoints, states outside their lanes,
diff --git a/archify/renderers/lifecycle/render-lifecycle.mjs b/archify/renderers/lifecycle/render-lifecycle.mjs
index 9f435e70..ab3eebdc 100644
--- a/archify/renderers/lifecycle/render-lifecycle.mjs
+++ b/archify/renderers/lifecycle/render-lifecycle.mjs
@@ -11,17 +11,20 @@ const templatePath = path.join(skillRoot, 'assets/template.html');
const template = fs.readFileSync(templatePath, 'utf8');
const outPath = path.resolve(process.cwd(), process.argv[3] || lifecycle.meta.output || 'lifecycle.html');
-const viewBox = lifecycle.meta.viewBox || [980, 720];
+const viewBox = lifecycle.meta.viewBox || [980, 660];
const layout = {
- laneX: 32,
- laneY: 44,
- laneW: 914,
- laneGap: 16,
- laneTitleH: 20,
- laneH: 104,
- colXs: [96, 246, 396, 546, 696, 846],
- nodeW: 112,
- nodeH: 54
+ phaseY: 126,
+ eventY: 278,
+ outcomeY: 450,
+ phaseW: 118,
+ phaseH: 62,
+ eventW: 126,
+ eventH: 58,
+ outcomeW: 118,
+ outcomeH: 58,
+ phaseXs: [94, 248, 402, 556, 710],
+ eventXs: [402, 556, 710],
+ outcomeXs: [402, 556, 710]
};
const typeClass = {
@@ -63,26 +66,22 @@ function esc(value) {
}[c]));
}
-const laneIndex = new Map((lifecycle.lanes || []).map((lane, index) => [lane.id, index]));
-
-function laneTop(id) {
- return layout.laneY + laneIndex.get(id) * (layout.laneH + layout.laneGap);
-}
-
-function lastLaneBottom() {
- return layout.laneY + lifecycle.lanes.length * layout.laneH + (lifecycle.lanes.length - 1) * layout.laneGap;
-}
-
function legendY() {
- return lastLaneBottom() + 44;
+ return 562;
}
function measureState(state) {
- const width = state.width || layout.nodeW;
- const height = state.height || layout.nodeH;
- const cx = layout.colXs[state.col];
- const contentH = layout.laneH - layout.laneTitleH;
- const y = laneTop(state.lane) + layout.laneTitleH + (contentH - height) / 2 + (state.yOffset || 0);
+ const isPhase = state.lane === 'main';
+ const isOutcome = state.lane === 'terminal';
+ const width = state.width || (isPhase ? layout.phaseW : isOutcome ? layout.outcomeW : layout.eventW);
+ const height = state.height || (isPhase ? layout.phaseH : isOutcome ? layout.outcomeH : layout.eventH);
+ const xs = isPhase ? layout.phaseXs : isOutcome ? layout.outcomeXs : layout.eventXs;
+ const cx = xs[state.col] ?? xs[xs.length - 1];
+ const y = (
+ isPhase ? layout.phaseY :
+ isOutcome ? layout.outcomeY :
+ layout.eventY
+ ) + (state.yOffset || 0);
return {
...state,
width,
@@ -123,16 +122,19 @@ function validateLifecycle() {
problems.push(`State "${state.id}" uses unknown lane "${state.lane}".`);
continue;
}
- if (typeof state.col !== 'number' || state.col < 0 || state.col >= layout.colXs.length) {
+ const maxCol = state.lane === 'main'
+ ? layout.phaseXs.length
+ : state.lane === 'terminal'
+ ? layout.outcomeXs.length
+ : layout.eventXs.length;
+ if (typeof state.col !== 'number' || state.col < 0 || state.col >= maxCol) {
problems.push(`State "${state.id}" uses invalid column ${state.col}.`);
}
- const top = laneTop(state.lane);
- const contentTop = top + layout.laneTitleH;
- if (state.x < layout.laneX || state.x + state.width > layout.laneX + layout.laneW) {
- problems.push(`State "${state.id}" exceeds the horizontal bounds of lane "${state.lane}".`);
+ if (state.x < 32 || state.x + state.width > viewBox[0] - 32) {
+ problems.push(`State "${state.id}" exceeds the horizontal bounds of the diagram.`);
}
- if (state.y < contentTop || state.y + state.height > top + layout.laneH) {
- problems.push(`State "${state.id}" collides with the title or boundary of lane "${state.lane}".`);
+ if (state.y < 64 || state.y + state.height > legendY() - 24) {
+ problems.push(`State "${state.id}" exceeds the vertical lifecycle area.`);
}
}
@@ -193,23 +195,17 @@ function defaultToSide(from, to) {
return 'bottom';
}
-function gapYBetween(fromLane, toLane, bias = 0.5) {
- const a = laneTop(fromLane) + layout.laneH;
- const b = laneTop(toLane);
- return a + (b - a) * bias;
-}
-
function routeVia(transition, from, to, start, end) {
if (transition.via) return transition.via;
switch (transition.route || 'auto') {
case 'straight':
return [];
case 'drop': {
- const y = gapYBetween(from.lane, to.lane, transition.bias || 0.5);
+ const y = transition.channelY || (start[1] + end[1]) / 2;
return [[start[0], y], [end[0], y]];
}
case 'raise': {
- const y = gapYBetween(to.lane, from.lane, transition.bias || 0.5);
+ const y = transition.channelY || (start[1] + end[1]) / 2;
return [[start[0], y], [end[0], y]];
}
case 'bottom-channel': {
@@ -231,7 +227,7 @@ function routeVia(transition, from, to, start, end) {
case 'auto':
default: {
if (from.lane === to.lane) return [];
- const y = gapYBetween(from.lane, to.lane, transition.bias || 0.5);
+ const y = transition.channelY || (start[1] + end[1]) / 2;
return [[start[0], y], [end[0], y]];
}
}
@@ -311,10 +307,13 @@ function renderDefinitions() {
</defs>`;
}
-function renderLane(lane, index) {
- const y = layout.laneY + index * (layout.laneH + layout.laneGap);
- return ` <path d="M ${layout.laneX} ${y + layout.laneTitleH} L ${layout.laneX + layout.laneW} ${y + layout.laneTitleH}" class="a-default" stroke-width="0.8" stroke-dasharray="3,8"/>
- <text x="${layout.laneX}" y="${y + 14}" class="t-dim" font-size="10" font-weight="600">${String(index + 1).padStart(2, '0')} / ${esc(lane.label)}</text>`;
+function renderBands() {
+ return ` <path d="M 72 112 L 908 112" class="a-default" stroke-width="0.8" stroke-dasharray="3,8"/>
+ <text x="72" y="100" class="t-dim" font-size="10" font-weight="600">01 / Lifecycle phases</text>
+ <path d="M 72 264 L 908 264" class="a-default" stroke-width="0.8" stroke-dasharray="3,8"/>
+ <text x="72" y="252" class="t-dim" font-size="10" font-weight="600">02 / Interruptions + recovery</text>
+ <path d="M 72 436 L 908 436" class="a-default" stroke-width="0.8" stroke-dasharray="3,8"/>
+ <text x="72" y="424" class="t-dim" font-size="10" font-weight="600">03 / Outcomes</text>`;
}
function renderState(state) {
@@ -323,8 +322,11 @@ function renderState(state) {
const tag = state.tag
? `\n <text x="${state.cx}" y="${state.y + state.height - 11}" class="${accent}" font-size="7" text-anchor="middle">${esc(state.tag)}</text>`
: '';
- return ` <rect x="${state.x}" y="${state.y}" width="${state.width}" height="${state.height}" rx="6" class="c-mask"/>
- <rect x="${state.x}" y="${state.y}" width="${state.width}" height="${state.height}" rx="6" class="${fill}" stroke-width="1.5"/>
+ const step = state.step
+ ? `\n <text x="${state.x + 10}" y="${state.y + 14}" class="${accent}" font-size="7" font-weight="700">${esc(state.step)}</text>`
+ : '';
+ return ` <rect x="${state.x}" y="${state.y}" width="${state.width}" height="${state.height}" rx="7" class="c-mask"/>
+ <rect x="${state.x}" y="${state.y}" width="${state.width}" height="${state.height}" rx="7" class="${fill}" stroke-width="1.5"/>${step}
<text x="${state.cx}" y="${state.y + 21}" class="t-primary" font-size="10" font-weight="600" text-anchor="middle">${esc(state.label)}</text>
<text x="${state.cx}" y="${state.y + 37}" class="t-muted" font-size="7" text-anchor="middle">${esc(state.sublabel || '')}</text>${tag}`;
}
@@ -342,7 +344,7 @@ function transitionAccent(transition) {
function renderTransitionPath(transition) {
const [cls, marker] = arrowClass[transition.variant || 'default'] || arrowClass.default;
const routed = pathFor(transition);
- const strokeWidth = transition.width || (transition.variant === 'emphasis' ? 1.8 : 1.2);
+ const strokeWidth = transition.width || (transition.variant === 'emphasis' ? 2 : 1.1);
return ` <path d="${routed.d}" class="${cls}" stroke-width="${strokeWidth}" marker-end="url(#${marker})"/>`;
}
@@ -370,9 +372,11 @@ function renderLegend() {
<rect x="415" y="${y - 8}" width="14" height="9" rx="2" class="c-database" stroke-width="1"/>
<text x="435" y="${y}" class="t-muted" font-size="7">terminal success</text>
<rect x="560" y="${y - 8}" width="14" height="9" rx="2" class="c-security" stroke-width="1"/>
- <text x="580" y="${y}" class="t-muted" font-size="7">failure / gate</text>
- <path d="M 690 ${y} L 724 ${y}" class="a-dashed" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
- <text x="733" y="${y + 3}" class="t-muted" font-size="7">retry / async</text>`;
+ <text x="580" y="${y}" class="t-muted" font-size="7">failure / exit</text>`;
+}
+
+function renderLifecycleRail() {
+ return ` <path d="M 154 ${layout.phaseY + 31} L 748 ${layout.phaseY + 31}" class="a-emphasis" stroke-width="2.2" marker-end="url(#arrowhead-emphasis)"/>`;
}
function renderSvg() {
@@ -382,8 +386,11 @@ ${renderDefinitions()}
<!-- Background Grid -->
<rect width="100%" height="100%" fill="url(#grid)" />
- <!-- Lifecycle lanes -->
-${lifecycle.lanes.map(renderLane).join('\n\n')}
+ <!-- Lifecycle bands -->
+${renderBands()}
+
+ <!-- Primary lifecycle rail -->
+${renderLifecycleRail()}
<!-- Transition paths -->
${(lifecycle.transitions || []).map(renderTransitionPath).join('\n')}
diff --git a/archify/schemas/lifecycle.schema.json b/archify/schemas/lifecycle.schema.json
index f280682a..ccc3448c 100644
--- a/archify/schemas/lifecycle.schema.json
+++ b/archify/schemas/lifecycle.schema.json
@@ -61,6 +61,7 @@
"label": { "type": "string", "minLength": 1 },
"sublabel": { "type": "string" },
"tag": { "type": "string" },
+ "step": { "type": "string" },
"lane": { "$ref": "#/$defs/id" },
"col": { "type": "integer", "minimum": 0 },
"width": { "type": "number", "minimum": 48 },
diff --git a/examples/images/archify-lifecycle.png b/examples/images/archify-lifecycle.png
index ba1f5b50..0234a105 100644
Binary files a/examples/images/archify-lifecycle.png and b/examples/images/archify-lifecycle.png differ
diff --git a/examples/lifecycle-agent-run.html b/examples/lifecycle-agent-run.html
index 914ad29a..395cb31b 100644
--- a/examples/lifecycle-agent-run.html
+++ b/examples/lifecycle-agent-run.html
@@ -448,7 +448,7 @@
<!-- Main Diagram -->
<div class="diagram-container">
- <svg viewBox="0 0 980 610">
+ <svg viewBox="0 0 980 660">
<!-- Definitions -->
<defs>
<marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
@@ -471,91 +471,89 @@
<!-- Background Grid -->
<rect width="100%" height="100%" fill="url(#grid)" />
- <!-- Lifecycle lanes -->
- <path d="M 32 64 L 946 64" class="a-default" stroke-width="0.8" stroke-dasharray="3,8"/>
- <text x="32" y="58" class="t-dim" font-size="10" font-weight="600">01 / Active lifecycle</text>
+ <!-- Lifecycle bands -->
+ <path d="M 72 112 L 908 112" class="a-default" stroke-width="0.8" stroke-dasharray="3,8"/>
+ <text x="72" y="100" class="t-dim" font-size="10" font-weight="600">01 / Lifecycle phases</text>
+ <path d="M 72 264 L 908 264" class="a-default" stroke-width="0.8" stroke-dasharray="3,8"/>
+ <text x="72" y="252" class="t-dim" font-size="10" font-weight="600">02 / Interruptions + recovery</text>
+ <path d="M 72 436 L 908 436" class="a-default" stroke-width="0.8" stroke-dasharray="3,8"/>
+ <text x="72" y="424" class="t-dim" font-size="10" font-weight="600">03 / Outcomes</text>
- <path d="M 32 184 L 946 184" class="a-default" stroke-width="0.8" stroke-dasharray="3,8"/>
- <text x="32" y="178" class="t-dim" font-size="10" font-weight="600">02 / Suspended states</text>
-
- <path d="M 32 304 L 946 304" class="a-default" stroke-width="0.8" stroke-dasharray="3,8"/>
- <text x="32" y="298" class="t-dim" font-size="10" font-weight="600">03 / Recovery loop</text>
-
- <path d="M 32 424 L 946 424" class="a-default" stroke-width="0.8" stroke-dasharray="3,8"/>
- <text x="32" y="418" class="t-dim" font-size="10" font-weight="600">04 / Terminal outcomes</text>
+ <!-- Primary lifecycle rail -->
+ <path d="M 154 157 L 748 157" class="a-emphasis" stroke-width="2.2" marker-end="url(#arrowhead-emphasis)"/>
<!-- Transition paths -->
- <path d="M 152 106 L 190 106" class="a-emphasis" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/>
- <path d="M 302 106 L 340 106" class="a-emphasis" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/>
- <path d="M 452 106 L 490 106" class="a-emphasis" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/>
- <path d="M 546 133 L 546 439" class="a-emphasis" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/>
- <path d="M 396 133 L 396 199" class="a-security" stroke-width="1.2" marker-end="url(#arrowhead-security)"/>
- <path d="M 602 106 L 602 146 Q 602 156 612 156 L 630 156 Q 640 156 640 166 L 640 226" class="a-default" stroke-width="1.2" marker-end="url(#arrowhead)"/>
- <path d="M 340 106 L 340 294 Q 340 304 330 304 L 253.5 304 Q 246 304 246 311.5 L 246 319" class="a-security" stroke-width="1.2" marker-end="url(#arrowhead-security)"/>
- <path d="M 246 319 L 246 133" class="a-dashed" stroke-width="1.2" marker-end="url(#arrowhead-dashed)"/>
- <path d="M 696 253 L 696 439" class="a-security" stroke-width="1.2" marker-end="url(#arrowhead-security)"/>
- <path d="M 396 253 L 396 439" class="a-security" stroke-width="1.2" marker-end="url(#arrowhead-security)"/>
+ <path d="M 402 188 L 402 278" class="a-security" stroke-width="1.1" marker-end="url(#arrowhead-security)"/>
+ <path d="M 556 188 L 556 233 L 556 233 L 556 278" class="a-default" stroke-width="1.1" marker-end="url(#arrowhead)"/>
+ <path d="M 343 157 L 340.1621408448257 332.00131456908264 Q 340 342 350 342 L 395 342 Q 402 342 402 349 L 402 356" class="a-security" stroke-width="1.1" marker-end="url(#arrowhead-security)"/>
+ <path d="M 556 336 L 556 450" class="a-security" stroke-width="1.1" marker-end="url(#arrowhead-security)"/>
+ <path d="M 402 336 L 402 450" class="a-security" stroke-width="1.1" marker-end="url(#arrowhead-security)"/>
<!-- States -->
- <rect x="40" y="79" width="112" height="54" rx="6" class="c-mask"/>
- <rect x="40" y="79" width="112" height="54" rx="6" class="c-frontend" stroke-width="1.5"/>
- <text x="96" y="100" class="t-primary" font-size="10" font-weight="600" text-anchor="middle">Queued</text>
- <text x="96" y="116" class="t-muted" font-size="7" text-anchor="middle">request accepted</text>
- <text x="96" y="122" class="t-frontend" font-size="7" text-anchor="middle">entry</text>
-
- <rect x="190" y="79" width="112" height="54" rx="6" class="c-mask"/>
- <rect x="190" y="79" width="112" height="54" rx="6" class="c-backend" stroke-width="1.5"/>
- <text x="246" y="100" class="t-primary" font-size="10" font-weight="600" text-anchor="middle">Planning</text>
- <text x="246" y="116" class="t-muted" font-size="7" text-anchor="middle">build task graph</text>
- <text x="246" y="122" class="t-backend" font-size="7" text-anchor="middle">model</text>
-
- <rect x="340" y="79" width="112" height="54" rx="6" class="c-mask"/>
- <rect x="340" y="79" width="112" height="54" rx="6" class="c-backend" stroke-width="1.5"/>
- <text x="396" y="100" class="t-primary" font-size="10" font-weight="600" text-anchor="middle">Executing</text>
- <text x="396" y="116" class="t-muted" font-size="7" text-anchor="middle">tool calls</text>
- <text x="396" y="122" class="t-backend" font-size="7" text-anchor="middle">work</text>
-
- <rect x="490" y="79" width="112" height="54" rx="6" class="c-mask"/>
- <rect x="490" y="79" width="112" height="54" rx="6" class="c-security" stroke-width="1.5"/>
- <text x="546" y="100" class="t-primary" font-size="10" font-weight="600" text-anchor="middle">Reviewing</text>
- <text x="546" y="116" class="t-muted" font-size="7" text-anchor="middle">quality gate</text>
- <text x="546" y="122" class="t-security" font-size="7" text-anchor="middle">check</text>
-
- <rect x="340" y="199" width="112" height="54" rx="6" class="c-mask"/>
- <rect x="340" y="199" width="112" height="54" rx="6" class="c-cloud" stroke-width="1.5"/>
- <text x="396" y="220" class="t-primary" font-size="10" font-weight="600" text-anchor="middle">Needs Approval</text>
- <text x="396" y="236" class="t-muted" font-size="7" text-anchor="middle">human gate</text>
- <text x="396" y="242" class="t-cloud" font-size="7" text-anchor="middle">pause</text>
-
- <rect x="640" y="199" width="112" height="54" rx="6" class="c-mask"/>
- <rect x="640" y="199" width="112" height="54" rx="6" class="c-cloud" stroke-width="1.5"/>
- <text x="696" y="220" class="t-primary" font-size="10" font-weight="600" text-anchor="middle">Blocked</text>
- <text x="696" y="236" class="t-muted" font-size="7" text-anchor="middle">missing input</text>
- <text x="696" y="242" class="t-cloud" font-size="7" text-anchor="middle">wait</text>
-
- <rect x="190" y="319" width="112" height="54" rx="6" class="c-mask"/>
- <rect x="190" y="319" width="112" height="54" rx="6" class="c-security" stroke-width="1.5"/>
- <text x="246" y="340" class="t-primary" font-size="10" font-weight="600" text-anchor="middle">Failed</text>
- <text x="246" y="356" class="t-muted" font-size="7" text-anchor="middle">recoverable error</text>
- <text x="246" y="362" class="t-security" font-size="7" text-anchor="middle">retryable</text>
-
- <rect x="340" y="439" width="112" height="54" rx="6" class="c-mask"/>
- <rect x="340" y="439" width="112" height="54" rx="6" class="c-security" stroke-width="1.5"/>
- <text x="396" y="460" class="t-primary" font-size="10" font-weight="600" text-anchor="middle">Cancelled</text>
- <text x="396" y="476" class="t-muted" font-size="7" text-anchor="middle">user stopped</text>
- <text x="396" y="482" class="t-security" font-size="7" text-anchor="middle">terminal</text>
-
- <rect x="490" y="439" width="112" height="54" rx="6" class="c-mask"/>
- <rect x="490" y="439" width="112" height="54" rx="6" class="c-database" stroke-width="1.5"/>
- <text x="546" y="460" class="t-primary" font-size="10" font-weight="600" text-anchor="middle">Completed</text>
- <text x="546" y="476" class="t-muted" font-size="7" text-anchor="middle">final response</text>
- <text x="546" y="482" class="t-database" font-size="7" text-anchor="middle">success</text>
-
- <rect x="640" y="439" width="112" height="54" rx="6" class="c-mask"/>
- <rect x="640" y="439" width="112" height="54" rx="6" class="c-security" stroke-width="1.5"/>
- <text x="696" y="460" class="t-primary" font-size="10" font-weight="600" text-anchor="middle">Expired</text>
- <text x="696" y="476" class="t-muted" font-size="7" text-anchor="middle">timeout</text>
- <text x="696" y="482" class="t-security" font-size="7" text-anchor="middle">terminal</text>
+ <rect x="35" y="126" width="118" height="62" rx="7" class="c-mask"/>
+ <rect x="35" y="126" width="118" height="62" rx="7" class="c-frontend" stroke-width="1.5"/>
+ <text x="45" y="140" class="t-frontend" font-size="7" font-weight="700">01</text>
+ <text x="94" y="147" class="t-primary" font-size="10" font-weight="600" text-anchor="middle">Queued</text>
+ <text x="94" y="163" class="t-muted" font-size="7" text-anchor="middle">request accepted</text>
+ <text x="94" y="177" class="t-frontend" font-size="7" text-anchor="middle">entry</text>
+
+ <rect x="189" y="126" width="118" height="62" rx="7" class="c-mask"/>
+ <rect x="189" y="126" width="118" height="62" rx="7" class="c-backend" stroke-width="1.5"/>
+ <text x="199" y="140" class="t-backend" font-size="7" font-weight="700">02</text>
+ <text x="248" y="147" class="t-primary" font-size="10" font-weight="600" text-anchor="middle">Planning</text>
+ <text x="248" y="163" class="t-muted" font-size="7" text-anchor="middle">build task graph</text>
+ <text x="248" y="177" class="t-backend" font-size="7" text-anchor="middle">model</text>
+
+ <rect x="343" y="126" width="118" height="62" rx="7" class="c-mask"/>
+ <rect x="343" y="126" width="118" height="62" rx="7" class="c-backend" stroke-width="1.5"/>
+ <text x="353" y="140" class="t-backend" font-size="7" font-weight="700">03</text>
+ <text x="402" y="147" class="t-primary" font-size="10" font-weight="600" text-anchor="middle">Executing</text>
+ <text x="402" y="163" class="t-muted" font-size="7" text-anchor="middle">tool calls</text>
+ <text x="402" y="177" class="t-backend" font-size="7" text-anchor="middle">work</text>
+
+ <rect x="497" y="126" width="118" height="62" rx="7" class="c-mask"/>
+ <rect x="497" y="126" width="118" height="62" rx="7" class="c-security" stroke-width="1.5"/>
+ <text x="507" y="140" class="t-security" font-size="7" font-weight="700">04</text>
+ <text x="556" y="147" class="t-primary" font-size="10" font-weight="600" text-anchor="middle">Reviewing</text>
+ <text x="556" y="163" class="t-muted" font-size="7" text-anchor="middle">quality gate</text>
+ <text x="556" y="177" class="t-security" font-size="7" text-anchor="middle">check</text>
+
+ <rect x="651" y="126" width="118" height="62" rx="7" class="c-mask"/>
+ <rect x="651" y="126" width="118" height="62" rx="7" class="c-database" stroke-width="1.5"/>
+ <text x="661" y="140" class="t-database" font-size="7" font-weight="700">05</text>
+ <text x="710" y="147" class="t-primary" font-size="10" font-weight="600" text-anchor="middle">Completed</text>
+ <text x="710" y="163" class="t-muted" font-size="7" text-anchor="middle">final response</text>
+ <text x="710" y="177" class="t-database" font-size="7" text-anchor="middle">done</text>
+
+ <rect x="339" y="278" width="126" height="58" rx="7" class="c-mask"/>
+ <rect x="339" y="278" width="126" height="58" rx="7" class="c-cloud" stroke-width="1.5"/>
+ <text x="402" y="299" class="t-primary" font-size="10" font-weight="600" text-anchor="middle">Needs Approval</text>
+ <text x="402" y="315" class="t-muted" font-size="7" text-anchor="middle">human gate</text>
+ <text x="402" y="325" class="t-cloud" font-size="7" text-anchor="middle">pause</text>
+
+ <rect x="493" y="278" width="126" height="58" rx="7" class="c-mask"/>
+ <rect x="493" y="278" width="126" height="58" rx="7" class="c-cloud" stroke-width="1.5"/>
+ <text x="556" y="299" class="t-primary" font-size="10" font-weight="600" text-anchor="middle">Blocked</text>
+ <text x="556" y="315" class="t-muted" font-size="7" text-anchor="middle">missing input</text>
+ <text x="556" y="325" class="t-cloud" font-size="7" text-anchor="middle">wait</text>
+
+ <rect x="339" y="356" width="126" height="58" rx="7" class="c-mask"/>
+ <rect x="339" y="356" width="126" height="58" rx="7" class="c-security" stroke-width="1.5"/>
+ <text x="402" y="377" class="t-primary" font-size="10" font-weight="600" text-anchor="middle">Failed</text>
+ <text x="402" y="393" class="t-muted" font-size="7" text-anchor="middle">recoverable error</text>
+ <text x="402" y="403" class="t-security" font-size="7" text-anchor="middle">retryable</text>
+
+ <rect x="343" y="450" width="118" height="58" rx="7" class="c-mask"/>
+ <rect x="343" y="450" width="118" height="58" rx="7" class="c-security" stroke-width="1.5"/>
+ <text x="402" y="471" class="t-primary" font-size="10" font-weight="600" text-anchor="middle">Cancelled</text>
+ <text x="402" y="487" class="t-muted" font-size="7" text-anchor="middle">user stopped</text>
+ <text x="402" y="497" class="t-security" font-size="7" text-anchor="middle">terminal</text>
+
+ <rect x="497" y="450" width="118" height="58" rx="7" class="c-mask"/>
+ <rect x="497" y="450" width="118" height="58" rx="7" class="c-security" stroke-width="1.5"/>
+ <text x="556" y="471" class="t-primary" font-size="10" font-weight="600" text-anchor="middle">Expired</text>
+ <text x="556" y="487" class="t-muted" font-size="7" text-anchor="middle">timeout</text>
+ <text x="556" y="497" class="t-security" font-size="7" text-anchor="middle">terminal</text>
<!-- Transition labels -->
@@ -564,23 +562,16 @@
-
-
-
-
-
<!-- Legend -->
- <text x="220" y="532" class="t-primary" font-size="10" font-weight="600">Legend</text>
- <rect x="220" y="544" width="14" height="9" rx="2" class="c-backend" stroke-width="1"/>
- <text x="240" y="552" class="t-muted" font-size="7">active state</text>
- <rect x="325" y="544" width="14" height="9" rx="2" class="c-cloud" stroke-width="1"/>
- <text x="345" y="552" class="t-muted" font-size="7">waiting</text>
- <rect x="415" y="544" width="14" height="9" rx="2" class="c-database" stroke-width="1"/>
- <text x="435" y="552" class="t-muted" font-size="7">terminal success</text>
- <rect x="560" y="544" width="14" height="9" rx="2" class="c-security" stroke-width="1"/>
- <text x="580" y="552" class="t-muted" font-size="7">failure / gate</text>
- <path d="M 690 552 L 724 552" class="a-dashed" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
- <text x="733" y="555" class="t-muted" font-size="7">retry / async</text>
+ <text x="220" y="542" class="t-primary" font-size="10" font-weight="600">Legend</text>
+ <rect x="220" y="554" width="14" height="9" rx="2" class="c-backend" stroke-width="1"/>
+ <text x="240" y="562" class="t-muted" font-size="7">active state</text>
+ <rect x="325" y="554" width="14" height="9" rx="2" class="c-cloud" stroke-width="1"/>
+ <text x="345" y="562" class="t-muted" font-size="7">waiting</text>
+ <rect x="415" y="554" width="14" height="9" rx="2" class="c-database" stroke-width="1"/>
+ <text x="435" y="562" class="t-muted" font-size="7">terminal success</text>
+ <rect x="560" y="554" width="14" height="9" rx="2" class="c-security" stroke-width="1"/>
+ <text x="580" y="562" class="t-muted" font-size="7">failure / exit</text>
</svg>
</div>
@@ -592,9 +583,9 @@
<h3>Main Path</h3>
</div>
<ul>
- <li>&bull; Queued, Planning, Executing, and Reviewing are active run states</li>
- <li>&bull; A clean run reads left to right before exiting to an outcome</li>
- <li>&bull; A successful review exits into the terminal outcome lane</li>
+ <li>&bull; The run has five ordered phases from queue to completion</li>
+ <li>&bull; The primary lifecycle is carried by one horizontal rail</li>
+ <li>&bull; Completion is a phase, not a detached side box</li>
</ul>
</div>
@@ -617,8 +608,8 @@
</div>
<ul>
<li>&bull; Failed loops back while retry budget remains</li>
- <li>&bull; Completed, Cancelled, and Expired are visually grouped as outcomes</li>
- <li>&bull; Terminal states do not point back into active execution</li>
+ <li>&bull; Cancelled and Expired are exits from the lifecycle</li>
+ <li>&bull; Terminal exits do not point back into active execution</li>
</ul>
</div>
</div>