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
@@ -33,7 +33,9 @@ Obtain the base SHA via `git rev-parse --short HEAD`.
33
33
 
34
34
  ### 4. Next steps
35
35
 
36
- After presenting the assessment output, evaluate whether any verdicts are non-baseline and, if so, present follow-up actions. Follow [next steps after assessment](next-steps-after-assessment.md) for the verdict-to-actions mapping, combination rules, and interaction protocol, and [Baseline verdicts](#baseline-verdicts) for the baseline definition.
36
+ After presenting the assessment output, evaluate whether any verdicts are non-baseline and, if so, present follow-up actions. Follow [next steps after assessment](next-steps-after-assessment.md) for the verdict-to-actions mapping, combination rules, and interaction protocol, [option format](#option-format) for the list's form, and [Baseline verdicts](#baseline-verdicts) for the baseline definition.
37
+
38
+ <!-- include: ../_partials/option-format.md / -->
37
39
 
38
40
  <!-- include: ../_partials/action-items.md / -->
39
41
 
@@ -66,33 +66,30 @@ When multiple dimensions produce non-baseline verdicts, their actions are combin
66
66
 
67
67
  ## Output format
68
68
 
69
- ```
70
- Next steps:
71
- 1. ♻️ {Update action}
72
- 2. 🏁 {Close action}
73
- 3. 💬 {Comment action}
74
- ```
69
+ Render the list per [option format](SKILL.md#option-format), with each action's icon before its marker. The list always renders, whatever the markers say, because every action writes to the ticket.
70
+
71
+ Mark each action at the strength that the evidence behind its verdict supports. When two actions answer the same verdict, such as an update and a close for `severe` drift, the one that the evidence favors leads.
75
72
 
76
73
  ## Example: Combined output
77
74
 
78
- Assessment produces drift: `partial`, relevance: `relevant` (baseline), progress: `partial`:
75
+ Assessment produces drift: `partial`, relevance: `relevant` (baseline), progress: `partial`, and the remaining work is a small part of the ticket:
79
76
 
80
77
  ```
81
78
  Next steps:
82
- 1. ♻️ Update ticket to match current codebase state
83
- 2. 🏁 Close and create a new ticket scoped to remaining work
79
+ 1. ♻️ ■□□ Update ticket to match current codebase state
80
+ 2. 🏁 ■■□ Close and create a new ticket scoped to remaining work
84
81
  ```
85
82
 
86
- Action 1 combines drift and progress update triggers into a single option. Action 2 comes from progress. Relevance is baseline and contributes nothing.
83
+ Action 1 combines drift and progress update triggers into a single option. Action 2 comes from progress, and leads because a new ticket scoped to the small remainder states the work more plainly than a revised one. Relevance is baseline and contributes nothing.
87
84
 
88
85
  ## Example: Distinct ♻️ flavors
89
86
 
90
- Assessment produces drift: `partial` and advisability: `questionable` (other dimensions baseline):
87
+ Assessment produces drift: `partial` and advisability: `questionable` (other dimensions baseline), and the advisability concern changes the ticket's scope:
91
88
 
92
89
  ```
93
90
  Next steps:
94
- 1. ♻️ Update ticket to match current codebase state
95
- 2. ♻️ Revise ticket to address advisability concerns
91
+ 1. ♻️ ■□□ Update ticket to match current codebase state
92
+ 2. ♻️ ■■□ Revise ticket to address advisability concerns
96
93
  ```
97
94
 
98
- Both actions share the ♻️ icon but represent distinct intents (factual sync with the codebase versus content/scope rework), so they appear as separate numbered options rather than collapsing under the dedupe rule.
95
+ Both actions share the ♻️ icon but represent distinct intents (factual sync with the codebase versus content/scope rework), so they appear as separate numbered options rather than collapsing under the dedupe rule. The revision leads because a scope change also rewrites the parts that the update would sync.
@@ -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
- When the findings leave nothing to triage, 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; otherwise the triage round makes the post. 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, or the ticket is not on a [triage platform](../_data/spike-conventions.md#triage-platforms), 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
 
@@ -45,7 +45,7 @@ Compose the brief with these sections. Each names its `browser` form, then its `
45
45
 
46
46
  1. **Product.** What the product is and whom it serves, in two or three sentences.
47
47
  2. **Targets.** One row per target: its URL, its write rule, its sign-in state, and the method by which a lens grants itself a role or an approval there. A target is read-only unless it is on `localhost` or the developer names it as disposable, per {rulebook:shared-data-conventions}. Writes go to a writable target, with `@example.com` accounts that the lens creates. Under `cli`, one row per target: the binary and its invocation, its write rule, its network and credential state, and what a lens may install. The checkout and every remote source are read-only; each lens's fixture is writable, and its git author is the only identity.
48
- 3. **Lenses.** Three to five: one per role, and one for styling and access. Give each a unique ID prefix (two roles can share an initial), its targets, and its minimum use cases, each with its route. The styling-and-access lens covers light and dark mode, a 1440×900 and a 390×844 viewport, and keyboard-only use of the other lenses' core flows, against the floors in {rulebook:accessibility-conventions}. It runs last, so that it can reach every screen that the earlier lenses found. Under `cli`, each use case has its command lines, and the last lens is output-and-access: the CLI's `--style` or equivalent option, `NO_COLOR`, TTY versus pipe when the developer opted in to `script` and pipe output otherwise, 80 columns, and help and error text, of the other lenses' core flows. Each lens also has its fixture: Create it now with `mktemp -d "${TMPDIR:-/tmp}/usability-{lens slug}.XXXXXX"`, outside the checkout and the artifact directory, as a git repository with `user.name` `Usability Assessor` and `user.email` `assessor@example.com` set locally and one empty initial commit, and name its absolute path in the lens's row.
48
+ 3. **Lenses.** Three to five: one per role, and one for styling and access. Give each a unique ID prefix (two roles can share an initial), its targets, and its minimum use cases, each with its route. The styling-and-access lens covers light and dark mode, a 1440×900 and a 390×844 viewport, and keyboard-only use of the other lenses' core flows, against the floors in {rulebook:accessibility-conventions} and {rulebook:visual-design-conventions}. It runs last, so that it can reach every screen that the earlier lenses found. Under `cli`, each use case has its command lines, and the last lens is output-and-access: the CLI's `--style` or equivalent option, `NO_COLOR`, TTY versus pipe when the developer opted in to `script` and pipe output otherwise, 80 columns, and help and error text, of the other lenses' core flows. Each lens also has its fixture: Create it now with `mktemp -d "${TMPDIR:-/tmp}/usability-{lens slug}.XXXXXX"`, outside the checkout and the artifact directory, as a git repository with `user.name` `Usability Assessor` and `user.email` `assessor@example.com` set locally and one empty initial commit, and name its absolute path in the lens's row.
49
49
  4. **Exclusions.** Routes, surfaces, and products out of scope, such as a developer-only page or a browser extension; under `cli`, commands, flags, and modes, such as one that runs source.
50
50
  5. **Settled.** The decisions above, stated as final, so that a lens does not re-decide them. State the medium as `medium: browser` or `medium: cli`. Under `cli`, also state the pseudo-terminal rule: A lens measures line lengths in captured output rather than observing a terminal, and runs `script` only when the developer opts in at the checkpoint.
51
51
 
@@ -95,6 +95,6 @@ Then publish it as an artifact page: Load the artifact-design skill, and render
95
95
 
96
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
- 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.
98
+ When the artifact has any finding or idea and the ticket is on a [triage platform](../_data/spike-conventions.md#triage-platforms), 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
99
 
100
- 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 use cases exercised and the page's URL.
100
+ Otherwise, name the findings and ideas left for disposal by hand when there are any, and 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.