codeassembly-guidance 0.6.0 → 0.8.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 +446 -0
- package/CHANGELOG.md +107 -0
- package/README.md +47 -51
- package/bin/codeassembly-validate-preferences.js +2 -8
- package/content/_partials/diff-audit-checklist.md +1 -0
- package/content/_partials/kb-unsearched-private-stores.md +6 -0
- package/content/_partials/plain-speech.md +2 -2
- package/content/_partials/ticket-assessment.md +3 -3
- package/content/codeassembly-content.yaml +8 -0
- package/content/collections/recommended.md +6 -0
- package/content/collections/williamthorsen.md +2 -1
- package/content/guidance/rulebooks/accessibility-conventions.md +6 -3
- package/content/guidance/rulebooks/cross-repo-migration-conventions.md +27 -0
- package/content/guidance/rulebooks/live-worktree-policy.md +2 -2
- package/content/guidance/rulebooks/ui-copy-conventions.md +2 -2
- package/content/guidance/rulebooks/visual-design-conventions.md +58 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +3 -18
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +7 -1
- package/content/guidance/rulebooks/williamthorsen-visual-design-preferences.md +14 -0
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +5 -3
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +5 -20
- package/content/guidance/shared/AGENTS.md +3 -4
- package/content/scripts/README.md +1 -1
- package/content/scripts/check-branch-currency.mjs +7 -7
- package/content/scripts/check-prose.mjs +38 -38
- package/content/scripts/describe-change.mjs +89 -89
- package/content/scripts/manage-jira-ticket.mjs +162 -160
- package/content/scripts/select-lede-exemplars.mjs +85 -85
- package/content/scripts/validate-preferences.mjs +41 -41
- package/content/skills/_data/artifact-conventions.md +3 -3
- package/content/skills/_data/entry-points.md +1 -1
- package/content/skills/_data/project-stage.md +9 -5
- package/content/skills/_data/reduced-object-relatives.md +15 -0
- package/content/skills/_data/spike-conventions.md +16 -6
- package/content/skills/_data/ticket-evaluation.md +3 -0
- package/content/skills/_partials/implementation-order-list.md +27 -0
- package/content/skills/_partials/merge-settled-criterion.md +1 -0
- package/content/skills/_partials/next-steps-after-plan.md +2 -2
- package/content/skills/_partials/plan-template.md +3 -1
- package/content/skills/_partials/resolve-plan-and-ticket.md +2 -2
- package/content/skills/_partials/split-launch-prompts.md +1 -1
- package/content/skills/_partials/split-ticket-create.md +1 -1
- package/content/skills/_partials/ticket-criteria-conventions.md +2 -0
- package/content/skills/align-ticket-with-implementation/SKILL.md +3 -3
- package/content/skills/analyze-performance/SKILL.md +1 -1
- package/content/skills/assess-code-health/SKILL.md +4 -4
- package/content/skills/assess-code-health/assess-code-health.mjs +20 -20
- package/content/skills/assess-ticket/SKILL.md +3 -1
- package/content/skills/assess-ticket/next-steps-after-assessment.md +11 -14
- package/content/skills/assess-usability/SKILL.md +4 -4
- package/content/skills/capture-event/SKILL.md +20 -11
- package/content/skills/capture-event/capture-event.mjs +123 -123
- package/content/skills/capture-feedback/SKILL.md +2 -1
- package/content/skills/capture-lede-decision/SKILL.md +1 -1
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +97 -97
- package/content/skills/collaborate/SKILL.md +1 -1
- package/content/skills/condense-branch/SKILL.md +18 -36
- package/content/skills/condense-branch/condense-branch.mjs +17 -0
- package/content/skills/create-bitbucket-pr/SKILL.md +9 -11
- package/content/skills/create-commit/SKILL.md +1 -1
- package/content/skills/create-devlog/SKILL.md +4 -4
- package/content/skills/create-gh-pr/SKILL.md +9 -11
- package/content/skills/create-pr/SKILL.md +10 -12
- package/content/skills/create-ticket/SKILL.md +22 -15
- package/content/skills/create-ticket/resolve-ticket-target.mjs +92 -92
- package/content/skills/curate-feedback/SKILL.md +2 -2
- package/content/skills/curate-feedback/curate-feedback.mjs +82 -82
- package/content/skills/derive-session-context/derive-session-context.mjs +120 -120
- package/content/skills/design-and-plan/SKILL.md +10 -8
- package/content/skills/groom-backlog/groom-backlog.mjs +15 -15
- package/content/skills/implement-plan/SKILL.md +4 -2
- package/content/skills/implementation-order/implementation-order.mjs +67 -0
- package/content/skills/index-prototypes/SKILL.md +2 -2
- package/content/skills/investigate-spike/SKILL.md +3 -3
- 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-gh-progress-items/SKILL.md +36 -0
- package/content/skills/list-gh-progress-items/list-gh-progress-items.mjs +68 -0
- package/content/skills/list-implementation-order/SKILL.md +23 -0
- package/content/skills/merge-bb-pr/SKILL.md +40 -19
- package/content/skills/merge-gh-pr/SKILL.md +34 -23
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +13 -8
- package/content/skills/merge-pr/SKILL.md +64 -31
- package/content/skills/migrate-feedback-memories/SKILL.md +1 -0
- package/content/skills/plan/SKILL.md +5 -3
- package/content/skills/prepare-prototype-brief/SKILL.md +5 -3
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +22 -22
- package/content/skills/refine-plan/SKILL.md +5 -3
- package/content/skills/refine-prototype/SKILL.md +2 -1
- package/content/skills/respond-to-review/SKILL.md +4 -4
- package/content/skills/review-bb-pr/SKILL.md +1 -2
- package/content/skills/review-branch/SKILL.md +19 -14
- package/content/skills/review-criteria/SKILL.md +2 -2
- package/content/skills/review-gh-pr/SKILL.md +1 -2
- package/content/skills/review-pr/SKILL.md +2 -3
- package/content/skills/revise-prose/revise-prose.mjs +109 -109
- package/content/skills/save-artifact/SKILL.md +4 -6
- package/content/skills/save-plan/SKILL.md +4 -2
- package/content/skills/start-ticket/SKILL.md +1 -1
- package/content/skills/streamline-guidance/streamline-guidance.mjs +80 -80
- package/content/skills/summarize-change/SKILL.md +20 -9
- package/content/skills/summarize-chat/SKILL.md +2 -2
- package/content/skills/testing-conventions/SKILL.md +2 -2
- package/content/skills/triage-feedback/SKILL.md +6 -2
- package/content/skills/triage-spike-findings/SKILL.md +33 -24
- package/content/skills/triage-spike-findings/triage-spike-findings.mjs +19 -19
- package/content/skills/update-project-guidance/SKILL.md +1 -1
- package/content/skills/wrap-up/SKILL.md +8 -4
- package/content/skills/write-progress-report/SKILL.md +111 -0
- package/content/skills/write-progress-report/write-progress-report.mjs +150 -0
- package/content/subagents/disposition-challenger.md +7 -6
- package/content/subagents/entry-drafter.md +2 -0
- package/content/subagents/usability-assessor.md +3 -2
- package/package.json +13 -12
- package/schemas/preferences.v1.json +82 -8
- package/schemas/work-types.v1.json +1 -1
|
@@ -64,12 +64,12 @@ 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
|
|
72
|
-
- When asking option-style questions, follow [option format](#option-format).
|
|
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
|
+
- When asking option-style questions, follow [option format](#option-format).
|
|
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.
|
|
75
75
|
|
|
@@ -78,7 +78,7 @@ Invoke the `{skill:assess-ticket}` skill with the resolved ticket source and mod
|
|
|
78
78
|
### Phase 3: Converge on a design and refine the ticket
|
|
79
79
|
|
|
80
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
|
-
- When asking option-style questions, follow [option format](#option-format).
|
|
81
|
+
- When asking option-style questions, follow [option format](#option-format).
|
|
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.
|
|
84
84
|
|
|
@@ -102,7 +102,7 @@ Here, _the implementation_ is the plan artifact (Phase 4): Mechanism that the ti
|
|
|
102
102
|
|
|
103
103
|
<!-- include: ../../_partials/prose-line-breaks.md / -->
|
|
104
104
|
|
|
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.
|
|
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. When the design spans several layers or adds a new subsystem, also state the size estimate and the split recommendation that "Splitting work across tickets" above requires; because a split creates tickets, offer it as a menu, with the split at ■■■ when each piece can be merged and verified on its own. Revise until approved. Approval of the ticket is approval of the design.
|
|
106
106
|
|
|
107
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
|
|
|
@@ -129,10 +129,10 @@ Present the plan as the second checkpoint, with its `## Decisions taken` section
|
|
|
129
129
|
Then save both artifacts:
|
|
130
130
|
|
|
131
131
|
1. Resolve artifact directory using `save-artifact` conventions:
|
|
132
|
-
- Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash to obtain `
|
|
133
|
-
- Target: `{
|
|
132
|
+
- Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash to obtain `ticket_dir` and `project_artifact_dir` from the manifest JSON emitted on stdout
|
|
133
|
+
- Target: `{ticket_dir}/`, or the directory that {skill:save-artifact} states when `ticket_dir` is null
|
|
134
134
|
- `mkdir -p` the target directory
|
|
135
|
-
- After an umbrella split, save the plan in the planned child's directory instead, `tickets/{child_id}/`, beside the ticket artifact that `{skill:create-ticket}` saved there
|
|
135
|
+
- After an umbrella split, save the plan in the planned child's directory instead, `{project_artifact_dir}/tickets/{child_id}/`, beside the ticket artifact that `{skill:create-ticket}` saved there
|
|
136
136
|
|
|
137
137
|
2. Resolve frontmatter fields for both artifacts. The frontmatter conforms to the [universal artifact frontmatter](../_data/artifact-conventions.md#universal-artifact-frontmatter) schema.
|
|
138
138
|
|
|
@@ -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 / -->
|