Skip to content

armgit / cogit

Public Imported from GitHub
0

Git for the intent behind agent-written code. Records what your coding agent decided and why, and links every commit to it.

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.md
index 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 lowercase
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
@@ -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 new
or 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, you
never draw it):
diff --git a/packages/cli/src/shape.ts b/packages/cli/src/shape.ts
index 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.ts
index 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");