Git for the intent behind agent-written code. Records what your coding agent decided and why, and links every commit to it.
JavaScript ai-codingclaudeclaude-codeclaude-code-pluginclicoding-agentsdeveloper-toolsgitllmtypescript
feat(shape): draw an ordered Flow as a sequence diagram
Eren1195cdc63cb1
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 64714db..87b3157 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -5,6 +5,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).## [Unreleased]+### Changed+- An ordered **Flow** is drawn as a sequence diagram with the kind symbols.++### Fixed+- A wide diagram in **Open** keeps its size and scrolls sideways instead of shrinking its text until it cannot be read.## [0.25.5] - 2026-10-31### Fixeddiff --git a/docs/guide/map.md b/docs/guide/map.mdindex b580210..4cdcd98 100644--- a/docs/guide/map.md+++ b/docs/guide/map.md@@ -89,7 +89,8 @@ A message that landed commits has three layers, in that order:- **Shape** — a small representation of what the change *does*, in up to three of these:- a **Flow** of the path through the code: each box is one kind of thing (a function, astore, a hook, an outside system) with its fixed symbol, and the arrows are the work- handed between them;+ handed between them. An ordered Flow — work handed between parts over time — is drawn+ as a sequence diagram, numbered arrow by arrow;- a **Before / After** table for a fix or any change you can see, and an **Interface**table for a command, flag, exported function, config key or schema field that changed;- an **Example**, one concrete run with real values (every new command gets one);diff --git a/packages/cli/skills/record/SKILL.md b/packages/cli/skills/record/SKILL.mdindex 1eccbcc..220d4af 100644--- a/packages/cli/skills/record/SKILL.md+++ b/packages/cli/skills/record/SKILL.md@@ -92,8 +92,9 @@ Tools (at most three, the ones that say the most; never two that tell the same t- `flow`: a path through code as JSON. Every node has a `kind` from the table below and a`label` in the project's own words; at most 12 nodes and 16 edges; ids are short lowercase- words (`a`, `hook`), unique, and every edge names two of them. Set `ordered: true` when the- edges are steps over time and work is handed between parts (the map numbers them 1, 2, 3…).+ words (`a`, `hook`), unique, and every edge names two of them. Set `ordered: true` when+ work is handed between parts over time (a hook → a job → a store, a client → a server): the+ map draws it as a sequence diagram, so keep the edges in time order.```json{"kind": "flow", "text": "{\"nodes\":[{\"id\":\"a\",\"kind\":\"event\",\"label\":\"after a commit\"}],\"edges\":[{\"from\":\"a\",\"to\":\"b\",\"label\":\"no\"}],\"ordered\":false}"}diff --git a/packages/cli/src/shape.ts b/packages/cli/src/shape.tsindex 32d42f3..1d5652f 100644--- a/packages/cli/src/shape.ts+++ b/packages/cli/src/shape.ts@@ -89,8 +89,9 @@ export const SHAPE_TOOLS: readonly ShapeToolSpec[] = ["The change is a path through code across files: the functions, files, stores, hooks and " +"outside calls it moves between. Every node gets a kind from the list below and a label " +"in the project's own words; the map draws the symbol, never you. Set `ordered` true " +- "when the edges are steps over time and work is handed between parts. Node ids are short " +- `lowercase words; at most ${FLOW_MAX_NODES} nodes and ${FLOW_MAX_EDGES} edges.`,+ "when work is handed between parts over time (a hook → a job → a store, a client → a " ++ "server): the map draws it as a sequence diagram, so keep the edges in time order. " ++ `Node ids are short lowercase words; at most ${FLOW_MAX_NODES} nodes and ${FLOW_MAX_EDGES} edges.`,output:'{"kind": "flow", "text": "{\\"nodes\\":[{\\"id\\":\\"a\\",\\"kind\\":\\"event\\",\\"label\\":\\"after a commit\\"}],\\"edges\\":[{\\"from\\":\\"a\\",\\"to\\":\\"b\\",\\"label\\":\\"no\\"}],\\"ordered\\":false}"}',validate(text) {@@ -351,7 +352,7 @@ export function shapePrompt(opts: {"","Rules:","- Give at most three tools, the ones that say the most about this change; never two that tell the same thing.",- "- A Flow for a change across two or more files: every node gets a kind from the list above and a label in the project's own words. Set `ordered` true when the edges are steps over time and work is handed between parts.",+ "- A Flow for a change across two or more files: every node gets a kind from the list above and a label in the project's own words. Set `ordered` true when work is handed between parts over time (a hook → a job → a store, a client → a server): the map draws it as a sequence diagram, so keep the edges in time order and give every edge a label saying what is handed over or done.","- A Before / After table when behaviour someone can see changes (a fix, a new default, a rule).","- A change nobody would notice from outside (a refactor, a rename, moved code, a wording tweak in a prompt or comment) takes no tool at all: return none.","- An Interface table only for what is reached from outside the changed module: a CLI command or flag, an exported function or type other packages use, a config key, a stored schema field, an HTTP route. Never an internal helper, a component prop or a view-model field.",diff --git a/packages/cli/src/view/shape.ts b/packages/cli/src/view/shape.tsindex dbbfad0..60f56d6 100644--- a/packages/cli/src/view/shape.ts+++ b/packages/cli/src/view/shape.ts@@ -197,25 +197,47 @@ function flowLabel(text: string): string {}/**- * The deterministic `flowchart TD` a Flow draws (Story 13.7): one node per box- * with its kind's symbol and shape, one edge per arrow; `ordered` numbers the- * edge labels 1, 2, 3… in the order given. Undefined for input the rules- * refuse. The same input is always byte-identical.+ * A sequence participant's name or a message's text: the flowchart label rules+ * plus no newlines; a `:` inside a participant's name reads ` -` so it cannot+ * break the `participant … as …` line.+ */+function sequenceText(text: string, actor: boolean): string {+ const base = flowLabel(text).replace(/[\r\n]+/g, "");+ return actor ? base.replace(/:/g, " -") : base;+}++/**+ * The deterministic Mermaid a Flow draws (Story 13.7): an ordered Flow is a+ * `sequenceDiagram` — one `participant` column per node and one numbered arrow+ * per edge, top to bottom — and an unordered one is a `flowchart TD`, one box+ * per node with its kind's symbol and shape, one edge per arrow. Undefined for+ * input the rules refuse. The same input is always byte-identical.*/export function flowToMermaid(text: string): string | undefined {const flow = parseFlow(text);if (flow === undefined) return undefined;const symbol = (kind: string) => UNIVERSAL_KINDS.find((entry) => entry.id === kind)?.symbol ?? "";+ if (flow.ordered) {+ const lines = ["sequenceDiagram"];+ for (const node of flow.nodes)+ lines.push(+ ` participant ${node.id} as ${symbol(node.kind)} ${sequenceText(node.label, true)}`,+ );+ flow.edges.forEach((edge, index) => {+ const label =+ edge.label !== undefined && edge.label !== "" ? ` ${sequenceText(edge.label, false)}` : "";+ lines.push(` ${edge.from}->>${edge.to}: ${index + 1}.${label}`);+ });+ return lines.join("\n");+ }const lines = ["flowchart TD"];for (const node of flow.nodes) {const [open, close] = FLOW_NODE_SHAPE[node.kind] ?? ["[", "]"];lines.push(` ${node.id}${open}"${symbol(node.kind)} ${flowLabel(node.label)}"${close}`);}- flow.edges.forEach((edge, index) => {- // Ordered edges keep their words after the step number: "2. puts it in the queue".- const label = flow.ordered ? `${index + 1}. ${edge.label ?? ""}`.trim() : edge.label;- if (label !== undefined && label !== "")- lines.push(` ${edge.from} -->|"${flowLabel(label)}"| ${edge.to}`);+ flow.edges.forEach((edge) => {+ if (edge.label !== undefined && edge.label !== "")+ lines.push(` ${edge.from} -->|"${flowLabel(edge.label)}"| ${edge.to}`);else lines.push(` ${edge.from} --> ${edge.to}`);});return lines.join("\n");diff --git a/packages/cli/test/shape.test.ts b/packages/cli/test/shape.test.tsindex 285fe13..da9d80a 100644--- a/packages/cli/test/shape.test.ts+++ b/packages/cli/test/shape.test.ts@@ -163,6 +163,7 @@ describe("the Shape tool catalogue", () => {expect(prompt).toContain("A Before / After table when behaviour someone can see changes");expect(prompt).toContain("A new or changed command or flag always gets an example");expect(prompt).toContain("Never an internal helper");+ expect(prompt).toContain("give every edge a label");expect(prompt).toContain("takes no tool at all");expect(prompt).toContain("never an invented one");expect(prompt).toContain("fn (ƒ Function): a function or method");@@ -174,7 +175,7 @@ describe("the Shape tool catalogue", () => {expect(prompt).toContain('"example" (Example)');// The retired Mermaid tools are no longer offered to the writer.expect(prompt).not.toContain("mermaid");- expect(prompt).not.toContain("sequence");+ expect(prompt).not.toContain('"sequence"');});it("names the offered tools and says when to use each", () => {@@ -269,27 +270,27 @@ describe("the Flow tool", () => {);});- it("numbers the edge labels when ordered, and refuses invalid input", () => {+ it("draws an ordered Flow as a sequence diagram, and refuses invalid input", () => {const ordered = JSON.stringify({nodes: [{ id: "a", kind: "event", label: "after a commit" },{ id: "b", kind: "fn", label: "enqueue" },- { id: "c", kind: "store", label: "queue" },+ { id: "c", kind: "store", label: "queue: pending" },],edges: [{ from: "a", to: "b" },- { from: "b", to: "c", label: "puts it in" },+ { from: "b", to: "c", label: "puts; it in: the queue" },],ordered: true,});expect(flowToMermaid(ordered)).toBe([- "flowchart TD",- ' a>"⚡ after a commit"]',- ' b["ƒ enqueue"]',- ' c[("▤ queue")]',- ' a -->|"1."| b',- ' b -->|"2. puts it in"| c',+ "sequenceDiagram",+ " participant a as ⚡ after a commit",+ " participant b as ƒ enqueue",+ " participant c as ▤ queue - pending",+ " a->>b: 1.",+ " b->>c: 2. puts it in: the queue",].join("\n"),);expect(flowToMermaid("not json")).toBeUndefined();diff --git a/packages/template/src/MermaidDiagram.tsx b/packages/template/src/MermaidDiagram.tsxindex ba92d85..83a9971 100644--- a/packages/template/src/MermaidDiagram.tsx+++ b/packages/template/src/MermaidDiagram.tsx@@ -57,7 +57,27 @@ function loadMermaid(): Promise<Mermaid> {let seq = 0;-export function MermaidDiagram({ source, className }: { source: string; className?: string }) {+/**+ * Gives a drawn diagram its own width: Mermaid writes `width="100%"`, which+ * shrinks a wide diagram's text to fit; the Open window scrolls it instead.+ */+export function naturalSize(svg: SVGSVGElement): void {+ const width = svg.style.maxWidth;+ if (width === "") return;+ svg.style.width = width;+ svg.style.maxWidth = "none";+}++export function MermaidDiagram({+ source,+ className,+ fit = false,+}: {+ source: string;+ className?: string;+ /** Shrink to the box (the panel's preview) instead of keeping the drawn size. */+ fit?: boolean;+}) {const host = useRef<HTMLDivElement>(null);const available = mermaidAvailable();const [failed, setFailed] = useState(false);@@ -70,7 +90,10 @@ export function MermaidDiagram({ source, className }: { source: string; classNamloadMermaid().then((mermaid) => mermaid.render(id, source)).then(({ svg }) => {- if (!cancelled && host.current !== null) host.current.innerHTML = svg;+ if (cancelled || host.current === null) return;+ host.current.innerHTML = svg;+ const drawn = host.current.querySelector("svg");+ if (!fit && drawn !== null) naturalSize(drawn);}).catch(() => {if (!cancelled) setFailed(true);@@ -78,7 +101,7 @@ export function MermaidDiagram({ source, className }: { source: string; classNamreturn () => {cancelled = true;};- }, [source, available]);+ }, [source, available, fit]);const extra = className ? ` ${className}` : "";if (!available)diff --git a/packages/template/src/ShapeModal.tsx b/packages/template/src/ShapeModal.tsxindex 68e99f8..4e896e7 100644--- a/packages/template/src/ShapeModal.tsx+++ b/packages/template/src/ShapeModal.tsx@@ -2,6 +2,7 @@ import { type ReactNode, useEffect, useRef, useState } from "react";import type { ViewNode } from "../../cli/src/view/model.js";import {flowToMermaid,+ parseFlow,SHAPE_READING,shapeKindsUsed,shapePreview,@@ -124,17 +125,28 @@ const KINDS_CAPTIONS = new Set(["flow", "pseudo"]);/*** A tool's caption with a "?" that says how to read it; a Flow or Steps also- * lists every kind, so the symbols name themselves.+ * lists every kind, so the symbols name themselves. `reading` swaps in another+ * tool's explanation (an ordered Flow reads like a Sequence).*/-function ToolCaption({ id, kind, label }: { id: string; kind: string; label: string }) {- const reading = SHAPE_READING[kind];+function ToolCaption({+ id,+ kind,+ label,+ reading = kind,+}: {+ id: string;+ kind: string;+ label: string;+ reading?: string;+}) {+ const help = SHAPE_READING[reading];const listsKinds = KINDS_CAPTIONS.has(kind);return (<figcaption className="shape-caption"><span>{label}</span>- {reading ? (+ {help ? (<HelpTip id={`shape-${id}`} label={`How to read the ${label}`}>- <span className="shape-reading">{reading}</span>+ <span className="shape-reading">{help}</span>{listsKinds ? (<span className="shape-kinds">{UNIVERSAL_KINDS.map((kind) => (@@ -235,11 +247,17 @@ function ShapeLayer({{tools.map((tool, index) => {const key = `${tool.kind}-${index}`;const source = tool.kind === "flow" ? flowToMermaid(tool.text) : tool.text;+ const orderedFlow = tool.kind === "flow" && parseFlow(tool.text)?.ordered === true;if (DIAGRAM_KINDS.has(tool.kind) && tool.valid !== false && source !== undefined)return (<figure key={key} className="shape-figure">{renderMermaid(source)}- <ToolCaption id={key} kind={tool.kind} label={diagramLabel(tool.kind)} />+ <ToolCaption+ id={key}+ kind={tool.kind}+ label={orderedFlow ? "Sequence" : diagramLabel(tool.kind)}+ reading={orderedFlow ? "sequence" : tool.kind}+ /></figure>);const columns = TABLE_COLUMNS[tool.kind];@@ -431,7 +449,7 @@ export function ShapeSection({preview ? (<pre className="shape-preview">{preview}</pre>) : diagramSource !== undefined ? (- <MermaidDiagram source={diagramSource} className="shape-preview-diagram" />+ <MermaidDiagram source={diagramSource} className="shape-preview-diagram" fit />) : null) : state === "off" ? (<p className="muted">Shapes are off.</p>diff --git a/packages/template/test/shape-modal.test.tsx b/packages/template/test/shape-modal.test.tsxindex 280e4ef..50d1a0a 100644--- a/packages/template/test/shape-modal.test.tsx+++ b/packages/template/test/shape-modal.test.tsx@@ -113,6 +113,42 @@ describe("Intent, Shape and Code", () => {expect(html).not.toContain("Function");});+ it("captions an ordered Flow as a Sequence and an unordered one as a Flow", () => {+ const ordered = JSON.stringify({+ nodes: [+ { id: "a", kind: "event", label: "after a commit" },+ { id: "b", kind: "store", label: "queue" },+ ],+ edges: [{ from: "a", to: "b", label: "enqueue" }],+ ordered: true,+ });+ const sequence = render("shape", {+ shape: {+ tools: [{ kind: "flow", text: ordered, valid: true }],+ commits: [],+ },+ });+ expect(sequence).toContain("<span>Sequence</span>");+ expect(sequence).toContain('aria-label="How to read the Sequence"');++ const unordered = JSON.stringify({+ nodes: [+ { id: "a", kind: "event", label: "after a commit" },+ { id: "b", kind: "store", label: "queue" },+ ],+ edges: [{ from: "a", to: "b", label: "enqueue" }],+ ordered: false,+ });+ const flow = render("shape", {+ shape: {+ tools: [{ kind: "flow", text: unordered, valid: true }],+ commits: [],+ },+ });+ expect(flow).toContain("<span>Flow</span>");+ expect(flow).toContain('aria-label="How to read the Flow"');+ });+it("lays out a Before / After table and shows an unknown tool as text", () => {const html = render("shape", {shape: {