@coldtea/pr-lens-agent-skill 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +6 -6
  2. package/SKILL.md +9 -9
  3. package/package.json +5 -3
  4. package/references/config.md +4 -4
  5. package/references/graph-document.md +8 -8
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @coldtea/pr-lens-agent-skill
2
2
 
3
- The PR Lens skill for coding agents. It teaches an agent to draw the change it just made: author a graph document from the diff, validate it against the contract, render it, attach it to the pull request — and to fix a repository's map by writing corrections rather than editing generated output.
3
+ The PR Lens skill for coding agents. It teaches an agent to draw the change it just made: author a graph document from the diff, validate it against the contract, render it, attach it to the pull request, and to fix a repository's map by writing corrections rather than editing generated output.
4
4
 
5
5
  MIT © Ohans Emmanuel.
6
6
 
@@ -10,21 +10,21 @@ MIT © Ohans Emmanuel.
10
10
  npm install --save-dev @coldtea/pr-lens-agent-skill
11
11
  ```
12
12
 
13
- **Claude Code** — copy it where skills live, per project or per user:
13
+ **Claude Code**: copy it where skills live, per project or per user:
14
14
 
15
15
  ```bash
16
16
  mkdir -p .claude/skills/pr-lens
17
17
  cp -R node_modules/@coldtea/pr-lens-agent-skill/{SKILL.md,references} .claude/skills/pr-lens/
18
18
  ```
19
19
 
20
- **Cursor** — the same file works as a rule:
20
+ **Cursor**: the same file works as a rule:
21
21
 
22
22
  ```bash
23
23
  mkdir -p .cursor/rules
24
24
  cp node_modules/@coldtea/pr-lens-agent-skill/SKILL.md .cursor/rules/pr-lens.mdc
25
25
  ```
26
26
 
27
- **Anything else** — point your agent's instructions file at `SKILL.md`. It is plain markdown with YAML frontmatter, and it assumes nothing beyond a shell and `npx`.
27
+ **Anything else**: point your agent's instructions file at `SKILL.md`. It is plain markdown with YAML frontmatter, and it assumes nothing beyond a shell and `npx`.
28
28
 
29
29
  ## What is in it
30
30
 
@@ -34,7 +34,7 @@ cp node_modules/@coldtea/pr-lens-agent-skill/SKILL.md .cursor/rules/pr-lens.mdc
34
34
  | `references/graph-document.md` | the document, field by field, and what the validator will catch |
35
35
  | `references/config.md` | `.github/pr-lens.yml` corrections, with recipes |
36
36
 
37
- The agent is usually the model. Rather than spending a provider key to describe a diff it already understands, it writes the document itself and lets `pr-lens validate` hold it to the contract — every failure is a path into the document, so the loop closes without a human in it.
37
+ The agent is usually the model. Rather than spending a provider key to describe a diff it already understands, it writes the document itself and lets `pr-lens validate` hold it to the contract. Every failure is a path into the document, so the loop closes without a human in it.
38
38
 
39
39
  ## Why this exists
40
40
 
@@ -42,4 +42,4 @@ A coding agent that opens a pull request is asking a person to review code the p
42
42
 
43
43
  ---
44
44
 
45
- Part of [PR Lens](https://prlens.dev) — review what actually matters.
45
+ Part of [PR Lens](https://prlens.dev). Review what actually matters.
package/SKILL.md CHANGED
@@ -1,11 +1,11 @@
1
1
  ---
2
2
  name: pr-lens
3
- description: Draw a code change as an architecture or data-flow diagram with PR Lens — author a graph document from a diff, validate it, render it to SVG, and attach it to a pull request; or correct a repository's map in .github/pr-lens.yml. Use when asked to diagram, visualise or explain the shape of a change, when attaching a diagram to a pull request you opened, or when an existing PR Lens diagram names things wrongly.
3
+ description: Draw a code change as an architecture or data-flow diagram with PR Lens. Author a graph document from a diff, validate it, render it to SVG, and attach it to a pull request; or correct a repository's map in .github/pr-lens.yml. Use when asked to diagram, visualise or explain the shape of a change, when attaching a diagram to a pull request you opened, or when an existing PR Lens diagram names things wrongly.
4
4
  ---
5
5
 
6
6
  # PR Lens
7
7
 
8
- PR Lens turns a diff into one JSON document — lanes, nodes, edges, ordered flows — and renders it as an animated SVG that reads inside a GitHub pull request comment. The document is the whole contract: if it validates, it renders.
8
+ PR Lens turns a diff into one JSON document (lanes, nodes, edges, ordered flows) and renders it as an animated SVG that reads inside a GitHub pull request comment. The document is the whole contract: if it validates, it renders.
9
9
 
10
10
  You are usually the model. Rather than calling out to a provider, read the diff and write the document yourself, then let the tooling check it.
11
11
 
@@ -23,14 +23,14 @@ You are usually the model. Rather than calling out to a provider, read the diff
23
23
  ```bash
24
24
  npx @coldtea/pr-lens-cli render pr-lens/graph.json --out pr-lens/
25
25
  ```
26
- Commit the SVGs somewhere durable — an orphan branch, or a release asset — and reference them from the pull request body with a `<picture>` pair so the diagram reads in both GitHub themes. `pr-lens comment --graph … --manifest …` composes that markdown for you.
26
+ Commit the SVGs somewhere durable, an orphan branch or a release asset, and reference them from the pull request body with a `<picture>` pair so the diagram reads in both GitHub themes. `pr-lens comment --graph … --manifest …` composes that markdown for you.
27
27
 
28
28
  If the repository has a model key configured and you would rather not author the document yourself, `npx @coldtea/pr-lens-cli analyze --base <ref>` does steps 1 and 2 with the provider of your choice.
29
29
 
30
30
  ## What makes a document worth reading
31
31
 
32
32
  - **Include what did not change.** A diagram of only the changed nodes says nothing about blast radius. The unchanged neighbours a change touches are the context; mark them `delta: "unchanged"`.
33
- - **Lanes are the reader's mental model** — a runtime, a tier, a boundary — not the folder tree.
33
+ - **Lanes are the reader's mental model** (a runtime, a tier, a boundary), not the folder tree.
34
34
  - **One hero edge**, two at the outside: the connection the change is really about.
35
35
  - **Add a flow only when there is a sequence** worth animating. One good flow beats three thin ones.
36
36
  - **Attach file refs**: they become the permalinks a reviewer clicks.
@@ -43,7 +43,7 @@ Read `references/graph-document.md` before writing. The four failures that accou
43
43
  | Code | What you did |
44
44
  | --- | --- |
45
45
  | `BROKEN_REFERENCE` | an edge, a flow step or a view names an id you never declared |
46
- | `INVALID_DOCUMENT` | an invented field — the schemas are strict, unknown keys are rejected |
46
+ | `INVALID_DOCUMENT` | an invented field; the schemas are strict, unknown keys are rejected |
47
47
  | `DUPLICATE_ID` | two nodes, edges or views sharing an id |
48
48
  | `UNSUPPORTED_SCHEMA_VERSION` | `schemaVersion` is not the contract version installed |
49
49
 
@@ -51,7 +51,7 @@ Four rules cannot be expressed in JSON Schema and are checked only by the parser
51
51
 
52
52
  ## Fixing a map instead of writing one
53
53
 
54
- When someone says the diagram is wrong — a node is misnamed, a folder should not be on it, something sits in the wrong lane — do not edit the generated document. It is regenerated on every run. Write the correction into `.github/pr-lens.yml`, which is an overlay applied over fresh inference every time:
54
+ When someone says the diagram is wrong (a node is misnamed, a folder should not be on it, something sits in the wrong lane), do not edit the generated document. It is regenerated on every run. Write the correction into `.github/pr-lens.yml`, which is an overlay applied over fresh inference every time:
55
55
 
56
56
  ```yaml
57
57
  schemaVersion: 0.1.0
@@ -68,13 +68,13 @@ map:
68
68
 
69
69
  `references/config.md` has the full format and the recipes. Validate it the same way: `npx @coldtea/pr-lens-cli validate .github/pr-lens.yml`.
70
70
 
71
- A `match` beginning with `id:` addresses one node exactly; anything else is a path glob matched against a node's file paths — prefer the glob, because it keeps holding when the next run names the node differently. A lane pin may name a lane the document never declared: the band is created, and takes the id for its label, so give it one a reader would want to see.
71
+ A `match` beginning with `id:` addresses one node exactly; anything else is a path glob matched against a node's file paths. Prefer the glob, because it keeps holding when the next run names the node differently. A lane pin may name a lane the document never declared: the band is created, and takes the id for its label, so give it one a reader would want to see.
72
72
 
73
- `pr-lens render` says so when a correction matched nothing, which is how a config that has drifted — the file it named moved or was deleted — becomes visible instead of quietly doing nothing.
73
+ `pr-lens render` says so when a correction matched nothing, which is how a config that has drifted, because the file it named moved or was deleted, becomes visible instead of quietly doing nothing.
74
74
 
75
75
  ## Reference documents
76
76
 
77
- The contract ships worked examples. `postmark-refactor.graph.json` is the realistic one — three lanes, all four delta states, a hero edge, a seven-step flow, a nested drill-down tree — and `minimal.graph.json` is the smallest document that validates:
77
+ The contract ships worked examples. `postmark-refactor.graph.json` is the realistic one (three lanes, all four delta states, a hero edge, a seven-step flow, a nested drill-down tree), and `minimal.graph.json` is the smallest document that validates:
78
78
 
79
79
  ```bash
80
80
  ls node_modules/@coldtea/pr-lens-schema/examples/
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@coldtea/pr-lens-agent-skill",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "The PR Lens skill for coding agents: author a graph document from a diff, validate it, render it, and correct a repository's map.",
5
5
  "license": "MIT",
6
6
  "author": "Ohans Emmanuel",
@@ -30,13 +30,15 @@
30
30
  },
31
31
  "devDependencies": {
32
32
  "@types/node": "^20.19.0",
33
+ "tsx": "4.23.12",
33
34
  "typescript": "7.0.2",
34
35
  "vitest": "4.1.11",
35
36
  "yaml": "^2.8.1",
36
- "@coldtea/pr-lens-renderer": "^0.1.0",
37
- "@coldtea/pr-lens-schema": "^0.1.0"
37
+ "@coldtea/pr-lens-renderer": "^0.1.1",
38
+ "@coldtea/pr-lens-schema": "^0.1.1"
38
39
  },
39
40
  "scripts": {
41
+ "skill:sync": "tsx scripts/sync.ts",
40
42
  "test": "vitest run",
41
43
  "typecheck": "tsc -p tsconfig.json --noEmit"
42
44
  }
package/references/config.md CHANGED
@@ -1,4 +1,4 @@
1
- # Correcting the map — `.github/pr-lens.yml`
1
+ # Correcting the map: `.github/pr-lens.yml`
2
2
 
3
3
  The generated document is regenerated on every run, so editing it is pointless. Corrections live in `.github/pr-lens.yml`, an overlay applied over fresh inference every time. Inference never writes back into this file, which is why a correction keeps holding as the code moves.
4
4
 
@@ -29,7 +29,7 @@ Every field except `schemaVersion` is optional, and the file itself is optional.
29
29
 
30
30
  ## Selectors
31
31
 
32
- A `match` beginning with `id:` addresses exactly one node — `id:build-bulk-payload`. Anything else is a repository-relative path glob matched against the node's file paths.
32
+ A `match` beginning with `id:` addresses exactly one node, as in `id:build-bulk-payload`. Anything else is a repository-relative path glob matched against the node's file paths.
33
33
 
34
34
  **Prefer the glob.** Ids come from inference and may change when the code does; a path correction survives that. Reach for `id:` only when no path distinguishes the node, or when the node has no files at all (an external service, a queue).
35
35
 
@@ -42,7 +42,7 @@ A `match` beginning with `id:` addresses exactly one node — `id:build-bulk-pay
42
42
  | `lane` | moves matching nodes into a lane, **creating it** when the document declares no such id |
43
43
  | `group` | clusters matching nodes under a sub-group inside their lane |
44
44
 
45
- Up to 128 of each. They are about intent rather than structure: there is no way to add a node or draw an edge here, and the one thing a correction can bring into existence is a lane — a band a repository wants that inference did not find. It takes the id for its label, because the id is the only name this file carries, so write `lane: infrastructure` rather than `lane: l3`. If the map is wrong in a way corrections cannot express, the fix belongs in the analysis, not in this file.
45
+ Up to 128 of each. They are about intent rather than structure: there is no way to add a node or draw an edge here, and the one thing a correction can bring into existence is a lane, a band a repository wants that inference did not find. It takes the id for its label, because the id is the only name this file carries, so write `lane: infrastructure` rather than `lane: l3`. If the map is wrong in a way corrections cannot express, the fix belongs in the analysis, not in this file.
46
46
 
47
47
  ## Recipes
48
48
 
@@ -87,4 +87,4 @@ lenses: [architecture]
87
87
  npx @coldtea/pr-lens-cli validate .github/pr-lens.yml
88
88
  ```
89
89
 
90
- `pr-lens render` reports any correction that changed nothing about the document it drew — that is a config that has drifted out of date, usually because the file a selector named has moved or gone. It is not an error and nothing stops, but it is worth fixing: a correction that matches nothing is a correction nobody is getting.
90
+ `pr-lens render` reports any correction that changed nothing about the document it drew. That is a config that has drifted out of date, usually because the file a selector named has moved or gone. It is not an error and nothing stops, but it is worth fixing: a correction that matches nothing is a correction nobody is getting.
package/references/graph-document.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  The authoritative shape is `node_modules/@coldtea/pr-lens-schema/json-schema/graph-doc.schema.json`. This page is what that schema cannot tell you: which parts matter, and where documents actually go wrong.
4
4
 
5
- Every schema here is **strict** — an unknown key is a rejection, not a warning. A field with a default may be left out.
5
+ Every schema here is **strict**: an unknown key is a rejection, not a warning. A field with a default may be left out.
6
6
 
7
7
  ## The document
8
8
 
@@ -25,7 +25,7 @@ Every schema here is **strict** — an unknown key is a rejection, not a warning
25
25
 
26
26
  `lenses` declares what the document carries enough detail to draw: `architecture`, `data-flow`, or both. A document carrying flows must declare `data-flow`.
27
27
 
28
- `provenance` is where the document came from: the repository, the base and head commit shas (lowercase hex, 7–40 characters), optionally the pull request and the generator. When you produce a document through the CLI these are filled in from the repository — do not invent them.
28
+ `provenance` is where the document came from: the repository, the base and head commit shas (lowercase hex, 7-40 characters), optionally the pull request and the generator. When you produce a document through the CLI these are filled in from the repository, so do not invent them.
29
29
 
30
30
  ## Ids
31
31
 
@@ -45,7 +45,7 @@ Every node, edge, flow and flow step declares one: `added`, `modified`, `removed
45
45
  { "id": "functions", "label": "Cloud Functions", "subtitle": "Node 20", "order": 1 }
46
46
  ```
47
47
 
48
- `order` (0–64) places lanes left to right; ties fall back to array order. Give a lane a `delta` only when the lane itself is new or gone.
48
+ `order` (0-64) places lanes left to right; ties fall back to array order. Give a lane a `delta` only when the lane itself is new or gone.
49
49
 
50
50
  ## Nodes
51
51
 
@@ -68,7 +68,7 @@ Every node, edge, flow and flow step declares one: `added`, `modified`, `removed
68
68
 
69
69
  `kind` is one of `service app module function route job queue datastore cache external ui config test package other`. It drives the card's icon and shape and nothing else; when in doubt, `other` still renders.
70
70
 
71
- `group` clusters nodes inside a lane — a package, a folder that means something. `files` (up to 64) become diff permalinks. `badges` (up to 6) are extra chips; the delta badge is drawn for you, so do not restate it.
71
+ `group` clusters nodes inside a lane: a package, a folder that means something. `files` (up to 64) become diff permalinks. `badges` (up to 6) are extra chips; the delta badge is drawn for you, so do not restate it.
72
72
 
73
73
  ## Edges
74
74
 
@@ -87,7 +87,7 @@ Up to 512.
87
87
  }
88
88
  ```
89
89
 
90
- `kind` is one of `call http rpc event queue data dependency render other`. `emphasis` is `normal` (default), `hero` or `muted`. More than one or two heroes and the emphasis stops meaning anything. `from` and `to` must be node ids you declared — this is the single most common failure.
90
+ `kind` is one of `call http rpc event queue data dependency render other`. `emphasis` is `normal` (default), `hero` or `muted`. More than one or two heroes and the emphasis stops meaning anything. `from` and `to` must be node ids you declared. This is the single most common failure.
91
91
 
92
92
  ## Flows
93
93
 
@@ -108,7 +108,7 @@ Up to 16, for the data-flow lens.
108
108
  ```
109
109
 
110
110
  - 2 to 12 participants, ordered by array position; each names a node id.
111
- - 1 to 64 messages. **Step order is array order** — there is no step number field, so a document cannot disagree with its own animation.
111
+ - 1 to 64 messages. **Step order is array order**: there is no step number field, so a document cannot disagree with its own animation.
112
112
  - `kind` is `sync`, `async`, `return` or `self`. `self` requires `from === to`, and no other kind may have them equal.
113
113
  - Both endpoints must be participants of that flow, not merely nodes of the document.
114
114
  - `repeat` says a step happens more than once per run, e.g. 4 batched requests.
@@ -145,7 +145,7 @@ The drill-down tree in the comment: up to 32 at the root, nesting up to 32 child
145
145
  { "direction": "right", "laneOrder": ["api", "functions", "external"], "rank": { "send-broadcast-bulk": 2 } }
146
146
  ```
147
147
 
148
- Hints, not instructions — the renderer owns final placement so a diagram stays deterministic and a stale hint cannot break it. Absolute coordinates are not expressible. Omitting `layout` entirely is normal.
148
+ Hints, not instructions: the renderer owns final placement, so a diagram stays deterministic and a stale hint cannot break it. Absolute coordinates are not expressible. Omitting `layout` entirely is normal.
149
149
 
150
150
  ## File references
151
151
 
@@ -157,7 +157,7 @@ Repository-relative POSIX paths: no leading `/`, no drive letter, no backslash,
157
157
 
158
158
  ## Length limits
159
159
 
160
- Labels 120 characters, summaries 2000, chip values 32. They are display fields — a label that needs 120 characters is a label the diagram cannot draw.
160
+ Labels 120 characters, summaries 2000, chip values 32. They are display fields: a label that needs 120 characters is a label the diagram cannot draw.
161
161
 
162
162
  ## Then validate
163
163