codeassembly-guidance 0.5.0 → 0.6.0

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 (71) hide show
  1. package/.meta/changelog.json +306 -0
  2. package/CHANGELOG.md +73 -0
  3. package/README.md +55 -4
  4. package/content/_partials/finding-grades.md +4 -0
  5. package/content/codeassembly-content.yaml +2 -0
  6. package/content/collections/recommended.md +5 -2
  7. package/content/guidance/_harnesses/rovo/AGENTS.md +0 -1
  8. package/content/guidance/rulebooks/accessibility-conventions.md +26 -6
  9. package/content/guidance/rulebooks/cli-conventions.md +17 -2
  10. package/content/guidance/rulebooks/codeassembly-content-specification.md +11 -11
  11. package/content/guidance/rulebooks/machine-readable-output-conventions.md +85 -0
  12. package/content/guidance/rulebooks/ui-copy-conventions.md +2 -2
  13. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +10 -10
  14. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +7 -3
  15. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +3 -1
  16. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +5 -5
  17. package/content/scripts/check-prose.mjs +1 -1
  18. package/content/scripts/describe-change.mjs +68 -68
  19. package/content/skills/_data/action-items.md +2 -2
  20. package/content/skills/_data/artifact-conventions.md +20 -10
  21. package/content/skills/_data/concision.md +1 -1
  22. package/content/skills/_data/entry-points.md +37 -0
  23. package/content/skills/_data/recommendation-gradient.md +6 -6
  24. package/content/skills/_data/spike-conventions.md +13 -3
  25. package/content/skills/_data/ticket-source-resolution.md +21 -4
  26. package/content/skills/_data/title-templates.md +4 -4
  27. package/content/skills/_partials/commit-title-rendering.md +2 -1
  28. package/content/skills/_partials/next-steps-after-plan.md +4 -3
  29. package/content/skills/_partials/option-format.md +8 -8
  30. package/content/skills/_partials/plan-template.md +3 -1
  31. package/content/skills/_partials/resolve-plan-and-ticket.md +22 -0
  32. package/content/skills/_partials/split-launch-prompts.md +1 -1
  33. package/content/skills/_partials/ticket-criteria-conventions.md +2 -0
  34. package/content/skills/analyze-performance/SKILL.md +102 -0
  35. package/content/skills/analyze-performance/analyze-performance.mjs +70 -0
  36. package/content/skills/assess-code-health/SKILL.md +16 -14
  37. package/content/skills/assess-code-health/assess-code-health.mjs +29 -28
  38. package/content/skills/assess-usability/SKILL.md +5 -3
  39. package/content/skills/convert-agent-prompt/SKILL.md +60 -0
  40. package/content/skills/create-commit/SKILL.md +10 -5
  41. package/content/skills/create-pr/SKILL.md +11 -11
  42. package/content/skills/create-ticket/SKILL.md +1 -0
  43. package/content/skills/design-and-plan/SKILL.md +2 -2
  44. package/content/skills/implement-plan/SKILL.md +1 -28
  45. package/content/skills/index-prototypes/SKILL.md +36 -17
  46. package/content/skills/index-prototypes/index-prototypes.mjs +14 -14
  47. package/content/skills/investigate-spike/SKILL.md +48 -0
  48. package/content/skills/prepare-prototype-brief/SKILL.md +17 -13
  49. package/content/skills/refine-plan/SKILL.md +7 -4
  50. package/content/skills/refine-prototype/SKILL.md +5 -5
  51. package/content/skills/review-branch/SKILL.md +7 -7
  52. package/content/skills/review-criteria/SKILL.md +3 -3
  53. package/content/skills/review-gh-pr/SKILL.md +1 -1
  54. package/content/skills/revise-prose/SKILL.md +9 -8
  55. package/content/skills/revise-prose/revise-prose.mjs +2 -2
  56. package/content/skills/start-ticket/SKILL.md +27 -0
  57. package/content/skills/summarize-change/SKILL.md +17 -9
  58. package/content/skills/testing-conventions/SKILL.md +12 -1
  59. package/content/skills/triage-spike-findings/SKILL.md +31 -12
  60. package/content/skills/typescript-testing-conventions/SKILL.md +40 -0
  61. package/content/subagents/_data/claude.yaml +3 -0
  62. package/content/subagents/code-health-assessor.md +4 -4
  63. package/content/subagents/disposition-challenger.md +3 -4
  64. package/content/subagents/entry-drafter.md +2 -2
  65. package/content/subagents/handoff-reviewer.md +1 -1
  66. package/content/subagents/prototype-builder.md +69 -0
  67. package/content/subagents/usability-assessor.md +1 -1
  68. package/package.json +5 -4
  69. package/schemas/preferences.v1.json +1 -1
  70. package/schemas/work-types.v1.json +1 -1
  71. package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +0 -4
@@ -1,4 +1,310 @@
1
1
  [
2
+ {
3
+ "version": "0.6.0",
4
+ "date": "2026-11-09",
5
+ "sections": [
6
+ {
7
+ "title": "🎉 Features",
8
+ "audience": "all",
9
+ "items": [
10
+ {
11
+ "description": "Adds the `analyze-performance` skill, which measures each page of a site for mobile and desktop through the PageSpeed Insights API or the Lighthouse CLI, reports field data from real users apart from lab data, and writes a `performance-findings` artifact that ranks improvements by expected effect, with the evidence, the metric, and the effort of each. (#5)",
12
+ "hash": "ebcf89f2442d1f44cc5de53aea0b31fa3efaf54e",
13
+ "entry": 1
14
+ },
15
+ {
16
+ "description": "Lets `triage-spike-findings` take a `performance-findings` artifact as input, so that it can create tickets for the improvements that `analyze-performance` ranks. (#5)",
17
+ "hash": "ebcf89f2442d1f44cc5de53aea0b31fa3efaf54e",
18
+ "entry": 2
19
+ },
20
+ {
21
+ "description": "Adds the `dead-code`, `duplication`, and `dependency-graph` sensors to `assess-code-health`'s `sense` command, which runs knip, jscpd, and dependency-cruiser on every invocation and limits their rows to the unit's tracked, non-excluded files. (#92)",
22
+ "hash": "0ff4ae50d9a9bce4cdac85e7d4f0dc6bdb7c67c3",
23
+ "entry": 1
24
+ },
25
+ {
26
+ "description": "Adds an `importers` count to each hotspot row in the sense document, taken from the dependency graph and null when the graph does not list the file. (#92)",
27
+ "hash": "0ff4ae50d9a9bce4cdac85e7d4f0dc6bdb7c67c3",
28
+ "entry": 2
29
+ },
30
+ {
31
+ "description": "Adds an \"Unexpected crashes\" section to the `cli-conventions` rulebook, which directs a tool to report a crash as `<bin>: internal error: <message>` followed by the stack frames, printed without a debug flag, and to exit 1, so that a reader can tell a bug in the tool from a handled error. (#94)",
32
+ "hash": "8503764bac043917d2556a8fef220a94ee3897f0",
33
+ "entry": 1
34
+ },
35
+ {
36
+ "description": "Adds the `machine-readable-output-conventions` rulebook, delivered as the `consult-machine-readable-output-conventions` skill, which requires a result shown to a person to be available as structured data rendered from the same object and states rules for canonical values, data embedded in a page, redaction of sensitive fields, and a journal of domain events. (#103)",
37
+ "hash": "69e953bbdb62cff9260ef19601300ce8f98310b9",
38
+ "entry": 1
39
+ },
40
+ {
41
+ "description": "Adds `machine-readable-output-conventions` to the `recommended` collection, which deploys it to every project that declares the collection. (#103)",
42
+ "hash": "69e953bbdb62cff9260ef19601300ce8f98310b9",
43
+ "entry": 2
44
+ },
45
+ {
46
+ "description": "Adds a \"Time-driven behavior\" section to the `testing-conventions` skill, which directs a test author to fake the clock and advance it explicitly, to wait on a condition with a deadline when the timer runs in another process, and to run a changed test repeatedly under CPU load before committing it. (#107)",
47
+ "hash": "3fc483b3011481c0dd099991d90f63a7d54b196c",
48
+ "entry": 1
49
+ },
50
+ {
51
+ "description": "Adds a matching \"Time-driven behavior\" section to `typescript-testing-conventions`, which shows a fake-timer Vitest test that moves time with `vi.advanceTimersByTimeAsync` and describes how to run several copies of `vitest run <file> --repeats <n>` at once to put the machine under CPU load. (#107)",
52
+ "hash": "3fc483b3011481c0dd099991d90f63a7d54b196c",
53
+ "entry": 2
54
+ },
55
+ {
56
+ "description": "Adds a \"Findings batches\" section to `spike-conventions.md`, which caps a triage batch at 10 items, gives each batch a ticket of its own, and shapes an assessment of several units as an umbrella with one child per unit, each blocked by the one before it. (#108)",
57
+ "hash": "eeb7aa01958ab2f763d2e9b4efc9a520c8b42310",
58
+ "entry": 1
59
+ },
60
+ {
61
+ "description": "Limits `triage-spike-findings` to one batch per triage ticket and has it create a follow-up triage ticket for each later batch, each blocked by the one before it and linked back to the triage ticket, so that every item still receives a disposition. (#108)",
62
+ "hash": "eeb7aa01958ab2f763d2e9b4efc9a520c8b42310",
63
+ "entry": 2
64
+ },
65
+ {
66
+ "description": "Lowers the default per-lens proposal cap of `assess-code-health` from 10 to 2, so that its five lenses produce at most 10 proposals for one unit. (#108)",
67
+ "hash": "eeb7aa01958ab2f763d2e9b4efc9a520c8b42310",
68
+ "entry": 3
69
+ },
70
+ {
71
+ "description": "Directs `plan`, `design-and-plan`, and `create-ticket` to scope a ticket or task that schedules an assessment or a triage of findings to one batch. (#108)",
72
+ "hash": "eeb7aa01958ab2f763d2e9b4efc9a520c8b42310",
73
+ "entry": 4
74
+ },
75
+ {
76
+ "description": "Changes the grade definitions shared by `triage-spike-findings` and `disposition-challenger` to grade an item from `assess-code-health` by the code that the change leaves, so that the one-time cost of the change no longer lowers the item's confidence or value. (#109)",
77
+ "hash": "0c1125ecd3660586c7341971cb4e1a04ec6a8228",
78
+ "entry": 1
79
+ },
80
+ {
81
+ "description": "Adds a working-directory argument to `create-commit`, which runs every git call, the ticket-ref lookup, and the title rendering against that worktree. (#110)",
82
+ "hash": "8b60780756d5a14cf70049ced34be9a45400a0eb",
83
+ "entry": 2
84
+ },
85
+ {
86
+ "description": "Adds a rule to `williamthorsen-workflow-preferences` that directs a session working in a worktree other than its cwd to pass that worktree to every skill that takes a working directory, or to commit inline with `git -C`. (#110)",
87
+ "hash": "8b60780756d5a14cf70049ced34be9a45400a0eb",
88
+ "entry": 3
89
+ },
90
+ {
91
+ "description": "Adds a \"TypeScript packages\" section to the `machine-readable-output-conventions` rulebook that names `@williamthorsen/readout`, `@williamthorsen/readout-journal`, and `@williamthorsen/readout-react` and the rules that each one implements, and states that the rules remain the contract whether or not an implementation uses them. (#113)",
92
+ "hash": "94412886b892a3a88828a718036fc1dc95dba60e",
93
+ "entry": 1
94
+ },
95
+ {
96
+ "description": "Adds a \"Machine-readable results\" section to the `williamthorsen-typescript-preferences` rulebook that directs an agent to build a result or a journal on the readout packages rather than by hand. (#113)",
97
+ "hash": "94412886b892a3a88828a718036fc1dc95dba60e",
98
+ "entry": 2
99
+ },
100
+ {
101
+ "description": "Adds a `--resweep` flag to `revise-prose`, which dispatches every versioned rule to every file whatever coverage `.agents/revise-prose.yaml` records, while recorded rejections still suppress their sites. (#114)",
102
+ "hash": "3a381d5f95de6d0792d40b995f723922fc52ac43",
103
+ "entry": 1
104
+ },
105
+ {
106
+ "description": "Adds the optional `provenance.parent` field to plan provenance, which `refine-plan` sets on every revised plan to the file name, without its directory, of the plan that it revised. (#117)",
107
+ "hash": "c0feb049f62fc602e2acfab801941ab1408dff14",
108
+ "entry": 1
109
+ },
110
+ {
111
+ "description": "Adds rules to `accessibility-conventions` that have an agent follow the established model that a feature resembles, place a control that opens or closes a region at that region's edge or in a persistent toolbar, and give a toggle a visible on state, an `aria-expanded` or `aria-pressed` attribute, and one label for both states, and adds toggling each toggle to the rulebook's browser check. (#118)",
112
+ "hash": "16d8c010485f374b372390ed149542adf1d11cc6",
113
+ "entry": 1
114
+ },
115
+ {
116
+ "description": "Exempts a toggle from the `ui-copy-conventions` rule that buttons are verbs, since a toggle's label names what it governs and stays the same in both states. (#118)",
117
+ "hash": "16d8c010485f374b372390ed149542adf1d11cc6",
118
+ "entry": 2
119
+ },
120
+ {
121
+ "description": "Has `design-and-plan`, `prepare-prototype-brief`, `refine-prototype`, and the shared plan template apply the new control rules when a design is chosen or a control is added or moved, with any departure from the named model recorded together with its reason. (#118)",
122
+ "hash": "16d8c010485f374b372390ed149542adf1d11cc6",
123
+ "entry": 3
124
+ },
125
+ {
126
+ "description": "Adds a \"Glanceable state\" section to the `accessibility-conventions` rulebook, which requires that a state for which a reader scans a list or table be marked by colour with a second cue, a symbol, grouping, or sort order rather than by text alone, and which states that a restraint on colour never excuses hiding such a state. (#120)",
127
+ "hash": "6d7ecb7fe02aa9c1ca475eb54eaf37c6cf56de8f",
128
+ "entry": 1
129
+ },
130
+ {
131
+ "description": "Adds a rule to `accessibility-conventions` that a button outside a toolbar has a border or fill at rest that meets 3:1 contrast against its surface, and extends the rulebook's browser check to cover this rule and the glanceable-state rule. (#120)",
132
+ "hash": "6d7ecb7fe02aa9c1ca475eb54eaf37c6cf56de8f",
133
+ "entry": 2
134
+ },
135
+ {
136
+ "description": "Names both rules in `prepare-prototype-brief`, `refine-prototype`, and the `usability-assessor` subagent, names the glanceable-state rule in `review-criteria` and the plan template's interface guidance, and adds a criterion to the judging section of every prototype brief that treats a list whose items must each be read to find a scanned state as a defect. (#120)",
137
+ "hash": "6d7ecb7fe02aa9c1ca475eb54eaf37c6cf56de8f",
138
+ "entry": 3
139
+ },
140
+ {
141
+ "description": "Adds the `prototype-builder` subagent, which builds one prototype for one lens of a brief and checks its page in a headless Playwright browser apart from the dispatching session's, and makes `prepare-prototype-brief` and `index-prototypes` dispatch it for each prototype that a subagent builds. (#126)",
142
+ "hash": "d66d565798e91ed3e6db2984022c92a9452165df",
143
+ "entry": 1
144
+ },
145
+ {
146
+ "description": "Adds the `index-prototypes probe-targets --endpoint <url>` command, which closes each page target of a browser's DevTools endpoint that does not answer a probe within 5 seconds, and directs `index-prototypes` to run it when a Playwright call times out and to report each closed page's prototype as defective. (#126)",
147
+ "hash": "d66d565798e91ed3e6db2984022c92a9452165df",
148
+ "entry": 3
149
+ },
150
+ {
151
+ "description": "Makes the brief composed by `prepare-prototype-brief` require every iterative loop in a prototype, such as an animation or a retry, to stop after a fixed number of iterations or a time limit, because a loop that does not end hangs the page's renderer. (#126)",
152
+ "hash": "d66d565798e91ed3e6db2984022c92a9452165df",
153
+ "entry": 4
154
+ },
155
+ {
156
+ "description": "Sets the browser title of the index page to `{set title} - Prototypes` and directs `prototype-builder` and `/refine-prototype` to title each prototype page `{set title} - {id} {title}`, so that a developer judging a round can tell its tabs apart. (#130)",
157
+ "hash": "560c8be1dcc6b9aa0f12c9566eb0388d052aef56",
158
+ "entry": 1
159
+ },
160
+ {
161
+ "description": "Makes the `index-prototypes` helper's `register` command fail with `title-mismatch` when the `--source` page's `<title>` is missing or differs from `{set title} - {id} {title}`, and with `source-not-found` when the source is not a readable file. (#130)",
162
+ "hash": "560c8be1dcc6b9aa0f12c9566eb0388d052aef56",
163
+ "entry": 2
164
+ },
165
+ {
166
+ "description": "Adds the `investigate-spike` skill, which works a spike plan's investigation steps within its timebox, saves the answers and recommendations as a `spike-findings` artifact that `triage-spike-findings` accepts, and offers the closing post on the ticket. (#132)",
167
+ "hash": "5e37d0d5f6007091f076337bf9628d1a12809881",
168
+ "entry": 1
169
+ },
170
+ {
171
+ "description": "Changes the post-plan menu's 🔬 Investigate option, which previously left the agent to work a spike plan without a skill, to invoke `investigate-spike` with the plan and the ticket. (#132)",
172
+ "hash": "5e37d0d5f6007091f076337bf9628d1a12809881",
173
+ "entry": 2
174
+ },
175
+ {
176
+ "description": "Adds the `start-ticket` skill, which chooses the skill that opens the work in a ticket's worktree (such as `design-and-plan`, `plan`, `refine-plan`, `implement-plan`, `investigate-spike`, or `triage-spike-findings`) from the ticket's state, its pull request, and its saved artifacts, and then invokes that skill. (#134)",
177
+ "hash": "5068d3fb2d372d13d5a883d5b6fe6c28fd9223b0",
178
+ "entry": 1
179
+ },
180
+ {
181
+ "description": "Changes the launch prompts of a plan-time split to invoke `start-ticket` without arguments instead of naming an entry-point skill chosen at split time, so that the choice reflects the piece's artifacts when its session starts. (#134)",
182
+ "hash": "5068d3fb2d372d13d5a883d5b6fe6c28fd9223b0",
183
+ "entry": 2
184
+ },
185
+ {
186
+ "description": "Adds a `start-ticket` line to the completion output of `create-ticket` to show how to start the new ticket in its worktree, and omits the line for a ticket created in another repository. (#134)",
187
+ "hash": "5068d3fb2d372d13d5a883d5b6fe6c28fd9223b0",
188
+ "entry": 3
189
+ },
190
+ {
191
+ "description": "Adds a `## How to test` section to the change summary, in which `summarize-change` lists the steps that a reviewer follows to exercise a changed page, UI component, or command output by hand, and has `create-pr` include that section in the pull-request body. (#140)",
192
+ "hash": "95b535e732b4c7bd50a69f162be1455af808ad0b",
193
+ "entry": 1
194
+ },
195
+ {
196
+ "description": "Adds the `convert-agent-prompt` skill, which converts an agent's prompt file into an agent-logic file, an XState v5 machine config that an agent-logic viewer renders as a statechart, by running version 0.1.0 of the `codeassembly-agent-logic` package through `pnpm dlx`. (#141)",
197
+ "hash": "6549396c7db0e6f7ba2efe9bce1c997b4872066f",
198
+ "entry": 1
199
+ }
200
+ ]
201
+ },
202
+ {
203
+ "title": "🐛 Bug fixes",
204
+ "audience": "all",
205
+ "items": [
206
+ {
207
+ "description": "Fixes the issue that `create-commit` wrote the change itself, in the wrong checkout, when the checkout in which it ran did not contain the change, and makes the skill stop without staging and report the directory and its `git status --short` output instead. (#110)",
208
+ "hash": "8b60780756d5a14cf70049ced34be9a45400a0eb",
209
+ "entry": 1
210
+ },
211
+ {
212
+ "description": "Fixes the issue that `resolve-scopes` resolved every path in a root package (`packages: ['.']` in `pnpm-workspace.yaml`) to the checkout directory's name, such as `app` or `app.106`, rather than to `root`, while nested packages keep their own scopes. (#111)",
213
+ "hash": "949cd390c6a84eb0c54219443faa218ce257ed05",
214
+ "entry": 1
215
+ },
216
+ {
217
+ "description": "Fixes the issue that a `project.scopes` entry naming the repository root without a `name` took the checkout directory's name as its scope, by making `resolve-scopes` skip such an entry with a warning and keep reading one that declares a `name`. (#111)",
218
+ "hash": "949cd390c6a84eb0c54219443faa218ce257ed05",
219
+ "entry": 2
220
+ },
221
+ {
222
+ "description": "Fixes the issue that rulebooks and skills such as the collaboration preferences, the writing preferences, the content specification, `review-branch`, and `action-items.md` still contained cleft constructions, figurative verbs, and overused words forbidden by the plain-speech rule, and bumps the three rulebooks to versions 17, 12, and 33 without changing what they direct. (#114)",
223
+ "hash": "3a381d5f95de6d0792d40b995f723922fc52ac43",
224
+ "entry": 2
225
+ },
226
+ {
227
+ "description": "Fixes the issue that skills and subagents that resolved a ticket read its body and skipped its comments, on GitHub, on Jira, and for a ticket artifact whose frontmatter names a `ticket_ref`. (#121)",
228
+ "hash": "3d2438ea27a1e00e36a4a15d7fbea250db9f98f2",
229
+ "entry": 1
230
+ },
231
+ {
232
+ "description": "Fixes the issue that `prepare-prototype-brief` dispatched every builder at once, so that one page that hung its renderer stalled the browser calls of every builder; the skill now dispatches builders one at a time and stops a builder that has not replied 30 minutes after its dispatch. (#126)",
233
+ "hash": "d66d565798e91ed3e6db2984022c92a9452165df",
234
+ "entry": 2
235
+ },
236
+ {
237
+ "description": "Fixes the issue that `assess-code-health` dropped each proposal whose change creates a file, by limiting `paths` in `code-health-assessor` to files that exist at assessment time and directing the assessor to name a created file in `change`. (#131)",
238
+ "hash": "057967a61ca0b1cd25fd1e39ae7a02082ab5184f",
239
+ "entry": 1
240
+ },
241
+ {
242
+ "description": "Fixes the issue that `assess-code-health`, `assess-usability`, and `investigate-spike` offered a spike's closing post before the `triage-spike-findings` round, when the post could not yet answer the ticket's decisions to enable. (#133)",
243
+ "hash": "8e77b7c4de59a0010fe8991d930fde247eb6ba62",
244
+ "entry": 1
245
+ },
246
+ {
247
+ "description": "Fixes the issue that `triage-spike-findings` never offered the closing post, although its round ends the spike when the findings leave items to triage. (#133)",
248
+ "hash": "8e77b7c4de59a0010fe8991d930fde247eb6ba62",
249
+ "entry": 2
250
+ },
251
+ {
252
+ "description": "Fixes the issue that the Rovo harness's `AGENTS.md` included a personal interaction preference, which forbade `ask_user_questions`, in the guidance that every Rovo user received. (#136)",
253
+ "hash": "a2d9af1de691ec1acff5c5f05a8d7b9e59c814b5",
254
+ "entry": 1
255
+ },
256
+ {
257
+ "description": "Fixes the issue that the rule against interactive selectors in `williamthorsen-collaboration-preferences` did not name the tools that present those selectors, by naming Claude Code's `AskUserQuestion` and Rovo's `ask_user_questions`. (#136)",
258
+ "hash": "a2d9af1de691ec1acff5c5f05a8d7b9e59c814b5",
259
+ "entry": 2
260
+ },
261
+ {
262
+ "description": "Fixes the issue that `assess-code-health.mjs sense` reported a `dead-code` unused-dependency row for a `package.json` matched by an `--exclude` glob, although every other sensor drops the paths that an `--exclude` glob matches. (#138)",
263
+ "hash": "9500a54327a69f09be08525c1f3e5709ce99c73d",
264
+ "entry": 1
265
+ }
266
+ ]
267
+ },
268
+ {
269
+ "title": "♻️ Refactoring",
270
+ "audience": "dev",
271
+ "items": [
272
+ {
273
+ "description": "Moves the CrUX field-data logic of the `analyze-performance` helper (`collectField` and the CrUX API queries that it makes) from `collect.ts` into a new `field.ts` module, which brings `collect.ts` under the 300-line `max-lines` limit. (#91)",
274
+ "hash": "c8da606ebe9e908d5f54f119b4d06f391d21d1a3",
275
+ "entry": 1
276
+ }
277
+ ]
278
+ },
279
+ {
280
+ "title": "🧪 Tests",
281
+ "audience": "dev",
282
+ "items": [
283
+ {
284
+ "description": "Adds the `makeScratchDir` test helper and replaces the direct `mkdtemp` calls and hand-written teardown in the tests of `packages/guidance` and in the repo-root `codeassembly-sync-live` test with it or with `createTempTree` and `disposeOnTestFinished`, which remove each scratch directory when its test finishes, failure included. (#123)",
285
+ "hash": "c6ab9113eded09aea72ce8affad9e26e090d2d88",
286
+ "entry": 1
287
+ },
288
+ {
289
+ "description": "Makes the smoke-test runner in `scripts/__tests__/smoke-test-skill-helpers.ts` remove the fixture directories that its builders create through the new `makeSmokeScratchDir`, whether the smoke tests pass, fail, or a builder throws. (#123)",
290
+ "hash": "c6ab9113eded09aea72ce8affad9e26e090d2d88",
291
+ "entry": 2
292
+ }
293
+ ]
294
+ },
295
+ {
296
+ "title": "📦 Dependencies",
297
+ "audience": "dev",
298
+ "items": [
299
+ {
300
+ "description": "Upgrade eslint-config-typescript to 20.2.0 (#98)",
301
+ "body": "Upgrades `@williamthorsen/eslint-config-typescript` from 20.1.3 to 20.2.0, which updates `eslint-plugin-unicorn` from 78 to 79, and edits the guidance package's sources and tests to pass the two rules that now report code accepted by 20.1.3: `unicorn/numeric-separators-style`, which no longer allows a separator in a number of fewer than 5 digits, and `unicorn/prefer-smaller-scope`.",
302
+ "hash": "24084122b518b38df84c7f063d49193b66669efc"
303
+ }
304
+ ]
305
+ }
306
+ ]
307
+ },
2
308
  {
3
309
  "version": "0.5.0",
4
310
  "date": "2026-11-02",
package/CHANGELOG.md CHANGED
@@ -2,6 +2,79 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file.
4
4
 
5
+ ## 0.6.0 — 2026-11-09
6
+
7
+ ### 🎉 Features
8
+
9
+ - Adds the `analyze-performance` skill, which measures each page of a site for mobile and desktop through the PageSpeed Insights API or the Lighthouse CLI, reports field data from real users apart from lab data, and writes a `performance-findings` artifact that ranks improvements by expected effect, with the evidence, the metric, and the effort of each. (#5)
10
+ - Lets `triage-spike-findings` take a `performance-findings` artifact as input, so that it can create tickets for the improvements that `analyze-performance` ranks. (#5)
11
+ - Adds the `dead-code`, `duplication`, and `dependency-graph` sensors to `assess-code-health`'s `sense` command, which runs knip, jscpd, and dependency-cruiser on every invocation and limits their rows to the unit's tracked, non-excluded files. (#92)
12
+ - Adds an `importers` count to each hotspot row in the sense document, taken from the dependency graph and null when the graph does not list the file. (#92)
13
+ - Adds an "Unexpected crashes" section to the `cli-conventions` rulebook, which directs a tool to report a crash as `<bin>: internal error: <message>` followed by the stack frames, printed without a debug flag, and to exit 1, so that a reader can tell a bug in the tool from a handled error. (#94)
14
+ - Adds the `machine-readable-output-conventions` rulebook, delivered as the `consult-machine-readable-output-conventions` skill, which requires a result shown to a person to be available as structured data rendered from the same object and states rules for canonical values, data embedded in a page, redaction of sensitive fields, and a journal of domain events. (#103)
15
+ - Adds `machine-readable-output-conventions` to the `recommended` collection, which deploys it to every project that declares the collection. (#103)
16
+ - Adds a "Time-driven behavior" section to the `testing-conventions` skill, which directs a test author to fake the clock and advance it explicitly, to wait on a condition with a deadline when the timer runs in another process, and to run a changed test repeatedly under CPU load before committing it. (#107)
17
+ - Adds a matching "Time-driven behavior" section to `typescript-testing-conventions`, which shows a fake-timer Vitest test that moves time with `vi.advanceTimersByTimeAsync` and describes how to run several copies of `vitest run <file> --repeats <n>` at once to put the machine under CPU load. (#107)
18
+ - Adds a "Findings batches" section to `spike-conventions.md`, which caps a triage batch at 10 items, gives each batch a ticket of its own, and shapes an assessment of several units as an umbrella with one child per unit, each blocked by the one before it. (#108)
19
+ - Limits `triage-spike-findings` to one batch per triage ticket and has it create a follow-up triage ticket for each later batch, each blocked by the one before it and linked back to the triage ticket, so that every item still receives a disposition. (#108)
20
+ - Lowers the default per-lens proposal cap of `assess-code-health` from 10 to 2, so that its five lenses produce at most 10 proposals for one unit. (#108)
21
+ - Directs `plan`, `design-and-plan`, and `create-ticket` to scope a ticket or task that schedules an assessment or a triage of findings to one batch. (#108)
22
+ - Changes the grade definitions shared by `triage-spike-findings` and `disposition-challenger` to grade an item from `assess-code-health` by the code that the change leaves, so that the one-time cost of the change no longer lowers the item's confidence or value. (#109)
23
+ - Adds a working-directory argument to `create-commit`, which runs every git call, the ticket-ref lookup, and the title rendering against that worktree. (#110)
24
+ - Adds a rule to `williamthorsen-workflow-preferences` that directs a session working in a worktree other than its cwd to pass that worktree to every skill that takes a working directory, or to commit inline with `git -C`. (#110)
25
+ - Adds a "TypeScript packages" section to the `machine-readable-output-conventions` rulebook that names `@williamthorsen/readout`, `@williamthorsen/readout-journal`, and `@williamthorsen/readout-react` and the rules that each one implements, and states that the rules remain the contract whether or not an implementation uses them. (#113)
26
+ - Adds a "Machine-readable results" section to the `williamthorsen-typescript-preferences` rulebook that directs an agent to build a result or a journal on the readout packages rather than by hand. (#113)
27
+ - Adds a `--resweep` flag to `revise-prose`, which dispatches every versioned rule to every file whatever coverage `.agents/revise-prose.yaml` records, while recorded rejections still suppress their sites. (#114)
28
+ - Adds the optional `provenance.parent` field to plan provenance, which `refine-plan` sets on every revised plan to the file name, without its directory, of the plan that it revised. (#117)
29
+ - Adds rules to `accessibility-conventions` that have an agent follow the established model that a feature resembles, place a control that opens or closes a region at that region's edge or in a persistent toolbar, and give a toggle a visible on state, an `aria-expanded` or `aria-pressed` attribute, and one label for both states, and adds toggling each toggle to the rulebook's browser check. (#118)
30
+ - Exempts a toggle from the `ui-copy-conventions` rule that buttons are verbs, since a toggle's label names what it governs and stays the same in both states. (#118)
31
+ - Has `design-and-plan`, `prepare-prototype-brief`, `refine-prototype`, and the shared plan template apply the new control rules when a design is chosen or a control is added or moved, with any departure from the named model recorded together with its reason. (#118)
32
+ - Adds a "Glanceable state" section to the `accessibility-conventions` rulebook, which requires that a state for which a reader scans a list or table be marked by colour with a second cue, a symbol, grouping, or sort order rather than by text alone, and which states that a restraint on colour never excuses hiding such a state. (#120)
33
+ - Adds a rule to `accessibility-conventions` that a button outside a toolbar has a border or fill at rest that meets 3:1 contrast against its surface, and extends the rulebook's browser check to cover this rule and the glanceable-state rule. (#120)
34
+ - Names both rules in `prepare-prototype-brief`, `refine-prototype`, and the `usability-assessor` subagent, names the glanceable-state rule in `review-criteria` and the plan template's interface guidance, and adds a criterion to the judging section of every prototype brief that treats a list whose items must each be read to find a scanned state as a defect. (#120)
35
+ - Adds the `prototype-builder` subagent, which builds one prototype for one lens of a brief and checks its page in a headless Playwright browser apart from the dispatching session's, and makes `prepare-prototype-brief` and `index-prototypes` dispatch it for each prototype that a subagent builds. (#126)
36
+ - Adds the `index-prototypes probe-targets --endpoint <url>` command, which closes each page target of a browser's DevTools endpoint that does not answer a probe within 5 seconds, and directs `index-prototypes` to run it when a Playwright call times out and to report each closed page's prototype as defective. (#126)
37
+ - Makes the brief composed by `prepare-prototype-brief` require every iterative loop in a prototype, such as an animation or a retry, to stop after a fixed number of iterations or a time limit, because a loop that does not end hangs the page's renderer. (#126)
38
+ - Sets the browser title of the index page to `{set title} - Prototypes` and directs `prototype-builder` and `/refine-prototype` to title each prototype page `{set title} - {id} {title}`, so that a developer judging a round can tell its tabs apart. (#130)
39
+ - Makes the `index-prototypes` helper's `register` command fail with `title-mismatch` when the `--source` page's `<title>` is missing or differs from `{set title} - {id} {title}`, and with `source-not-found` when the source is not a readable file. (#130)
40
+ - Adds the `investigate-spike` skill, which works a spike plan's investigation steps within its timebox, saves the answers and recommendations as a `spike-findings` artifact that `triage-spike-findings` accepts, and offers the closing post on the ticket. (#132)
41
+ - Changes the post-plan menu's 🔬 Investigate option, which previously left the agent to work a spike plan without a skill, to invoke `investigate-spike` with the plan and the ticket. (#132)
42
+ - Adds the `start-ticket` skill, which chooses the skill that opens the work in a ticket's worktree (such as `design-and-plan`, `plan`, `refine-plan`, `implement-plan`, `investigate-spike`, or `triage-spike-findings`) from the ticket's state, its pull request, and its saved artifacts, and then invokes that skill. (#134)
43
+ - Changes the launch prompts of a plan-time split to invoke `start-ticket` without arguments instead of naming an entry-point skill chosen at split time, so that the choice reflects the piece's artifacts when its session starts. (#134)
44
+ - Adds a `start-ticket` line to the completion output of `create-ticket` to show how to start the new ticket in its worktree, and omits the line for a ticket created in another repository. (#134)
45
+ - Adds a `## How to test` section to the change summary, in which `summarize-change` lists the steps that a reviewer follows to exercise a changed page, UI component, or command output by hand, and has `create-pr` include that section in the pull-request body. (#140)
46
+ - Adds the `convert-agent-prompt` skill, which converts an agent's prompt file into an agent-logic file, an XState v5 machine config that an agent-logic viewer renders as a statechart, by running version 0.1.0 of the `codeassembly-agent-logic` package through `pnpm dlx`. (#141)
47
+
48
+ ### 🐛 Bug fixes
49
+
50
+ - Fixes the issue that `create-commit` wrote the change itself, in the wrong checkout, when the checkout in which it ran did not contain the change, and makes the skill stop without staging and report the directory and its `git status --short` output instead. (#110)
51
+ - Fixes the issue that `resolve-scopes` resolved every path in a root package (`packages: ['.']` in `pnpm-workspace.yaml`) to the checkout directory's name, such as `app` or `app.106`, rather than to `root`, while nested packages keep their own scopes. (#111)
52
+ - Fixes the issue that a `project.scopes` entry naming the repository root without a `name` took the checkout directory's name as its scope, by making `resolve-scopes` skip such an entry with a warning and keep reading one that declares a `name`. (#111)
53
+ - Fixes the issue that rulebooks and skills such as the collaboration preferences, the writing preferences, the content specification, `review-branch`, and `action-items.md` still contained cleft constructions, figurative verbs, and overused words forbidden by the plain-speech rule, and bumps the three rulebooks to versions 17, 12, and 33 without changing what they direct. (#114)
54
+ - Fixes the issue that skills and subagents that resolved a ticket read its body and skipped its comments, on GitHub, on Jira, and for a ticket artifact whose frontmatter names a `ticket_ref`. (#121)
55
+ - Fixes the issue that `prepare-prototype-brief` dispatched every builder at once, so that one page that hung its renderer stalled the browser calls of every builder; the skill now dispatches builders one at a time and stops a builder that has not replied 30 minutes after its dispatch. (#126)
56
+ - Fixes the issue that `assess-code-health` dropped each proposal whose change creates a file, by limiting `paths` in `code-health-assessor` to files that exist at assessment time and directing the assessor to name a created file in `change`. (#131)
57
+ - Fixes the issue that `assess-code-health`, `assess-usability`, and `investigate-spike` offered a spike's closing post before the `triage-spike-findings` round, when the post could not yet answer the ticket's decisions to enable. (#133)
58
+ - Fixes the issue that `triage-spike-findings` never offered the closing post, although its round ends the spike when the findings leave items to triage. (#133)
59
+ - Fixes the issue that the Rovo harness's `AGENTS.md` included a personal interaction preference, which forbade `ask_user_questions`, in the guidance that every Rovo user received. (#136)
60
+ - Fixes the issue that the rule against interactive selectors in `williamthorsen-collaboration-preferences` did not name the tools that present those selectors, by naming Claude Code's `AskUserQuestion` and Rovo's `ask_user_questions`. (#136)
61
+ - Fixes the issue that `assess-code-health.mjs sense` reported a `dead-code` unused-dependency row for a `package.json` matched by an `--exclude` glob, although every other sensor drops the paths that an `--exclude` glob matches. (#138)
62
+
63
+ ### ♻️ Refactoring
64
+
65
+ - Moves the CrUX field-data logic of the `analyze-performance` helper (`collectField` and the CrUX API queries that it makes) from `collect.ts` into a new `field.ts` module, which brings `collect.ts` under the 300-line `max-lines` limit. (#91)
66
+
67
+ ### 🧪 Tests
68
+
69
+ - Adds the `makeScratchDir` test helper and replaces the direct `mkdtemp` calls and hand-written teardown in the tests of `packages/guidance` and in the repo-root `codeassembly-sync-live` test with it or with `createTempTree` and `disposeOnTestFinished`, which remove each scratch directory when its test finishes, failure included. (#123)
70
+ - Makes the smoke-test runner in `scripts/__tests__/smoke-test-skill-helpers.ts` remove the fixture directories that its builders create through the new `makeSmokeScratchDir`, whether the smoke tests pass, fail, or a builder throws. (#123)
71
+
72
+ ### 📦 Dependencies
73
+
74
+ - Upgrade eslint-config-typescript to 20.2.0 (#98)
75
+
76
+ Upgrades `@williamthorsen/eslint-config-typescript` from 20.1.3 to 20.2.0, which updates `eslint-plugin-unicorn` from 78 to 79, and edits the guidance package's sources and tests to pass the two rules that now report code accepted by 20.1.3: `unicorn/numeric-separators-style`, which no longer allows a separator in a number of fewer than 5 digits, and `unicorn/prefer-smaller-scope`.
77
+
5
78
  ## 0.5.0 — 2026-11-02
6
79
 
7
80
  ### 🎉 Features
package/README.md CHANGED
@@ -5,13 +5,63 @@
5
5
  The CodeAssembly library of agent guidance: rulebooks, skills, and subagents for coding harnesses, which the [`codeassembly`](https://github.com/williamthorsen/codeassembly/blob/main/packages/agents/README.md) CLI deploys into Claude Code and Rovo Dev.
6
6
 
7
7
  <!-- section:release-notes -->
8
- ## Release notes — v0.5.0 (2026-11-02)
8
+ ## Release notes — v0.6.0 (2026-11-09)
9
9
 
10
10
  ### 🎉 Features
11
11
 
12
- - Adds rules to the `shared-data-conventions` rulebook stating that an agent's verdict that decides a write to shared state includes evidence that a script checks before the write, and that a skill writing to shared state runs against the real data before merge, stopping at its approval checkpoint or in a dry run. (#2245)
13
- - Extends the data-change guidance in `create-ticket`, `design-and-plan`, `plan`, and `align-ticket-with-implementation` to require an acceptance criterion for the evidence check and a `## Verification` step that runs the skill against the real data without writing. (#2245)
14
- - Adds a "Judged writes" check to `plan-reviewer`, which reports a plan for a skill that writes to shared state when the plan does not run the skill against the real data before merge or does not name the script that checks a verdict's evidence. (#2245)
12
+ - Adds the `analyze-performance` skill, which measures each page of a site for mobile and desktop through the PageSpeed Insights API or the Lighthouse CLI, reports field data from real users apart from lab data, and writes a `performance-findings` artifact that ranks improvements by expected effect, with the evidence, the metric, and the effort of each. (#5)
13
+ - Lets `triage-spike-findings` take a `performance-findings` artifact as input, so that it can create tickets for the improvements that `analyze-performance` ranks. (#5)
14
+ - Adds the `dead-code`, `duplication`, and `dependency-graph` sensors to `assess-code-health`'s `sense` command, which runs knip, jscpd, and dependency-cruiser on every invocation and limits their rows to the unit's tracked, non-excluded files. (#92)
15
+ - Adds an `importers` count to each hotspot row in the sense document, taken from the dependency graph and null when the graph does not list the file. (#92)
16
+ - Adds an "Unexpected crashes" section to the `cli-conventions` rulebook, which directs a tool to report a crash as `<bin>: internal error: <message>` followed by the stack frames, printed without a debug flag, and to exit 1, so that a reader can tell a bug in the tool from a handled error. (#94)
17
+ - Adds the `machine-readable-output-conventions` rulebook, delivered as the `consult-machine-readable-output-conventions` skill, which requires a result shown to a person to be available as structured data rendered from the same object and states rules for canonical values, data embedded in a page, redaction of sensitive fields, and a journal of domain events. (#103)
18
+ - Adds `machine-readable-output-conventions` to the `recommended` collection, which deploys it to every project that declares the collection. (#103)
19
+ - Adds a "Time-driven behavior" section to the `testing-conventions` skill, which directs a test author to fake the clock and advance it explicitly, to wait on a condition with a deadline when the timer runs in another process, and to run a changed test repeatedly under CPU load before committing it. (#107)
20
+ - Adds a matching "Time-driven behavior" section to `typescript-testing-conventions`, which shows a fake-timer Vitest test that moves time with `vi.advanceTimersByTimeAsync` and describes how to run several copies of `vitest run <file> --repeats <n>` at once to put the machine under CPU load. (#107)
21
+ - Adds a "Findings batches" section to `spike-conventions.md`, which caps a triage batch at 10 items, gives each batch a ticket of its own, and shapes an assessment of several units as an umbrella with one child per unit, each blocked by the one before it. (#108)
22
+ - Limits `triage-spike-findings` to one batch per triage ticket and has it create a follow-up triage ticket for each later batch, each blocked by the one before it and linked back to the triage ticket, so that every item still receives a disposition. (#108)
23
+ - Lowers the default per-lens proposal cap of `assess-code-health` from 10 to 2, so that its five lenses produce at most 10 proposals for one unit. (#108)
24
+ - Directs `plan`, `design-and-plan`, and `create-ticket` to scope a ticket or task that schedules an assessment or a triage of findings to one batch. (#108)
25
+ - Changes the grade definitions shared by `triage-spike-findings` and `disposition-challenger` to grade an item from `assess-code-health` by the code that the change leaves, so that the one-time cost of the change no longer lowers the item's confidence or value. (#109)
26
+ - Adds a working-directory argument to `create-commit`, which runs every git call, the ticket-ref lookup, and the title rendering against that worktree. (#110)
27
+ - Adds a rule to `williamthorsen-workflow-preferences` that directs a session working in a worktree other than its cwd to pass that worktree to every skill that takes a working directory, or to commit inline with `git -C`. (#110)
28
+ - Adds a "TypeScript packages" section to the `machine-readable-output-conventions` rulebook that names `@williamthorsen/readout`, `@williamthorsen/readout-journal`, and `@williamthorsen/readout-react` and the rules that each one implements, and states that the rules remain the contract whether or not an implementation uses them. (#113)
29
+ - Adds a "Machine-readable results" section to the `williamthorsen-typescript-preferences` rulebook that directs an agent to build a result or a journal on the readout packages rather than by hand. (#113)
30
+ - Adds a `--resweep` flag to `revise-prose`, which dispatches every versioned rule to every file whatever coverage `.agents/revise-prose.yaml` records, while recorded rejections still suppress their sites. (#114)
31
+ - Adds the optional `provenance.parent` field to plan provenance, which `refine-plan` sets on every revised plan to the file name, without its directory, of the plan that it revised. (#117)
32
+ - Adds rules to `accessibility-conventions` that have an agent follow the established model that a feature resembles, place a control that opens or closes a region at that region's edge or in a persistent toolbar, and give a toggle a visible on state, an `aria-expanded` or `aria-pressed` attribute, and one label for both states, and adds toggling each toggle to the rulebook's browser check. (#118)
33
+ - Exempts a toggle from the `ui-copy-conventions` rule that buttons are verbs, since a toggle's label names what it governs and stays the same in both states. (#118)
34
+ - Has `design-and-plan`, `prepare-prototype-brief`, `refine-prototype`, and the shared plan template apply the new control rules when a design is chosen or a control is added or moved, with any departure from the named model recorded together with its reason. (#118)
35
+ - Adds a "Glanceable state" section to the `accessibility-conventions` rulebook, which requires that a state for which a reader scans a list or table be marked by colour with a second cue, a symbol, grouping, or sort order rather than by text alone, and which states that a restraint on colour never excuses hiding such a state. (#120)
36
+ - Adds a rule to `accessibility-conventions` that a button outside a toolbar has a border or fill at rest that meets 3:1 contrast against its surface, and extends the rulebook's browser check to cover this rule and the glanceable-state rule. (#120)
37
+ - Names both rules in `prepare-prototype-brief`, `refine-prototype`, and the `usability-assessor` subagent, names the glanceable-state rule in `review-criteria` and the plan template's interface guidance, and adds a criterion to the judging section of every prototype brief that treats a list whose items must each be read to find a scanned state as a defect. (#120)
38
+ - Adds the `prototype-builder` subagent, which builds one prototype for one lens of a brief and checks its page in a headless Playwright browser apart from the dispatching session's, and makes `prepare-prototype-brief` and `index-prototypes` dispatch it for each prototype that a subagent builds. (#126)
39
+ - Adds the `index-prototypes probe-targets --endpoint <url>` command, which closes each page target of a browser's DevTools endpoint that does not answer a probe within 5 seconds, and directs `index-prototypes` to run it when a Playwright call times out and to report each closed page's prototype as defective. (#126)
40
+ - Makes the brief composed by `prepare-prototype-brief` require every iterative loop in a prototype, such as an animation or a retry, to stop after a fixed number of iterations or a time limit, because a loop that does not end hangs the page's renderer. (#126)
41
+ - Sets the browser title of the index page to `{set title} - Prototypes` and directs `prototype-builder` and `/refine-prototype` to title each prototype page `{set title} - {id} {title}`, so that a developer judging a round can tell its tabs apart. (#130)
42
+ - Makes the `index-prototypes` helper's `register` command fail with `title-mismatch` when the `--source` page's `<title>` is missing or differs from `{set title} - {id} {title}`, and with `source-not-found` when the source is not a readable file. (#130)
43
+ - Adds the `investigate-spike` skill, which works a spike plan's investigation steps within its timebox, saves the answers and recommendations as a `spike-findings` artifact that `triage-spike-findings` accepts, and offers the closing post on the ticket. (#132)
44
+ - Changes the post-plan menu's 🔬 Investigate option, which previously left the agent to work a spike plan without a skill, to invoke `investigate-spike` with the plan and the ticket. (#132)
45
+ - Adds the `start-ticket` skill, which chooses the skill that opens the work in a ticket's worktree (such as `design-and-plan`, `plan`, `refine-plan`, `implement-plan`, `investigate-spike`, or `triage-spike-findings`) from the ticket's state, its pull request, and its saved artifacts, and then invokes that skill. (#134)
46
+ - Changes the launch prompts of a plan-time split to invoke `start-ticket` without arguments instead of naming an entry-point skill chosen at split time, so that the choice reflects the piece's artifacts when its session starts. (#134)
47
+ - Adds a `start-ticket` line to the completion output of `create-ticket` to show how to start the new ticket in its worktree, and omits the line for a ticket created in another repository. (#134)
48
+ - Adds a `## How to test` section to the change summary, in which `summarize-change` lists the steps that a reviewer follows to exercise a changed page, UI component, or command output by hand, and has `create-pr` include that section in the pull-request body. (#140)
49
+ - Adds the `convert-agent-prompt` skill, which converts an agent's prompt file into an agent-logic file, an XState v5 machine config that an agent-logic viewer renders as a statechart, by running version 0.1.0 of the `codeassembly-agent-logic` package through `pnpm dlx`. (#141)
50
+
51
+ ### 🐛 Bug fixes
52
+
53
+ - Fixes the issue that `create-commit` wrote the change itself, in the wrong checkout, when the checkout in which it ran did not contain the change, and makes the skill stop without staging and report the directory and its `git status --short` output instead. (#110)
54
+ - Fixes the issue that `resolve-scopes` resolved every path in a root package (`packages: ['.']` in `pnpm-workspace.yaml`) to the checkout directory's name, such as `app` or `app.106`, rather than to `root`, while nested packages keep their own scopes. (#111)
55
+ - Fixes the issue that a `project.scopes` entry naming the repository root without a `name` took the checkout directory's name as its scope, by making `resolve-scopes` skip such an entry with a warning and keep reading one that declares a `name`. (#111)
56
+ - Fixes the issue that rulebooks and skills such as the collaboration preferences, the writing preferences, the content specification, `review-branch`, and `action-items.md` still contained cleft constructions, figurative verbs, and overused words forbidden by the plain-speech rule, and bumps the three rulebooks to versions 17, 12, and 33 without changing what they direct. (#114)
57
+ - Fixes the issue that skills and subagents that resolved a ticket read its body and skipped its comments, on GitHub, on Jira, and for a ticket artifact whose frontmatter names a `ticket_ref`. (#121)
58
+ - Fixes the issue that `prepare-prototype-brief` dispatched every builder at once, so that one page that hung its renderer stalled the browser calls of every builder; the skill now dispatches builders one at a time and stops a builder that has not replied 30 minutes after its dispatch. (#126)
59
+ - Fixes the issue that `assess-code-health` dropped each proposal whose change creates a file, by limiting `paths` in `code-health-assessor` to files that exist at assessment time and directing the assessor to name a created file in `change`. (#131)
60
+ - Fixes the issue that `assess-code-health`, `assess-usability`, and `investigate-spike` offered a spike's closing post before the `triage-spike-findings` round, when the post could not yet answer the ticket's decisions to enable. (#133)
61
+ - Fixes the issue that `triage-spike-findings` never offered the closing post, although its round ends the spike when the findings leave items to triage. (#133)
62
+ - Fixes the issue that the Rovo harness's `AGENTS.md` included a personal interaction preference, which forbade `ask_user_questions`, in the guidance that every Rovo user received. (#136)
63
+ - Fixes the issue that the rule against interactive selectors in `williamthorsen-collaboration-preferences` did not name the tools that present those selectors, by naming Claude Code's `AskUserQuestion` and Rovo's `ask_user_questions`. (#136)
64
+ - Fixes the issue that `assess-code-health.mjs sense` reported a `dead-code` unused-dependency row for a `package.json` matched by an `--exclude` glob, although every other sensor drops the paths that an `--exclude` glob matches. (#138)
15
65
  <!-- /section:release-notes -->
16
66
 
17
67
  ## Using the library
@@ -75,5 +125,6 @@ codeassembly-validate-preferences --strict .agents/preferences.yaml
75
125
  - [Guidance streamlining helper](docs/streamline-guidance-helper.md): the helper that the `streamline-guidance` skill runs.
76
126
  - [Findings triage helper](docs/triage-spike-findings-helper.md): the helper that the `triage-spike-findings` skill runs.
77
127
  - [Code-health helper](docs/assess-code-health-helper.md): the helper that the `assess-code-health` skill runs.
128
+ - [Performance helper](docs/analyze-performance-helper.md): the helper that the `analyze-performance` skill runs.
78
129
  - [Feedback triage helpers](docs/triage-feedback-helper.md): the helpers that the `triage-feedback` skill runs.
79
130
  - [Feedback curation helper](docs/curate-feedback-helper.md): the helper that the `curate-feedback` skill runs.
@@ -0,0 +1,4 @@
1
+ - **Confidence** states advisability: `high` is clearly worth doing, `medium` is worth doing but arguable, `low` is not worth a ticket now. A borderline item takes the lower grade. Only an item graded `high` or `medium` gets a ticket.
2
+ - **Value** states how much the item matters: `must-have`, `should-have`, `nice-to-have`, `questionable`.
3
+
4
+ An item from a code-health assessment, whose findings artifact names `assess-code-health` in its frontmatter `provenance.skill` or has a filename ending in `_code-health-findings.md`, is graded by the code that the change leaves: its conformance, its clarity, and its correctness. The assessment asks how the code would be written afresh today, a state in which the one-time cost of making the change does not exist. That cost is never a ground to lower either grade or to drop the item, whether it is importers or call sites to rewrite, files to move, or imports churned. A small side benefit, such as the little runtime that the change saves, is not a ground either: The item is graded by the code that it leaves. A lasting cost of the end state stays a ground, such as a behavior change that a user sees or the reversal of a design decision that the repository records. Sequencing against in-flight work is a blocker on the item's ticket, not a lower grade. A proposal's `size` is not a cost either: `code-health-assessor` states what it records.
@@ -53,6 +53,8 @@ helpers:
53
53
  out: skills/create-ticket/resolve-ticket-target.mjs
54
54
  - entry: ../src/assess-code-health/cli.ts
55
55
  out: skills/assess-code-health/assess-code-health.mjs
56
+ - entry: ../src/analyze-performance/cli.ts
57
+ out: skills/analyze-performance/analyze-performance.mjs
56
58
  - entry: ../src/curate-feedback/cli.ts
57
59
  out: skills/curate-feedback/curate-feedback.mjs
58
60
  - entry: ../src/lesson-clusters/cli.ts
@@ -8,6 +8,7 @@ members:
8
8
  - cli-conventions
9
9
  - command-output-conventions
10
10
  - generated-content-policy
11
+ - machine-readable-output-conventions
11
12
  - readme-conventions
12
13
  - shared-data-conventions
13
14
  - ui-copy-conventions
@@ -26,16 +27,18 @@ The skills belong here on different grounds. A rulebook of the personal collecti
26
27
 
27
28
  `generated-content-policy` qualifies on its own terms too: What it states is a mechanism that every consumer meets, not a preference, and the guidance that a reader needs beyond the trigger is in the linked reference rather than in the ambient body loaded by every session.
28
29
 
29
- `accessibility-conventions` also qualifies on its own terms. It states an external standard, WCAG 2.2 AA, and floors that do not name any author, repository, or tool. Its body does not contain any invocation token, so its closure is empty.
30
+ `accessibility-conventions` also qualifies on its own terms. It states WCAG 2.2 AA, an external standard, and adds floors and rules for interactive controls that do not name any author, repository, or tool. Its body does not contain any invocation token, so its closure is empty.
30
31
 
31
32
  `cli-conventions` qualifies on its own terms as well. What it asks of a CLI's options, configuration, help, exit codes, errors, JSON output, progress reports, and check results, and of the split between its logic and its presentation, follows from who reads them, a person at a terminal that cannot follow a link and a script or an agent that reads the exit code and the streams, rather than from a preference. It does not name any author, repository, language, or tool. Its body does not contain any invocation token, so its closure is empty.
32
33
 
33
34
  `command-output-conventions` qualifies on its own terms too. What it states follows from a mechanism that every agent session meets, the context-window space that retained output takes up, rather than from a preference, and it does not name any tool, host, or store. Its body does not contain any invocation token, so its closure is empty.
34
35
 
36
+ `machine-readable-output-conventions` qualifies on its own terms as well. What it asks of a result shown to a person (one object under every renderer, canonical values, structured data beside the result, redacted sensitive fields, and a journal that a test reads) follows from who reads the result, a person and an agent or a script that drives the program, rather than from a preference, and it does not name any author, repository, library, or tool. Its invocation tokens name one artifact, `cli-conventions`, which is already a member, so admitting it does not add any other artifact to what this collection deploys.
37
+
35
38
  `readme-conventions` qualifies on its own terms as well. It does not name any repository, tool, or path belonging to one author, and what it asks of a README follows from who reads the file rather than from a preference about how a README should read. Its body does not contain any invocation token, so its closure is empty and admitting it does not add any other artifact to what this collection deploys.
36
39
 
37
40
  Adding a skill that declares a guidance hook has a drawback that the current members do not have. A project declaring this collection deploys its own copy of that skill, and that copy shadows the user's home-bound one. Because guidance-hook bindings do not cross the boundary between the user-global and project domains, guidance bound globally by the developer goes missing in that repository until the project binds it too. Weigh that against the general applicability claimed by membership before admitting such a skill.
38
41
 
39
42
  `shared-data-conventions` qualifies on its own terms too. It states a standard practice, expand, migrate, contract, the rule that unmerged code does not write to shared state, and the checks that a skill writing to shared state needs before merge, and it does not name any author, platform, or store: Each repository's `AGENTS.md` names its own. Its body does not contain any invocation token, so its closure is empty.
40
43
 
41
- `ui-copy-conventions` qualifies on its own terms as well. What it asks of the text on a page follows from who reads that text, the person who returns to the page every week, rather than from a preference, and it does not name any author, repository, product, or tool. A project that has content guidelines of its own names them, and they take precedence. Its body does not contain any invocation token, so its closure is empty.
44
+ `ui-copy-conventions` qualifies on its own terms as well. What it asks of the text on a page follows from who reads that text, the person who returns to the page every week, rather than from a preference, and it does not name any author, repository, product, or tool. A project that has content guidelines of its own names them, and they take precedence. Its invocation tokens name one artifact, `accessibility-conventions`, which is already a member, so admitting it does not add any other artifact to what this collection deploys.
@@ -1,5 +1,4 @@
1
1
  <!-- include: ../../shared/AGENTS.md / -->
2
- <!-- include: ./codeassembly-guidance.md / -->
3
2
 
4
3
  <!-- codeassembly-ambient:start -->
5
4
  <!-- codeassembly-ambient:end -->