codeassembly-guidance 0.5.0 → 0.7.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 +491 -0
- package/CHANGELOG.md +118 -0
- package/README.md +33 -4
- package/content/_partials/finding-grades.md +4 -0
- package/content/_partials/kb-unsearched-private-stores.md +6 -0
- package/content/codeassembly-content.yaml +4 -0
- package/content/collections/recommended.md +5 -2
- package/content/guidance/_harnesses/rovo/AGENTS.md +0 -1
- package/content/guidance/rulebooks/accessibility-conventions.md +26 -6
- package/content/guidance/rulebooks/cli-conventions.md +17 -2
- package/content/guidance/rulebooks/codeassembly-content-specification.md +11 -11
- package/content/guidance/rulebooks/live-worktree-policy.md +2 -2
- package/content/guidance/rulebooks/machine-readable-output-conventions.md +85 -0
- package/content/guidance/rulebooks/ui-copy-conventions.md +2 -2
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +10 -10
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -1
- package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +7 -3
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +3 -1
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +5 -5
- package/content/guidance/shared/AGENTS.md +1 -1
- package/content/scripts/check-prose.mjs +1 -1
- package/content/scripts/describe-change.mjs +88 -88
- package/content/scripts/manage-jira-ticket.mjs +113 -113
- package/content/scripts/select-lede-exemplars.mjs +85 -85
- package/content/scripts/validate-preferences.mjs +38 -38
- package/content/skills/_data/action-items.md +2 -2
- package/content/skills/_data/artifact-conventions.md +20 -10
- package/content/skills/_data/concision.md +1 -1
- package/content/skills/_data/entry-points.md +37 -0
- package/content/skills/_data/project-stage.md +9 -5
- package/content/skills/_data/recommendation-gradient.md +6 -6
- package/content/skills/_data/spike-conventions.md +20 -7
- package/content/skills/_data/ticket-source-resolution.md +21 -4
- package/content/skills/_data/title-templates.md +4 -4
- package/content/skills/_partials/commit-title-rendering.md +2 -1
- package/content/skills/_partials/implementation-order-list.md +27 -0
- package/content/skills/_partials/next-steps-after-plan.md +6 -5
- package/content/skills/_partials/option-format.md +8 -8
- package/content/skills/_partials/plan-template.md +5 -1
- package/content/skills/_partials/resolve-plan-and-ticket.md +22 -0
- package/content/skills/_partials/split-launch-prompts.md +2 -2
- package/content/skills/_partials/ticket-criteria-conventions.md +2 -0
- package/content/skills/align-ticket-with-implementation/SKILL.md +1 -1
- package/content/skills/analyze-performance/SKILL.md +102 -0
- package/content/skills/analyze-performance/analyze-performance.mjs +70 -0
- package/content/skills/assess-code-health/SKILL.md +16 -14
- package/content/skills/assess-code-health/assess-code-health.mjs +29 -28
- package/content/skills/assess-usability/SKILL.md +5 -3
- package/content/skills/capture-event/SKILL.md +20 -11
- package/content/skills/capture-event/capture-event.mjs +122 -122
- package/content/skills/capture-feedback/SKILL.md +2 -1
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +97 -97
- package/content/skills/convert-agent-prompt/SKILL.md +60 -0
- package/content/skills/create-commit/SKILL.md +10 -5
- package/content/skills/create-pr/SKILL.md +11 -11
- package/content/skills/create-ticket/SKILL.md +1 -0
- package/content/skills/create-ticket/resolve-ticket-target.mjs +92 -92
- package/content/skills/curate-feedback/curate-feedback.mjs +82 -82
- package/content/skills/derive-session-context/derive-session-context.mjs +107 -107
- package/content/skills/design-and-plan/SKILL.md +6 -4
- package/content/skills/implement-plan/SKILL.md +4 -29
- package/content/skills/implementation-order/implementation-order.mjs +67 -0
- package/content/skills/index-prototypes/SKILL.md +36 -17
- package/content/skills/index-prototypes/index-prototypes.mjs +14 -14
- package/content/skills/investigate-spike/SKILL.md +48 -0
- package/content/skills/kb-add/SKILL.md +12 -3
- package/content/skills/kb-add/kb-add.mjs +88 -88
- package/content/skills/kb-curate/kb-curate.mjs +88 -88
- package/content/skills/kb-edit/kb-edit.mjs +90 -90
- package/content/skills/kb-retrieve/SKILL.md +8 -3
- package/content/skills/kb-retrieve/kb-retrieve.mjs +104 -104
- package/content/skills/kb-retrieve-events/SKILL.md +8 -3
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +113 -113
- package/content/skills/kb-update-events/kb-update-events.mjs +92 -92
- package/content/skills/lesson-clusters/lesson-clusters.mjs +102 -102
- package/content/skills/list-implementation-order/SKILL.md +23 -0
- package/content/skills/merge-bb-pr/SKILL.md +31 -8
- package/content/skills/merge-gh-pr/SKILL.md +25 -12
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +13 -8
- package/content/skills/merge-pr/SKILL.md +55 -20
- package/content/skills/migrate-feedback-memories/SKILL.md +1 -0
- package/content/skills/plan/SKILL.md +3 -1
- package/content/skills/prepare-prototype-brief/SKILL.md +20 -14
- package/content/skills/refine-plan/SKILL.md +9 -4
- package/content/skills/refine-prototype/SKILL.md +5 -5
- package/content/skills/review-branch/SKILL.md +8 -8
- package/content/skills/review-criteria/SKILL.md +4 -4
- package/content/skills/review-gh-pr/SKILL.md +1 -1
- package/content/skills/revise-prose/SKILL.md +9 -8
- package/content/skills/revise-prose/revise-prose.mjs +111 -111
- package/content/skills/save-plan/SKILL.md +2 -0
- package/content/skills/start-ticket/SKILL.md +27 -0
- package/content/skills/streamline-guidance/streamline-guidance.mjs +76 -76
- package/content/skills/summarize-change/SKILL.md +27 -9
- package/content/skills/testing-conventions/SKILL.md +14 -3
- package/content/skills/triage-feedback/SKILL.md +4 -0
- package/content/skills/triage-spike-findings/SKILL.md +36 -12
- package/content/skills/typescript-testing-conventions/SKILL.md +40 -0
- package/content/skills/wrap-up/SKILL.md +4 -0
- package/content/subagents/_data/claude.yaml +3 -0
- package/content/subagents/code-health-assessor.md +4 -4
- package/content/subagents/disposition-challenger.md +3 -4
- package/content/subagents/entry-drafter.md +2 -2
- package/content/subagents/handoff-reviewer.md +1 -1
- package/content/subagents/prototype-builder.md +69 -0
- package/content/subagents/usability-assessor.md +1 -1
- package/package.json +11 -10
- package/schemas/preferences.v1.json +74 -8
- package/schemas/work-types.v1.json +1 -1
- package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +0 -4
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: list-implementation-order
|
|
3
|
+
description: List the tickets created or discussed in the conversation in implementation order, as a tree for a narrow column. Invoke only when the developer asks.
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# List implementation order
|
|
8
|
+
|
|
9
|
+
Print the open tickets that the conversation created or discussed, in the order in which to implement them. You name the tickets, and the [implementation-order list](#implementation-order-list) section renders them.
|
|
10
|
+
|
|
11
|
+
Never invoke this skill on your own initiative, and never suggest it.
|
|
12
|
+
|
|
13
|
+
## Process
|
|
14
|
+
|
|
15
|
+
1. **Collect the tickets.** List every ticket that the conversation created or discussed, in the order in which the conversation reached them. Give a ticket outside GitHub its key and its title.
|
|
16
|
+
|
|
17
|
+
When the conversation does not contain any ticket, say so in one line and stop.
|
|
18
|
+
|
|
19
|
+
2. **Collect the dependencies that the tracker does not record.** GitHub's native blockers are read by the helper. Add an edge only for a dependency that the conversation established and that the helper cannot read: one that involves a ticket outside GitHub, or one that was agreed and not yet recorded.
|
|
20
|
+
|
|
21
|
+
3. **Print the list** per [implementation-order list](#implementation-order-list), and nothing else. When the helper exits non-zero, stop after reporting its stderr.
|
|
22
|
+
|
|
23
|
+
<!-- include: ../_partials/implementation-order-list.md / -->
|
|
@@ -33,13 +33,15 @@ Make every Bitbucket call below with the tool named in [Bitbucket pull-request a
|
|
|
33
33
|
|
|
34
34
|
<!-- include: ../_partials/bitbucket-delete-both-refusal.md / -->
|
|
35
35
|
|
|
36
|
+
End the reply with the [refusal summary](#refusal-summary), with that refusal as its reason.
|
|
37
|
+
|
|
36
38
|
`remote` and `none` map to `closeSourceBranch` in step 4.
|
|
37
39
|
|
|
38
40
|
### 2. Fetch and validate PR state
|
|
39
41
|
|
|
40
|
-
Issue one `action: "get"` call with `prId` set to `pr_number`, per [Reading a pull request](../_data/bitbucket-pr-access.md#reading-a-pull-request). Capture `state`, `source.branch.name`, `source.repository.full_name`, and `links.html.href`.
|
|
42
|
+
Issue one `action: "get"` call with `prId` set to `pr_number`, per [Reading a pull request](../_data/bitbucket-pr-access.md#reading-a-pull-request). Capture `state`, `source.branch.name`, `source.repository.full_name`, `destination.branch.name`, and `links.html.href`.
|
|
41
43
|
|
|
42
|
-
Refuse the merge when `state` is not `OPEN`, naming the state: "PR #{n} is {state} (not OPEN); cannot merge." The refusal covers `MERGED`, `DECLINED`, and `SUPERSEDED`. When `state` is missing from the response, **fail closed**: Refuse with "Cannot determine merge state for PR #{n}; verify and merge manually."
|
|
44
|
+
On each refusal in this step and in step 3, stop, and end the reply with the [refusal summary](#refusal-summary), with the refusal's text as its reason. Refuse the merge when `state` is not `OPEN`, naming the state: "PR #{n} is {state} (not OPEN); cannot merge." The refusal covers `MERGED`, `DECLINED`, and `SUPERSEDED`. When `state` is missing from the response, **fail closed**: Refuse with "Cannot determine merge state for PR #{n}; verify and merge manually."
|
|
43
45
|
|
|
44
46
|
Bitbucket does not expose a counterpart to GitHub's `mergeable` or `mergeStateStatus`, and this step does not invent one. The merge call in step 4 reports a conflict, a failing required check, or a missing required approval as its own error, before anything is published.
|
|
45
47
|
|
|
@@ -75,7 +77,7 @@ Passing a composed title for `merge_commit` diverges from `merge-gh-pr`, which o
|
|
|
75
77
|
|
|
76
78
|
Set `closeSourceBranch` to `true` for `deletion_strategy: remote` and `false` for `none`.
|
|
77
79
|
|
|
78
|
-
Call `action: "merge"` with `prId`, `mergeStrategy`, `message` (except for `rebase_fast_forward`), and `closeSourceBranch`. If the call fails,
|
|
80
|
+
Call `action: "merge"` with `prId`, `mergeStrategy`, `message` (except for `rebase_fast_forward`), and `closeSourceBranch`. If the call fails, stop, and end the reply with the [refusal summary](#refusal-summary), with the tool's error as its reason. Do not retry, and do not fall back to another strategy.
|
|
79
81
|
|
|
80
82
|
### 5. Capture the merge result
|
|
81
83
|
|
|
@@ -125,12 +127,33 @@ Branch: {source.branch.name}
|
|
|
125
127
|
|
|
126
128
|
## Completion
|
|
127
129
|
|
|
130
|
+
Report `Artifact saved: {artifact path}` on a line of its own, then print these lines as the last element of the reply:
|
|
131
|
+
|
|
128
132
|
```
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
133
|
+
---
|
|
134
|
+
|
|
135
|
+
## 🔀 Merged into {destination.branch.name} · {strategy name} · {first 7 characters of merge_commit.hash, or unavailable}
|
|
136
|
+
|
|
137
|
+
{title line}
|
|
138
|
+
PR: {links.html.href}
|
|
139
|
+
Remote branch {source.branch.name}: {🗑️ Deleted for deletion_strategy: remote, ⏸️ Kept for none}
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
The strategy name is the result's name: `squash`, `merge commit` for `merge`, and `rebase`. The title line is `Commit title: {title}` for `squash` and `merge`, whose `message` step 4 composes from `title`, and `Last commit title: unavailable` for `rebase`, which submits no message; the tool does not expose a read of the commit. Separate the lines with single newlines, and keep the blank line below the rule and the one below the heading. Print the lines exactly as this template renders them, and do not write any sentence before them that restates the outcome: The heading states it, and the bottom of the reply is the part that the terminal shows first. `merge-pr` places them directly above an action-items block when its turn has an ask.
|
|
143
|
+
|
|
144
|
+
### Refusal summary
|
|
145
|
+
|
|
146
|
+
A refusal in steps 1 to 4 means that the PR was not merged. End the reply with these lines, in place of the summary above:
|
|
147
|
+
|
|
134
148
|
```
|
|
149
|
+
---
|
|
150
|
+
|
|
151
|
+
## ❌ Not merged
|
|
152
|
+
|
|
153
|
+
PR: {links.html.href, or #{pr_number} when step 2 did not read it}
|
|
154
|
+
Reason: {reason}
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
Keep the lines single-spaced: When the reason spans several lines, drop its blank lines.
|
|
135
158
|
|
|
136
159
|
Local state is intentionally left untouched; removing the merged branch is left to the user. Do not append local-branch cleanup steps or advice. Do not report this state to the user.
|
|
@@ -28,14 +28,16 @@ Internal delegate that merges a pull request on GitHub. Called by `merge-pr` wit
|
|
|
28
28
|
Use a single `gh pr view` call to fetch every field needed for validation:
|
|
29
29
|
|
|
30
30
|
```bash
|
|
31
|
-
gh pr view {pr_number} --json state,isDraft,mergeable,mergeStateStatus,reviewDecision,headRefName,isCrossRepository,baseRefName
|
|
31
|
+
gh pr view {pr_number} --json state,isDraft,mergeable,mergeStateStatus,reviewDecision,headRefName,isCrossRepository,baseRefName,url
|
|
32
32
|
```
|
|
33
33
|
|
|
34
34
|
Parse the JSON with a real parser (`python3 -c "import sys,json; ..."` or `jq`). Do not regex-extract.
|
|
35
35
|
|
|
36
|
+
If the call fails, stop, and end the reply with the [refusal summary](#refusal-summary), with `gh`'s stderr as the reason.
|
|
37
|
+
|
|
36
38
|
### 2. Run pre-merge checks
|
|
37
39
|
|
|
38
|
-
Refuse the merge with a specific reason on any of the following. On each refusal,
|
|
40
|
+
Refuse the merge with a specific reason on any of the following. On each refusal, stop, and end the reply with the [refusal summary](#refusal-summary), with the reason below as its reason:
|
|
39
41
|
|
|
40
42
|
| Field | Failure condition | Refusal reason |
|
|
41
43
|
| ------------------ | ------------------------------------------------------------ | --------------------------------------------------------------------------- |
|
|
@@ -69,13 +71,13 @@ git fetch origin
|
|
|
69
71
|
git rev-list --left-right --count "origin/{headRefName}...HEAD"
|
|
70
72
|
```
|
|
71
73
|
|
|
72
|
-
If the counts differ from `0\t0`, refuse: "Local branch is out of sync with `origin/{headRefName}` (ahead {a}, behind {b}); push or pull before merging."
|
|
74
|
+
If the counts differ from `0\t0`, refuse with the [refusal summary](#refusal-summary): "Local branch is out of sync with `origin/{headRefName}` (ahead {a}, behind {b}); push or pull before merging."
|
|
73
75
|
|
|
74
76
|
### 4. Write the title and body to scratch files
|
|
75
77
|
|
|
76
78
|
Write `body` to a scratch file per [gh body file](#gh-body-file), naming it for the PR (`gh-body-pr{pr_number}-{timestamp}.md`). When `strategy` is `squash`, also write `title` to `gh-title-pr{pr_number}-{timestamp}.txt` in the same directory. Do not inline either into a command.
|
|
77
79
|
|
|
78
|
-
**Read both files back before step 5.** Read each path that step 5 is about to pass, with the {tool:Read} tool rather than a shell command, and compare its content against the `body` and `title` received by this delegate; a single trailing newline in the title file is ignored. Refuse when either differs, naming the PR and the path: "Body file for PR #{n} at {path} is not the approved merge body." or "Title file for PR #{n} at {path} is not the approved merge title." A squash merge onto a protected default branch publishes a commit message that cannot be amended, so this is the last point at which a wrong message can be caught. Read the paths being passed rather than the ones written earlier in this step, so that a path left over from another PR is caught rather than confirmed.
|
|
80
|
+
**Read both files back before step 5.** Read each path that step 5 is about to pass, with the {tool:Read} tool rather than a shell command, and compare its content against the `body` and `title` received by this delegate; a single trailing newline in the title file is ignored. Refuse with the [refusal summary](#refusal-summary) when either differs, naming the PR and the path: "Body file for PR #{n} at {path} is not the approved merge body." or "Title file for PR #{n} at {path} is not the approved merge title." A squash merge onto a protected default branch publishes a commit message that cannot be amended, so this is the last point at which a wrong message can be caught. Read the paths being passed rather than the ones written earlier in this step, so that a path left over from another PR is caught rather than confirmed.
|
|
79
81
|
|
|
80
82
|
### 5. Merge and delete the branch
|
|
81
83
|
|
|
@@ -99,19 +101,22 @@ On success, the helper exits 0 and prints JSON on stdout:
|
|
|
99
101
|
"headRefName": "feature/cache",
|
|
100
102
|
"mergeCommit": { "oid": "abc123" },
|
|
101
103
|
"mergedAt": "2026-09-28T22:00:00Z",
|
|
104
|
+
"summary": "---\n\n## 🔀 Merged into main · squash · abc1234\n\nCommit title: widgets|feat: Cache the lookup (#42)\nPR: https://github.com/acme/widgets/pull/42\nRemote branch feature/cache: 🗑️ Deleted",
|
|
102
105
|
"url": "https://github.com/acme/widgets/pull/42"
|
|
103
106
|
}
|
|
104
107
|
```
|
|
105
108
|
|
|
109
|
+
`summary` contains the outcome lines that [Completion](#completion) prints. Its commit-title line contains the subject of the commit that the merge created, which the helper reads from GitHub after the merge. When it cannot read the subject, it writes a warning on stderr and shows the submitted title, or `unavailable` for `merge` and `rebase`, which do not submit one; the merge still succeeded, so continue.
|
|
110
|
+
|
|
106
111
|
`branchDeletion` is one of these values:
|
|
107
112
|
|
|
108
113
|
- `deleted`: The helper deleted the branch.
|
|
109
114
|
- `already-deleted`: The branch or its fork was already gone, for example because the repository deletes branches on merge.
|
|
110
|
-
- `failed`: A warning on stderr gives the reason. The merge still succeeded, so
|
|
115
|
+
- `failed`: A warning on stderr gives the reason, which the summary's branch line repeats. The merge still succeeded, so continue.
|
|
111
116
|
- `by-gh`: The deletion strategy was `both`, and `gh pr merge --delete-branch` handled the deletion.
|
|
112
117
|
- `not-requested`: The deletion strategy was `none`.
|
|
113
118
|
|
|
114
|
-
When the helper exits non-zero,
|
|
119
|
+
When the helper exits non-zero, it still prints JSON on stdout, containing only `summary`. Stop, and end the reply with that `summary`, printed verbatim. Its reason contains the helper's stderr, so do not print the stderr as well. This covers a refused input file, a failed `gh pr merge` (whose stderr the helper passes on), a PR that is not `MERGED` after `gh` accepted the merge, such as a PR placed in a merge queue, and a PR whose state cannot be read after `gh` accepted the merge, whose summary is headed `## ⚠️ Merge not confirmed`. Do not retry, and do not bypass with `--admin`.
|
|
115
120
|
|
|
116
121
|
### 6. Save merge artifact
|
|
117
122
|
|
|
@@ -153,15 +158,23 @@ Branch: {headRefName}
|
|
|
153
158
|
|
|
154
159
|
## Completion
|
|
155
160
|
|
|
161
|
+
Report `Artifact saved: {artifact path}` on a line of its own, then print the helper's `summary` verbatim, as the last element of the reply. Do not write any sentence before it that restates the outcome: The summary's heading states it, and the bottom of the reply is the part that the terminal shows first. `merge-pr` places the summary directly above an action-items block when its turn has an ask.
|
|
162
|
+
|
|
163
|
+
### Refusal summary
|
|
164
|
+
|
|
165
|
+
A refusal in steps 1 to 4 means that the PR was not merged. End the reply with these lines, in place of the summary that the helper would have printed:
|
|
166
|
+
|
|
156
167
|
```
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
168
|
+
---
|
|
169
|
+
|
|
170
|
+
## ❌ Not merged
|
|
171
|
+
|
|
172
|
+
PR: {url, or #{pr_number} when step 1 did not read it}
|
|
173
|
+
Reason: {reason}
|
|
163
174
|
```
|
|
164
175
|
|
|
176
|
+
Keep the lines single-spaced: When the reason spans several lines, drop its blank lines.
|
|
177
|
+
|
|
165
178
|
Local state is intentionally left untouched; removing the merged branch is left to the user. Do not append local-branch cleanup steps or advice. Do not report this state to the user.
|
|
166
179
|
|
|
167
180
|
<!-- include: ../_partials/gh-body-file.md / -->
|
|
@@ -1,10 +1,15 @@
|
|
|
1
1
|
import { createRequire as __cjsCreateRequire } from 'node:module';
|
|
2
2
|
const require = __cjsCreateRequire(import.meta.url);
|
|
3
|
-
var
|
|
4
|
-
`),!0}}o(
|
|
5
|
-
${n.stderr}
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
`);
|
|
9
|
-
`)}
|
|
10
|
-
`)
|
|
3
|
+
var V=Object.defineProperty;var o=(e,t)=>V(e,"name",{value:t,configurable:!0});import{execFile as X}from"node:child_process";import{readFileSync as Y,statSync as Q}from"node:fs";import m from"node:process";import{promisify as Z}from"node:util";function w(e){return e instanceof Error||Object.prototype.toString.call(e)==="[object Error]"}o(w,"isError");function l(e){try{return w(e)&&typeof e.message=="string"&&e.message!==""?e.message:String(e)}catch{return"[unstringifiable value]"}}o(l,"describeError");import{realpathSync as E}from"node:fs";import x from"node:process";import{fileURLToPath as v}from"node:url";function N(e,t){let r=x.argv[1];if(r===void 0)return!1;try{return E(v(e))===E(r)}catch(n){return x.stderr.write(`${t}: warning: could not determine entry point: ${l(n)}
|
|
4
|
+
`),!0}}o(N,"isEntryPoint");function $(e,t){let r=[],n=[];for(let i=0;i<e.length;i+=1){let s=e[i];if(s===void 0)continue;if(!s.startsWith("--")){r.push(s);continue}let a=I(s,t);if(a===null)throw new Error(`unknown flag: ${s}`);let{spec:d,inlineValue:u}=a;if(!d.takesValue){if(u!==null)throw new Error(`--${d.name} does not take a value`);n.push({name:d.name,value:null});continue}if(u!==null){n.push({name:d.name,value:u});continue}let f=e[i+1]??null;if(f===null||f.startsWith("--"))throw new Error(`--${d.name} requires a value`);n.push({name:d.name,value:f}),i+=1}return{positionals:r,flags:n}}o($,"scanFlags");function S(e){let t={};for(let{name:r,value:n}of e)n!==null&&(t[r]=n);return t}o(S,"valueFlagMap");function I(e,t){for(let r of t)for(let n of[r.name,...r.aliases??[]]){let i=`--${n}`;if(e===i)return{spec:r,inlineValue:null};if(e.startsWith(`${i}=`))return{spec:r,inlineValue:e.slice(i.length+1)}}return null}o(I,"matchFlag");function j(e,t){return k(e)&&e.code===t}o(j,"isErrorCode");function M(e){return j(e,"ENOENT")}o(M,"isEnoent");function c(e){return k(e)&&!Array.isArray(e)}o(c,"isRecord");function k(e){return typeof e=="object"&&e!==null}o(k,"isObject");var D=["both","none","remote"],F=["merge","rebase","squash"];var L="state,mergeCommit,url,mergedAt,baseRefName,headRefName,headRepository,headRepositoryOwner";function g(e,t){let r=e===void 0?[]:[`PR: ${e}`];return y("## \u274C Not merged",[...r,`Reason: ${h(t)}`])}o(g,"formatRefusalSummary");async function C(e,t){let r=await t(q(e));if(r.exitCode!==0){let u=r.stderr.trim()||`\`gh pr merge\` exited with code ${r.exitCode}.`;return{ok:!1,exitCode:r.exitCode,stderr:r.stderr,summary:g(`#${e.prNumber}`,u)}}let n=await b(t,["pr","view",String(e.prNumber),"--json",L]);if(n.exitCode!==0)return{ok:!1,exitCode:n.exitCode,stderr:`PR #${e.prNumber} merge ran, but its state could not be read; branch not deleted.
|
|
5
|
+
${n.stderr}`,summary:T(e.prNumber,n.stderr)};let i=z(n.stdout);if(i.kind==="unreadable")return{ok:!1,exitCode:1,stderr:`PR #${e.prNumber} merge ran, but its state could not be read; branch not deleted.
|
|
6
|
+
`,summary:T(e.prNumber,"")};if(i.kind==="not-merged"){let u=`PR #${e.prNumber} is ${i.state} after the merge command, so a merge queue may hold it. The branch was not deleted.`;return{ok:!1,exitCode:1,stderr:`PR #${e.prNumber} is ${i.state} after merge; branch not deleted.
|
|
7
|
+
`,summary:g(i.url??`#${e.prNumber}`,u)}}let s=[],a=await U(e.deletionStrategy,i,t,s),d=await K(e,i.oid,t,s);return{ok:!0,result:{branchDeletion:a.branchDeletion,headRefName:i.headRefName,mergeCommit:{oid:i.oid},mergedAt:i.mergedAt,summary:J(e,i,a,d),url:i.url},warnings:s}}o(C,"mergePullRequest");var _="repos/{owner}/{repo}/commits",B={merge:"merge commit",rebase:"rebase",squash:"squash"};function q(e){let t=["pr","merge",String(e.prNumber),`--${e.strategy}`];return e.strategy==="squash"&&e.title!==void 0&&t.push("--subject",e.title),e.strategy!=="rebase"&&e.bodyPath!==void 0&&t.push("--body-file",e.bodyPath),e.deletionStrategy==="both"&&t.push("--delete-branch"),t}o(q,"buildMergeArgs");async function U(e,t,r,n){if(e==="none")return{branchDeletion:"not-requested"};if(e==="both")return{branchDeletion:"by-gh"};if(t.headOwner===void 0||t.headRepo===void 0)return{branchDeletion:"already-deleted"};let i=t.headRefName.split("/").map(encodeURIComponent).join("/"),s=`repos/${encodeURIComponent(t.headOwner)}/${encodeURIComponent(t.headRepo)}/git/refs/heads/${i}`,a=await b(r,["api","-X","DELETE",s]);if(a.exitCode===0)return{branchDeletion:"deleted"};if(a.stderr.includes("HTTP 422")&&a.stderr.includes("Reference does not exist"))return{branchDeletion:"already-deleted"};let d=a.stderr.trim();return n.push(`warning: Failed to delete remote branch '${t.headRefName}': ${d}`),{branchDeletion:"failed",reason:d}}o(U,"deleteHeadBranch");function W(e,t){return`${t.branchDeletion==="by-gh"?`Local and remote branch ${e}`:`Remote branch ${e}`}: ${H(t)}`}o(W,"formatDeletionLine");function H(e){switch(e.branchDeletion){case"already-deleted":return"\u{1F5D1}\uFE0F Already deleted";case"by-gh":case"deleted":return"\u{1F5D1}\uFE0F Deleted";case"failed":return`\u26A0\uFE0F Not deleted: ${h(e.reason??"unknown error")}`;case"not-requested":return"\u23F8\uFE0F Kept"}}o(H,"formatDeletionState");function J(e,t,r,n){let i=t.baseRefName===void 0?"":` into ${t.baseRefName}`,s=e.strategy==="rebase"?"Last commit title":"Commit title";return y(`## \u{1F500} Merged${i} \xB7 ${B[e.strategy]} \xB7 ${t.oid.slice(0,7)}`,[`${s}: ${n}`,`PR: ${t.url}`,W(t.headRefName,r)])}o(J,"formatMergedSummary");function y(e,t){return["---","",e,"",...t].join(`
|
|
8
|
+
`)}o(y,"formatSummary");function T(e,t){let r="The merge command succeeded, but the PR's state could not be read. The branch was not deleted.",n=t.trim();return y("## \u26A0\uFE0F Merge not confirmed",[`PR: #${e}`,`Reason: ${n.length>0?`${r}
|
|
9
|
+
${h(n)}`:r}`])}o(T,"formatUnconfirmedSummary");function h(e){return e.trim().replaceAll(/\n(?:[\t ]*\n)+/g,`
|
|
10
|
+
`)}o(h,"normalizeBlock");function z(e){let t;try{t=JSON.parse(e)}catch{return{kind:"unreadable"}}if(!c(t)||typeof t.state!="string")return{kind:"unreadable"};if(t.state!=="MERGED")return{kind:"not-merged",state:t.state,url:p(t.url)};let{headRefName:r,mergeCommit:n,mergedAt:i,url:s}=t,a=c(n)?n.oid:void 0;return typeof r!="string"||typeof i!="string"||typeof a!="string"||typeof s!="string"?{kind:"unreadable"}:{kind:"merged",baseRefName:p(t.baseRefName),headOwner:P(t.headRepositoryOwner,"login"),headRefName:r,headRepo:P(t.headRepository,"name"),mergedAt:i,oid:a,url:s}}o(z,"parseMergedView");async function K(e,t,r,n){let i=await b(r,["api",`${_}/${t}`,"--jq",".commit.message"]),s=i.exitCode===0?(i.stdout.trim().split(`
|
|
11
|
+
`,1)[0]??"").trim():"";if(s.length>0)return s;let a=i.exitCode===0?"empty commit message":i.stderr.trim()||`\`gh api\` exited with code ${i.exitCode}.`;return n.push(`warning: Could not read the subject of merge commit ${t}: ${a}`),e.title??"unavailable"}o(K,"readCommitTitle");function P(e,t){return c(e)?p(e[t]):void 0}o(P,"readNamedField");function p(e){return typeof e=="string"&&e.length>0?e:void 0}o(p,"readNonEmptyString");async function b(e,t){try{return await e(t)}catch(r){return{exitCode:1,stderr:`${l(r)}
|
|
12
|
+
`,stdout:""}}}o(b,"runGhAfterMerge");var ee=Z(X),te=[{name:"body-file",takesValue:!0},{name:"delete",takesValue:!0},{name:"pr",takesValue:!0},{name:"strategy",takesValue:!0},{name:"title-file",takesValue:!0}];async function re(){let e=m.argv.slice(2);try{let t=ie(ne(e)),r=await C(t,se);r.ok||(m.stderr.write(r.stderr),R({summary:r.summary}),m.exit(r.exitCode));for(let n of r.warnings)m.stderr.write(`${n}
|
|
13
|
+
`);R(r.result)}catch(t){let r=l(t);m.stderr.write(`merge-gh-pr: ${r}
|
|
14
|
+
`);let n=ae(e);R({summary:g(n===void 0?void 0:`#${n}`,r)}),m.exit(1)}}o(re,"main");N(import.meta.url,"merge-gh-pr")&&await re();function G(e){try{let t=Q(e);return t.isFile()&&t.size>0}catch{return!1}}o(G,"isNonEmptyFile");function ne(e){let{flags:t,positionals:r}=$(e,te);if(r.length>0)throw new Error(`unexpected argument: ${r.join(" ")}`);let n=S(t),i=O(n,"pr");if(!/^[1-9]\d*$/.test(i))throw new Error(`--pr must be a positive integer, got '${i}'`);return{bodyFile:n["body-file"],deletionStrategy:A(n,"delete",D),prNumber:Number(i),strategy:A(n,"strategy",F),titleFile:n["title-file"]}}o(ne,"parseArgs");function ie(e){let t=e.strategy!=="rebase",r=e.strategy==="squash",n;if(r&&(n=oe(e.titleFile)),t){if(e.bodyFile===void 0)throw new Error(`--body-file is required for --strategy ${e.strategy}`);if(!G(e.bodyFile))throw new Error(`Body file missing or empty: ${e.bodyFile}`)}return{bodyPath:t?e.bodyFile:void 0,deletionStrategy:e.deletionStrategy,prNumber:e.prNumber,strategy:e.strategy,title:n}}o(ie,"readRequest");function oe(e){if(e===void 0)throw new Error("--title-file is required for --strategy squash");if(!G(e))throw new Error(`Title file missing or empty: ${e}`);let t=Y(e,"utf8").replace(/\r?\n$/,"");if(t.length===0)throw new Error(`Title file missing or empty: ${e}`);return t}o(oe,"readTitle");function A(e,t,r){let n=O(e,t),i=r.find(s=>s===n);if(i===void 0)throw new Error(`--${t} must be one of ${r.join(", ")}, got '${n}'`);return i}o(A,"requireMember");function O(e,t){let r=e[t];if(r===void 0)throw new Error(`--${t} is required`);return r}o(O,"requireValue");async function se(e){try{let{stderr:t,stdout:r}=await ee("gh",e,{maxBuffer:16777216});return{exitCode:0,stderr:t,stdout:r}}catch(t){if(M(t))throw new Error("gh is not installed or not on PATH",{cause:t});if(c(t)&&typeof t.code=="number"&&typeof t.stderr=="string"&&typeof t.stdout=="string")return{exitCode:t.code,stderr:t.stderr,stdout:t.stdout};throw t}}o(se,"runGh");function ae(e){for(let[t,r]of e.entries()){let n=r==="--pr"?e[t+1]:r.startsWith("--pr=")?r.slice(5):void 0;if(n!==void 0)return/^[1-9]\d*$/.test(n)?Number(n):void 0}}o(ae,"scanPrNumber");function R(e){m.stdout.write(`${JSON.stringify(e,null,2)}
|
|
15
|
+
`)}o(R,"writeJson");
|
|
@@ -10,24 +10,25 @@ Merge a pull request on the appropriate platform. `describe-change.mjs` resolves
|
|
|
10
10
|
|
|
11
11
|
## Optional arguments
|
|
12
12
|
|
|
13
|
-
| Flag | Effect | Default
|
|
14
|
-
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
15
|
-
| `--pr {n}` | Merge PR `{n}` instead of the PR for the current branch. | PR for the current branch
|
|
16
|
-
| `--scope {scope}` | Override the scope. Outranks the PR's `change-record` block and every other source; `*` merges without a scope. | resolved in step 3
|
|
17
|
-
| `--type {type}` | Override the work type, spelled bare (`feat`, not `feat!`). Outranks the PR's `change-record` block and every other source, and keeps the resolved marker. | resolved in step 3
|
|
18
|
-
| `--breaking`, `--no-breaking` | Merge as breaking, or as not breaking. Outranks the PR's `change-record` block and every other source. | resolved in step 3
|
|
19
|
-
| `--strategy {s}` | Override the merge strategy: `squash`, `merge`, or `rebase`. | `
|
|
20
|
-
| `--delete {v}` | Override branch deletion: `both`, `remote`, or `none`. `both` is GitHub-only. | `
|
|
13
|
+
| Flag | Effect | Default |
|
|
14
|
+
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
|
|
15
|
+
| `--pr {n}` | Merge PR `{n}` instead of the PR for the current branch. | PR for the current branch |
|
|
16
|
+
| `--scope {scope}` | Override the scope. Outranks the PR's `change-record` block and every other source; `*` merges without a scope. | resolved in step 3 |
|
|
17
|
+
| `--type {type}` | Override the work type, spelled bare (`feat`, not `feat!`). Outranks the PR's `change-record` block and every other source, and keeps the resolved marker. | resolved in step 3 |
|
|
18
|
+
| `--breaking`, `--no-breaking` | Merge as breaking, or as not breaking. Outranks the PR's `change-record` block and every other source. | resolved in step 3 |
|
|
19
|
+
| `--strategy {s}` | Override the merge strategy: `squash`, `merge`, or `rebase`. | per `merge_strategy` |
|
|
20
|
+
| `--delete {v}` | Override branch deletion: `both`, `remote`, or `none`. `both` is GitHub-only. | per `merge_deletion_strategy` |
|
|
21
|
+
| `--confirm` | Show the approval gate even when `merge.approval` is `auto`. | per `merge_approval` |
|
|
21
22
|
|
|
22
|
-
##
|
|
23
|
+
## Preference keys
|
|
23
24
|
|
|
24
|
-
|
|
25
|
+
Three keys in `.agents/preferences.yaml` and `~/.agents/preferences.yaml` set this skill's defaults: `merge.approval` (step 6), `merge.strategy`, and `merge.deletion_strategy` (step 4). Each value resolves from the CLI flag, then the project file, then the user file, then the built-in default (`ask`, `squash`, `remote`). `derive-session-context` resolves the files and reports `merge_approval`, `merge_strategy`, and `merge_deletion_strategy`; it fails on a value outside the accepted set, naming the file, the key, and the accepted values, which stops the run at step 1. The guidance package's `docs/preferences.md` lists the accepted values.
|
|
25
26
|
|
|
26
27
|
## Process
|
|
27
28
|
|
|
28
29
|
### 1. Get session context
|
|
29
30
|
|
|
30
|
-
Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash. The bundle emits the session-context manifest JSON to stdout; extract `ticket_ref`, `branch_name`, `default_branch`, `scm`, `project_slug`, `ticket_id`, `artifact_base_dir`, and `
|
|
31
|
+
Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash. The bundle emits the session-context manifest JSON to stdout; extract `ticket_ref`, `branch_name`, `default_branch`, `scm`, `project_slug`, `ticket_id`, `artifact_base_dir`, `pr_url`, `merge_approval`, `merge_strategy`, and `merge_deletion_strategy` from it.
|
|
31
32
|
|
|
32
33
|
### 2. Resolve the PR
|
|
33
34
|
|
|
@@ -38,15 +39,15 @@ Read the PR's metadata for the steps below, dispatching on `scm`:
|
|
|
38
39
|
- **`"github"`**:
|
|
39
40
|
|
|
40
41
|
```bash
|
|
41
|
-
gh pr view {pr} --json number,title,body,labels,headRefName,headRefOid,baseRefName,isCrossRepository,url
|
|
42
|
+
gh pr view {pr} --json number,title,body,labels,headRefName,headRefOid,baseRefName,isCrossRepository,mergeStateStatus,url
|
|
42
43
|
```
|
|
43
44
|
|
|
44
|
-
- **`"bitbucket"`**: Issue an `action: "get"` call per [Bitbucket pull-request access](../_data/bitbucket-pr-access.md), then map its fields onto the same names that the steps below use: `description` to `body`, `source.branch.name` to `headRefName`, `source.commit.hash` to `headRefOid`, `destination.branch.name` to `baseRefName`, `links.html.href` to `url`, and an empty array to `labels`. `isCrossRepository` is true when `source.repository.full_name` names a repository other than the PR's own.
|
|
45
|
+
- **`"bitbucket"`**: Issue an `action: "get"` call per [Bitbucket pull-request access](../_data/bitbucket-pr-access.md), then map its fields onto the same names that the steps below use: `description` to `body`, `source.branch.name` to `headRefName`, `source.commit.hash` to `headRefOid`, `destination.branch.name` to `baseRefName`, `links.html.href` to `url`, and an empty array to `labels`. `isCrossRepository` is true when `source.repository.full_name` names a repository other than the PR's own. Bitbucket does not report a counterpart to `mergeStateStatus`, so leave it unset.
|
|
45
46
|
- **Unknown or missing**: Ask the user which platform to use, matching step 7's behavior.
|
|
46
47
|
|
|
47
48
|
If this step cannot resolve or discover a PR, stop with: "No open PR found for branch `{branch_name}`. Create one with `{skill:create-pr}` first."
|
|
48
49
|
|
|
49
|
-
Capture `title` (PR title), `body` (PR body), `labels` (label objects), `number`, `headRefName` (head branch), `headRefOid` (head commit), `baseRefName` (base branch), and `
|
|
50
|
+
Capture `title` (PR title), `body` (PR body), `labels` (label objects), `number`, `headRefName` (head branch), `headRefOid` (head commit), `baseRefName` (base branch), `isCrossRepository`, and `mergeStateStatus` from the response. The steps below use them.
|
|
50
51
|
|
|
51
52
|
Then fetch the PR's base branch and head, so that step 3 reads the PR's own commits whichever branch is checked out. `{remote}` is the remote that `default_branch` names (`origin` in `origin/main`):
|
|
52
53
|
|
|
@@ -89,7 +90,7 @@ The guard keeps a failed read out of the merge. The redirect above truncates the
|
|
|
89
90
|
|
|
90
91
|
Pass each PR label from step 2 as a separate `--pr-label` flag. Pass `--ticket-ref` only when `ticket_ref` from session context is non-null and `headRefName` is `branch_name`, since a PR merged from another branch's checkout belongs to another ticket; the helper uses that reference only when the PR title contains none. Pass this skill's `--scope`, `--type`, `--breaking`, and `--no-breaking` as `--override-scope`, `--override-type`, `--override-breaking`, and `--no-override-breaking`, omitting each one that was not given.
|
|
91
92
|
|
|
92
|
-
If this step's first run exits non-zero, or the helper is not found, stop with its message. Do not compose a title or body without it. Step 8's re-read stops the same way, since the failure there does not come from any answer.
|
|
93
|
+
If this step's first run exits non-zero, or the helper is not found, stop with its message. Do not compose a title or body without it. Step 8's re-read stops the same way, since the failure there does not come from any answer, and ends the reply with the [refusal summary](#11-report-the-outcome).
|
|
93
94
|
|
|
94
95
|
A re-run driven by a decision or an answer at step 6's gate does not stop the skill, and neither does a refused `amend-entry`. Report the helper's message and return to the decision or the question that produced the value: The refusal is in the value, and the resolution already in hand is still good. A type spelled with `!` is that case, which step 6 maps rather than passes through.
|
|
95
96
|
|
|
@@ -130,8 +131,8 @@ On no, and when `{skill:add-change-record}` stopped for any of its own reasons,
|
|
|
130
131
|
### 4. Resolve strategy and deletion strategy
|
|
131
132
|
|
|
132
133
|
```
|
|
133
|
-
resolveStrategy(cliOverride): return cliOverride ??
|
|
134
|
-
resolveDeletionStrategy(cliOverride): return cliOverride ??
|
|
134
|
+
resolveStrategy(cliOverride): return cliOverride ?? merge_strategy
|
|
135
|
+
resolveDeletionStrategy(cliOverride): return cliOverride ?? merge_deletion_strategy
|
|
135
136
|
```
|
|
136
137
|
|
|
137
138
|
`--delete both|remote|none` map directly to the same string values.
|
|
@@ -221,6 +222,17 @@ When asking option-style questions, follow [option format](#option-format). (Rei
|
|
|
221
222
|
|
|
222
223
|
Re-run step 3 after each amendment and each override, with every override added to the override set, until `defects` is empty. Never offer the merge while `defects` contains an item. If an override or an amendment moves the effective record to another tier and step 5 drafted the body, re-run step 5's drafting against the new tier.
|
|
223
224
|
|
|
225
|
+
**Decide whether to ask.** The gate asks unless every one of these holds, in which case the run merges without asking:
|
|
226
|
+
|
|
227
|
+
- `merge_approval` is `auto`, and `--confirm` was not passed.
|
|
228
|
+
- `scm` is `"github"`. Bitbucket does not report merge state, so the gate fails closed there.
|
|
229
|
+
- The report's `notices` is empty.
|
|
230
|
+
- The run did not decide anything of its own: It did not amend an entry in this step, did not add an override in this step on its own decision, and step 5 did not dispatch the drafter. An override passed as a flag and an answer that the developer gave are not the run's decisions, and a work-type test that agrees with the record adds nothing.
|
|
231
|
+
- `effective_record.breaking` is false.
|
|
232
|
+
- `mergeStateStatus` is `CLEAN` or `HAS_HOOKS`. Any other value, or a missing one, means that a check is pending or failing, or that the state is unknown.
|
|
233
|
+
|
|
234
|
+
When the gate asks because one of these failed, do not add a line saying which: The notice, the decision, the `!` in the title, or the merge state already appears in the report.
|
|
235
|
+
|
|
224
236
|
Render the proposed merge to the user:
|
|
225
237
|
|
|
226
238
|
```
|
|
@@ -263,6 +275,12 @@ Render `{confirmation}` so that the ask itself names every destructive side effe
|
|
|
263
275
|
- `remote` → `Merge PR #{pr_number} and delete the remote branch {headRefName}? 👍🏼👎🏼`
|
|
264
276
|
- `both` → `Merge PR #{pr_number} and delete the local and remote branch {headRefName}? 👍🏼👎🏼`
|
|
265
277
|
|
|
278
|
+
When the run merges without asking, render the authorization line in place of the ask, naming the same side effects, and continue to step 7:
|
|
279
|
+
|
|
280
|
+
- `none` → `Merging PR #{pr_number} without confirmation, as merge.approval: auto authorizes.`
|
|
281
|
+
- `remote` → `Merging PR #{pr_number} and deleting the remote branch {headRefName} without confirmation, as merge.approval: auto authorizes.`
|
|
282
|
+
- `both` → `Merging PR #{pr_number} and deleting the local and remote branch {headRefName} without confirmation, as merge.approval: auto authorizes.`
|
|
283
|
+
|
|
266
284
|
Under a `stale-entries` notice, open the ask with `The change record is stale. ` so that the approval names what it accepts: `The change record is stale. Merge PR #{pr_number}? 👍🏼👎🏼`. Under an `absent-block` notice, open it with `The pull request does not contain a change record. ` in the same way.
|
|
267
285
|
|
|
268
286
|
If the user declines, stop without making an API call or writing an artifact. If they approve, continue.
|
|
@@ -297,6 +315,8 @@ The merge block takes a comparison of its own because `body` excludes the `chang
|
|
|
297
315
|
|
|
298
316
|
The window that this step closes is an edit to the PR's title or description. New commits pushed to the branch are not in scope: The re-run reads the commits up to the head commit read in step 2, and a generated body is not recomposed on account of later commits. The delegate's own branch-sync check reports local and remote divergence.
|
|
299
317
|
|
|
318
|
+
When step 6 merged without asking, the approved values are the ones that it rendered: its `merge_title`, the report's `body` and `merge_block`, and the published body. A change then shows the gate, and the rest of the run proceeds as if `merge_approval` were `ask`.
|
|
319
|
+
|
|
300
320
|
If every re-read value matches the approved one, continue to step 9 without saying anything. If any differs, re-render step 6's gate with the new values and ask again, and repeat this step after each approval until the values stop changing. Merging the newest version silently would publish text that the user never approved, which is the same defect from the other direction. If the user declines, stop without merging or writing an artifact, exactly as step 6 does.
|
|
301
321
|
|
|
302
322
|
### 9. Check the published body
|
|
@@ -313,7 +333,7 @@ node {harness_home_dir}/scripts/describe-change.mjs check-merge-body \
|
|
|
313
333
|
|
|
314
334
|
The helper refuses a body whose block is malformed, or whose entry count differs from `--entry-count`. A count of `0` requires the body not to contain a block. [`check-merge-body`](../_data/title-templates.md#check-merge-body) states the rules.
|
|
315
335
|
|
|
316
|
-
If it exits non-zero, stop with its message. Nothing is merged.
|
|
336
|
+
If it exits non-zero, stop, and end the reply with the [refusal summary](#11-report-the-outcome), with its message as the reason. Nothing is merged.
|
|
317
337
|
|
|
318
338
|
### 10. Call delegate
|
|
319
339
|
|
|
@@ -332,11 +352,26 @@ Pass the following inputs to the selected delegate per the delegate interface:
|
|
|
332
352
|
|
|
333
353
|
The orchestrator never passes a title that `defects` blocks, or a `prompt` sentinel, to the delegate: All values are concrete by this point.
|
|
334
354
|
|
|
335
|
-
If the delegate stopped or failed, stop. Otherwise continue.
|
|
355
|
+
If the delegate stopped or failed, stop: Its reply ends with its own summary. Otherwise continue.
|
|
336
356
|
|
|
337
357
|
### 11. Report the outcome
|
|
338
358
|
|
|
339
|
-
Report nothing beyond the delegate's completion report, and invoke nothing but step 12's offer to close the parent. The
|
|
359
|
+
Report nothing beyond the delegate's completion report, and invoke nothing but step 12's offer to close the parent. The completion report ends with the delegate's outcome summary, a rule followed by a heading that states the outcome. Print the summary verbatim, as the last element of the reply, or directly above step 12's action-items block when the turn has an ask. Do not write any sentence of your own before it that restates the outcome: The heading states it, and the bottom of the reply is the part that the terminal shows first.
|
|
360
|
+
|
|
361
|
+
Every stop after the merge is approved, at step 6's gate or by `merge_approval: auto`, ends the reply the same way. When the delegate did not produce the summary, because the run stopped at step 8 or step 9, end the reply with the refusal summary:
|
|
362
|
+
|
|
363
|
+
```
|
|
364
|
+
---
|
|
365
|
+
|
|
366
|
+
## ❌ Not merged
|
|
367
|
+
|
|
368
|
+
PR: {url}
|
|
369
|
+
Reason: {reason}
|
|
370
|
+
```
|
|
371
|
+
|
|
372
|
+
`{url}` is the PR's URL from step 2. Keep the lines single-spaced: When the reason spans several lines, drop its blank lines.
|
|
373
|
+
|
|
374
|
+
A decline at step 6's gate, or at the gate that step 8 re-renders, is the developer's own choice, and keeps the form that those steps state. The merge flow does not record a lede decision or offer to record one; a capture is the author's own request, made whenever they choose.
|
|
340
375
|
|
|
341
376
|
### 12. Offer to close the parent
|
|
342
377
|
|
|
@@ -122,6 +122,7 @@ On approval, run all captures first, then a single deletion pass:
|
|
|
122
122
|
### Composing a capture
|
|
123
123
|
|
|
124
124
|
- `--store @feedback`: The feedback KB is configured in the registry, not chosen per memory.
|
|
125
|
+
- `--shared`: Only after a `shared-store` refusal, and only for a capture that passes the check in `{skill:capture-event}`'s shared-stores rule. A capture that fails the check, or for which the check is not conclusive, is a failed capture: Its memory stays in place, per step 5.
|
|
125
126
|
- `--tags feedback` always; add `,mistake` (i.e. `--tags feedback,mistake`) when the memory recorded a _misapplied_ existing rule, including the violation-of-existing-guidance memory that the Delete rule routes to Capture instead of deleting.
|
|
126
127
|
- `--skill <slug>` when the lesson targets a specific skill.
|
|
127
128
|
- `--impact <low|medium|high|critical>`: Rate on the merits of the memory's content: how much acting on the lesson would improve future behavior. Omit only on a genuine toss-up.
|
|
@@ -17,7 +17,7 @@ Create an implementation plan from a ticket or task. `plan` is the standalone pl
|
|
|
17
17
|
|
|
18
18
|
## Resolve the task source
|
|
19
19
|
|
|
20
|
-
Resolve the task source using the [ticket source resolution](../_data/ticket-source-resolution.md) table, then read the resolved ticket or description and plan against it. When the source resolves to a URL, persist it to the branch manifest per [Stored ticket URL](../_data/ticket-source-resolution.md#stored-ticket-url) so that a later session does not need a ticket argument. Report the ticket's open blockers per [Open blockers](../_data/ticket-source-resolution.md#open-blockers), and continue: A blocker does not stop planning. Then check the branch per [branch currency](../_data/branch-currency.md), reading `branch_name` and `default_branch` from the manifest that `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` emits, and passing the paths that the ticket names. `plan` does not run the staleness check or interactive design Q&A; that ceremony belongs to `design-and-plan`. The one exception is the project's declared stage: Read `project_maturity`, `project_sensitivity`, and `
|
|
20
|
+
Resolve the task source using the [ticket source resolution](../_data/ticket-source-resolution.md) table, then read the resolved ticket or description and plan against it. When the source resolves to a URL, persist it to the branch manifest per [Stored ticket URL](../_data/ticket-source-resolution.md#stored-ticket-url) so that a later session does not need a ticket argument. Report the ticket's open blockers per [Open blockers](../_data/ticket-source-resolution.md#open-blockers), and continue: A blocker does not stop planning. Then check the branch per [branch currency](../_data/branch-currency.md), reading `branch_name` and `default_branch` from the manifest that `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` emits, and passing the paths that the ticket names. `plan` does not run the staleness check or interactive design Q&A; that ceremony belongs to `design-and-plan`. The one exception is the project's declared stage: Read `project_maturity`, `project_sensitivity`, `project_audience`, and `project_stages` from the manifest that `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` emits, take the stage that governs the work's paths, and treat it as the premise of every security, availability, infrastructure, and verification decision per [project stage](../_data/project-stage.md), and ask for each undeclared value at the plan checkpoint, adding a task that declares each answered value. When the source is a free-form description rather than a ticket, plan directly from the description.
|
|
21
21
|
|
|
22
22
|
When the resolved source is a local artifact, read its `provenance.skill`: `design-and-plan` means an interactive design phase ran; another skill means the ticket was authored without one. Remote issues and free-form descriptions do not have provenance.
|
|
23
23
|
|
|
@@ -85,3 +85,5 @@ Follow the options, output format, and recommendation rules in [next-steps optio
|
|
|
85
85
|
<!-- include: ../_partials/next-steps-after-plan.md / -->
|
|
86
86
|
|
|
87
87
|
<!-- include: ../_partials/option-format.md / -->
|
|
88
|
+
|
|
89
|
+
<!-- include: ../_partials/implementation-order-list.md / -->
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: prepare-prototype-brief
|
|
3
|
-
description: Compose the shared brief and the lens sections for a round of competing prototypes, check the brief against the rules that builders over-apply, dispatch one builder per lens, and once the round is judged, take the developer through a decision on every prototype idea. Use when a ticket calls for two or more prototypes of one idea
|
|
3
|
+
description: Compose the shared brief and the lens sections for a round of competing prototypes, check the brief against the rules that builders over-apply, dispatch one builder per lens, and once the round is judged, take the developer through a decision on every prototype idea. Use when a ticket calls for two or more competing prototypes of one idea, or when the developer has judged such a round.
|
|
4
4
|
user-invocable: true
|
|
5
5
|
supported-harnesses: [claude]
|
|
6
6
|
---
|
|
@@ -61,9 +61,15 @@ The failure that this prevents: the lens paragraph reproduced as helper text und
|
|
|
61
61
|
|
|
62
62
|
### Require a salience order
|
|
63
63
|
|
|
64
|
-
Require a salience order in every working view: the current state in one place, the next thing to happen more prominent than the rest, and every action visibly an action. Name {rulebook:accessibility-conventions} and {rulebook:ui-copy-conventions} as the floor, and state that usability outranks restraint. Require that a status repeated on every row be a mark, a column, or a style, not a sentence.
|
|
64
|
+
Require a salience order in every working view: the current state in one place, the next thing to happen more prominent than the rest, and every action visibly an action. Name {rulebook:accessibility-conventions} and {rulebook:ui-copy-conventions} as the floor, including the accessibility rulebook's named-model, placement, toggle, glanceable-state, and button-at-rest rules, and state that usability outranks restraint: A calm or restrained direction never hides a state for which the reader scans. A builder departs from the named model only for a reason, which it reports with its distinctive ideas. Require that a status repeated on every row be a mark, a column, or a style, not a sentence.
|
|
65
65
|
|
|
66
|
-
The failure that this prevents: a page in one colour, in which the operator hunts for the control,
|
|
66
|
+
The failure that this prevents: a page in one colour, in which the operator hunts for the control, "Hidden from the players." written out on every hidden row, and an expiry column in plain text, in which the operator reads every row to find the expired ones.
|
|
67
|
+
|
|
68
|
+
### Bound every loop
|
|
69
|
+
|
|
70
|
+
Require that every iterative loop in a prototype, such as layout fitting, animation, simulation, or retry, stop after a fixed number of iterations or a time limit.
|
|
71
|
+
|
|
72
|
+
The failure that this prevents: one page whose loop does not end hangs its renderer, and every browser call queued behind it stalls, including the screenshots of the round.
|
|
67
73
|
|
|
68
74
|
### Write the brief in plain speech
|
|
69
75
|
|
|
@@ -79,10 +85,10 @@ Write the brief in this order, with these headings:
|
|
|
79
85
|
|
|
80
86
|
1. **Context.** The ticket, quoted. The developer's motivating picture, restated in plain speech.
|
|
81
87
|
2. **Settled intent.** Bullets. Each is a decision, with its reason when the reason constrains the design.
|
|
82
|
-
3. **Deliverable.** The file and its path per {skill:index-prototypes}; the constraints (self-contained, opens from `file://`, inline CSS and JavaScript, no framework, readable with JavaScript off, phone width); the mechanism that must run; the demo control that plays the written scene; a full-screen mode when the product has an audience view. The demo chrome (the demo control, scene captions, the lens note, the data-model note, the API list) is in a band visibly distinct from the product surface, and every part of it is inside an element that has the `data-demo` attribute. The band's first line is the id
|
|
88
|
+
3. **Deliverable.** The file and its path per {skill:index-prototypes}; the constraints (self-contained, opens from `file://`, inline CSS and JavaScript, no framework, readable with JavaScript off, phone width, every loop bounded by an iteration count or a time limit); the mechanism that must run; the demo control that plays the written scene; a full-screen mode when the product has an audience view. The demo chrome (the demo control, scene captions, the lens note, the data-model note, the API list) is in a band visibly distinct from the product surface, and every part of it is inside an element that has the `data-demo` attribute. The band's first line is the id from the dispatch block and the prototype's title, `{id} {title}`. The page's `<title>` is `{set title} - {id} {title}`, with the set title and the id from the dispatch block.
|
|
83
89
|
4. **Sections.** Numbered, each a noun phrase plus what it contains and a length bound. None asks for persuasion; one is the scene, exhibited; one is the data-model note when the product stores data; one is the API list when the product has an API.
|
|
84
90
|
5. **Quality bar.** Works, legible, accessible, and within the copy rules, with {rulebook:accessibility-conventions} and {rulebook:ui-copy-conventions} named, the design skill to invoke before markup, and the salience order required.
|
|
85
|
-
6. **How this round is judged.** The criteria, in the reviewer's voice, with the divergence between lenses named as the point of the round. One criterion is the copy: "Read every string on the product surface as its user opening the page for the tenth time. A string that explains the page, reassures, or repeats the brief, and any copy over the budget in {rulebook:ui-copy-conventions}, is a defect."
|
|
91
|
+
6. **How this round is judged.** The criteria, in the reviewer's voice, with the divergence between lenses named as the point of the round. One criterion is the copy: "Read every string on the product surface as its user opening the page for the tenth time. A string that explains the page, reassures, or repeats the brief, and any copy over the budget in {rulebook:ui-copy-conventions}, is a defect." Another is the glanceable state: "A list in which the reader must read each item to find a state for which the reader scans, such as expired or failing, is a defect, whatever restraint the lens asks for."
|
|
86
92
|
7. **Rules of engagement.** The write allowance from the inputs. The default: Write the output file and nothing else, modify nothing in the repository, install nothing. When the ask allows more, state what it allows. Then: Publish the prototype and report its artifact URL, a value for each of the set's note labels (listed here), and five lines of distinctive ideas.
|
|
87
93
|
|
|
88
94
|
Then add the lens sections, one per builder, in the developer's words after a plain-speech pass.
|
|
@@ -116,7 +122,7 @@ Resolve the set directory and the scratch directory per {skill:index-prototypes}
|
|
|
116
122
|
|
|
117
123
|
### 2. Gather the inputs
|
|
118
124
|
|
|
119
|
-
Take the ticket and the ask. Propose lenses when the ask lacks them. Take the write allowance from the ask, and apply the default when the ask does not state one. Choose a slug per lens and the set's note labels, per {skill:index-prototypes} "The set", before anything is built, and resolve the slugs' ids per the same section, in the order of the lens sections.
|
|
125
|
+
Take the ticket and the ask. Propose lenses when the ask lacks them. Take the write allowance from the ask, and apply the default when the ask does not state one. Choose the set title (or read it from the manifest), a slug per lens, and the set's note labels, per {skill:index-prototypes} "The set", before anything is built, and resolve the slugs' ids per the same section, in the order of the lens sections.
|
|
120
126
|
|
|
121
127
|
### 3. Compose and check the brief
|
|
122
128
|
|
|
@@ -129,8 +135,9 @@ Write the brief to `{scratch_dir}/brief.md`. Then check it against each rule abo
|
|
|
129
135
|
- Every `do not know`, `mystery`, `unknown to`, `without knowing` in an audience-facing instruction: rewritten as what the audience sees, without the withheld information.
|
|
130
136
|
- `cost`, `price`, `free`, `cheap`, `budget`: absent, or present once in the judging section.
|
|
131
137
|
- Every `state`, `say`, `tell`, `explain` in a requirement: rewritten as what the viewer can learn and at what moment.
|
|
132
|
-
- Salience order, the accessibility floor, and the copy rules: named in the quality bar, and the copy rules named again in "How this round is judged".
|
|
138
|
+
- Salience order, the accessibility floor, and the copy rules: named in the quality bar, and the copy rules and the glanceable state named again in "How this round is judged".
|
|
133
139
|
- The `data-demo` band: required in the deliverable.
|
|
140
|
+
- Bounded loops: required in the deliverable's constraints.
|
|
134
141
|
- The write allowance: stated in the rules of engagement.
|
|
135
142
|
- The note labels: listed in the rules of engagement.
|
|
136
143
|
|
|
@@ -138,13 +145,15 @@ Report what the check changed, in one line per rule that fired.
|
|
|
138
145
|
|
|
139
146
|
### 4. Checkpoint
|
|
140
147
|
|
|
141
|
-
Save the brief with {skill:save-artifact} as a ticket-level `brief` artifact, and show it to the developer.
|
|
148
|
+
Save the brief with {skill:save-artifact} as a ticket-level `brief` artifact, and show it to the developer. Ask for approval in one confirmation whose wording says that approval also posts the brief on the ticket as a comment: Posting is remote state, and the approval is the developer's consent to it. When the developer redirects, revise the brief, save it again, and show it again; post only the version that the developer approves.
|
|
149
|
+
|
|
150
|
+
Once the developer approves the brief, post it on the ticket without a further ask. The comment opens with a one-line summary that names the lenses and the brief artifact's path, written `~/`-relative as in the [closing post](../_data/spike-conventions.md#closing-post), and contains the full brief in a `<details>` block below the summary, so that the ticket stays readable. Pass the body through a file, per [gh body file](../_data/ticket-source-resolution.md#gh-body-file). Before posting, read the ticket's comments, and skip the post when a comment already opens with the summary line, so that a rerun does not post the brief twice. When the session does not have a remote ticket, skip the post and say so in one line. When the post fails, report the failure and continue with step 5.
|
|
142
151
|
|
|
143
152
|
<!-- include: ../_partials/action-items.md / -->
|
|
144
153
|
|
|
145
154
|
### 5. Dispatch the builders
|
|
146
155
|
|
|
147
|
-
Send one {tool:Task} call per lens
|
|
156
|
+
Each builder is a {subagent:prototype-builder}, which checks its page in a headless browser apart from this session's. Dispatch the builders one at a time, in the order of the lens sections, and wait for each reply before the next dispatch: Builders that run at once share one browser, and a page that hangs there stalls every builder. Send one {tool:Task} call per lens, `subagent_type: prototype-builder`, with this block and nothing else composed into it:
|
|
148
157
|
|
|
149
158
|
```dispatch
|
|
150
159
|
brief: {path to the saved brief}
|
|
@@ -152,14 +161,11 @@ lens: {lens name}
|
|
|
152
161
|
slug: {slug}
|
|
153
162
|
version: {n}
|
|
154
163
|
id: {number}.{n}
|
|
164
|
+
set-title: {set title}
|
|
155
165
|
output: {set_dir}/{slug}-v{n}.html
|
|
156
166
|
```
|
|
157
167
|
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
> Read the brief in full and build the prototype for the lens named above. Write only the files that the brief's rules of engagement allow. Put the id above and the prototype's title on the first line of the page's `data-demo` band. Invoke the design skill that the brief names before writing markup. Publish the output with the Artifact tool. When done, reply with the artifact URL, a short title, the lens, the inputs that you drew on, a one-sentence description, one line per note label in the brief as `{label}: {value}`, and five lines of the system's distinctive ideas. Nothing else.
|
|
161
|
-
|
|
162
|
-
Dispatch a builder once more with the same block when it returns without the file, with a file that does not open, or without an artifact URL. Report a second failure in the summary and leave the lens out of the round.
|
|
168
|
+
Dispatch a builder once more with the same block when it returns without the file, with a file that does not open, without an artifact URL, or with a page that it reports as still not responding. A builder whose browser call hangs on its own page cannot return, so stop a builder that has not replied 30 minutes after its dispatch, and count that as a failed attempt. Report a second failure in the summary and leave the lens out of the round.
|
|
163
169
|
|
|
164
170
|
### 6. Index and compare
|
|
165
171
|
|