codeassembly-guidance 0.0.0 → 0.1.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 (204) hide show
  1. package/.meta/changelog.json +563 -0
  2. package/CHANGELOG.md +134 -0
  3. package/LICENSE +7 -0
  4. package/README.md +165 -1
  5. package/content/_partials/README.md +192 -0
  6. package/content/_partials/code-descriptions.md +4 -0
  7. package/content/_partials/code-style.md +7 -0
  8. package/content/_partials/comment-discipline.md +89 -0
  9. package/content/_partials/concision.md +3 -0
  10. package/content/_partials/diff-audit-checklist.md +9 -0
  11. package/content/_partials/file-access.md +4 -0
  12. package/content/_partials/live-repo-writes.md +13 -0
  13. package/content/_partials/plain-speech-calibration.md +66 -0
  14. package/content/_partials/plain-speech.md +13 -0
  15. package/content/_partials/prose-line-breaks.md +3 -0
  16. package/content/_partials/record-marker.md +1 -0
  17. package/content/_partials/reduced-object-relative.md +28 -0
  18. package/content/_partials/shell-commands.md +3 -0
  19. package/content/_partials/target-file-set-resolution.md +22 -0
  20. package/content/_partials/technical-recommendations.md +5 -0
  21. package/content/_partials/test-structure-audit-checklist.md +7 -0
  22. package/content/_partials/ticket-assessment-baseline.md +12 -0
  23. package/content/_partials/ticket-assessment.md +202 -0
  24. package/content/_partials/work-type-choice.md +13 -0
  25. package/content/codeassembly-content.yaml +49 -0
  26. package/content/collections/all.md +11 -0
  27. package/content/collections/atlassian.md +16 -0
  28. package/content/collections/recommended.md +34 -0
  29. package/content/collections/triage.md +77 -0
  30. package/content/collections/williamthorsen.md +25 -0
  31. package/content/guidance/README.md +22 -0
  32. package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
  33. package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
  34. package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
  35. package/content/guidance/rulebooks/accessibility-conventions.md +20 -0
  36. package/content/guidance/rulebooks/codeassembly-content-specification.md +161 -0
  37. package/content/guidance/rulebooks/command-output-conventions.md +14 -0
  38. package/content/guidance/rulebooks/commit-conventions.md +72 -0
  39. package/content/guidance/rulebooks/generated-content-policy.md +10 -0
  40. package/content/guidance/rulebooks/live-worktree-policy.md +18 -0
  41. package/content/guidance/rulebooks/readme-conventions.md +74 -0
  42. package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
  43. package/content/guidance/rulebooks/shell-conventions.md +279 -0
  44. package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
  45. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +58 -0
  46. package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
  47. package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
  48. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
  49. package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
  50. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
  51. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
  52. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
  53. package/content/guidance/shared/AGENTS.md +43 -0
  54. package/content/scripts/README.md +41 -0
  55. package/content/scripts/describe-change.mjs +165 -0
  56. package/content/scripts/get-ticket-id.sh +131 -0
  57. package/content/scripts/manage-jira-ticket.mjs +209 -0
  58. package/content/scripts/resolve-frontmatter.sh +540 -0
  59. package/content/scripts/resolve-review-run.mjs +12 -0
  60. package/content/scripts/select-lede-exemplars.mjs +208 -0
  61. package/content/skills/_data/action-items.md +83 -0
  62. package/content/skills/_data/artifact-conventions.md +969 -0
  63. package/content/skills/_data/bitbucket-pr-access.md +89 -0
  64. package/content/skills/_data/branch-format.md +34 -0
  65. package/content/skills/_data/change-record.md +163 -0
  66. package/content/skills/_data/complexity-classification.md +58 -0
  67. package/content/skills/_data/concision.md +23 -0
  68. package/content/skills/_data/deployed-file-provenance.md +46 -0
  69. package/content/skills/_data/design-priorities.md +76 -0
  70. package/content/skills/_data/gh-body-file.md +30 -0
  71. package/content/skills/_data/git-commands.md +39 -0
  72. package/content/skills/_data/naming-conventions.md +50 -0
  73. package/content/skills/_data/pr-resolution.md +25 -0
  74. package/content/skills/_data/pr-source-resolution.md +36 -0
  75. package/content/skills/_data/recommendation-gradient.md +90 -0
  76. package/content/skills/_data/scope-and-deferral.md +83 -0
  77. package/content/skills/_data/spike-conventions.md +89 -0
  78. package/content/skills/_data/ticket-evaluation.md +13 -0
  79. package/content/skills/_data/ticket-id-extraction.md +43 -0
  80. package/content/skills/_data/ticket-source-resolution.md +147 -0
  81. package/content/skills/_data/title-templates.md +624 -0
  82. package/content/skills/_data/title-voice.md +17 -0
  83. package/content/skills/_data/work-types.json +168 -0
  84. package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
  85. package/content/skills/_partials/action-items.md +22 -0
  86. package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
  87. package/content/skills/_partials/commit-title-rendering.md +14 -0
  88. package/content/skills/_partials/gh-body-file.md +22 -0
  89. package/content/skills/_partials/nested-list-indent.md +9 -0
  90. package/content/skills/_partials/next-steps-after-plan.md +99 -0
  91. package/content/skills/_partials/next-steps-after-review.md +350 -0
  92. package/content/skills/_partials/option-format.md +84 -0
  93. package/content/skills/_partials/plan-template.md +97 -0
  94. package/content/skills/_partials/split-launch-prompts.md +5 -0
  95. package/content/skills/_partials/split-ticket-compose.md +5 -0
  96. package/content/skills/_partials/split-ticket-create.md +3 -0
  97. package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
  98. package/content/skills/_partials/ticket-concision.md +18 -0
  99. package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
  100. package/content/skills/_partials/ticket-placement.md +14 -0
  101. package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
  102. package/content/skills/_partials/ticket-skeleton.md +13 -0
  103. package/content/skills/add-change-record/SKILL.md +136 -0
  104. package/content/skills/add-test-ids/SKILL.md +51 -0
  105. package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
  106. package/content/skills/anti-patterns/SKILL.md +57 -0
  107. package/content/skills/assess-ticket/SKILL.md +46 -0
  108. package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
  109. package/content/skills/brainstorming/SKILL.md +107 -0
  110. package/content/skills/capture-event/SKILL.md +108 -0
  111. package/content/skills/capture-event/capture-event.mjs +216 -0
  112. package/content/skills/capture-feedback/SKILL.md +71 -0
  113. package/content/skills/capture-lede-decision/SKILL.md +163 -0
  114. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
  115. package/content/skills/classify-complexity/SKILL.md +92 -0
  116. package/content/skills/collaborate/SKILL.md +86 -0
  117. package/content/skills/condense-branch/SKILL.md +83 -0
  118. package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
  119. package/content/skills/create-commit/SKILL.md +65 -0
  120. package/content/skills/create-devlog/SKILL.md +108 -0
  121. package/content/skills/create-gh-pr/SKILL.md +106 -0
  122. package/content/skills/create-pr/SKILL.md +150 -0
  123. package/content/skills/create-ticket/SKILL.md +350 -0
  124. package/content/skills/derive-session-context/derive-session-context.mjs +148 -0
  125. package/content/skills/design-and-plan/SKILL.md +194 -0
  126. package/content/skills/development-workflows/SKILL.md +41 -0
  127. package/content/skills/get-ticket-id/SKILL.md +67 -0
  128. package/content/skills/groom-backlog/SKILL.md +245 -0
  129. package/content/skills/groom-backlog/groom-backlog.mjs +106 -0
  130. package/content/skills/implement-plan/SKILL.md +164 -0
  131. package/content/skills/index-prototypes/SKILL.md +145 -0
  132. package/content/skills/index-prototypes/index-prototypes.mjs +328 -0
  133. package/content/skills/kb-add/SKILL.md +156 -0
  134. package/content/skills/kb-add/kb-add.mjs +216 -0
  135. package/content/skills/kb-curate/SKILL.md +117 -0
  136. package/content/skills/kb-curate/kb-curate.mjs +213 -0
  137. package/content/skills/kb-edit/SKILL.md +128 -0
  138. package/content/skills/kb-edit/kb-edit.mjs +219 -0
  139. package/content/skills/kb-retrieve/SKILL.md +100 -0
  140. package/content/skills/kb-retrieve/kb-retrieve.mjs +206 -0
  141. package/content/skills/kb-retrieve-events/SKILL.md +98 -0
  142. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +206 -0
  143. package/content/skills/kb-update-events/SKILL.md +77 -0
  144. package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
  145. package/content/skills/merge-bb-pr/SKILL.md +136 -0
  146. package/content/skills/merge-gh-pr/SKILL.md +167 -0
  147. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
  148. package/content/skills/merge-pr/SKILL.md +368 -0
  149. package/content/skills/migrate-feedback-memories/SKILL.md +136 -0
  150. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
  151. package/content/skills/people-report/SKILL.md +208 -0
  152. package/content/skills/plan/SKILL.md +87 -0
  153. package/content/skills/prepare-prototype-brief/SKILL.md +126 -0
  154. package/content/skills/pull-from-backlog/SKILL.md +83 -0
  155. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +208 -0
  156. package/content/skills/refine-plan/SKILL.md +259 -0
  157. package/content/skills/respond-to-review/SKILL.md +292 -0
  158. package/content/skills/review-bb-pr/SKILL.md +161 -0
  159. package/content/skills/review-branch/SKILL.md +301 -0
  160. package/content/skills/review-criteria/SKILL.md +108 -0
  161. package/content/skills/review-gh-pr/SKILL.md +155 -0
  162. package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
  163. package/content/skills/review-permissions/SKILL.md +39 -0
  164. package/content/skills/review-pr/SKILL.md +123 -0
  165. package/content/skills/revise-comments/SKILL.md +115 -0
  166. package/content/skills/revise-prose/SKILL.md +197 -0
  167. package/content/skills/revise-prose/revise-prose.mjs +229 -0
  168. package/content/skills/save-artifact/SKILL.md +69 -0
  169. package/content/skills/save-plan/SKILL.md +55 -0
  170. package/content/skills/software-engineering/SKILL.md +74 -0
  171. package/content/skills/streamline-guidance/SKILL.md +174 -0
  172. package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
  173. package/content/skills/summarize-change/SKILL.md +308 -0
  174. package/content/skills/summarize-chat/SKILL.md +100 -0
  175. package/content/skills/systematic-debugging/SKILL.md +308 -0
  176. package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
  177. package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
  178. package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
  179. package/content/skills/systematic-debugging/find-polluter.sh +68 -0
  180. package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
  181. package/content/skills/systematic-debugging/test-academic.md +16 -0
  182. package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
  183. package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
  184. package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
  185. package/content/skills/testing-conventions/SKILL.md +168 -0
  186. package/content/skills/testing-conventions/mistakes.md +1 -0
  187. package/content/skills/typescript-testing-conventions/SKILL.md +129 -0
  188. package/content/skills/update-jira-ticket/SKILL.md +245 -0
  189. package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
  190. package/content/skills/update-project-guidance/SKILL.md +300 -0
  191. package/content/skills/upgrade-dependencies/SKILL.md +139 -0
  192. package/content/skills/wrap-up/SKILL.md +431 -0
  193. package/content/subagents/_data/claude.yaml +19 -0
  194. package/content/subagents/_data/rovo.yaml +31 -0
  195. package/content/subagents/canary.md +11 -0
  196. package/content/subagents/entry-drafter.md +187 -0
  197. package/content/subagents/handoff-reviewer.md +75 -0
  198. package/content/subagents/plan-reviewer.md +184 -0
  199. package/content/subagents/plan-reviser.md +88 -0
  200. package/content/subagents/prose-reviser.md +130 -0
  201. package/content/subagents/ticket-assessor.md +139 -0
  202. package/package.json +70 -2
  203. package/schemas/preferences.v1.json +294 -0
  204. package/schemas/work-types.v1.json +142 -0
@@ -0,0 +1,107 @@
1
+ ---
2
+ name: brainstorming
3
+ description: 'You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation.'
4
+ user-invocable: false
5
+ supported-harnesses: [rovo]
6
+ ---
7
+
8
+ <!-- Extracted verbatim from the superpowers plugin. Do not edit. -->
9
+
10
+ # Brainstorming Ideas Into Designs
11
+
12
+ ## Overview
13
+
14
+ Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
15
+
16
+ Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.
17
+
18
+ <HARD-GATE>
19
+ Do NOT use any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
20
+ </HARD-GATE>
21
+
22
+ ## Anti-Pattern: "This Is Too Simple To Need A Design"
23
+
24
+ Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
25
+
26
+ ## Checklist
27
+
28
+ You MUST create a task for each of these items and complete them in order:
29
+
30
+ 1. **Explore project context** — check files, docs, recent commits
31
+ 2. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
32
+ 3. **Propose 2-3 approaches** — with trade-offs and your recommendation
33
+ 4. **Present design** — in sections scaled to their complexity, get user approval after each section
34
+ 5. **Write design doc** — save to `docs/plans/YYYY-MM-DD-<topic>-design.md` and commit
35
+ 6. **Transition to implementation** — use writing-plans skill to create implementation plan
36
+
37
+ ## Process Flow
38
+
39
+ ```dot
40
+ digraph brainstorming {
41
+ "Explore project context" [shape=box];
42
+ "Ask clarifying questions" [shape=box];
43
+ "Propose 2-3 approaches" [shape=box];
44
+ "Present design sections" [shape=box];
45
+ "User approves design?" [shape=diamond];
46
+ "Write design doc" [shape=box];
47
+ "Use writing-plans skill" [shape=doublecircle];
48
+
49
+ "Explore project context" -> "Ask clarifying questions";
50
+ "Ask clarifying questions" -> "Propose 2-3 approaches";
51
+ "Propose 2-3 approaches" -> "Present design sections";
52
+ "Present design sections" -> "User approves design?";
53
+ "User approves design?" -> "Present design sections" [label="no, revise"];
54
+ "User approves design?" -> "Write design doc" [label="yes"];
55
+ "Write design doc" -> "Use writing-plans skill";
56
+ }
57
+ ```
58
+
59
+ **The terminal state is using writing-plans.** Do NOT use frontend-design, mcp-builder, or any other implementation skill. The ONLY skill you use after brainstorming is writing-plans.
60
+
61
+ ## The Process
62
+
63
+ **Understanding the idea:**
64
+
65
+ - Check out the current project state first (files, docs, recent commits)
66
+ - Ask questions one at a time to refine the idea
67
+ - Prefer multiple choice questions when possible, but open-ended is fine too
68
+ - Only one question per message - if a topic needs more exploration, break it into multiple questions
69
+ - Focus on understanding: purpose, constraints, success criteria
70
+
71
+ **Exploring approaches:**
72
+
73
+ - Propose 2-3 different approaches with trade-offs
74
+ - Present options conversationally with your recommendation and reasoning
75
+ - Lead with your recommended option and explain why
76
+
77
+ **Presenting the design:**
78
+
79
+ - Once you believe you understand what you're building, present the design
80
+ - Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced
81
+ - Ask after each section whether it looks right so far
82
+ - Cover architecture, components, data flow, error handling, testing
83
+ - Be ready to go back and clarify if something doesn't make sense
84
+
85
+ <!-- include: ../_partials/action-items.md / -->
86
+
87
+ ## After the Design
88
+
89
+ **Documentation:**
90
+
91
+ - Write the validated design to `docs/plans/YYYY-MM-DD-<topic>-design.md`
92
+ - Use elements-of-style:writing-clearly-and-concisely skill if available
93
+ - Commit the design document to git
94
+
95
+ **Implementation:**
96
+
97
+ - Use the writing-plans skill to create a detailed implementation plan
98
+ - Do NOT use any other skill. writing-plans is the next step.
99
+
100
+ ## Key Principles
101
+
102
+ - **One question at a time** - Don't overwhelm with multiple questions
103
+ - **Multiple choice preferred** - Easier to answer than open-ended when possible
104
+ - **YAGNI ruthlessly** - Remove unnecessary features from all designs
105
+ - **Explore alternatives** - Always propose 2-3 approaches before settling
106
+ - **Incremental validation** - Present design, get approval before moving on
107
+ - **Be flexible** - Go back and clarify when something doesn't make sense
@@ -0,0 +1,108 @@
1
+ ---
2
+ name: capture-event
3
+ description: 'Capture an event into the shared knowledge substrate. Use when noticing something worth recording for later recall: an observation, a pattern, a refinement, a surprising API surface, a workaround, or a problem that you hit and resolved. A fast pure append, without a survey, recall, or dedup.'
4
+ user-invocable: true
5
+ ---
6
+
7
+ # Capture an event
8
+
9
+ Append an event record to the shared knowledge substrate, or amend an existing one. A bundled helper does the mechanical work: It resolves the event store by name, auto-fills the record's context (a ULID `id`, the capture timestamp, the working directory, and a best-effort `session` and `repo`), validates the event record's required fields, and writes the record atomically. You supply the `summary` and the event body.
10
+
11
+ This is a pure append. Unlike `kb-add`, it does not run a survey, `kb-retrieve` cross-referencing, or dedup. The point is to capture the event cheaply and move on; a later pass recalls and triages the record via `kb-retrieve`.
12
+
13
+ **Announce at start:** "Using capture-event to record this event."
14
+
15
+ ## When to capture
16
+
17
+ Capture anything worth recalling later: a behavior, a pattern, a refinement, a surprising API surface, a workaround. Problem→solution and pattern-plus-refinement are useful shapes, but an event may simply be an observation; do not force it into a template.
18
+
19
+ A **solved-problem episode**, a problem that you hit and resolved, is worth tagging so that you can recall past fixes as a group: Capture it with `--tags fix` (plus any topical tags), putting the problem and its resolution in the body. The `fix` tag lets you recall past fixes together later.
20
+
21
+ A **skill-caused mistake**, an error that a clearer skill definition would have prevented, is worth tagging the same way: Capture it with `--tags mistake` and `--skill <skill-at-fault>`, putting what went wrong and what the skill should have said in the body. The `mistake` tag lets you recall skill mistakes as a group when deciding which skills to revise.
22
+
23
+ ## Arguments
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 |
35
+
36
+ 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
+ ### Auto-filled vs agent-supplied
39
+
40
+ - **Auto-filled by the helper:** `recordType` (`event`), `id` (ULID), `captured-at`, `cwd`, `session` (`CLAUDE_CODE_SESSION_ID`, best-effort; omitted silently on a harness that does not expose a session id), and `repo` (the `owner/name` git remote at `cwd`, best-effort; omitted silently when the helper cannot resolve a remote at `cwd`).
41
+ - **Template-injected:** `harness`. `codeassembly` writes the agent platform (`claude` or `rovo`) into the `--harness` flag when it installs this skill. Unlike `model`, which varies per session and is self-reported, the harness is fixed at install time; keep the injected `--harness` flag verbatim rather than filling in a value yourself.
42
+ - **Agent-supplied:** `summary`, the optional `skill`/`model`/`tags`/`impact`, and the body.
43
+
44
+ ### Store selection
45
+
46
+ `--store` is required: Every capture names its destination. The helper resolves the store by registry name only. It never walks the working directory for a `.kb/` folder, so a capture goes to the named store and never to a project-local KB near which it happened to be invoked. The store must be registered in `kb.yaml`. Omitting `--store` is refused with an error that lists the registered stores rather than defaulting silently.
47
+
48
+ Choose the destination deliberately. When the lesson is specific to a project, pass that project's KB with `--store <name>`. Only when the lesson is environment-level, meaning an observation or refinement that applies across every project in the current environment, send it to the registry's `default_kb` by passing `--store @default`. Selecting the default is an explicit act, not what happens when the flag is forgotten.
49
+
50
+ 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
+ ### Amending an event
53
+
54
+ `--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 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.
55
+
56
+ Amend is a plain in-place edit and does not consult push state. To correct an event that may already have been shared, prefer appending a supersession with `kb-update-events --add-addressed-by` over rewriting it, so that the correction becomes a new record rather than a change to history.
57
+
58
+ ## Runtime dependencies
59
+
60
+ - **`node` ≥ 24**: The bundled helper inherits the Node version floor of `@williamthorsen/kb`.
61
+ - **A `kb.yaml` registry naming the store**: The helper resolves `--store` through `.agents/kb.yaml` in the project or `~/.agents/kb.yaml`. When the named store is not declared in either registry, every capture is refused rather than written somewhere else.
62
+
63
+ ## Process
64
+
65
+ ### 1. Compose the summary and body
66
+
67
+ Write a one-line `--summary` that reads well on its own (it is the record's recall label). Put the detail (context, the problem and its resolution, the pattern and its refinement) in the body on stdin. Capture enough context that the event is intelligible months later without the surrounding conversation.
68
+
69
+ Optionally rate `--impact` (`low`, `medium`, `high`, or `critical`): your subjective read of how much addressing the event matters, which applies equally to a bug and to a beneficial change. Omit it when you do not have a clear read; an unrated event is left for a later triage pass. The rating is revisable later with `kb-update-events`.
70
+
71
+ ### 2. Invoke the helper
72
+
73
+ Pipe the body to the bundled helper. A heredoc keeps multi-line bodies legible:
74
+
75
+ ```bash
76
+ cat <<'EOF' | node {harness_home_dir}/skills/capture-event/capture-event.mjs \
77
+ --summary "<one-line summary>" \
78
+ --store <name|@default|@feedback> \
79
+ --harness {harness_id} \
80
+ [--skill <skill>] [--model <model>] [--tags <comma,separated>] [--impact <level>]
81
+ <event body, may span multiple lines and contain any characters>
82
+ EOF
83
+ ```
84
+
85
+ The helper prints a JSON object to stdout:
86
+
87
+ - `ok: true` with `id`, `capturedAt`, `path`, `store` on success.
88
+ - `ok: false` with `error`, `message`, and optional `errors` on a recoverable failure.
89
+
90
+ ### 3. Handle the result
91
+
92
+ On `ok: true`, report the captured `id` and `path`.
93
+
94
+ On `ok: false`, handle the `error` code as follows:
95
+
96
+ - `invalid-args`: Report the helper's message and propose a corrected invocation.
97
+ - `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.
98
+ - `store-not-registered`: The named store is not in `kb.yaml`. Confirm the store name or register it.
99
+ - `readonly-store`: The store is marked readonly; captures are refused.
100
+ - `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`.
101
+ - `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.
102
+ - `schema-validation`: Report the `errors`, then supply the missing field and retry.
103
+ - `amend-not-found`: `--amend` named an id that does not match an event in the store. Confirm the id and store.
104
+ - `amend-parse`: The event to amend is not a valid event record. Inspect the file.
105
+
106
+ ## Completion
107
+
108
+ A written record at the reported path, validated as an event record. A fresh capture never overwrites an existing event; use `--amend` to rewrite one in place.