codeassembly-guidance 0.5.0 → 0.7.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 (110) hide show
  1. package/.meta/changelog.json +491 -0
  2. package/CHANGELOG.md +118 -0
  3. package/README.md +33 -4
  4. package/content/_partials/finding-grades.md +4 -0
  5. package/content/_partials/kb-unsearched-private-stores.md +6 -0
  6. package/content/codeassembly-content.yaml +4 -0
  7. package/content/collections/recommended.md +5 -2
  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/live-worktree-policy.md +2 -2
  13. package/content/guidance/rulebooks/machine-readable-output-conventions.md +85 -0
  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-ticketing-preferences.md +3 -1
  17. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +7 -3
  18. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +3 -1
  19. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +5 -5
  20. package/content/guidance/shared/AGENTS.md +1 -1
  21. package/content/scripts/check-prose.mjs +1 -1
  22. package/content/scripts/describe-change.mjs +88 -88
  23. package/content/scripts/manage-jira-ticket.mjs +113 -113
  24. package/content/scripts/select-lede-exemplars.mjs +85 -85
  25. package/content/scripts/validate-preferences.mjs +38 -38
  26. package/content/skills/_data/action-items.md +2 -2
  27. package/content/skills/_data/artifact-conventions.md +20 -10
  28. package/content/skills/_data/concision.md +1 -1
  29. package/content/skills/_data/entry-points.md +37 -0
  30. package/content/skills/_data/project-stage.md +9 -5
  31. package/content/skills/_data/recommendation-gradient.md +6 -6
  32. package/content/skills/_data/spike-conventions.md +20 -7
  33. package/content/skills/_data/ticket-source-resolution.md +21 -4
  34. package/content/skills/_data/title-templates.md +4 -4
  35. package/content/skills/_partials/commit-title-rendering.md +2 -1
  36. package/content/skills/_partials/implementation-order-list.md +27 -0
  37. package/content/skills/_partials/next-steps-after-plan.md +6 -5
  38. package/content/skills/_partials/option-format.md +8 -8
  39. package/content/skills/_partials/plan-template.md +5 -1
  40. package/content/skills/_partials/resolve-plan-and-ticket.md +22 -0
  41. package/content/skills/_partials/split-launch-prompts.md +2 -2
  42. package/content/skills/_partials/ticket-criteria-conventions.md +2 -0
  43. package/content/skills/align-ticket-with-implementation/SKILL.md +1 -1
  44. package/content/skills/analyze-performance/SKILL.md +102 -0
  45. package/content/skills/analyze-performance/analyze-performance.mjs +70 -0
  46. package/content/skills/assess-code-health/SKILL.md +16 -14
  47. package/content/skills/assess-code-health/assess-code-health.mjs +29 -28
  48. package/content/skills/assess-usability/SKILL.md +5 -3
  49. package/content/skills/capture-event/SKILL.md +20 -11
  50. package/content/skills/capture-event/capture-event.mjs +122 -122
  51. package/content/skills/capture-feedback/SKILL.md +2 -1
  52. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +97 -97
  53. package/content/skills/convert-agent-prompt/SKILL.md +60 -0
  54. package/content/skills/create-commit/SKILL.md +10 -5
  55. package/content/skills/create-pr/SKILL.md +11 -11
  56. package/content/skills/create-ticket/SKILL.md +1 -0
  57. package/content/skills/create-ticket/resolve-ticket-target.mjs +92 -92
  58. package/content/skills/curate-feedback/curate-feedback.mjs +82 -82
  59. package/content/skills/derive-session-context/derive-session-context.mjs +107 -107
  60. package/content/skills/design-and-plan/SKILL.md +6 -4
  61. package/content/skills/implement-plan/SKILL.md +4 -29
  62. package/content/skills/implementation-order/implementation-order.mjs +67 -0
  63. package/content/skills/index-prototypes/SKILL.md +36 -17
  64. package/content/skills/index-prototypes/index-prototypes.mjs +14 -14
  65. package/content/skills/investigate-spike/SKILL.md +48 -0
  66. package/content/skills/kb-add/SKILL.md +12 -3
  67. package/content/skills/kb-add/kb-add.mjs +88 -88
  68. package/content/skills/kb-curate/kb-curate.mjs +88 -88
  69. package/content/skills/kb-edit/kb-edit.mjs +90 -90
  70. package/content/skills/kb-retrieve/SKILL.md +8 -3
  71. package/content/skills/kb-retrieve/kb-retrieve.mjs +104 -104
  72. package/content/skills/kb-retrieve-events/SKILL.md +8 -3
  73. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +113 -113
  74. package/content/skills/kb-update-events/kb-update-events.mjs +92 -92
  75. package/content/skills/lesson-clusters/lesson-clusters.mjs +102 -102
  76. package/content/skills/list-implementation-order/SKILL.md +23 -0
  77. package/content/skills/merge-bb-pr/SKILL.md +31 -8
  78. package/content/skills/merge-gh-pr/SKILL.md +25 -12
  79. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +13 -8
  80. package/content/skills/merge-pr/SKILL.md +55 -20
  81. package/content/skills/migrate-feedback-memories/SKILL.md +1 -0
  82. package/content/skills/plan/SKILL.md +3 -1
  83. package/content/skills/prepare-prototype-brief/SKILL.md +20 -14
  84. package/content/skills/refine-plan/SKILL.md +9 -4
  85. package/content/skills/refine-prototype/SKILL.md +5 -5
  86. package/content/skills/review-branch/SKILL.md +8 -8
  87. package/content/skills/review-criteria/SKILL.md +4 -4
  88. package/content/skills/review-gh-pr/SKILL.md +1 -1
  89. package/content/skills/revise-prose/SKILL.md +9 -8
  90. package/content/skills/revise-prose/revise-prose.mjs +111 -111
  91. package/content/skills/save-plan/SKILL.md +2 -0
  92. package/content/skills/start-ticket/SKILL.md +27 -0
  93. package/content/skills/streamline-guidance/streamline-guidance.mjs +76 -76
  94. package/content/skills/summarize-change/SKILL.md +27 -9
  95. package/content/skills/testing-conventions/SKILL.md +14 -3
  96. package/content/skills/triage-feedback/SKILL.md +4 -0
  97. package/content/skills/triage-spike-findings/SKILL.md +36 -12
  98. package/content/skills/typescript-testing-conventions/SKILL.md +40 -0
  99. package/content/skills/wrap-up/SKILL.md +4 -0
  100. package/content/subagents/_data/claude.yaml +3 -0
  101. package/content/subagents/code-health-assessor.md +4 -4
  102. package/content/subagents/disposition-challenger.md +3 -4
  103. package/content/subagents/entry-drafter.md +2 -2
  104. package/content/subagents/handoff-reviewer.md +1 -1
  105. package/content/subagents/prototype-builder.md +69 -0
  106. package/content/subagents/usability-assessor.md +1 -1
  107. package/package.json +11 -10
  108. package/schemas/preferences.v1.json +74 -8
  109. package/schemas/work-types.v1.json +1 -1
  110. package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +0 -4
@@ -9,7 +9,7 @@ supported-harnesses: [claude]
9
9
 
10
10
  Find where a product would lead its users to conclude that it is broken or unfinished. Each lens is a {subagent:usability-assessor} that walks its use cases in a browser or, for a command-line product, in a shell, without seeing any other lens's report. You prepare the targets, write the brief that every lens reads, dispatch the lenses one at a time, and merge their reports into one findings artifact.
11
11
 
12
- The skill's one remote write is the [closing post](../_data/spike-conventions.md#closing-post) on the ticket, made on the developer's consent: It does not create a ticket or edit an issue. The findings artifact is the input of `triage-spike-findings`, which decides what becomes a ticket.
12
+ When the findings leave nothing to triage, the skill's remote writes are the [closing post](../_data/spike-conventions.md#closing-post) on the ticket and the ticket's close, both made on one consent from the developer; otherwise the triage round makes both. It does not create a ticket or edit any other issue. The findings artifact is the input of `triage-spike-findings`, which decides what becomes a ticket.
13
13
 
14
14
  ## Inputs
15
15
 
@@ -93,6 +93,8 @@ Then publish it as an artifact page: Load the artifact-design skill, and render
93
93
 
94
94
  ### 7. Report
95
95
 
96
- Give the developer the findings artifact's path, the page's URL, and one line of counts: use cases exercised, findings by effect, and ideas. Name `triage-spike-findings` as the next step, with the findings artifact's path as its input.
96
+ Give the developer the findings artifact's path, the page's URL, and one line of counts: use cases exercised, findings by effect, and ideas.
97
97
 
98
- 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 findings by effect, and its groupings are the proposed groupings of step 5.
98
+ When the artifact has any finding or idea, 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. Findings above the ceiling of a [findings batch](../_data/spike-conventions.md#findings-batches) are triaged in several batches, each on its own ticket.
99
+
100
+ Otherwise, offer to close the ticket with the closing post in the same response's action-items block. The post's contents, the consent, and the checks that a rerun relies on are stated in [Closing post](../_data/spike-conventions.md#closing-post). For an assessment, the answers that the post gives are the use cases exercised and the page's URL.
@@ -22,16 +22,17 @@ A **skill-caused mistake**, an error that a clearer skill definition would have
22
22
 
23
23
  ## Arguments
24
24
 
25
- | Argument | Description | Required |
26
- | ----------- | ------------------------------------------------------------------------------------- | -------- |
27
- | `--summary` | A human-readable one-line summary; becomes the record's label on recall. | Yes |
28
- | `--store` | Registry name, `@default` for the `default_kb`, or `@feedback` for the `feedback_kb`. | Yes |
29
- | `--skill` | The skill to which the event relates. | No |
30
- | `--model` | The model identifier in play. | No |
31
- | `--harness` | The agent platform (`claude`, `rovo`); install-injected. Keep as-is. | Injected |
32
- | `--tags` | Comma-separated tag list. | No |
33
- | `--impact` | Impact rating: one of `low`, `medium`, `high`, `critical`. Omit to leave unrated. | No |
34
- | `--amend` | Id of an existing event to rewrite in place instead of capturing a new one. | No |
25
+ | Argument | Description | Required |
26
+ | ----------- | -------------------------------------------------------------------------------------------------------- | -------- |
27
+ | `--summary` | A human-readable one-line summary; becomes the record's label on recall. | Yes |
28
+ | `--store` | Registry name, `@default` for the `default_kb`, or `@feedback` for the `feedback_kb`. | Yes |
29
+ | `--skill` | The skill to which the event relates. | No |
30
+ | `--model` | The model identifier in play. | No |
31
+ | `--harness` | The agent platform (`claude`, `rovo`); install-injected. Keep as-is. | Injected |
32
+ | `--tags` | Comma-separated tag list. | No |
33
+ | `--impact` | Impact rating: one of `low`, `medium`, `high`, `critical`. Omit to leave unrated. | No |
34
+ | `--amend` | Id of an existing event to rewrite in place instead of capturing a new one. | No |
35
+ | `--shared` | Permit a fresh capture into a store whose `visibility` is `shared`. See [Shared stores](#shared-stores). | No |
35
36
 
36
37
  A value-bearing flag accepts both `--summary text` and `--summary=text`. The event body is read from stdin to EOF; an empty body is allowed.
37
38
 
@@ -49,6 +50,12 @@ Choose the destination deliberately. When the lesson is specific to a project, p
49
50
 
50
51
  A caller whose destination is a configured role rather than a per-lesson judgment passes that role's sentinel: `--store @feedback` sends a record to the registry's `feedback_kb`, the KB that receives feedback about agent guidance.
51
52
 
53
+ ### Shared stores
54
+
55
+ A store's `.kb/config.yaml` declares its `visibility`: `shared` for a store published to collaborators, `private` otherwise; a store that does not declare it counts as `private`. The helper refuses a fresh capture into a `shared` store unless the invocation passes `--shared`, because a record published in that store's history cannot be withdrawn.
56
+
57
+ Never pass `--shared` by habit. On a `shared-store` refusal, read the event's summary and body as a collaborator would: Retry with `--shared` only when they contain nothing unfit for that audience, such as a credential, a personal detail, or a workplace-internal fact. Otherwise, capture into a private store, or report the event uncaptured. When you cannot tell, do not pass the flag. `--amend` is exempt, because it rewrites an event already in the named store.
58
+
52
59
  ### Amending an event
53
60
 
54
61
  `--amend <id>` rewrites an existing capture in place (for example, an event that a `capture-feedback` pass got wrong). Prefer amending over capturing a near-duplicate. Amend always rewrites `summary` and the body from the invocation. It overwrites `--skill`, `--model`, `--tags`, or `--impact` only when you pass that flag; any that you omit keep their existing value, as do the provenance fields (`id`, `captured-at`, `session`, `cwd`, `repo`, `harness`) and any `addressed-by` marks. To clear a curatorial field rather than edit content, use its `kb-update-events` mutator.
@@ -79,7 +86,7 @@ cat <<'EOF' | node {harness_home_dir}/skills/capture-event/capture-event.mjs \
79
86
  --summary "<one-line summary>" \
80
87
  --store <name|@default|@feedback> \
81
88
  --harness {harness_id} \
82
- [--skill <skill>] [--model <model>] [--tags <comma,separated>] [--impact <level>]
89
+ [--skill <skill>] [--model <model>] [--tags <comma,separated>] [--impact <level>] [--shared]
83
90
  <event body, may span multiple lines and contain any characters>
84
91
  EOF
85
92
  ```
@@ -99,6 +106,8 @@ On `ok: false`, handle the `error` code as follows:
99
106
  - `missing-store`: `--store` was omitted. Re-run with `--store <name>` for the KB named by the user, or `--store @default` for an environment-level lesson; the message lists the registered stores.
100
107
  - `store-not-registered`: The named store is not in `kb.yaml`. Confirm the store name or register it.
101
108
  - `readonly-store`: The store is marked readonly; captures are refused.
109
+ - `shared-store`: The store is shared and the invocation did not pass `--shared`. Act per [Shared stores](#shared-stores).
110
+ - `invalid-config`: The store's `.kb/config.yaml` is malformed, so its visibility is unknown and the capture is refused. The message names the file; report it and have the user repair it.
102
111
  - `no-default-store`: `--store @default` was given but `kb.yaml` does not configure a `default_kb`. Name a store explicitly or configure a default with `kb set-default`.
103
112
  - `no-feedback-store`: `--store @feedback` was given but `kb.yaml` does not configure a `feedback_kb`. Set `feedback_kb` in `kb.yaml` to the KB that receives feedback about agent guidance.
104
113
  - `schema-validation`: Report the `errors`, then supply the missing field and retry.