codeassembly-guidance 0.5.0 → 0.7.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 +491 -0
- package/CHANGELOG.md +118 -0
- package/README.md +33 -4
- package/content/_partials/finding-grades.md +4 -0
- package/content/_partials/kb-unsearched-private-stores.md +6 -0
- package/content/codeassembly-content.yaml +4 -0
- package/content/collections/recommended.md +5 -2
- package/content/guidance/_harnesses/rovo/AGENTS.md +0 -1
- package/content/guidance/rulebooks/accessibility-conventions.md +26 -6
- package/content/guidance/rulebooks/cli-conventions.md +17 -2
- package/content/guidance/rulebooks/codeassembly-content-specification.md +11 -11
- package/content/guidance/rulebooks/live-worktree-policy.md +2 -2
- package/content/guidance/rulebooks/machine-readable-output-conventions.md +85 -0
- package/content/guidance/rulebooks/ui-copy-conventions.md +2 -2
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +10 -10
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -1
- package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +7 -3
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +3 -1
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +5 -5
- package/content/guidance/shared/AGENTS.md +1 -1
- package/content/scripts/check-prose.mjs +1 -1
- package/content/scripts/describe-change.mjs +88 -88
- package/content/scripts/manage-jira-ticket.mjs +113 -113
- package/content/scripts/select-lede-exemplars.mjs +85 -85
- package/content/scripts/validate-preferences.mjs +38 -38
- package/content/skills/_data/action-items.md +2 -2
- package/content/skills/_data/artifact-conventions.md +20 -10
- package/content/skills/_data/concision.md +1 -1
- package/content/skills/_data/entry-points.md +37 -0
- package/content/skills/_data/project-stage.md +9 -5
- package/content/skills/_data/recommendation-gradient.md +6 -6
- package/content/skills/_data/spike-conventions.md +20 -7
- package/content/skills/_data/ticket-source-resolution.md +21 -4
- package/content/skills/_data/title-templates.md +4 -4
- package/content/skills/_partials/commit-title-rendering.md +2 -1
- package/content/skills/_partials/implementation-order-list.md +27 -0
- package/content/skills/_partials/next-steps-after-plan.md +6 -5
- package/content/skills/_partials/option-format.md +8 -8
- package/content/skills/_partials/plan-template.md +5 -1
- package/content/skills/_partials/resolve-plan-and-ticket.md +22 -0
- package/content/skills/_partials/split-launch-prompts.md +2 -2
- package/content/skills/_partials/ticket-criteria-conventions.md +2 -0
- package/content/skills/align-ticket-with-implementation/SKILL.md +1 -1
- package/content/skills/analyze-performance/SKILL.md +102 -0
- package/content/skills/analyze-performance/analyze-performance.mjs +70 -0
- package/content/skills/assess-code-health/SKILL.md +16 -14
- package/content/skills/assess-code-health/assess-code-health.mjs +29 -28
- package/content/skills/assess-usability/SKILL.md +5 -3
- package/content/skills/capture-event/SKILL.md +20 -11
- package/content/skills/capture-event/capture-event.mjs +122 -122
- package/content/skills/capture-feedback/SKILL.md +2 -1
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +97 -97
- package/content/skills/convert-agent-prompt/SKILL.md +60 -0
- package/content/skills/create-commit/SKILL.md +10 -5
- package/content/skills/create-pr/SKILL.md +11 -11
- package/content/skills/create-ticket/SKILL.md +1 -0
- package/content/skills/create-ticket/resolve-ticket-target.mjs +92 -92
- package/content/skills/curate-feedback/curate-feedback.mjs +82 -82
- package/content/skills/derive-session-context/derive-session-context.mjs +107 -107
- package/content/skills/design-and-plan/SKILL.md +6 -4
- package/content/skills/implement-plan/SKILL.md +4 -29
- package/content/skills/implementation-order/implementation-order.mjs +67 -0
- package/content/skills/index-prototypes/SKILL.md +36 -17
- package/content/skills/index-prototypes/index-prototypes.mjs +14 -14
- package/content/skills/investigate-spike/SKILL.md +48 -0
- package/content/skills/kb-add/SKILL.md +12 -3
- package/content/skills/kb-add/kb-add.mjs +88 -88
- package/content/skills/kb-curate/kb-curate.mjs +88 -88
- package/content/skills/kb-edit/kb-edit.mjs +90 -90
- package/content/skills/kb-retrieve/SKILL.md +8 -3
- package/content/skills/kb-retrieve/kb-retrieve.mjs +104 -104
- package/content/skills/kb-retrieve-events/SKILL.md +8 -3
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +113 -113
- package/content/skills/kb-update-events/kb-update-events.mjs +92 -92
- package/content/skills/lesson-clusters/lesson-clusters.mjs +102 -102
- package/content/skills/list-implementation-order/SKILL.md +23 -0
- package/content/skills/merge-bb-pr/SKILL.md +31 -8
- package/content/skills/merge-gh-pr/SKILL.md +25 -12
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +13 -8
- package/content/skills/merge-pr/SKILL.md +55 -20
- package/content/skills/migrate-feedback-memories/SKILL.md +1 -0
- package/content/skills/plan/SKILL.md +3 -1
- package/content/skills/prepare-prototype-brief/SKILL.md +20 -14
- package/content/skills/refine-plan/SKILL.md +9 -4
- package/content/skills/refine-prototype/SKILL.md +5 -5
- package/content/skills/review-branch/SKILL.md +8 -8
- package/content/skills/review-criteria/SKILL.md +4 -4
- package/content/skills/review-gh-pr/SKILL.md +1 -1
- package/content/skills/revise-prose/SKILL.md +9 -8
- package/content/skills/revise-prose/revise-prose.mjs +111 -111
- package/content/skills/save-plan/SKILL.md +2 -0
- package/content/skills/start-ticket/SKILL.md +27 -0
- package/content/skills/streamline-guidance/streamline-guidance.mjs +76 -76
- package/content/skills/summarize-change/SKILL.md +27 -9
- package/content/skills/testing-conventions/SKILL.md +14 -3
- package/content/skills/triage-feedback/SKILL.md +4 -0
- package/content/skills/triage-spike-findings/SKILL.md +36 -12
- package/content/skills/typescript-testing-conventions/SKILL.md +40 -0
- package/content/skills/wrap-up/SKILL.md +4 -0
- package/content/subagents/_data/claude.yaml +3 -0
- package/content/subagents/code-health-assessor.md +4 -4
- package/content/subagents/disposition-challenger.md +3 -4
- package/content/subagents/entry-drafter.md +2 -2
- package/content/subagents/handoff-reviewer.md +1 -1
- package/content/subagents/prototype-builder.md +69 -0
- package/content/subagents/usability-assessor.md +1 -1
- package/package.json +11 -10
- package/schemas/preferences.v1.json +74 -8
- package/schemas/work-types.v1.json +1 -1
- package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +0 -4
|
@@ -64,11 +64,11 @@ Invoke the `{skill:assess-ticket}` skill with the resolved ticket source and mod
|
|
|
64
64
|
|
|
65
65
|
### Phase 2: Understand the task
|
|
66
66
|
|
|
67
|
-
1. **Explore project context:** Check relevant files, docs, recent commits to understand the affected area of the codebase. Read the project's declared stage from the manifest's `project_maturity`, `project_sensitivity`, and `project_audience` fields, which `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` emits.
|
|
67
|
+
1. **Explore project context:** Check relevant files, docs, recent commits to understand the affected area of the codebase. Read the project's declared stage from the manifest's `project_maturity`, `project_sensitivity`, and `project_audience` fields, and the stages that its subdirectories declare from the `project_stages` field, which `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` emits.
|
|
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
|
|
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 stage that governs the work's paths as the premise of every security, availability, infrastructure, and verification 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), 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.
|
|
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. When the design places a control or shapes an interface, start from the established model that {rulebook:accessibility-conventions} has the agent name, and record in `## Proposed solution` the reason for any departure from it.
|
|
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.
|
|
@@ -104,7 +104,7 @@ Here, _the implementation_ is the plan artifact (Phase 4): Mechanism that the ti
|
|
|
104
104
|
|
|
105
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.
|
|
106
106
|
|
|
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
|
|
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 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.
|
|
108
108
|
|
|
109
109
|
### Phase 4: Generate implementation plan
|
|
110
110
|
|
|
@@ -191,3 +191,5 @@ Follow the options, output format, and recommendation rules in [next-steps optio
|
|
|
191
191
|
<!-- include: ../_partials/next-steps-after-plan.md / -->
|
|
192
192
|
|
|
193
193
|
<!-- include: ../_partials/option-format.md / -->
|
|
194
|
+
|
|
195
|
+
<!-- include: ../_partials/implementation-order-list.md / -->
|
|
@@ -15,10 +15,6 @@ Implement the work described by a feature plan. This skill is the canonical path
|
|
|
15
15
|
| `--plan=<path>` | The plan artifact to implement. | Auto-resolved (see below) |
|
|
16
16
|
| `--ticket=<source>` | The ticket that the plan serves. Resolved per [ticket source resolution](../_data/ticket-source-resolution.md). | Auto-resolved (see below) |
|
|
17
17
|
|
|
18
|
-
## Scope
|
|
19
|
-
|
|
20
|
-
This skill implements a feature plan, the `## Tasks` / `## Verification` shape defined by the plan template. A spike plan has `## Investigation steps` and a `## Deliverable` instead (see [spike conventions](../_data/spike-conventions.md)): It is carried out to produce findings rather than implemented to produce a diff, and none of the steps below read its shape. Step 4 rejects one.
|
|
21
|
-
|
|
22
18
|
## The contract
|
|
23
19
|
|
|
24
20
|
The ticket's acceptance criteria are the contract; the plan is the mechanism by which they are met. When the plan and the facts found during implementation disagree, the acceptance criteria decide: A plan step that no longer serves them is the one to abandon.
|
|
@@ -27,30 +23,7 @@ The plan artifact is read-only. It is a record of what was decided at plan time,
|
|
|
27
23
|
|
|
28
24
|
## Process
|
|
29
25
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
2. **Resolve the plan**: Stop at the first source that yields one:
|
|
33
|
-
- **Explicit `--plan=<path>`**: Read it.
|
|
34
|
-
- **Already in context**: This session produced or read the plan. Use it as-is; do not re-read the file.
|
|
35
|
-
- **Newest plan for the ticket**: The newest of `*_plan.md` and `*_plan-v*.md` under `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/` (run subdirectories included), by the greatest `YYYYMMDD-HHMMSSZ` filename prefix. Both forms have that prefix, so they sort chronologically together and the lexicographically greatest is the newest across the two. Because `refine-plan` writes its revision as `_plan-v2.md` under a later prefix than the plan that it revises, matching both forms lets a refined plan take precedence over the original that it supersedes. Do not widen to `*_plan*.md`, which also matches the `_plan-review.md` artifact written beside the revision.
|
|
36
|
-
- **Ask**: The sources above do not resolve a plan. Ask the user for a path rather than implementing from the ticket alone: A caller who invoked this skill has a plan in mind.
|
|
37
|
-
|
|
38
|
-
Announce the resolved path and its timestamp before executing anything. Several plans can exist for one ticket, and the newest is not always the intended one: This announcement is how the user catches a superseded plan while the choice can still change without cost. It is not ceremony, and it is not skippable when the resolution was unambiguous.
|
|
39
|
-
|
|
40
|
-
3. **Resolve the ticket**: Stop at the first source that yields one:
|
|
41
|
-
- **Explicit `--ticket=<source>`**: Resolve per [ticket source resolution](../_data/ticket-source-resolution.md).
|
|
42
|
-
- **Already in context**: This session already resolved the ticket. Use it as-is.
|
|
43
|
-
- **Stored URL**: `ticket_url` from step 1, fetched per [Stored ticket URL](../_data/ticket-source-resolution.md#stored-ticket-url).
|
|
44
|
-
- **Plan provenance**: The plan's frontmatter `ticket_ref` / `ticket_id`, resolved per [auto-resolve](../_data/ticket-source-resolution.md#auto-resolve).
|
|
45
|
-
- **No ticket**: Every source failed; the plan was produced from a free-form description, or the ticket is unreachable. Announce that a ticket does not govern the run and execute against the plan as the sole contract. Do not stall on a missing ticket; do not silently substitute the plan for one without saying so.
|
|
46
|
-
|
|
47
|
-
4. **Read the plan and the ticket** in full before touching code, including the plan's `## Risks` section: It names the parts of the work that the author expected to need adaptation.
|
|
48
|
-
|
|
49
|
-
Check the shape as you read: A plan with `## Investigation steps` rather than `## Tasks` is a spike, which this skill does not implement (see [Scope](#scope)). Stop and tell the user the plan is a spike, to be carried out directly rather than implemented here.
|
|
50
|
-
|
|
51
|
-
Then, when a ticket governs the run, read its open blockers per [Open blockers](../_data/ticket-source-resolution.md#open-blockers). When it has one, report it and ask the user to confirm that implementation should start despite it, as a `👍🏼👎🏼` confirmation. Do not start the first task without a clear affirmation.
|
|
52
|
-
|
|
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.
|
|
26
|
+
<!-- include: ../_partials/resolve-plan-and-ticket.md / -->
|
|
54
27
|
|
|
55
28
|
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
29
|
|
|
@@ -76,7 +49,7 @@ The plan artifact is read-only. It is a record of what was decided at plan time,
|
|
|
76
49
|
|
|
77
50
|
## Fact routing
|
|
78
51
|
|
|
79
|
-
The audience decides where a fact goes. A fact that the user acts on, such as a decision that is theirs or a divergence that they must weigh, belongs in the response. A fact that a reviewer acts on belongs in the commit body
|
|
52
|
+
The audience decides where a fact goes. A fact that the user acts on, such as a decision that is theirs or a divergence that they must weigh, belongs in the response. A fact that a reviewer acts on belongs in the commit body or a comment in the source; `summarize-change` adds a commit-body fact to the pull-request description's `## Notes for reviewers` when the fact passes that skill's reader test. A fact needed by both goes in the artifact and may be summarized in the response; the artifact is never skipped.
|
|
80
53
|
|
|
81
54
|
The failure that this prevents is visible in the phrasing: Any wording that treats the reader as an intermediary, such as "worth a reviewer's attention", "flag this in review", or "mention that...", marks a fact that belongs in an artifact. When one is found after the artifact is written, amend the artifact rather than narrate the gap.
|
|
82
55
|
|
|
@@ -166,3 +139,5 @@ Never push, force-push, or delete a remote branch, never create a worktree, and
|
|
|
166
139
|
<!-- include: ../_partials/split-launch-prompts.md / -->
|
|
167
140
|
|
|
168
141
|
<!-- include: ../_partials/option-format.md / -->
|
|
142
|
+
|
|
143
|
+
<!-- include: ../_partials/implementation-order-list.md / -->
|