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(record): a Flow whenever data crosses files or layers
Erenddbe702bf52c
diff --git a/packages/cli/skills/record/SKILL.md b/packages/cli/skills/record/SKILL.mdindex 60ba9d7..51e877e 100644--- a/packages/cli/skills/record/SKILL.md+++ b/packages/cli/skills/record/SKILL.md@@ -93,7 +93,9 @@ message's node, with the node's commit hashes:Tools (at most three, the ones that say the most; never two that tell the same thing):-- `flow`: a path through code as JSON. Every node has a `kind` from the table below and a+- `flow`: a path through code as JSON. Take it whenever data or control crosses more than one+ file or layer, even when the change also reads like a list of steps — it is what the map+ draws best. 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 lowercasewords (`a`, `hook`), unique, and every edge names two of them. Set `ordered: true` whenwork is handed between parts over time (a hook → a job → a store, a client → a server): the@@ -110,8 +112,9 @@ Tools (at most three, the ones that say the most; never two that tell the same t`—` for nothing.- `example`: one concrete case with real values, each result on its own line after `→`. A newor changed command or flag always gets one that runs it.-- `pseudo`: numbered plain-language steps of the new logic, each starting with the symbol of- its kind after its number (`1. ⚡ After a commit, …`), naming the functions and files.+- `pseudo`: numbered plain-language steps for logic that stays inside one function or module,+ with no path across files to draw; each starts with the symbol of its kind after its number+ (`1. ⚡ After a commit, …`), naming the functions and files.Kinds (one per Flow node, and the symbol a step starts with; the map draws the symbol, younever draw it):diff --git a/packages/cli/src/shape.ts b/packages/cli/src/shape.tsindex b91db81..09eecf8 100644--- a/packages/cli/src/shape.ts+++ b/packages/cli/src/shape.ts@@ -87,7 +87,8 @@ export const SHAPE_TOOLS: readonly ShapeToolSpec[] = [name: "Flow",when:"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 " ++ "outside calls it moves between. Prefer it whenever data or control crosses more than one " ++ "file or layer, even when the change also reads like a list. 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 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. " +@@ -102,8 +103,9 @@ export const SHAPE_TOOLS: readonly ShapeToolSpec[] = [kind: "pseudo",name: "Steps",when:- "The change is mostly logic: a new path through functions, a rule, a check. " +- "Numbered plain-language steps, naming the functions and files they touch.",+ "The change is logic that stays inside one function or module (a rule, a check, a " ++ "rewrite) with no path across files to draw. Numbered plain-language steps, naming the " ++ "functions and files they touch.",output: '{"kind": "pseudo", "text": "1. ...\\n2. ..."}',validate(text) {const lines = text@@ -352,12 +354,12 @@ 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 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 Flow whenever data or control crosses more than one file or layer — a request path, a hook into a store, a queue drained later — even when the change also reads like a list of steps: it is what the map draws best. 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.","- A new or changed command or flag always gets an example that runs it and shows what it prints, with real values from the diff; a file path in it must be one the diff touches, never an invented one. Otherwise an example only when one concrete case shows the change faster than steps.",- "- Steps only when the logic itself is the point and no other tool says it; each step starts with the symbol of its kind after its number, e.g. `1. ⚡ After a commit, …`.",+ "- Steps only for logic that stays inside one function or module (a rule, a check, a rewrite) with no path across files to draw; each step starts with the symbol of its kind after its number, e.g. `1. ⚡ After a commit, …`.","- Tables have no header row (the map adds one); every line is one row of three cells split by |.","- Order the tools: diagram, tables, example, steps. Return none when the change is a small fix not worth a picture.",`- Name real functions, files and modules from the diff. Never invent a path.`,@@ -373,7 +375,7 @@ export function shapePrompt(opts: {`Diff${opts.diffTruncated ? " (cut to fit; the commits above are complete)" : ""}:`,opts.diff,"",- 'Return only one JSON object, no code fences: {"tools": [{"kind": "pseudo", "text": "1. ...\\n2. ..."}]}. A change across two or more files always includes a Flow; return {"tools": []} only for a change that is not worth showing.',+ 'Return only one JSON object, no code fences: {"tools": [{"kind": "pseudo", "text": "1. ...\\n2. ..."}]}. A change across two or more files or layers always includes a Flow; return {"tools": []} only for a change that is not worth showing.',].join("\n");}diff --git a/packages/cli/test/shape.test.ts b/packages/cli/test/shape.test.tsindex a336a6b..66591ff 100644--- a/packages/cli/test/shape.test.ts+++ b/packages/cli/test/shape.test.ts@@ -159,9 +159,11 @@ describe("the Shape tool catalogue", () => {diffTruncated: false,language: "auto",});- expect(prompt).toContain("A Flow for a change across two or more files");+ expect(prompt).toContain("A Flow whenever data or control crosses more than one file or layer");// The last line the writer reads says it again, since a small model forgets.- expect(prompt).toContain("A change across two or more files always includes a Flow");+ expect(prompt).toContain("A change across two or more files or layers always includes a Flow");+ // Steps stay for what cannot be drawn: logic inside one function.+ expect(prompt).toContain("Steps only for logic that stays inside one function or module");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");