codeassembly-guidance 0.7.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.
Files changed (101) hide show
  1. package/.meta/changelog.json +261 -0
  2. package/CHANGELOG.md +62 -0
  3. package/README.md +47 -29
  4. package/bin/codeassembly-validate-preferences.js +2 -8
  5. package/content/_partials/diff-audit-checklist.md +1 -0
  6. package/content/_partials/plain-speech.md +2 -2
  7. package/content/_partials/ticket-assessment.md +3 -3
  8. package/content/codeassembly-content.yaml +6 -0
  9. package/content/collections/recommended.md +6 -0
  10. package/content/collections/williamthorsen.md +2 -1
  11. package/content/guidance/rulebooks/accessibility-conventions.md +6 -3
  12. package/content/guidance/rulebooks/cross-repo-migration-conventions.md +27 -0
  13. package/content/guidance/rulebooks/ui-copy-conventions.md +2 -2
  14. package/content/guidance/rulebooks/visual-design-conventions.md +58 -0
  15. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +3 -18
  16. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +6 -2
  17. package/content/guidance/rulebooks/williamthorsen-visual-design-preferences.md +14 -0
  18. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +5 -3
  19. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +5 -20
  20. package/content/guidance/shared/AGENTS.md +2 -3
  21. package/content/scripts/README.md +1 -1
  22. package/content/scripts/check-branch-currency.mjs +7 -7
  23. package/content/scripts/check-prose.mjs +38 -38
  24. package/content/scripts/describe-change.mjs +32 -32
  25. package/content/scripts/manage-jira-ticket.mjs +148 -146
  26. package/content/scripts/validate-preferences.mjs +9 -9
  27. package/content/skills/_data/artifact-conventions.md +3 -3
  28. package/content/skills/_data/entry-points.md +1 -1
  29. package/content/skills/_data/reduced-object-relatives.md +15 -0
  30. package/content/skills/_data/spike-conventions.md +9 -2
  31. package/content/skills/_data/ticket-evaluation.md +3 -0
  32. package/content/skills/_partials/implementation-order-list.md +4 -4
  33. package/content/skills/_partials/merge-settled-criterion.md +1 -0
  34. package/content/skills/_partials/plan-template.md +1 -1
  35. package/content/skills/_partials/resolve-plan-and-ticket.md +2 -2
  36. package/content/skills/_partials/split-ticket-create.md +1 -1
  37. package/content/skills/_partials/ticket-criteria-conventions.md +2 -0
  38. package/content/skills/align-ticket-with-implementation/SKILL.md +2 -2
  39. package/content/skills/analyze-performance/SKILL.md +1 -1
  40. package/content/skills/assess-code-health/SKILL.md +4 -4
  41. package/content/skills/assess-code-health/assess-code-health.mjs +20 -20
  42. package/content/skills/assess-ticket/SKILL.md +3 -1
  43. package/content/skills/assess-ticket/next-steps-after-assessment.md +11 -14
  44. package/content/skills/assess-usability/SKILL.md +4 -4
  45. package/content/skills/capture-event/capture-event.mjs +30 -30
  46. package/content/skills/capture-lede-decision/SKILL.md +1 -1
  47. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +37 -37
  48. package/content/skills/collaborate/SKILL.md +1 -1
  49. package/content/skills/condense-branch/SKILL.md +18 -36
  50. package/content/skills/condense-branch/condense-branch.mjs +17 -0
  51. package/content/skills/create-bitbucket-pr/SKILL.md +9 -11
  52. package/content/skills/create-commit/SKILL.md +1 -1
  53. package/content/skills/create-devlog/SKILL.md +4 -4
  54. package/content/skills/create-gh-pr/SKILL.md +9 -11
  55. package/content/skills/create-pr/SKILL.md +9 -11
  56. package/content/skills/create-ticket/SKILL.md +22 -15
  57. package/content/skills/curate-feedback/SKILL.md +2 -2
  58. package/content/skills/derive-session-context/derive-session-context.mjs +103 -103
  59. package/content/skills/design-and-plan/SKILL.md +6 -6
  60. package/content/skills/groom-backlog/groom-backlog.mjs +15 -15
  61. package/content/skills/implement-plan/SKILL.md +1 -1
  62. package/content/skills/implementation-order/implementation-order.mjs +29 -29
  63. package/content/skills/index-prototypes/SKILL.md +2 -2
  64. package/content/skills/investigate-spike/SKILL.md +3 -3
  65. package/content/skills/list-gh-progress-items/SKILL.md +36 -0
  66. package/content/skills/list-gh-progress-items/list-gh-progress-items.mjs +68 -0
  67. package/content/skills/list-implementation-order/SKILL.md +2 -2
  68. package/content/skills/merge-bb-pr/SKILL.md +9 -11
  69. package/content/skills/merge-gh-pr/SKILL.md +9 -11
  70. package/content/skills/merge-pr/SKILL.md +10 -12
  71. package/content/skills/plan/SKILL.md +2 -2
  72. package/content/skills/prepare-prototype-brief/SKILL.md +2 -2
  73. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +22 -22
  74. package/content/skills/refine-plan/SKILL.md +3 -3
  75. package/content/skills/refine-prototype/SKILL.md +2 -1
  76. package/content/skills/respond-to-review/SKILL.md +4 -4
  77. package/content/skills/review-bb-pr/SKILL.md +1 -2
  78. package/content/skills/review-branch/SKILL.md +18 -13
  79. package/content/skills/review-criteria/SKILL.md +1 -1
  80. package/content/skills/review-gh-pr/SKILL.md +1 -2
  81. package/content/skills/review-pr/SKILL.md +2 -3
  82. package/content/skills/revise-prose/revise-prose.mjs +52 -52
  83. package/content/skills/save-artifact/SKILL.md +4 -6
  84. package/content/skills/save-plan/SKILL.md +2 -2
  85. package/content/skills/start-ticket/SKILL.md +1 -1
  86. package/content/skills/streamline-guidance/streamline-guidance.mjs +24 -24
  87. package/content/skills/summarize-change/SKILL.md +5 -4
  88. package/content/skills/summarize-chat/SKILL.md +2 -2
  89. package/content/skills/triage-feedback/SKILL.md +2 -2
  90. package/content/skills/triage-spike-findings/SKILL.md +26 -22
  91. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +19 -19
  92. package/content/skills/update-project-guidance/SKILL.md +1 -1
  93. package/content/skills/wrap-up/SKILL.md +4 -4
  94. package/content/skills/write-progress-report/SKILL.md +111 -0
  95. package/content/skills/write-progress-report/write-progress-report.mjs +150 -0
  96. package/content/subagents/disposition-challenger.md +7 -6
  97. package/content/subagents/entry-drafter.md +2 -0
  98. package/content/subagents/usability-assessor.md +3 -2
  99. package/package.json +11 -10
  100. package/schemas/preferences.v1.json +9 -1
  101. package/schemas/work-types.v1.json +1 -1
@@ -6,13 +6,13 @@ disable-model-invocation: true
6
6
 
7
7
  # List implementation order
8
8
 
9
- Print the open tickets that the conversation created or discussed, in the order in which to implement them. You name the tickets, and the [implementation-order list](#implementation-order-list) section renders them.
9
+ Print the open tickets that the conversation created or discussed and that have work of their own, in the order in which to implement them. You name the tickets, and the [implementation-order list](#implementation-order-list) section renders them.
10
10
 
11
11
  Never invoke this skill on your own initiative, and never suggest it.
12
12
 
13
13
  ## Process
14
14
 
15
- 1. **Collect the tickets.** List every ticket that the conversation created or discussed, in the order in which the conversation reached them. Give a ticket outside GitHub its key and its title.
15
+ 1. **Collect the tickets.** List every ticket that the conversation created or discussed, in the order in which the conversation reached them. Give a ticket outside GitHub its key, its title, and, when the conversation establishes it, the repository in which the ticket is implemented. For an umbrella, name its children as well: The list leaves the umbrella out.
16
16
 
17
17
  When the conversation does not contain any ticket, say so in one line and stop.
18
18
 
@@ -10,16 +10,14 @@ Internal delegate that merges a pull request on Bitbucket. Called by `merge-pr`
10
10
 
11
11
  ## Delegate interface
12
12
 
13
- | Input | Type | Description |
14
- | ------------------- | ------------------------------- | ----------------------------------------- |
15
- | `pr_number` | number | PR to merge |
16
- | `title` | string | Pre-rendered merge-commit title |
17
- | `body` | string | Pre-composed merge-commit body |
18
- | `strategy` | `squash` \| `merge` \| `rebase` | Concrete strategy (no `prompt` sentinel) |
19
- | `deletion_strategy` | `both` \| `remote` \| `none` | Which branches to delete after merge |
20
- | `ticket_id` | string | Ticket ID for artifact path resolution |
21
- | `project_slug` | string | Project slug for artifact path resolution |
22
- | `artifact_base_dir` | string | Base directory for artifact storage |
13
+ | Input | Type | Description |
14
+ | ------------------- | ------------------------------- | --------------------------------------------------------- |
15
+ | `pr_number` | number | PR to merge |
16
+ | `title` | string | Pre-rendered merge-commit title |
17
+ | `body` | string | Pre-composed merge-commit body |
18
+ | `strategy` | `squash` \| `merge` \| `rebase` | Concrete strategy (no `prompt` sentinel) |
19
+ | `deletion_strategy` | `both` \| `remote` \| `none` | Which branches to delete after merge |
20
+ | `ticket_dir` | string | Ticket artifact directory, in which the artifact is saved |
23
21
 
24
22
  ## Bitbucket access
25
23
 
@@ -91,7 +89,7 @@ Success in step 4 means that the PR was merged, so a `merge_commit.hash` absent
91
89
 
92
90
  Save a `merge` artifact in the ticket directory, in the same format that `merge-gh-pr` writes, so that `capture-lede-decision` reads it on this platform as it does on GitHub.
93
91
 
94
- Ticket directory: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
92
+ Ticket directory: `{ticket_dir}/`
95
93
 
96
94
  `mkdir -p` the target directory before writing.
97
95
 
@@ -10,16 +10,14 @@ Internal delegate that merges a pull request on GitHub. Called by `merge-pr` wit
10
10
 
11
11
  ## Delegate interface
12
12
 
13
- | Input | Type | Description |
14
- | ------------------- | ------------------------------- | ----------------------------------------- |
15
- | `pr_number` | number | PR to merge |
16
- | `title` | string | Pre-rendered merge-commit title |
17
- | `body` | string | Pre-composed merge-commit body |
18
- | `strategy` | `squash` \| `merge` \| `rebase` | Concrete strategy (no `prompt` sentinel) |
19
- | `deletion_strategy` | `both` \| `remote` \| `none` | Which branches to delete after merge |
20
- | `ticket_id` | string | Ticket ID for artifact path resolution |
21
- | `project_slug` | string | Project slug for artifact path resolution |
22
- | `artifact_base_dir` | string | Base directory for artifact storage |
13
+ | Input | Type | Description |
14
+ | ------------------- | ------------------------------- | --------------------------------------------------------- |
15
+ | `pr_number` | number | PR to merge |
16
+ | `title` | string | Pre-rendered merge-commit title |
17
+ | `body` | string | Pre-composed merge-commit body |
18
+ | `strategy` | `squash` \| `merge` \| `rebase` | Concrete strategy (no `prompt` sentinel) |
19
+ | `deletion_strategy` | `both` \| `remote` \| `none` | Which branches to delete after merge |
20
+ | `ticket_dir` | string | Ticket artifact directory, in which the artifact is saved |
23
21
 
24
22
  ## Process
25
23
 
@@ -122,7 +120,7 @@ When the helper exits non-zero, it still prints JSON on stdout, containing only
122
120
 
123
121
  Save a `merge` artifact in the ticket directory.
124
122
 
125
- Ticket directory: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
123
+ Ticket directory: `{ticket_dir}/`
126
124
 
127
125
  `mkdir -p` the target directory before writing.
128
126
 
@@ -28,7 +28,7 @@ Three keys in `.agents/preferences.yaml` and `~/.agents/preferences.yaml` set th
28
28
 
29
29
  ### 1. Get session context
30
30
 
31
- 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_ref`, `branch_name`, `default_branch`, `scm`, `project_slug`, `ticket_id`, `artifact_base_dir`, `pr_url`, `merge_approval`, `merge_strategy`, and `merge_deletion_strategy` from it.
31
+ 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_ref`, `branch_name`, `default_branch`, `scm`, `ticket_id`, `ticket_dir`, `pr_url`, `merge_approval`, `merge_strategy`, and `merge_deletion_strategy` from it.
32
32
 
33
33
  ### 2. Resolve the PR
34
34
 
@@ -218,7 +218,7 @@ A type that the developer named, through `--type` or in an answer at the gate, s
218
218
 
219
219
  Take a type spelled with the marker, whether decided here or named by the developer, as the pair that the flags imply: `feat!` is `--override-type feat` with `--override-breaking`, and for an entry, `--type feat` with `--breaking`. The helper refuses a type spelled with `!`, so it would refuse such a type passed through unchanged, and the defect would stay unsettled.
220
220
 
221
- When asking option-style questions, follow [option format](#option-format). (Reinforces the rule in `AGENTS.md`: intentional redundancy.)
221
+ When asking option-style questions, follow [option format](#option-format).
222
222
 
223
223
  Re-run step 3 after each amendment and each override, with every override added to the override set, until `defects` is empty. Never offer the merge while `defects` contains an item. If an override or an amendment moves the effective record to another tier and step 5 drafted the body, re-run step 5's drafting against the new tier.
224
224
 
@@ -339,16 +339,14 @@ If it exits non-zero, stop, and end the reply with the [refusal summary](#11-rep
339
339
 
340
340
  Pass the following inputs to the selected delegate per the delegate interface:
341
341
 
342
- | Input | Value |
343
- | ------------------- | -------------------------------------------------------------------- |
344
- | `pr_number` | Resolved PR number |
345
- | `title` | Rendered `merge_title` as step 8 last resolved and the user approved |
346
- | `body` | Published body as step 8 last resolved and the user approved |
347
- | `strategy` | Resolved strategy from step 4 |
348
- | `deletion_strategy` | Resolved value from step 4 (`both` \| `remote` \| `none`) |
349
- | `ticket_id` | From session context |
350
- | `project_slug` | From session context |
351
- | `artifact_base_dir` | From session context |
342
+ | Input | Value |
343
+ | ------------------- | ----------------------------------------------------------------------------------------------------- |
344
+ | `pr_number` | Resolved PR number |
345
+ | `title` | Rendered `merge_title` as step 8 last resolved and the user approved |
346
+ | `body` | Published body as step 8 last resolved and the user approved |
347
+ | `strategy` | Resolved strategy from step 4 |
348
+ | `deletion_strategy` | Resolved value from step 4 (`both` \| `remote` \| `none`) |
349
+ | `ticket_dir` | `ticket_dir` from session context, or the directory that {skill:save-artifact} states when it is null |
352
350
 
353
351
  The orchestrator never passes a title that `defects` blocks, or a `prompt` sentinel, to the delegate: All values are concrete by this point.
354
352
 
@@ -54,8 +54,8 @@ Run `{harness_home_dir}/scripts/resolve-frontmatter.sh --skill plan --interactiv
54
54
 
55
55
  ### Ticket context
56
56
 
57
- 1. Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash to obtain `ticket_id`, `project_slug`, and `artifact_base_dir` from the manifest JSON emitted on stdout. If the manifest does not contain a ticket ID, auto-generate: `{YYYYMMDD}-{4 random hex}`.
58
- 2. Save as ticket-level artifact: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/{timestamp}_{slug}_plan.md`
57
+ 1. Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash to obtain `ticket_dir` from the manifest JSON emitted on stdout. When it is null, use the directory that {skill:save-artifact} states.
58
+ 2. Save as ticket-level artifact: `{ticket_dir}/{timestamp}_{slug}_plan.md`
59
59
  3. Slug per [artifact conventions](../_data/artifact-conventions.md#naming-conventions).
60
60
 
61
61
  Follow [artifact conventions](../_data/artifact-conventions.md).
@@ -61,7 +61,7 @@ The failure that this prevents: the lens paragraph reproduced as helper text und
61
61
 
62
62
  ### Require a salience order
63
63
 
64
- Require a salience order in every working view: the current state in one place, the next thing to happen more prominent than the rest, and every action visibly an action. Name {rulebook:accessibility-conventions} and {rulebook:ui-copy-conventions} as the floor, including the accessibility rulebook's named-model, placement, toggle, glanceable-state, and button-at-rest rules, and state that usability outranks restraint: A calm or restrained direction never hides a state for which the reader scans. A builder departs from the named model only for a reason, which it reports with its distinctive ideas. Require that a status repeated on every row be a mark, a column, or a style, not a sentence.
64
+ Require a salience order in every working view: the current state in one place, the next thing to happen more prominent than the rest, and every action visibly an action. Name {rulebook:accessibility-conventions}, {rulebook:visual-design-conventions}, and {rulebook:ui-copy-conventions} as the floor, including the accessibility rulebook's named-model, placement, consequence-at-the-control, toggle, glanceable-state, and button-at-rest rules, and state that usability outranks restraint: A calm or restrained direction never hides a state for which the reader scans. A builder departs from the named model only for a reason, which it reports with its distinctive ideas. Require that a status repeated on every row be a mark, a column, or a style, not a sentence.
65
65
 
66
66
  The failure that this prevents: a page in one colour, in which the operator hunts for the control, "Hidden from the players." written out on every hidden row, and an expiry column in plain text, in which the operator reads every row to find the expired ones.
67
67
 
@@ -87,7 +87,7 @@ Write the brief in this order, with these headings:
87
87
  2. **Settled intent.** Bullets. Each is a decision, with its reason when the reason constrains the design.
88
88
  3. **Deliverable.** The file and its path per {skill:index-prototypes}; the constraints (self-contained, opens from `file://`, inline CSS and JavaScript, no framework, readable with JavaScript off, phone width, every loop bounded by an iteration count or a time limit); the mechanism that must run; the demo control that plays the written scene; a full-screen mode when the product has an audience view. The demo chrome (the demo control, scene captions, the lens note, the data-model note, the API list) is in a band visibly distinct from the product surface, and every part of it is inside an element that has the `data-demo` attribute. The band's first line is the id from the dispatch block and the prototype's title, `{id} {title}`. The page's `<title>` is `{set title} - {id} {title}`, with the set title and the id from the dispatch block.
89
89
  4. **Sections.** Numbered, each a noun phrase plus what it contains and a length bound. None asks for persuasion; one is the scene, exhibited; one is the data-model note when the product stores data; one is the API list when the product has an API.
90
- 5. **Quality bar.** Works, legible, accessible, and within the copy rules, with {rulebook:accessibility-conventions} and {rulebook:ui-copy-conventions} named, the design skill to invoke before markup, and the salience order required.
90
+ 5. **Quality bar.** Works, legible, accessible, and within the copy rules, with {rulebook:accessibility-conventions}, {rulebook:visual-design-conventions}, and {rulebook:ui-copy-conventions} named, the design skill to invoke before markup, and the salience order required.
91
91
  6. **How this round is judged.** The criteria, in the reviewer's voice, with the divergence between lenses named as the point of the round. One criterion is the copy: "Read every string on the product surface as its user opening the page for the tenth time. A string that explains the page, reassures, or repeats the brief, and any copy over the budget in {rulebook:ui-copy-conventions}, is a defect." Another is the glanceable state: "A list in which the reader must read each item to find a state for which the reader scans, such as expired or failing, is a defect, whatever restraint the lens asks for."
92
92
  7. **Rules of engagement.** The write allowance from the inputs. The default: Write the output file and nothing else, modify nothing in the repository, install nothing. When the ask allows more, state what it allows. Then: Publish the prototype and report its artifact URL, a value for each of the set's note labels (listed here), and five lines of distinctive ideas.
93
93