@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.
- package/README.md +66 -66
- package/THIRD_PARTY_NOTICES.md +101 -6
- package/dist/build-info.json +1 -1
- package/dist/catalog.js +3 -3
- package/dist/cli.js +1 -1
- package/dist/commands.js +52 -15
- package/dist/manifest.js +8 -1
- package/dist/paths.js +0 -4
- package/dist/targets.js +3 -9
- package/dist/wizard.js +1 -1
- package/package.json +5 -3
- package/{plugin/rules → rules}/comments.upstream.json +1 -1
- package/{plugin/rules → rules}/ponytail.md +1 -1
- package/{plugin/rules → rules}/ponytail.upstream.json +1 -1
- package/{plugin/rules → rules}/writing.md +5 -2
- package/{plugin/rules → rules}/writing.upstream.json +1 -1
- package/{plugin/scaffold → scaffold}/AGENTS.md.tmpl +1 -1
- package/{plugin/skills → skills}/dot-code-review/SKILL.md +2 -0
- package/{plugin/skills → skills}/dot-code-review/UPSTREAM.json +1 -1
- package/skills/dot-code-review/references/finding-classes.md +33 -0
- package/{plugin/skills → skills}/dot-code-review/references/maintainability.md +1 -0
- package/{plugin/skills → skills}/dot-comments/UPSTREAM.json +1 -1
- package/{plugin/skills → skills}/dot-commit/SKILL.md +0 -2
- package/skills/dot-correct/UPSTREAM.json +8 -0
- package/{plugin/skills → skills}/dot-debug/UPSTREAM.json +1 -1
- package/{plugin/skills → skills}/dot-grilling/UPSTREAM.json +2 -2
- package/{plugin/skills → skills}/dot-handoff/UPSTREAM.json +1 -1
- package/{plugin/skills → skills}/dot-implement/SKILL.md +2 -2
- package/{plugin/skills → skills}/dot-implement/references/typescript.md +2 -1
- package/{plugin/skills → skills}/dot-plan/SKILL.md +3 -1
- package/{plugin/skills → skills}/dot-roadmap/SKILL.md +7 -4
- package/skills/dot-security-audit/SKILL.md +87 -0
- package/skills/dot-security-audit/UPSTREAM.json +8 -0
- package/skills/dot-security-audit/references/AI-AND-LLM.md +83 -0
- package/skills/dot-security-audit/references/ATTACK-CLASSES.md +130 -0
- package/skills/dot-security-audit/references/CLIENT-SIDE.md +83 -0
- package/skills/dot-security-audit/references/CLOUD-AND-DEPLOYMENT.md +86 -0
- package/skills/dot-security-audit/references/DATA-ISOLATION-AND-LIFECYCLE.md +84 -0
- package/skills/dot-security-audit/references/DESKTOP-MOBILE-AND-LOCAL-IPC.md +89 -0
- package/skills/dot-security-audit/references/MEMORY-SAFETY-AND-BINARY.md +101 -0
- package/skills/dot-security-audit/references/PROTOCOLS-RPC-AND-MESSAGING.md +81 -0
- package/skills/dot-security-audit/references/RESOURCE-EXHAUSTION-AND-AVAILABILITY.md +78 -0
- package/skills/dot-security-audit/references/SUPPLY-CHAIN-AND-RELEASE.md +73 -0
- package/skills/dot-security-audit/references/WEB-PROTOCOL-AND-AUTH.md +105 -0
- package/skills/dot-security-changes/SKILL.md +68 -0
- package/{plugin/skills → skills}/dot-testing/UPSTREAM.json +1 -1
- package/skills/dot-ui-review/SKILL.md +79 -0
- package/skills/dot-ui-review/UPSTREAM.json +8 -0
- package/skills/dot-ux-review/SKILL.md +50 -0
- package/skills/dot-ux-review/UPSTREAM.json +8 -0
- package/skills/dot-ux-review/references/web-interface-guidelines.md +191 -0
- package/{plugin/skills/dot-stack-review → skills/dot-walkthrough-branch}/SKILL.md +9 -30
- package/skills/dot-walkthrough-branch/references/layers.md +38 -0
- package/{plugin/skills/dot-stack-review → skills/dot-walkthrough-branch}/scripts/page.mjs +39 -10
- package/skills/dot-walkthrough-changes/SKILL.md +62 -0
- package/skills/dot-writing-for-agents/UPSTREAM.json +8 -0
- package/plugin/.claude-plugin/plugin.json +0 -10
- package/plugin/agents/dot-implementer.md +0 -27
- package/plugin/agents/dot-reviewer.md +0 -44
- package/plugin/agents/dot-tester.md +0 -25
- package/plugin/hooks/check.mjs +0 -118
- package/plugin/hooks/hooks.json +0 -54
- package/plugin/hooks/rules.mjs +0 -27
- package/plugin/skills/dot-correct/UPSTREAM.json +0 -8
- package/plugin/skills/dot-correct/agents/openai.yaml +0 -5
- package/plugin/skills/dot-debug/agents/openai.yaml +0 -3
- package/plugin/skills/dot-flow/SKILL.md +0 -105
- package/plugin/skills/dot-flow/agents/openai.yaml +0 -5
- package/plugin/skills/dot-flow/references/fix-round.md +0 -64
- package/plugin/skills/dot-flow/references/inline.md +0 -9
- package/plugin/skills/dot-grilling/agents/openai.yaml +0 -3
- package/plugin/skills/dot-handoff/agents/openai.yaml +0 -5
- package/plugin/skills/dot-roadmap/agents/openai.yaml +0 -5
- package/plugin/skills/dot-stack-review/agents/openai.yaml +0 -5
- package/plugin/skills/dot-writing-for-agents/UPSTREAM.json +0 -8
- package/plugin/skills/dot-writing-for-agents/agents/openai.yaml +0 -3
- /package/{plugin/rules → rules}/code-style.md +0 -0
- /package/{plugin/rules → rules}/comments.md +0 -0
- /package/{plugin/rules → rules}/core.md +0 -0
- /package/{plugin/scaffold → scaffold}/.claude/settings.json.tmpl +0 -0
- /package/{plugin/scaffold → scaffold}/.editorconfig.tmpl +0 -0
- /package/{plugin/scaffold → scaffold}/.gitattributes.tmpl +0 -0
- /package/{plugin/scaffold → scaffold}/CLAUDE.md.tmpl +0 -0
- /package/{plugin/skills → skills}/dot-comments/SKILL.md +0 -0
- /package/{plugin/skills → skills}/dot-correct/SKILL.md +0 -0
- /package/{plugin/skills → skills}/dot-debug/SKILL.md +0 -0
- /package/{plugin/skills → skills}/dot-debug/references/loops.md +0 -0
- /package/{plugin/skills → skills}/dot-debug/scripts/hitl-loop.template.sh +0 -0
- /package/{plugin/skills → skills}/dot-docs-writing/SKILL.md +0 -0
- /package/{plugin/skills → skills}/dot-docs-writing/references/formatting.md +0 -0
- /package/{plugin/skills → skills}/dot-docs-writing/references/global-and-accessible.md +0 -0
- /package/{plugin/skills → skills}/dot-docs-writing/references/word-list.md +0 -0
- /package/{plugin/skills → skills}/dot-grilling/SKILL.md +0 -0
- /package/{plugin/skills → skills}/dot-handoff/SKILL.md +0 -0
- /package/{plugin/skills → skills}/dot-implement/UPSTREAM.json +0 -0
- /package/{plugin/skills → skills}/dot-plan/UPSTREAM.json +0 -0
- /package/{plugin/skills → skills}/dot-plan/references/entity-schemas.md +0 -0
- /package/{plugin/skills → skills}/dot-roadmap/UPSTREAM.json +0 -0
- /package/{plugin/skills → skills}/dot-roadmap/references/wide-refactor.md +0 -0
- /package/{plugin/skills → skills}/dot-testing/SKILL.md +0 -0
- /package/{plugin/skills → skills}/dot-testing/references/after-implement.md +0 -0
- /package/{plugin/skills → skills}/dot-testing/references/http.md +0 -0
- /package/{plugin/skills → skills}/dot-testing/references/shared-state.md +0 -0
- /package/{plugin/skills → skills}/dot-testing/references/typescript.md +0 -0
- /package/{plugin/skills → skills}/dot-writing-for-agents/SKILL.md +0 -0
- /package/{plugin/skills → skills}/dot-writing-for-agents/references/pointers.md +0 -0
- /package/{plugin/skills → skills}/dot-writing-for-agents/references/skill-mechanics.md +0 -0
- /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 MB`, `⌘ 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-
|
|
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
|
-
#
|
|
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
|
|
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
|
|
86
|
-
2. Write the layers of step 2 and the findings of step 3 to `.tmp/
|
|
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
|
-
|
|
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/
|
|
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
|
|
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",
|
|
23
|
-
if (!diffs.get(file)) invalid(`layers[${i}].files[${j}]`, "has no changes
|
|
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", "
|
|
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
|
|
88
|
-
|
|
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
|
|
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
|
|
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.
|