codeassembly-guidance 0.6.0 → 0.8.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 (124) hide show
  1. package/.meta/changelog.json +446 -0
  2. package/CHANGELOG.md +107 -0
  3. package/README.md +47 -51
  4. package/bin/codeassembly-validate-preferences.js +2 -8
  5. package/content/_partials/diff-audit-checklist.md +1 -0
  6. package/content/_partials/kb-unsearched-private-stores.md +6 -0
  7. package/content/_partials/plain-speech.md +2 -2
  8. package/content/_partials/ticket-assessment.md +3 -3
  9. package/content/codeassembly-content.yaml +8 -0
  10. package/content/collections/recommended.md +6 -0
  11. package/content/collections/williamthorsen.md +2 -1
  12. package/content/guidance/rulebooks/accessibility-conventions.md +6 -3
  13. package/content/guidance/rulebooks/cross-repo-migration-conventions.md +27 -0
  14. package/content/guidance/rulebooks/live-worktree-policy.md +2 -2
  15. package/content/guidance/rulebooks/ui-copy-conventions.md +2 -2
  16. package/content/guidance/rulebooks/visual-design-conventions.md +58 -0
  17. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +3 -18
  18. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +7 -1
  19. package/content/guidance/rulebooks/williamthorsen-visual-design-preferences.md +14 -0
  20. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +5 -3
  21. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +5 -20
  22. package/content/guidance/shared/AGENTS.md +3 -4
  23. package/content/scripts/README.md +1 -1
  24. package/content/scripts/check-branch-currency.mjs +7 -7
  25. package/content/scripts/check-prose.mjs +38 -38
  26. package/content/scripts/describe-change.mjs +89 -89
  27. package/content/scripts/manage-jira-ticket.mjs +162 -160
  28. package/content/scripts/select-lede-exemplars.mjs +85 -85
  29. package/content/scripts/validate-preferences.mjs +41 -41
  30. package/content/skills/_data/artifact-conventions.md +3 -3
  31. package/content/skills/_data/entry-points.md +1 -1
  32. package/content/skills/_data/project-stage.md +9 -5
  33. package/content/skills/_data/reduced-object-relatives.md +15 -0
  34. package/content/skills/_data/spike-conventions.md +16 -6
  35. package/content/skills/_data/ticket-evaluation.md +3 -0
  36. package/content/skills/_partials/implementation-order-list.md +27 -0
  37. package/content/skills/_partials/merge-settled-criterion.md +1 -0
  38. package/content/skills/_partials/next-steps-after-plan.md +2 -2
  39. package/content/skills/_partials/plan-template.md +3 -1
  40. package/content/skills/_partials/resolve-plan-and-ticket.md +2 -2
  41. package/content/skills/_partials/split-launch-prompts.md +1 -1
  42. package/content/skills/_partials/split-ticket-create.md +1 -1
  43. package/content/skills/_partials/ticket-criteria-conventions.md +2 -0
  44. package/content/skills/align-ticket-with-implementation/SKILL.md +3 -3
  45. package/content/skills/analyze-performance/SKILL.md +1 -1
  46. package/content/skills/assess-code-health/SKILL.md +4 -4
  47. package/content/skills/assess-code-health/assess-code-health.mjs +20 -20
  48. package/content/skills/assess-ticket/SKILL.md +3 -1
  49. package/content/skills/assess-ticket/next-steps-after-assessment.md +11 -14
  50. package/content/skills/assess-usability/SKILL.md +4 -4
  51. package/content/skills/capture-event/SKILL.md +20 -11
  52. package/content/skills/capture-event/capture-event.mjs +123 -123
  53. package/content/skills/capture-feedback/SKILL.md +2 -1
  54. package/content/skills/capture-lede-decision/SKILL.md +1 -1
  55. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +97 -97
  56. package/content/skills/collaborate/SKILL.md +1 -1
  57. package/content/skills/condense-branch/SKILL.md +18 -36
  58. package/content/skills/condense-branch/condense-branch.mjs +17 -0
  59. package/content/skills/create-bitbucket-pr/SKILL.md +9 -11
  60. package/content/skills/create-commit/SKILL.md +1 -1
  61. package/content/skills/create-devlog/SKILL.md +4 -4
  62. package/content/skills/create-gh-pr/SKILL.md +9 -11
  63. package/content/skills/create-pr/SKILL.md +10 -12
  64. package/content/skills/create-ticket/SKILL.md +22 -15
  65. package/content/skills/create-ticket/resolve-ticket-target.mjs +92 -92
  66. package/content/skills/curate-feedback/SKILL.md +2 -2
  67. package/content/skills/curate-feedback/curate-feedback.mjs +82 -82
  68. package/content/skills/derive-session-context/derive-session-context.mjs +120 -120
  69. package/content/skills/design-and-plan/SKILL.md +10 -8
  70. package/content/skills/groom-backlog/groom-backlog.mjs +15 -15
  71. package/content/skills/implement-plan/SKILL.md +4 -2
  72. package/content/skills/implementation-order/implementation-order.mjs +67 -0
  73. package/content/skills/index-prototypes/SKILL.md +2 -2
  74. package/content/skills/investigate-spike/SKILL.md +3 -3
  75. package/content/skills/kb-add/SKILL.md +12 -3
  76. package/content/skills/kb-add/kb-add.mjs +88 -88
  77. package/content/skills/kb-curate/kb-curate.mjs +88 -88
  78. package/content/skills/kb-edit/kb-edit.mjs +90 -90
  79. package/content/skills/kb-retrieve/SKILL.md +8 -3
  80. package/content/skills/kb-retrieve/kb-retrieve.mjs +104 -104
  81. package/content/skills/kb-retrieve-events/SKILL.md +8 -3
  82. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +113 -113
  83. package/content/skills/kb-update-events/kb-update-events.mjs +92 -92
  84. package/content/skills/lesson-clusters/lesson-clusters.mjs +102 -102
  85. package/content/skills/list-gh-progress-items/SKILL.md +36 -0
  86. package/content/skills/list-gh-progress-items/list-gh-progress-items.mjs +68 -0
  87. package/content/skills/list-implementation-order/SKILL.md +23 -0
  88. package/content/skills/merge-bb-pr/SKILL.md +40 -19
  89. package/content/skills/merge-gh-pr/SKILL.md +34 -23
  90. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +13 -8
  91. package/content/skills/merge-pr/SKILL.md +64 -31
  92. package/content/skills/migrate-feedback-memories/SKILL.md +1 -0
  93. package/content/skills/plan/SKILL.md +5 -3
  94. package/content/skills/prepare-prototype-brief/SKILL.md +5 -3
  95. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +22 -22
  96. package/content/skills/refine-plan/SKILL.md +5 -3
  97. package/content/skills/refine-prototype/SKILL.md +2 -1
  98. package/content/skills/respond-to-review/SKILL.md +4 -4
  99. package/content/skills/review-bb-pr/SKILL.md +1 -2
  100. package/content/skills/review-branch/SKILL.md +19 -14
  101. package/content/skills/review-criteria/SKILL.md +2 -2
  102. package/content/skills/review-gh-pr/SKILL.md +1 -2
  103. package/content/skills/review-pr/SKILL.md +2 -3
  104. package/content/skills/revise-prose/revise-prose.mjs +109 -109
  105. package/content/skills/save-artifact/SKILL.md +4 -6
  106. package/content/skills/save-plan/SKILL.md +4 -2
  107. package/content/skills/start-ticket/SKILL.md +1 -1
  108. package/content/skills/streamline-guidance/streamline-guidance.mjs +80 -80
  109. package/content/skills/summarize-change/SKILL.md +20 -9
  110. package/content/skills/summarize-chat/SKILL.md +2 -2
  111. package/content/skills/testing-conventions/SKILL.md +2 -2
  112. package/content/skills/triage-feedback/SKILL.md +6 -2
  113. package/content/skills/triage-spike-findings/SKILL.md +33 -24
  114. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +19 -19
  115. package/content/skills/update-project-guidance/SKILL.md +1 -1
  116. package/content/skills/wrap-up/SKILL.md +8 -4
  117. package/content/skills/write-progress-report/SKILL.md +111 -0
  118. package/content/skills/write-progress-report/write-progress-report.mjs +150 -0
  119. package/content/subagents/disposition-challenger.md +7 -6
  120. package/content/subagents/entry-drafter.md +2 -0
  121. package/content/subagents/usability-assessor.md +3 -2
  122. package/package.json +13 -12
  123. package/schemas/preferences.v1.json +82 -8
  124. package/schemas/work-types.v1.json +1 -1
package/README.md CHANGED
@@ -5,63 +5,59 @@
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.6.0 (2026-11-09)
8
+ ## Release notes — v0.8.0 (2026-11-20)
9
9
 
10
10
  ### 🎉 Features
11
11
 
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)
12
+ - Changes `review-branch` to reflow each comment line that the diff adds or modifies and that exceeds the `max_line_length` set by `.editorconfig`, commit the reflow with `create-commit`, and list it in a new "Applied reflows" section of the review, rather than report it as a finding; a review of a pull request, or of a file with uncommitted changes, still reports the line as a finding. (#196)
13
+ - Adds a width item to the diff-audit checklist used by `implement-plan`, `respond-to-review`, and `revise-comments`, which directs the agent to reflow each comment line in its own hunks that exceeds the `.editorconfig` `max_line_length`, changing only whitespace. (#196)
14
+ - Adds to the `recommended` collection the `cross-repo-migration-conventions` rulebook, which covers the umbrella ticket and its one child per repository, shared runtimes moved before the repositories that use them, contract changes decided before any child acts, and a comment on the umbrella that each child posts before merge. (#197)
15
+ - Adds to `williamthorsen-ticketing-preferences` a reference to `cross-repo-migration-conventions` for a change that migrates many repositories to a new version or convention. (#197)
16
+ - Adds a requirement to the `williamthorsen-ticketing-preferences` rulebook to estimate the layers, subsystems, and approximate source and test lines of work that spans several layers or adds a new subsystem before its ticket count is decided, and to recommend the split when each piece can be merged and verified on its own, and has the `design-and-plan` ticket checkpoint present that split as the recommended option of a menu. (#202)
17
+ - Directs `list-implementation-order` to pass the repository in which a ticket outside GitHub is implemented, through the helper's new `--external "[REPOSITORY:]KEY=Title"` form, which the helper uses to label that ticket with the repository's prefix, such as `mc.MAC-7`. (#206)
18
+ - Lower-cases the repository prefixes in the implementation-order list, such as `cg.12` in place of `CG.12`, to set them apart from an upper-case Jira key. (#206)
19
+ - Adds a durability check to `summarize-change` that rejects a lede, entry, or migration stating the change's delivery state in a main or subordinate clause, and adds a step that the change needs in order to take effect, such as a deploy or a sync, to the facts that `## Notes for reviewers` contains. (#207)
20
+ - Adds a convention to `create-ticket`, `design-and-plan`, and `align-ticket-with-implementation` that limits a code ticket's acceptance criteria to those that its pull request's tests, checks, or review can show to hold or fail at merge, and directs the agent to move a criterion that depends on elapsed time, deployed state, or a run against shared data to the ticket that consumes the change. (#208)
21
+ - Adds a criterion-settleability facet to the ticket evaluation used by `design-and-plan` and by the advisability dimension of `assess-ticket`, which reports each acceptance criterion of a code ticket that its pull request cannot show to hold or fail at merge, together with the ticket to which the criterion moves. (#208)
22
+ - Adds the `write-progress-report` skill, which writes a customer-facing progress report from a tracker or an `--items` file, with one section per workstream that states its health and lists the items that need the customer's input, are done, are in progress, or are planned. (#213)
23
+ - Adds `list-gh-progress-items`, which `write-progress-report` calls for `--source github` to read a repository's GitHub issues as report items, treating each parent issue as a workstream and each issue labeled `needs-input` as an ask of the customer. (#213)
24
+ - Adds `confluence` to the values of the `write-progress-report` skill's `--format` argument, which renders the report in Confluence storage format (the XML that Confluence stores as a page body), with health and statuses as status lozenges and dates as date elements that Confluence shows in the reader's locale. (#215)
25
+ - Adds `project_artifact_dir` (`{artifact_base_dir}/projects/{project_slug}`) and `ticket_dir` (`{project_artifact_dir}/tickets/{ticket_id}`, or `null` when the branch does not name a ticket) to the session-context manifest that `derive-session-context` emits. (#219)
26
+ - Changes `save-artifact` and every other skill that saves or reads artifacts to take the artifact directories from the manifest, with `save-artifact` stating the fallback for a `null` `ticket_dir`, which generates a ticket ID and saves under `{project_artifact_dir}/tickets/{generated id}`. (#219)
27
+ - Adds to the `recommended` collection the `visual-design-conventions` rulebook, which states the visual-design rules that hold whatever the style: padding inside a bordered or filled container, alignment with another block, marks only on the exception, colour as a way to tell kinds and states apart, an appearance that follows each element's role, the product's own name and favicon, and a browser check of each changed view. (#220)
28
+ - Adds to the `williamthorsen` collection the `williamthorsen-visual-design-preferences` rulebook, which prefers a quiet colour scheme, with muted hues on neutral surfaces that each encode a kind or a state, to a monochrome one. (#220)
29
+ - Adds `visual-design-conventions` beside `accessibility-conventions` to the floor that the planning, building, assessment, and review skills and the `usability-assessor` subagent set for an interface, including the rulebook's browser check of each changed view. (#220)
30
+ - Adds the "Consequence at the control" rule to `accessibility-conventions`, which requires the explanation of an action that cannot be undone to be visible at rest, allows a toggletip for one that can be undone, and never accepts a hover-only tooltip as the only explanation. (#221)
31
+ - Opens `accessibility-conventions` with a statement that its rules are floors, and directs agents to aim beyond them by following an established model, as the named-model rule describes. (#221)
32
+ - Extends the helper-text rule of `ui-copy-conventions` to say what an action's consequence explanation states, and counts that explanation toward the copy budget's one line of helper text. (#221)
33
+ - Adds the consequence-at-the-control rule to the skills and the subagent that list the accessibility rules that they apply, among them `review-criteria`, `prepare-prototype-brief`, and the `usability-assessor` per-screen checklist. (#221)
34
+ - Adds a `close` subcommand to `manage-jira-ticket.mjs`, which posts a Markdown body as a comment unless an existing comment opens with the body's first line, then transitions the work item to the status that the new `integrations.jira.done_status` preference names (default `Done`) unless its status category is already done. (#225)
35
+ - Extends the closing post of the spike skills and the close of the triage ticket in `triage-spike-findings` to Jira tickets through `manage-jira-ticket.mjs close`; the guidance previously named only `gh issue close`, which does not close a Jira ticket. (#225)
36
+ - Extends `triage-spike-findings` to run on Jira as well as GitHub, adding a `platform` field to the dispositions record so that the record accepts work item keys such as `PROJ-123`, and creating each Jira ticket under the triage ticket's parent in place of an umbrella. (#227)
37
+ - Makes `analyze-performance`, `assess-code-health`, `assess-usability`, and `investigate-spike` name `triage-spike-findings` as the next step only for a ticket on GitHub or Jira, and name the findings left for disposal by hand for a ticket on any other platform. (#227)
38
+ - Adds a rule to the `williamthorsen-ticketing-preferences` rulebook that splits adding a package to a monorepo into two tickets: an empty scaffold with its documentation and package references that passes the repository's checks on its own, and the package's functionality, blocked by the scaffold. (#229)
39
+ - Changes `create-commit` to record a scaffold that passes the repository's checks and is fully wired as a commit of its own, while a scaffold that a later change fills in still goes into that change. (#229)
40
+ - Requires in the `visual-design-conventions` rulebook that text and elements within a block be start-aligned and a column of numbers end-aligned, limits centring to a viewport-centred dialog, a single-line label in a button or a tag, and an icon in a square control, and adds a matching item to the rulebook's browser check. (#231)
41
+ - Adds the `--umbrella` flag to `create-ticket`, which on Jira creates the ticket at the issue type that the new `integrations.jira.umbrella_issue_type` preference sets, `Epic` by default, so that Jira accepts it as the parent of its child tickets. (#232)
50
42
 
51
43
  ### 🐛 Bug fixes
52
44
 
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)
45
+ - Fixes the issue that `assess-ticket` prescribed a plain numbered list of next-step actions, which the ambient option format overrode on every run, by including the shared option format and marking each action at the strength that the evidence behind its verdict supports. (#193)
46
+ - Fixes the issue that `condense-branch` left uncommitted changes in a stash shared by every worktree of the repository, or folded them into the condensed commit through `git add --all` when the stash was skipped. (#195)
47
+ - Fixes the issue that `review-pr` passed its session-context values only to `review-branch`'s steps 4–9, which left out the step that saves the review. (#196)
48
+ - Fixes the issue that `list-implementation-order` listed an umbrella ticket, one that has sub-issues, as a ticket to implement, although its children do its work. (#199)
49
+ - Fixes the issue that `entry-drafter` could write a change's delivery state, such as "takes effect once deployed", into the lede or an entry, which the merge commit keeps after the statement becomes false. (#207)
50
+ - Fixes the issue that `williamthorsen-workflow-preferences` did not stop a session from creating a branch, a worktree, or commits in a repository or ticket other than its own, and that its cross-repo sequencing rule told the session to make the upstream change itself. (#214)
51
+ - Fixes the issue that `create-ticket` reversed a Jira blocked-by link by putting the blocker in the `--out` option of `acli jira workitem link create`, when `--in` is the option that names the blocker. (#227)
52
+ - Fixes the issue that `triage-spike-findings` did not create an umbrella on Jira and parented each new ticket to the triage ticket's parent, by having it create the umbrella on Jira as on GitHub and parent each child ticket to it. (#232)
53
+ - Fixes the issue that `create-ticket` gave a Jira child of a level-0 parent, such as a `Task`, the child's own issue type, which Jira rejects under that parent, and makes `create-ticket` create the child as a subtask at the type that the new `integrations.jira.subtask_issue_type` setting declares (`Subtask` by default). (#233)
54
+
55
+ ### ⚡ Performance
56
+
57
+ - Cuts about 110 words from the shared `AGENTS.md` and the plain-speech partial, both loaded into every session, by removing a redundant example, a sentence of rationale, a repeated repair, and three sentences that describe skills or tickets without directing the agent. (#190)
58
+ - Cuts the prompt-formatting rules that the option-format and action-items guidance already states from the ambient `williamthorsen-collaboration-preferences` rulebook, which shrinks from 11,919 to 6,031 bytes in every session that loads it. (#191)
59
+ - Removes the note "(Reinforces the rule in `AGENTS.md`: intentional redundancy.)" from the option-format directive in the skills that link to the option format, because the rulebook no longer states that rule. (#191)
60
+ - Cuts the `williamthorsen-writing-preferences` rulebook from 9,234 to 7,246 bytes by moving three rarely needed reduced-object-relative cases into `skills/_data/reduced-object-relatives.md`, which the rule links to, and by removing passages that the remaining rules already direct. (#192)
65
61
  <!-- /section:release-notes -->
66
62
 
67
63
  ## Using the library
@@ -5,14 +5,8 @@
5
5
  import path from 'node:path';
6
6
  import process from 'node:process';
7
7
 
8
- import { runValidatePreferences } from '../content/scripts/validate-preferences.mjs';
8
+ import { runValidatePreferencesCommand } from '../content/scripts/validate-preferences.mjs';
9
9
 
10
10
  const programName = path.basename(process.argv[1] ?? 'codeassembly-validate-preferences', '.js');
11
11
 
12
- try {
13
- process.exitCode = await runValidatePreferences(process.argv.slice(2), process.cwd(), programName);
14
- } catch (error) {
15
- const message = error instanceof Error ? error.message : String(error);
16
- process.stderr.write(`${programName}: ${message}\n`);
17
- process.exitCode = 1;
18
- }
12
+ process.exitCode = await runValidatePreferencesCommand(process.argv.slice(2), process.cwd(), programName);
@@ -5,6 +5,7 @@ Before reporting what a change did, read the change back, and repair what you fi
5
5
  - **Claims.** Every statement about the change is read from the diff, not from what you set out to do. A claim that something was left unchanged needs the same evidence as a claim that something changed, and it is the one most often written from memory.
6
6
  - **Reach.** What the edit moved beyond its target: a parallel enumeration of the same list elsewhere, such as a README mirroring the edited source doc; sibling wording invalidated by a rename or re-framing, in a test title, a function header, or a neighboring doc; declaration ordering after an insertion; and adjacent behavior that a changed guard now covers or stops covering.
7
7
  - **Placement.** Each hunk that writes guidance or documentation states a fact only where the fact is defined, such as the config that declares it, the code, its owning README section, or a rulebook, and elsewhere points to that source. A list copied from a config, or a paragraph that restates a rulebook, is a copy that drifts.
8
+ - **Width.** Each comment line in your hunks fits the `max_line_length` that `.editorconfig` sets for its file. Reflow a line that exceeds it, from that line to the end of its paragraph, changing only whitespace. A line that whitespace changes cannot bring within the width, such as one holding a long URL, stays as it is.
8
9
  - **Class.** When the change corrects a defect, the site that you were pointed at is a sample of its class. Audit the other members before reporting, or the next reviewer finds the one that you left.
9
10
 
10
11
  A green gate is not this audit: A suite that passes reports that nothing broke, not that the record which you are about to write is true.
@@ -0,0 +1,6 @@
1
+ `unsearchedPrivateStores` names each registered `private` store that the recall did not search. A private store may contain notes that no other store has, so a recall that skipped one is partial. Whenever the list is not empty, whether or not candidates were returned, tell the user that the recall was partial and name each store by its `name`:
2
+
3
+ - For a store that a `path does not exist` warning also names, say that its path needs fixing: Neither flag can search a store whose directory is absent.
4
+ - For every other store, name the flag that would include it: `--store <name>` for that store alone, or `--all-kbs` for every registered store.
5
+
6
+ In an empty result, never report that nothing was found without this disclosure.
@@ -2,12 +2,12 @@ Speak plainly in practical documentation, in code comments, and in chat. The one
2
2
 
3
3
  Write for a reader who does not share the author's first language, and test each sentence by asking whether that reader parses it on one pass. The test is about structure, not vocabulary: A domain term stays. Use the clearest verb: A file **contains** a section (not "bears" or "carries"), a function **returns** a result (not "the function answers with the result"), a tool **reports** its findings (not "the findings arrive").
4
4
 
5
- A sentence can pass that test and still be **mannered prose**: a figure built for the sentence when a direct statement would do. "a dial worth turning" becomes "a parameter worth varying"; "this point earns its keep" becomes "this point still matters". A figure also adds connotations that the writer did not choose and cannot control. When a literal phrase is available, use it.
5
+ A sentence can pass that test and still be **mannered prose**: a figure built for the sentence when a direct statement would do. "a dial worth turning" becomes "a parameter worth varying". When a literal phrase is available, use it.
6
6
 
7
7
  A verb that fits any subject and object does not state any relation between them. "The file carries a section", "the record carries a version", "the change carries a flag": One verb covers three relations and therefore names none of them. Write the verb that names this one: contains, declares, sets. Such a verb passes both tests above, because it is common rather than built for the sentence; therefore, test for it separately.
8
8
 
9
9
  When a sentence makes data, a file, or a part of a document the subject of an action that an agent or a command performs, the reader cannot tell who acts: "the roots join the recorded ones", "the body reaches the approval gate". A passive that omits an actor that the reader needs hides the actor in the same way. Make the actor the subject. In instructions to an agent, the actor is usually the agent, and the sentence is an imperative: "Show the body to the user at the approval gate." In a document that describes code, the actor is the command or function that acts: "`record` adds the roots to the recorded ones"; an imperative there would give the action to the reader. A subject stays when it performs its verb, animate or not, or when its verb states a relation: A function returns a result, and a file contains a section.
10
10
 
11
- "No" used as a determiner, in any position, leaves the reader unable to tell whether the thing does not exist or exists and fails the condition, and it hides where the absence was observed: "There's no Vercel CLI" was meant as "the Vercel CLI isn't installed on this machine" and read as "the Vercel CLI doesn't exist". As the subject of a relative clause, it also hides the actor and states a claim about every actor when the sentence is about one. Negate the verb, and name the scope in which the absence was observed: "the Vercel CLI isn't installed on this machine", "doesn't publish any build output", "a field not covered by any of the tests", "a condition that the user could not observe". Swapping in another negative quantifier is not a repair, because "a field that none of the tests names" keeps the construction. When existence is itself in question, state it separately: "the package doesn't have any tests". A site stays when it is a fixed idiom, such as "no longer", "no matter", or "no more than"; the pronoun "no one"; a hyphenated compound, such as "no-op"; a verbless label, heading, or table cell, which does not contain a verb to negate; or code, a quotation, or a marked exhibit.
11
+ "No" used as a determiner, in any position, leaves the reader unable to tell whether the thing does not exist or exists and fails the condition, and it hides where the absence was observed: "There's no Vercel CLI" was meant as "the Vercel CLI isn't installed on this machine" and read as "the Vercel CLI doesn't exist". As the subject of a relative clause, it also hides the actor and states a claim about every actor when the sentence is about one. Negate the verb, and name the scope in which the absence was observed: "doesn't publish any build output", "a field not covered by any of the tests", "a condition that the user could not observe". Swapping in another negative quantifier is not a repair, because "a field that none of the tests names" keeps the construction. When existence is itself in question, state it separately: "the package doesn't have any tests". A site stays when it is a fixed idiom, such as "no longer", "no matter", or "no more than"; the pronoun "no one"; a hyphenated compound, such as "no-op"; a verbless label, heading, or table cell, which does not contain a verb to negate; or code, a quotation, or a marked exhibit.
12
12
 
13
13
  This rule takes precedence over the register of the surrounding documents, this guidance included.
@@ -60,9 +60,9 @@ Determine whether the described work has been implemented. The output format dep
60
60
 
61
61
  ### Advisability
62
62
 
63
- Determine whether the ticket should be implemented as written. Synthesize the four facets defined in `{harness_home_dir}/skills/_data/ticket-evaluation.md` (problem reality, scope correctness, solution soundness, title accuracy) against the codebase and ticket text.
63
+ Determine whether the ticket should be implemented as written. Synthesize the five facets defined in `{harness_home_dir}/skills/_data/ticket-evaluation.md` (problem reality, scope correctness, solution soundness, criterion settleability, title accuracy) against the codebase and ticket text.
64
64
 
65
- 1. Apply each facet in turn. Does the underlying observation hold? Is scope right at the appropriate class? Does the proposed solution treat the cause? Does the title accurately describe the work?
65
+ 1. Apply each facet in turn. Does the underlying observation hold? Is scope right at the appropriate class? Does the proposed solution treat the cause? Can the pull request of a code ticket show each criterion to hold or fail at merge? Does the title accurately describe the work?
66
66
  2. Synthesize a verdict from the facet results.
67
67
  3. Emit one prose evidence bullet per concern raised by the facets. Do not prefix a bullet with its facet name. Omit bullets entirely when the verdict is `advisable`.
68
68
 
@@ -70,7 +70,7 @@ Bias toward `advisable`: For a recommendation dimension, false-positive concerns
70
70
 
71
71
  **Verdicts:**
72
72
 
73
- - 🟢 `advisable`: Recommend implementing as written; all four facets pass scrutiny
73
+ - 🟢 `advisable`: Recommend implementing as written; all five facets pass scrutiny
74
74
  - 🟠 `questionable`: Recommend with concerns; one or more facets raise issues warranting human review
75
75
  - 🔴 `inadvisable`: Recommend against implementing as written; rework needed before proceeding
76
76
 
@@ -59,6 +59,8 @@ helpers:
59
59
  out: skills/curate-feedback/curate-feedback.mjs
60
60
  - entry: ../src/lesson-clusters/cli.ts
61
61
  out: skills/lesson-clusters/lesson-clusters.mjs
62
+ - entry: ../src/implementation-order/cli.ts
63
+ out: skills/implementation-order/implementation-order.mjs
62
64
  - entry: ../src/triage-feedback/cli.ts
63
65
  out: skills/triage-feedback/triage-feedback.mjs
64
66
  - entry: ../src/triage-spike-findings/cli.ts
@@ -67,3 +69,9 @@ helpers:
67
69
  out: scripts/check-branch-currency.mjs
68
70
  - entry: ../src/check-prose/cli.ts
69
71
  out: scripts/check-prose.mjs
72
+ - entry: ../src/condense-branch/cli.ts
73
+ out: skills/condense-branch/condense-branch.mjs
74
+ - entry: ../src/write-progress-report/cli.ts
75
+ out: skills/write-progress-report/write-progress-report.mjs
76
+ - entry: ../src/list-gh-progress-items/cli.ts
77
+ out: skills/list-gh-progress-items/list-gh-progress-items.mjs
@@ -7,11 +7,13 @@ members:
7
7
  - accessibility-conventions
8
8
  - cli-conventions
9
9
  - command-output-conventions
10
+ - cross-repo-migration-conventions
10
11
  - generated-content-policy
11
12
  - machine-readable-output-conventions
12
13
  - readme-conventions
13
14
  - shared-data-conventions
14
15
  - ui-copy-conventions
16
+ - visual-design-conventions
15
17
  skills:
16
18
  - capture-event
17
19
  - capture-feedback
@@ -25,6 +27,8 @@ Membership is per-artifact and enumerated in full rather than by dependency root
25
27
 
26
28
  The skills belong here on different grounds. A rulebook of the personal collection names `capture-feedback` in a body token, and `capture-feedback` names `capture-event` in another. Because a collection cannot be closed over an artifact of lesser standing, both were promoted. `capture-event`'s promotion was forced by that chain rather than chosen on its own merits. It is the one member to re-examine first. `capture-feedback` qualifies on its own terms: It does not name any store, declares the registry needed by a capture, and sends a record to the store that the registry's `feedback_kb` names.
27
29
 
30
+ `cross-repo-migration-conventions` qualifies on its own terms as well. Each rule that it states follows from a mechanism that any migration across repositories meets, such as a ticket body that freezes once work starts, a session that ends at merge, and a shared host that runs the checks of every repository that uses it, rather than from a preference, and it does not name any author, repository, host, or tracker. Its body does not contain any invocation token, so its closure is empty.
31
+
28
32
  `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.
29
33
 
30
34
  `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.
@@ -42,3 +46,5 @@ Adding a skill that declares a guidance hook has a drawback that the current mem
42
46
  `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.
43
47
 
44
48
  `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.
49
+
50
+ `visual-design-conventions` qualifies on its own terms as well. What it asks of a page's marks, spacing, alignment, and roles follows from how a reader sees a page's structure before reading its text, rather than from a preference, and it leaves taste to each author's own rulebooks. It does not name any author, repository, product, or tool, and a project's design system takes 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.
@@ -11,6 +11,7 @@ members:
11
11
  - williamthorsen-ticketing-preferences
12
12
  - williamthorsen-tooling-preferences
13
13
  - williamthorsen-typescript-preferences
14
+ - williamthorsen-visual-design-preferences
14
15
  - williamthorsen-workflow-preferences
15
16
  - williamthorsen-writing-preferences
16
17
  skills:
@@ -19,7 +20,7 @@ members:
19
20
 
20
21
  # William Thorsen
21
22
 
22
- The personal collection. Membership claims that an artifact was examined and found deliberately fitted to one author rather than generally applicable. What disqualifies each member from `recommended` is the reason it belongs here: The nine rulebooks state one author's preferences as rules that another team would decide differently, and `people-report` serves a domain in which one author works rather than one that every project shares.
23
+ The personal collection. Membership claims that an artifact was examined and found deliberately fitted to one author rather than generally applicable. What disqualifies each member from `recommended` is the reason it belongs here: The ten rulebooks state one author's preferences as rules that another team would decide differently, and `people-report` serves a domain in which one author works rather than one that every project shares.
23
24
 
24
25
  Its closure contains `capture-feedback` and `capture-event` in `recommended` and nothing else, which makes declaring it safe alongside the public collection.
25
26
 
@@ -1,12 +1,14 @@
1
1
  ---
2
2
  slug: accessibility-conventions
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.'
3
+ description: 'Accessibility of interfaces: the aim beyond the floors, usability before style, contrast and size floors for text, the placement, model, and states of interactive controls, the explanation of an action''s consequence at the control, 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: '5'
5
+ version: '6'
6
6
  ---
7
7
 
8
8
  # Accessibility conventions
9
9
 
10
+ The rules below are floors. Aim beyond them, for an interface with which its users work confidently and that they enjoy using, and reach it by following a good established model, as the named-model rule states.
11
+
10
12
  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
13
 
12
14
  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.
@@ -23,6 +25,7 @@ Check contrast whenever colour tokens are defined or changed. Compute the WCAG c
23
25
 
24
26
  - **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
27
  - **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.
28
+ - **Consequence at the control.** An action whose consequence is not evident from its label, especially one that publishes, deletes, or hands work to a later step, explains that consequence where the control is, and not only in external documentation. The consequence is not evident when a user who has not read the documentation could not say what the action changes, who sees the result, or whether it can be undone. The explanation of an action that cannot be undone is visible at rest: a helper line beside the control, or, for an action repeated on every row of a list, one line where the list starts. The explanation of an action that can be undone may instead sit in a toggletip: a button beside the control that shows the explanation on click, Enter, and tap, and hides it on Escape. A tooltip that opens only on hover never carries the explanation alone, because touch users and many keyboard users cannot open it, and content that appears on hover or focus meets SC 1.4.13. The control names its explanation through `aria-describedby`. Render every explanation in a product through one shared component, so that every control explains itself the same way. Example: ❌ Each row of a review queue shows Publish and Reject, and nothing more. ✅ One line above the queue states that Publish shows the item to every reader of the site and cannot be undone.
26
29
 
27
30
  ## Glanceable state
28
31
 
@@ -53,6 +56,6 @@ Put the states in a base style or a shared component rather than setting them at
53
56
 
54
57
  ## Checking in a browser
55
58
 
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.
59
+ 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 action whose consequence is not evident has its explanation, visible at rest when the action cannot be undone, and otherwise reachable by keyboard and under touch emulation. 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.
57
60
 
58
61
  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.
@@ -0,0 +1,27 @@
1
+ ---
2
+ slug: cross-repo-migration-conventions
3
+ description: 'A migration that spans repositories, such as a move to a new runtime version or convention: one umbrella ticket with a child per repository, shared runtimes moved first, the umbrella''s comments as the ledger of lessons, contract changes decided before any child acts, and what each child reads, posts, and verifies. Consult before creating an umbrella ticket for such a migration, or a child of one.'
4
+ delivery: [skill]
5
+ version: '1'
6
+ ---
7
+
8
+ # Cross-repo migration conventions
9
+
10
+ A migration that spans repositories moves each repository to the same new version or convention, such as a runtime upgrade. The ticketing preferences already give each repository its own ticket and record the order as blocked-by relations, upstream first; the rules below add what such a migration needs beyond that.
11
+
12
+ ## The umbrella
13
+
14
+ - **Children.** The umbrella has one child per repository, linked as a sub-issue, and "Every child is closed" as its acceptance criterion.
15
+ - **Shared runtimes first.** A runtime that several repositories use, such as a reusable CI workflow, a shared host that runs checks, or the toolchain installed on each machine, is upstream of every repository that uses it, and its child blocks theirs. When the shared runtime can read each repository's pin, as a reusable workflow can, its child makes it do so, and each repository then moves with its own child. A runtime with one version for every repository, such as a shared host, moves every repository that uses it, including those that have not moved yet; the child that moves it states so on the ledger.
16
+ - **The ledger.** The umbrella's comments record what each child found. A ticket is readable and writable from a session in any repository, so the ledger does not need a branch in a shared repository, and a comment can be added after the umbrella's body is frozen by the start of work. The body states the plan; the comments state what the plan met.
17
+ - **Per-machine steps.** A step that each machine needs follows [who applies the change](../../skills/_data/design-priorities.md#who-applies-the-change). When it reaches the script rung, post the script on the ledger as well as committing it, and open a ticket for each machine that has not run it.
18
+
19
+ ## Contract changes
20
+
21
+ The umbrella decides a step that changes a published contract, such as a package's supported runtime floor, before any child acts on it: It states the problem that the step solves, weighs a step that keeps the contract against it, such as testing the claim that the floor makes, and counts the consumers outside the migrated repositories as well as those inside. A contract change found wrong after children have executed it costs a revert in each repository that executed it, and a release for each one that published it. When the umbrella reverses such a decision, it closes the children not yet done as not planned and adds the reverts as children.
22
+
23
+ ## Each child
24
+
25
+ - **Before the work.** The child reads the ledger, and its `## Context` names the lessons that apply to its repository and those that do not, with the fact that rules each one out.
26
+ - **The ledger comment.** The child posts its comment before merge, naming its pull request: Merging closes the child, and the session that merges ends there, so a comment due after merge is the one that gets skipped. The comment states what broke and how it was fixed, or that nothing did, and each fact on which a later repository can act. The comment leaves out the lessons that did not apply, because the child's `## Context` already records them. A fact learned after merge goes in a later comment. A rollout step that follows the merge as planned is named in the comment with its command, and a later comment reports its result. A comment that narrows or corrects an earlier lesson links to the comment that it revises.
27
+ - **Verification.** Each check that the comment reports names the runtime on which it ran. A check delegated to a shared host runs on that host's runtime, which may not be the version that the repository pins; a child verifying its own move runs the check where that version is installed, or relies on CI that installs it.
@@ -3,14 +3,14 @@ slug: live-worktree-policy
3
3
  description: How a repository with a `live` worktree deploys, and where changes to it are authored.
4
4
  standalone: wanted in the repositories that have a `live` worktree, which declare it directly
5
5
  delivery: ambient
6
- version: '3'
6
+ version: '4'
7
7
  ---
8
8
 
9
9
  # Live worktree policy
10
10
 
11
11
  A repository that keeps a worktree on a `live` branch deploys from that worktree, and never from the main one. Deployed configuration, installed commands, and loaded extensions all resolve through it, so a path derived from the main worktree names a file that nothing on the machine reads.
12
12
 
13
- Because `git worktree list` reports every worktree of a repository from any one of them, a `live` row identifies a participating repository and gives the deployment worktree's path in the same line. That worktree is named `{path}.live`, where `{path}` is the main worktree's path: `~/repos/projects/codeassembly` is accompanied by `~/repos/projects/codeassembly.live`. If the machine has the repo registry, `thor-repo list --tag live` enumerates the tagged set; for a registry whose entries do not have the tag, it returns nothing, which is not evidence that a repository does not deploy from a `live` worktree.
13
+ Because `git worktree list` reports every worktree of a repository from any one of them, a `live` row identifies a participating repository and gives the deployment worktree's path in the same line. That worktree is named `{path}.live`, where `{path}` is the main worktree's path: `~/repos/oss/codeassembly` is accompanied by `~/repos/oss/codeassembly.live`. If the machine has the repo registry, `thor-repo list --tag live` enumerates the tagged set; for a registry whose entries do not have the tag, it returns nothing, which is not evidence that a repository does not deploy from a `live` worktree.
14
14
 
15
15
  A merged change is deployed to the machine only once `live` is advanced to it. Until then the deployed behavior is the old one, so a change is not live while `live` still points at its predecessor.
16
16
 
@@ -2,7 +2,7 @@
2
2
  slug: ui-copy-conventions
3
3
  description: 'Text in a product surface: written for the person who returns to the page, with rules for labels, helper text, errors, and empty states, and a copy budget. Consult before writing labels, helper text, messages, or empty states for a page, a prototype, or a UI component.'
4
4
  delivery: [skill]
5
- version: '2'
5
+ version: '3'
6
6
  ---
7
7
 
8
8
  # UI copy conventions
@@ -14,7 +14,7 @@ When a project names its own content guidelines, such as a design system's, thos
14
14
  ## Rules
15
15
 
16
16
  - **Labels** are nouns. **Buttons** are verbs that name the action that they perform, except a toggle, whose label names what it governs and stays the same in both states, as {rulebook:accessibility-conventions} states.
17
- - **Helper text** states a constraint or a consequence: the format that a field accepts, or what an action changes.
17
+ - **Helper text** states a constraint or a consequence: the format that a field accepts, or what an action changes. The explanation that the consequence-at-the-control rule of {rulebook:accessibility-conventions} requires states what the action changes, who sees the result, and whether it can be undone, and it counts toward the copy budget's one line of helper text.
18
18
  - **An error** names the problem and the fix.
19
19
  - **Register.** A sentence never explains the page, reassures, congratulates, or narrates the reader ("you are done", "you can…").
20
20
  - **Minimizers.** Leave out "simply" and "just".
@@ -0,0 +1,58 @@
1
+ ---
2
+ slug: visual-design-conventions
3
+ description: 'Visual design of interfaces: marks for the exception, colour as an encoding channel, padding inside bounded containers, alignment, an appearance that follows each element''s role, tags, product identity, and the browser check of a visible change. Consult before writing an artifact page, a prototype, or a mockup, before writing CSS or a UI component, and before finishing or reviewing a change to a visible component.'
4
+ delivery: [skill]
5
+ version: '2'
6
+ ---
7
+
8
+ # Visual design conventions
9
+
10
+ A reader sees a page's structure through its marks, its spacing, and its alignment before reading its text. These conventions state the principles that hold whatever the style; a taste, such as one colour scheme over another, does not belong here. They apply to a prototype or a mockup exactly as they apply to a released interface, and {rulebook:accessibility-conventions} sets the floors beneath them.
11
+
12
+ When a project names its own design system, that system takes precedence where the two conflict.
13
+
14
+ ## Marks
15
+
16
+ A mark, such as bold, italics, a colour, a highlight, or a badge, is for the exception, and the common state is unmarked. A mark that covers most of a text distinguishes nothing, and the reader can no longer find what it was meant to set apart. The glanceable-state rule of {rulebook:accessibility-conventions} names the states that a list marks. Example: ❌ Every term in a paragraph is bold. ✅ Only the term that the paragraph defines is bold.
17
+
18
+ ## Colour as encoding
19
+
20
+ Colour is an encoding channel: Use it to tell kinds and states apart, rather than leaving weight and style to do all the work. Pair each colour with a second cue, as the glanceable-state rule of {rulebook:accessibility-conventions} requires. Example: ❌ Errors, warnings, and notes differ only in weight and italics. ✅ Each has a colour and an icon of its own.
21
+
22
+ ## Spacing
23
+
24
+ Text never touches the edge of a container that has a visible boundary, such as a border or a fill: Padding separates the text from every edge. A container without a visible boundary does not have an edge that the text could touch. Example: ❌ A badge's label runs into its border. ✅ The label has padding on every side.
25
+
26
+ ## Alignment
27
+
28
+ Every block aligns with an edge or an axis of another block on the page. A block does not float in the vertical middle of a region that it does not fill: It starts where the region's content starts, and an empty state sits where the content that it replaces would begin. A dialog centred in the viewport over the page is not such a block. Example: ❌ An empty-list message floats in the middle of a tall panel, aligned with nothing. ✅ The message starts at the top of the panel, on the list's left edge.
29
+
30
+ Within a block, text and elements are start-aligned, so that each one shares an edge with its neighbours: Everything aligns with something. A column of numbers aligns on its end edge instead, so that digits of the same place value line up. Centring is the rare exception, and it is permitted only for a dialog centred in the viewport, as above, a short single-line label inside a button or a tag, and an icon in a square control. Centred multi-line text never qualifies: Each of its lines starts at a different place, and the reader's eye has to find each start. Example: ❌ A dialog centres its heading and its three-line body, and each line starts at a different place. ✅ The heading and the body start on the dialog's left edge.
31
+
32
+ ## Roles
33
+
34
+ The element follows semantics, and the appearance follows the role:
35
+
36
+ - **Link.** An `<a>` navigates, and a text link looks like a link: a colour that sets it apart from the text around it, with a cue beyond colour, such as an underline.
37
+ - **Navigation item.** An item of a navigation bar or a menu looks like navigation: It sits in the navigation region, and the item for the current view is marked.
38
+ - **Button.** A `<button>` acts, and it looks like a button, as the interaction-state rules of {rulebook:accessibility-conventions} state.
39
+ - **Tag.** A value that tags or classifies an item, such as a status or a category, looks like a tag: a compact shape with a fill or a border, set apart from the body text.
40
+
41
+ Example: ❌ "View details" and "Delete" are both blue underlined text. ✅ "View details" is a link to the detail view, and "Delete" is a button.
42
+
43
+ ## Identity
44
+
45
+ The product's name and a link to its home view are visible on every view. A product does not ship a template's placeholder identity, such as the template's favicon.
46
+
47
+ ## Checking in a browser
48
+
49
+ Check every change to a visible component in a browser before reporting it finished or reviewed, alongside the check in {rulebook:accessibility-conventions}. On each new or changed view, confirm each of these:
50
+
51
+ - The text in each bordered or filled container has padding on every side.
52
+ - Each block aligns with another block, and each block that does not fill its region starts where the region's content starts.
53
+ - Text and the elements within each block are start-aligned, a column of numbers is end-aligned, and centred text appears only in a button's or a tag's single-line label.
54
+ - Marks fall on exceptions only.
55
+ - Each link, navigation item, button, and tag looks like its role.
56
+ - The product's name and home link are visible, and the favicon is the product's own.
57
+
58
+ A reading of the diff does not replace this check: Padding and alignment show only once the page renders. When a browser is not available, report that the check did not run and name the views that it would have covered. Never report it as passed.
@@ -2,7 +2,7 @@
2
2
  slug: williamthorsen-collaboration-preferences
3
3
  description: William Thorsen's personal preferences for how an agent collaborates -- the persona that it adopts, and the form that its prompts take.
4
4
  delivery: ambient
5
- version: '18'
5
+ version: '19'
6
6
  ---
7
7
 
8
8
  # William Thorsen's collaboration preferences
@@ -28,21 +28,11 @@ A question receives an answer, not a procedure for the developer to run: When th
28
28
 
29
29
  Hand over a part that takes more than one command as one paste-ready script, which runs every step, cleans up after itself, and prints only the facts that you need, so that the developer pastes once and replies once. Never build up a check by asking for one command per turn. When the developer's shell can read your files, also write the script to a file and give its path, so that the developer can rerun the check without pasting it again. Before running or handing over a check of a GUI application, confirm which machine your commands run on, such as by comparing `hostname` with the machine that displays the application, rather than assume that the two are the same.
30
30
 
31
- The handoff has a recognizable sign. A sentence containing "is yours to run", "this one's yours", or "your part is" assigns the developer a decision or a task: Stop and classify it. Give a decision your recommendation and its reason, per "Prompt formatting" below, and take a task up the ladder. Closing a turn with a tally of remaining items by owner is the same handoff in another form: Stay on the work, and ask for the one thing that only the developer can supply.
31
+ The handoff has a recognizable sign. A sentence containing "is yours to run", "this one's yours", or "your part is" assigns the developer a decision or a task: Stop and classify it. Give a decision your recommendation and its reason, and take a task up the ladder. Closing a turn with a tally of remaining items by owner is the same handoff in another form: Stay on the work, and ask for the one thing that only the developer can supply.
32
32
 
33
33
  ## Prompt formatting
34
34
 
35
- Mark the options before asking, and read the markers: Render a menu only when the two strongest options are both ■■□, when the list is unmarked, or when the decision is in the gated class. Decide every other field: State the decision in one line with its reason, record it, and proceed, putting the rejected alternative in a clause rather than a numbered option. Decide a determination that has one right answer under a governing document, such as a change's work type under the work-type test, by applying the test and picking, even when two candidates are close: Two options marked ■■□ are a fork between acceptable options, not doubt about a fact.
36
-
37
- The gated class is closed: the shape of a public API or a contract; remote shared state, such as a ticket edit, a push, a merge, or the creation of a branch or a ticket; data loss or any action that cannot be undone; spend or budget; and a preference for which you do not have any evidence, which includes a templated next-steps menu. Decide everything else yourself by default; verification is never in the class. Never decide a gated action in your own voice: The developer authorizes it; recommend, build on the recommendation provisionally, and ask at the checkpoint. Building on it means doing the work that depends on the answer; do not take the gated action itself until the developer authorizes it.
38
-
39
- Proceed provisionally: Do everything that does not depend on an answer first, and raise an ask only when the work is blocked or at the checkpoint. In a skill without a phase structure, or in work outside a skill, treat the skill's own approval gate, or the end of the work, as the checkpoint. Collect the asks that survive the gate into one review at the checkpoint, never one per turn. Write every decision that you take in place of an ask into the plan's `## Decisions taken` section with its one-line reason, or into the turn's summary when the work does not have a plan; a silent decision is worse than an ask. Start each line that states a decision awaiting the checkpoint with 🔲, in the record and in a turn's narrative alike, and drop the marker once the developer approves the checkpoint at which you presented the decision.
40
-
41
- Never rank the options by your own elapsed time, round trips, or effort. You measure all three yourself, and that measure counts the developer's context switch and review cycles as nothing, so measuring one does not make the call yours, and a more accurate measurement still cannot rank them. Ordering follows from this: When the order changes the code or the total effort, recommend it and mark it, naming the delay that it causes and saying nothing about delay when none is involved; when the outcomes are identical and only the timing differs, present the delay that each option causes, render the options unmarked, and put the choice at the checkpoint.
42
-
43
- An ask costs the developer a context switch and idles the session until the answer arrives; a recorded decision costs them a word to overrule. Full spec: [recommendation-gradient.md](../../skills/_data/recommendation-gradient.md).
44
-
45
- End every response that asks for something with a labelled action-items block that contains every ask and nothing else; when a skill defines its own canonical block for asks, use that block instead. Prose above may discuss; only the block may ask. Before ending a turn, sweep the draft for anything that invites a response: A soft offer -- "let me know if", "say the word and I will", "worth knowing", "I can also" -- is an ask, and leaving it in the narrative is how asks get missed. So is an environment blocker that remains once you climb the ladder in "Handoffs": Ask for the resource that its third rung names, and a blocker left in the prose is a defect. Do not add a block to a response without an ask. When the block has more than one ask, or more than one independently-numbered list, label each with its identifier (`A` for an action, `Q` for a question); a single ask needs none. Full spec: [action-items.md](../../skills/_data/action-items.md).
35
+ An environment blocker that remains once you climb the ladder in "Handoffs" is an ask like any other: Ask for the resource that its third rung names, and a blocker left in the prose is a defect.
46
36
 
47
37
  When the developer signals overload, such as "I can't do this any more" or a count of the commands that they have run, stop adding asks: Do what you can, say once what is left undone, and end the turn without an ask and without an action-items block. Stay in that mode in every later turn until the developer asks for something.
48
38
 
@@ -50,15 +40,10 @@ When prompting the user for input, never use interactive UI controls (pop-up, ar
50
40
 
51
41
  - **Confirmation prompts** (the user's response is approve-or-redirect; "no" means "let's adjust or discuss," not a concrete alternative action): End with `👍🏼👎🏼`.
52
42
  - **All other questions** (open-ended, clarifications): End with `🤔`
53
- - **Numbered options (2 or more choices)**: Follow the recommendation-gradient convention, marking each option ■■■/■■□/■□□/□□□ at the strength that you actually hold. Bullets report the weight of each option, not a balance between the options, so an uneven menu is the accurate one when the options differ in quality. Write a `➕` or `➖` only when it is real: It must be false for at least one other option, and a reader who believed it must pick differently. State in a `➖` what breaks or what it costs, and for whom; cut one that you cannot state that way, and never keep a minor con by deleting its qualifier. Never add a bullet to fill a slot or to balance the options. Leave an option without a real bullet bare, and when every option lacks one, let the markers alone convey the recommendation. Before rendering, check the leader, in a gated decision as in any other, because the marker tells the developer how much deliberation the ask needs: State as an alternative's `➖` any drawback that disqualifies it, including one that follows from the constraints and acceptance criteria of the work at hand, cut each `➖` on the strongest option that a reader would not act on, mark it ■■■ when every alternative has a disqualifying `➖`, and re-apply the gate. This covers every option-style list with substantive tradeoffs, including templated next-steps menus and yes/no choices in which both paths are concrete actions (rendered as a 2-option gradient list rather than `👍🏼👎🏼`). When a response has 2+ such lists, label each with its identifier (`A1`/`A2` for actions, `Q1`/`Q2` for questions). Full spec: [recommendation-gradient.md](../../skills/_data/recommendation-gradient.md).
54
43
 
55
44
  Examples:
56
45
 
57
46
  - "Do you want me to start implementation? 👍🏼👎🏼"
58
- - "Does this design look correct? 👍🏼👎🏼"
59
- - "Should I proceed with this approach? 👍🏼👎🏼"
60
- - "Apply these revisions (say no if you'd like to adjust something else first)? 👍🏼👎🏼"
61
47
  - "Which color scheme would you prefer? 🤔"
62
- - "What additional features should I include? 🤔"
63
48
 
64
49
  **Comprehension contract for `👍🏼👎🏼`.** If the user clearly affirms ("yes", "looks good", "go ahead", 👍), proceed. If they clearly negate ("no", "stop", 👎), do not. Anything else -- including positive commentary that isn't a clear go-ahead -- is conversation, not inferred approval. Never treat a clear affirmation as ambiguous, and never treat an ambiguous response as a clear affirmation. When in doubt, treat as conversation.