codeassembly-guidance 0.4.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (78) hide show
  1. package/.meta/changelog.json +635 -280
  2. package/CHANGELOG.md +89 -0
  3. package/README.md +55 -19
  4. package/content/_partials/finding-grades.md +4 -0
  5. package/content/_partials/guidance-change-since-capture.md +1 -1
  6. package/content/codeassembly-content.yaml +2 -0
  7. package/content/collections/recommended.md +6 -3
  8. package/content/guidance/_harnesses/rovo/AGENTS.md +0 -1
  9. package/content/guidance/rulebooks/accessibility-conventions.md +26 -6
  10. package/content/guidance/rulebooks/cli-conventions.md +17 -2
  11. package/content/guidance/rulebooks/codeassembly-content-specification.md +11 -11
  12. package/content/guidance/rulebooks/machine-readable-output-conventions.md +85 -0
  13. package/content/guidance/rulebooks/shared-data-conventions.md +4 -2
  14. package/content/guidance/rulebooks/ui-copy-conventions.md +2 -2
  15. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +10 -10
  16. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +7 -3
  17. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +3 -1
  18. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +5 -5
  19. package/content/scripts/check-prose.mjs +38 -38
  20. package/content/scripts/describe-change.mjs +68 -68
  21. package/content/skills/_data/action-items.md +2 -2
  22. package/content/skills/_data/artifact-conventions.md +22 -431
  23. package/content/skills/_data/concision.md +1 -1
  24. package/content/skills/_data/entry-points.md +37 -0
  25. package/content/skills/_data/recommendation-gradient.md +6 -6
  26. package/content/skills/_data/spike-conventions.md +13 -3
  27. package/content/skills/_data/ticket-source-resolution.md +21 -4
  28. package/content/skills/_data/title-templates.md +4 -4
  29. package/content/skills/_partials/commit-title-rendering.md +2 -1
  30. package/content/skills/_partials/next-steps-after-plan.md +4 -3
  31. package/content/skills/_partials/option-format.md +8 -8
  32. package/content/skills/_partials/plan-template.md +4 -2
  33. package/content/skills/_partials/resolve-plan-and-ticket.md +22 -0
  34. package/content/skills/_partials/split-launch-prompts.md +1 -1
  35. package/content/skills/_partials/ticket-criteria-conventions.md +3 -1
  36. package/content/skills/analyze-performance/SKILL.md +102 -0
  37. package/content/skills/analyze-performance/analyze-performance.mjs +70 -0
  38. package/content/skills/assess-code-health/SKILL.md +16 -14
  39. package/content/skills/assess-code-health/assess-code-health.mjs +29 -28
  40. package/content/skills/assess-usability/SKILL.md +5 -3
  41. package/content/skills/convert-agent-prompt/SKILL.md +60 -0
  42. package/content/skills/create-commit/SKILL.md +10 -5
  43. package/content/skills/create-pr/SKILL.md +11 -11
  44. package/content/skills/create-ticket/SKILL.md +1 -0
  45. package/content/skills/design-and-plan/SKILL.md +2 -2
  46. package/content/skills/implement-plan/SKILL.md +1 -28
  47. package/content/skills/index-prototypes/SKILL.md +36 -17
  48. package/content/skills/index-prototypes/index-prototypes.mjs +14 -14
  49. package/content/skills/investigate-spike/SKILL.md +48 -0
  50. package/content/skills/prepare-prototype-brief/SKILL.md +17 -13
  51. package/content/skills/refine-guidance/SKILL.md +1 -1
  52. package/content/skills/refine-plan/SKILL.md +7 -4
  53. package/content/skills/refine-prototype/SKILL.md +5 -5
  54. package/content/skills/review-branch/SKILL.md +7 -7
  55. package/content/skills/review-criteria/SKILL.md +3 -3
  56. package/content/skills/review-gh-pr/SKILL.md +1 -1
  57. package/content/skills/revise-prose/SKILL.md +9 -8
  58. package/content/skills/revise-prose/revise-prose.mjs +2 -2
  59. package/content/skills/save-artifact/SKILL.md +1 -1
  60. package/content/skills/start-ticket/SKILL.md +27 -0
  61. package/content/skills/summarize-change/SKILL.md +17 -9
  62. package/content/skills/testing-conventions/SKILL.md +12 -1
  63. package/content/skills/triage-feedback/SKILL.md +1 -1
  64. package/content/skills/triage-spike-findings/SKILL.md +31 -12
  65. package/content/skills/typescript-testing-conventions/SKILL.md +40 -0
  66. package/content/subagents/_data/claude.yaml +3 -0
  67. package/content/subagents/code-health-assessor.md +4 -4
  68. package/content/subagents/disposition-challenger.md +3 -4
  69. package/content/subagents/entry-drafter.md +2 -2
  70. package/content/subagents/feedback-triage-challenger.md +1 -1
  71. package/content/subagents/handoff-reviewer.md +1 -1
  72. package/content/subagents/plan-reviewer.md +8 -7
  73. package/content/subagents/prototype-builder.md +69 -0
  74. package/content/subagents/usability-assessor.md +1 -1
  75. package/package.json +8 -7
  76. package/schemas/preferences.v1.json +1 -1
  77. package/schemas/work-types.v1.json +1 -1
  78. package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +0 -4
@@ -9,11 +9,11 @@ supported-harnesses: [claude]
9
9
 
10
10
  Find the code and tests in one unit of a codebase that would be written differently if they were written afresh today, and propose one change for each. Each lens is a {subagent:code-health-assessor} that reads the unit without seeing any other lens's report. You run the sensors, write the brief that every lens reads, dispatch the lenses, check every proposal's evidence against the tree, and merge the proposals into one findings artifact.
11
11
 
12
- The skill does not grade anything: The findings artifact is the input of `triage-spike-findings`, which grades each proposal, has a challenger argue against every grade, and decides what becomes a ticket. Its one remote write is the [closing post](../_data/spike-conventions.md#closing-post) on the ticket, made on the developer's consent.
12
+ The skill does not grade anything: The findings artifact is the input of `triage-spike-findings`, which grades each proposal, has a challenger argue against every grade, and decides what becomes a ticket. When the findings leave nothing to triage, its one remote write is the [closing post](../_data/spike-conventions.md#closing-post) on the ticket, made on the developer's consent; otherwise the triage round makes the post.
13
13
 
14
14
  ## Inputs
15
15
 
16
- - **The unit**: a package or a subtree, as the developer names it. When the developer does not name one, propose one from the hotspot ranking at the checkpoint. Never assess the whole repository by default.
16
+ - **The unit**: a package or a subtree, as the developer names it. When the developer does not name one, propose one from the hotspot ranking at the checkpoint. Never assess the whole repository by default. Plan an assessment of several units as [findings batches](../_data/spike-conventions.md#findings-batches) states, one ticket per unit.
17
17
  - **The window**: the number of days of history that the hotspots read, 180 by default.
18
18
  - **The ticket**, optional. Without one in session, {skill:save-artifact} saves the artifacts under the ticket ID that it generates.
19
19
 
@@ -43,7 +43,7 @@ node {harness_home_dir}/skills/assess-code-health/assess-code-health.mjs sense -
43
43
  --coverage-summary {summary path} --junit {junit path} --exclude {glob}
44
44
  ```
45
45
 
46
- Omit `--coverage-summary` or `--junit` when the test command cannot write that report; the sensor is then recorded as not applicable. A sensor that fails is recorded with its reason and does not stop the run.
46
+ Omit `--coverage-summary` or `--junit` when the test command cannot write that report; the sensor is then recorded as not applicable. A sensor that fails is recorded with its reason and does not stop the run. The dead-code, duplication, and dependency-graph sensors run on every invocation from the project's copy of each tool, or through `pnpm dlx` with registry access; the helper doc states how each one decides its status.
47
47
 
48
48
  ### 2. Write the brief
49
49
 
@@ -51,15 +51,15 @@ Compose the brief with these sections:
51
51
 
52
52
  1. **Unit.** The unit, the window and its first commit date from the sense document, and the top ten hotspots.
53
53
  2. **Reference points.** The reuse-candidate directory and the library inventory. Take the directory from the implementation guidance spliced below when it names one. The inventory is the repository's declared dependencies plus any library that the guidance names.
54
- 3. **Lenses.** Five, each with its name, its slug, its ID prefix, its subject, the rulebooks that it reads by path, and its proposal cap (10 by default):
54
+ 3. **Lenses.** Five, each with its name, its slug, its ID prefix, its subject, the rulebooks that it reads by path, and its proposal cap (2 by default). The default caps keep a unit's proposals within the ceiling of a [findings batch](../_data/spike-conventions.md#findings-batches); the groupings of step 5 only merge proposals, so they never raise the count:
55
55
 
56
- | Lens | Slug | Prefix | Subject |
57
- | ----------------------------------- | ------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------- |
58
- | Convention conformance | `conventions` | `C` | What the linters miss, cited by rulebook path, section, and quoted sentence |
59
- | Structure | `structure` | `S` | Smells with a metric attached, and coupling from the co-change pairs |
60
- | Extraction | `extraction` | `X` | Code duplicated across packages, code that belongs in the reuse-candidate directory, and code equivalent to a library in the inventory |
61
- | Error handling and input validation | `errors` | `E` | Statically evidenced patterns only; performance is out of scope |
62
- | Tests | `tests` | `T` | Coverage intersected with hotspots, duration outliers, duplicated setup, and tests below the bar of the testing conventions |
56
+ | Lens | Slug | Prefix | Subject |
57
+ | ----------------------------------- | ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
58
+ | Convention conformance | `conventions` | `C` | What the linters miss, cited by rulebook path, section, and quoted sentence |
59
+ | Structure | `structure` | `S` | Smells with a metric attached, dead code from `dead-code`, and coupling from the co-change pairs and `dependency-graph` |
60
+ | Extraction | `extraction` | `X` | Code duplicated within the unit or across packages (`duplication`), code that belongs in the reuse-candidate directory, and code equivalent to a library in the inventory |
61
+ | Error handling and input validation | `errors` | `E` | Statically evidenced patterns only; performance is out of scope |
62
+ | Tests | `tests` | `T` | Coverage intersected with hotspots, duration outliers, duplicated setup, and tests below the bar of the testing conventions |
63
63
 
64
64
  List the deployed rulebooks and guidance skills under `{harness_home_dir}/skills/`, and the guidance spliced below, and assign each to the lenses whose subject it governs: the testing conventions to tests, layout and language preferences to conventions and extraction, and every code rulebook to conventions. Name each by its absolute path.
65
65
 
@@ -68,7 +68,7 @@ Compose the brief with these sections:
68
68
 
69
69
  ### 3. Checkpoint
70
70
 
71
- Save the brief with {skill:save-artifact} as a ticket-level `code-health-brief` artifact, and show it to the developer. Ask in one action-items block for approval of the brief, the unit, and the caps. Do not dispatch any lens before approval.
71
+ Save the brief with {skill:save-artifact} as a ticket-level `code-health-brief` artifact, and show it to the developer. Ask in one action-items block for approval of the brief, the unit, and the caps. Caps that sum above the batch ceiling produce findings that triage takes in several batches. Do not dispatch any lens before approval.
72
72
 
73
73
  <!-- include: ../_partials/action-items.md / -->
74
74
 
@@ -120,8 +120,10 @@ Save the document with {skill:save-artifact} as a ticket-level `code-health-find
120
120
 
121
121
  ### 7. Report
122
122
 
123
- Give the developer the findings artifact's path and one line of counts: proposals ranked, tracked, and dropped. Name `triage-spike-findings` as the next step, with the findings artifact's path as its input.
123
+ Give the developer the findings artifact's path and one line of counts: proposals ranked, tracked, and dropped.
124
124
 
125
- In the same response's action-items block, offer the closing post on the ticket, whose contents, consent, and duplicate check are stated in [Closing post](../_data/spike-conventions.md#closing-post). For an assessment, the answers that the post gives are the counts and the top ranked proposals, and its groupings are the proposed groupings of step 5.
125
+ When the findings rank any proposal, name `triage-spike-findings` as the next step, with the findings artifact's path as its input, and do not offer the closing post: The triage round ends the spike and offers it, as [Closing post](../_data/spike-conventions.md#closing-post) states.
126
+
127
+ Otherwise, offer the closing post on the ticket in the same response's action-items block. Its contents, consent, and duplicate check are stated in [Closing post](../_data/spike-conventions.md#closing-post). For an assessment, the answers that the post gives are the counts, and the post names the proposals that a prior disposition or an issue already tracks.
126
128
 
127
129
  <!-- guidance-hook: implementation-preferences -->