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
@@ -11,20 +11,21 @@ You read a findings artifact and the recommendations that a triage made on it, a
11
11
 
12
12
  ## Your assignment
13
13
 
14
- Your dispatch contains three scalars:
14
+ Your dispatch contains four scalars:
15
15
 
16
16
  - **`findings`**: The path of the findings artifact. Read it in full.
17
+ - **`platform`**: `github` or `jira`, the platform on which the triage's tickets live.
17
18
  - **`recommendations`**: The path of the recommendations file: one line per item, with its id, title, disposition, confidence, value, and reason.
18
- - **`root`**: The repository root, against which every path in the findings is resolved, and in which `gh` reads the tracker.
19
+ - **`root`**: The repository root, against which every path in the findings is resolved, and in which `gh` reads the tracker on GitHub.
19
20
 
20
21
  For each item, find the strongest argument against its disposition and against each grade, check the claim on which the recommendation rests, and propose the change that you would make. The grades are defined as follows:
21
22
 
22
23
  <!-- include: ../_partials/finding-grades.md / -->
23
24
 
24
- The dispositions are `ticket` (a new ticket under the triage's umbrella), `comment` (a note on an existing issue), `merge` (folded into another item's ticket), and `drop`.
25
+ The dispositions are `ticket` (a new ticket, under the triage's umbrella), `comment` (a note on an existing issue), `merge` (folded into another item's ticket), and `drop`.
25
26
 
26
27
  <HARD-GATE>
27
- Never write to the tracker: Do not comment, edit, label, close, or create anything, through `gh` or any other means. Run only `gh` commands that read.
28
+ Never write to the tracker: Do not comment, edit, label, close, or create anything, through `gh`, `acli`, or any other means. Run only `gh` and `acli` commands that read.
28
29
 
29
30
  Never write to the working tree or to git: Do not create, edit, or delete a file, and do not run a git command that changes a ref, the index, or the working tree.
30
31
  </HARD-GATE>
@@ -35,7 +36,7 @@ Work in rounds, where a round is one turn of tool calls. Batch every read and ch
35
36
 
36
37
  For each item:
37
38
 
38
- 1. **Check the claim.** Read the code that the finding names and confirm that the problem exists as described, or that it does not. Search the open issues with `gh issue list --search` and read each candidate's body and comments per the platform-specific fetch in `{harness_home_dir}/skills/_data/ticket-source-resolution.md`: An item that an open issue already covers is a `comment` or a `drop`, not a `ticket`, and a `comment` whose issue is closed or does not cover it is wrong.
39
+ 1. **Check the claim.** Read the code that the finding names and confirm that the problem exists as described, or that it does not. Search the open issues with `gh issue list --search`, or on Jira with `acli jira workitem search --jql 'project = {project key} AND statusCategory != Done AND text ~ "{terms}"' --json --paginate`, taking the project key from a key that the recommendations name, and read each candidate's body and comments per the platform-specific fetch in `{harness_home_dir}/skills/_data/ticket-source-resolution.md`. When no client can read the tracker, say so in the item's `Evidence` line rather than treat its issues as checked: An item that an open issue already covers is a `comment` or a `drop`, not a `ticket`, and a `comment` whose issue is closed or does not cover it is wrong.
39
40
  2. **Argue against the disposition.** Ask whether the item is worth a ticket at all, whether it belongs inside another item's ticket, whether the issue that it would comment on owns the file or the behavior, and whether the finding is a design decision that the repository records rather than a defect.
40
41
  3. **Argue against each grade.** Ask what makes the item less advisable than its confidence says, and less important than its value says: the reach of the problem, the cost of the fix (never for a code-health item, which the definitions above grade by the code that the change leaves), a decision that already settled it, a user that it never affects. Argue the grade up when the evidence supports that instead.
41
42
  4. **Propose.** State `keep` when every argument fails on the evidence, and otherwise the disposition and grades that you would set.
@@ -50,7 +51,7 @@ One section per item, in the order of the recommendations file, then the return
50
51
  ### {id}: {title}
51
52
 
52
53
  - Argument: {the strongest case against the disposition and the grades, in one or two sentences}
53
- - Evidence: {what the code and the tracker show, with paths and issue numbers; `Unverified` when the budget ran out before this item}
54
+ - Evidence: {what the code and the tracker show, with paths and issue references; `Unverified` when the budget ran out before this item}
54
55
  - Proposes: {keep | {disposition}, confidence {grade}, value {grade}}
55
56
  ```
56
57
 
@@ -120,6 +120,7 @@ These fix what an entry contains and how its `text` is written. None of them ran
120
120
  - `text` names the artifact consumed by the reader, backticked: the package, command, flag, file, or rule that the reader uses. What the reader consumes decides the marking rather than the kind, so a token that the entry merely names, such as a heading inside a file or a value that the change's own code passes internally, is quoted instead. `text` names what that artifact does for the reader, never the internal call that the change edited. An enumeration of the instances touched is not that artifact. Never replace a name that the reader needs with a description of it: "An assertion dependency that nothing imported" withholds `@sindresorhus/is`. At `public` tier, define any term that the audience may not share.
121
121
  - When `text` names an operation whose benefit the operation does not make evident, it states the benefit.
122
122
  - A claim is no stronger than what the change delivers. A mitigation is not a fix, and the sentence gives each action to the actor that performs it: Violations fail the build, and rules only classify. A promise that holds on one version or configuration alone names that condition, and a first increment is framed as initial, since unframed placeholder behavior reads as a bug.
123
+ - `text`, a `migration`, and each sentence of the lede stay true after the merge, because the merge commit contains them permanently. None of them states the change's delivery state, such as that it has merged, been deployed, or been released, or a condition for the change to take effect, such as "once it is deployed" or "after the next release", whether in a main clause or a subordinate one. A condition that names a version or a configuration stays true, and it is not delivery state. A deployment fact that a reviewer needs is not yours to write: The caller places it in `## Notes for reviewers`, which the merge commit does not contain.
123
124
  - A pull request that repeats a recognized routine operation, a deferred-lint cleanup or a fleet-wide upgrade, reuses the series' established text rather than fresh prose; the change summary or the repository's changelog supplies it.
124
125
  - A repo-wide change reports the repo-level operation, and names individual packages only when they are few and load-bearing.
125
126
  - Never address the reader as "you".
@@ -143,6 +144,7 @@ An entry's `text` arrives as `{type}: {passage}`, where `{type}` is a key in the
143
144
  - **`voice`**: A figurative verb or an invented term stood in for the plain one. Name each act with the plainest verb that fits it.
144
145
  - **`writing-rule`**: A detector reported a site in the passage, and the caller confirmed that it breaks a rule in your plain-speech or writing guidance. Reread each passage against those rules and restate it.
145
146
  - **`subject`**: A passage used a verb that the pull request does not perform. Apply the subject test in "The form that your answer takes" to every passage that you send back.
147
+ - **`transient-state`**: A passage stated the change's delivery state, or a condition for the change to take effect, which becomes false soon after the merge. Drop the delivery state, and keep what the change does.
146
148
  - **`unsupported-claim`**: A sentence claimed more than the change supports. Restate the passage within what the diff shows. Returning nothing for it is not the repair: A return short of one replacement per passage cannot be placed.
147
149
  - **`unmatched-return`**: The return contained a different number of passages than the fence sent, so the caller could place none of them. Return exactly one replacement per passage, in the order the fence listed them.
148
150
 
@@ -5,6 +5,7 @@ disallowedTools: Edit, NotebookEdit, Task, Write
5
5
  rulebooks:
6
6
  - accessibility-conventions
7
7
  - ui-copy-conventions
8
+ - visual-design-conventions
8
9
  ---
9
10
 
10
11
  # Usability assessor
@@ -40,7 +41,7 @@ The brief marks each target read-only or writable, and the mark is absolute. You
40
41
 
41
42
  **Steps.** A flow is the routes and the controls in order.
42
43
 
43
- **On each screen**, also look for: an error that does not say what to do next, an empty state without a next step, an action without feedback or undo, a name or a style that changes between screens, a link that leads nowhere, a state conveyed by colour or an icon alone, a list in which the reader must read each row to find a state for which the reader scans, such as expired or failing, a button outside a toolbar that does not look like a button at rest, and text that fails the floors in the accessibility conventions or the rules in the UI copy conventions.
44
+ **On each screen**, also look for: an error that does not say what to do next, an empty state without a next step, an action without feedback or undo, a name or a style that changes between screens, a link that leads nowhere, a state conveyed by colour or an icon alone, a list in which the reader must read each row to find a state for which the reader scans, such as expired or failing, a button outside a toolbar that does not look like a button at rest, an action whose consequence is not evident from its label and is not explained at the control, text that touches the edge of a bordered or filled container, a block aligned with nothing, marks on most of a text, a link, navigation item, button, or tag that does not look like its role, a view that lacks the product's name or home link, a placeholder favicon, and text that fails the floors in the accessibility conventions or the rules in the UI copy conventions.
44
45
 
45
46
  **Evidence.** Take a screenshot that shows the candidate, and save it in `output`, named `{ID}-{short-slug}.png`. Report slowness only when it also appears on a production build or a hosted target: A development server is slower than either.
46
47
 
@@ -66,7 +67,7 @@ Each invocation is a process, so there is nothing to reset before you return.
66
67
 
67
68
  **On each output**, also look for: an error that does not say what to do next; an exit code that disagrees with the text; a command that writes nothing and says nothing; a flag that help lists and the command rejects; a name that changes between help, output, and the docs; a documented path, topic, or file that does not exist; a state conveyed by colour or emoji alone; and text that fails the rules in the UI copy conventions or the output checks below.
68
69
 
69
- **Output checks.** These replace the floors in the accessibility conventions, which do not apply to a terminal:
70
+ **Output checks.** These replace the floors in the accessibility and visual-design conventions, which do not apply to a terminal:
70
71
 
71
72
  - The output is legible under plain style and when piped.
72
73
  - Meaning is never conveyed by colour or emoji alone.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "codeassembly-guidance",
3
- "version": "0.7.0",
3
+ "version": "0.8.0",
4
4
  "description": "The CodeAssembly library of agent guidance: rulebooks, skills, and subagents that the codeassembly CLI deploys",
5
5
  "keywords": [
6
6
  "agents",
@@ -40,22 +40,23 @@
40
40
  "schemas"
41
41
  ],
42
42
  "devDependencies": {
43
- "@hyperjump/json-schema": "1.18.0",
43
+ "@hyperjump/json-schema": "1.18.1",
44
44
  "@types/node": "24.19.2",
45
45
  "@williamthorsen/change-grammar": "0.4.1",
46
46
  "@williamthorsen/kb": "0.12.0",
47
- "@williamthorsen/nmr": "2.2.1",
48
- "@williamthorsen/toolbelt.errors": "0.10.1",
49
- "@williamthorsen/toolbelt.terminal": "0.3.1",
50
- "@williamthorsen/toolbelt.testing": "0.8.3",
51
- "@williamthorsen/toolbelt.vitest": "0.13.5",
52
- "codeassembly": "0.20.2",
47
+ "@williamthorsen/nmr": "2.3.0",
48
+ "@williamthorsen/toolbelt.errors": "0.11.3",
49
+ "@williamthorsen/toolbelt.terminal": "0.3.2",
50
+ "@williamthorsen/toolbelt.testing": "0.8.7",
51
+ "@williamthorsen/toolbelt.vitest": "0.13.8",
52
+ "codeassembly": "0.21.0",
53
53
  "esbuild": "0.28.2",
54
- "eslint": "10.14.0",
54
+ "eslint": "10.15.0",
55
55
  "happy-dom": "21.0.4",
56
+ "marked": "18.2.1",
56
57
  "marklassian": "1.2.1",
57
58
  "ulid": "3.0.2",
58
- "vitest": "5.1.0",
59
+ "vitest": "5.1.1",
59
60
  "yaml": "2.9.1",
60
61
  "zod": "4.6.7"
61
62
  },
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "$schema": "https://json-schema.org/draft/2020-12/schema",
3
- "$id": "https://unpkg.com/codeassembly-guidance@0.7.0/schemas/preferences.v1.json",
3
+ "$id": "https://unpkg.com/codeassembly-guidance@0.8.0/schemas/preferences.v1.json",
4
4
  "title": "Preferences",
5
5
  "description": "Configuration read by agent skills. Resolved from .agents/preferences.yaml at the project level, with ~/.agents/preferences.yaml as a global fallback.",
6
6
  "type": "object",
@@ -87,6 +87,14 @@
87
87
  "project_key": {
88
88
  "type": "string",
89
89
  "description": "Key of the Jira project to create work items in (e.g., `MAC`). Overrides the key derived from `project.ticket_ref_prefix` minus its trailing separator."
90
+ },
91
+ "subtask_issue_type": {
92
+ "type": "string",
93
+ "description": "Jira issue-type name of a work item that `create-ticket` creates under a level-0 parent, such as a `Task`, under which Jira accepts only a subtask (e.g., `Subtask`, or `Sub-task` on older sites). Overrides the `Subtask` default; the work type does not apply."
94
+ },
95
+ "umbrella_issue_type": {
96
+ "type": "string",
97
+ "description": "Jira issue-type name of an umbrella, a work item that `create-ticket --umbrella` creates for its children to be parented to (e.g., `Epic`). Overrides the `Epic` default; the work type does not apply."
90
98
  }
91
99
  },
92
100
  "required": [
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "$schema": "https://json-schema.org/draft/2020-12/schema",
3
- "$id": "https://unpkg.com/codeassembly-guidance@0.7.0/schemas/work-types.v1.json",
3
+ "$id": "https://unpkg.com/codeassembly-guidance@0.8.0/schemas/work-types.v1.json",
4
4
  "additionalProperties": false,
5
5
  "description": "Canonical work-types taxonomy consumed by skill content and downstream changelog/release-notes tooling. Defines the work-type vocabulary, tier grouping, breaking-change policy, changelog-eligibility flags, and cross-cutting section markers (e.g., the breaking-changes indicator).",
6
6
  "properties": {