codeassembly-guidance 0.0.0 โ†’ 0.2.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 (219) hide show
  1. package/.meta/changelog.json +1320 -0
  2. package/CHANGELOG.md +315 -0
  3. package/LICENSE +7 -0
  4. package/README.md +195 -1
  5. package/bin/codeassembly-validate-preferences.js +18 -0
  6. package/content/_partials/README.md +192 -0
  7. package/content/_partials/code-descriptions.md +4 -0
  8. package/content/_partials/code-style.md +7 -0
  9. package/content/_partials/comment-discipline.md +89 -0
  10. package/content/_partials/concision.md +3 -0
  11. package/content/_partials/diff-audit-checklist.md +9 -0
  12. package/content/_partials/file-access.md +4 -0
  13. package/content/_partials/live-repo-writes.md +13 -0
  14. package/content/_partials/plain-speech-calibration.md +70 -0
  15. package/content/_partials/plain-speech.md +13 -0
  16. package/content/_partials/prose-line-breaks.md +3 -0
  17. package/content/_partials/record-marker.md +1 -0
  18. package/content/_partials/reduced-object-relative.md +28 -0
  19. package/content/_partials/shell-commands.md +3 -0
  20. package/content/_partials/target-file-set-resolution.md +22 -0
  21. package/content/_partials/technical-recommendations.md +6 -0
  22. package/content/_partials/test-structure-audit-checklist.md +7 -0
  23. package/content/_partials/ticket-assessment-baseline.md +12 -0
  24. package/content/_partials/ticket-assessment.md +202 -0
  25. package/content/_partials/work-type-choice.md +13 -0
  26. package/content/codeassembly-content.yaml +59 -0
  27. package/content/collections/all.md +11 -0
  28. package/content/collections/atlassian.md +17 -0
  29. package/content/collections/recommended.md +41 -0
  30. package/content/collections/triage.md +13 -0
  31. package/content/collections/williamthorsen.md +26 -0
  32. package/content/guidance/README.md +22 -0
  33. package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
  34. package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
  35. package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
  36. package/content/guidance/rulebooks/accessibility-conventions.md +38 -0
  37. package/content/guidance/rulebooks/cli-conventions.md +192 -0
  38. package/content/guidance/rulebooks/codeassembly-content-specification.md +184 -0
  39. package/content/guidance/rulebooks/command-output-conventions.md +14 -0
  40. package/content/guidance/rulebooks/commit-conventions.md +72 -0
  41. package/content/guidance/rulebooks/generated-content-policy.md +10 -0
  42. package/content/guidance/rulebooks/live-worktree-policy.md +19 -0
  43. package/content/guidance/rulebooks/readme-conventions.md +74 -0
  44. package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
  45. package/content/guidance/rulebooks/shell-conventions.md +273 -0
  46. package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
  47. package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
  48. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +60 -0
  49. package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
  50. package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
  51. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
  52. package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
  53. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
  54. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
  55. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
  56. package/content/guidance/shared/AGENTS.md +51 -0
  57. package/content/scripts/README.md +44 -0
  58. package/content/scripts/check-branch-currency.mjs +11 -0
  59. package/content/scripts/check-prose.mjs +171 -0
  60. package/content/scripts/describe-change.mjs +165 -0
  61. package/content/scripts/get-ticket-id.sh +131 -0
  62. package/content/scripts/manage-jira-ticket.mjs +214 -0
  63. package/content/scripts/resolve-frontmatter.sh +540 -0
  64. package/content/scripts/resolve-review-run.mjs +12 -0
  65. package/content/scripts/select-lede-exemplars.mjs +208 -0
  66. package/content/scripts/validate-preferences.mjs +146 -0
  67. package/content/skills/_data/action-items.md +83 -0
  68. package/content/skills/_data/artifact-conventions.md +1001 -0
  69. package/content/skills/_data/bitbucket-pr-access.md +89 -0
  70. package/content/skills/_data/branch-currency.md +36 -0
  71. package/content/skills/_data/branch-format.md +34 -0
  72. package/content/skills/_data/change-record.md +163 -0
  73. package/content/skills/_data/complexity-classification.md +58 -0
  74. package/content/skills/_data/concision.md +23 -0
  75. package/content/skills/_data/deployed-file-provenance.md +46 -0
  76. package/content/skills/_data/design-priorities.md +76 -0
  77. package/content/skills/_data/gh-body-file.md +30 -0
  78. package/content/skills/_data/git-commands.md +39 -0
  79. package/content/skills/_data/naming-conventions.md +50 -0
  80. package/content/skills/_data/pr-resolution.md +25 -0
  81. package/content/skills/_data/pr-source-resolution.md +36 -0
  82. package/content/skills/_data/project-stage.md +32 -0
  83. package/content/skills/_data/recommendation-gradient.md +92 -0
  84. package/content/skills/_data/scope-and-deferral.md +83 -0
  85. package/content/skills/_data/spike-conventions.md +89 -0
  86. package/content/skills/_data/ticket-evaluation.md +13 -0
  87. package/content/skills/_data/ticket-id-extraction.md +43 -0
  88. package/content/skills/_data/ticket-source-resolution.md +180 -0
  89. package/content/skills/_data/title-templates.md +632 -0
  90. package/content/skills/_data/title-voice.md +17 -0
  91. package/content/skills/_data/work-types.json +168 -0
  92. package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
  93. package/content/skills/_partials/action-items.md +22 -0
  94. package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
  95. package/content/skills/_partials/commit-title-rendering.md +14 -0
  96. package/content/skills/_partials/gh-body-file.md +22 -0
  97. package/content/skills/_partials/jira-task-list-flattening.md +1 -0
  98. package/content/skills/_partials/nested-list-indent.md +9 -0
  99. package/content/skills/_partials/next-steps-after-plan.md +99 -0
  100. package/content/skills/_partials/next-steps-after-review.md +350 -0
  101. package/content/skills/_partials/option-format.md +85 -0
  102. package/content/skills/_partials/plan-template.md +97 -0
  103. package/content/skills/_partials/split-launch-prompts.md +5 -0
  104. package/content/skills/_partials/split-ticket-compose.md +5 -0
  105. package/content/skills/_partials/split-ticket-create.md +3 -0
  106. package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
  107. package/content/skills/_partials/ticket-concision.md +18 -0
  108. package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
  109. package/content/skills/_partials/ticket-placement.md +14 -0
  110. package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
  111. package/content/skills/_partials/ticket-skeleton.md +13 -0
  112. package/content/skills/add-change-record/SKILL.md +136 -0
  113. package/content/skills/add-test-ids/SKILL.md +51 -0
  114. package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
  115. package/content/skills/anti-patterns/SKILL.md +57 -0
  116. package/content/skills/assess-ticket/SKILL.md +46 -0
  117. package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
  118. package/content/skills/assess-usability/SKILL.md +96 -0
  119. package/content/skills/brainstorming/SKILL.md +107 -0
  120. package/content/skills/capture-event/SKILL.md +108 -0
  121. package/content/skills/capture-event/capture-event.mjs +216 -0
  122. package/content/skills/capture-feedback/SKILL.md +71 -0
  123. package/content/skills/capture-lede-decision/SKILL.md +163 -0
  124. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
  125. package/content/skills/classify-complexity/SKILL.md +92 -0
  126. package/content/skills/collaborate/SKILL.md +86 -0
  127. package/content/skills/condense-branch/SKILL.md +83 -0
  128. package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
  129. package/content/skills/create-commit/SKILL.md +65 -0
  130. package/content/skills/create-devlog/SKILL.md +108 -0
  131. package/content/skills/create-gh-pr/SKILL.md +121 -0
  132. package/content/skills/create-pr/SKILL.md +150 -0
  133. package/content/skills/create-ticket/SKILL.md +395 -0
  134. package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
  135. package/content/skills/derive-session-context/derive-session-context.mjs +149 -0
  136. package/content/skills/design-and-plan/SKILL.md +197 -0
  137. package/content/skills/development-workflows/SKILL.md +41 -0
  138. package/content/skills/get-ticket-id/SKILL.md +67 -0
  139. package/content/skills/groom-backlog/SKILL.md +247 -0
  140. package/content/skills/groom-backlog/groom-backlog.mjs +108 -0
  141. package/content/skills/implement-plan/SKILL.md +168 -0
  142. package/content/skills/index-prototypes/SKILL.md +200 -0
  143. package/content/skills/index-prototypes/index-prototypes.mjs +388 -0
  144. package/content/skills/kb-add/SKILL.md +157 -0
  145. package/content/skills/kb-add/kb-add.mjs +216 -0
  146. package/content/skills/kb-curate/SKILL.md +119 -0
  147. package/content/skills/kb-curate/kb-curate.mjs +213 -0
  148. package/content/skills/kb-edit/SKILL.md +128 -0
  149. package/content/skills/kb-edit/kb-edit.mjs +219 -0
  150. package/content/skills/kb-retrieve/SKILL.md +100 -0
  151. package/content/skills/kb-retrieve/kb-retrieve.mjs +207 -0
  152. package/content/skills/kb-retrieve-events/SKILL.md +98 -0
  153. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +207 -0
  154. package/content/skills/kb-update-events/SKILL.md +77 -0
  155. package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
  156. package/content/skills/merge-bb-pr/SKILL.md +136 -0
  157. package/content/skills/merge-gh-pr/SKILL.md +167 -0
  158. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
  159. package/content/skills/merge-pr/SKILL.md +368 -0
  160. package/content/skills/migrate-feedback-memories/SKILL.md +137 -0
  161. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
  162. package/content/skills/people-report/SKILL.md +208 -0
  163. package/content/skills/plan/SKILL.md +87 -0
  164. package/content/skills/prepare-prototype-brief/SKILL.md +178 -0
  165. package/content/skills/pull-from-backlog/SKILL.md +83 -0
  166. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +209 -0
  167. package/content/skills/refine-plan/SKILL.md +263 -0
  168. package/content/skills/refine-prototype/SKILL.md +113 -0
  169. package/content/skills/respond-to-review/SKILL.md +292 -0
  170. package/content/skills/review-bb-pr/SKILL.md +161 -0
  171. package/content/skills/review-branch/SKILL.md +303 -0
  172. package/content/skills/review-criteria/SKILL.md +141 -0
  173. package/content/skills/review-gh-pr/SKILL.md +155 -0
  174. package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
  175. package/content/skills/review-permissions/SKILL.md +39 -0
  176. package/content/skills/review-pr/SKILL.md +123 -0
  177. package/content/skills/revise-comments/SKILL.md +148 -0
  178. package/content/skills/revise-prose/SKILL.md +197 -0
  179. package/content/skills/revise-prose/revise-prose.mjs +229 -0
  180. package/content/skills/save-artifact/SKILL.md +71 -0
  181. package/content/skills/save-plan/SKILL.md +55 -0
  182. package/content/skills/software-engineering/SKILL.md +74 -0
  183. package/content/skills/streamline-guidance/SKILL.md +174 -0
  184. package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
  185. package/content/skills/summarize-change/SKILL.md +317 -0
  186. package/content/skills/summarize-chat/SKILL.md +100 -0
  187. package/content/skills/systematic-debugging/SKILL.md +308 -0
  188. package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
  189. package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
  190. package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
  191. package/content/skills/systematic-debugging/find-polluter.sh +68 -0
  192. package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
  193. package/content/skills/systematic-debugging/test-academic.md +16 -0
  194. package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
  195. package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
  196. package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
  197. package/content/skills/testing-conventions/SKILL.md +235 -0
  198. package/content/skills/triage-spike-findings/SKILL.md +113 -0
  199. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +71 -0
  200. package/content/skills/typescript-testing-conventions/SKILL.md +178 -0
  201. package/content/skills/update-jira-ticket/SKILL.md +257 -0
  202. package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
  203. package/content/skills/update-project-guidance/SKILL.md +300 -0
  204. package/content/skills/upgrade-dependencies/SKILL.md +139 -0
  205. package/content/skills/wrap-up/SKILL.md +431 -0
  206. package/content/subagents/_data/claude.yaml +25 -0
  207. package/content/subagents/_data/rovo.yaml +41 -0
  208. package/content/subagents/canary.md +12 -0
  209. package/content/subagents/disposition-challenger.md +78 -0
  210. package/content/subagents/entry-drafter.md +191 -0
  211. package/content/subagents/handoff-reviewer.md +75 -0
  212. package/content/subagents/plan-reviewer.md +184 -0
  213. package/content/subagents/plan-reviser.md +88 -0
  214. package/content/subagents/prose-reviser.md +132 -0
  215. package/content/subagents/ticket-assessor.md +142 -0
  216. package/content/subagents/usability-assessor.md +157 -0
  217. package/package.json +74 -2
  218. package/schemas/preferences.v1.json +321 -0
  219. package/schemas/work-types.v1.json +142 -0
@@ -0,0 +1,17 @@
1
+ # The title
2
+
3
+ These rules govern the text of a title: the string that an author composes for a ticket, a commit, a pull request, or a squash merge. [`title-templates.md`](./title-templates.md) states how that string is rendered on each surface.
4
+
5
+ The rules apply to both authored strings: the ticket string, which becomes the issue title, and the change string, which becomes the commit, pull-request, and squash-merge title.
6
+
7
+ - **72 characters, hard.** Count the authored string, not a rendering of it. The bound is a maximum, not a length to aim for.
8
+ - **Imperative, task-oriented.** The verb names the task: "Addโ€ฆ", "Fixโ€ฆ", "Preventโ€ฆ", "Enableโ€ฆ", not "Addsโ€ฆ". A title states the task, not the topic: "Enable playback at different speeds", not "Different playback speeds".
9
+ - **The bug-ticket exception.** A bug's ticket string states the symptom, declaratively; its change string still states the fix.
10
+ - Ticket: Playback stutters at speeds higher than 32x
11
+ - Change: Fix playback stutter at speeds higher than 32x
12
+ - **The subject, not the occasion.** A change string names what the diff does; a ticket string names the work wanted, or the symptom of a bug. Neither names the review, the meeting, or the conversation that raised it: never "Address review findings" or "Apply feedback".
13
+ - **Specific over categorical.** "Disambiguate phase name mismatch between agents and factory layers", not "Phase name disambiguation".
14
+ - **No jargon.** Use plain speech and the project's own vocabulary. Never use a term coined to describe the change.
15
+ - **No ephemeral references.** The title must make sense to a reader who has only a `git log`: no ticket ID, pull-request number, review-finding ID, or run identifier. It does not contain a ticket reference; a template adds one to any surface that shows it.
16
+ - **No backticks.** Write an identifier bare: "Add listConsoleLines to toolbelt.vitest". In a body, backtick identifiers as usual.
17
+ - **No external actions.** Neither string mentions an action such as updating a ticket or sending a notification.
@@ -0,0 +1,168 @@
1
+ {
2
+ "markers": {
3
+ "breaking": {
4
+ "emoji": "๐Ÿšจ",
5
+ "label": "Breaking"
6
+ }
7
+ },
8
+ "tiers": [
9
+ "public",
10
+ "internal",
11
+ "process"
12
+ ],
13
+ "types": [
14
+ {
15
+ "aliases": [
16
+ "feature"
17
+ ],
18
+ "breakingPolicy": "optional",
19
+ "description": "A change that gives consumers a new capability or extends an existing one.",
20
+ "emoji": "๐ŸŽ‰",
21
+ "key": "feat",
22
+ "label": "Features",
23
+ "tier": "public"
24
+ },
25
+ {
26
+ "aliases": [],
27
+ "breakingPolicy": "optional",
28
+ "description": "A change that removes a capability or surface on which consumers depend.",
29
+ "emoji": "๐Ÿชฆ",
30
+ "key": "drop",
31
+ "label": "Removed",
32
+ "tier": "public"
33
+ },
34
+ {
35
+ "aliases": [],
36
+ "breakingPolicy": "forbidden",
37
+ "description": "A change that marks a capability or surface for removal while the capability or surface keeps working.",
38
+ "emoji": "๐Ÿ—‘๏ธ",
39
+ "key": "deprecate",
40
+ "label": "Deprecated",
41
+ "tier": "public"
42
+ },
43
+ {
44
+ "aliases": [
45
+ "bugfix"
46
+ ],
47
+ "breakingPolicy": "optional",
48
+ "description": "A change that corrects behavior that consumers meet and that differs from what was intended.",
49
+ "emoji": "๐Ÿ›",
50
+ "key": "fix",
51
+ "label": "Bug fixes",
52
+ "tier": "public"
53
+ },
54
+ {
55
+ "aliases": [
56
+ "security"
57
+ ],
58
+ "breakingPolicy": "optional",
59
+ "description": "A change that closes a vulnerability or hardens a consumer-facing surface against attack.",
60
+ "emoji": "๐Ÿ”’",
61
+ "key": "sec",
62
+ "label": "Security",
63
+ "tier": "public"
64
+ },
65
+ {
66
+ "aliases": [
67
+ "performance"
68
+ ],
69
+ "breakingPolicy": "optional",
70
+ "description": "A change that reduces the time, memory, or other resources that consumer-facing work uses, without changing its result.",
71
+ "emoji": "โšก",
72
+ "key": "perf",
73
+ "label": "Performance",
74
+ "tier": "public"
75
+ },
76
+ {
77
+ "aliases": [
78
+ "utility"
79
+ ],
80
+ "breakingPolicy": "forbidden",
81
+ "description": "A change that adds, extends, or repairs a capability that consumers do not use directly, such as a helper or an internal module.",
82
+ "emoji": "๐Ÿ—๏ธ",
83
+ "key": "internal",
84
+ "label": "Internal features",
85
+ "tier": "internal"
86
+ },
87
+ {
88
+ "aliases": [],
89
+ "breakingPolicy": "forbidden",
90
+ "description": "A change that restructures existing code without changing its behavior.",
91
+ "emoji": "โ™ป๏ธ",
92
+ "key": "refactor",
93
+ "label": "Refactoring",
94
+ "tier": "internal"
95
+ },
96
+ {
97
+ "aliases": [
98
+ "test"
99
+ ],
100
+ "breakingPolicy": "forbidden",
101
+ "description": "A change confined to tests, test fixtures, or test helpers, including one that unblocks a build or a type check.",
102
+ "emoji": "๐Ÿงช",
103
+ "key": "tests",
104
+ "label": "Tests",
105
+ "tier": "internal"
106
+ },
107
+ {
108
+ "aliases": [],
109
+ "breakingPolicy": "forbidden",
110
+ "description": "A change to the tools used to develop the project: build, lint, formatting, and release configuration, and development scripts.",
111
+ "emoji": "โš™๏ธ",
112
+ "key": "tooling",
113
+ "label": "Tooling",
114
+ "tier": "process"
115
+ },
116
+ {
117
+ "aliases": [],
118
+ "breakingPolicy": "forbidden",
119
+ "description": "A change to continuous-integration workflows and their configuration.",
120
+ "emoji": "๐Ÿ‘ท",
121
+ "key": "ci",
122
+ "label": "CI",
123
+ "tier": "process"
124
+ },
125
+ {
126
+ "aliases": [
127
+ "dep"
128
+ ],
129
+ "breakingPolicy": "forbidden",
130
+ "description": "A change that adds, removes, or upgrades a dependency, including its lockfile and version-catalog entries.",
131
+ "emoji": "๐Ÿ“ฆ",
132
+ "key": "deps",
133
+ "label": "Dependencies",
134
+ "tier": "process"
135
+ },
136
+ {
137
+ "aliases": [],
138
+ "breakingPolicy": "forbidden",
139
+ "description": "A change to guidance on working in the repository itself, such as its `AGENTS.md` or a repo-local skill, or to the repository's agent configuration.",
140
+ "emoji": "๐Ÿค–",
141
+ "key": "ai",
142
+ "label": "Agentic support",
143
+ "tier": "process"
144
+ },
145
+ {
146
+ "aliases": [
147
+ "doc"
148
+ ],
149
+ "breakingPolicy": "forbidden",
150
+ "description": "A change to documentation for human readers, such as a README, a guide, or a code comment.",
151
+ "emoji": "๐Ÿ“š",
152
+ "key": "docs",
153
+ "label": "Documentation",
154
+ "tier": "process"
155
+ },
156
+ {
157
+ "aliases": [],
158
+ "breakingPolicy": "forbidden",
159
+ "description": "A change to formatting alone, such as whitespace or line wrapping, that leaves the content unchanged.",
160
+ "emoji": "๐ŸŽจ",
161
+ "excludedFromChangelog": true,
162
+ "key": "fmt",
163
+ "label": "Formatting",
164
+ "tier": "process"
165
+ }
166
+ ],
167
+ "version": "1.3.0"
168
+ }
@@ -0,0 +1,15 @@
1
+ ## Acceptance criteria
2
+
3
+ Include only the tiers that have criteria. Omit any empty tier; do not emit a "Should have" or "Nice to have" header with nothing under it.
4
+
5
+ ### Must have
6
+
7
+ - [ ] {Critical requirement}
8
+
9
+ ### Should have
10
+
11
+ - [ ] {Important but not blocking}
12
+
13
+ ### Nice to have
14
+
15
+ - [ ] {Optional enhancement}
@@ -0,0 +1,22 @@
1
+ **Close the turn with an action-items block.** Before sending, sweep the draft for anything that invites a response: A soft offer ("let me know if", "say the word and I will", "worth knowing", "I can also") is an ask, and leaving it in the narrative is how asks get missed. Run a check that a command, a test, or a browser could settle rather than ask for it; a command for the developer to run is a handoff. Prose may discuss; only the block may ask. Move every ask into one labelled block at the end of the response, stated as the concrete action and punctuated as the question that it is. Do not add a block to a turn without an ask. When this skill defines its own canonical block for asks (a next-steps menu, an action menu, a finding-keyed question list), use that block: Add the ad-hoc ask to it, keeping the block's own identifiers, and never close a turn with two competing blocks.
2
+
3
+ Prefix with `A` an action that you propose to take (a "yes" makes you act) and with `Q` information or a judgment that you need (a "yes" only informs you). Number each so that the user can answer the whole block in one line. Leave a non-ask, such as a status note, in the prose without a prefix, and keep each prefix in agreement with its marker. Do not prefix the item of a single-item block.
4
+
5
+ ```
6
+ ---
7
+
8
+ **Action items**
9
+
10
+ **A1:** Add the packaging note to #977? ๐Ÿ‘๐Ÿผ๐Ÿ‘Ž๐Ÿผ
11
+
12
+ **A2:** The fixture helper now has three call sites. Extract, or leave inline?
13
+
14
+ 1. โ– โ– โ–ก Extract it into `test-utils/`:
15
+ - โž• the third call site copy-pasted a stale variant, which is how the leak got in
16
+ 2. โ– โ– โ–ก Leave it inline until #981 settles the fixture format:
17
+ - โž• #981 changes every fixture's shape, so an extracted helper would be rewritten within the week
18
+
19
+ **Q1:** Which package owns the shared fixture once it moves? ๐Ÿค”
20
+ ```
21
+
22
+ When the block presents more than one independently-numbered list (a next-steps menu with two or more selects), put each list's identifier as a bold prefix on its header (`**A1: Remote issue**`) and keep each list's own 1-based numbering, so a bare numeral always names an option and `A1: 1, A2: 3` answers the block. A single-list block does not need that prefix.
@@ -0,0 +1,3 @@
1
+ ```
2
+ Bitbucket cannot delete a local branch as part of a merge; Bitbucket does not have a counterpart to `--delete both`. Re-run with `--delete remote` and remove the local branch yourself.
3
+ ```
@@ -0,0 +1,14 @@
1
+ ```bash
2
+ node {harness_home_dir}/scripts/describe-change.mjs render-titles \
3
+ --title "{title}" \
4
+ --scope "{scope}" \
5
+ --type "{type}" \
6
+ --ticket-ref "{ticket_ref}" \
7
+ | python3 -c "import sys,json; print(json.load(sys.stdin).get('commit_title',''))"
8
+ ```
9
+
10
+ Pass `--ticket-ref` from the bundled session-context deriver so that a project whose `commit.title_format` references `{ticket_ref}` renders the ref. Omit any flag whose value is empty or null, `--ticket-ref` included when session context reports it as `null`.
11
+
12
+ Parse the output with a JSON parser (`python3` above; `jq -r '.commit_title'` if `jq` is available) rather than `grep` or `cut`: A rendered title may contain backslash-escaped double quotes, which a regex extractor silently truncates.
13
+
14
+ The pipeline prints the rendered title. Read it from the command's output and use it verbatim as the commit title, which already contains the rendered prefix, per the configured `commit.title_format`, and the bare title text. Assigning the parse instead prints nothing, and a shell variable does not survive to the commit call, so copy the title as literal text into the message file. If the script is not found, fall back to the bare `{title}`.
@@ -0,0 +1,22 @@
1
+ ## gh body file
2
+
3
+ Pass composed content to a CLI through a file, never through the shell. This governs every command that takes composed content, such as a Markdown body, a commit message, or a JSON or YAML payload; `git commit`, `gh pr create`, `gh issue comment`, and `acli jira workitem create` are examples. The shell damages composed content in two ways. A double-quoted argument has its backticks and `$(โ€ฆ)` expanded, and the shell runs what the message only meant to quote. A single-quoted argument cannot hold an apostrophe, and an agent drops the character rather than escape it, which leaves text that still parses and reads wrong.
4
+
5
+ **Resolve the scratch directory; never reference it.** Create one with `mktemp -d "${TMPDIR:-/tmp}/gh-body.XXXXXX"` in a Bash call and use the absolute path that call prints; bare `mktemp -d` picks a path denied by the agent sandbox. Because the {tool:Write} tool does not perform shell expansion, a path containing `$TMPDIR` handed to it creates a directory named `$TMPDIR`.
6
+
7
+ **Name the file for its consumer.** `gh-body-pr123-{timestamp}.md`, `gh-body-issue456-{timestamp}.md`, `gh-body-insight2-{timestamp}.md`, with `{timestamp}` in `YYYYMMDD-HHMMSSZ` format. A body written for a different target is then visibly not this one's, and a loop does not need a separate collision rule.
8
+
9
+ **Assign the path and guard it inside the call that consumes it.** Nothing survives a Bash invocation: neither `$TMPDIR`, whose value changes between calls, nor a variable set by an earlier call. Every invocation that passes a body file opens with the assignment and refuses on a missing or empty file.
10
+
11
+ ```bash
12
+ body_path="{absolute path from the write step}"
13
+ [ -s "$body_path" ] || { echo "Body file missing or empty: $body_path" >&2; exit 1; }
14
+ ```
15
+
16
+ The guard makes the failure loud. `gh` accepts `--body-file ""` without complaint and publishes its own default body in place of the composed one, and given an empty file it publishes an empty body just as quietly. An unset variable fails `[ -s ]`, so the refusal holds even when the assignment is dropped.
17
+
18
+ A retry re-states the assignment rather than inheriting it. The file is the same file; only the handoff is re-done.
19
+
20
+ A bundled helper that refuses a missing or empty file itself takes the literal absolute path, unquoted, without the assignment or the guard. The skill that invokes such a helper says so at the call.
21
+
22
+ Why a file rather than the shell, and why the path is re-stated at every call: [gh body file](../_data/gh-body-file.md).
@@ -0,0 +1 @@
1
+ **Flatten task lists for Markdown and HTML clients.** Before submitting a Jira description or comment through a `contentFormat` tool or an HTML tool, on creation and update alike, convert task-list syntax (`- [ ]` / `- [x]`) to plain `-` bullets. Neither Jira conversion maps it to task items: The brackets are escaped, so each line persists as a bullet reading `\[ \] ...`. The `acli` path is the exception and keeps its checkboxes, because `manage-jira-ticket.mjs` converts task-list syntax to native `taskList` / `taskItem` nodes.
@@ -0,0 +1,9 @@
1
+ **Indent a nested list item 4 spaces.** Bitbucket Cloud reads a 2-space indent as a sibling of its parent rather than a child, and reports nothing: The list flattens, and the only way to notice is to view the published text. GitHub accepts either width, so 4 spaces renders as intended on both.
2
+
3
+ ```
4
+ - parent
5
+ - child
6
+ - grandchild
7
+ ```
8
+
9
+ This rule governs text composed for a rendering surface: a pull-request description, a merge-commit body, a comment. It does not govern Markdown inside the repository, where the formatter in use sets the indent: Prettier normalizes a nested item to its parent's content column.
@@ -0,0 +1,99 @@
1
+ ## Next-steps options
2
+
3
+ ### Options
4
+
5
+ | # | Emoji | Option | Description |
6
+ | --- | ----- | ---------------- | --------------------------------------------------------------- |
7
+ | 1 | ๐Ÿง  | Refine plan | Review the plan for completeness and correctness |
8
+ | 2 | โœ‚๏ธ | Split the ticket | Cut the plan at a seam into tickets that each ship on their own |
9
+ | 3 | ๐Ÿš€ | Implement | Work the plan's tasks, then choose a review pass |
10
+
11
+ ### Output format
12
+
13
+ Present all three options as a numbered list per [option format](#option-format). Each option has a strength marker (โ– โ– โ– /โ– โ– โ–ก/โ– โ–กโ–ก/โ–กโ–กโ–ก); the recommendation rules below determine which option takes the strongest marker. Pros and cons are omitted by default; add a `โž•` or `โž–` line only when the specific plan presents a tradeoff that survives the option-format tests bearing on which option fits (e.g., "the schema change ships and is verifiable before the reader that consumes it," "every task follows the sibling table's established pattern"). Generic option properties ("structured review pass," "longer wall time") are noise and must be omitted. Include all known paths (plan, ticket) in each option line; omit paths that are not available in the current context. Use `~/`-relative paths when possible and absolute paths otherwise. Every line subordinate to an option (invocation guidance as much as a pro or con) is a nested list item, never a whitespace-indented continuation.
14
+
15
+ **The ticket and plan are the complete handoff.** Every option assumes that a fresh session acts on the saved artifacts alone, whether or not one does, so nothing that only this session knows distinguishes one option from another. A pro or con never cites the conversation, session-held context, or what is "already in context", and neither does the invocation guidance of any option, the spike's ๐Ÿ”ฌ Investigate included. When a fact that an option needs exists only in the session, the artifact is incomplete: Add the fact to the ticket or the plan before rendering the menu, rather than citing the session.
16
+
17
+ **One `โž•` line is mandatory rather than omitted.** When Refine plan is the selected option, it must include a `โž•` line naming the specific unsettled decision that the pass would raise (rule 1). The line names an open decision, never a reassurance about work already done: "a refine pass is the cheap way to find out whether I missed something" is the shape that this requirement exists to forbid. When Split the ticket is the selected option, it must include a `โž•` line naming the plan's size and the pieces (rule 2). Selecting either without its line is a defect: If the line cannot be written, the rule did not match and the cascade continues.
18
+
19
+ **Spike plans.** A spike plan has `## Investigation steps` rather than `## Tasks` (see [spike conventions](../_data/spike-conventions.md)). It is carried out to produce findings rather than implemented to produce a diff, and `implement-plan` reads only the feature shape. Render option 3 as ๐Ÿ”ฌ Investigate, without invoking a skill; the agent works the investigation steps directly. Option 1 renders unchanged. Option 2 renders at โ–กโ–กโ–ก with the `โž–` that a spike produces findings rather than pieces that ship. In the recommendation rules below, rule 2 never matches on a spike plan, so Investigate is the fallthrough whenever rule 1 does not match.
20
+
21
+ Options that invoke a skill include context-clearing guidance:
22
+
23
+ - **Refine plan**: Prepend "Clear context, then..." because the plan artifact is self-contained; prior conversation wastes tokens and can introduce bias.
24
+ - **Split the ticket**: No "Clear context" prefix, and no pasted invocation line; the split runs in this session because the library doesn't have a skill for it, and it cuts the pieces from the saved plan. See [Splitting the ticket](#splitting-the-ticket).
25
+ - **Implement**: No "Clear context" prefix. The ticket and plan are self-contained, so `implement-plan` works the same in this session or in a fresh one, and clearing gains nothing: Unlike a refine or review pass, implementation is not harmed by sharing the planner's view. The user can also paste the same line into a fresh session, or into the other harness with its own skill sigil, in which the skill re-resolves the plan and ticket from the environment.
26
+
27
+ Example (rendered for the default case, in which the recommendation rules below select Implement):
28
+
29
+ ```
30
+ Next steps:
31
+ 1. ๐Ÿง  โ– โ–กโ–ก Refine plan:
32
+ - Clear context, then {skill?:refine-plan} with plan: {plan_path}, ticket: {ticket_source}
33
+ 2. โœ‚๏ธ โ– โ–กโ–ก Split the ticket:
34
+ - Selection runs the split in this session
35
+ 3. ๐Ÿš€ โ– โ– โ–ก Implement:
36
+ - {skill?:implement-plan} with plan: {plan_path}, ticket: {ticket_source}
37
+ ```
38
+
39
+ Skill names for each option:
40
+
41
+ - ๐Ÿง  **Refine plan** -> `refine-plan`
42
+ - โœ‚๏ธ **Split the ticket** -> `{skill:create-ticket}`, once per piece, in this session
43
+ - ๐Ÿš€ **Implement** -> `implement-plan`; on a spike plan the option is ๐Ÿ”ฌ **Investigate** and does not invoke a skill
44
+
45
+ ### Recommendation rules
46
+
47
+ Select the recommended option by checking these rules in order and stopping at the first match.
48
+
49
+ 1. **Refine plan**: Recommend only when you can name a load-bearing decision that the plan leaves unsettled and that a refine pass would raise.
50
+
51
+ A decision is **unsettled** when the plan invented it and nothing has challenged it. It is **settled** when it was ratified interactively, taken from prior design work, verified against source, or copied from an established pattern already in the codebase. A `## Decisions taken` entry that survived an approval checkpoint is ratified: The developer read it and did not overrule it. The calling skill's recommendation context tells you which: A plan whose forks were challenged and ratified interactively has settled decisions, and a plan produced without a design phase is likelier to have unsettled ones.
52
+
53
+ Rule 1 also fails when the plan's residual unknowns are **empirical**, answered by running code or writing the test. A refine pass re-reads the plan and structurally cannot answer those. Only **analytical** residue, resolvable by a closer reading, counts.
54
+
55
+ "The plan might have a flaw I missed" does not satisfy the test. That is a reassurance about work already done, not an unsettled decision.
56
+
57
+ The following make a plan _more likely_ to have an unsettled decision. They are evidence to weigh, and none of them matches rule 1 on its own:
58
+ - Changes to dependency boundaries (which libraries are used, which APIs are consumed, or how they're configured)
59
+ - Changes to the shape or semantics of behavioral contracts or data structures
60
+ - Far-reaching downstream consequences
61
+ - Changes to control flow, state management, or execution order
62
+ - Introduction of new interfaces, modules, or subsystems
63
+ - A prior `refine-plan` round significantly altered the plan or expanded the scope of the changes needed to implement it
64
+
65
+ When rule 1 matches, the rendered option must name that decision on a `โž•` line. Being unable to write the line means rule 1 did not match.
66
+
67
+ 2. **Split the ticket**: Recommend only when the plan is too large for one implement-and-review pass, and it contains two or more pieces that can each be merged and verified on their own. Both halves are required: Too large without a seam is not a match, and a seam in a plan that one pass would cover is not one either.
68
+
69
+ A piece gets its own ticket when it can be merged and verified on its own, not when it looks large enough to deserve one. The `โž•` line names the size and the pieces, each with the tasks that it takes: `โž• eleven tasks across three packages, and two pieces ship on their own: the schema change (tasks 1โ€“4), then the reader that consumes it (tasks 5โ€“11)`.
70
+
71
+ Structural properties (new module boundaries, changed interfaces, several packages) make a plan _more likely_ to be too large. They are evidence to weigh, and none of them matches rule 2 on its own.
72
+
73
+ When rule 2 matches, the rendered option must name the size and the pieces on a `โž•` line. Being unable to write the line means rule 2 did not match.
74
+
75
+ 3. **Implement**: All other cases (default), whatever the number of modules or packages that the plan touches. `implement-plan`'s closing menu re-decides the review depth from the realized diff, and it offers a split when the diff proves too large for one review pass, so a plan sent here is not committed to a single pull request.
76
+
77
+ When the work is trivial enough that a review pass would catch nothing meaningful ([complexity levels 1โ€“2](../_data/complexity-classification.md): a typo fix, an unused-import removal, a single-file mechanical rename), add a `โž•` line noting that the follow-up review can be skipped at `implement-plan`'s closing menu. Because that menu decides the review from the diff that the implementation actually produced, a plan-time triviality read is a hint to it rather than a commitment.
78
+
79
+ #### Marker strengths
80
+
81
+ The selected option's marker follows how cleanly its rule matched: โ– โ– โ–  when the rule's test is met squarely and the alternatives are worse on the criteria that decided it, โ– โ– โ–ก when the fit is good but an alternative stays defensible, โ– โ–กโ–ก when little separates the options. Because rule 3 is the cascade's fallthrough rather than a positive match, its marker follows how squarely rules 1 and 2 failed: โ– โ– โ–  when neither came close, โ– โ– โ–ก when one stayed defensible. The unselected options take โ– โ–กโ–ก by default, and โ–กโ–กโ–ก when one has a clear drawback in the current context.
82
+
83
+ Each skill supplies its own recommendation context (e.g., whether the plan was developed interactively, whether a review just completed). That context applies to rule 1's settled/unsettled test.
84
+
85
+ #### Splitting the ticket
86
+
87
+ <!-- include: split-ticket-compose.md / -->
88
+
89
+ **Cut the plans.** Cut a plan per piece from the approved plan, so that each piece's session can start at Implement. Keep each piece's plan in context when its ticket is created, so that `{skill:create-ticket}` saves the plan beside the ticket artifact and posts it on the ticket.
90
+
91
+ <!-- include: split-ticket-create.md / -->
92
+
93
+ **Save the first piece's plan.** With two pieces, save the first piece's plan in the originating ticket's directory per `{skill:save-artifact}`. Its timestamp is later than the approved plan's, so `implement-plan` resolves it rather than the unsplit plan.
94
+
95
+ **Report.** Report the ticket references and the plan paths. Choose each ticket's entry point from what its artifacts settle: `{skill?:design-and-plan}` when the piece's design needs a closer look; `{skill?:plan}` when the ticket is ready but does not have a plan; `{skill?:refine-plan}` when its plan leaves a decision unsettled, by the test in rule 1 above; `{skill?:implement-plan}` otherwise, which is the default for a plan cut from an approved one.
96
+
97
+ <!-- include: split-launch-prompts.md / -->
98
+
99
+ See [`scope-and-deferral.md`](../_data/scope-and-deferral.md) for the related decision on whether a finding warrants its own ticket. That decision (do now / batch later / separate ticket) is about work that comes up alongside the plan; rule 2 is about the plan's own work, and its seam test comes from the ticketing preferences: A piece gets its own ticket when it can be merged and verified on its own.