codeassembly-guidance 0.4.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 (78) hide show
  1. package/.meta/changelog.json +635 -280
  2. package/CHANGELOG.md +89 -0
  3. package/README.md +55 -19
  4. package/content/_partials/finding-grades.md +4 -0
  5. package/content/_partials/guidance-change-since-capture.md +1 -1
  6. package/content/codeassembly-content.yaml +2 -0
  7. package/content/collections/recommended.md +6 -3
  8. package/content/guidance/_harnesses/rovo/AGENTS.md +0 -1
  9. package/content/guidance/rulebooks/accessibility-conventions.md +26 -6
  10. package/content/guidance/rulebooks/cli-conventions.md +17 -2
  11. package/content/guidance/rulebooks/codeassembly-content-specification.md +11 -11
  12. package/content/guidance/rulebooks/machine-readable-output-conventions.md +85 -0
  13. package/content/guidance/rulebooks/shared-data-conventions.md +4 -2
  14. package/content/guidance/rulebooks/ui-copy-conventions.md +2 -2
  15. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +10 -10
  16. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +7 -3
  17. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +3 -1
  18. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +5 -5
  19. package/content/scripts/check-prose.mjs +38 -38
  20. package/content/scripts/describe-change.mjs +68 -68
  21. package/content/skills/_data/action-items.md +2 -2
  22. package/content/skills/_data/artifact-conventions.md +22 -431
  23. package/content/skills/_data/concision.md +1 -1
  24. package/content/skills/_data/entry-points.md +37 -0
  25. package/content/skills/_data/recommendation-gradient.md +6 -6
  26. package/content/skills/_data/spike-conventions.md +13 -3
  27. package/content/skills/_data/ticket-source-resolution.md +21 -4
  28. package/content/skills/_data/title-templates.md +4 -4
  29. package/content/skills/_partials/commit-title-rendering.md +2 -1
  30. package/content/skills/_partials/next-steps-after-plan.md +4 -3
  31. package/content/skills/_partials/option-format.md +8 -8
  32. package/content/skills/_partials/plan-template.md +4 -2
  33. package/content/skills/_partials/resolve-plan-and-ticket.md +22 -0
  34. package/content/skills/_partials/split-launch-prompts.md +1 -1
  35. package/content/skills/_partials/ticket-criteria-conventions.md +3 -1
  36. package/content/skills/analyze-performance/SKILL.md +102 -0
  37. package/content/skills/analyze-performance/analyze-performance.mjs +70 -0
  38. package/content/skills/assess-code-health/SKILL.md +16 -14
  39. package/content/skills/assess-code-health/assess-code-health.mjs +29 -28
  40. package/content/skills/assess-usability/SKILL.md +5 -3
  41. package/content/skills/convert-agent-prompt/SKILL.md +60 -0
  42. package/content/skills/create-commit/SKILL.md +10 -5
  43. package/content/skills/create-pr/SKILL.md +11 -11
  44. package/content/skills/create-ticket/SKILL.md +1 -0
  45. package/content/skills/design-and-plan/SKILL.md +2 -2
  46. package/content/skills/implement-plan/SKILL.md +1 -28
  47. package/content/skills/index-prototypes/SKILL.md +36 -17
  48. package/content/skills/index-prototypes/index-prototypes.mjs +14 -14
  49. package/content/skills/investigate-spike/SKILL.md +48 -0
  50. package/content/skills/prepare-prototype-brief/SKILL.md +17 -13
  51. package/content/skills/refine-guidance/SKILL.md +1 -1
  52. package/content/skills/refine-plan/SKILL.md +7 -4
  53. package/content/skills/refine-prototype/SKILL.md +5 -5
  54. package/content/skills/review-branch/SKILL.md +7 -7
  55. package/content/skills/review-criteria/SKILL.md +3 -3
  56. package/content/skills/review-gh-pr/SKILL.md +1 -1
  57. package/content/skills/revise-prose/SKILL.md +9 -8
  58. package/content/skills/revise-prose/revise-prose.mjs +2 -2
  59. package/content/skills/save-artifact/SKILL.md +1 -1
  60. package/content/skills/start-ticket/SKILL.md +27 -0
  61. package/content/skills/summarize-change/SKILL.md +17 -9
  62. package/content/skills/testing-conventions/SKILL.md +12 -1
  63. package/content/skills/triage-feedback/SKILL.md +1 -1
  64. package/content/skills/triage-spike-findings/SKILL.md +31 -12
  65. package/content/skills/typescript-testing-conventions/SKILL.md +40 -0
  66. package/content/subagents/_data/claude.yaml +3 -0
  67. package/content/subagents/code-health-assessor.md +4 -4
  68. package/content/subagents/disposition-challenger.md +3 -4
  69. package/content/subagents/entry-drafter.md +2 -2
  70. package/content/subagents/feedback-triage-challenger.md +1 -1
  71. package/content/subagents/handoff-reviewer.md +1 -1
  72. package/content/subagents/plan-reviewer.md +8 -7
  73. package/content/subagents/prototype-builder.md +69 -0
  74. package/content/subagents/usability-assessor.md +1 -1
  75. package/package.json +8 -7
  76. package/schemas/preferences.v1.json +1 -1
  77. package/schemas/work-types.v1.json +1 -1
  78. package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +0 -4
package/CHANGELOG.md CHANGED
@@ -2,6 +2,95 @@
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
+
78
+ ## 0.5.0 — 2026-11-02
79
+
80
+ ### 🎉 Features
81
+
82
+ - 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)
83
+ - 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)
84
+ - 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)
85
+
86
+ ### 📦 Dependencies
87
+
88
+ - Pins `codeassembly` and `@williamthorsen/kb` in guidance to their published releases `0.20.0` and `0.11.1` in place of `workspace:*`, and exempts both from the 24-hour `minimumReleaseAge` in `pnpm-workspace.yaml` so that guidance can install a release as soon as this repository's CI publishes it. (#2246)
89
+
90
+ ### 📚 Documentation
91
+
92
+ - Moves the `run-index.json`, `run-log.jsonl`, and `status.json` specification from guidance's `artifact-conventions.md` to `packages/run-core/docs/run-data-format.md`, beside the Zod schemas that implement it. (#2246)
93
+
5
94
  ## 0.4.0 — 2026-11-02
6
95
 
7
96
  ### 🎉 Features
package/README.md CHANGED
@@ -2,31 +2,66 @@
2
2
 
3
3
  # codeassembly-guidance
4
4
 
5
- The CodeAssembly library of agent guidance: rulebooks, skills, and subagents for coding harnesses, which the [`codeassembly`](../agents/README.md) CLI deploys into Claude Code and Rovo Dev.
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.4.0 (2026-11-02)
8
+ ## Release notes — v0.6.0 (2026-11-09)
9
9
 
10
10
  ### 🎉 Features
11
11
 
12
- - Adds the `curate-feedback` skill, which has `feedback-coverage-judge` subagents sort each open feedback event into covered, duplicate, obsolete, or kept against guidance pinned at a commit, and then, after approval or under `--apply`, marks every event that is not kept through `kb-update-events` and records the run in a `feedback-curation` artifact. (#2231)
13
- - Adds each covered entry's quote to the `feedback-curation` artifact's events table and to the approval table that `curate-feedback --list` presents, so that the developer can check every covered verdict against its stating sentence before approving the marks. (#2236)
14
-
15
- ### 🪦 Removed
16
-
17
- - Remove the factory and the demos (#2234)
18
-
19
- Removes the dormant factory visualization package and the catwalk demos, together with the docs, repo-local skills, dependencies, and configuration that only they used. Adds to `docs/repository-split.md` the command that finds the last commit containing the factory, which is the commit from which a revival restores it.
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)
20
50
 
21
51
  ### 🐛 Bug fixes
22
52
 
23
- - Fixes the issue that the `feedback-coverage-judge` subagent of `curate-feedback` marked a feedback event `obsolete` when the change that removed the event's target had renamed or moved it, or had named a replacement for it. (#2233)
24
- - Fixes the issue that `curate-feedback validate` accepted a `covered` entry after checking only that the cited guidance file existed, by requiring a verbatim `quote` of the stating sentence and rejecting the entry when the file at the pin does not contain it, ignoring differences in whitespace and in `*`, `_`, and backtick markers. (#2236)
25
- - Fixes the issue that `triage-feedback` ranked a feedback cluster by its events even when all of them predated a change to the guidance that governs its lesson, and directs the skill and its `feedback-triage-challenger` subagent to check that guidance's commit history and set such a cluster to `low` unless evidence shows the failure recurring under the changed guidance. (#2243)
26
- - Fixes the issue that `triage-feedback` and `triage-spike-findings` accepted a defense against the challenger that rested on grounds other than the evidence named by the challenger's argument. (#2243)
27
- - Remove the unshipped `source` export condition from the published packages (#2244)
28
-
29
- Removes the `source` export condition from `codeassembly`, `@williamthorsen/kb`, and `codeassembly-run-core`, because it pointed at TypeScript files that their tarballs don't contain, so that a consumer that enables the condition resolves the shipped `dist/` output instead of failing.
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)
30
65
  <!-- /section:release-notes -->
31
66
 
32
67
  ## Using the library
@@ -36,13 +71,13 @@ A declaration names the library as a source and selects artifacts from it, usual
36
71
  ```yaml
37
72
  sources:
38
73
  - name: codeassembly-guidance
39
- path: ~/repos/codeassembly/packages/guidance/content
74
+ path: ~/repos/codeassembly-guidance/packages/guidance/content
40
75
  collections:
41
76
  use:
42
77
  - recommended
43
78
  ```
44
79
 
45
- Then run `codeassembly install` and `codeassembly sync --global`. A project declares the same in its own `.agents/codeassembly.yaml` and runs `codeassembly sync`. [Project declaration](../agents/docs/project-declaration.md) documents the declaration format.
80
+ Then run `codeassembly install` and `codeassembly sync --global`. A project declares the same in its own `.agents/codeassembly.yaml` and runs `codeassembly sync`. [Project declaration](https://github.com/williamthorsen/codeassembly/blob/main/packages/agents/docs/project-declaration.md) documents the declaration format.
46
81
 
47
82
  ## What the content contains
48
83
 
@@ -90,5 +125,6 @@ codeassembly-validate-preferences --strict .agents/preferences.yaml
90
125
  - [Guidance streamlining helper](docs/streamline-guidance-helper.md): the helper that the `streamline-guidance` skill runs.
91
126
  - [Findings triage helper](docs/triage-spike-findings-helper.md): the helper that the `triage-spike-findings` skill runs.
92
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.
93
129
  - [Feedback triage helpers](docs/triage-feedback-helper.md): the helpers that the `triage-feedback` skill runs.
94
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.
@@ -2,7 +2,7 @@ A cluster whose events all predate a change to the guidance that governs its les
2
2
 
3
3
  Check each artifact that states or should state the lesson: the target, every artifact that your search found stating the lesson, and every partial that one of them includes.
4
4
 
5
- 1. Find the artifact's source file in the repository that owns it. A guidance-library artifact's source is under `packages/guidance/content/` in the CodeAssembly repository, at its path relative to the content root, such as `subagents/entry-drafter.md`.
5
+ 1. Find the artifact's source file in the repository that owns it. A guidance-library artifact's source is under `packages/guidance/content/` in the CodeAssembly guidance repository (`williamthorsen/codeassembly-guidance`), at its path relative to the content root, such as `subagents/entry-drafter.md`.
6
6
  2. List the commits on the owning repository's default branch that touched the source file after the latest capture: `gh api 'repos/{owner}/{repo}/commits?path={path}&since={latestCapturedAt}' --jq '.[] | [.sha[0:8], .commit.committer.date, (.commit.message | split("\n")[0])] | @tsv'`. Only when `gh` cannot reach the repository, read a local clone of it at its remote's default branch, never at the checked-out branch, which may predate the change: `git -C {clone} log --first-parent --since={latestCapturedAt} --format='%h %cs %s' origin/HEAD -- {path}`. The clone shows history only up to its last fetch.
7
7
  3. Read the message of each listed commit, with `gh api repos/{owner}/{repo}/commits/{sha} --jq .commit.message`, or with `git -C {clone} show --no-patch --format=%B {sha}` on the fallback route. A commit changed the guidance when it changed what the artifact tells the agent to do about the lesson. A commit that only repairs prose, reformats, or renames does not.
8
8
 
@@ -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
- `shared-data-conventions` qualifies on its own terms too. It states a standard practice, expand, migrate, contract, and the rule that unmerged code does not write to shared state, 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.
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 -->
@@ -1,13 +1,13 @@
1
1
  ---
2
2
  slug: accessibility-conventions
3
- description: 'Accessibility of interfaces: usability before style, contrast and size floors for text, the states that show an element is interactive, and the browser check of a visible change. Consult before writing an artifact page, a prototype, or a mockup, before defining or changing colour tokens, before writing CSS or a UI component, and before finishing or reviewing a change to a visible component.'
3
+ description: 'Accessibility of interfaces: usability before style, contrast and size floors for text, the placement, model, and states of interactive controls, the states for which a reader scans a list, and the browser check of a visible change. Consult before writing an artifact page, a prototype, or a mockup, before designing or placing a control that opens a region or toggles a setting, before designing or reviewing a list, a table, or another surface of repeated items, before defining or changing colour tokens, before writing CSS or a UI component, and before finishing or reviewing a change to a visible component.'
4
4
  delivery: [skill]
5
- version: '2'
5
+ version: '5'
6
6
  ---
7
7
 
8
8
  # Accessibility conventions
9
9
 
10
- Accessibility and usability are requirements, not a finishing touch. Make an interface usable before making it look refined, and when a style choice conflicts with readability or usability, choose usability whatever the aesthetic: "Subtle" and "refined" never justify small or faint text. These conventions apply to a prototype or a mockup exactly as they apply to a released interface.
10
+ Make an interface usable before making it look refined, and when a style choice conflicts with readability or usability, choose usability whatever the aesthetic: "Subtle" and "refined" never justify small or faint text. These conventions apply to a prototype or a mockup exactly as they apply to a released interface.
11
11
 
12
12
  The standard is WCAG 2.2 AA. This rulebook restates only the values that an agent checks while authoring and the rules that WCAG does not set; for everything else, follow WCAG.
13
13
 
@@ -15,10 +15,26 @@ The standard is WCAG 2.2 AA. This rulebook restates only the values that an agen
15
15
 
16
16
  - **Contrast.** Every text colour meets SC 1.4.3 against each surface on which it is set, in each theme that the page defines: 4.5:1, or 3:1 for large text (at least 24px, or at least 18.7px bold).
17
17
  - **Size.** Body text is at least 14px, and secondary text (captions, counts, states, hints) at least 12px. WCAG does not set either floor.
18
- - **Tiers.** Use two text colours, primary and secondary. Add a third only if it meets the same contrast floor; a third tier that passes is within a few shades of the second and adds little.
18
+ - **Tiers.** Use two text colours, primary and secondary. Add a third only if it meets the same contrast floor.
19
19
 
20
20
  Check contrast whenever colour tokens are defined or changed. Compute the WCAG contrast ratio of each text token against each surface token on which it is used, in each theme, compositing any translucent colour or `opacity` over its surface first. Report every failing pair with its ratio, and fix it before presenting the page.
21
21
 
22
+ ## Designing controls
23
+
24
+ - **Named model.** Before designing an affordance, name the established model that the feature most resembles, such as a browser's developer tools, an editor's side panel, or a panel that the product already has, and follow it. Depart from the model only for a reason, and record the reason wherever the design is recorded. Example: An activity drawer follows the editor side-panel model.
25
+ - **Placement.** A control that opens or closes a region sits at that region's edge or in a persistent toolbar, never in an unrelated group of actions. Example: ❌ An "Activity" button among the page header's actions opens a drawer on the right. ✅ The toggle sits at the right end of the toolbar, on the drawer's side.
26
+
27
+ ## Glanceable state
28
+
29
+ A state for which a reader scans a list, a table, or another surface of repeated items, such as expired, failing, selected, in progress, or due soon, is visible without reading each item. Mark it by one or more of these means:
30
+
31
+ - **Colour with a second cue.** A colour paired with a cue that does not rely on colour, such as an icon, a badge, or a weight, per SC 1.4.1.
32
+ - **Symbol.** An icon or a badge beside each item in the state.
33
+ - **Grouping.** A section or a divider that sets the items in the state apart from the rest.
34
+ - **Order.** A sort that brings the items in the state to the top.
35
+
36
+ Text alone does not meet the rule, even in a column of its own: The reader still reads each cell to find the items in the state. A restraint on colour, such as a decision to keep a page calm, governs decoration and never such a state, and a design decision or a prototype verdict that hides one is a defect. Example: ❌ An expiry column that reads "Expired 1 day ago" and "In 200 days" in one style. ✅ Each expired token shows a red badge with a warning icon, and the expired tokens sort first.
37
+
22
38
  ## Interaction states
23
39
 
24
40
  Every element that responds to a click or a key shows that it does:
@@ -27,12 +43,16 @@ Every element that responds to a click or a key shows that it does:
27
43
  - **Hover.** Its appearance changes while the pointer is over it.
28
44
  - **Focus.** A visible indicator marks it while it has keyboard focus, per SC 2.4.7, and the indicator meets the 3:1 non-text contrast of SC 1.4.11 against its surface.
29
45
 
46
+ A button outside a toolbar also looks like a button at rest: It has a border or a fill that meets the 3:1 contrast of SC 1.4.11 against its surface. Only a button inside a toolbar may be borderless text.
47
+
30
48
  A disabled element, whether disabled by the native attribute or by `aria-disabled`, shows neither the hover state nor the pointer.
31
49
 
32
- Put the states in a base style or a shared component rather than setting them at each call site, so that a new element has them without anyone remembering to add them. Do not rely on a framework's or a reset's defaults: Some remove the pointer from a button.
50
+ A control that toggles also shows its on state at rest, by a cue that does not rely on colour alone (SC 1.4.1) and that meets the 3:1 contrast of SC 1.4.11. It exposes the state as `aria-expanded` when it shows or hides a region, and as `aria-pressed` when it switches a setting. Its label names what it governs and stays the same in both states. Example: ❌ "Show activity", which becomes "Hide activity". ✅ "Activity", with `aria-expanded` and a pressed style while the drawer is open.
51
+
52
+ Put the states in a base style or a shared component rather than setting them at each call site. Do not rely on a framework's or a reset's defaults: Some remove the pointer from a button.
33
53
 
34
54
  ## Checking in a browser
35
55
 
36
- Check every change to a visible component in a browser before reporting it finished or reviewed. Open the page, then hover over and tab through each new or changed interactive element, and confirm the three states above, or their absence on a disabled element. A test that renders HTML, or a reading of the diff, does not replace this check: Neither shows what the element looks like under the pointer or with focus.
56
+ Check every change to a visible component in a browser before reporting it finished or reviewed. Open the page, then hover over and tab through each new or changed interactive element, and confirm the three states above, or their absence on a disabled element. Toggle each control that toggles, and confirm its on state and its off state. Confirm that each button outside a toolbar has its border or fill at rest, and scan each new or changed list to confirm that its scanned states are visible without reading each item. A test that renders HTML, or a reading of the diff, does not replace this check: Neither shows what the element looks like under the pointer or with focus.
37
57
 
38
58
  When a browser is not available, report that the check did not run and name the elements that it would have covered. Never report it as passed.
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  slug: cli-conventions
3
- description: 'How a command-line tool talks to its user: subcommands and options, standard option names, configuration, writing modes, help on every command, exit codes, error messages, JSON output, progress and outcome reports, check results, color, the split of logic from presentation, and help topics. Consult before writing or changing any command-line tool, in any language.'
3
+ description: 'How a command-line tool talks to its user: subcommands and options, standard option names, configuration, writing modes, help on every command, exit codes, error messages, unexpected crashes, JSON output, progress and outcome reports, check results, color, the split of logic from presentation, and help topics. Consult before writing or changing any command-line tool, in any language.'
4
4
  delivery: skill
5
- version: '5'
5
+ version: '6'
6
6
  ---
7
7
 
8
8
  # CLI conventions
@@ -124,6 +124,21 @@ Example, for a command that needs an access token:
124
124
  - ❌ `<bin> publish --token <value>`
125
125
  - ✅ `<bin> publish --token-file <path>`, or the token piped to `<bin> publish --token-stdin`
126
126
 
127
+ ## Unexpected crashes
128
+
129
+ An unexpected crash is a bug in the tool, as opposed to a failure that the tool anticipated and reports as an error message.
130
+
131
+ - **A last-resort handler reports a crash as `<bin>: internal error: <message>` on stderr, followed by the stack frames.** The prefix follows "Error messages", and `internal error` tells the reader that the fault is the tool's.
132
+ - **The stack frames are always printed, not only under a debug flag.** A crash may not reproduce, and the stack frames are where a bug report starts.
133
+ - **A thrown value that is not an error is reported by its string form**, without stack frames, because it does not have any.
134
+ - **A crash exits 1**, as "Any other failure while running" in the exit-code table states.
135
+ - **A handled error never takes the crash shape, and a crash never takes the shape of a handled error**, so that a reader can tell a bug in the tool from a mistake in their own input.
136
+
137
+ Example, for a crash caused by reading a property of an undefined value:
138
+
139
+ - ❌ `Error: Cannot read properties of undefined (reading 'name')`, which reads as a handled error
140
+ - ✅ `<bin>: internal error: Cannot read properties of undefined (reading 'name')`, followed by the stack frames
141
+
127
142
  ## JSON output
128
143
 
129
144
  - **A command whose output a script or an agent may read supports `--json`.** Parsing text written for a person breaks when its wording changes.
@@ -3,7 +3,7 @@ slug: codeassembly-content-specification
3
3
  description: The declaration contract and authoring doctrine for CodeAssembly skills, subagents, rulebooks, and collections -- frontmatter, dependencies, invocation tokens, how broad a guidance change goes, which kind of artifact it goes in, and when a procedure belongs in a helper.
4
4
  standalone: wanted by repositories that author CodeAssembly content, which declare it directly
5
5
  delivery: skill
6
- version: '32'
6
+ version: '33'
7
7
  ---
8
8
 
9
9
  # CodeAssembly content specification
@@ -105,25 +105,25 @@ members:
105
105
 
106
106
  ### Dispositions
107
107
 
108
- A `disposition:` states what membership in a collection that enumerates its members claims about them, and `codeassembly validate` holds the root to that claim. A collection without one is a plain bundle: Its membership does not claim anything, so it neither covers an artifact nor conflicts with a disposition.
108
+ A `disposition:` states what membership in a collection that enumerates its members claims about them, and `codeassembly validate` checks the root against that claim. A collection without one is a plain bundle: Its membership does not claim anything, so it neither covers an artifact nor conflicts with a disposition.
109
109
 
110
- - `public`: Its members are generally fit. Its closure may reach only the members of public collections.
111
- - `personal`: Its members are fitted to one author. Its closure may reach the members of personal and public collections.
112
- - `opt-in`: Its members are fitted to one vendor ecosystem. Its closure may reach its own members and the members of public collections, and the closure of every other collection, other than an `'@library'` one, must not reach its members, so that only a consumer declaring it deploys them.
110
+ - `public`: Its members are generally fit. Its closure may include only the members of public collections.
111
+ - `personal`: Its members are fitted to one author. Its closure may include the members of personal and public collections.
112
+ - `opt-in`: Its members are fitted to one vendor ecosystem. Its closure may include its own members and the members of public collections, and the closure of every other collection, other than an `'@library'` one, must not include its members, so that only a consumer declaring it deploys them.
113
113
 
114
- An artifact that is deliberately outside every collection declares `standalone:` in its own frontmatter, with the reason as the value. A collection must not enumerate it, and the closure of a collection, other than an `'@library'` one, must not reach it. An artifact that several collections claim is within a closure's reach when any one of its claims is. `disposition:` on a collection whose members are computed, `standalone:` on a collection, and `disposition:` on any other type are errors.
114
+ An artifact that is deliberately outside every collection declares `standalone:` in its own frontmatter, with the reason as the value. A collection must not enumerate it, and the closure of a collection, other than an `'@library'` one, must not include it. A closure may include an artifact that several collections claim when it may include the members of any one of those collections. `disposition:` on a collection whose members are computed, `standalone:` on a collection, and `disposition:` on any other type are errors.
115
115
 
116
116
  `validate` checks a root that declares a disposition, a standalone artifact, or an `'@unclaimed'` collection, and reports each of these as a `disposition` defect:
117
117
 
118
- - a standalone artifact that a collection enumerates, or that the closure of a collection other than an `'@library'` one reaches
119
- - a collection with a disposition whose closure reaches an artifact outside its reach
120
- - a collection, other than an `'@library'` one, whose closure reaches a member of an opt-in collection other than itself
118
+ - a standalone artifact that a collection enumerates, or that the closure of a collection other than an `'@library'` one includes
119
+ - a collection with a disposition whose closure includes an artifact that its disposition does not permit
120
+ - a collection, other than an `'@library'` one, whose closure includes a member of an opt-in collection other than itself
121
121
  - in a root without an `'@unclaimed'` collection, an artifact that is not covered by any disposition
122
122
  - a `disposition:` or `standalone:` value that cannot be read
123
123
 
124
124
  ## Frontmatter fields
125
125
 
126
- - **Rulebooks:** `slug`, optional `description`, required `delivery` (`ambient`, `hook`, `skill`, or a non-empty list of them; `ambient` only when nearly every session needs the content, since an ambient rulebook is loaded by every session that declares it, and `skill` or `hook` otherwise), optional `skill-name`, optional `supported-harnesses` (a harness id or list restricting every delivery mode to those harnesses; absent deploys to all), optional `version`. A declared `version` is an opaque string, never parsed as semver, and every route that delivers the rulebook names it on a `<!-- rulebook-version: <version> -->` line directly below the marker that names the slug, so that an agent can read which version of a rulebook it has. A route omits the line for a rulebook that does not declare a version. Quote the value: YAML reads an unquoted `1.10` as the number `1.1`, and the schema rejects a non-string rather than deploying the digits that it lost. It rejects a value that the version line cannot contain on its own, which is a blank one, a multi-line one, and one containing `-->`.
126
+ - **Rulebooks:** `slug`, optional `description`, required `delivery` (`ambient`, `hook`, `skill`, or a non-empty list of them; `ambient` only when nearly every session needs the content, since an ambient rulebook is loaded by every session that declares it, and `skill` or `hook` otherwise), optional `skill-name`, optional `supported-harnesses` (a harness id or list restricting every delivery mode to those harnesses; absent deploys to all), optional `version`. A declared `version` is an opaque string, never parsed as semver, and every delivery mode of the rulebook names it on a `<!-- rulebook-version: <version> -->` line directly below the marker that names the slug, so that an agent can read which version of a rulebook it has. A rulebook that does not declare a version does not have the line in any delivery mode. Quote the value: YAML reads an unquoted `1.10` as the number `1.1`, and the schema rejects a non-string rather than deploying the digits that it lost. It rejects a value that the version line cannot contain on its own, which is a blank one, a multi-line one, and one containing `-->`.
127
127
  - **Skills:** `name`, `description`, optional `user-invocable` (defaults to `true`), optional `supported-harnesses` (a harness id or list restricting deployment to those harnesses; absent deploys to all). The deploy writes every other key to every harness unchanged, so a key that only one harness reads, such as Claude's `context` or `model`, is also written to the others, which ignore it.
128
128
  - **Subagents:** `name`, `description`, optional `tools`, optional `disallowedTools`, optional `maxTurns`, optional `skills` (skills injected into the subagent's context), optional `rulebooks` (rulebooks injected the same way, named by slug rather than by deploy name, so that a `skill-name` override on the target stays correct). `sync` pulls both lists into the deploy closure, merges each injected rulebook's deploy name into the deployed `skills:`, and drops the `rulebooks:` key from what it writes.
129
129
  - **Collections:** `name`, `description`, a `members:` block, and an optional `disposition`; see [Dispositions](#dispositions).
@@ -192,7 +192,7 @@ A sweep version is a positive integer, and a new rule starts at `1`. Raise it wh
192
192
 
193
193
  ## Guidance hooks
194
194
 
195
- When a step's guidance is a matter of local taste rather than library doctrine -- such as a user's code-style preferences, or a project's own glossary -- neither a pointer to a stated rule nor an inlined partial fits: A pointer sends the agent away to fetch the rule, and an inlined partial fixes one answer for every consumer at authoring time. Declare a guidance hook instead, `<!-- guidance-hook: <name> -->`, and leave the slot for a `codeassembly.yaml` to bind per project or per machine. An unbound hook contributes nothing to deployed output, so declaring one is safe wherever nothing fills it. A rulebook written for that slot declares `delivery: hook`, which records the route and lets `sync` report a binding and a delivery that disagree. The directive grammar is specified in `content/_partials/README.md` and the binding syntax in `packages/agents/docs/project-declaration.md`. _(Convention; not enforced.)_
195
+ When a step's guidance is a matter of local taste rather than library doctrine -- such as a user's code-style preferences, or a project's own glossary -- neither a pointer to a stated rule nor an inlined partial fits: A pointer sends the agent away to fetch the rule, and an inlined partial fixes one answer for every consumer at authoring time. Declare a guidance hook instead, `<!-- guidance-hook: <name> -->`, and leave the slot for a `codeassembly.yaml` to bind per project or per machine. An unbound hook contributes nothing to deployed output, so declaring one is safe wherever nothing fills it. A rulebook written for that slot declares `delivery: hook`, which records the delivery mode and lets `sync` report a binding and a delivery that disagree. The directive grammar is specified in `content/_partials/README.md` and the binding syntax in `packages/agents/docs/project-declaration.md`. _(Convention; not enforced.)_
196
196
 
197
197
  ## Injection-point placement
198
198
 
@@ -0,0 +1,85 @@
1
+ ---
2
+ slug: machine-readable-output-conventions
3
+ description: 'Results that a program shows to a person and that an agent or a script also reads: one result object under every renderer, the scope test, canonical values, the command-line case, structured data beside a result on a page, formats, sensitive fields, a journal of domain events, and the TypeScript packages that implement them. Consult before writing a command, a page, a dialog, or a component that shows a person a result, a report, or a confirmation, and before building an app whose state an agent or an end-to-end test verifies.'
4
+ delivery: [skill]
5
+ version: '2'
6
+ ---
7
+
8
+ # Machine-readable output conventions
9
+
10
+ A result that a program shows to a person has a second reader: an agent or a script that drives the program and needs the same facts as data. When the facts exist only in their presentational form, that reader parses prose or an accessibility tree, and the parse breaks when the wording or the formatting changes. These rules make every such result available in both forms without letting the two disagree.
11
+
12
+ These rules apply whatever language, framework, or library implements them.
13
+
14
+ ## Principle
15
+
16
+ - **A result is one object.** The program's logic produces it, and every form of it, for a person or for a machine, is a renderer over that object.
17
+ - **Every renderer reads the same object.** Two renderers cannot disagree about a fact, because neither one computes it, and each renderer can be tested without running the program.
18
+
19
+ ## Scope
20
+
21
+ - **The rules cover a result that a person would otherwise transcribe:** a created thing, a report, a check outcome, or a confirmation.
22
+ - **They cover a view of state that an agent needs in order to verify its own action**, such as the record that a form submission changed.
23
+ - **They do not cover a screen's ordinary content**, such as a table, a list, or a tooltip.
24
+
25
+ ## Canonical values
26
+
27
+ Each value in the object is in canonical form, and a renderer for a person formats it.
28
+
29
+ - **Timestamps** are ISO 8601 with an offset.
30
+ - **Numbers** are unformatted, and the field name states the unit: `ttlSeconds: 604800`, not `ttl: "7 days"`.
31
+ - **References** are ids, not display names.
32
+ - **Enumerated values** are codes, not labels.
33
+
34
+ Example, for the expiry of a created token:
35
+
36
+ - ❌ `{"expires": "Nov 12, 2026 (in 7 days)"}`
37
+ - ✅ `{"expiresAt": "2026-11-12T00:00:00Z"}`, which the dialog renders as "Nov 12, 2026 (in 7 days)"
38
+
39
+ ## Command-line output
40
+
41
+ A command-line tool exposes its result through `--json`, as the "JSON output" section of {rulebook:cli-conventions} states, and splits its logic from its presentation as that rulebook's "Logic and presentation" section states.
42
+
43
+ ## Results on a page
44
+
45
+ A result that a page shows to a person is also available as structured data, in two forms that serialize the same object:
46
+
47
+ - **A revealable element.** A tab, a pane, or a drawer beside the result shows the data and copies it with one click.
48
+ - **Embedded data.** The page embeds the data in the DOM, in a `<script type="application/json">` element or a `data-` attribute on the result's container, so that a driven browser reads it without revealing or clicking anything.
49
+
50
+ The embedded data is part of the page's interface: A published field follows the same rule that {rulebook:cli-conventions} states for a field of `--json` output.
51
+
52
+ ## Formats
53
+
54
+ - **JSON is required.** It is the canonical, lossless form, and it is the form that the page embeds.
55
+ - **YAML and Markdown are optional renderers** over the same object. Because a YAML renderer adds a dependency, an app includes one only when a person asks for it.
56
+
57
+ ## Sensitive fields
58
+
59
+ - **The result type marks a sensitive field**, such as a secret.
60
+ - **The copy and the embedded data redact a sensitive field by default.** Embedded data reaches page snapshots, test traces, and logs, which outlive the page and reach readers other than the person viewing it.
61
+ - **Including a sensitive field is an explicit act**, such as turning on an "Include secret" control beside the copy.
62
+ - **Redacted data names what it leaves out**, so that a reader can tell a redacted field from an absent one.
63
+
64
+ Example, for the copy of a created token:
65
+
66
+ - ❌ "Copy JSON" copies the token with its secret.
67
+ - ✅ "Copy JSON" copies the token without `secret` and with `"redacted": ["secret"]`, until the person turns on "Include secret".
68
+
69
+ ## Journal
70
+
71
+ An app that an agent or an end-to-end test must verify after a person's actions keeps a journal of what those actions did.
72
+
73
+ - **An entry records a domain event, not a raw action:** "token created", not "button clicked".
74
+ - **A pure function derives each entry** from the state before the action, the action, and the state after it.
75
+ - **An entry has an id, a timestamp, a type, the ids of its subjects, and canonical data.** The sentence that a person reads and the JSON are two renderers over the entry.
76
+ - **The app never reads its journal to compute state.** The state stays the one source of truth, and the journal records what changed in it.
77
+ - **The journal is a test oracle.** An end-to-end test or an agent reads it to confirm what happened, and the app exposes it as it exposes any other result.
78
+
79
+ ## TypeScript packages
80
+
81
+ Three packages implement these rules, and an implementation in TypeScript can start from them. The rules above remain the contract, whether or not an implementation uses them. Each package's README states its API.
82
+
83
+ - **[`@williamthorsen/readout`](https://github.com/williamthorsen/showroom/tree/main/packages/readout#readme)** supplies the result type, with its sensitive fields marked; a JSON serializer that redacts them and names what it leaves out; the escaping that embedded data needs; and typed renderers over the result. It implements "Formats", "Sensitive fields", and the embedded data of "Results on a page".
84
+ - **[`@williamthorsen/readout-journal`](https://github.com/williamthorsen/showroom/tree/main/packages/readout-journal#readme)** supplies a journal that a wrapped reducer derives from each state transition, its JSON form, and a renderer for each entry type. It implements "Journal".
85
+ - **[`@williamthorsen/readout-react`](https://github.com/williamthorsen/showroom/tree/main/packages/readout-react#readme)** supplies React components for a copy button, a JSON view, a view that reveals a result's data beside the result, and a drawer that lists the journal. It implements the revealable element of "Results on a page" in a React app.