codeassembly-guidance 0.2.0 → 0.3.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 +227 -0
- package/CHANGELOG.md +59 -0
- package/README.md +37 -121
- package/content/_partials/README.md +19 -3
- package/content/_partials/diff-audit-checklist.md +1 -0
- package/content/_partials/kb-standard-tags.md +7 -0
- package/content/codeassembly-content.yaml +6 -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/validate-preferences.mjs +1 -1
- package/content/skills/_data/action-items.md +2 -0
- package/content/skills/_data/artifact-conventions.md +18 -2
- 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/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-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/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-edit/SKILL.md +2 -0
- package/content/skills/kb-edit/kb-edit.mjs +24 -24
- 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/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 +85 -85
- 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 +73 -73
- 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 +150 -0
- package/content/skills/triage-feedback/triage-feedback.mjs +70 -0
- package/content/skills/triage-spike-findings/SKILL.md +5 -5
- 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-triage-challenger.md +81 -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
|
@@ -9,7 +9,7 @@ supported-harnesses: [claude]
|
|
|
9
9
|
|
|
10
10
|
Find where a product would lead its users to conclude that it is broken or unfinished. Each lens is a {subagent:usability-assessor} that walks its use cases in a browser or, for a command-line product, in a shell, without seeing any other lens's report. You prepare the targets, write the brief that every lens reads, dispatch the lenses one at a time, and merge their reports into one findings artifact.
|
|
11
11
|
|
|
12
|
-
The skill
|
|
12
|
+
The skill's one remote write is the [closing post](../_data/spike-conventions.md#closing-post) on the ticket, made on the developer's consent: It does not create a ticket or edit an issue. The findings artifact is the input of `triage-spike-findings`, which decides what becomes a ticket.
|
|
13
13
|
|
|
14
14
|
## Inputs
|
|
15
15
|
|
|
@@ -94,3 +94,5 @@ Then publish it as an artifact page: Load the artifact-design skill, and render
|
|
|
94
94
|
### 7. Report
|
|
95
95
|
|
|
96
96
|
Give the developer the findings artifact's path, the page's URL, and one line of counts: use cases exercised, findings by effect, and ideas. Name `triage-spike-findings` as the next step, with the findings artifact's path as its input.
|
|
97
|
+
|
|
98
|
+
In the same response's action-items block, offer the closing post on the ticket, whose contents, consent, and duplicate check are stated in [Closing post](../_data/spike-conventions.md#closing-post). For an assessment, the answers that the post gives are the counts and the top findings by effect, and its groupings are the proposed groupings of step 5.
|
|
@@ -55,6 +55,8 @@ A caller whose destination is a configured role rather than a per-lesson judgmen
|
|
|
55
55
|
|
|
56
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
57
|
|
|
58
|
+
<!-- include: ../../_partials/kb-standard-tags.md / -->
|
|
59
|
+
|
|
58
60
|
## Runtime dependencies
|
|
59
61
|
|
|
60
62
|
- **`node` ≥ 24**: The bundled helper inherits the Node version floor of `@williamthorsen/kb`.
|
|
@@ -8,7 +8,7 @@ user-invocable: true
|
|
|
8
8
|
|
|
9
9
|
Record feedback on the agent's behavior as evidence for a future guidance refinement, applying the immediate fix when there is something concrete to change. The user describes a correction or a desired behavior, the agent applies it when applicable, and the agent appends a generalized record that a later recall-driven pass reads to refine guidance.
|
|
10
10
|
|
|
11
|
-
The actual guidance refinement is **deferred**: This skill captures the candidate, it does not edit the skill, subagent, rulebook, general guidance, or helper. A later pass refines the guidance in bulk, recalling the accumulated `feedback` records together, so a single data point never over-fits a rule.
|
|
11
|
+
The actual guidance refinement is **deferred**: This skill captures the candidate, it does not edit the skill, subagent, rulebook, general guidance, or helper. A later pass refines the guidance in bulk, recalling the accumulated `feedback` records together, so a single data point never over-fits a rule: {skill?:triage-feedback} clusters the records by lesson and surfaces the lessons worth a guidance change, and {skill?:refine-guidance} makes the change.
|
|
12
12
|
|
|
13
13
|
**Announce at start:** "Using capture-feedback to apply this and record it for guidance refinement."
|
|
14
14
|
|
|
@@ -13,7 +13,7 @@ This skill is invoked by a directive in the harness's global guidance during int
|
|
|
13
13
|
## Principles
|
|
14
14
|
|
|
15
15
|
- Act as a conscientious collaborator, not a mindless code generator.
|
|
16
|
-
- **Never make changes unless asked.** If the developer asks a question, answer it. If they comment on your work, address the comment. They are engaging in discussion.
|
|
16
|
+
- **Never make changes unless asked.** If the developer asks a question, answer it with an answer, not a procedure for them to run, and run any check that the answer needs. If they comment on your work, address the comment. They are engaging in discussion.
|
|
17
17
|
- Don't let refactoring grow beyond the task; recommend the scope call, build on it, and raise it at the checkpoint.
|
|
18
18
|
- Ask for guidance on naming and approach when the choice turns on the developer's preference; when a convention or the merits already settle it, state the decision with its reason and proceed.
|
|
19
19
|
- Proceed provisionally: Decide what the gate lets you decide, record it, and collect the surviving asks into one review at the checkpoint.
|
|
@@ -43,7 +43,7 @@ If the right answer depends on context that you don't yet have, get it before we
|
|
|
43
43
|
|
|
44
44
|
## Asking questions
|
|
45
45
|
|
|
46
|
-
Not every response needs to end with a question. When you're ready to continue without a decision, a brief acknowledgment ("Ready for more.", "Got it.") is often better than inventing a question to fill the slot. A question that you could answer from evidence that you already hold is the same failure in a more diligent form: Answer it, give the reason in a clause, and carry on.
|
|
46
|
+
Not every response needs to end with a question. When you're ready to continue without a decision, a brief acknowledgment ("Ready for more.", "Got it.") is often better than inventing a question to fill the slot. A question that you could answer from evidence that you already hold is the same failure in a more diligent form: Answer it, give the reason in a clause, and carry on. When the developer signals overload, stop asking until they ask for something, per the "Prompt formatting" section of the collaboration preferences.
|
|
47
47
|
|
|
48
48
|
When you do ask, prefer forms that the user can answer unambiguously:
|
|
49
49
|
|
|
@@ -21,6 +21,7 @@ This skill receives the following inputs from the orchestrator:
|
|
|
21
21
|
| `ticket_id` | string | Ticket ID for artifact path resolution |
|
|
22
22
|
| `project_slug` | string | Project slug for artifact path resolution |
|
|
23
23
|
| `artifact_base_dir` | string | Base directory for artifact storage |
|
|
24
|
+
| `initial_state` | string | `draft` to open the pull request as a draft, `ready` to open it ready for review |
|
|
24
25
|
|
|
25
26
|
## Process
|
|
26
27
|
|
|
@@ -32,7 +33,7 @@ Call `action: "create"` on the tool named in [Bitbucket pull-request access](../
|
|
|
32
33
|
- **Description**: Use `body` as provided.
|
|
33
34
|
- **Source branch**: Use the current branch, `git rev-parse --abbrev-ref HEAD`. The action requires it, and the delegate interface does not have a head-branch input.
|
|
34
35
|
- **Destination branch**: Use `base_branch`.
|
|
35
|
-
- **Draft/WIP**:
|
|
36
|
+
- **Draft/WIP**: When `initial_state` is `draft`, create as draft if the platform supports it. When it is `ready`, create an open pull request.
|
|
36
37
|
|
|
37
38
|
### 2. Report every label as skipped
|
|
38
39
|
|
|
@@ -46,7 +46,7 @@ Record each unit as it is finished. Several single-concern commits read better t
|
|
|
46
46
|
git commit --file "$body_path"
|
|
47
47
|
```
|
|
48
48
|
|
|
49
|
-
7. **Report the result**: the new commit's short SHA and title, or, when step 2 stopped or the commit failed, why nothing was committed.
|
|
49
|
+
7. **Report the result**: the new commit's short SHA and title, or, when step 2 stopped or the commit failed, why nothing was committed. Do not comment on the title's format. The template sets which tokens the title contains, a ticket reference among them, so neither a token that the title omits nor a difference from earlier commits is a finding.
|
|
50
50
|
|
|
51
51
|
## Work type test
|
|
52
52
|
|
|
@@ -21,6 +21,7 @@ This skill receives the following inputs from the orchestrator:
|
|
|
21
21
|
| `ticket_id` | string | Ticket ID for artifact path resolution |
|
|
22
22
|
| `project_slug` | string | Project slug for artifact path resolution |
|
|
23
23
|
| `artifact_base_dir` | string | Base directory for artifact storage |
|
|
24
|
+
| `initial_state` | string | `draft` to open the pull request as a draft, `ready` to open it ready for review |
|
|
24
25
|
|
|
25
26
|
## Process
|
|
26
27
|
|
|
@@ -41,11 +42,13 @@ gh pr create \
|
|
|
41
42
|
--title "{title}" \
|
|
42
43
|
--body-file "$body_path" \
|
|
43
44
|
--base "{base_branch}" \
|
|
44
|
-
|
|
45
|
+
{draft_flag} \
|
|
45
46
|
--assignee "@me" \
|
|
46
47
|
{label_flags}
|
|
47
48
|
```
|
|
48
49
|
|
|
50
|
+
`{draft_flag}` is `--draft` when `initial_state` is `draft`, and is left out of the call entirely when it is `ready`. Write it into the call as literal text, as the label flags are.
|
|
51
|
+
|
|
49
52
|
`--assignee "@me"` assigns the pull request to the authenticated `gh` user, who is the developer creating it.
|
|
50
53
|
|
|
51
54
|
`gh pr create` prints the pull-request URL. Read it from the command's output and include it in step 5's artifact and the completion line; never capture it into a shell variable.
|
|
@@ -21,7 +21,7 @@ Both are passed to `summarize-change`, which records them as overrides beside th
|
|
|
21
21
|
|
|
22
22
|
### 1. Get session context
|
|
23
23
|
|
|
24
|
-
Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash. The bundle emits the session-context manifest JSON to stdout; extract `ticket_id`, `ticket_ref`, `project_slug`, `scm`, `default_branch`, `branch_name`, and `
|
|
24
|
+
Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash. The bundle emits the session-context manifest JSON to stdout; extract `ticket_id`, `ticket_ref`, `project_slug`, `scm`, `default_branch`, `branch_name`, `artifact_base_dir`, and `pr_initial_state` from it.
|
|
25
25
|
|
|
26
26
|
### 2. Check branch sync
|
|
27
27
|
|
|
@@ -134,6 +134,7 @@ Pass the following inputs to the selected delegate per the delegate interface:
|
|
|
134
134
|
| `ticket_id` | From session context |
|
|
135
135
|
| `project_slug` | From session context |
|
|
136
136
|
| `artifact_base_dir` | From session context |
|
|
137
|
+
| `initial_state` | `pr_initial_state` from session context: `draft` or `ready` |
|
|
137
138
|
|
|
138
139
|
### 11. Persist the PR URL
|
|
139
140
|
|
|
@@ -61,18 +61,14 @@ Create the ticket body describing WHAT needs to be done: problem, context, and a
|
|
|
61
61
|
|
|
62
62
|
**Spike mode.** If the ticket describes a spike, use the spike ticket template in [spike conventions](../_data/spike-conventions.md) in place of the skeleton above.
|
|
63
63
|
|
|
64
|
-
<!-- include: ../_partials/ticket-
|
|
65
|
-
|
|
66
|
-
<!-- include: ../_partials/ticket-concision.md / -->
|
|
67
|
-
|
|
68
|
-
<!-- include: ../../_partials/prose-line-breaks.md / -->
|
|
69
|
-
|
|
70
|
-
<!-- include: ../_partials/ticket-placement.md / -->
|
|
64
|
+
<!-- include: ../_partials/ticket-composition.md / -->
|
|
71
65
|
|
|
72
66
|
`create-ticket` does not produce a plan, so _the implementation_ is derived when the work is later planned; state the subject and outcomes, and leave mechanism for that step.
|
|
73
67
|
|
|
74
68
|
<!-- include: ../_partials/ticket-criteria-conventions.md / -->
|
|
75
69
|
|
|
70
|
+
<!-- include: ../../_partials/prose-line-breaks.md / -->
|
|
71
|
+
|
|
76
72
|
Also draft the ticket string, per [`title-voice.md`](../_data/title-voice.md), for use in step 6.
|
|
77
73
|
|
|
78
74
|
Then decide the ticket's scope and type, for use in steps 5 and 6. The type is the [work type](../_data/work-types.json) of the change that the ticket asks for: a ticket reporting a defect is `fix`, and one asking for a new capability is `feat`. Append `!` only when the proposed change breaks consumers and the type's `breakingPolicy` admits the marker. The scope is the workspace that the change belongs to, per [Scope values](../_data/title-templates.md#scope-values); a change spanning more than one takes `*`, which does not render or label any scope. The pull request that implements the ticket compares its derived type with the type label applied here.
|