codeassembly-guidance 0.0.0 → 0.2.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 (219) hide show
  1. package/.meta/changelog.json +1320 -0
  2. package/CHANGELOG.md +315 -0
  3. package/LICENSE +7 -0
  4. package/README.md +195 -1
  5. package/bin/codeassembly-validate-preferences.js +18 -0
  6. package/content/_partials/README.md +192 -0
  7. package/content/_partials/code-descriptions.md +4 -0
  8. package/content/_partials/code-style.md +7 -0
  9. package/content/_partials/comment-discipline.md +89 -0
  10. package/content/_partials/concision.md +3 -0
  11. package/content/_partials/diff-audit-checklist.md +9 -0
  12. package/content/_partials/file-access.md +4 -0
  13. package/content/_partials/live-repo-writes.md +13 -0
  14. package/content/_partials/plain-speech-calibration.md +70 -0
  15. package/content/_partials/plain-speech.md +13 -0
  16. package/content/_partials/prose-line-breaks.md +3 -0
  17. package/content/_partials/record-marker.md +1 -0
  18. package/content/_partials/reduced-object-relative.md +28 -0
  19. package/content/_partials/shell-commands.md +3 -0
  20. package/content/_partials/target-file-set-resolution.md +22 -0
  21. package/content/_partials/technical-recommendations.md +6 -0
  22. package/content/_partials/test-structure-audit-checklist.md +7 -0
  23. package/content/_partials/ticket-assessment-baseline.md +12 -0
  24. package/content/_partials/ticket-assessment.md +202 -0
  25. package/content/_partials/work-type-choice.md +13 -0
  26. package/content/codeassembly-content.yaml +59 -0
  27. package/content/collections/all.md +11 -0
  28. package/content/collections/atlassian.md +17 -0
  29. package/content/collections/recommended.md +41 -0
  30. package/content/collections/triage.md +13 -0
  31. package/content/collections/williamthorsen.md +26 -0
  32. package/content/guidance/README.md +22 -0
  33. package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
  34. package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
  35. package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
  36. package/content/guidance/rulebooks/accessibility-conventions.md +38 -0
  37. package/content/guidance/rulebooks/cli-conventions.md +192 -0
  38. package/content/guidance/rulebooks/codeassembly-content-specification.md +184 -0
  39. package/content/guidance/rulebooks/command-output-conventions.md +14 -0
  40. package/content/guidance/rulebooks/commit-conventions.md +72 -0
  41. package/content/guidance/rulebooks/generated-content-policy.md +10 -0
  42. package/content/guidance/rulebooks/live-worktree-policy.md +19 -0
  43. package/content/guidance/rulebooks/readme-conventions.md +74 -0
  44. package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
  45. package/content/guidance/rulebooks/shell-conventions.md +273 -0
  46. package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
  47. package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
  48. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +60 -0
  49. package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
  50. package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
  51. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
  52. package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
  53. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
  54. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
  55. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
  56. package/content/guidance/shared/AGENTS.md +51 -0
  57. package/content/scripts/README.md +44 -0
  58. package/content/scripts/check-branch-currency.mjs +11 -0
  59. package/content/scripts/check-prose.mjs +171 -0
  60. package/content/scripts/describe-change.mjs +165 -0
  61. package/content/scripts/get-ticket-id.sh +131 -0
  62. package/content/scripts/manage-jira-ticket.mjs +214 -0
  63. package/content/scripts/resolve-frontmatter.sh +540 -0
  64. package/content/scripts/resolve-review-run.mjs +12 -0
  65. package/content/scripts/select-lede-exemplars.mjs +208 -0
  66. package/content/scripts/validate-preferences.mjs +146 -0
  67. package/content/skills/_data/action-items.md +83 -0
  68. package/content/skills/_data/artifact-conventions.md +1001 -0
  69. package/content/skills/_data/bitbucket-pr-access.md +89 -0
  70. package/content/skills/_data/branch-currency.md +36 -0
  71. package/content/skills/_data/branch-format.md +34 -0
  72. package/content/skills/_data/change-record.md +163 -0
  73. package/content/skills/_data/complexity-classification.md +58 -0
  74. package/content/skills/_data/concision.md +23 -0
  75. package/content/skills/_data/deployed-file-provenance.md +46 -0
  76. package/content/skills/_data/design-priorities.md +76 -0
  77. package/content/skills/_data/gh-body-file.md +30 -0
  78. package/content/skills/_data/git-commands.md +39 -0
  79. package/content/skills/_data/naming-conventions.md +50 -0
  80. package/content/skills/_data/pr-resolution.md +25 -0
  81. package/content/skills/_data/pr-source-resolution.md +36 -0
  82. package/content/skills/_data/project-stage.md +32 -0
  83. package/content/skills/_data/recommendation-gradient.md +92 -0
  84. package/content/skills/_data/scope-and-deferral.md +83 -0
  85. package/content/skills/_data/spike-conventions.md +89 -0
  86. package/content/skills/_data/ticket-evaluation.md +13 -0
  87. package/content/skills/_data/ticket-id-extraction.md +43 -0
  88. package/content/skills/_data/ticket-source-resolution.md +180 -0
  89. package/content/skills/_data/title-templates.md +632 -0
  90. package/content/skills/_data/title-voice.md +17 -0
  91. package/content/skills/_data/work-types.json +168 -0
  92. package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
  93. package/content/skills/_partials/action-items.md +22 -0
  94. package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
  95. package/content/skills/_partials/commit-title-rendering.md +14 -0
  96. package/content/skills/_partials/gh-body-file.md +22 -0
  97. package/content/skills/_partials/jira-task-list-flattening.md +1 -0
  98. package/content/skills/_partials/nested-list-indent.md +9 -0
  99. package/content/skills/_partials/next-steps-after-plan.md +99 -0
  100. package/content/skills/_partials/next-steps-after-review.md +350 -0
  101. package/content/skills/_partials/option-format.md +85 -0
  102. package/content/skills/_partials/plan-template.md +97 -0
  103. package/content/skills/_partials/split-launch-prompts.md +5 -0
  104. package/content/skills/_partials/split-ticket-compose.md +5 -0
  105. package/content/skills/_partials/split-ticket-create.md +3 -0
  106. package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
  107. package/content/skills/_partials/ticket-concision.md +18 -0
  108. package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
  109. package/content/skills/_partials/ticket-placement.md +14 -0
  110. package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
  111. package/content/skills/_partials/ticket-skeleton.md +13 -0
  112. package/content/skills/add-change-record/SKILL.md +136 -0
  113. package/content/skills/add-test-ids/SKILL.md +51 -0
  114. package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
  115. package/content/skills/anti-patterns/SKILL.md +57 -0
  116. package/content/skills/assess-ticket/SKILL.md +46 -0
  117. package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
  118. package/content/skills/assess-usability/SKILL.md +96 -0
  119. package/content/skills/brainstorming/SKILL.md +107 -0
  120. package/content/skills/capture-event/SKILL.md +108 -0
  121. package/content/skills/capture-event/capture-event.mjs +216 -0
  122. package/content/skills/capture-feedback/SKILL.md +71 -0
  123. package/content/skills/capture-lede-decision/SKILL.md +163 -0
  124. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
  125. package/content/skills/classify-complexity/SKILL.md +92 -0
  126. package/content/skills/collaborate/SKILL.md +86 -0
  127. package/content/skills/condense-branch/SKILL.md +83 -0
  128. package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
  129. package/content/skills/create-commit/SKILL.md +65 -0
  130. package/content/skills/create-devlog/SKILL.md +108 -0
  131. package/content/skills/create-gh-pr/SKILL.md +121 -0
  132. package/content/skills/create-pr/SKILL.md +150 -0
  133. package/content/skills/create-ticket/SKILL.md +395 -0
  134. package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
  135. package/content/skills/derive-session-context/derive-session-context.mjs +149 -0
  136. package/content/skills/design-and-plan/SKILL.md +197 -0
  137. package/content/skills/development-workflows/SKILL.md +41 -0
  138. package/content/skills/get-ticket-id/SKILL.md +67 -0
  139. package/content/skills/groom-backlog/SKILL.md +247 -0
  140. package/content/skills/groom-backlog/groom-backlog.mjs +108 -0
  141. package/content/skills/implement-plan/SKILL.md +168 -0
  142. package/content/skills/index-prototypes/SKILL.md +200 -0
  143. package/content/skills/index-prototypes/index-prototypes.mjs +388 -0
  144. package/content/skills/kb-add/SKILL.md +157 -0
  145. package/content/skills/kb-add/kb-add.mjs +216 -0
  146. package/content/skills/kb-curate/SKILL.md +119 -0
  147. package/content/skills/kb-curate/kb-curate.mjs +213 -0
  148. package/content/skills/kb-edit/SKILL.md +128 -0
  149. package/content/skills/kb-edit/kb-edit.mjs +219 -0
  150. package/content/skills/kb-retrieve/SKILL.md +100 -0
  151. package/content/skills/kb-retrieve/kb-retrieve.mjs +207 -0
  152. package/content/skills/kb-retrieve-events/SKILL.md +98 -0
  153. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +207 -0
  154. package/content/skills/kb-update-events/SKILL.md +77 -0
  155. package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
  156. package/content/skills/merge-bb-pr/SKILL.md +136 -0
  157. package/content/skills/merge-gh-pr/SKILL.md +167 -0
  158. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
  159. package/content/skills/merge-pr/SKILL.md +368 -0
  160. package/content/skills/migrate-feedback-memories/SKILL.md +137 -0
  161. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
  162. package/content/skills/people-report/SKILL.md +208 -0
  163. package/content/skills/plan/SKILL.md +87 -0
  164. package/content/skills/prepare-prototype-brief/SKILL.md +178 -0
  165. package/content/skills/pull-from-backlog/SKILL.md +83 -0
  166. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +209 -0
  167. package/content/skills/refine-plan/SKILL.md +263 -0
  168. package/content/skills/refine-prototype/SKILL.md +113 -0
  169. package/content/skills/respond-to-review/SKILL.md +292 -0
  170. package/content/skills/review-bb-pr/SKILL.md +161 -0
  171. package/content/skills/review-branch/SKILL.md +303 -0
  172. package/content/skills/review-criteria/SKILL.md +141 -0
  173. package/content/skills/review-gh-pr/SKILL.md +155 -0
  174. package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
  175. package/content/skills/review-permissions/SKILL.md +39 -0
  176. package/content/skills/review-pr/SKILL.md +123 -0
  177. package/content/skills/revise-comments/SKILL.md +148 -0
  178. package/content/skills/revise-prose/SKILL.md +197 -0
  179. package/content/skills/revise-prose/revise-prose.mjs +229 -0
  180. package/content/skills/save-artifact/SKILL.md +71 -0
  181. package/content/skills/save-plan/SKILL.md +55 -0
  182. package/content/skills/software-engineering/SKILL.md +74 -0
  183. package/content/skills/streamline-guidance/SKILL.md +174 -0
  184. package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
  185. package/content/skills/summarize-change/SKILL.md +317 -0
  186. package/content/skills/summarize-chat/SKILL.md +100 -0
  187. package/content/skills/systematic-debugging/SKILL.md +308 -0
  188. package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
  189. package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
  190. package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
  191. package/content/skills/systematic-debugging/find-polluter.sh +68 -0
  192. package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
  193. package/content/skills/systematic-debugging/test-academic.md +16 -0
  194. package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
  195. package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
  196. package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
  197. package/content/skills/testing-conventions/SKILL.md +235 -0
  198. package/content/skills/triage-spike-findings/SKILL.md +113 -0
  199. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +71 -0
  200. package/content/skills/typescript-testing-conventions/SKILL.md +178 -0
  201. package/content/skills/update-jira-ticket/SKILL.md +257 -0
  202. package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
  203. package/content/skills/update-project-guidance/SKILL.md +300 -0
  204. package/content/skills/upgrade-dependencies/SKILL.md +139 -0
  205. package/content/skills/wrap-up/SKILL.md +431 -0
  206. package/content/subagents/_data/claude.yaml +25 -0
  207. package/content/subagents/_data/rovo.yaml +41 -0
  208. package/content/subagents/canary.md +12 -0
  209. package/content/subagents/disposition-challenger.md +78 -0
  210. package/content/subagents/entry-drafter.md +191 -0
  211. package/content/subagents/handoff-reviewer.md +75 -0
  212. package/content/subagents/plan-reviewer.md +184 -0
  213. package/content/subagents/plan-reviser.md +88 -0
  214. package/content/subagents/prose-reviser.md +132 -0
  215. package/content/subagents/ticket-assessor.md +142 -0
  216. package/content/subagents/usability-assessor.md +157 -0
  217. package/package.json +74 -2
  218. package/schemas/preferences.v1.json +321 -0
  219. package/schemas/work-types.v1.json +142 -0
@@ -0,0 +1,100 @@
1
+ ---
2
+ name: kb-retrieve
3
+ description: Query the knowledge base for assertions relevant to a task and return a ranked list with freshness and supersession signals
4
+ user-invocable: true
5
+ ---
6
+
7
+ # Retrieve knowledge-base assertions
8
+
9
+ Find the knowledge-base assertions most relevant to a query. A bundled helper does the mechanical recall: It resolves which knowledge bases to search, runs ripgrep over note files, expands query terms through the tag aliases, and emits a structured candidate table. You then rank those candidates by genuine relevance and present a ranked list.
10
+
11
+ The split is deliberate: The helper is wide and mechanical; the ranking is narrow and judgment-driven. Treat the helper's output as evidence, not as a finished answer.
12
+
13
+ This skill returns assertions, the canonical knowledge-base notes. For event recall (the raw observations captured to refine assertions), use `kb-retrieve-events` instead.
14
+
15
+ **Announce at start:** "Using kb-retrieve to search for {query}."
16
+
17
+ ## Arguments
18
+
19
+ | Argument | Description | Required |
20
+ | ------------ | -------------------------------------------------------------------------------------- | -------- |
21
+ | `<query>` | The free-text search query. All non-flag tokens are joined into the query string. | Yes |
22
+ | `--all-kbs` | Widen the search to every registered knowledge base, not just the default scope. | No |
23
+ | `--store` | Scope the search to a single registered knowledge base by name (alias: `--kb`). | No |
24
+ | `--diataxis` | Keep only notes whose `diataxis` facet matches (e.g. `howto`, `concept`, `reference`). | No |
25
+ | `--tag` | Keep only notes with this tag (canonical or alias form), matched case-insensitively. | No |
26
+ | `--folder` | Keep only notes whose path contains this folder segment. | No |
27
+
28
+ A value-bearing flag accepts both `--diataxis howto` and `--diataxis=howto`.
29
+
30
+ ### Scope
31
+
32
+ By default the helper searches up to two knowledge bases: the one discovered by walking up from the current directory for a `.kb/` folder, plus the registry's `default_kb` (the machine's default knowledge base). When neither source resolves, or the two resolve to the same path, the default scope contains fewer than two. `--all-kbs` widens the search to every knowledge base declared in the merged `kb.yaml` registry.
33
+
34
+ `--store <name>` (alias `--kb <name>`) narrows the search to a single registered knowledge base, resolved by registry name alone: The helper does not run a `.kb/` discovery walk, so a project-local `.kb/` near which the helper happened to be invoked is never in scope. A name that does not match any registry entry yields an empty result with an explanatory diagnostic.
35
+
36
+ Within each knowledge base, recall is limited to the notes declared by the store, the files matching its configured `targets`/`exclude` (the same note set that `kb check` enforces; `content/**/*.md` by default). Inside a git working tree, that set also excludes every note that the repository ignores. Markdown outside that set, such as a root `README.md` or an excluded draft, is not recalled even when it contains the query terms.
37
+
38
+ ## Runtime dependencies
39
+
40
+ - **`node` ≥ 24**: The bundled helper inherits the Node version floor of `@williamthorsen/kb`.
41
+ - **`ripgrep` (`rg`)**: The recall backend; the helper exits with a remediation hint when it is missing.
42
+
43
+ ## Process
44
+
45
+ ### 1. Run the recall helper
46
+
47
+ Invoke the co-located bundled helper with `node`, passing the query and any flags through verbatim:
48
+
49
+ ```bash
50
+ node {harness_home_dir}/skills/kb-retrieve/kb-retrieve.mjs <query> [--all-kbs] [--store <name>] [--diataxis <label>] [--tag <tag>] [--folder <folder>]
51
+ ```
52
+
53
+ A worked example:
54
+
55
+ ```bash
56
+ node {harness_home_dir}/skills/kb-retrieve/kb-retrieve.mjs "pnpm workspace setup" --diataxis howto
57
+ ```
58
+
59
+ The helper prints a JSON object to stdout:
60
+
61
+ - `candidates`: An array of assertion candidates, each with `path`, `title`, `diataxis`, `tags`, `snippet`, `lastVerifiedAgeDays`, `supersession`, and `kbName`. A candidate also has `addressedBy` -- the references from its `addressed-by` list (what was done about the problem that it notes) -- when the note declares one. A note that matches but does not declare a recordType is returned as a degraded candidate with a `diagnostic`, so a note broken in that way is not hidden from recall.
62
+ - `scopedKbs`: The knowledge bases that were actually searched.
63
+ - `warnings`: An array (possibly empty) of registry-health problems, present even when candidates are returned.
64
+ - `diagnostic`: Present only when scope is empty or the query did not match any notes.
65
+
66
+ ### 2. Rank the candidates
67
+
68
+ Parse the JSON and rank the `candidates` by genuine relevance to the query's intent. Tag, Diátaxis, and folder overlap with the query are **evidence**, not terms in a weighted sum: A note in the right folder with the wrong intent ranks below a note that directly answers the question. Read each `snippet` to judge whether the note actually addresses the query rather than merely mentioning its terms.
69
+
70
+ Once relevance is established, rank by freshness: A recently verified note outranks a stale one of equal relevance. `lastVerifiedAgeDays` is the freshness signal, the whole days since the note was last verified.
71
+
72
+ ### 3. Present a ranked list
73
+
74
+ Present the ranked notes, each showing `path`, `title`, `snippet`, and `diataxis`. Apply these annotations:
75
+
76
+ - **Stale notes**: When `lastVerifiedAgeDays` exceeds 90, annotate the note as not recently verified.
77
+ - **Volatile notes**: When a note's `tags` include `volatile`, flag it prominently: Its claims may be out of date and should be re-confirmed before use.
78
+ - **Deprecated notes**: When a note's `tags` include `deprecated`, or its `supersession.superseded` is `true`, refer the reader to the successor: Prefer `supersession.canonicalPath` and present the canonical note in place of the deprecated one. When `supersession.diagnostic` is set (a broken or cyclic `superseded-by` chain), report that the chain could not be fully followed.
79
+ - **Addressed problems**: When a candidate has `addressedBy`, show its references so that a recurring-but-addressed problem reads as _addressed_ rather than _unaddressed_. The references are heterogeneous (a KB note, a commit, a PR/issue, or a URL), and the relation is neutral: It records what was done about the problem, not that the problem is verifiably resolved. Unlike supersession, it does not redirect the reader; the record remains a true observation worth keeping.
80
+
81
+ ### 4. Report empty results plainly
82
+
83
+ When the helper returns a `diagnostic` without any candidates, report the empty result plainly; do not treat it as an error. `diagnostic` explains **why the result is empty**:
84
+
85
+ - `no knowledge base configured or discovered`: The helper did not find a `.kb/` folder, and a `kb.yaml` registry is not configured.
86
+ - `registry invalid: …`: The only configured `kb.yaml` registry failed to load, so the helper could not search any knowledge base; this is a setup problem to fix, not a missing-notes outcome.
87
+ - `the query did not match any notes`: The knowledge bases were searched but nothing matched; suggest broadening the query or adding `--all-kbs`. An empty `warnings` array is the reliable signal that the in-scope KBs were actually searched and genuinely contained nothing; when `warnings` is non-empty, a registry-health problem (a malformed registry or dead KB paths) may explain the empty or partial result even though the diagnostic reads `the query did not match any notes`. Read `warnings` before concluding the query simply found nothing.
88
+ - `all matches were filtered out`: The knowledge bases were searched and found hits, but every hit was excluded by `--diataxis`, `--tag`, or `--folder`; suggest dropping or loosening a filter rather than broadening the query.
89
+ - `matches were found but none are assertions; use kb-retrieve-events for event recall`: The query matched only non-assertion records, such as events; the reader likely wants `kb-retrieve-events`.
90
+
91
+ ### 5. Relay registry-health warnings
92
+
93
+ `warnings` is separate from `diagnostic`: It reports **what is wrong with the registry**, and it is present even when candidates are returned. Always relay any warning to the user as a setup problem to fix, not as a failed query, so that a degraded registry does not silently shrink the search:
94
+
95
+ - `registry invalid: …`: The `kb.yaml` registry could not be loaded; entries that it would have contributed are missing from the search.
96
+ - `… path does not exist: …`: A registry entry names a knowledge base whose directory is absent on disk, so that KB was skipped; the entry or the directory needs fixing.
97
+
98
+ ## Completion
99
+
100
+ A ranked list of relevant notes with freshness and supersession annotations, or a plain empty-result report.