@igorlau/dotagents 1.0.20 → 1.0.22

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 (108) hide show
  1. package/README.md +66 -66
  2. package/THIRD_PARTY_NOTICES.md +101 -6
  3. package/dist/build-info.json +1 -1
  4. package/dist/catalog.js +3 -3
  5. package/dist/cli.js +1 -1
  6. package/dist/commands.js +52 -15
  7. package/dist/manifest.js +8 -1
  8. package/dist/paths.js +0 -4
  9. package/dist/targets.js +3 -9
  10. package/dist/wizard.js +1 -1
  11. package/package.json +5 -3
  12. package/{plugin/rules → rules}/comments.upstream.json +1 -1
  13. package/{plugin/rules → rules}/ponytail.md +1 -1
  14. package/{plugin/rules → rules}/ponytail.upstream.json +1 -1
  15. package/{plugin/rules → rules}/writing.md +5 -2
  16. package/{plugin/rules → rules}/writing.upstream.json +1 -1
  17. package/{plugin/scaffold → scaffold}/AGENTS.md.tmpl +1 -1
  18. package/{plugin/skills → skills}/dot-code-review/SKILL.md +2 -0
  19. package/{plugin/skills → skills}/dot-code-review/UPSTREAM.json +1 -1
  20. package/skills/dot-code-review/references/finding-classes.md +33 -0
  21. package/{plugin/skills → skills}/dot-code-review/references/maintainability.md +1 -0
  22. package/{plugin/skills → skills}/dot-comments/UPSTREAM.json +1 -1
  23. package/{plugin/skills → skills}/dot-commit/SKILL.md +0 -2
  24. package/skills/dot-correct/UPSTREAM.json +8 -0
  25. package/{plugin/skills → skills}/dot-debug/UPSTREAM.json +1 -1
  26. package/{plugin/skills → skills}/dot-grilling/UPSTREAM.json +2 -2
  27. package/{plugin/skills → skills}/dot-handoff/UPSTREAM.json +1 -1
  28. package/{plugin/skills → skills}/dot-implement/SKILL.md +2 -2
  29. package/{plugin/skills → skills}/dot-implement/references/typescript.md +2 -1
  30. package/{plugin/skills → skills}/dot-plan/SKILL.md +3 -1
  31. package/{plugin/skills → skills}/dot-roadmap/SKILL.md +7 -4
  32. package/skills/dot-security-audit/SKILL.md +87 -0
  33. package/skills/dot-security-audit/UPSTREAM.json +8 -0
  34. package/skills/dot-security-audit/references/AI-AND-LLM.md +83 -0
  35. package/skills/dot-security-audit/references/ATTACK-CLASSES.md +130 -0
  36. package/skills/dot-security-audit/references/CLIENT-SIDE.md +83 -0
  37. package/skills/dot-security-audit/references/CLOUD-AND-DEPLOYMENT.md +86 -0
  38. package/skills/dot-security-audit/references/DATA-ISOLATION-AND-LIFECYCLE.md +84 -0
  39. package/skills/dot-security-audit/references/DESKTOP-MOBILE-AND-LOCAL-IPC.md +89 -0
  40. package/skills/dot-security-audit/references/MEMORY-SAFETY-AND-BINARY.md +101 -0
  41. package/skills/dot-security-audit/references/PROTOCOLS-RPC-AND-MESSAGING.md +81 -0
  42. package/skills/dot-security-audit/references/RESOURCE-EXHAUSTION-AND-AVAILABILITY.md +78 -0
  43. package/skills/dot-security-audit/references/SUPPLY-CHAIN-AND-RELEASE.md +73 -0
  44. package/skills/dot-security-audit/references/WEB-PROTOCOL-AND-AUTH.md +105 -0
  45. package/skills/dot-security-changes/SKILL.md +68 -0
  46. package/{plugin/skills → skills}/dot-testing/UPSTREAM.json +1 -1
  47. package/skills/dot-ui-review/SKILL.md +79 -0
  48. package/skills/dot-ui-review/UPSTREAM.json +8 -0
  49. package/skills/dot-ux-review/SKILL.md +50 -0
  50. package/skills/dot-ux-review/UPSTREAM.json +8 -0
  51. package/skills/dot-ux-review/references/web-interface-guidelines.md +191 -0
  52. package/{plugin/skills/dot-stack-review → skills/dot-walkthrough-branch}/SKILL.md +9 -30
  53. package/skills/dot-walkthrough-branch/references/layers.md +38 -0
  54. package/{plugin/skills/dot-stack-review → skills/dot-walkthrough-branch}/scripts/page.mjs +39 -10
  55. package/skills/dot-walkthrough-changes/SKILL.md +62 -0
  56. package/skills/dot-writing-for-agents/UPSTREAM.json +8 -0
  57. package/plugin/.claude-plugin/plugin.json +0 -10
  58. package/plugin/agents/dot-implementer.md +0 -27
  59. package/plugin/agents/dot-reviewer.md +0 -44
  60. package/plugin/agents/dot-tester.md +0 -25
  61. package/plugin/hooks/check.mjs +0 -118
  62. package/plugin/hooks/hooks.json +0 -54
  63. package/plugin/hooks/rules.mjs +0 -27
  64. package/plugin/skills/dot-correct/UPSTREAM.json +0 -8
  65. package/plugin/skills/dot-correct/agents/openai.yaml +0 -5
  66. package/plugin/skills/dot-debug/agents/openai.yaml +0 -3
  67. package/plugin/skills/dot-flow/SKILL.md +0 -105
  68. package/plugin/skills/dot-flow/agents/openai.yaml +0 -5
  69. package/plugin/skills/dot-flow/references/fix-round.md +0 -64
  70. package/plugin/skills/dot-flow/references/inline.md +0 -9
  71. package/plugin/skills/dot-grilling/agents/openai.yaml +0 -3
  72. package/plugin/skills/dot-handoff/agents/openai.yaml +0 -5
  73. package/plugin/skills/dot-roadmap/agents/openai.yaml +0 -5
  74. package/plugin/skills/dot-stack-review/agents/openai.yaml +0 -5
  75. package/plugin/skills/dot-writing-for-agents/UPSTREAM.json +0 -8
  76. package/plugin/skills/dot-writing-for-agents/agents/openai.yaml +0 -3
  77. /package/{plugin/rules → rules}/code-style.md +0 -0
  78. /package/{plugin/rules → rules}/comments.md +0 -0
  79. /package/{plugin/rules → rules}/core.md +0 -0
  80. /package/{plugin/scaffold → scaffold}/.claude/settings.json.tmpl +0 -0
  81. /package/{plugin/scaffold → scaffold}/.editorconfig.tmpl +0 -0
  82. /package/{plugin/scaffold → scaffold}/.gitattributes.tmpl +0 -0
  83. /package/{plugin/scaffold → scaffold}/CLAUDE.md.tmpl +0 -0
  84. /package/{plugin/skills → skills}/dot-comments/SKILL.md +0 -0
  85. /package/{plugin/skills → skills}/dot-correct/SKILL.md +0 -0
  86. /package/{plugin/skills → skills}/dot-debug/SKILL.md +0 -0
  87. /package/{plugin/skills → skills}/dot-debug/references/loops.md +0 -0
  88. /package/{plugin/skills → skills}/dot-debug/scripts/hitl-loop.template.sh +0 -0
  89. /package/{plugin/skills → skills}/dot-docs-writing/SKILL.md +0 -0
  90. /package/{plugin/skills → skills}/dot-docs-writing/references/formatting.md +0 -0
  91. /package/{plugin/skills → skills}/dot-docs-writing/references/global-and-accessible.md +0 -0
  92. /package/{plugin/skills → skills}/dot-docs-writing/references/word-list.md +0 -0
  93. /package/{plugin/skills → skills}/dot-grilling/SKILL.md +0 -0
  94. /package/{plugin/skills → skills}/dot-handoff/SKILL.md +0 -0
  95. /package/{plugin/skills → skills}/dot-implement/UPSTREAM.json +0 -0
  96. /package/{plugin/skills → skills}/dot-plan/UPSTREAM.json +0 -0
  97. /package/{plugin/skills → skills}/dot-plan/references/entity-schemas.md +0 -0
  98. /package/{plugin/skills → skills}/dot-roadmap/UPSTREAM.json +0 -0
  99. /package/{plugin/skills → skills}/dot-roadmap/references/wide-refactor.md +0 -0
  100. /package/{plugin/skills → skills}/dot-testing/SKILL.md +0 -0
  101. /package/{plugin/skills → skills}/dot-testing/references/after-implement.md +0 -0
  102. /package/{plugin/skills → skills}/dot-testing/references/http.md +0 -0
  103. /package/{plugin/skills → skills}/dot-testing/references/shared-state.md +0 -0
  104. /package/{plugin/skills → skills}/dot-testing/references/typescript.md +0 -0
  105. /package/{plugin/skills → skills}/dot-writing-for-agents/SKILL.md +0 -0
  106. /package/{plugin/skills → skills}/dot-writing-for-agents/references/pointers.md +0 -0
  107. /package/{plugin/skills → skills}/dot-writing-for-agents/references/skill-mechanics.md +0 -0
  108. /package/{plugin/skills → skills}/dot-writing-for-agents/references/steps.md +0 -0
@@ -0,0 +1,191 @@
1
+ ---
2
+ description: Review UI code for Vercel Web Interface Guidelines compliance
3
+ argument-hint: <file-or-pattern>
4
+ ---
5
+
6
+ # Web Interface Guidelines
7
+
8
+ Review these files for compliance: $ARGUMENTS
9
+
10
+ Read files, check against rules below. Output concise but comprehensive. Sacrifice grammar for brevity. High signal-to-noise.
11
+
12
+ ## Rules
13
+
14
+ ### Accessibility
15
+
16
+ - Icon-only buttons need `aria-label`
17
+ - Form controls need `<label>` or `aria-label`
18
+ - Interactive elements need keyboard handlers (`onKeyDown`/`onKeyUp`)
19
+ - `<button>` for actions, `<a>`/`<Link>` for navigation (not `<div onClick>`)
20
+ - Images need `alt` (or `alt=""` if decorative)
21
+ - Decorative icons need `aria-hidden="true"`
22
+ - Async updates (toasts, validation) need `aria-live="polite"`
23
+ - Use semantic HTML (`<button>`, `<a>`, `<label>`, `<table>`) before ARIA
24
+ - Headings hierarchical `<h1>`–`<h6>`; include skip link for main content
25
+ - `scroll-margin-top` on heading anchors
26
+ - Meaningful media needs captions, transcripts, or descriptions as applicable
27
+ - Media controls need keyboard support; decorative media needs assistive-tech hiding
28
+
29
+ ### Focus States
30
+
31
+ - Interactive elements need visible focus: `focus-visible:ring-*` or equivalent
32
+ - Never `outline-none` / `outline: none` without focus replacement
33
+ - Use `:focus-visible` over `:focus` (avoid focus ring on click)
34
+ - Group focus with `:focus-within` for compound controls
35
+ - Sticky headers/footers/overlays must not cover the focused element
36
+
37
+ ### Forms
38
+
39
+ - Inputs need `autocomplete` and meaningful `name`
40
+ - Use correct `type` (`email`, `tel`, `url`, `number`) and `inputmode`
41
+ - Never block paste (`onPaste` + `preventDefault`)
42
+ - Labels clickable (`htmlFor` or wrapping control)
43
+ - Disable spellcheck on emails, codes, usernames (`spellCheck={false}`)
44
+ - Checkboxes/radios: label + control share single hit target (no dead zones)
45
+ - Submit button stays enabled until request starts; spinner during request
46
+ - Errors inline next to fields; focus first error on submit
47
+ - Placeholders end with `…` and show example pattern
48
+ - `autocomplete="off"` on non-auth fields to avoid password manager triggers
49
+ - Warn before navigation with unsaved changes (`beforeunload` or router guard)
50
+
51
+ ### Animation
52
+
53
+ - Honor `prefers-reduced-motion` (provide reduced variant or disable)
54
+ - Animate `transform`/`opacity` only (compositor-friendly)
55
+ - Never `transition: all`: list properties explicitly
56
+ - Set correct `transform-origin`
57
+ - SVG: transforms on `<g>` wrapper with `transform-box: fill-box; transform-origin: center`
58
+ - Animations interruptible: respond to user input mid-animation
59
+ - Autoplay motion >5 seconds alongside other content needs pause, stop, or hide controls
60
+ - Muted decorative loops must stop under `prefers-reduced-motion`
61
+
62
+ ### Typography
63
+
64
+ - `…` not `...`
65
+ - Curly quotes `“` `”` not straight `"`
66
+ - Non-breaking spaces: `10&nbsp;MB`, `⌘&nbsp;K`, brand names
67
+ - Loading states end with `…`: `"Loading…"`, `"Saving…"`
68
+ - `font-variant-numeric: tabular-nums` for number columns/comparisons
69
+ - Use `text-wrap: balance` or `text-pretty` on headings (prevents widows)
70
+
71
+ ### Content Handling
72
+
73
+ - Text containers handle long content: `truncate`, `line-clamp-*`, or `break-words`
74
+ - Flex children need `min-w-0` to allow text truncation
75
+ - Handle empty states: do not render broken UI for empty strings/arrays
76
+ - User-generated content: anticipate short, average, and very long inputs
77
+
78
+ ### Images
79
+
80
+ - `<img>` needs explicit `width` and `height` (prevents CLS)
81
+ - Below-fold images: `loading="lazy"`
82
+ - Above-fold critical images: `priority` or `fetchpriority="high"`
83
+
84
+ ### Performance
85
+
86
+ - Large lists (>50 items): virtualize (`virtua`, `content-visibility: auto`)
87
+ - No layout reads in render (`getBoundingClientRect`, `offsetHeight`, `offsetWidth`, `scrollTop`)
88
+ - Batch DOM reads/writes; avoid interleaving
89
+ - Prefer uncontrolled inputs; controlled inputs must be cheap per keystroke
90
+ - Add `<link rel="preconnect">` for CDN/asset domains
91
+ - Critical fonts: `<link rel="preload" as="font">` with `font-display: swap`
92
+ - Prefer `<video autoplay muted loop playsinline>` over animated GIF; provide a still alternative
93
+ - Short non-essential loops: Safari H.264 MP4 `<picture>` source, `prefers-reduced-motion` media condition, and still fallback
94
+
95
+ ### Navigation & State
96
+
97
+ - URL reflects state: filters, tabs, pagination, expanded panels in query params
98
+ - Links use `<a>`/`<Link>` (Cmd/Ctrl+click, middle-click support)
99
+ - Deep-link all stateful UI (if uses `useState`, consider URL sync via nuqs or similar)
100
+ - Destructive actions need confirmation modal or undo window, never immediate
101
+
102
+ ### Touch & Interaction
103
+
104
+ - `touch-action: manipulation` (prevents double-tap zoom delay)
105
+ - `-webkit-tap-highlight-color` set intentionally
106
+ - `overscroll-behavior: contain` in modals/drawers/sheets
107
+ - Page rubber-band suppression: `overscroll-behavior: none` on `<html>` inside `@media (pointer: fine)`; keep coarse-pointer page defaults for pull-to-refresh. Test hybrid touch devices: `pointer` describes the primary input, and `none` also disables scroll chaining and native swipe navigation
108
+ - During drag: disable text selection, `inert` on dragged elements
109
+ - Drag/swipe/pinch/path gestures need tap/click and keyboard alternatives unless essential
110
+ - `autoFocus` sparingly: desktop only, single primary input; avoid on mobile
111
+
112
+ ### Safe Areas & Layout
113
+
114
+ - Full-bleed layouts need `env(safe-area-inset-*)` for notches
115
+ - Avoid unwanted scrollbars: `overflow-x-hidden` on containers, fix content overflow
116
+ - Flex/grid over JS measurement for layout
117
+
118
+ ### Dark Mode & Theming
119
+
120
+ - `color-scheme: dark` on `<html>` for dark themes (fixes scrollbar, inputs)
121
+ - `<meta name="theme-color">` matches page background
122
+ - Native `<select>`: explicit `background-color` and `color` (Windows dark mode)
123
+
124
+ ### Locale & i18n
125
+
126
+ - Dates/times: use `Intl.DateTimeFormat` not hardcoded formats
127
+ - Numbers/currency: use `Intl.NumberFormat` not hardcoded formats
128
+ - Detect language via `Accept-Language` / `navigator.languages`, not IP
129
+ - Brand names, code tokens, identifiers: wrap with `translate="no"` to prevent garbled auto-translation
130
+
131
+ ### Hydration Safety
132
+
133
+ - Inputs with `value` need `onChange` (or use `defaultValue` for uncontrolled)
134
+ - Date/time rendering: guard against hydration mismatch (server vs client)
135
+ - `suppressHydrationWarning` only where truly needed
136
+
137
+ ### Hover & Interactive States
138
+
139
+ - Buttons/links need `hover:` state (visual feedback)
140
+ - Interactive states increase contrast: hover/active/focus more prominent than rest
141
+
142
+ ### Content & Copy
143
+
144
+ - Active voice: "Install the CLI" not "The CLI will be installed"
145
+ - Title Case for headings/buttons (Chicago style)
146
+ - Numerals for counts: "8 deployments" not "eight"
147
+ - Specific button labels: "Save API Key" not "Continue"
148
+ - Error messages include fix/next step, not just problem
149
+ - Second person; avoid first person
150
+ - `&` over "and" where space-constrained
151
+
152
+ ### Anti-patterns (flag these)
153
+
154
+ - `user-scalable=no` or `maximum-scale=1` disabling zoom
155
+ - `onPaste` with `preventDefault`
156
+ - `transition: all`
157
+ - `outline-none` without focus-visible replacement
158
+ - Inline `onClick` navigation without `<a>`
159
+ - `<div>` or `<span>` with click handlers (should be `<button>`)
160
+ - Images without dimensions
161
+ - Large arrays `.map()` without virtualization
162
+ - Form inputs without labels
163
+ - Icon buttons without `aria-label`
164
+ - Hardcoded date/number formats (use `Intl.*`)
165
+ - `autoFocus` without clear justification
166
+ - Animated GIF when compressed video is suitable
167
+ - Gesture-only action without tap/click and keyboard alternative
168
+
169
+ ## Output Format
170
+
171
+ Group by file. Use `file:line` format (VS Code clickable). Terse findings.
172
+
173
+ ```text
174
+ ## src/Button.tsx
175
+
176
+ src/Button.tsx:42 - icon button missing aria-label
177
+ src/Button.tsx:18 - input lacks label
178
+ src/Button.tsx:55 - animation missing prefers-reduced-motion
179
+ src/Button.tsx:67 - transition: all → list properties
180
+
181
+ ## src/Modal.tsx
182
+
183
+ src/Modal.tsx:12 - missing overscroll-behavior: contain
184
+ src/Modal.tsx:34 - "..." → "…"
185
+
186
+ ## src/Card.tsx
187
+
188
+ ✓ pass
189
+ ```
190
+
191
+ State issue + location. Skip explanation unless fix non-obvious. No preamble.
@@ -1,10 +1,10 @@
1
1
  ---
2
- name: dot-stack-review
2
+ name: dot-walkthrough-branch
3
3
  description: Review the commits of a branch as an ordered stack of dependency layers, and report each layer with its findings.
4
4
  disable-model-invocation: true
5
5
  ---
6
6
 
7
- # Stack review
7
+ # Branch walkthrough
8
8
 
9
9
  Review the committed changes of a branch as a **stack**: layers of files in dependency order. A reader understands layer 1 on its own, and each later layer from the layers above it. The `dot-code-review` skill gives the review. This skill gives the layers and the report.
10
10
 
@@ -24,13 +24,7 @@ Done when you have the merge base and the list of changed files.
24
24
 
25
25
  ## 2. Group the layers
26
26
 
27
- Group the changed files into layers by dependency, such as types and contracts, core logic, callers, tests, then docs and config.
28
-
29
- - Derive each dependency from the imports and the diff. File A depends on file B when A imports, calls, links, or names something that the diff adds or changes in B. A folder name is a hint only.
30
- - A layer holds whole files. Split a file into hunks only when it holds changes for 2 layers. List the file in both layers, each with its own hunks.
31
- - Order the layers in the order that a reader must understand them. Each layer depends only on layers with a lower number. Merge 2 layers that depend on each other.
32
-
33
- Show the layer map, one line per layer: the number, the name, and the files. Then continue to step 3. The user can ask for new layers after the report.
27
+ Group the changed files of step 1 into layers with the rules of [`references/layers.md`](references/layers.md). Then continue to step 3. The user can ask for new layers after the report.
34
28
 
35
29
  Done when each changed hunk is in exactly one layer, and no layer depends on a layer below it.
36
30
 
@@ -82,35 +76,20 @@ Done when the report has every layer of step 2 and every finding of step 3.
82
76
 
83
77
  Write a self-contained HTML page of the stack, with the diff of each file and its findings.
84
78
 
85
- 1. Run `git check-ignore -q .tmp` at the repository root. When it exits with a non-zero code, stop, and tell the user that Git does not ignore `.tmp`, so the page could reach a commit.
86
- 2. Write the layers of step 2 and the findings of step 3 to `.tmp/stack-review/<branch-slug>.json`. `<branch-slug>` is head with each character other than a letter, a digit, `.`, `_`, or `-` replaced by `-`, such as `feat-flow-fix-loop`. Sort the keys. `dependsOn` has the 1-based numbers of the layers that a layer needs.
79
+ 1. Run `git check-ignore -q .tmp/` at the repository root. When it exits with a non-zero code, stop, and tell the user that Git does not ignore `.tmp`, so the page could reach a commit.
80
+ 2. Write the layers of step 2 and the findings of step 3 to `.tmp/walkthrough/<branch-slug>.json`. `<branch-slug>` is head with each character other than a letter, a digit, `.`, `_`, or `-` replaced by `-`, such as `feat-flow-fix-loop`. Sort the keys.
87
81
 
88
82
  ```json
89
83
  {
90
84
  "base": "main",
91
85
  "head": "feat/my-change",
92
- "layers": [
93
- {
94
- "dependsOn": [],
95
- "files": ["src/types.ts"],
96
- "findings": [
97
- {
98
- "body": "**Scenario:** ...\n**Fix:** ...",
99
- "file": "src/types.ts",
100
- "kind": "correctness",
101
- "line": 42,
102
- "severity": "high",
103
- "summary": "One-line summary"
104
- }
105
- ],
106
- "name": "Contracts",
107
- "purpose": "One line"
108
- }
109
- ]
86
+ "layers": []
110
87
  }
111
88
  ```
112
89
 
113
- 3. Run the script of this skill directory from the repository root: `node <skill directory>/scripts/page.mjs .tmp/stack-review/<branch-slug>.json`. It runs `git merge-base` and `git diff` itself, and prints the path of the page.
90
+ `layers` has the layer objects of the layers JSON in [`references/layers.md`](references/layers.md).
91
+
92
+ 3. Run the script of this skill directory from the repository root: `node <skill directory>/scripts/page.mjs .tmp/walkthrough/<branch-slug>.json`. It runs `git merge-base` and `git diff` itself, and prints the path of the page.
114
93
  4. When the script exits with a non-zero code, fix the field that its message names, and run it again.
115
94
 
116
95
  Done when the user has the path of the page.
@@ -0,0 +1,38 @@
1
+ # Layers
2
+
3
+ Group the changed files of a diff into layers by dependency, such as types and contracts, core logic, callers, tests, then docs and config. A reader understands layer 1 on its own, and each later layer from the layers above it.
4
+
5
+ ## Group the layers
6
+
7
+ - Derive each dependency from the imports and the diff. File A depends on file B when A imports, calls, links, or names something that the diff adds or changes in B. A folder name is a hint only.
8
+ - A layer holds whole files. Split a file into hunks only when it holds changes for 2 layers. List the file in both layers, each with its own hunks.
9
+ - Order the layers in the order that a reader must understand them. Each layer depends only on layers with a lower number. Merge 2 layers that depend on each other.
10
+
11
+ Show the layer map, one line per layer: the number, the name, and the files.
12
+
13
+ A grouping is done when each changed hunk is in exactly one layer, and no layer depends on a layer below it.
14
+
15
+ ## Layers JSON
16
+
17
+ The `layers` array of a layers file has one object per layer, in layer order. Sort the keys. `dependsOn` has the 1-based numbers of the layers that a layer needs. Each finding names a file of its layer.
18
+
19
+ ```json
20
+ [
21
+ {
22
+ "dependsOn": [],
23
+ "files": ["src/types.ts"],
24
+ "findings": [
25
+ {
26
+ "body": "**Scenario:** ...\n**Fix:** ...",
27
+ "file": "src/types.ts",
28
+ "kind": "correctness",
29
+ "line": 42,
30
+ "severity": "high",
31
+ "summary": "One-line summary"
32
+ }
33
+ ],
34
+ "name": "Contracts",
35
+ "purpose": "One line"
36
+ }
37
+ ]
38
+ ```
@@ -1,7 +1,10 @@
1
1
  // Usage: node page.mjs <layers.json>, from inside the repository. Writes
2
- // .tmp/stack-review/<branch-slug>.html at the repository root, and prints its path.
2
+ // .tmp/walkthrough/<slug>.html at the repository root, and prints its path.
3
+ // The layers file names the target with "base" and "head" (a branch), with "oldTree" and
4
+ // "newTree" (a tree range), or with none of them (the working tree against HEAD).
3
5
  import { spawnSync } from "node:child_process";
4
6
  import fs from "node:fs";
7
+ import os from "node:os";
5
8
  import path from "node:path";
6
9
 
7
10
  const SEVERITIES = ["high", "medium", "low"];
@@ -14,18 +17,19 @@ const stack = readStack(layersFile);
14
17
  validate(stack);
15
18
 
16
19
  const root = git(["rev-parse", "--show-toplevel"]);
17
- const mergeBase = git(["merge-base", stack.base, stack.head]);
20
+ const target = resolveTarget();
18
21
  // shortcut: a file that is split between 2 layers shows its full diff in both layers, split the diff by hunk when readers need only the hunks of each layer.
19
22
  const diffs = new Map();
20
23
  stack.layers.forEach((layer, i) => {
21
24
  layer.files.forEach((file, j) => {
22
- if (!diffs.has(file)) diffs.set(file, git(["--literal-pathspecs", "diff", "--no-color", "--no-ext-diff", mergeBase, stack.head, "--", file], root));
23
- if (!diffs.get(file)) invalid(`layers[${i}].files[${j}]`, "has no changes between the merge base and head");
25
+ if (!diffs.has(file)) diffs.set(file, git(["--literal-pathspecs", "diff", "--no-color", "--no-ext-diff", target.from, target.to, "--", file], root));
26
+ if (!diffs.get(file)) invalid(`layers[${i}].files[${j}]`, "has no changes in the target");
24
27
  });
25
28
  });
26
29
 
27
- const page = path.join(root, ".tmp", "stack-review", `${stack.head.replace(/[^\w.-]/g, "-")}.html`);
30
+ const page = path.join(root, ".tmp", "walkthrough", `${target.slug.replace(/[^\w.-]/g, "-")}.html`);
28
31
  fs.mkdirSync(path.dirname(page), { recursive: true });
32
+ fs.rmSync(page, { force: true });
29
33
  fs.writeFileSync(page, renderPage());
30
34
  console.log(page);
31
35
 
@@ -56,8 +60,14 @@ function isText(value) {
56
60
  function validate(stack) {
57
61
  if (!isObject(stack)) invalid("the root", "must be an object");
58
62
  for (const key of ["base", "head"]) {
59
- if (typeof stack[key] !== "string" || !/^[^-\s]\S*$/.test(stack[key])) invalid(key, "must be a branch or commit name without spaces that does not start with -");
63
+ if (key in stack && (typeof stack[key] !== "string" || !/^[^-\s]\S*$/.test(stack[key]))) invalid(key, "must be a branch or commit name without spaces that does not start with -");
60
64
  }
65
+ if ("base" in stack !== "head" in stack) invalid("base and head", "must both be present or both be absent");
66
+ for (const key of ["oldTree", "newTree"]) {
67
+ if (key in stack && (typeof stack[key] !== "string" || !/^[0-9a-f]{4,64}$/.test(stack[key]))) invalid(key, "must be a tree id in lowercase hexadecimal");
68
+ }
69
+ if ("oldTree" in stack !== "newTree" in stack) invalid("oldTree and newTree", "must both be present or both be absent");
70
+ if ("base" in stack && "oldTree" in stack) invalid("base", "cannot go with oldTree: name a branch or a tree range, not both");
61
71
  if (!Array.isArray(stack.layers) || stack.layers.length === 0) invalid("layers", "must be a non-empty array");
62
72
  stack.layers.forEach((layer, index) => {
63
73
  const at = `layers[${index}]`;
@@ -84,8 +94,27 @@ function validate(stack) {
84
94
  });
85
95
  }
86
96
 
87
- function git(args, cwd) {
88
- const result = spawnSync("git", args, { cwd, encoding: "utf8", maxBuffer: MAX_DIFF });
97
+ function resolveTarget() {
98
+ if ("head" in stack) {
99
+ const mergeBase = git(["merge-base", stack.base, stack.head]);
100
+ return { from: mergeBase, slug: stack.head, subtitle: `Merge base <code>${mergeBase.slice(0, 7)}</code>`, title: `${stack.head} vs ${stack.base}`, to: stack.head };
101
+ }
102
+ if ("oldTree" in stack) {
103
+ const [from, to] = [stack.oldTree, stack.newTree].map((id) => git(["rev-parse", "--verify", "--end-of-options", `${id}^{tree}`], root));
104
+ const range = `${from.slice(0, 12)}..${to.slice(0, 12)}`;
105
+ return { from, slug: `tree-${range}`, subtitle: "Tree range", title: range, to };
106
+ }
107
+ const indexDir = fs.mkdtempSync(path.join(os.tmpdir(), "walkthrough-"));
108
+ process.once("exit", () => fs.rmSync(indexDir, { recursive: true, force: true }));
109
+ const env = { ...process.env, GIT_INDEX_FILE: path.join(indexDir, "index") };
110
+ git(["read-tree", "HEAD"], root, env);
111
+ // shortcut: git add writes every changed and untracked file as a loose object into the real object database, point GIT_OBJECT_DIRECTORY at a temporary directory with the real one as an alternate when that growth matters.
112
+ git(["add", "--all", "--", "."], root, env);
113
+ return { from: "HEAD", slug: "working-tree", subtitle: "Working tree against <code>HEAD</code>", title: "working tree", to: git(["write-tree"], root, env) };
114
+ }
115
+
116
+ function git(args, cwd, env = process.env) {
117
+ const result = spawnSync("git", args, { cwd, env, encoding: "utf8", maxBuffer: MAX_DIFF });
89
118
  if (result.status !== 0) fail(`git ${args.join(" ")} failed: ${(result.stderr || result.error?.message || "").trim()}`);
90
119
  return result.stdout.trimEnd();
91
120
  }
@@ -209,7 +238,7 @@ function renderOverviewRow(layer, index) {
209
238
  }
210
239
 
211
240
  function renderPage() {
212
- const title = `${stack.head} vs ${stack.base}`;
241
+ const { subtitle, title } = target;
213
242
  return `<!doctype html>
214
243
  <html lang="en">
215
244
  <head>
@@ -336,7 +365,7 @@ table.diff tr:target td { background: color-mix(in srgb, var(--blue) 18%, transp
336
365
  <main>
337
366
  <div class="hero">
338
367
  <h1>${escapeHtml(title)}</h1>
339
- <p>Merge base <code>${mergeBase.slice(0, 7)}</code></p>
368
+ <p>${subtitle}</p>
340
369
  </div>
341
370
  <h2 class="section-title">Layers</h2>
342
371
  <ol class="stack">
@@ -0,0 +1,62 @@
1
+ ---
2
+ name: dot-walkthrough-changes
3
+ description: Walk through the uncommitted changes of the working tree, or the changes between two trees, as an ordered stack of dependency layers, with an optional review and an HTML page. Use when the user or an agent asks to walk through or group the current changes before a commit. Do not use it for a review that needs no layers: use `dot-code-review`.
4
+ ---
5
+
6
+ # Changes walkthrough
7
+
8
+ Walk through the changes of the working tree as a **stack**: layers of files in dependency order. This skill follows [`dot-walkthrough-branch`](../dot-walkthrough-branch/SKILL.md). It differs in the target, the optional review, and the output path.
9
+
10
+ ## 1. Pick the target
11
+
12
+ - **Working tree** (default): the working tree against `HEAD`. The diff is `git diff HEAD`, and each untracked file that `git status --porcelain` lists is a new file. Git ignores the files that `.gitignore` names, so they stay out.
13
+ - **Tree range**: `<old-tree> <new-tree>`, when the caller gives the two tree ids. The diff is `git diff <old-tree> <new-tree>`.
14
+ - **Output path**: a file path from the caller, for the layers JSON.
15
+ - **Layers only**: when the caller says "layers only", skip step 3.
16
+ - **Page**: when the arguments include `page`, run step 5 after the report, without the offer.
17
+
18
+ Read each changed file from the working tree, or with `git show <tree>:<path>` for a tree range. For a deleted file, read it from `HEAD` or from the old tree.
19
+
20
+ State the target in one line: `working tree vs HEAD (<short sha>)`, or `<old-tree> .. <new-tree>`.
21
+
22
+ Done when you have the list of changed files. When there are none, stop and tell the user.
23
+
24
+ ## 2. Group the layers
25
+
26
+ Group the changed files into layers with the rules of [`layers.md`](../dot-walkthrough-branch/references/layers.md).
27
+
28
+ Done when each changed hunk is in exactly one layer, and no layer depends on a layer below it.
29
+
30
+ ## 3. Review
31
+
32
+ Skip this step when the caller said "layers only". Each layer then has an empty `findings` array.
33
+
34
+ Otherwise, follow step 3 of [`dot-walkthrough-branch`](../dot-walkthrough-branch/SKILL.md#3-review) on the diff of step 1.
35
+
36
+ Done when each layer has its findings, is clean, or was skipped.
37
+
38
+ ## 4. Report
39
+
40
+ Run this step only when the caller gave no output path. Fill the template of step 4 of [`dot-walkthrough-branch`](../dot-walkthrough-branch/SKILL.md#4-report), with the target line of step 1 in place of the branch line. When step 3 ran, add the "Make it impossible" section. Then offer the page of step 5.
41
+
42
+ With an output path, skip the report. Go to step 5.
43
+
44
+ Done when the report has every layer of step 2, and every finding of step 3 when it ran.
45
+
46
+ ## 5. Page
47
+
48
+ 1. Run `git check-ignore -q .tmp/` at the repository root. When it exits with a non-zero code, stop, and tell the caller that Git does not ignore `.tmp`, so the page could reach a commit.
49
+ 2. Write the layers to the output path of the caller, or to `.tmp/walkthrough/working-tree.json`. Sort the keys. Leave out `base` and `head`. For a tree range, add `oldTree` and `newTree` as full tree ids.
50
+
51
+ ```json
52
+ {
53
+ "layers": []
54
+ }
55
+ ```
56
+
57
+ `layers` has the layer objects of the layers JSON in [`layers.md`](../dot-walkthrough-branch/references/layers.md).
58
+
59
+ 3. Run the script of `dot-walkthrough-branch` from the repository root: `node <skills directory>/dot-walkthrough-branch/scripts/page.mjs <layers file>`. The page title is `working tree`, or the tree range.
60
+ 4. When the script exits with a non-zero code, fix the field that its message names, and run it again.
61
+
62
+ Done when the caller has the path of the page. With an output path, return the page path as the last line of the answer.
@@ -0,0 +1,8 @@
1
+ {
2
+ "repository": "https://github.com/mattpocock/skills",
3
+ "path": "skills/productivity/writing-for-agents",
4
+ "commit": "49dd158d1076134a641b33efb035946536778336",
5
+ "license": "MIT",
6
+ "modified": true,
7
+ "notes": "Added a sentence about the conventions of the repository. Renamed with the dot- prefix. Rewrote the text under rules/writing.md. Moved SKILL-MECHANICS.md to references/skill-mechanics.md, and moved the context pointers, the two loads, and the splits to references/pointers.md, and the completion criteria to references/steps.md."
8
+ }
@@ -1,10 +0,0 @@
1
- {
2
- "name": "dotagents",
3
- "description": "Skills, agents, and hooks for a planned, tested, and reviewed coding workflow.",
4
- "author": {
5
- "name": "igorlau"
6
- },
7
- "homepage": "https://github.com/igorlau/dotagents#readme",
8
- "repository": "https://github.com/igorlau/dotagents",
9
- "license": "MIT"
10
- }
@@ -1,27 +0,0 @@
1
- ---
2
- name: dot-implementer
3
- description: Write the production code of one roadmap task with the dot-implement skill, and hand off the test changes it needs. Use for the implementation step of the dot-flow skill.
4
- skills: dotagents:dot-implement
5
- disallowedTools: Agent
6
- ---
7
-
8
- # Implementer
9
-
10
- Run the implementation step of a roadmap task. Follow the `dot-implement` skill.
11
-
12
- ## Input
13
-
14
- The prompt gives these fields:
15
-
16
- - **Task**: the path of the roadmap task file.
17
- - **Findings**: only on a second run, the review findings to fix. Fix these findings and nothing else. For each finding, fix every place in the task change that has the same problem.
18
-
19
- When the task is missing, stop and report it.
20
-
21
- Write no tests, do not commit, and do not tick the roadmap checkbox.
22
-
23
- ## Output
24
-
25
- End with the handoff of step 5 of `dot-implement`, and write nothing after it. The next step writes the tests.
26
-
27
- On a run with **Findings**, end the handoff with the line `**Behavior change:** <yes | no>`. A behavior change is a change to what the code does for any input.
@@ -1,44 +0,0 @@
1
- ---
2
- name: dot-reviewer
3
- description: Review the uncommitted changes of one roadmap task with the dot-code-review skill. Use for the review step of the dot-flow skill.
4
- skills: dotagents:dot-code-review
5
- disallowedTools: Agent
6
- ---
7
-
8
- # Reviewer
9
-
10
- Run the review step of a roadmap task. Follow the `dot-code-review` skill.
11
-
12
- ## Input
13
-
14
- The prompt gives these fields:
15
-
16
- - **Task**: the path of the roadmap task file. Check the change against its requirements and its "Out of scope" section. Also read the `## Requirements` section of the roadmap `README.md`. Check the change against every non-negotiable (`NN`) and against each business rule (`BR`) that the task names. Report a breached `NN` as a `high` finding.
17
- - **Handoff**: the replies of the earlier steps.
18
- - **Since**: only on a delta review of a fix run, `<old-tree> <new-tree>`. Run `git diff <old-tree> <new-tree>`, and review only that diff. Still check the diff against every `NN` and each `BR` that the task names.
19
- - **Earlier findings**: only on a fix run, the findings of the earlier review that the implementer fixed. Give each one a status:
20
- - `fixed`: the problem is gone.
21
- - `open`: the problem is still there.
22
- - `regressed`: the fix made the problem worse, or moved it to other code.
23
-
24
- Do not report an earlier finding again as a new finding.
25
-
26
- When the task or the handoff is missing, stop and report it.
27
-
28
- Without **Since**, the target is the uncommitted change: `git diff HEAD`, plus the untracked files that `git status --short` lists. Review the whole target.
29
-
30
- Without **Earlier findings**, report every finding at every severity, so that no finding waits for a later round. With **Earlier findings**, on a full or a delta review, report only new `high` and `medium` findings.
31
-
32
- Keep the code as it is. Delete each test that you write to prove a finding. Do not commit, and do not tick the roadmap checkbox.
33
-
34
- ## Output
35
-
36
- Start the reply with this line. On a fix run, add the status of each earlier finding after it. Then give the report of `dot-code-review` with the new findings:
37
-
38
- ```markdown
39
- **Highest severity:** <high | medium | low | none>
40
- **Earlier findings:**
41
- - <fixed | open | regressed>: <the summary of the finding>
42
- ```
43
-
44
- The highest severity covers the new findings and the earlier findings that are `open` or `regressed`.
@@ -1,25 +0,0 @@
1
- ---
2
- name: dot-tester
3
- description: Write the tests of one roadmap task with the dot-testing skill, after the code exists. Use for the test step of the dot-flow skill.
4
- skills: dotagents:dot-testing
5
- disallowedTools: Agent
6
- ---
7
-
8
- # Tester
9
-
10
- Run the test step of a roadmap task. Follow the `dot-testing` skill and its `references/after-implement.md`.
11
-
12
- ## Input
13
-
14
- The prompt gives these fields:
15
-
16
- - **Task**: the path of the roadmap task file.
17
- - **Handoff**: the handoff of the implementation step, with the "Expected failures" and "Behaviors that need tests" fields.
18
-
19
- When a field is missing, stop and report it.
20
-
21
- Keep the production code as it is. Do not commit, and do not tick the roadmap checkbox.
22
-
23
- ## Output
24
-
25
- End with the reply that `references/after-implement.md` gives, and write nothing after it.