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.
- package/.meta/changelog.json +563 -0
- package/CHANGELOG.md +134 -0
- package/LICENSE +7 -0
- package/README.md +165 -1
- package/content/_partials/README.md +192 -0
- package/content/_partials/code-descriptions.md +4 -0
- package/content/_partials/code-style.md +7 -0
- package/content/_partials/comment-discipline.md +89 -0
- package/content/_partials/concision.md +3 -0
- package/content/_partials/diff-audit-checklist.md +9 -0
- package/content/_partials/file-access.md +4 -0
- package/content/_partials/live-repo-writes.md +13 -0
- package/content/_partials/plain-speech-calibration.md +66 -0
- package/content/_partials/plain-speech.md +13 -0
- package/content/_partials/prose-line-breaks.md +3 -0
- package/content/_partials/record-marker.md +1 -0
- package/content/_partials/reduced-object-relative.md +28 -0
- package/content/_partials/shell-commands.md +3 -0
- package/content/_partials/target-file-set-resolution.md +22 -0
- package/content/_partials/technical-recommendations.md +5 -0
- package/content/_partials/test-structure-audit-checklist.md +7 -0
- package/content/_partials/ticket-assessment-baseline.md +12 -0
- package/content/_partials/ticket-assessment.md +202 -0
- package/content/_partials/work-type-choice.md +13 -0
- package/content/codeassembly-content.yaml +49 -0
- package/content/collections/all.md +11 -0
- package/content/collections/atlassian.md +16 -0
- package/content/collections/recommended.md +34 -0
- package/content/collections/triage.md +77 -0
- package/content/collections/williamthorsen.md +25 -0
- package/content/guidance/README.md +22 -0
- package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
- package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
- package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
- package/content/guidance/rulebooks/accessibility-conventions.md +20 -0
- package/content/guidance/rulebooks/codeassembly-content-specification.md +161 -0
- package/content/guidance/rulebooks/command-output-conventions.md +14 -0
- package/content/guidance/rulebooks/commit-conventions.md +72 -0
- package/content/guidance/rulebooks/generated-content-policy.md +10 -0
- package/content/guidance/rulebooks/live-worktree-policy.md +18 -0
- package/content/guidance/rulebooks/readme-conventions.md +74 -0
- package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
- package/content/guidance/rulebooks/shell-conventions.md +279 -0
- package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +58 -0
- package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
- package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
- package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
- package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
- package/content/guidance/shared/AGENTS.md +43 -0
- package/content/scripts/README.md +41 -0
- package/content/scripts/describe-change.mjs +165 -0
- package/content/scripts/get-ticket-id.sh +131 -0
- package/content/scripts/manage-jira-ticket.mjs +209 -0
- package/content/scripts/resolve-frontmatter.sh +540 -0
- package/content/scripts/resolve-review-run.mjs +12 -0
- package/content/scripts/select-lede-exemplars.mjs +208 -0
- package/content/skills/_data/action-items.md +83 -0
- package/content/skills/_data/artifact-conventions.md +969 -0
- package/content/skills/_data/bitbucket-pr-access.md +89 -0
- package/content/skills/_data/branch-format.md +34 -0
- package/content/skills/_data/change-record.md +163 -0
- package/content/skills/_data/complexity-classification.md +58 -0
- package/content/skills/_data/concision.md +23 -0
- package/content/skills/_data/deployed-file-provenance.md +46 -0
- package/content/skills/_data/design-priorities.md +76 -0
- package/content/skills/_data/gh-body-file.md +30 -0
- package/content/skills/_data/git-commands.md +39 -0
- package/content/skills/_data/naming-conventions.md +50 -0
- package/content/skills/_data/pr-resolution.md +25 -0
- package/content/skills/_data/pr-source-resolution.md +36 -0
- package/content/skills/_data/recommendation-gradient.md +90 -0
- package/content/skills/_data/scope-and-deferral.md +83 -0
- package/content/skills/_data/spike-conventions.md +89 -0
- package/content/skills/_data/ticket-evaluation.md +13 -0
- package/content/skills/_data/ticket-id-extraction.md +43 -0
- package/content/skills/_data/ticket-source-resolution.md +147 -0
- package/content/skills/_data/title-templates.md +624 -0
- package/content/skills/_data/title-voice.md +17 -0
- package/content/skills/_data/work-types.json +168 -0
- package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
- package/content/skills/_partials/action-items.md +22 -0
- package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
- package/content/skills/_partials/commit-title-rendering.md +14 -0
- package/content/skills/_partials/gh-body-file.md +22 -0
- package/content/skills/_partials/nested-list-indent.md +9 -0
- package/content/skills/_partials/next-steps-after-plan.md +99 -0
- package/content/skills/_partials/next-steps-after-review.md +350 -0
- package/content/skills/_partials/option-format.md +84 -0
- package/content/skills/_partials/plan-template.md +97 -0
- package/content/skills/_partials/split-launch-prompts.md +5 -0
- package/content/skills/_partials/split-ticket-compose.md +5 -0
- package/content/skills/_partials/split-ticket-create.md +3 -0
- package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
- package/content/skills/_partials/ticket-concision.md +18 -0
- package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
- package/content/skills/_partials/ticket-placement.md +14 -0
- package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
- package/content/skills/_partials/ticket-skeleton.md +13 -0
- package/content/skills/add-change-record/SKILL.md +136 -0
- package/content/skills/add-test-ids/SKILL.md +51 -0
- package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
- package/content/skills/anti-patterns/SKILL.md +57 -0
- package/content/skills/assess-ticket/SKILL.md +46 -0
- package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
- package/content/skills/brainstorming/SKILL.md +107 -0
- package/content/skills/capture-event/SKILL.md +108 -0
- package/content/skills/capture-event/capture-event.mjs +216 -0
- package/content/skills/capture-feedback/SKILL.md +71 -0
- package/content/skills/capture-lede-decision/SKILL.md +163 -0
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
- package/content/skills/classify-complexity/SKILL.md +92 -0
- package/content/skills/collaborate/SKILL.md +86 -0
- package/content/skills/condense-branch/SKILL.md +83 -0
- package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
- package/content/skills/create-commit/SKILL.md +65 -0
- package/content/skills/create-devlog/SKILL.md +108 -0
- package/content/skills/create-gh-pr/SKILL.md +106 -0
- package/content/skills/create-pr/SKILL.md +150 -0
- package/content/skills/create-ticket/SKILL.md +350 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +148 -0
- package/content/skills/design-and-plan/SKILL.md +194 -0
- package/content/skills/development-workflows/SKILL.md +41 -0
- package/content/skills/get-ticket-id/SKILL.md +67 -0
- package/content/skills/groom-backlog/SKILL.md +245 -0
- package/content/skills/groom-backlog/groom-backlog.mjs +106 -0
- package/content/skills/implement-plan/SKILL.md +164 -0
- package/content/skills/index-prototypes/SKILL.md +145 -0
- package/content/skills/index-prototypes/index-prototypes.mjs +328 -0
- package/content/skills/kb-add/SKILL.md +156 -0
- package/content/skills/kb-add/kb-add.mjs +216 -0
- package/content/skills/kb-curate/SKILL.md +117 -0
- package/content/skills/kb-curate/kb-curate.mjs +213 -0
- package/content/skills/kb-edit/SKILL.md +128 -0
- package/content/skills/kb-edit/kb-edit.mjs +219 -0
- package/content/skills/kb-retrieve/SKILL.md +100 -0
- package/content/skills/kb-retrieve/kb-retrieve.mjs +206 -0
- package/content/skills/kb-retrieve-events/SKILL.md +98 -0
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +206 -0
- package/content/skills/kb-update-events/SKILL.md +77 -0
- package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
- package/content/skills/merge-bb-pr/SKILL.md +136 -0
- package/content/skills/merge-gh-pr/SKILL.md +167 -0
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
- package/content/skills/merge-pr/SKILL.md +368 -0
- package/content/skills/migrate-feedback-memories/SKILL.md +136 -0
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
- package/content/skills/people-report/SKILL.md +208 -0
- package/content/skills/plan/SKILL.md +87 -0
- package/content/skills/prepare-prototype-brief/SKILL.md +126 -0
- package/content/skills/pull-from-backlog/SKILL.md +83 -0
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +208 -0
- package/content/skills/refine-plan/SKILL.md +259 -0
- package/content/skills/respond-to-review/SKILL.md +292 -0
- package/content/skills/review-bb-pr/SKILL.md +161 -0
- package/content/skills/review-branch/SKILL.md +301 -0
- package/content/skills/review-criteria/SKILL.md +108 -0
- package/content/skills/review-gh-pr/SKILL.md +155 -0
- package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
- package/content/skills/review-permissions/SKILL.md +39 -0
- package/content/skills/review-pr/SKILL.md +123 -0
- package/content/skills/revise-comments/SKILL.md +115 -0
- package/content/skills/revise-prose/SKILL.md +197 -0
- package/content/skills/revise-prose/revise-prose.mjs +229 -0
- package/content/skills/save-artifact/SKILL.md +69 -0
- package/content/skills/save-plan/SKILL.md +55 -0
- package/content/skills/software-engineering/SKILL.md +74 -0
- package/content/skills/streamline-guidance/SKILL.md +174 -0
- package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
- package/content/skills/summarize-change/SKILL.md +308 -0
- package/content/skills/summarize-chat/SKILL.md +100 -0
- package/content/skills/systematic-debugging/SKILL.md +308 -0
- package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
- package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
- package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
- package/content/skills/systematic-debugging/find-polluter.sh +68 -0
- package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
- package/content/skills/systematic-debugging/test-academic.md +16 -0
- package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
- package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
- package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
- package/content/skills/testing-conventions/SKILL.md +168 -0
- package/content/skills/testing-conventions/mistakes.md +1 -0
- package/content/skills/typescript-testing-conventions/SKILL.md +129 -0
- package/content/skills/update-jira-ticket/SKILL.md +245 -0
- package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
- package/content/skills/update-project-guidance/SKILL.md +300 -0
- package/content/skills/upgrade-dependencies/SKILL.md +139 -0
- package/content/skills/wrap-up/SKILL.md +431 -0
- package/content/subagents/_data/claude.yaml +19 -0
- package/content/subagents/_data/rovo.yaml +31 -0
- package/content/subagents/canary.md +11 -0
- package/content/subagents/entry-drafter.md +187 -0
- package/content/subagents/handoff-reviewer.md +75 -0
- package/content/subagents/plan-reviewer.md +184 -0
- package/content/subagents/plan-reviser.md +88 -0
- package/content/subagents/prose-reviser.md +130 -0
- package/content/subagents/ticket-assessor.md +139 -0
- package/package.json +70 -2
- package/schemas/preferences.v1.json +294 -0
- 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.
|