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
@@ -14,7 +14,7 @@ Publish one index page for a ticket's prototypes instead of one link per prototy
14
14
  A ticket has one prototype set, in its artifact directory:
15
15
 
16
16
  ```
17
- {artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/prototypes/
17
+ {ticket_dir}/prototypes/
18
18
  ├── manifest.json # set title, summary, index URL, one entry per registration
19
19
  ├── shots/{slug}-v{n}.png
20
20
  └── {slug}-v{n}.html # prototype sources
@@ -47,7 +47,7 @@ The set has one list of note labels: a few facts that differ from one prototype
47
47
 
48
48
  ### 1. Resolve the set directory
49
49
 
50
- Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash, and build the set directory from `artifact_base_dir`, `project_slug`, and `ticket_id` as shown above. When `manifest.json` exists there, read it, and [read back the verdicts](#read-back-the-verdicts) before planning the round.
50
+ Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash, and build the set directory from the manifest's `ticket_dir` as shown above. When `manifest.json` exists there, read it, and [read back the verdicts](#read-back-the-verdicts) before planning the round.
51
51
 
52
52
  Resolve a scratch directory for the rendered page: the scratchpad directory that the environment declares, or, when it declares none, a new one:
53
53
 
@@ -6,7 +6,7 @@ user-invocable: true
6
6
 
7
7
  # Investigate spike
8
8
 
9
- Carry out a spike plan, the `## Investigation steps` / `## Deliverable` shape defined in [spike conventions](../_data/spike-conventions.md). A spike produces findings rather than a diff: The run ends with a findings artifact and either the offer of the closing post or, when the findings propose work, the recommendation of the triage round that offers it, not with commits. The skill re-resolves everything it needs from the environment, so it works the same in the session that produced the plan and in a fresh one.
9
+ Carry out a spike plan, the `## Investigation steps` / `## Deliverable` shape defined in [spike conventions](../_data/spike-conventions.md). A spike produces findings rather than a diff: The run ends with a findings artifact and either the offer of the closing post or, when the findings propose work on a [triage platform](../_data/spike-conventions.md#triage-platforms), the recommendation of the triage round that offers it, not with commits. The skill re-resolves everything it needs from the environment, so it works the same in the session that produced the plan and in a fresh one.
10
10
 
11
11
  ## Arguments
12
12
 
@@ -40,8 +40,8 @@ The plan artifact is read-only. It records what was planned, and a later reader
40
40
  7. **Report** the answers and the recommendations against the ticket's questions and decisions, naming any question left unanswered and any departure from the plan, and give the artifact's path.
41
41
 
42
42
  8. **Close** with an action-items block:
43
- - When the findings propose work, recommend {skill?:triage-spike-findings} with the artifact path and the ticket, 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.
44
- - Otherwise, when a ticket governs the run, offer the closing post on it, with its body shown; on consent, post it as that section states.
43
+ - When the findings propose work and the ticket is on a [triage platform](../_data/spike-conventions.md#triage-platforms), recommend {skill?:triage-spike-findings} with the artifact path and the ticket, 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.
44
+ - Otherwise, when a ticket governs the run, name the proposals left for disposal by hand when there are any, and offer to close it with the closing post, with the post's body shown; on consent, post it and close the ticket as that section states.
45
45
 
46
46
  <!-- include: ../_partials/action-items.md / -->
47
47
 
@@ -21,6 +21,7 @@ The split is deliberate: The helper is narrow and mechanical; the classification
21
21
  | `--domain-description` | One-line description for a domain that the write declares. Takes prose, not a path; the path comes from `--folder`. Without it the domain is declared bare. | No |
22
22
  | `--folder` | Topic subpath beneath the assertions root (`content/assertions/`). The helper supplies the `assertions/` segment; pass the topic only. Defaults to `content/assertions/` itself. | No |
23
23
  | `--kb` | Knowledge base name, or `@default` for the registry default. Overrides `.kb/` discovery; the registry default is reachable only via `--kb @default`. | No |
24
+ | `--shared` | Permit a write into a KB whose `visibility` is `shared`. See [Shared KBs](#shared-kbs). | No |
24
25
  | `--survey` | Report the destination's shape and exit. Takes `--kb` alone; writes nothing and does not read stdin. See [step 2](#2-survey-the-destination-kb). | No |
25
26
  | `--tags` | Comma-separated tag list. Known aliases are canonicalized at write time. | No |
26
27
  | `--title` | The note title; also doubles as the filename. | Yes |
@@ -31,6 +32,12 @@ A value-bearing flag accepts both `--diataxis howto` and `--diataxis=howto`. The
31
32
 
32
33
  By default the helper writes to the knowledge base discovered by walking up from the current directory for a `.kb/` folder. When the walk does not discover a `.kb/` and the caller does not pass `--kb`, the helper refuses to write rather than guessing a destination. `--kb <name>` names a specific entry from the merged `kb.yaml` registry and overrides discovery; `--kb @default` is the only way to reach the registry's `default_kb`. The chosen KB is shown in the proposal so that the user can redirect the write via `--kb` if it is wrong.
33
34
 
35
+ ### Shared KBs
36
+
37
+ A KB's `.kb/config.yaml` declares its `visibility`: `shared` for a KB published to collaborators, `private` otherwise; a KB that does not declare it counts as `private`. The helper refuses a write into a `shared` KB unless the invocation passes `--shared`, because a note published in that KB's history cannot be withdrawn.
38
+
39
+ Never pass `--shared` by habit. Read the note's title, tags, and body as a collaborator would, and pass the flag only when they contain nothing unfit for that audience, such as a credential, a personal detail, or a workplace-internal fact. Otherwise, redirect the note to a private KB with `--kb <name>`, or report it uncaptured. When you cannot tell, do not pass the flag. In default mode, the user's confirmation of a proposal that names the KB as shared is the opt-in; in auto mode, the check is yours.
40
+
34
41
  <!-- include: ../../_partials/kb-standard-tags.md / -->
35
42
 
36
43
  ## Runtime dependencies
@@ -74,6 +81,7 @@ It reports:
74
81
 
75
82
  - `kb`: The knowledge base to which the write will resolve, by the same rules.
76
83
  - `taxonomyPath`: The `.kb/taxonomy.yaml` from which the domains came.
84
+ - `visibility`: `shared` or `private`; a write into a `shared` KB needs `--shared`, per [Shared KBs](#shared-kbs).
77
85
  - `domains`: Each declared domain with its `description`, its `provisional` flag, and the `noteCount` at or beneath it.
78
86
  - `undeclaredFolders`: Folders containing notes outside every declared domain.
79
87
 
@@ -98,7 +106,7 @@ Write the note body. Embed cross-references inline when the reference contribute
98
106
 
99
107
  ### 6. Present the proposal (default mode)
100
108
 
101
- In default mode, present the proposed KB, folder, Diátaxis label, title, tags, and body to the user. Name the domain that the folder matched, that domain's description, and the taxonomy file from which they came, so that the user can see what the placement was measured against. When the folder is a new domain, name it as new and propose the description that you will pass as `--domain-description`. When the survey reported an undeclared folder relevant to the choice, say so. Wait for confirmation or a redirect. In auto mode, skip this step.
109
+ In default mode, present the proposed KB, folder, Diátaxis label, title, tags, and body to the user. Name the domain that the folder matched, that domain's description, and the taxonomy file from which they came, so that the user can see what the placement was measured against. When the folder is a new domain, name it as new and propose the description that you will pass as `--domain-description`. When the survey reported an undeclared folder relevant to the choice, say so. When the survey reported `visibility: shared`, say that the KB is shared and that confirming the proposal writes into it with `--shared`. Wait for confirmation or a redirect. In auto mode, skip this step.
102
110
 
103
111
  <!-- include: ../_partials/action-items.md / -->
104
112
 
@@ -110,7 +118,7 @@ Pipe the composed body to the bundled helper. A heredoc keeps multi-line bodies
110
118
  cat <<'EOF' | node {harness_home_dir}/skills/kb-add/kb-add.mjs \
111
119
  --diataxis <label> --title "<title>" \
112
120
  [--kb <name>] [--folder <topic-subpath>] \
113
- [--tags <comma,separated>] [--domain-description "<description>"] [--auto]
121
+ [--tags <comma,separated>] [--domain-description "<description>"] [--auto] [--shared]
114
122
  <note body, may span multiple lines and contain any characters>
115
123
  EOF
116
124
  ```
@@ -150,8 +158,9 @@ On `ok: false`, act on the `error` code:
150
158
  - `missing-destination`: The helper did not discover a `.kb/`, and the invocation did not pass `--kb`. Ask the user where the note should go, passing `--kb <name>` for a specific KB or `--kb @default` for the registry default (or, in auto mode, fail visibly with the categorical reason).
151
159
  - `no-default`: `--kb @default` was given but `kb.yaml` does not configure a `default_kb`. Report the message; have the user name a KB explicitly or configure a default.
152
160
  - `readonly-kb`: The resolved KB is marked `readonly: true` in `kb.yaml`, so the write was refused. Report the message; have the user choose a writable KB with `--kb <name>`.
161
+ - `shared-kb`: The resolved KB is shared and the invocation did not pass `--shared`. Act per [Shared KBs](#shared-kbs).
153
162
  - `invalid-args` / `invalid-title`: Report the helper's message and propose a corrected invocation.
154
- - `invalid-config`: A survey found a malformed `.kb/config.yaml` or `.kb/taxonomy.yaml`. The message names the file; report it and have the user repair it before capturing.
163
+ - `invalid-config`: A survey found a malformed `.kb/config.yaml` or `.kb/taxonomy.yaml`, or a write found a malformed `.kb/config.yaml` and refused because the KB's visibility is unknown. The message names the file; report it and have the user repair it before capturing.
155
164
  - `collision`: A note already exists at the target path. Decide whether to re-title, append the new material to the existing note (read it first, then write a follow-up edit), or abort.
156
165
 
157
166
  ## Completion