codeassembly-guidance 0.0.0 → 0.1.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 (204) hide show
  1. package/.meta/changelog.json +563 -0
  2. package/CHANGELOG.md +134 -0
  3. package/LICENSE +7 -0
  4. package/README.md +165 -1
  5. package/content/_partials/README.md +192 -0
  6. package/content/_partials/code-descriptions.md +4 -0
  7. package/content/_partials/code-style.md +7 -0
  8. package/content/_partials/comment-discipline.md +89 -0
  9. package/content/_partials/concision.md +3 -0
  10. package/content/_partials/diff-audit-checklist.md +9 -0
  11. package/content/_partials/file-access.md +4 -0
  12. package/content/_partials/live-repo-writes.md +13 -0
  13. package/content/_partials/plain-speech-calibration.md +66 -0
  14. package/content/_partials/plain-speech.md +13 -0
  15. package/content/_partials/prose-line-breaks.md +3 -0
  16. package/content/_partials/record-marker.md +1 -0
  17. package/content/_partials/reduced-object-relative.md +28 -0
  18. package/content/_partials/shell-commands.md +3 -0
  19. package/content/_partials/target-file-set-resolution.md +22 -0
  20. package/content/_partials/technical-recommendations.md +5 -0
  21. package/content/_partials/test-structure-audit-checklist.md +7 -0
  22. package/content/_partials/ticket-assessment-baseline.md +12 -0
  23. package/content/_partials/ticket-assessment.md +202 -0
  24. package/content/_partials/work-type-choice.md +13 -0
  25. package/content/codeassembly-content.yaml +49 -0
  26. package/content/collections/all.md +11 -0
  27. package/content/collections/atlassian.md +16 -0
  28. package/content/collections/recommended.md +34 -0
  29. package/content/collections/triage.md +77 -0
  30. package/content/collections/williamthorsen.md +25 -0
  31. package/content/guidance/README.md +22 -0
  32. package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
  33. package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
  34. package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
  35. package/content/guidance/rulebooks/accessibility-conventions.md +20 -0
  36. package/content/guidance/rulebooks/codeassembly-content-specification.md +161 -0
  37. package/content/guidance/rulebooks/command-output-conventions.md +14 -0
  38. package/content/guidance/rulebooks/commit-conventions.md +72 -0
  39. package/content/guidance/rulebooks/generated-content-policy.md +10 -0
  40. package/content/guidance/rulebooks/live-worktree-policy.md +18 -0
  41. package/content/guidance/rulebooks/readme-conventions.md +74 -0
  42. package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
  43. package/content/guidance/rulebooks/shell-conventions.md +279 -0
  44. package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
  45. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +58 -0
  46. package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
  47. package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
  48. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
  49. package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
  50. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
  51. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
  52. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
  53. package/content/guidance/shared/AGENTS.md +43 -0
  54. package/content/scripts/README.md +41 -0
  55. package/content/scripts/describe-change.mjs +165 -0
  56. package/content/scripts/get-ticket-id.sh +131 -0
  57. package/content/scripts/manage-jira-ticket.mjs +209 -0
  58. package/content/scripts/resolve-frontmatter.sh +540 -0
  59. package/content/scripts/resolve-review-run.mjs +12 -0
  60. package/content/scripts/select-lede-exemplars.mjs +208 -0
  61. package/content/skills/_data/action-items.md +83 -0
  62. package/content/skills/_data/artifact-conventions.md +969 -0
  63. package/content/skills/_data/bitbucket-pr-access.md +89 -0
  64. package/content/skills/_data/branch-format.md +34 -0
  65. package/content/skills/_data/change-record.md +163 -0
  66. package/content/skills/_data/complexity-classification.md +58 -0
  67. package/content/skills/_data/concision.md +23 -0
  68. package/content/skills/_data/deployed-file-provenance.md +46 -0
  69. package/content/skills/_data/design-priorities.md +76 -0
  70. package/content/skills/_data/gh-body-file.md +30 -0
  71. package/content/skills/_data/git-commands.md +39 -0
  72. package/content/skills/_data/naming-conventions.md +50 -0
  73. package/content/skills/_data/pr-resolution.md +25 -0
  74. package/content/skills/_data/pr-source-resolution.md +36 -0
  75. package/content/skills/_data/recommendation-gradient.md +90 -0
  76. package/content/skills/_data/scope-and-deferral.md +83 -0
  77. package/content/skills/_data/spike-conventions.md +89 -0
  78. package/content/skills/_data/ticket-evaluation.md +13 -0
  79. package/content/skills/_data/ticket-id-extraction.md +43 -0
  80. package/content/skills/_data/ticket-source-resolution.md +147 -0
  81. package/content/skills/_data/title-templates.md +624 -0
  82. package/content/skills/_data/title-voice.md +17 -0
  83. package/content/skills/_data/work-types.json +168 -0
  84. package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
  85. package/content/skills/_partials/action-items.md +22 -0
  86. package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
  87. package/content/skills/_partials/commit-title-rendering.md +14 -0
  88. package/content/skills/_partials/gh-body-file.md +22 -0
  89. package/content/skills/_partials/nested-list-indent.md +9 -0
  90. package/content/skills/_partials/next-steps-after-plan.md +99 -0
  91. package/content/skills/_partials/next-steps-after-review.md +350 -0
  92. package/content/skills/_partials/option-format.md +84 -0
  93. package/content/skills/_partials/plan-template.md +97 -0
  94. package/content/skills/_partials/split-launch-prompts.md +5 -0
  95. package/content/skills/_partials/split-ticket-compose.md +5 -0
  96. package/content/skills/_partials/split-ticket-create.md +3 -0
  97. package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
  98. package/content/skills/_partials/ticket-concision.md +18 -0
  99. package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
  100. package/content/skills/_partials/ticket-placement.md +14 -0
  101. package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
  102. package/content/skills/_partials/ticket-skeleton.md +13 -0
  103. package/content/skills/add-change-record/SKILL.md +136 -0
  104. package/content/skills/add-test-ids/SKILL.md +51 -0
  105. package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
  106. package/content/skills/anti-patterns/SKILL.md +57 -0
  107. package/content/skills/assess-ticket/SKILL.md +46 -0
  108. package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
  109. package/content/skills/brainstorming/SKILL.md +107 -0
  110. package/content/skills/capture-event/SKILL.md +108 -0
  111. package/content/skills/capture-event/capture-event.mjs +216 -0
  112. package/content/skills/capture-feedback/SKILL.md +71 -0
  113. package/content/skills/capture-lede-decision/SKILL.md +163 -0
  114. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
  115. package/content/skills/classify-complexity/SKILL.md +92 -0
  116. package/content/skills/collaborate/SKILL.md +86 -0
  117. package/content/skills/condense-branch/SKILL.md +83 -0
  118. package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
  119. package/content/skills/create-commit/SKILL.md +65 -0
  120. package/content/skills/create-devlog/SKILL.md +108 -0
  121. package/content/skills/create-gh-pr/SKILL.md +106 -0
  122. package/content/skills/create-pr/SKILL.md +150 -0
  123. package/content/skills/create-ticket/SKILL.md +350 -0
  124. package/content/skills/derive-session-context/derive-session-context.mjs +148 -0
  125. package/content/skills/design-and-plan/SKILL.md +194 -0
  126. package/content/skills/development-workflows/SKILL.md +41 -0
  127. package/content/skills/get-ticket-id/SKILL.md +67 -0
  128. package/content/skills/groom-backlog/SKILL.md +245 -0
  129. package/content/skills/groom-backlog/groom-backlog.mjs +106 -0
  130. package/content/skills/implement-plan/SKILL.md +164 -0
  131. package/content/skills/index-prototypes/SKILL.md +145 -0
  132. package/content/skills/index-prototypes/index-prototypes.mjs +328 -0
  133. package/content/skills/kb-add/SKILL.md +156 -0
  134. package/content/skills/kb-add/kb-add.mjs +216 -0
  135. package/content/skills/kb-curate/SKILL.md +117 -0
  136. package/content/skills/kb-curate/kb-curate.mjs +213 -0
  137. package/content/skills/kb-edit/SKILL.md +128 -0
  138. package/content/skills/kb-edit/kb-edit.mjs +219 -0
  139. package/content/skills/kb-retrieve/SKILL.md +100 -0
  140. package/content/skills/kb-retrieve/kb-retrieve.mjs +206 -0
  141. package/content/skills/kb-retrieve-events/SKILL.md +98 -0
  142. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +206 -0
  143. package/content/skills/kb-update-events/SKILL.md +77 -0
  144. package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
  145. package/content/skills/merge-bb-pr/SKILL.md +136 -0
  146. package/content/skills/merge-gh-pr/SKILL.md +167 -0
  147. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
  148. package/content/skills/merge-pr/SKILL.md +368 -0
  149. package/content/skills/migrate-feedback-memories/SKILL.md +136 -0
  150. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
  151. package/content/skills/people-report/SKILL.md +208 -0
  152. package/content/skills/plan/SKILL.md +87 -0
  153. package/content/skills/prepare-prototype-brief/SKILL.md +126 -0
  154. package/content/skills/pull-from-backlog/SKILL.md +83 -0
  155. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +208 -0
  156. package/content/skills/refine-plan/SKILL.md +259 -0
  157. package/content/skills/respond-to-review/SKILL.md +292 -0
  158. package/content/skills/review-bb-pr/SKILL.md +161 -0
  159. package/content/skills/review-branch/SKILL.md +301 -0
  160. package/content/skills/review-criteria/SKILL.md +108 -0
  161. package/content/skills/review-gh-pr/SKILL.md +155 -0
  162. package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
  163. package/content/skills/review-permissions/SKILL.md +39 -0
  164. package/content/skills/review-pr/SKILL.md +123 -0
  165. package/content/skills/revise-comments/SKILL.md +115 -0
  166. package/content/skills/revise-prose/SKILL.md +197 -0
  167. package/content/skills/revise-prose/revise-prose.mjs +229 -0
  168. package/content/skills/save-artifact/SKILL.md +69 -0
  169. package/content/skills/save-plan/SKILL.md +55 -0
  170. package/content/skills/software-engineering/SKILL.md +74 -0
  171. package/content/skills/streamline-guidance/SKILL.md +174 -0
  172. package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
  173. package/content/skills/summarize-change/SKILL.md +308 -0
  174. package/content/skills/summarize-chat/SKILL.md +100 -0
  175. package/content/skills/systematic-debugging/SKILL.md +308 -0
  176. package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
  177. package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
  178. package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
  179. package/content/skills/systematic-debugging/find-polluter.sh +68 -0
  180. package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
  181. package/content/skills/systematic-debugging/test-academic.md +16 -0
  182. package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
  183. package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
  184. package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
  185. package/content/skills/testing-conventions/SKILL.md +168 -0
  186. package/content/skills/testing-conventions/mistakes.md +1 -0
  187. package/content/skills/typescript-testing-conventions/SKILL.md +129 -0
  188. package/content/skills/update-jira-ticket/SKILL.md +245 -0
  189. package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
  190. package/content/skills/update-project-guidance/SKILL.md +300 -0
  191. package/content/skills/upgrade-dependencies/SKILL.md +139 -0
  192. package/content/skills/wrap-up/SKILL.md +431 -0
  193. package/content/subagents/_data/claude.yaml +19 -0
  194. package/content/subagents/_data/rovo.yaml +31 -0
  195. package/content/subagents/canary.md +11 -0
  196. package/content/subagents/entry-drafter.md +187 -0
  197. package/content/subagents/handoff-reviewer.md +75 -0
  198. package/content/subagents/plan-reviewer.md +184 -0
  199. package/content/subagents/plan-reviser.md +88 -0
  200. package/content/subagents/prose-reviser.md +130 -0
  201. package/content/subagents/ticket-assessor.md +139 -0
  202. package/package.json +70 -2
  203. package/schemas/preferences.v1.json +294 -0
  204. package/schemas/work-types.v1.json +142 -0
@@ -0,0 +1,155 @@
1
+ ---
2
+ name: review-gh-pr
3
+ description: Fetch GitHub PR metadata, verify HEAD, and resolve specification sources for review-pr
4
+ user-invocable: false
5
+ ---
6
+
7
+ # Review GitHub pull request
8
+
9
+ Internal delegate that handles the GitHub-specific work for `review-pr`: Fetch PR metadata in a single `gh pr view` call, verify the local HEAD matches the PR's head commit, resolve the ticket from PR linked issues (with body-parse fallback), and prepare the spec-source list. Returns a resolved-input record that `review-pr` passes to `review-branch`'s shared review process.
10
+
11
+ This skill does not run a review. The review logic is implemented in `review-branch`.
12
+
13
+ ## Delegate interface
14
+
15
+ | Input | Type | Description |
16
+ | -------------------- | -------------- | ------------------------------------------------------------------------------------ |
17
+ | `pr_id` | string | PR number (e.g., `"1024"`) or full URL (`"https://github.com/owner/repo/pull/1024"`) |
18
+ | `diff_base_override` | string \| null | `--diff-base` value from `review-pr` if provided |
19
+ | `ticket_override` | string \| null | `--ticket` value from `review-pr` if provided |
20
+ | `project_slug` | string | From session context |
21
+ | `ticket_id` | string \| null | From session context |
22
+ | `artifact_base_dir` | string | From session context |
23
+
24
+ ## Resolved-output contract
25
+
26
+ On success, return a record with the following fields. `review-pr` passes this directly to `review-branch`:
27
+
28
+ | Field | Type | Description |
29
+ | ---------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
30
+ | `merge_base_sha` | string | Result of `git merge-base HEAD <diff_base>` |
31
+ | `diff_base` | string | Resolved ref (override if provided, else `baseRefName`) |
32
+ | `spec_sources` | array of `{ source_type, label, content, criteria?, provenance, last_updated }` | One entry per available specification source (PR description always present; ticket if resolved). Every source is `provenance: "remote"` (this path fetches live and never reads a local snapshot), so the review never renders a divergence note for it |
33
+ | `pr_metadata` | object | `{ number, url, head_oid, base_ref, title }` |
34
+
35
+ On HEAD mismatch, do not return; exit non-zero with the mismatch error. `review-pr` reports the message and stops.
36
+
37
+ ## Process
38
+
39
+ ### 1. Normalize `pr_id`
40
+
41
+ If `pr_id` is a URL of the form `https://github.com/{owner}/{repo}/pull/{number}`, extract `{number}`. Otherwise treat `pr_id` as the number directly.
42
+
43
+ ### 2. Fetch PR metadata
44
+
45
+ Issue a single `gh pr view` call with all fields needed downstream, and save its output for step 5:
46
+
47
+ ```bash
48
+ pr_json=$(mktemp "${TMPDIR:-/tmp}/review-gh-pr.XXXXXX")
49
+ gh pr view {pr_number} --json number,title,body,url,updatedAt,headRefName,headRefOid,baseRefName,closingIssuesReferences > "$pr_json"
50
+ echo "$pr_json"
51
+ ```
52
+
53
+ Write the printed absolute path wherever `{pr_json}` appears below. Parse the JSON with a real parser (`python3 -c "import sys,json; ..."` or `jq`). Capture:
54
+
55
+ - `number`, `title`, `body`, `url`, `updatedAt`
56
+ - `headRefName`, `headRefOid`, `baseRefName`
57
+ - `closingIssuesReferences` (array of `{ number, title, url }` or empty)
58
+
59
+ If `gh pr view` exits non-zero, report its stderr and stop.
60
+
61
+ ### 3. Verify HEAD
62
+
63
+ Compare the local HEAD against the PR's head commit:
64
+
65
+ ```bash
66
+ git rev-parse HEAD
67
+ ```
68
+
69
+ If the printed HEAD does not equal `headRefOid`, exit non-zero with:
70
+
71
+ ```
72
+ PR #{number}'s head commit is {short(headRefOid)} but HEAD is at {short(HEAD)}. Run "gh pr checkout {number}" first.
73
+ ```
74
+
75
+ Use the first 7 characters of each SHA for the short form. **Fail closed**: Never proceed with mismatched state. Compilation, dependency installation, and test execution all require the working tree to match the commit being reviewed.
76
+
77
+ ### 4. Resolve the diff base
78
+
79
+ Apply this cascade:
80
+
81
+ 1. If `diff_base_override` is non-null, use it.
82
+ 2. Otherwise, use `baseRefName` from PR metadata.
83
+
84
+ Compute the merge-base once:
85
+
86
+ ```bash
87
+ git merge-base HEAD {diff_base}
88
+ ```
89
+
90
+ ### 5. Resolve the ticket
91
+
92
+ Apply this cascade in order and use the first match:
93
+
94
+ 1. **`ticket_override`**: If non-null, resolve per [ticket source resolution](../_data/ticket-source-resolution.md) and use it.
95
+ 2. **Linked or referenced issue**: Run the bundled helper on the saved PR JSON:
96
+
97
+ ```bash
98
+ node {harness_home_dir}/skills/review-gh-pr/select-pr-ticket.mjs < {pr_json}
99
+ ```
100
+
101
+ It prints `{"number": <n or null>, "source": "<source>"}`. `source` is `closing-reference` (the first entry in `closingIssuesReferences`), `body-keyword` or `body-bare` (the earliest issue reference in the body outside code), or `none`, with `number` null. When `number` is not null, fetch the issue via `gh issue view --json number,title,body,labels,updatedAt {number}` and use it. When the helper exits non-zero, report its stderr and stop.
102
+
103
+ 3. **No ticket**: When `source` is `none`, proceed with the PR description as the only spec source.
104
+
105
+ ### 6. Build the spec-source list
106
+
107
+ Always include the PR description as a source:
108
+
109
+ ```
110
+ {
111
+ source_type: "pr_description",
112
+ label: "pr_description: PR #{number}",
113
+ content: <body>,
114
+ criteria: <optional: extracted bullets from `## What`, `## Summary`, or an explicit acceptance-criteria heading; null when the description does not contain a list>,
115
+ provenance: "remote",
116
+ last_updated: <PR `updatedAt`>
117
+ }
118
+ ```
119
+
120
+ If a ticket was resolved in step 5, prepend it:
121
+
122
+ ```
123
+ {
124
+ source_type: "ticket",
125
+ label: "ticket: {ticket_ref or short identifier}",
126
+ content: <ticket body>,
127
+ criteria: <optional: extracted from the ticket structure>,
128
+ provenance: "remote",
129
+ last_updated: <issue `updatedAt`>
130
+ }
131
+ ```
132
+
133
+ The list order is `[ticket?, pr_description]`: When both are present, the ticket is listed first because the ticket is the higher-authority source (PR description is a presentation of what the implementation delivers; the ticket states what was asked).
134
+
135
+ ### 7. Return the resolved-output record
136
+
137
+ Return:
138
+
139
+ ```
140
+ {
141
+ merge_base_sha: <from step 4>,
142
+ diff_base: <from step 4>,
143
+ spec_sources: <from step 6>,
144
+ pr_metadata: { number, url, head_oid: headRefOid, base_ref: baseRefName, title }
145
+ }
146
+ ```
147
+
148
+ `review-pr` passes this to `review-branch` and the review proceeds.
149
+
150
+ ## Important
151
+
152
+ - **Single `gh pr view` call.** All fields are fetched at once. Do not split into multiple calls: Repeated `gh` invocations are slow and add failure modes.
153
+ - **HEAD mismatch is a hard stop.** The error message must include the literal `gh pr checkout {number}` suggestion so that the user has a one-line copy-pasteable fix.
154
+ - **Ticket-resolution cascade order is fixed.** `ticket_override` → `closingIssuesReferences[0]` → body parse → none. Document this order in any future change so that future readers do not silently rearrange it.
155
+ - **No review logic here.** This delegate prepares inputs only. The review process (diff analysis, finding generation, "Specification compliance" rendering) runs inside `review-branch` after `review-pr` invokes it with the resolved inputs.
@@ -0,0 +1,8 @@
1
+ import { createRequire as __cjsCreateRequire } from 'node:module';
2
+ const require = __cjsCreateRequire(import.meta.url);
3
+ var p=Object.defineProperty;var n=(r,e)=>p(r,"name",{value:e,configurable:!0});import{realpathSync as b}from"node:fs";import i from"node:process";import{fileURLToPath as E}from"node:url";function f(r){return r instanceof Error||Object.prototype.toString.call(r)==="[object Error]"}n(f,"isError");function u(r){try{return f(r)&&typeof r.message=="string"&&r.message!==""?r.message:String(r)}catch{return"[unstringifiable value]"}}n(u,"describeError");async function a(r){let e=[];for await(let t of r){if(!Buffer.isBuffer(t))throw new TypeError("readAll: expected Buffer chunks (stream must be in binary mode)");e.push(t)}return Buffer.concat(e).toString("utf8")}n(a,"readAll");function c(r){return g(r)&&!Array.isArray(r)}n(c,"isRecord");function g(r){return typeof r=="object"&&r!==null}n(g,"isObject");var y=/\b(?:closes|fixes|resolves):?\s+#(\d+)\b|(?<![\w/#&])#(\d+)\b/iu;function m(r){if(!c(r))throw new Error("input must be a JSON object");let{body:e,closingIssuesReferences:t}=r;if(e!=null&&typeof e!="string")throw new Error("body must be a string");if(t!==void 0&&!Array.isArray(t))throw new Error("closingIssuesReferences must be an array");let o=(t??[]).map(s=>{if(!c(s)||typeof s.number!="number"||!Number.isSafeInteger(s.number))throw new Error("each closingIssuesReferences entry must have an integer number");return s.number});return{body:e??"",closingIssueNumbers:o}}n(m,"parsePrTicketInput");function l(r){let[e]=r.closingIssueNumbers;if(e!==void 0)return{number:e,source:"closing-reference"};let t=y.exec(k(r.body));if(t===null)return{number:null,source:"none"};let[,o,s=""]=t;return o!==void 0?{number:Number(o),source:"body-keyword"}:{number:Number(s),source:"body-bare"}}n(l,"selectPrTicket");function d(r){return r.replaceAll(/[^\n]/gu," ")}n(d,"blank");function k(r){return h(w(r))}n(k,"maskCode");function w(r){let e;return r.split(`
4
+ `).map(t=>{let o=/^ {0,3}(`{3,}|~{3,})/u.exec(t)?.[1];if(e===void 0){if(o===void 0)return t;e={char:o.charAt(0),length:o.length}}else o!==void 0&&o.charAt(0)===e.char&&o.length>=e.length&&t.trim()===o&&(e=void 0);return d(t)}).join(`
5
+ `)}n(w,"maskFencedBlocks");function h(r){return r.replaceAll(/(?<!`)(`+)(?!`)(?:(?!\n[ \t]*\n)[\s\S])*?(?<!`)\1(?!`)/gu,e=>d(e))}n(h,"maskInlineCode");async function x(){try{let r=i.argv.slice(2);if(r.length>0)throw new Error(`unexpected argument: ${r.join(" ")}`);let e=m(JSON.parse(await a(i.stdin)));i.stdout.write(`${JSON.stringify(l(e))}
6
+ `)}catch(r){i.stderr.write(`select-pr-ticket: ${u(r)}
7
+ `),i.exit(1)}}n(x,"main");N()&&await x();function N(){let r=i.argv[1];if(r===void 0)return!1;try{return b(E(import.meta.url))===b(r)}catch(e){return i.stderr.write(`select-pr-ticket: warning: could not determine entry point: ${u(e)}
8
+ `),!1}}n(N,"isEntryPoint");
@@ -0,0 +1,39 @@
1
+ ---
2
+ name: review-permissions
3
+ description: Use at end of session to recommend updates to the Claude Code permissions allow list based on commands used
4
+ user-invocable: true
5
+ supported-harnesses: [claude]
6
+ ---
7
+
8
+ # Review permissions
9
+
10
+ Recommend modifications to `~/.claude/settings.json` permissions based on commands used in this session.
11
+
12
+ ## Process
13
+
14
+ 1. **Read current settings** from `~/.claude/settings.json` → `permissions`
15
+ 2. **Review commands executed** in this session
16
+ 3. **Identify gaps**: Commands that needed manual approval or were missing from the list
17
+ 4. **Recommend additions**, following the consolidation strategy below
18
+ 5. **Check deny list**: Do not recommend additions that conflict with `permissions.deny`
19
+ 6. **Output a proposed diff** to `settings.json`
20
+
21
+ ## Current strategy
22
+
23
+ The permissions use `acceptEdits` mode + consolidated allowlist + deny list:
24
+
25
+ - **`acceptEdits` mode** (`defaultMode: "acceptEdits"`) auto-approves all file operations (Read, Edit, Write). This eliminates file-modification confirmation prompts. The worktree-based workflow makes this safe: Every branch is trivially revertible.
26
+ - **Bash allowlist** uses broad prefix patterns (`Bash(git:*)`) rather than individual subcommand entries (`Bash(git add:*)`, `Bash(git commit:*)`, etc.). One wildcard per tool family.
27
+ - **Deny list** blocks destructive patterns that the broad allowlist would otherwise permit. This is the primary safety mechanism for Bash commands.
28
+
29
+ ## Guidance for recommendations
30
+
31
+ - **Prefer the broadest safe pattern.** `Bash(docker:*)` over listing individual subcommands.
32
+ - **When adding a broad pattern, check for destructive subcommands** that need deny list entries. For example, `Bash(git:*)` requires `Bash(git checkout .)`, `Bash(git clean:*)`, `Bash(git reset --hard:*)`, etc. in the deny list.
33
+ - **Do not recommend Edit or Read rules**: `acceptEdits` mode covers all file operations. Read rules in the allow list only serve as explicit documentation for paths outside the working directory.
34
+ - **Never recommend allowing commands that are destructive by nature** (rm -rf, git push --force, git reset --hard): These belong in the deny list.
35
+ - **Note any commands that the user approved manually** and that seem intentionally ungated (one-off operations).
36
+
37
+ ## Limitations
38
+
39
+ A formal approval log is not available to this skill. Recommendations are based on commands executed in this session and the agent's memory of permission prompts. Invoke this skill while the conversation context is fresh.
@@ -0,0 +1,123 @@
1
+ ---
2
+ name: review-pr
3
+ description: Review a pull request by detecting the platform, fetching PR metadata via a delegate, and running the shared branch-review process
4
+ user-invocable: true
5
+ ---
6
+
7
+ # Review pull request
8
+
9
+ Review a pull request on the appropriate platform. Detects the platform, dispatches to a delegate (`{skill:review-gh-pr}` or `{skill?:review-bb-pr}`) that fetches PR metadata, verifies HEAD matches the PR's head commit, and resolves specification sources, then invokes the shared review process from `{skill:review-branch}` with the resolved inputs.
10
+
11
+ This is a thin entry skill: The shared review logic (diff analysis, finding generation, "Specification compliance" rendering, artifact saving) is implemented in `review-branch`. Delegates own only the platform-specific work (PR-metadata fetch, HEAD verification, ticket resolution from PR linked issues, PR-description preparation). After the delegate returns its resolved inputs, this skill invokes `review-branch`'s review process with the prepared spec-source list and resolved diff base.
12
+
13
+ ## Arguments
14
+
15
+ | Argument | Description | Default |
16
+ | ------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
17
+ | `<pr_id>` | Positional. Full GitHub or Bitbucket PR URL, or a bare PR number. An explicit value always overrides the stored URL. | _(required unless a stored `pr_url` exists in the manifest)_ |
18
+ | `--diff-base=<ref>` | Override the diff base. Reviews `merge-base(HEAD, <ref>)..HEAD`. | The PR's `baseRefName` (or Bitbucket equivalent) |
19
+ | `--ticket=<source>` | Override the auto-resolved ticket. Resolved per [ticket source resolution](../_data/ticket-source-resolution.md). | PR's first linked issue, then PR-body parse, then none |
20
+
21
+ ## Process
22
+
23
+ ### 1. Get session context
24
+
25
+ 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 `project_slug`, `ticket_id`, `ticket_ref`, `default_branch`, `artifact_base_dir`, `scm`, and `pr_url` from it. Pass these values into `review-branch`'s steps 4–9 (review header, scoring, saving) so that `review-branch`'s own step 1 does not need to re-run.
26
+
27
+ ### 2. Resolve the PR
28
+
29
+ Resolve the PR to review per [PR source resolution](../_data/pr-source-resolution.md#runtime-resolution-path-add-change-record-review-pr-merge-pr): An explicit `<pr_id>` overrides; otherwise a stored `pr_url` from session context is the default; otherwise discover the PR for the current branch. Persist the resolved URL via `--set-pr-url`, and invalidate (`--clear-pr-url`) and re-resolve a stored URL that does not yield the expected PR. The resolved value is passed to the delegate as `pr_id` in step 5.
30
+
31
+ ### 3. Detect platform
32
+
33
+ Apply the [platform resolution cascade](../_data/ticket-source-resolution.md#platform-resolution-cascade):
34
+
35
+ 1. Check `.agents/preferences.yaml` → `integrations` (if exactly one is enabled, use it; if multiple, ask).
36
+ 2. Check `git remote get-url origin` (`github.com` → GitHub; `bitbucket.org` → Bitbucket).
37
+ 3. Ask the user.
38
+
39
+ If `<pr_id>` is a full URL, the URL host overrides the cascade: A `https://github.com/...` URL is GitHub regardless of preferences. Numeric `<pr_id>` inputs use the cascade-resolved platform.
40
+
41
+ ### 4. Select delegate
42
+
43
+ | Platform | Delegate |
44
+ | ------------------------- | -------------- |
45
+ | `github` | `review-gh-pr` |
46
+ | `bitbucket` | `review-bb-pr` |
47
+ | Unknown after the cascade | Ask the user |
48
+
49
+ ### 5. Call delegate
50
+
51
+ Pass the following inputs to the selected delegate per its delegate interface:
52
+
53
+ | Input | Value |
54
+ | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
55
+ | `pr_id` | The PR resolved in step 2. The delegate parses and normalizes it (extracts the PR number from a URL when applicable; the Bitbucket delegate also resolves the workspace and repository that it addresses). |
56
+ | `diff_base_override` | Value of `--diff-base` if provided; otherwise `null` |
57
+ | `ticket_override` | Value of `--ticket` if provided; otherwise `null` |
58
+ | `project_slug` | From session context |
59
+ | `ticket_id` | From session context |
60
+ | `artifact_base_dir` | From session context |
61
+
62
+ The delegate returns a resolved-input record:
63
+
64
+ | Field | Type | Description |
65
+ | ---------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
66
+ | `merge_base_sha` | string | Result of `git merge-base HEAD <diff-base>` after delegate-side resolution |
67
+ | `diff_base` | string | The ref against which the delegate resolved |
68
+ | `spec_sources` | array of `{ source_type, label, content, criteria?, provenance, last_updated }` | One entry per available specification source. `provenance`/`last_updated` are recorded so that the review can state which contract it measured against; delegate-supplied sources are always `provenance: "remote"` |
69
+ | `pr_metadata` | object (PR number, URL, head SHA, base ref, title) | Used by the review heading |
70
+
71
+ If the delegate exits with a HEAD-mismatch error (the PR's head commit is not the local HEAD), report its error message and stop. Do not proceed with mismatched state.
72
+
73
+ ### 6. Invoke the shared review process
74
+
75
+ Invoke `review-branch`'s review process with the resolved inputs:
76
+
77
+ - The diff base is `merge_base_sha` (already computed by the delegate).
78
+ - The spec-source list is `spec_sources` from the delegate. The "Specification compliance" section in the review output renders one subsection per entry. For a typical PR, this list contains both the ticket (when one was resolved) and the PR description as a `pr_description` source.
79
+ - The review heading uses `pr_metadata` to show the PR number and URL alongside the ticket reference.
80
+
81
+ Invoke `review-branch`'s [Process](../review-branch/SKILL.md#process) starting at step 4 (read prior artifacts). Steps 1–3 of `review-branch` are already complete: Session context was gathered in step 1 above; `merge_base_sha` and `spec_sources` were resolved by the delegate.
82
+
83
+ ### 7. Save and present next steps
84
+
85
+ `review-branch`'s saving and next-steps logic apply unchanged. The review artifact is saved into the ticket's active run directory.
86
+
87
+ Because this review covers a pull request, the next-steps Findings sub-block renders its PR variant: "Post findings on the PR" rather than the local-branch options. The Source-divergence sub-block likewise appears here whenever the PR description and ticket diverge, since both spec sources are present.
88
+
89
+ ## Examples
90
+
91
+ ### Review the PR for the current branch
92
+
93
+ ```bash
94
+ # Check out the PR branch first, then review it.
95
+ gh pr checkout 1024
96
+ {skill:review-pr} 1024
97
+ ```
98
+
99
+ ### Review a PR by URL
100
+
101
+ ```bash
102
+ gh pr checkout https://github.com/williamthorsen/codeassembly/pull/1024
103
+ {skill:review-pr} https://github.com/williamthorsen/codeassembly/pull/1024
104
+ ```
105
+
106
+ ### Review a stacked PR with a non-default diff base
107
+
108
+ ```bash
109
+ gh pr checkout 1024
110
+ {skill:review-pr} 1024 --diff-base=feature/parent-branch
111
+ ```
112
+
113
+ ### Override the auto-resolved ticket
114
+
115
+ ```bash
116
+ {skill:review-pr} 1024 --ticket=#553
117
+ ```
118
+
119
+ ## Important
120
+
121
+ - **Always check out the PR first.** The delegate compares `git rev-parse HEAD` to the PR's head commit and fails closed if they differ. The error message includes the platform-specific checkout command (e.g., `gh pr checkout <n>`).
122
+ - **The orchestrator does not own any review logic.** All findings, scoring, and the "Specification compliance" rendering happen inside `review-branch`. This skill is platform detection + delegate dispatch + invocation of the shared review process.
123
+ - **Two specification sources by default.** Unlike `{skill:review-branch}` (one source: the ticket), `{skill:review-pr}` adds the PR description as a second source so that the review evaluates the implementation against both. Source-vs-source divergence is reported in the `## Specification consistency` section of the review output (see `review-branch/SKILL.md`).
@@ -0,0 +1,115 @@
1
+ ---
2
+ name: revise-comments
3
+ description: Revise comments in target files per the comment-discipline rules, editing in place
4
+ user-invocable: true
5
+ ---
6
+
7
+ # Revise comments
8
+
9
+ Apply the comment-discipline audit to a target file set, editing comments in place. The default workflow is `{skill:revise-comments}` after a feature is implemented; explicit paths support cleaning up legacy code.
10
+
11
+ If the `revise-prose` sweep is wanted on the same files, run this skill first: It decides whether a comment exists at all, and it may delete the very comment that the prose sweep would otherwise polish.
12
+
13
+ ## Invocation
14
+
15
+ - `{skill:revise-comments}`: Default target is files committed on the current branch relative to the default branch. To audit uncommitted work, pass explicit paths (`{skill:revise-comments} .` covers the working tree).
16
+ - `{skill:revise-comments} <path> [<path>...]`: Explicit file or directory targets. Directories are processed recursively.
17
+ - `{skill:revise-comments} --dry-run [...]`: Produce the summary without applying edits. Triage and dry-run are unified under this flag.
18
+
19
+ ## Process
20
+
21
+ 1. **Resolve the target file set** per [Target file set](#target-file-set), keeping the comment-supporting files from what it yields.
22
+
23
+ Without an argument, the target is the set of files changed in commits on the current branch relative to the default branch. Obtain `{default_branch}` via `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs`, then:
24
+
25
+ ```bash
26
+ git diff --name-only "{default_branch}...HEAD"
27
+ ```
28
+
29
+ 2. **Apply the audit per file.** Read each target file. Put every comment through the tests below. Decide one of three actions: kept, deleted, or rewritten. In normal mode, apply edits in place via the Edit tool. In `--dry-run` mode, record the proposed action without editing.
30
+
31
+ 3. **Audit the diff** per [Diff audit](#diff-audit), over the edits just applied. A re-worded comment is the reach sweep's central case: It can invalidate a sibling doc, a README, or a test title that echoed the phrasing that it replaced. Such a file is outside the resolved target set, so the hard gate in [Target file set](#target-file-set) applies and the hit is reported to the user alongside the summary rather than repaired. Because `--dry-run` does not apply any edits, the step is skipped under that flag.
32
+
33
+ 4. **Emit the summary.** After processing all targets, emit one table per file with non-trivial decisions.
34
+
35
+ <!-- include: ../../_partials/target-file-set-resolution.md / -->
36
+
37
+ <!-- include: ../../_partials/comment-discipline.md / -->
38
+
39
+ <!-- include: ../../_partials/diff-audit-checklist.md / -->
40
+
41
+ ## File-level carve-outs
42
+
43
+ The carve-outs above apply to comments. Two file-level rules decide which lines this skill may touch at all:
44
+
45
+ - **Test files.** Path contains `__tests__/` or filename matches `*.spec.*` / `*.test.*`. The test-comment carve-out applies inside them; the tests still apply to everything else in the file.
46
+ - **`eslint-disable` lines.** Lines beginning with `eslint-disable`, `eslint-disable-next-line`, `eslint-disable-line`, or the block forms `/* eslint-disable */` and `/* eslint-enable */`. Keep the rationale, tightened to name only why the rule is suppressed at that line. Strip surrounding context, ticket references, and design discussion.
47
+
48
+ ## When to pause and ask
49
+
50
+ The default is to act. Pause and ask the user when one of these holds:
51
+
52
+ - A test comment could plausibly be non-obvious setup, but the test name already conveys the setup intent.
53
+ - An `eslint-disable` rationale is at the boundary between tight and over-scoped.
54
+ - A file header describes potentially load-bearing architecture (composition order, threading model, invariants across functions), so it may state a constraint that the code cannot show.
55
+
56
+ ## Summary format
57
+
58
+ After processing, emit one Markdown table per file. Skip files with zero decisions. The same format appears in normal and `--dry-run` runs; in dry-run mode, append `(dry-run)` to the heading.
59
+
60
+ ```
61
+ revise-comments summary
62
+
63
+ src/lib/payload.ts
64
+ | Line | Action | Test | Reason |
65
+ | ---- | --------- | ------------ | -------------------------------- |
66
+ | 1 | deleted | one-location | duplicates the per-function docs |
67
+ | 2 | deleted | stranger | PR reference |
68
+ | 4 | rewritten | stranger | "we discussed" |
69
+ | 6 | kept | n/a | why-inline |
70
+ ```
71
+
72
+ Line numbers refer to the pre-edit file, so each row is checked against `git diff` output before the table is emitted: The `Action` column reports what the diff shows, not what was intended. For a comment failing more than one test, report the first that it fails.
73
+
74
+ ## Worked example
75
+
76
+ A small file demonstrating multi-comment revision end-to-end.
77
+
78
+ **Before** (`src/lib/payload.ts`):
79
+
80
+ ```ts
81
+ // Helpers for building the request payload sent to the orchestrator API.
82
+ // Originally added in PR #423 to consolidate the type narrowing logic.
83
+
84
+ // Builds the canonical payload shape. We discussed inlining but it's used at three call sites.
85
+ export function buildPayload(input: Input): Payload {
86
+ // react-select types value as a union; narrow to array.
87
+ const items = Array.isArray(input.value) ? input.value : [input.value];
88
+ return { items };
89
+ }
90
+ ```
91
+
92
+ **After:**
93
+
94
+ ```ts
95
+ /** Builds the canonical payload shape. */
96
+ export function buildPayload(input: Input): Payload {
97
+ // react-select types value as a union; narrow to array.
98
+ const items = Array.isArray(input.value) ? input.value : [input.value];
99
+ return { items };
100
+ }
101
+ ```
102
+
103
+ **Summary emitted:**
104
+
105
+ ```
106
+ revise-comments summary
107
+
108
+ src/lib/payload.ts
109
+ | Line | Action | Test | Reason |
110
+ | ---- | --------- | ------------ | -------------------------------- |
111
+ | 1 | deleted | one-location | duplicates the per-function docs |
112
+ | 2 | deleted | stranger | PR reference |
113
+ | 4 | rewritten | stranger | "we discussed" |
114
+ | 6 | kept | n/a | why-inline |
115
+ ```