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.
- package/.meta/changelog.json +563 -0
- package/CHANGELOG.md +134 -0
- package/LICENSE +7 -0
- package/README.md +165 -1
- package/content/_partials/README.md +192 -0
- package/content/_partials/code-descriptions.md +4 -0
- package/content/_partials/code-style.md +7 -0
- package/content/_partials/comment-discipline.md +89 -0
- package/content/_partials/concision.md +3 -0
- package/content/_partials/diff-audit-checklist.md +9 -0
- package/content/_partials/file-access.md +4 -0
- package/content/_partials/live-repo-writes.md +13 -0
- package/content/_partials/plain-speech-calibration.md +66 -0
- package/content/_partials/plain-speech.md +13 -0
- package/content/_partials/prose-line-breaks.md +3 -0
- package/content/_partials/record-marker.md +1 -0
- package/content/_partials/reduced-object-relative.md +28 -0
- package/content/_partials/shell-commands.md +3 -0
- package/content/_partials/target-file-set-resolution.md +22 -0
- package/content/_partials/technical-recommendations.md +5 -0
- package/content/_partials/test-structure-audit-checklist.md +7 -0
- package/content/_partials/ticket-assessment-baseline.md +12 -0
- package/content/_partials/ticket-assessment.md +202 -0
- package/content/_partials/work-type-choice.md +13 -0
- package/content/codeassembly-content.yaml +49 -0
- package/content/collections/all.md +11 -0
- package/content/collections/atlassian.md +16 -0
- package/content/collections/recommended.md +34 -0
- package/content/collections/triage.md +77 -0
- package/content/collections/williamthorsen.md +25 -0
- package/content/guidance/README.md +22 -0
- package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
- package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
- package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
- package/content/guidance/rulebooks/accessibility-conventions.md +20 -0
- package/content/guidance/rulebooks/codeassembly-content-specification.md +161 -0
- package/content/guidance/rulebooks/command-output-conventions.md +14 -0
- package/content/guidance/rulebooks/commit-conventions.md +72 -0
- package/content/guidance/rulebooks/generated-content-policy.md +10 -0
- package/content/guidance/rulebooks/live-worktree-policy.md +18 -0
- package/content/guidance/rulebooks/readme-conventions.md +74 -0
- package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
- package/content/guidance/rulebooks/shell-conventions.md +279 -0
- package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +58 -0
- package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
- package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
- package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
- package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
- package/content/guidance/shared/AGENTS.md +43 -0
- package/content/scripts/README.md +41 -0
- package/content/scripts/describe-change.mjs +165 -0
- package/content/scripts/get-ticket-id.sh +131 -0
- package/content/scripts/manage-jira-ticket.mjs +209 -0
- package/content/scripts/resolve-frontmatter.sh +540 -0
- package/content/scripts/resolve-review-run.mjs +12 -0
- package/content/scripts/select-lede-exemplars.mjs +208 -0
- package/content/skills/_data/action-items.md +83 -0
- package/content/skills/_data/artifact-conventions.md +969 -0
- package/content/skills/_data/bitbucket-pr-access.md +89 -0
- package/content/skills/_data/branch-format.md +34 -0
- package/content/skills/_data/change-record.md +163 -0
- package/content/skills/_data/complexity-classification.md +58 -0
- package/content/skills/_data/concision.md +23 -0
- package/content/skills/_data/deployed-file-provenance.md +46 -0
- package/content/skills/_data/design-priorities.md +76 -0
- package/content/skills/_data/gh-body-file.md +30 -0
- package/content/skills/_data/git-commands.md +39 -0
- package/content/skills/_data/naming-conventions.md +50 -0
- package/content/skills/_data/pr-resolution.md +25 -0
- package/content/skills/_data/pr-source-resolution.md +36 -0
- package/content/skills/_data/recommendation-gradient.md +90 -0
- package/content/skills/_data/scope-and-deferral.md +83 -0
- package/content/skills/_data/spike-conventions.md +89 -0
- package/content/skills/_data/ticket-evaluation.md +13 -0
- package/content/skills/_data/ticket-id-extraction.md +43 -0
- package/content/skills/_data/ticket-source-resolution.md +147 -0
- package/content/skills/_data/title-templates.md +624 -0
- package/content/skills/_data/title-voice.md +17 -0
- package/content/skills/_data/work-types.json +168 -0
- package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
- package/content/skills/_partials/action-items.md +22 -0
- package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
- package/content/skills/_partials/commit-title-rendering.md +14 -0
- package/content/skills/_partials/gh-body-file.md +22 -0
- package/content/skills/_partials/nested-list-indent.md +9 -0
- package/content/skills/_partials/next-steps-after-plan.md +99 -0
- package/content/skills/_partials/next-steps-after-review.md +350 -0
- package/content/skills/_partials/option-format.md +84 -0
- package/content/skills/_partials/plan-template.md +97 -0
- package/content/skills/_partials/split-launch-prompts.md +5 -0
- package/content/skills/_partials/split-ticket-compose.md +5 -0
- package/content/skills/_partials/split-ticket-create.md +3 -0
- package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
- package/content/skills/_partials/ticket-concision.md +18 -0
- package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
- package/content/skills/_partials/ticket-placement.md +14 -0
- package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
- package/content/skills/_partials/ticket-skeleton.md +13 -0
- package/content/skills/add-change-record/SKILL.md +136 -0
- package/content/skills/add-test-ids/SKILL.md +51 -0
- package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
- package/content/skills/anti-patterns/SKILL.md +57 -0
- package/content/skills/assess-ticket/SKILL.md +46 -0
- package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
- package/content/skills/brainstorming/SKILL.md +107 -0
- package/content/skills/capture-event/SKILL.md +108 -0
- package/content/skills/capture-event/capture-event.mjs +216 -0
- package/content/skills/capture-feedback/SKILL.md +71 -0
- package/content/skills/capture-lede-decision/SKILL.md +163 -0
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
- package/content/skills/classify-complexity/SKILL.md +92 -0
- package/content/skills/collaborate/SKILL.md +86 -0
- package/content/skills/condense-branch/SKILL.md +83 -0
- package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
- package/content/skills/create-commit/SKILL.md +65 -0
- package/content/skills/create-devlog/SKILL.md +108 -0
- package/content/skills/create-gh-pr/SKILL.md +106 -0
- package/content/skills/create-pr/SKILL.md +150 -0
- package/content/skills/create-ticket/SKILL.md +350 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +148 -0
- package/content/skills/design-and-plan/SKILL.md +194 -0
- package/content/skills/development-workflows/SKILL.md +41 -0
- package/content/skills/get-ticket-id/SKILL.md +67 -0
- package/content/skills/groom-backlog/SKILL.md +245 -0
- package/content/skills/groom-backlog/groom-backlog.mjs +106 -0
- package/content/skills/implement-plan/SKILL.md +164 -0
- package/content/skills/index-prototypes/SKILL.md +145 -0
- package/content/skills/index-prototypes/index-prototypes.mjs +328 -0
- package/content/skills/kb-add/SKILL.md +156 -0
- package/content/skills/kb-add/kb-add.mjs +216 -0
- package/content/skills/kb-curate/SKILL.md +117 -0
- package/content/skills/kb-curate/kb-curate.mjs +213 -0
- package/content/skills/kb-edit/SKILL.md +128 -0
- package/content/skills/kb-edit/kb-edit.mjs +219 -0
- package/content/skills/kb-retrieve/SKILL.md +100 -0
- package/content/skills/kb-retrieve/kb-retrieve.mjs +206 -0
- package/content/skills/kb-retrieve-events/SKILL.md +98 -0
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +206 -0
- package/content/skills/kb-update-events/SKILL.md +77 -0
- package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
- package/content/skills/merge-bb-pr/SKILL.md +136 -0
- package/content/skills/merge-gh-pr/SKILL.md +167 -0
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
- package/content/skills/merge-pr/SKILL.md +368 -0
- package/content/skills/migrate-feedback-memories/SKILL.md +136 -0
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
- package/content/skills/people-report/SKILL.md +208 -0
- package/content/skills/plan/SKILL.md +87 -0
- package/content/skills/prepare-prototype-brief/SKILL.md +126 -0
- package/content/skills/pull-from-backlog/SKILL.md +83 -0
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +208 -0
- package/content/skills/refine-plan/SKILL.md +259 -0
- package/content/skills/respond-to-review/SKILL.md +292 -0
- package/content/skills/review-bb-pr/SKILL.md +161 -0
- package/content/skills/review-branch/SKILL.md +301 -0
- package/content/skills/review-criteria/SKILL.md +108 -0
- package/content/skills/review-gh-pr/SKILL.md +155 -0
- package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
- package/content/skills/review-permissions/SKILL.md +39 -0
- package/content/skills/review-pr/SKILL.md +123 -0
- package/content/skills/revise-comments/SKILL.md +115 -0
- package/content/skills/revise-prose/SKILL.md +197 -0
- package/content/skills/revise-prose/revise-prose.mjs +229 -0
- package/content/skills/save-artifact/SKILL.md +69 -0
- package/content/skills/save-plan/SKILL.md +55 -0
- package/content/skills/software-engineering/SKILL.md +74 -0
- package/content/skills/streamline-guidance/SKILL.md +174 -0
- package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
- package/content/skills/summarize-change/SKILL.md +308 -0
- package/content/skills/summarize-chat/SKILL.md +100 -0
- package/content/skills/systematic-debugging/SKILL.md +308 -0
- package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
- package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
- package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
- package/content/skills/systematic-debugging/find-polluter.sh +68 -0
- package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
- package/content/skills/systematic-debugging/test-academic.md +16 -0
- package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
- package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
- package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
- package/content/skills/testing-conventions/SKILL.md +168 -0
- package/content/skills/testing-conventions/mistakes.md +1 -0
- package/content/skills/typescript-testing-conventions/SKILL.md +129 -0
- package/content/skills/update-jira-ticket/SKILL.md +245 -0
- package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
- package/content/skills/update-project-guidance/SKILL.md +300 -0
- package/content/skills/upgrade-dependencies/SKILL.md +139 -0
- package/content/skills/wrap-up/SKILL.md +431 -0
- package/content/subagents/_data/claude.yaml +19 -0
- package/content/subagents/_data/rovo.yaml +31 -0
- package/content/subagents/canary.md +11 -0
- package/content/subagents/entry-drafter.md +187 -0
- package/content/subagents/handoff-reviewer.md +75 -0
- package/content/subagents/plan-reviewer.md +184 -0
- package/content/subagents/plan-reviser.md +88 -0
- package/content/subagents/prose-reviser.md +130 -0
- package/content/subagents/ticket-assessor.md +139 -0
- package/package.json +70 -2
- package/schemas/preferences.v1.json +294 -0
- 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
|
+
```
|