codeassembly-guidance 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/.meta/changelog.json +306 -0
  2. package/CHANGELOG.md +73 -0
  3. package/README.md +55 -4
  4. package/content/_partials/finding-grades.md +4 -0
  5. package/content/codeassembly-content.yaml +2 -0
  6. package/content/collections/recommended.md +5 -2
  7. package/content/guidance/_harnesses/rovo/AGENTS.md +0 -1
  8. package/content/guidance/rulebooks/accessibility-conventions.md +26 -6
  9. package/content/guidance/rulebooks/cli-conventions.md +17 -2
  10. package/content/guidance/rulebooks/codeassembly-content-specification.md +11 -11
  11. package/content/guidance/rulebooks/machine-readable-output-conventions.md +85 -0
  12. package/content/guidance/rulebooks/ui-copy-conventions.md +2 -2
  13. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +10 -10
  14. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +7 -3
  15. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +3 -1
  16. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +5 -5
  17. package/content/scripts/check-prose.mjs +1 -1
  18. package/content/scripts/describe-change.mjs +68 -68
  19. package/content/skills/_data/action-items.md +2 -2
  20. package/content/skills/_data/artifact-conventions.md +20 -10
  21. package/content/skills/_data/concision.md +1 -1
  22. package/content/skills/_data/entry-points.md +37 -0
  23. package/content/skills/_data/recommendation-gradient.md +6 -6
  24. package/content/skills/_data/spike-conventions.md +13 -3
  25. package/content/skills/_data/ticket-source-resolution.md +21 -4
  26. package/content/skills/_data/title-templates.md +4 -4
  27. package/content/skills/_partials/commit-title-rendering.md +2 -1
  28. package/content/skills/_partials/next-steps-after-plan.md +4 -3
  29. package/content/skills/_partials/option-format.md +8 -8
  30. package/content/skills/_partials/plan-template.md +3 -1
  31. package/content/skills/_partials/resolve-plan-and-ticket.md +22 -0
  32. package/content/skills/_partials/split-launch-prompts.md +1 -1
  33. package/content/skills/_partials/ticket-criteria-conventions.md +2 -0
  34. package/content/skills/analyze-performance/SKILL.md +102 -0
  35. package/content/skills/analyze-performance/analyze-performance.mjs +70 -0
  36. package/content/skills/assess-code-health/SKILL.md +16 -14
  37. package/content/skills/assess-code-health/assess-code-health.mjs +29 -28
  38. package/content/skills/assess-usability/SKILL.md +5 -3
  39. package/content/skills/convert-agent-prompt/SKILL.md +60 -0
  40. package/content/skills/create-commit/SKILL.md +10 -5
  41. package/content/skills/create-pr/SKILL.md +11 -11
  42. package/content/skills/create-ticket/SKILL.md +1 -0
  43. package/content/skills/design-and-plan/SKILL.md +2 -2
  44. package/content/skills/implement-plan/SKILL.md +1 -28
  45. package/content/skills/index-prototypes/SKILL.md +36 -17
  46. package/content/skills/index-prototypes/index-prototypes.mjs +14 -14
  47. package/content/skills/investigate-spike/SKILL.md +48 -0
  48. package/content/skills/prepare-prototype-brief/SKILL.md +17 -13
  49. package/content/skills/refine-plan/SKILL.md +7 -4
  50. package/content/skills/refine-prototype/SKILL.md +5 -5
  51. package/content/skills/review-branch/SKILL.md +7 -7
  52. package/content/skills/review-criteria/SKILL.md +3 -3
  53. package/content/skills/review-gh-pr/SKILL.md +1 -1
  54. package/content/skills/revise-prose/SKILL.md +9 -8
  55. package/content/skills/revise-prose/revise-prose.mjs +2 -2
  56. package/content/skills/start-ticket/SKILL.md +27 -0
  57. package/content/skills/summarize-change/SKILL.md +17 -9
  58. package/content/skills/testing-conventions/SKILL.md +12 -1
  59. package/content/skills/triage-spike-findings/SKILL.md +31 -12
  60. package/content/skills/typescript-testing-conventions/SKILL.md +40 -0
  61. package/content/subagents/_data/claude.yaml +3 -0
  62. package/content/subagents/code-health-assessor.md +4 -4
  63. package/content/subagents/disposition-challenger.md +3 -4
  64. package/content/subagents/entry-drafter.md +2 -2
  65. package/content/subagents/handoff-reviewer.md +1 -1
  66. package/content/subagents/prototype-builder.md +69 -0
  67. package/content/subagents/usability-assessor.md +1 -1
  68. package/package.json +5 -4
  69. package/schemas/preferences.v1.json +1 -1
  70. package/schemas/work-types.v1.json +1 -1
  71. package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +0 -4
@@ -84,7 +84,9 @@ Both are optional, and each is recorded as an override beside the consolidated r
84
84
  3. **Compose title**: Compose the change string per [`title-voice.md`](../_data/title-voice.md).
85
85
  - The change summary's own heading prefixes that string with the ticket reference for identification: `{ticket_ref} {title}`, or just `{title}` when `ticket_ref` is null.
86
86
 
87
- 4. **Compose `## Why`** per the output format below. `## What` and `## Details` both come from what step 5 draws, so neither exists until step 8. Step 6's writing-rules check reads `## Why` with the drafted passages.
87
+ 4. **Compose `## Why`, and `## How to test` when the change has a surface to exercise**, per the output format below. `## What` and `## Details` both come from what step 5 draws, so neither exists until step 8. Step 6's writing-rules check reads `## Why` and `## How to test` with the drafted passages.
88
+
89
+ Write `## How to test` only when the diff changes a surface that a person sees or operates: a page, a UI component, or a command's output. Otherwise omit the section, heading included. Compose it from the diff and the ticket as numbered steps, each stating where to go (the route, the page, or the command, and how to start the app when the repository does not make that obvious), what to do there, and what the reviewer should observe. Cover only what CI does not assert: Never list automated checks, such as formatting, linting, typechecking, or tests.
88
90
 
89
91
  5. **Draft the lede and the entries via `entry-drafter`**: Resolve the tier by looking up the effective type from step 2 in [work-types.json](../_data/work-types.json); if there is none, use `internal`. Then dispatch the `{subagent:entry-drafter}` subagent via the {tool:Task} tool with this block:
90
92
 
@@ -106,19 +108,19 @@ Both are optional, and each is recorded as an override beside the consolidated r
106
108
 
107
109
  On a first dispatch, take the drafter's `## Lede` section as it stands; step 9 makes it `## What`, and later steps do not rewrite it. A redispatch returns every replacement under `## Entries` and does not return a `## Lede` section at all, so the lede that it keeps is whichever text the placement above left in the lede's place. Parse the `## Entries` fence as YAML. Each entry declares `type`, `scopes`, `breaking`, and `text`, and `migration` when the entry calls for one. Read the `## Report` for any source that the drafter could not access. Step 6 checks each entry's `type`.
108
110
 
109
- 6. **Audit the lede and the entries.** The first three checks apply to the lede, to each entry's `text`, and to each entry's `migration` alike, except as the subject check states, and each names the rejection code that its failure raises, for which a redispatch is the repair rather than an edit of your own. The type check applies to each entry, and raises its code against the entry's `text` alone. `scopes` and `breaking` are not prose and are never rejected; `type` is corrected by the type check and never rejected. The writing-rules check runs last, and it also reads `## Why`.
111
+ 6. **Audit the lede and the entries.** The first three checks apply to the lede, to each entry's `text`, and to each entry's `migration` alike, except as the subject check states, and each names the rejection code that its failure raises, for which a redispatch is the repair rather than an edit of your own. The type check applies to each entry, and raises its code against the entry's `text` alone. `scopes` and `breaking` are not prose and are never rejected; `type` is corrected by the type check and never rejected. The writing-rules check runs last, and it also reads `## Why` and `## How to test`.
110
112
 
111
113
  - **Verification.** Read the lede, each entry's `text`, and each `migration` against the diff from step 2. Strike a claim that the diff contradicts, and correct one that it states differently. Never add: A fact omitted from the draft was left out by the reader of the change, and supplying it here restores the weighting that the fresh-context dispatch removed. The drafter read the diff, so this check no longer supplies the draft's grounding; it catches a sentence claiming more than the diff supports, such as one that only the commit log, the ticket, or this session supports, which the diff does not contradict and which is not one to strike: `rejection: unsupported-claim`.
112
114
  - **Subject.** Read the lede's each sentence, and each entry's `text`, with "This pull request" in front of it. If that sentence is false, the verb names what the system does rather than what the change did: `rejection: subject`. This check fails most often on a change that adds something which itself acts, such as a command, a check, a rule, or a hook, because the added thing's behavior is true, interesting, and reads as a correct entry while standing in for the change. A `migration` is exempt: It is an imperative addressed to the consumer, not a sentence whose subject is the pull request.
113
115
  - **Voice.** A figurative verb, or an invented term when a plain one exists: `rejection: voice`.
114
116
  - **Type.** Apply [Work type test](#work-type-test) to the entry's outcome. When the test's type differs from the drafted `type`, or the drafted `type` does not name a key in [work-types.json](../_data/work-types.json), set `type` to the test's result and state the correction in one line with its reason. A type is a determination that you make by applying a test, not prose, so the correction is never a redispatch and never an ask. The entry's `text` is prose: When it is still written in the form that the replaced type takes, such as a `fix` entry's opening on an entry now typed `feat`, that passage fails: `rejection: type-mismatch`.
115
- - **Writing rules.** Run this check over the passages that passed every check above, and over `## Why`, so that a redispatch names one code. Write them to a scratch file, created per the path rules of [gh body file](#gh-body-file) and named `prose-check-{timestamp}.md`, as bare paragraphs separated by blank lines, without headings or list markers: the lede, each entry's `text` and each `migration` as paragraphs of their own, and each paragraph of `## Why`. Write it with a file-writing tool rather than a shell heredoc, as step 7 does. Then run:
117
+ - **Writing rules.** Run this check over the passages that passed every check above, and over `## Why` and `## How to test`, so that a redispatch names one code. Write them to a scratch file, created per the path rules of [gh body file](#gh-body-file) and named `prose-check-{timestamp}.md`, as bare paragraphs separated by blank lines, without headings or list markers: the lede, each entry's `text` and each `migration` as paragraphs of their own, each paragraph of `## Why`, and each step of `## How to test`. Write it with a file-writing tool rather than a shell heredoc, as step 7 does. Then run:
116
118
 
117
119
  ```bash
118
120
  node {harness_home_dir}/scripts/check-prose.mjs --file "{absolute path of the scratch file}" --json
119
121
  ```
120
122
 
121
- The helper runs every `revise-prose` detector over the file, reading it as Markdown, and prints one JSON document, `{ file, rules, candidates }`, in which each candidate names its `rule` and the `sentence` that contains the site. It exits 0 without candidates, 1 with candidates, and 2 on a usage error or when it cannot read the file. Read exit 1 as candidates found, not as a failure. Map each candidate to its passage by its `sentence`, and to every passage containing that sentence when more than one does. Judge each against the rule that it names, as your plain-speech and writing guidance states that rule; a watchlist word used in the sense that names its relation, such as a promise that holds, is not a violation. State a candidate judged legitimate in one line with its reason. A confirmed violation in the lede, an entry's `text`, or a `migration` fails that passage: `rejection: writing-rule`. Rewrite a confirmed violation in `## Why` yourself, since this session wrote it. Run the check again over every replaced passage.
123
+ The helper runs every `revise-prose` detector over the file, reading it as Markdown, and prints one JSON document, `{ file, rules, candidates }`, in which each candidate names its `rule` and the `sentence` that contains the site. It exits 0 without candidates, 1 with candidates, and 2 on a usage error or when it cannot read the file. Read exit 1 as candidates found, not as a failure. Map each candidate to its passage by its `sentence`, and to every passage containing that sentence when more than one does. Judge each against the rule that it names, as your plain-speech and writing guidance states that rule; a watchlist word used in the sense that names its relation, such as a promise that holds, is not a violation. State a candidate judged legitimate in one line with its reason. A confirmed violation in the lede, an entry's `text`, or a `migration` fails that passage: `rejection: writing-rule`. Rewrite a confirmed violation in `## Why` or `## How to test` yourself, since this session wrote it. Run the check again over every replaced passage.
122
124
 
123
125
  If the helper is unavailable or the call fails, relay its error, say that the summary was saved without the writing-rules check, and continue.
124
126
 
@@ -126,7 +128,7 @@ Both are optional, and each is recorded as an override beside the consolidated r
126
128
 
127
129
  Repeat step 5 with `rejection:` set to the code that the failed check names, and with the passages that failed in the `rejected` fence that step describes.
128
130
 
129
- Redispatch at most twice. After a second redispatch fails, the passages still failing are the ones that you last sent. Present those to the developer with the code, and ask for a replacement or for an explicit acceptance of each passage as it stands; place the answer, then continue to step 7 with the verified entries. If you could never place a return, show the developer each passage as the fence contained it. Take a passage rejected by the audit past step 6 only after asking the developer. Rewrite `## Why` at most twice for the writing-rules check; a confirmed violation that remains after the second rewrite goes to the developer the same way.
131
+ Redispatch at most twice. After a second redispatch fails, the passages still failing are the ones that you last sent. Present those to the developer with the code, and ask for a replacement or for an explicit acceptance of each passage as it stands; place the answer, then continue to step 7 with the verified entries. If you could never place a return, show the developer each passage as the fence contained it. Take a passage rejected by the audit past step 6 only after asking the developer. Rewrite `## Why` and `## How to test` at most twice each for the writing-rules check; a confirmed violation that remains after the second rewrite goes to the developer the same way.
130
132
 
131
133
  7. **Consolidate the change's record from the entries.** Do this before step 8, and before the frontmatter call: Step 8 reads the entries file that this step writes, and the title and the labels read the record that it produces.
132
134
  - **Write the verified entries** to a scratch file, created per the path rules of [gh body file](#gh-body-file) and named `entries-{timestamp}.yaml`. The file is a top-level YAML list of mappings, one per entry, each declaring `type`, `scopes`, `breaking`, and `text`, and `migration` when the entry has one, as the drafter returned them, with the corrections that step 6 made. Write each `text` and `migration` double-quoted, and quote any value that the drafter returned unquoted: Unquoted, a space followed by `#` opens a YAML comment, and the parse drops the rest of the text. Write it with a file-writing tool rather than a shell heredoc: `text` and `migration` are arbitrary prose containing backticks and quotes. Keep its path; steps 8 and 10 read the same file.
@@ -172,7 +174,7 @@ Both are optional, and each is recorded as an override beside the consolidated r
172
174
 
173
175
  Pass the overrides resolved in step 2, never the effective record: `resolve-merge` ranks the entries and applies the overrides itself. Omit each override flag whose field is absent, and pass `--override-breaking` only if that field is `true`.
174
176
 
175
- [`render-block`](../_data/title-templates.md#render-block) states the output, which is JSON; the last command decodes it and prints the `block` field. Render and decode in one Bash invocation, and write the printed block verbatim below `## Details`, separated by one blank line. Never copy the block out of the raw JSON: `text` is arbitrary prose, and JSON escapes its quotes and backslashes a second time.
177
+ [`render-block`](../_data/title-templates.md#render-block) states the output, which is JSON; the last command decodes it and prints the `block` field. Render and decode in one Bash invocation, and write the printed block verbatim below `## How to test`, or below `## Details` when the body does not contain that section, separated by one blank line. Never copy the block out of the raw JSON: `text` is arbitrary prose, and JSON escapes its quotes and backslashes a second time.
176
178
 
177
179
  `create-pr` copies this block into the pull-request body rather than rendering one of its own, so if the body is saved without one, the pull request does not contain one either. If the helper is unavailable or the call fails, relay its error, say that the summary does not contain a block, and save the body without one.
178
180
 
@@ -216,6 +218,13 @@ Good: "Heavy-upload sessions were intermittently failing as users hit the upstre
216
218
  - 🚨 **Breaking:** Stops `kb check` resolving a bare wikilink against every store. #kb
217
219
  - Migration: Qualify each wikilink that names a note outside its own store as `[[store:Note title]]`.
218
220
 
221
+ ## How to test
222
+
223
+ {Only when the change alters a page, a UI component, or a command's output.}
224
+
225
+ 1. In a vault whose `work` store contains `Roadmap`, run `kb check` on a note in another store that links `[[work:Roadmap]]`, and confirm that it reports the link as resolved.
226
+ 2. Change the link to `[[Roadmap]]` and run `kb check` again; confirm that it reports the link as unresolved.
227
+
219
228
  ```change-record
220
229
  title: Add the store-qualified wikilink
221
230
  entries_commit: e5029924
@@ -229,13 +238,12 @@ entries:
229
238
  ## Guidance
230
239
 
231
240
  - When `ticket_ref` is null (the branch does not have a ticket), omit the `{ticket_ref} ` portion of the heading and the title so that they read naturally without it.
232
- - The change summary follows **newspaper style**, progressive disclosure from most to least essential: `## What` is the lede, `## Why` is the purpose that the change serves, `## Details` is every outcome that the change contains
241
+ - The change summary follows **newspaper style**, progressive disclosure from most to least essential: `## What` is the lede, `## Why` is the purpose that the change serves, `## Details` is every outcome that the change contains, and `## How to test`, when present, is how a reviewer exercises the change by hand
233
242
  - Both `## What` and `## Details` come from the drafter, so neither is composed in this session
234
243
  - `## What` contains none of the `## Details` bullets: The two sections cover the change at different lengths rather than repeating one list
235
244
  - Ignore auto-formatter and lint-fix changes
236
- - `## What` and `## Why` are required
245
+ - `## What` and `## Why` are required; `## How to test` appears only when the change alters a surface that a person sees or operates, per step 4
237
246
  - The rendered `change-record` block is the body's last element, per [the change record](../_data/change-record.md)
238
- - Never list automated checks (formatting, linting, typechecking, unit tests) in a test plan. They run automatically in CI.
239
247
 
240
248
  <!-- include: ../../_partials/prose-line-breaks.md / -->
241
249
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: testing-conventions
3
- description: What a test is for, how to name and structure it, and how it calls git and other external programs. Consult before writing or changing a test.
3
+ description: What a test is for, how to name and structure it, how it calls git and other external programs, and how it controls time. Consult before writing or changing a test.
4
4
  user-invocable: false
5
5
  ---
6
6
 
@@ -192,6 +192,17 @@ Intercept only the channels that the test expects to fire. A silencer installed
192
192
 
193
193
  The `typescript-testing-conventions` skill names the TypeScript techniques.
194
194
 
195
+ ## Time-driven behavior
196
+
197
+ The clock is a dependency that the test controls. Behavior is time-driven when its outcome depends on when something happens: polling, retries and reconnect delays, debounces and throttles, timeouts, and code that reads the current time.
198
+
199
+ - **Fake the clock.** A test of time-driven behavior runs on fake timers and advances time explicitly, by the amount that the behavior names. It never sleeps on real time: A real sleep passes on an idle machine and fails under load, when the scheduler delays the timer past the sleep.
200
+ - **Show that nothing more happens by advancing.** To assert that the code stops, such as a poller after it is cancelled, advance past the next tick that would have been due and assert that the count did not change. Never wait a real interval and assert silence.
201
+ - **Wait on a condition across a process boundary.** When the timer runs in another process, such as an entry point that the test spawns, the test cannot fake that clock. Wait for the condition that the behavior produces, with a deadline, never for a fixed delay.
202
+ - **Run a changed test under load before committing it.** Before committing a new or changed test of time-driven behavior, run it repeatedly while the machine is under CPU load. An idle run does not expose a race.
203
+
204
+ The `typescript-testing-conventions` skill names the TypeScript techniques.
205
+
195
206
  ## Mocking principles
196
207
 
197
208
  Mock only what matters in component tests. Don't forward irrelevant props or replicate complex implementation details.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: triage-spike-findings
3
- description: Dispose of the findings that a spike, a usability assessment, or a code-health assessment left without a ticket. Inventories every undisposed item, grades each one's confidence and value, has a subagent without session context challenge every grade, and then creates the labelled tickets under an umbrella and records every disposition on the triage ticket. Use when a findings artifact has proposals or ideas that the existing tickets have not absorbed.
3
+ description: Dispose of the findings that a spike, a usability assessment, a code-health assessment, or a performance analysis left without a ticket. Inventories every undisposed item, grades each one's confidence and value, has a subagent without session context challenge every grade, and then creates the labelled tickets under an umbrella and records every disposition on the triage ticket. Use when a findings artifact has proposals or ideas that the existing tickets have not absorbed.
4
4
  user-invocable: true
5
5
  ---
6
6
 
@@ -12,8 +12,11 @@ Dispose of every item that a findings artifact leaves undisposed: the proposals,
12
12
 
13
13
  ## Inputs
14
14
 
15
- - **The findings artifact**: A spike's findings, a `usability-findings` artifact, or a `code-health-findings` artifact, by local path or by artifact URL. Read a URL with the Artifact tool and save the content to `{ticket_dir}/triage/findings.md`, so that the challenger can read it from a path; on a harness without that tool, the input is a local path.
15
+ - **The findings artifact**: A `spike-findings` artifact, a `usability-findings` artifact, a `code-health-findings` artifact, or a `performance-findings` artifact, by local path or by artifact URL. Read a URL with the Artifact tool and save the content to `{ticket_dir}/triage/findings.md`, so that the challenger can read it from a path; on a harness without that tool, the input is a local path.
16
16
  - **The triage ticket**: The ticket on which the dispositions are posted and under which the working files are kept, resolved per [ticket source resolution](../_data/ticket-source-resolution.md); when none is given, the session's ticket. The umbrella is created as a separate ticket, so the triage ticket may be the spike's own ticket.
17
+ - **The batch**, optional: the item ids, each with its title, that a follow-up triage ticket names. When it is given, the inventory covers those items alone.
18
+
19
+ A run triages one [findings batch](../_data/spike-conventions.md#findings-batches) on one triage ticket.
17
20
 
18
21
  GitHub alone is supported, through `gh`. When the session-context manifest's `scm` is not `github`, stop at preflight and report that the skill does not support the platform.
19
22
 
@@ -22,8 +25,10 @@ GitHub alone is supported, through `gh`. When the session-context manifest's `sc
22
25
  Each item takes a disposition and two grades:
23
26
 
24
27
  - **Disposition**: `ticket` (a child of the umbrella), `comment` (a note on an existing issue, which must be open and must own the file or the behavior), `merge` (folded into another item's ticket; the target is a `ticket` item), or `drop`.
25
- - **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; the helper refuses a record that gives a `low` item one.
26
- - **Value** states how much the item matters: `must-have`, `should-have`, `nice-to-have`, `questionable`. Value never decides whether an item gets a ticket; it is recorded on every item and labels every child.
28
+
29
+ <!-- include: ../../_partials/finding-grades.md / -->
30
+
31
+ The helper refuses a record that gives a `low` item a ticket. Value never decides whether an item gets a ticket; it is recorded on every item and labels every child.
27
32
 
28
33
  The labels come from the common preset of `release-kit sync-labels`: the `value:` family, and the `confidence:` family that williamthorsen/node-monorepo-tools#1017 added. A repository whose labels lack either family cannot take the children, because `gh issue create` fails on a label that the repository does not have.
29
34
 
@@ -45,9 +50,11 @@ Resolve `{ticket_dir}` per {skill:save-artifact}, and write every working file u
45
50
 
46
51
  ### 2. Inventory
47
52
 
48
- Read the findings in full. List every item that the artifact leaves without a disposition, where a disposition is a ticket or a comment that the artifact itself names: a proposed ticket that was not filed, a grouping, a finding outside every grouping, and an idea that the filed tickets did not absorb. Verify each item's claim against the current code and against the open issues (`gh issue list --search`, `gh issue view`): The finding may describe a problem that a merge has since fixed, a decision that the repository records, or work that an open issue already covers.
53
+ Read the findings in full. List every item that the artifact leaves without a disposition, where a disposition is a ticket or a comment that the artifact itself names: a proposed ticket that was not filed, a grouping, a finding outside every grouping, and an idea that the filed tickets did not absorb. Verify each item's claim against the current code and against the open issues, found with `gh issue list --search` and read with their comments per [platform-specific fetch](../_data/ticket-source-resolution.md#platform-specific-fetch): The finding may describe a problem that a merge has since fixed, a decision that the repository records, or work that an open issue already covers.
54
+
55
+ Write `inventory.md` as a table: the item's id (the artifact's own id when it has one), its title, where it appears in the artifact, the verification outcome (holds, partly holds, or does not hold, with the evidence), and, when the findings give the item an evidence key and the paths that it covers, that key and those paths, copied verbatim. Give an item that the artifact does not identify an id of the inventory's own, so that a follow-up triage ticket can name it.
49
56
 
50
- Write `inventory.md` as a table: the item's id (the artifact's own id when it has one), its title, where it appears in the artifact, the verification outcome (holds, partly holds, or does not hold, with the evidence), and, when the findings give the item an evidence key and the paths that it covers, that key and those paths, copied verbatim.
57
+ When the inventory holds more items than the batch ceiling, split it into batches of at most the ceiling, in the artifact's ranking order, or in the order in which the items appear when the artifact does not rank them, and keep each grouping in one batch. Triage the first batch, and drop the other items from the table. Add a **Batches** table to `inventory.md` with the batch number, its items' ids and titles, and its follow-up ticket, blank until step 7 creates it.
51
58
 
52
59
  ### 3. Recommend
53
60
 
@@ -65,7 +72,7 @@ root: {repository root}
65
72
 
66
73
  **A reply that lacks the `Phase: disposition-challenge` line is a challenger stopped by its turn limit.** Resume it once, asking only for its report; on Claude Code, send it a message with `SendMessage`, addressed by the agent ID that its dispatch returned. When the resumed challenger still does not return a report, do not dispatch again: Record the challenge as not returned, treat every item as unchallenged, and say so in the record's `challengeSummary`.
67
74
 
68
- Save the reply as `challenge.md`. Then take each item in turn: Defend the recommendation when the argument fails on the evidence, modify it when the argument stands in part, and abandon it when the argument stands. A defense answers the argument on the evidence that the argument names; a defense that rests on other grounds fails.
75
+ Save the reply as `challenge.md`. Then take each item in turn: Defend the recommendation when the argument fails on the evidence, modify it when the argument stands in part, and abandon it when the argument stands. A defense answers the argument on the evidence that the argument names; a defense that rests on other grounds fails. An argument that lowers the grade of a code-health item on the one-time cost of the change fails under the grade definitions above, even when the challenger raises it.
69
76
 
70
77
  Decide the blockers of every `ticket` item under the threshold in the ticketing preferences rulebook: An item is blocked by another ticket when there is some probability that the other ticket affects it and should be merged first, and a ticket whose design takes another ticket's outcome as an input is blocked by it. A blocker is another `ticket` item, by id, or an open issue in this repository outside the triage, by number; check each issue with `gh issue view {issue} --json state`, and omit a closed one, which does not block. Record every such dependency in `blockedBy`, never in `notes`.
71
78
 
@@ -83,10 +90,11 @@ Compose the bodies:
83
90
 
84
91
  - **The umbrella**, when at least one item is a `ticket`: its problem (the follow-up work of the findings), its context (a link to the triage ticket, and the tickets that the findings filed without adopting them, listed and not made children), and "Every child is closed" as its acceptance criterion. It does not take a graded label.
85
92
  - **One child per `ticket` item**, in the ticket skeleton that {skill:create-ticket} step 2 states: problem, context, and acceptance criteria, with the title and reason of every `merge` item that targets it folded in. Its labels are `confidence:{grade}` and `value:{grade}`.
93
+ - **One follow-up triage ticket per later batch**, when the **Batches** table has more than one row: titled `Triage batch {n} of {findings title}`, with a link to the findings artifact, its path written `~/`-relative as in the [closing post](../_data/spike-conventions.md#closing-post), a link to the triage ticket, whose dispositions comment records the earlier round, the batch's items by id and title as its **The batch** input, and `triage-spike-findings` as its next step. Read the triage ticket's parent with `gh issue view {triage ticket} --json parent`: A follow-up takes that parent when there is one, so that it sits beside its siblings, and no parent otherwise. Each follow-up is blocked by the one before it. The first is not blocked: The triage ticket stays open after this run, and this round's dispositions are posted before the next round starts. Add one line per follow-up to the record's `notes`, `Batch {n} ({item ids}) is triaged in {follow-up}`, with the follow-up's title in place of `{follow-up}` until step 7 creates it, so that the dispositions comment names every follow-up.
86
94
 
87
95
  Run the helper's `render --preview` to `{ticket_dir}/triage/preview/`, which writes the dispositions comment with `(pending)` where a number is not yet known, and one comment file per issue that a `comment` disposition names.
88
96
 
89
- Show everything that step 7 will create or post in one block: every body with its title and labels, the parent relationship and the blockers of each child, every per-issue comment with its issue, and the dispositions comment. Confirm once in the action-items block. This confirmation is the only one: {skill:create-ticket} does not re-confirm a relationship given as an argument.
97
+ Show everything that step 7 will create or post in one block: every body with its title and labels, the parent relationship and the blockers of each child and each follow-up, every per-issue comment with its issue, and the dispositions comment. Confirm once in the action-items block. This confirmation is the only one: {skill:create-ticket} does not re-confirm a relationship given as an argument.
90
98
 
91
99
  ### 7. Write
92
100
 
@@ -95,8 +103,9 @@ Nothing before this step writes anything remote. On a failed write, stop and rep
95
103
  1. When at least one item is a `ticket` and `umbrella` is null, create the umbrella with {skill:create-ticket}, and write its number into `umbrella`.
96
104
  2. For each `ticket` item, in the order that `validate` reports as `order` for the approved record, run {skill:create-ticket} with `--parent {umbrella}` and `--label confidence:{grade},value:{grade}`, adding `--blocked-by` with the item's blockers as `#{number}` (the recorded `ticket` of each item id, and each issue number) when it has any, and write the returned number into the item's `ticket` as soon as it is returned. Because `order` places every blocker first, each item id that `--blocked-by` names already has its number.
97
105
  3. For each `ticket` item, read `gh issue view {ticket} --json parent,blockedBy`, and add what is missing in one `gh issue edit {ticket} --parent {umbrella} --add-blocked-by {numbers}` call, omitting a flag that has nothing to add. {skill:create-ticket} sets the parent and the blockers in one call, so a rejected blocker can drop the parent as well, and this read-back is how a failed link is found. On a re-run, it completes the links of the items that an earlier run created.
98
- 4. Run the helper's `render` to `{ticket_dir}/triage/rendered/`, without `--preview`.
99
- 5. Post each `comment-{issue}.md` on its issue, and then `dispositions-comment.md` on the triage ticket. Before each post, read the issue's comments with `gh issue view {issue} --json comments`, and skip the post when a comment already opens with the first line of the rendered file:
106
+ 4. For each later batch, in batch order, skip the batch when its follow-up ticket is already recorded in the **Batches** table. Otherwise create its follow-up with {skill:create-ticket}, adding `--parent` and `--blocked-by` as step 6 composed them, and as soon as the number is returned, write it into the table and replace the follow-up's title with `#{number}` in its `notes` line.
107
+ 5. Run the helper's `render` to `{ticket_dir}/triage/rendered/`, without `--preview`.
108
+ 6. Post each `comment-{issue}.md` on its issue, and then `dispositions-comment.md` on the triage ticket. Before each post, read the issue's comments with `gh issue view {issue} --json comments`, and skip the post when a comment already opens with the first line of the rendered file:
100
109
 
101
110
  ```bash
102
111
  body_path="{ticket_dir}/triage/rendered/comment-{issue}.md"
@@ -104,10 +113,20 @@ Nothing before this step writes anything remote. On a failed write, stop and rep
104
113
  gh issue comment {issue} --body-file "$body_path"
105
114
  ```
106
115
 
107
- 6. Save `dispositions-comment.md`, with frontmatter, as the ticket-level `dispositions` artifact per {skill:save-artifact}.
116
+ Keep the URL that `gh issue comment` prints for the dispositions comment; when the post was skipped, keep the `url` of the matching comment instead. Step 8 links it.
117
+
118
+ 7. Save `dispositions-comment.md`, with frontmatter, as the ticket-level `dispositions` artifact per {skill:save-artifact}.
108
119
 
109
120
  ### 8. Report
110
121
 
111
- Report the umbrella when one was created, each child with its grades and blockers in the order in which step 7 created them, each issue commented on, and the artifact's path. The triage ticket stays open: Closing it is the developer's call, once they have read the record.
122
+ Report the umbrella when one was created, each child with its grades and blockers in the order in which step 7 created them, each follow-up triage ticket with its batch, each issue commented on, and the artifact's path. The triage ticket stays open: Closing it is the developer's call, once they have read the record.
123
+
124
+ The triage round ends the spike, so offer the [closing post](../_data/spike-conventions.md#closing-post) on the triage ticket in the same response's action-items block, showing its body, and post it on consent with that section's duplicate check, passing the body through a file. Do not offer it when the run was given **The batch**: A follow-up triage ticket's dispositions comment is its record. The post contains:
125
+
126
+ - The answer to each question to answer and the recommendation on each decision to enable that the triage ticket's body lists, taken from the findings and the approved dispositions. A body that lists neither leaves the post with the items below alone.
127
+ - The count of items by disposition.
128
+ - Links to the umbrella, to each follow-up triage ticket, to the dispositions comment, and to the findings artifact, its path written `~/`-relative.
129
+
130
+ It does not repeat the dispositions, which the dispositions comment records.
112
131
 
113
132
  <!-- include: ../_partials/gh-body-file.md / -->
@@ -176,3 +176,43 @@ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
176
176
  ```
177
177
 
178
178
  Under Jest, `jest.spyOn` takes the same form.
179
+
180
+ ## Time-driven behavior
181
+
182
+ The `testing-conventions` skill states the rule: A test of time-driven behavior controls the clock. Under Vitest, call `vi.useFakeTimers()` in `beforeEach` and `vi.useRealTimers()` in `afterEach`, and move time with `vi.advanceTimersByTimeAsync`. Prefer it to `vi.advanceTimersByTime`, because it also settles the promises that the fired timers start, so that code that awaits between ticks keeps pace with the clock. Jest takes the same calls on `jest`.
183
+
184
+ ```typescript
185
+ // ✅ Good: The test advances the clock past the next tick and asserts the count
186
+ beforeEach(() => {
187
+ vi.useFakeTimers();
188
+ });
189
+
190
+ afterEach(() => {
191
+ vi.useRealTimers();
192
+ });
193
+
194
+ it('when stopped, does not poll again', async () => {
195
+ const fetchStatus = vi.fn();
196
+ const poller = startPolling(fetchStatus, { intervalMs: 20 });
197
+ await vi.advanceTimersByTimeAsync(20);
198
+ expect(fetchStatus).toHaveBeenCalledTimes(1);
199
+
200
+ poller.stop();
201
+ await vi.advanceTimersByTimeAsync(40);
202
+ expect(fetchStatus).toHaveBeenCalledTimes(1);
203
+ });
204
+
205
+ // ❌ Avoid: The test sleeps on real time, and fails when load delays a tick past the sleep
206
+ it('when stopped, does not poll again', async () => {
207
+ const fetchStatus = vi.fn();
208
+ const poller = startPolling(fetchStatus, { intervalMs: 20 });
209
+ await new Promise((resolve) => setTimeout(resolve, 30));
210
+ expect(fetchStatus).toHaveBeenCalledTimes(1);
211
+
212
+ poller.stop();
213
+ await new Promise((resolve) => setTimeout(resolve, 60));
214
+ expect(fetchStatus).toHaveBeenCalledTimes(1);
215
+ });
216
+ ```
217
+
218
+ To run a changed test under load, start several copies of `vitest run <file> --repeats <n>` at once, so that they compete for the CPU. Run Vitest directly: A wrapper that runs one heavy command at a time on the machine, such as nmr's machine lock, makes the copies wait for each other, and the machine never comes under load. A project whose tests run against a repo-root config passes the same `--config` that its test script passes.
@@ -21,5 +21,8 @@ plan-reviser:
21
21
  prose-reviser:
22
22
  model: inherit
23
23
 
24
+ prototype-builder:
25
+ model: inherit
26
+
24
27
  usability-assessor:
25
28
  model: inherit
@@ -14,7 +14,7 @@ Your dispatch contains four scalars:
14
14
 
15
15
  - **`brief`**: The path of the code-health brief. Read it in full before your first step.
16
16
  - **`lens`**: The name of your lens, as the brief's lens table writes it.
17
- - **`sense`**: The path of the sense document: the unit's hotspots, co-change pairs, coverage, test timings, and the results of the repository's own checks, each with its status. The `outputPath` of a check names its log.
17
+ - **`sense`**: The path of the sense document: the unit's hotspots with their importer counts, co-change pairs, coverage, test timings, dead code, clone pairs, dependency graph, and the results of the repository's own checks, each with its status. The `outputPath` of a check names its log.
18
18
  - **`output`**: Your evidence directory. It exists.
19
19
 
20
20
  From the brief, take your lens's row: its ID prefix, its subject, the rulebooks that it reads by path, and its proposal cap. Take the unit, the exclusions, the reuse-candidate directory, and the library inventory. Everything that the brief marks settled is settled: Do not re-decide the unit, the lenses, or the caps.
@@ -40,17 +40,17 @@ A proposal is one change that makes the code or a test the way it would be writt
40
40
  Each proposal has:
41
41
 
42
42
  - **`key`**: `{path}:{rule-or-smell}`, a stable name for the subject, such as `src/run.ts:long-function` or `src/a.test.ts:duplicated-setup`. Use the smell or tidying names of Fowler's catalogue and Beck's tidyings, or the rulebook's own term, in kebab case. Two runs that find the same problem write the same key.
43
- - **`paths`**: The files that the change touches.
43
+ - **`paths`**: The files that the proposal is about, each of which exists in the tree at the time of the assessment. Name every file that the change creates in `change`, and leave it out of `paths`.
44
44
  - **`evidence`**: One or more entries that a helper checks against the tree:
45
45
  - `span`: a `path`, a `startLine` and `endLine`, and a `quote` copied from those lines.
46
46
  - `rule`: a `rulebook` path, a `section` (the heading text without `#`), and a `quote` copied from that section.
47
47
  - `sensor`: the `sensor` name from the sense document and a `detail`, such as the hotspot rank or the coverage percentage.
48
48
  - **`change`**: One change, stated so that an implementer could make it without your report. Two changes are two proposals.
49
49
  - **`strength`**: `sensor` when a sensor shows the problem, `rule` when a rulebook sentence states it, `reading` when only your reading does.
50
- - **`size`**: `small` (one function or one test), `medium` (one module), or `large` (several modules).
50
+ - **`size`**: `small` (one function or one test), `medium` (one module), or `large` (several modules). It records the extent of the change, so that the triage can scope the ticket for it, such as whether the change fits one pull request; it is not a cost to weigh against the proposal.
51
51
  - **`reach`**: The number of files or call sites that the problem affects.
52
52
 
53
- A quote that is not copied exactly from its lines or its section fails the check, and the proposal is dropped. Stay within your lens's proposal cap; when you find more, keep the ones with the greatest reach.
53
+ A quote that is not copied exactly from its lines or its section fails the check, and so does a `paths` entry that names a missing file; either way, the proposal is dropped. Stay within your lens's proposal cap; when you find more, keep the ones with the greatest reach.
54
54
 
55
55
  ## Report format
56
56
 
@@ -19,8 +19,7 @@ Your dispatch contains three scalars:
19
19
 
20
20
  For each item, find the strongest argument against its disposition and against each grade, check the claim on which the recommendation rests, and propose the change that you would make. The grades are defined as follows:
21
21
 
22
- - **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.
23
- - **Value** states how much the item matters: `must-have`, `should-have`, `nice-to-have`, `questionable`.
22
+ <!-- include: ../_partials/finding-grades.md / -->
24
23
 
25
24
  The dispositions are `ticket` (a new ticket under the triage's umbrella), `comment` (a note on an existing issue), `merge` (folded into another item's ticket), and `drop`.
26
25
 
@@ -36,9 +35,9 @@ Work in rounds, where a round is one turn of tool calls. Batch every read and ch
36
35
 
37
36
  For each item:
38
37
 
39
- 1. **Check the claim.** Read the code that the finding names and confirm that the problem exists as described, or that it does not. Search the open issues with `gh issue list --search` and read the candidates with `gh issue view`: An item that an open issue already covers is a `comment` or a `drop`, not a `ticket`, and a `comment` whose issue is closed or does not cover it is wrong.
38
+ 1. **Check the claim.** Read the code that the finding names and confirm that the problem exists as described, or that it does not. Search the open issues with `gh issue list --search` and read each candidate's body and comments per the platform-specific fetch in `{harness_home_dir}/skills/_data/ticket-source-resolution.md`: An item that an open issue already covers is a `comment` or a `drop`, not a `ticket`, and a `comment` whose issue is closed or does not cover it is wrong.
40
39
  2. **Argue against the disposition.** Ask whether the item is worth a ticket at all, whether it belongs inside another item's ticket, whether the issue that it would comment on owns the file or the behavior, and whether the finding is a design decision that the repository records rather than a defect.
41
- 3. **Argue against each grade.** Ask what makes the item less advisable than its confidence says, and less important than its value says: the reach of the problem, the cost of the fix, a decision that already settled it, a user that it never affects. Argue the grade up when the evidence supports that instead.
40
+ 3. **Argue against each grade.** Ask what makes the item less advisable than its confidence says, and less important than its value says: the reach of the problem, the cost of the fix (never for a code-health item, which the definitions above grade by the code that the change leaves), a decision that already settled it, a user that it never affects. Argue the grade up when the evidence supports that instead.
42
41
  4. **Propose.** State `keep` when every argument fails on the evidence, and otherwise the disposition and grades that you would set.
43
42
 
44
43
  Do not propose a new item: The inventory is the triage's, and you judge what it recommends. Do not redesign the fix behind an item.
@@ -54,9 +54,9 @@ Read the change and settle the entries: what each outcome is, which type it take
54
54
 
55
55
  4. **The taxonomy.** Read `{harness_home_dir}/skills/_data/work-types.json` and assign each outcome the `key` of the type whose `description` the outcome meets. That key is the entry's `type`, and its `tier` names the entry's reader.
56
56
 
57
- 5. **The ticket.** Resolve it in this order: the `ticket-source` scalar from your dispatch, when present; otherwise `ticket_url`; otherwise `ticket_id`. Fetch a GitHub issue with `gh issue view {number} --json title,body`. Fetch a Jira issue with whichever connected read tool takes an issue URL, or the one taking an issue key and a cloud id when that is what the machine has.
57
+ 5. **The ticket.** Resolve it in this order: the `ticket-source` scalar from your dispatch, when present; otherwise `ticket_url`; otherwise `ticket_id`. Fetch it per the platform-specific fetch in `{harness_home_dir}/skills/_data/ticket-source-resolution.md`.
58
58
 
59
- **Read the ticket's `## Problem` section and nothing else.** It says what need in the repository the change meets, and the diff says what the change did. When it explains why the work is split across pull requests or what a later one will do, that is how the work was staged, not what the change is for. The proposed solution and the acceptance criteria are deliberation about what to build, and an entry reports what the change did, not what the ticket asked for.
59
+ **Read the ticket's `## Problem` section and nothing else.** It says what need in the repository the change meets, and the diff says what the change did. When it explains why the work is split across pull requests or what a later one will do, that is how the work was staged, not what the change is for. The proposed solution, the acceptance criteria, and the comments are deliberation about what to build, and an entry reports what the change did, not what the ticket asked for.
60
60
 
61
61
  A ticket that you cannot fetch, and a branch that names none, are both normal. Draft from the commit log and the diff alone, and name the omission in your report. Never fill the gap by asking the caller for a summary.
62
62
 
@@ -15,7 +15,7 @@ Answer one question: **Could a competent developer, reading only the ticket and
15
15
 
16
16
  You are that developer. Everything you know about the work comes from the artifacts and the repository, and your value is that you know nothing else. Nothing is handed to you but the scalars in your dispatch:
17
17
 
18
- - **`ticket-source`**: The ticket. A local path is a ticket artifact; read it. A URL or a shorthand reference such as `#123` is a remote ticket; fetch a GitHub issue with `gh issue view {number} --json title,body`, and any other platform's issue per the platform-specific fetch in `{harness_home_dir}/skills/_data/ticket-source-resolution.md`.
18
+ - **`ticket-source`**: The ticket. A local path is a ticket artifact; read it. A URL or a shorthand reference such as `#123` is a remote ticket; fetch its body and comments per the platform-specific fetch in `{harness_home_dir}/skills/_data/ticket-source-resolution.md`. Its comments are part of the ticket: A comment that the plan contradicts or omits is a finding.
19
19
  - **`plan`**: The path of the plan artifact.
20
20
  - **`root`**: The repository root, against which every path in the artifacts is resolved.
21
21
 
@@ -0,0 +1,69 @@
1
+ ---
2
+ name: prototype-builder
3
+ description: Build one prototype for one lens of a prototype brief, check it in a headless browser apart from the dispatching session's, and publish it as an artifact. Returns the artifact URL, the prototype's metadata, and its distinctive ideas.
4
+ disallowedTools: NotebookEdit, Task, mcp__plugin_playwright_playwright
5
+ mcpServers:
6
+ - prototype-browser:
7
+ type: stdio
8
+ command: npx
9
+ # Pinned by hand: `nmr upgrade` does not read frontmatter.
10
+ args: ['--yes', '@playwright/mcp@0.0.84', '--headless', '--isolated']
11
+ ---
12
+
13
+ # Prototype builder
14
+
15
+ You build one prototype of a round of competing prototypes, for one lens of the round's brief. Other builders build the other lenses before or after you. You have not seen the session that dispatched you or any other builder's work.
16
+
17
+ ## Your assignment
18
+
19
+ Your dispatch contains seven scalars:
20
+
21
+ - **`brief`**: The path of the brief. Read it in full before you write anything.
22
+ - **`lens`**: The name of your lens, as the brief's lens sections write it.
23
+ - **`slug`**: The prototype's slug.
24
+ - **`version`**: The prototype's version.
25
+ - **`id`**: The prototype's id, `{number}.{version}`.
26
+ - **`set-title`**: The set's title, the product's name.
27
+ - **`output`**: The path of the page that you write. Its directory is the prototype set.
28
+
29
+ Build the prototype for your lens. Write only the files that the brief's rules of engagement allow. Choose the prototype's short title before writing the page. Put the id and the title, as `{id} {title}`, on the first line of the page's `data-demo` band, and make the page's `<title>` `{set-title} - {id} {title}`, such as `Top Right - 1.1 Next item`. Report the same title. Invoke the design skill that the brief names before writing markup.
30
+
31
+ ## Checking the page
32
+
33
+ Check the page in a browser before you publish it, through the tools of the `prototype-browser` MCP server alone. That server runs a headless browser apart from the session that dispatched you. Never use another browser server's tools, and never run `thor-chrome`: That browser is shared with the dispatching session, and a call that you make there can stall it.
34
+
35
+ The server refuses `file:` URLs. Serve the directory that contains `output` on a free port, in the background, and read the port from the server's first line of output:
36
+
37
+ ```bash
38
+ python3 -u -m http.server --bind 127.0.0.1 --directory "{directory of output}" 0
39
+ ```
40
+
41
+ Open `http://127.0.0.1:{port}/{file name of output}`, and stop the server before you reply.
42
+
43
+ A browser call that ends in a timeout error, or that takes over 30 seconds by `date` read before and after it, is a defect of the page, most likely a loop that does not end. Fix the page and reload it; never retry the call unchanged. When the page still does not respond after a fix, report the defect in your reply rather than describe the page as working.
44
+
45
+ When the server cannot start a browser, publish the page, and state in the description that it was not checked in a browser and why.
46
+
47
+ ## Reply
48
+
49
+ Publish the output with the Artifact tool. Then reply with these and nothing else:
50
+
51
+ - The artifact URL
52
+ - A short title
53
+ - The lens
54
+ - The inputs on which you drew
55
+ - A one-sentence description
56
+ - One line per note label in the brief, as `{label}: {value}`
57
+ - Five lines of the prototype's distinctive ideas
58
+
59
+ ## How you write
60
+
61
+ <!-- include: ../_partials/plain-speech.md / -->
62
+
63
+ <!-- include: ../_partials/concision.md / -->
64
+
65
+ <!-- include: ../_partials/file-access.md / -->
66
+
67
+ <!-- include: ../_partials/shell-commands.md / -->
68
+
69
+ <!-- guidance-hook: writing-preferences -->
@@ -40,7 +40,7 @@ The brief marks each target read-only or writable, and the mark is absolute. You
40
40
 
41
41
  **Steps.** A flow is the routes and the controls in order.
42
42
 
43
- **On each screen**, also look for: an error that does not say what to do next, an empty state without a next step, an action without feedback or undo, a name or a style that changes between screens, a link that leads nowhere, a state conveyed by colour or an icon alone, and text that fails the floors in the accessibility conventions or the rules in the UI copy conventions.
43
+ **On each screen**, also look for: an error that does not say what to do next, an empty state without a next step, an action without feedback or undo, a name or a style that changes between screens, a link that leads nowhere, a state conveyed by colour or an icon alone, a list in which the reader must read each row to find a state for which the reader scans, such as expired or failing, a button outside a toolbar that does not look like a button at rest, and text that fails the floors in the accessibility conventions or the rules in the UI copy conventions.
44
44
 
45
45
  **Evidence.** Take a screenshot that shows the candidate, and save it in `output`, named `{ID}-{short-slug}.png`. Report slowness only when it also appears on a production build or a hosted target: A development server is slower than either.
46
46
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "codeassembly-guidance",
3
- "version": "0.5.0",
3
+ "version": "0.6.0",
4
4
  "description": "The CodeAssembly library of agent guidance: rulebooks, skills, and subagents that the codeassembly CLI deploys",
5
5
  "keywords": [
6
6
  "agents",
@@ -44,17 +44,18 @@
44
44
  "@types/node": "24.19.2",
45
45
  "@williamthorsen/change-grammar": "0.3.0",
46
46
  "@williamthorsen/kb": "0.11.1",
47
- "@williamthorsen/nmr": "0.53.1",
47
+ "@williamthorsen/nmr": "0.55.0",
48
48
  "@williamthorsen/toolbelt.errors": "0.9.0",
49
49
  "@williamthorsen/toolbelt.terminal": "0.3.0",
50
50
  "@williamthorsen/toolbelt.testing": "0.8.0",
51
+ "@williamthorsen/toolbelt.vitest": "0.13.2",
51
52
  "codeassembly": "0.20.0",
52
53
  "esbuild": "0.28.2",
53
- "eslint": "10.13.0",
54
+ "eslint": "10.14.0",
54
55
  "happy-dom": "21.0.4",
55
56
  "marklassian": "1.2.1",
56
57
  "ulid": "3.0.2",
57
- "vitest": "5.0.5",
58
+ "vitest": "5.1.0",
58
59
  "yaml": "2.9.1",
59
60
  "zod": "4.6.7"
60
61
  },
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "$schema": "https://json-schema.org/draft/2020-12/schema",
3
- "$id": "https://unpkg.com/codeassembly-guidance@0.5.0/schemas/preferences.v1.json",
3
+ "$id": "https://unpkg.com/codeassembly-guidance@0.6.0/schemas/preferences.v1.json",
4
4
  "title": "Preferences",
5
5
  "description": "Configuration read by agent skills. Resolved from .agents/preferences.yaml at the project level, with ~/.agents/preferences.yaml as a global fallback.",
6
6
  "type": "object",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "$schema": "https://json-schema.org/draft/2020-12/schema",
3
- "$id": "https://unpkg.com/codeassembly-guidance@0.5.0/schemas/work-types.v1.json",
3
+ "$id": "https://unpkg.com/codeassembly-guidance@0.6.0/schemas/work-types.v1.json",
4
4
  "additionalProperties": false,
5
5
  "description": "Canonical work-types taxonomy consumed by skill content and downstream changelog/release-notes tooling. Defines the work-type vocabulary, tier grouping, breaking-change policy, changelog-eligibility flags, and cross-cutting section markers (e.g., the breaking-changes indicator).",
6
6
  "properties": {
@@ -1,4 +0,0 @@
1
- ## Interaction style
2
-
3
- - Don't use `ask_user_questions`: The arrow-key UI is hard to scan and inflexible.
4
- - Instead, present choices as a numbered list in plain text. I'll reply with a number or free-form text.