codeassembly-guidance 0.2.0 → 0.4.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 +291 -0
- package/CHANGELOG.md +82 -0
- package/README.md +20 -121
- package/content/_partials/README.md +19 -3
- package/content/_partials/diff-audit-checklist.md +1 -0
- package/content/_partials/guidance-change-since-capture.md +9 -0
- package/content/_partials/kb-standard-tags.md +7 -0
- package/content/codeassembly-content.yaml +8 -0
- package/content/collections/recommended.md +1 -1
- package/content/guidance/README.md +1 -1
- package/content/guidance/rulebooks/cli-conventions.md +16 -2
- package/content/guidance/rulebooks/codeassembly-content-specification.md +19 -2
- package/content/guidance/rulebooks/commit-conventions.md +3 -2
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +6 -2
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +28 -1
- package/content/guidance/shared/AGENTS.md +31 -4
- package/content/scripts/check-prose.mjs +38 -38
- package/content/scripts/describe-change.mjs +69 -69
- package/content/scripts/manage-jira-ticket.mjs +73 -73
- package/content/scripts/select-lede-exemplars.mjs +53 -53
- package/content/scripts/validate-preferences.mjs +1 -1
- package/content/skills/_data/action-items.md +2 -0
- package/content/skills/_data/artifact-conventions.md +24 -3
- package/content/skills/_data/complexity-classification.md +1 -1
- package/content/skills/_data/design-priorities.md +12 -1
- package/content/skills/_data/spike-conventions.md +21 -6
- package/content/skills/_data/title-templates.md +3 -1
- package/content/skills/_partials/apply-guidance-edits.md +5 -0
- package/content/skills/_partials/cluster-feedback-events.md +21 -0
- package/content/skills/_partials/commit-title-rendering.md +1 -1
- package/content/skills/_partials/next-steps-after-plan.md +1 -1
- package/content/skills/_partials/option-format.md +2 -2
- package/content/skills/_partials/plan-template.md +4 -2
- package/content/skills/_partials/ticket-and-plan-completeness.md +1 -1
- package/content/skills/_partials/ticket-composition.md +40 -0
- package/content/skills/_partials/ticket-skeleton.md +15 -1
- package/content/skills/align-ticket-with-implementation/SKILL.md +1 -5
- package/content/skills/assess-code-health/SKILL.md +127 -0
- package/content/skills/assess-code-health/assess-code-health.mjs +77 -0
- package/content/skills/assess-usability/SKILL.md +3 -1
- package/content/skills/capture-event/SKILL.md +2 -0
- package/content/skills/capture-event/capture-event.mjs +32 -32
- package/content/skills/capture-feedback/SKILL.md +1 -1
- package/content/skills/collaborate/SKILL.md +2 -2
- package/content/skills/create-bitbucket-pr/SKILL.md +2 -1
- package/content/skills/create-commit/SKILL.md +1 -1
- package/content/skills/create-gh-pr/SKILL.md +4 -1
- package/content/skills/create-pr/SKILL.md +2 -1
- package/content/skills/create-ticket/SKILL.md +3 -7
- package/content/skills/curate-feedback/SKILL.md +102 -0
- package/content/skills/curate-feedback/curate-feedback.mjs +211 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +94 -94
- package/content/skills/design-and-plan/SKILL.md +5 -9
- package/content/skills/implement-plan/SKILL.md +2 -2
- package/content/skills/index-prototypes/SKILL.md +1 -1
- package/content/skills/kb-add/SKILL.md +2 -0
- package/content/skills/kb-add/kb-add.mjs +53 -53
- package/content/skills/kb-curate/kb-curate.mjs +64 -64
- package/content/skills/kb-edit/SKILL.md +2 -0
- package/content/skills/kb-edit/kb-edit.mjs +59 -59
- package/content/skills/kb-retrieve/kb-retrieve.mjs +75 -75
- package/content/skills/kb-retrieve-events/SKILL.md +19 -10
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +75 -75
- package/content/skills/kb-update-events/SKILL.md +9 -6
- package/content/skills/kb-update-events/kb-update-events.mjs +86 -85
- package/content/skills/lesson-clusters/lesson-clusters.mjs +209 -0
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +75 -75
- package/content/skills/plan/SKILL.md +1 -1
- package/content/skills/refine-guidance/SKILL.md +97 -0
- package/content/skills/review-branch/SKILL.md +350 -1
- package/content/skills/revise-prose/revise-prose.mjs +103 -103
- package/content/skills/save-artifact/SKILL.md +1 -1
- package/content/skills/streamline-guidance/SKILL.md +10 -15
- package/content/skills/streamline-guidance/streamline-guidance.mjs +74 -74
- package/content/skills/summarize-change/SKILL.md +1 -1
- package/content/skills/testing-conventions/SKILL.md +7 -1
- package/content/skills/triage-feedback/SKILL.md +135 -0
- package/content/skills/triage-feedback/triage-feedback.mjs +70 -0
- package/content/skills/triage-spike-findings/SKILL.md +6 -6
- package/content/skills/triage-spike-findings/triage-spike-findings.mjs +30 -28
- package/content/skills/update-project-guidance/SKILL.md +10 -10
- package/content/subagents/code-health-assessor.md +98 -0
- package/content/subagents/feedback-coverage-judge.md +95 -0
- package/content/subagents/feedback-triage-challenger.md +86 -0
- package/content/subagents/lesson-clusterer.md +68 -0
- package/package.json +13 -13
- package/schemas/preferences.v1.json +22 -6
- package/schemas/work-types.v1.json +1 -1
- package/content/_partials/code-descriptions.md +0 -4
- package/content/_partials/code-style.md +0 -7
- package/content/_partials/live-repo-writes.md +0 -13
- package/content/_partials/reduced-object-relative.md +0 -28
- package/content/_partials/test-structure-audit-checklist.md +0 -7
- package/content/skills/_partials/acceptance-criteria-scaffold.md +0 -15
- package/content/skills/_partials/next-steps-after-review.md +0 -350
- package/content/skills/_partials/ticket-concision.md +0 -18
- package/content/skills/_partials/ticket-placement.md +0 -14
- package/content/skills/_partials/ticket-skeleton-tiers.md +0 -6
|
@@ -68,7 +68,7 @@ Invoke the `{skill:assess-ticket}` skill with the resolved ticket source and mod
|
|
|
68
68
|
|
|
69
69
|
2. **Evaluate the ticket on its merits**: Apply the criteria in [ticket evaluation](../_data/ticket-evaluation.md). When evaluation reveals a divergence from the ticket as written, recommend a disposition, build the design on it, and present the divergence at the ticket checkpoint; raise it earlier only when the design cannot proceed without the answer. Divergence includes scope that should grow: By default, fold work that the problem requires into this change rather than into a follow-up (see [scope-and-deferral](../_data/scope-and-deferral.md)).
|
|
70
70
|
|
|
71
|
-
3. **Form the questions that the design turns on, and decide what the gate lets you decide.** The questions cover purpose and motivation, constraints and scope boundaries, and success criteria and edge cases. Answer each from the codebase, the ticket, and the [option format](#option-format) gate when you can, and record the answer as a decision taken, with its reason. Defer the asks that survive the gate to the ticket checkpoint in Phase 3; ask earlier only when the design cannot proceed without the answer, and prefer multiple choice when you do. Treat the declared stage as the premise of every security, availability, and infrastructure question, per [project stage](../_data/project-stage.md). Ask for each undeclared stage value: in this step when the design has such a question, since the answer decides it, and otherwise at the ticket checkpoint. The ticket's `## Context` states each premise that decided such a question, and the plan includes a task that declares each answered value.
|
|
71
|
+
3. **Form the questions that the design turns on, and decide what the gate lets you decide.** The questions cover purpose and motivation, constraints and scope boundaries, and success criteria and edge cases. Answer each from the codebase, the ticket, and the [option format](#option-format) gate when you can, and record the answer as a decision taken, with its reason. Defer the asks that survive the gate to the ticket checkpoint in Phase 3; ask earlier only when the design cannot proceed without the answer, and prefer multiple choice when you do. Treat the declared stage as the premise of every security, availability, and infrastructure question, per [project stage](../_data/project-stage.md). Treat a step that a person must run on each machine as a defect of the design, per [who applies the change](../_data/design-priorities.md#who-applies-the-change): Prefer a design that the agent applies and verifies itself, and when the step stays, the ticket's `## Proposed solution` names the rung of that ladder that shapes it. Ask for each undeclared stage value: in this step when the design has such a question, since the answer decides it, and otherwise at the ticket checkpoint. The ticket's `## Context` states each premise that decided such a question, and the plan includes a task that declares each answered value.
|
|
72
72
|
- When asking option-style questions, follow [option format](#option-format). (Reinforces the rule in `AGENTS.md`: intentional redundancy.)
|
|
73
73
|
|
|
74
74
|
**Important:** Do not use `{tool:AskUserQuestion}` or any interactive selector (pop-up, arrow-key, structured-choice) for multiple-choice questions. Ask the question as plain text in the message body, with options as a numbered list.
|
|
@@ -77,7 +77,7 @@ Invoke the `{skill:assess-ticket}` skill with the resolved ticket source and mod
|
|
|
77
77
|
|
|
78
78
|
### Phase 3: Converge on a design and refine the ticket
|
|
79
79
|
|
|
80
|
-
1. **Choose the approach.** When the solution is obvious, build on it; don't manufacture alternatives for the sake of it. When it is not obvious, weigh 2-3 approaches, ranked per [design priorities](../_data/design-priorities.md), and apply the gate: A fork whose two strongest options are both ■■□ is presented at the checkpoint below with its trade-offs; otherwise the draft records the choice as "X, not Y" with its reason.
|
|
80
|
+
1. **Choose the approach.** When the solution is obvious, build on it; don't manufacture alternatives for the sake of it. When it is not obvious, weigh 2-3 approaches, ranked per [design priorities](../_data/design-priorities.md), in which a design that needs a person to act on each machine ranks below one that the agent applies itself, and apply the gate: A fork whose two strongest options are both ■■□ is presented at the checkpoint below with its trade-offs; otherwise the draft records the choice as "X, not Y" with its reason.
|
|
81
81
|
- When asking option-style questions, follow [option format](#option-format). (Reinforces the rule in `AGENTS.md`: intentional redundancy.)
|
|
82
82
|
|
|
83
83
|
2. **Draft the ticket on the recommended approach, provisionally.** The design is the draft ticket: Its `## Proposed solution` states the design, scaled to complexity, and a fork that survived the gate is written on its recommended branch until the checkpoint settles it.
|
|
@@ -94,18 +94,14 @@ When the ticket needs work, produce or update it to state the proposed approach:
|
|
|
94
94
|
<!-- include: ../_partials/ticket-skeleton.md / -->
|
|
95
95
|
```
|
|
96
96
|
|
|
97
|
-
<!-- include: ../_partials/ticket-
|
|
98
|
-
|
|
99
|
-
<!-- include: ../_partials/ticket-concision.md / -->
|
|
100
|
-
|
|
101
|
-
<!-- include: ../../_partials/prose-line-breaks.md / -->
|
|
102
|
-
|
|
103
|
-
<!-- include: ../_partials/ticket-placement.md / -->
|
|
97
|
+
<!-- include: ../_partials/ticket-composition.md / -->
|
|
104
98
|
|
|
105
99
|
Here, _the implementation_ is the plan artifact (Phase 4): Mechanism that the ticket omits is recorded there, not dropped.
|
|
106
100
|
|
|
107
101
|
<!-- include: ../_partials/ticket-criteria-conventions.md / -->
|
|
108
102
|
|
|
103
|
+
<!-- include: ../../_partials/prose-line-breaks.md / -->
|
|
104
|
+
|
|
109
105
|
**Present the ticket as the first checkpoint**, in one turn: the draft ticket, the decisions taken so far with their reasons, and the forks that survived the gate as option-style questions. Revise until approved. Approval of the ticket is approval of the design.
|
|
110
106
|
|
|
111
107
|
**When the checkpoint splits the ticket**, the session continues with one piece: With two pieces, it plans the originating ticket, which keeps the first piece; with an umbrella, it plans the first child, whose work belongs in that child's own worktree. Phase 5 then ends with the launch prompts that [Splitting the ticket](#splitting-the-ticket) defines, with each ticket's entry point chosen by that section's **Report.** rule, and the planned piece's prompt names its saved plan. With two pieces, the next-steps menu stays for the originating ticket, and that ticket's prompt heading adds that this session continues with it at the menu. With an umbrella, the launch prompts replace the `Next action` menu, so that nothing offers to implement a child in the current worktree.
|
|
@@ -52,13 +52,13 @@ The plan artifact is read-only. It is a record of what was decided at plan time,
|
|
|
52
52
|
|
|
53
53
|
Then check the branch per [branch currency](../_data/branch-currency.md), passing the paths in the plan's **Files:** lists. Do not start the first task while a question about the gap is unanswered.
|
|
54
54
|
|
|
55
|
-
5. **Execute the tasks in plan order.** Each task is done when its own acceptance criteria are met, not when its files have been touched. Task order encodes dependencies; do not reorder for convenience. Audit the comments that you write along the way per [Comment discipline](#comment-discipline).
|
|
55
|
+
5. **Execute the tasks in plan order.** Each task is done when its own acceptance criteria are met, not when its files have been touched. Task order encodes dependencies; do not reorder for convenience. Audit the comments that you write along the way per [Comment discipline](#comment-discipline), and the guidance and documentation that you write per the "Documentation placement" section of the shared agent instructions.
|
|
56
56
|
|
|
57
57
|
Raise material divergence to the user before proceeding, rather than departing from the plan silently. **Material** means the plan's approach no longer fits what the code turns out to be: A named file or symbol does not exist, a task's premise is false, or meeting the acceptance criteria requires an approach that the plan did not consider. Adapting details within the plan's approach (a different helper name, an extra test case, a step that turns out unnecessary because the code already does it) is ordinary implementation; continue and note it in the closing summary.
|
|
58
58
|
|
|
59
59
|
A task step or a verification check that writes to shared state from the branch is material divergence, even when the plan directs it: Do not run it; report the conflict, citing {rulebook:shared-data-conventions}.
|
|
60
60
|
|
|
61
|
-
A step that names the developer as its actor is yours to carry out, unless the task has a `**Residue:**` line: Perform every part that you can, and raise the residue as the one ask that it states. Such a step is not material divergence, and it is never handed back as a step for the developer to run.
|
|
61
|
+
A step that names the developer as its actor is yours to carry out, unless the task has a `**Residue:**` line: Perform every part that you can, and raise the residue as the one ask that it states. Such a step is not material divergence, and it is never handed back as a step for the developer to run. The records of a step, such as a log entry or a ticket comment, stay yours even when the step has a residue line.
|
|
62
62
|
|
|
63
63
|
Commit each task's work as its own commit with the `{skill:create-commit}` skill. Everything the closing menu offers reads committed history, so work left uncommitted is work that the next step cannot see.
|
|
64
64
|
|
|
@@ -78,7 +78,7 @@ Then, for each prototype:
|
|
|
78
78
|
|
|
79
79
|
Stop the server once every prototype is captured.
|
|
80
80
|
|
|
81
|
-
The Playwright MCP attaches to the worktree's debug browser
|
|
81
|
+
The Playwright MCP attaches to the worktree's debug browser, and a call that reports a refused connection means that the browser is not running. Run `thor-chrome` from the worktree; the next call then reaches the browser without restarting the MCP. When `thor-chrome` refuses the launch with `session-unavailable`, as it can in the agent sandbox, ask the developer to run `thor-chrome` from the worktree in a terminal in the GUI login session, and wait for it rather than publishing an index without screenshots.
|
|
82
82
|
|
|
83
83
|
### 4. Register each prototype
|
|
84
84
|
|
|
@@ -31,6 +31,8 @@ A value-bearing flag accepts both `--diataxis howto` and `--diataxis=howto`. The
|
|
|
31
31
|
|
|
32
32
|
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
33
|
|
|
34
|
+
<!-- include: ../../_partials/kb-standard-tags.md / -->
|
|
35
|
+
|
|
34
36
|
## Runtime dependencies
|
|
35
37
|
|
|
36
38
|
- **`node` ≥ 24**: The bundled helper inherits the Node version floor of `@williamthorsen/kb`.
|