codeassembly-guidance 0.6.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (124) hide show
  1. package/.meta/changelog.json +446 -0
  2. package/CHANGELOG.md +107 -0
  3. package/README.md +47 -51
  4. package/bin/codeassembly-validate-preferences.js +2 -8
  5. package/content/_partials/diff-audit-checklist.md +1 -0
  6. package/content/_partials/kb-unsearched-private-stores.md +6 -0
  7. package/content/_partials/plain-speech.md +2 -2
  8. package/content/_partials/ticket-assessment.md +3 -3
  9. package/content/codeassembly-content.yaml +8 -0
  10. package/content/collections/recommended.md +6 -0
  11. package/content/collections/williamthorsen.md +2 -1
  12. package/content/guidance/rulebooks/accessibility-conventions.md +6 -3
  13. package/content/guidance/rulebooks/cross-repo-migration-conventions.md +27 -0
  14. package/content/guidance/rulebooks/live-worktree-policy.md +2 -2
  15. package/content/guidance/rulebooks/ui-copy-conventions.md +2 -2
  16. package/content/guidance/rulebooks/visual-design-conventions.md +58 -0
  17. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +3 -18
  18. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +7 -1
  19. package/content/guidance/rulebooks/williamthorsen-visual-design-preferences.md +14 -0
  20. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +5 -3
  21. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +5 -20
  22. package/content/guidance/shared/AGENTS.md +3 -4
  23. package/content/scripts/README.md +1 -1
  24. package/content/scripts/check-branch-currency.mjs +7 -7
  25. package/content/scripts/check-prose.mjs +38 -38
  26. package/content/scripts/describe-change.mjs +89 -89
  27. package/content/scripts/manage-jira-ticket.mjs +162 -160
  28. package/content/scripts/select-lede-exemplars.mjs +85 -85
  29. package/content/scripts/validate-preferences.mjs +41 -41
  30. package/content/skills/_data/artifact-conventions.md +3 -3
  31. package/content/skills/_data/entry-points.md +1 -1
  32. package/content/skills/_data/project-stage.md +9 -5
  33. package/content/skills/_data/reduced-object-relatives.md +15 -0
  34. package/content/skills/_data/spike-conventions.md +16 -6
  35. package/content/skills/_data/ticket-evaluation.md +3 -0
  36. package/content/skills/_partials/implementation-order-list.md +27 -0
  37. package/content/skills/_partials/merge-settled-criterion.md +1 -0
  38. package/content/skills/_partials/next-steps-after-plan.md +2 -2
  39. package/content/skills/_partials/plan-template.md +3 -1
  40. package/content/skills/_partials/resolve-plan-and-ticket.md +2 -2
  41. package/content/skills/_partials/split-launch-prompts.md +1 -1
  42. package/content/skills/_partials/split-ticket-create.md +1 -1
  43. package/content/skills/_partials/ticket-criteria-conventions.md +2 -0
  44. package/content/skills/align-ticket-with-implementation/SKILL.md +3 -3
  45. package/content/skills/analyze-performance/SKILL.md +1 -1
  46. package/content/skills/assess-code-health/SKILL.md +4 -4
  47. package/content/skills/assess-code-health/assess-code-health.mjs +20 -20
  48. package/content/skills/assess-ticket/SKILL.md +3 -1
  49. package/content/skills/assess-ticket/next-steps-after-assessment.md +11 -14
  50. package/content/skills/assess-usability/SKILL.md +4 -4
  51. package/content/skills/capture-event/SKILL.md +20 -11
  52. package/content/skills/capture-event/capture-event.mjs +123 -123
  53. package/content/skills/capture-feedback/SKILL.md +2 -1
  54. package/content/skills/capture-lede-decision/SKILL.md +1 -1
  55. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +97 -97
  56. package/content/skills/collaborate/SKILL.md +1 -1
  57. package/content/skills/condense-branch/SKILL.md +18 -36
  58. package/content/skills/condense-branch/condense-branch.mjs +17 -0
  59. package/content/skills/create-bitbucket-pr/SKILL.md +9 -11
  60. package/content/skills/create-commit/SKILL.md +1 -1
  61. package/content/skills/create-devlog/SKILL.md +4 -4
  62. package/content/skills/create-gh-pr/SKILL.md +9 -11
  63. package/content/skills/create-pr/SKILL.md +10 -12
  64. package/content/skills/create-ticket/SKILL.md +22 -15
  65. package/content/skills/create-ticket/resolve-ticket-target.mjs +92 -92
  66. package/content/skills/curate-feedback/SKILL.md +2 -2
  67. package/content/skills/curate-feedback/curate-feedback.mjs +82 -82
  68. package/content/skills/derive-session-context/derive-session-context.mjs +120 -120
  69. package/content/skills/design-and-plan/SKILL.md +10 -8
  70. package/content/skills/groom-backlog/groom-backlog.mjs +15 -15
  71. package/content/skills/implement-plan/SKILL.md +4 -2
  72. package/content/skills/implementation-order/implementation-order.mjs +67 -0
  73. package/content/skills/index-prototypes/SKILL.md +2 -2
  74. package/content/skills/investigate-spike/SKILL.md +3 -3
  75. package/content/skills/kb-add/SKILL.md +12 -3
  76. package/content/skills/kb-add/kb-add.mjs +88 -88
  77. package/content/skills/kb-curate/kb-curate.mjs +88 -88
  78. package/content/skills/kb-edit/kb-edit.mjs +90 -90
  79. package/content/skills/kb-retrieve/SKILL.md +8 -3
  80. package/content/skills/kb-retrieve/kb-retrieve.mjs +104 -104
  81. package/content/skills/kb-retrieve-events/SKILL.md +8 -3
  82. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +113 -113
  83. package/content/skills/kb-update-events/kb-update-events.mjs +92 -92
  84. package/content/skills/lesson-clusters/lesson-clusters.mjs +102 -102
  85. package/content/skills/list-gh-progress-items/SKILL.md +36 -0
  86. package/content/skills/list-gh-progress-items/list-gh-progress-items.mjs +68 -0
  87. package/content/skills/list-implementation-order/SKILL.md +23 -0
  88. package/content/skills/merge-bb-pr/SKILL.md +40 -19
  89. package/content/skills/merge-gh-pr/SKILL.md +34 -23
  90. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +13 -8
  91. package/content/skills/merge-pr/SKILL.md +64 -31
  92. package/content/skills/migrate-feedback-memories/SKILL.md +1 -0
  93. package/content/skills/plan/SKILL.md +5 -3
  94. package/content/skills/prepare-prototype-brief/SKILL.md +5 -3
  95. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +22 -22
  96. package/content/skills/refine-plan/SKILL.md +5 -3
  97. package/content/skills/refine-prototype/SKILL.md +2 -1
  98. package/content/skills/respond-to-review/SKILL.md +4 -4
  99. package/content/skills/review-bb-pr/SKILL.md +1 -2
  100. package/content/skills/review-branch/SKILL.md +19 -14
  101. package/content/skills/review-criteria/SKILL.md +2 -2
  102. package/content/skills/review-gh-pr/SKILL.md +1 -2
  103. package/content/skills/review-pr/SKILL.md +2 -3
  104. package/content/skills/revise-prose/revise-prose.mjs +109 -109
  105. package/content/skills/save-artifact/SKILL.md +4 -6
  106. package/content/skills/save-plan/SKILL.md +4 -2
  107. package/content/skills/start-ticket/SKILL.md +1 -1
  108. package/content/skills/streamline-guidance/streamline-guidance.mjs +80 -80
  109. package/content/skills/summarize-change/SKILL.md +20 -9
  110. package/content/skills/summarize-chat/SKILL.md +2 -2
  111. package/content/skills/testing-conventions/SKILL.md +2 -2
  112. package/content/skills/triage-feedback/SKILL.md +6 -2
  113. package/content/skills/triage-spike-findings/SKILL.md +33 -24
  114. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +19 -19
  115. package/content/skills/update-project-guidance/SKILL.md +1 -1
  116. package/content/skills/wrap-up/SKILL.md +8 -4
  117. package/content/skills/write-progress-report/SKILL.md +111 -0
  118. package/content/skills/write-progress-report/write-progress-report.mjs +150 -0
  119. package/content/subagents/disposition-challenger.md +7 -6
  120. package/content/subagents/entry-drafter.md +2 -0
  121. package/content/subagents/usability-assessor.md +3 -2
  122. package/package.json +13 -12
  123. package/schemas/preferences.v1.json +82 -8
  124. package/schemas/work-types.v1.json +1 -1
@@ -49,7 +49,7 @@ When you do ask, prefer forms that the user can answer unambiguously:
49
49
 
50
50
  - **A confirmation prompt** (end with `👍🏼👎🏼`). A fixed comprehension contract applies to the marker: On a clear affirmation, proceed; on a clear negation, don't; treat anything else as conversation. Full spec in `AGENTS.md` under "Prompt formatting". (Reinforces the rule in `AGENTS.md`: intentional redundancy.)
51
51
  - **A numbered options list.** Include a "some other approach (describe)" option if alternatives should stay open.
52
- - When asking option-style questions, follow [option format](#option-format). (Reinforces the rule in `AGENTS.md`: intentional redundancy.)
52
+ - When asking option-style questions, follow [option format](#option-format).
53
53
 
54
54
  **Never use an interactive selector to pose the question.** `{tool:AskUserQuestion}` (or any pop-up / arrow-key picker) cannot render the strength markers or pros and cons that the gradient requires, so it silently discards the convention. Always write the choice as plain text in the message body.
55
55
 
@@ -8,11 +8,16 @@ user-invocable: true
8
8
 
9
9
  Condense the current branch into a single commit with a comprehensive message.
10
10
 
11
- ## Process
11
+ ## Result
12
+
13
+ The branch holds one commit on its merge base with the default branch. That commit's tree is the tree of the branch's original head, and its message describes the branch as a whole.
14
+
15
+ - A backup branch points at the original head.
16
+ - Uncommitted changes, staged or not, and untracked files are not part of the condensed commit, and they are not discarded. Leave them where they are: Do not stash, stage, or commit them.
12
17
 
13
- 1. **Stash changes** if working tree is dirty
18
+ ## Process
14
19
 
15
- 2. **Analyze branch** to create a good commit message, and consolidate it while its commits still exist:
20
+ 1. **Analyze branch** to create a good commit message, and consolidate it while its commits still exist:
16
21
  - Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash to obtain `default_branch` from the manifest JSON that it emits on stdout.
17
22
  - Consolidate the range into a scratch file, created per the path rules of [gh body file](#gh-body-file) and named `consolidation-{timestamp}.json`:
18
23
 
@@ -23,41 +28,24 @@ Condense the current branch into a single commit with a comprehensive message.
23
28
 
24
29
  If the call fails, as it does when `commit.title_format` is empty, it leaves the file empty. Relay its error and continue without a consolidated record: The subject renders without a scope or type, and the message does not contain a trailer.
25
30
 
26
- - Report each `unmatched` subject and each `violations` entry to the developer. An unmatched subject does not get a trailer in step 4, so it drops out of the entries that the condensed commit declares.
31
+ - Report each `unmatched` subject and each `violations` entry to the developer. An unmatched subject does not get a trailer in step 2, so it drops out of the entries that the condensed commit declares.
27
32
 
28
33
  [The change record](../_data/change-record.md) states the consolidated record and the `Change:` trailer.
29
34
 
30
- 3. **Create backup branch**:
31
-
32
- ```bash
33
- git branch $(git branch --show-current)-v1
34
- ```
35
-
36
- If branch exists, increment version number.
35
+ 2. **Condense commits**:
37
36
 
38
- 4. **Condense commits**:
37
+ Write the title, a blank line, and the body to a scratch file per [gh body file](#gh-body-file), naming it `commit-message-{timestamp}.md`; do not inline the message into the shell command. Do not write any `Change:` trailer: The helper appends one per consolidation entry, oldest first, as the last paragraph.
39
38
 
40
- Write the title, a blank line, and the body to a scratch file per [gh body file](#gh-body-file), naming it `commit-message-{timestamp}.md`; do not inline the message into the shell command.
41
-
42
- The call below composes the final message from that file and the step-2 consolidation: the body, a blank line, and one `Change: {change}` trailer per entry, oldest first, as the last paragraph. The trailers are read from the consolidation file inside the call, so the agent does not retype any entry into a command, and a retry rebuilds the message rather than appending to it. If the consolidation did not find any entry, or failed and left the file empty, the message does not contain a trailer.
39
+ Run the bundled helper as one command:
43
40
 
44
41
  ```bash
45
- body_path="{absolute path from the write step}"
46
- consolidation_path="{absolute path of the step-2 consolidation file}"
47
- [ -s "$body_path" ] || { echo "Body file missing or empty: $body_path" >&2; exit 1; }
48
- message_path="${body_path%.md}-with-trailers.md"
49
- {
50
- cat "$body_path"
51
- if [ -s "$consolidation_path" ]; then
52
- printf '\n\n'
53
- jq -r '.entries[] | "Change: " + .change' "$consolidation_path"
54
- fi
55
- } > "$message_path"
56
- git reset --soft $(git merge-base {default_branch} HEAD)
57
- git add --all
58
- git commit --file "$message_path" --no-gpg-sign --no-verify
42
+ node {harness_home_dir}/skills/condense-branch/condense-branch.mjs --base {default_branch} --message-file {absolute message path} --consolidation-file {absolute path of the step-1 consolidation file}
59
43
  ```
60
44
 
45
+ Pass `--consolidation-file` even when step 1 failed and left the file empty; the helper reads an empty or absent file as no trailers. Pass each path as the literal absolute path, unquoted, without a shell variable or a guard: The helper refuses a missing or empty message file itself.
46
+
47
+ The helper creates the backup branch `{branch}-v{N}` at the first free version, writes the condensed commit without running hooks or signing it, and moves the branch to it. It does not touch the index or the working tree. It prints JSON naming the `backup` branch and the number of `trailers`; report both. On a non-zero exit it has not changed any ref: Relay its stderr and stop.
48
+
61
49
  ## Commit message creation
62
50
 
63
51
  ### If commits have detailed descriptions
@@ -70,14 +58,8 @@ Use `{skill:summarize-change}` to compose a good commit message. Save the descri
70
58
 
71
59
  ## Commit format
72
60
 
73
- Compose the message per `{rulebook:commit-conventions}`. Use `describe-change.mjs` to render the full commit title (see [title-templates.md](../_data/title-templates.md) for syntax), taking `{scope}` and `{type}` from the step-2 `consolidated_record` and appending `!` to the type if it is breaking. If the consolidation failed, or a field is `null`, omit that flag:
61
+ Compose the message per `{rulebook:commit-conventions}`. Use `describe-change.mjs` to render the full commit title (see [title-templates.md](../_data/title-templates.md) for syntax), taking `{scope}` and `{type}` from the step-1 `consolidated_record` and appending `!` to the type if it is breaking. If the consolidation failed, or a field is `null`, omit that flag:
74
62
 
75
63
  <!-- include: ../_partials/commit-title-rendering.md / -->
76
64
 
77
- ## Safety
78
-
79
- - Always create a backup branch before condensing
80
- - Increment version numbers if backup already exists
81
- - Use `--no-gpg-sign --no-verify` to avoid hook issues
82
-
83
65
  <!-- include: ../_partials/gh-body-file.md / -->
@@ -0,0 +1,17 @@
1
+ import { createRequire as __cjsCreateRequire } from 'node:module';
2
+ const require = __cjsCreateRequire(import.meta.url);
3
+ var B=Object.defineProperty;var i=(e,n)=>B(e,"name",{value:n,configurable:!0});import d from"node:process";function b(e){return e instanceof Error||Object.prototype.toString.call(e)==="[object Error]"}i(b,"isError");function l(e){try{return b(e)&&typeof e.message=="string"&&e.message!==""?e.message:String(e)}catch{return"[unstringifiable value]"}}i(l,"describeError");import{realpathSync as $}from"node:fs";import x from"node:process";import{fileURLToPath as H}from"node:url";function F(e,n){let t=x.argv[1];if(t===void 0)return!1;try{return $(H(e))===$(t)}catch(r){return x.stderr.write(`${n}: warning: could not determine entry point: ${l(r)}
4
+ `),!0}}i(F,"isEntryPoint");function v(e,n){let t=[],r=[];for(let o=0;o<e.length;o+=1){let s=e[o];if(s===void 0)continue;if(!s.startsWith("--")){t.push(s);continue}let p=V(s,n);if(p===null)throw new Error(`unknown flag: ${s}`);let{spec:c,inlineValue:a}=p;if(!c.takesValue){if(a!==null)throw new Error(`--${c.name} does not take a value`);r.push({name:c.name,value:null});continue}if(a!==null){r.push({name:c.name,value:a});continue}let g=e[o+1]??null;if(g===null||g.startsWith("--"))throw new Error(`--${c.name} requires a value`);r.push({name:c.name,value:g}),o+=1}return{positionals:t,flags:r}}i(v,"scanFlags");function V(e,n){for(let t of n)for(let r of[t.name,...t.aliases??[]]){let o=`--${r}`;if(e===o)return{spec:t,inlineValue:null};if(e.startsWith(`${o}=`))return{spec:t,inlineValue:e.slice(o.length+1)}}return null}i(V,"matchFlag");import{execFileSync as j}from"node:child_process";import{readFileSync as C}from"node:fs";function k(e,n){return N(e)&&e.code===n}i(k,"isErrorCode");function h(e){return k(e,"ENOENT")||k(e,"ENOTDIR")}i(h,"isMissingFile");function f(e){return N(e)&&!Array.isArray(e)}i(f,"isRecord");function N(e){return typeof e=="object"&&e!==null}i(N,"isObject");function S(e,n){let t=e.trimEnd();if(n.length===0)return`${t}
5
+ `;let r=n.map(o=>`Change: ${o}`).join(`
6
+ `);return`${t}
7
+
8
+ ${r}
9
+ `}i(S,"composeMessage");function R(e){if(e.trim()==="")return[];let n;try{n=JSON.parse(e)}catch(r){throw new Error(`consolidation file is not valid JSON: ${l(r)}`,{cause:r})}let t=f(n)?n.entries:void 0;if(!Array.isArray(t))throw new TypeError("consolidation file does not contain an `entries` array");return t.map((r,o)=>{let s=f(r)?r.change:void 0;if(typeof s!="string"||s.trim()==="")throw new TypeError(`consolidation entry ${o} does not have a non-empty \`change\` string`);return s})}i(R,"parseChangeEntries");function M(e){let{base:n,consolidationFile:t,cwd:r,messageFile:o}=e,s=G(r),p=P(o),c=R(t===void 0?"":J(t)),a=u(r,["rev-parse","--verify","HEAD^{commit}"]),g=W(r,n,a);if(g===a)throw new Error(`${s} does not have any commits beyond its merge base with ${n}`);let O=S(p,c),y=u(r,["commit-tree",a+"^{tree}","-p",g,"--no-gpg-sign"],O),E=D(r,s,a);try{u(r,["update-ref","-m","condense-branch",`refs/heads/${s}`,y,a])}catch(A){throw u(r,["update-ref","-d",`refs/heads/${E}`,a]),A}return{backup:E,branch:s,condensedHead:y,mergeBase:g,originalHead:a,trailers:c.length}}i(M,"condenseBranch");function D(e,n,t){for(let r=1;;r+=1){let o=`${n}-v${r}`;if(!q(e,o))return u(e,["branch","--no-track",o,t]),o}}i(D,"createBackupBranch");function T(e){let n=f(e)?e.stderr:void 0;return typeof n=="string"&&n.trim()!==""?n.trim():l(e)}i(T,"describeGitFailure");function q(e,n){try{return u(e,["show-ref","--verify","--quiet",`refs/heads/${n}`]),!0}catch{return!1}}i(q,"hasBranch");function G(e){try{return u(e,["symbolic-ref","--quiet","--short","HEAD"])}catch(n){throw new Error("HEAD is detached; check out the branch to condense",{cause:n})}}i(G,"readCheckedOutBranch");function P(e){let n;try{n=C(e,"utf8")}catch(t){throw h(t)?new Error(`message file is missing: ${e}`,{cause:t}):t}if(n.trim()==="")throw new Error(`message file is empty: ${e}`);return n}i(P,"readMessageBody");function J(e){try{return C(e,"utf8")}catch(n){if(h(n))return"";throw n}}i(J,"readOptionalFile");function W(e,n,t){let r=u(e,["merge-base","--all",n,t]),o=r===""?[]:r.split(`
10
+ `);if(o.length===0)throw new Error(`HEAD does not have a merge base with ${n}`);if(o.length>1)throw new Error(`HEAD has ${o.length} merge bases with ${n}, so the condensed commit's parent is ambiguous`);return o[0]??""}i(W,"resolveMergeBase");function u(e,n,t){try{return j("git",["-C",e,...n],{encoding:"utf8",input:t,stdio:["pipe","pipe","pipe"]}).trim()}catch(r){throw new Error(`git ${n[0]??""} failed: ${T(r)}`,{cause:r})}}i(u,"runGit");var L=[{name:"base",takesValue:!0},{name:"consolidation-file",takesValue:!0},{name:"message-file",takesValue:!0}],m="usage: condense-branch --base <revision> --message-file <path> [--consolidation-file <path>]";function U(){try{let e=I(d.argv.slice(2));d.stdout.write(`${JSON.stringify(e,null,2)}
11
+ `)}catch(e){d.stderr.write(`condense-branch: ${l(e)}
12
+ `),d.exit(1)}}i(U,"main");F(import.meta.url,"condense-branch")&&U();function w(e,n){let t=e.filter(o=>o.name===n).map(o=>o.value??"");if(t.length>1)throw new Error(`--${n} may be given only once
13
+ ${m}`);let[r]=t;if(r==="")throw new Error(`--${n} must not be empty
14
+ ${m}`);return r}i(w,"readSingleFlag");function I(e){let{flags:n,positionals:t}=v(e,L);if(t.length>0)throw new Error(`unexpected argument: ${t.join(" ")}
15
+ ${m}`);let r=w(n,"base");if(r===void 0)throw new Error(`--base is required
16
+ ${m}`);let o=w(n,"message-file");if(o===void 0)throw new Error(`--message-file is required
17
+ ${m}`);let s=w(n,"consolidation-file");return M({base:r,consolidationFile:s,cwd:d.cwd(),messageFile:o})}i(I,"runCommand");
@@ -12,16 +12,14 @@ Internal delegate that creates a pull request on Bitbucket. Called by `create-pr
12
12
 
13
13
  This skill receives the following inputs from the orchestrator:
14
14
 
15
- | Input | Type | Description |
16
- | ------------------- | -------- | ------------------------------------------------------------------------------------------------------ |
17
- | `title` | string | Final PR title, already prefixed if applicable |
18
- | `body` | string | PR body: `## What` onward from the change summary, then the closing line and the `change-record` block |
19
- | `labels` | string[] | Resolved label names (may be empty) |
20
- | `base_branch` | string | Bare branch name (e.g., `main`, not `origin/main`) |
21
- | `ticket_id` | string | Ticket ID for artifact path resolution |
22
- | `project_slug` | string | Project slug for artifact path resolution |
23
- | `artifact_base_dir` | string | Base directory for artifact storage |
24
- | `initial_state` | string | `draft` to open the pull request as a draft, `ready` to open it ready for review |
15
+ | Input | Type | Description |
16
+ | --------------- | -------- | ------------------------------------------------------------------------------------------------------ |
17
+ | `title` | string | Final PR title, already prefixed if applicable |
18
+ | `body` | string | PR body: `## What` onward from the change summary, then the closing line and the `change-record` block |
19
+ | `labels` | string[] | Resolved label names (may be empty) |
20
+ | `base_branch` | string | Bare branch name (e.g., `main`, not `origin/main`) |
21
+ | `ticket_dir` | string | Ticket artifact directory, in which the artifact is saved |
22
+ | `initial_state` | string | `draft` to open the pull request as a draft, `ready` to open it ready for review |
25
23
 
26
24
  ## Process
27
25
 
@@ -47,7 +45,7 @@ The artifact's label lines keep `create-gh-pr`'s three-field shape: `Labels atte
47
45
 
48
46
  Save a `pull-request` artifact in the ticket directory.
49
47
 
50
- Ticket directory: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
48
+ Ticket directory: `{ticket_dir}/`
51
49
 
52
50
  Follow [artifact conventions](../_data/artifact-conventions.md).
53
51
 
@@ -27,7 +27,7 @@ It writes the commit message file and the commit, and nothing else. It never edi
27
27
 
28
28
  ## What one commit contains
29
29
 
30
- One logical unit of work, together with whatever that unit needs to stand on its own. Work that does not stand alone -- a scaffold filled in by a later change -- goes into the change that completes it rather than becoming a commit of its own.
30
+ One logical unit of work, together with whatever that unit needs to stand on its own. Work that does not stand alone, such as a scaffold that a later change fills in, goes into the change that completes it rather than becoming a commit of its own. A scaffold that passes the repository's checks and is fully wired stands alone: A new package's empty scaffold, with its documentation and its package references, is a commit of its own.
31
31
 
32
32
  Record each unit as it is finished. Several single-concern commits read better than one that bundles them, and each can be reverted without taking the others with it.
33
33
 
@@ -55,11 +55,11 @@ Resolve session context and the artifact directory before writing.
55
55
 
56
56
  ### Path resolution
57
57
 
58
- 1. 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_id`, `project_slug`, `artifact_base_dir`, `artifact_paths`, and `branch_name` from it.
59
- 2. If `ticket_id` is non-null: Save as a ticket-level artifact at:
58
+ 1. 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_dir`, `project_artifact_dir`, `artifact_paths`, and `branch_name` from it.
59
+ 2. If `ticket_dir` is non-null: Save as a ticket-level artifact at:
60
60
 
61
61
  ```
62
- {artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/{filename}
62
+ {ticket_dir}/{filename}
63
63
  ```
64
64
 
65
65
  Filename uses the ticket-level shape: `{YYYYMMDD-HHMMSSZ}_{slug}_devlog.md`.
@@ -67,7 +67,7 @@ Resolve session context and the artifact directory before writing.
67
67
  3. Else (no ticket; research/exploration sessions): Save to the project-scoped fallback at:
68
68
 
69
69
  ```
70
- {artifact_base_dir}/projects/{project_slug}/{artifact_paths.devlogs}/{filename}
70
+ {project_artifact_dir}/{artifact_paths.devlogs}/{filename}
71
71
  ```
72
72
 
73
73
  Filename uses the ticket-level timestamp and slug without the artifact-type segment: `{YYYYMMDD-HHMMSSZ}_{slug}.md`.
@@ -12,16 +12,14 @@ Internal delegate that creates a pull request on GitHub. Called by `create-pr` w
12
12
 
13
13
  This skill receives the following inputs from the orchestrator:
14
14
 
15
- | Input | Type | Description |
16
- | ------------------- | -------- | ------------------------------------------------------------------------------------------------------ |
17
- | `title` | string | Final PR title, already prefixed if applicable |
18
- | `body` | string | PR body: `## What` onward from the change summary, then the closing line and the `change-record` block |
19
- | `labels` | string[] | Resolved label names (may be empty) |
20
- | `base_branch` | string | Bare branch name (e.g., `main`, not `origin/main`) |
21
- | `ticket_id` | string | Ticket ID for artifact path resolution |
22
- | `project_slug` | string | Project slug for artifact path resolution |
23
- | `artifact_base_dir` | string | Base directory for artifact storage |
24
- | `initial_state` | string | `draft` to open the pull request as a draft, `ready` to open it ready for review |
15
+ | Input | Type | Description |
16
+ | --------------- | -------- | ------------------------------------------------------------------------------------------------------ |
17
+ | `title` | string | Final PR title, already prefixed if applicable |
18
+ | `body` | string | PR body: `## What` onward from the change summary, then the closing line and the `change-record` block |
19
+ | `labels` | string[] | Resolved label names (may be empty) |
20
+ | `base_branch` | string | Bare branch name (e.g., `main`, not `origin/main`) |
21
+ | `ticket_dir` | string | Ticket artifact directory, in which the artifact is saved |
22
+ | `initial_state` | string | `draft` to open the pull request as a draft, `ready` to open it ready for review |
25
23
 
26
24
  ## Process
27
25
 
@@ -78,7 +76,7 @@ An empty result means that the pull request has no assignee: Record the assignee
78
76
 
79
77
  Save a `pull-request` artifact in the ticket directory.
80
78
 
81
- Ticket directory: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
79
+ Ticket directory: `{ticket_dir}/`
82
80
 
83
81
  Follow [artifact conventions](../_data/artifact-conventions.md).
84
82
 
@@ -21,7 +21,7 @@ Both are passed to `summarize-change`, which records them as overrides beside th
21
21
 
22
22
  ### 1. Get session context
23
23
 
24
- 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_id`, `ticket_ref`, `project_slug`, `scm`, `default_branch`, `branch_name`, `artifact_base_dir`, and `pr_initial_state` from it.
24
+ 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_id`, `ticket_ref`, `scm`, `default_branch`, `branch_name`, `ticket_dir`, and `pr_initial_state` from it.
25
25
 
26
26
  ### 2. Check branch sync
27
27
 
@@ -125,16 +125,14 @@ If the change summary's body does not end with a block, append the closing line
125
125
 
126
126
  Pass the following inputs to the selected delegate per the delegate interface:
127
127
 
128
- | Input | Value |
129
- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
130
- | `title` | Rendered `pr_title` from step 6 (or bare `title` if the script was unavailable) |
131
- | `body` | Content from `## What` onward in the change summary, `## How to test` included when the summary has it, with the closing line inserted per step 9 |
132
- | `labels` | Resolved label names (may be empty list) |
133
- | `base_branch` | Bare branch name derived from `default_branch` (strip remote prefix, e.g., `origin/main` -> `main`) |
134
- | `ticket_id` | From session context |
135
- | `project_slug` | From session context |
136
- | `artifact_base_dir` | From session context |
137
- | `initial_state` | `pr_initial_state` from session context: `draft` or `ready` |
128
+ | Input | Value |
129
+ | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
130
+ | `title` | Rendered `pr_title` from step 6 (or bare `title` if the script was unavailable) |
131
+ | `body` | Content from `## What` onward in the change summary, `## Notes for reviewers` and `## How to test` included when the summary has them, with the closing line inserted per step 9 |
132
+ | `labels` | Resolved label names (may be empty list) |
133
+ | `base_branch` | Bare branch name derived from `default_branch` (strip remote prefix, e.g., `origin/main` -> `main`) |
134
+ | `ticket_dir` | `ticket_dir` from session context, or the directory that {skill:save-artifact} states when it is null |
135
+ | `initial_state` | `pr_initial_state` from session context: `draft` or `ready` |
138
136
 
139
137
  ### 11. Persist the PR URL
140
138
 
@@ -148,4 +146,4 @@ node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs
148
146
 
149
147
  - The orchestrator makes all decisions (scope, type, title rendering, labels). Delegates only make the platform API calls.
150
148
  - Strip the remote prefix from `default_branch` (e.g., `origin/main` -> `main`) before passing to the delegate.
151
- - The body's manual test steps come from the change summary's `## How to test`, which `summarize-change` writes; never add a test plan of your own.
149
+ - The body consists of the change summary's sections, which `summarize-change` writes under its reader test; never add a section, a note, or a test plan of your own.
@@ -13,13 +13,14 @@ Create a ticket on the appropriate platform. The remote platform (e.g., GitHub)
13
13
 
14
14
  ## Arguments
15
15
 
16
- | Argument | Effect |
17
- | --------------------- | --------------------------------------------------------------------------------------------- |
18
- | `--parent <ref>` | Make the new ticket a child of the referenced ticket. One reference; a ticket has one parent. |
19
- | `--blocked-by <refs>` | Mark the new ticket as blocked by the referenced tickets. |
20
- | `--blocking <refs>` | Mark the new ticket as blocking the referenced tickets. |
21
- | `--label <labels>` | Apply these labels with the ones that step 5 resolves. GitHub only. |
22
- | `--repo <OWNER/REPO>` | File the ticket in this GitHub repository. See [Another repository](#another-repository). |
16
+ | Argument | Effect |
17
+ | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
18
+ | `--parent <ref>` | Make the new ticket a child of the referenced ticket. One reference; a ticket has one parent. On Jira, a child of a level-0 parent, such as a `Task`, is created as a subtask, at the issue type that `integrations.jira.subtask_issue_type` sets (`Subtask` by default). |
19
+ | `--blocked-by <refs>` | Mark the new ticket as blocked by the referenced tickets. |
20
+ | `--blocking <refs>` | Mark the new ticket as blocking the referenced tickets. |
21
+ | `--label <labels>` | Apply these labels with the ones that step 5 resolves. GitHub only. |
22
+ | `--repo <OWNER/REPO>` | File the ticket in this GitHub repository. See [Another repository](#another-repository). |
23
+ | `--umbrella` | Create the ticket as an umbrella, whose children do its work. On Jira, it takes the issue type that `integrations.jira.umbrella_issue_type` sets (`Epic` by default) in place of the work type's, so that Jira accepts it as its children's parent. On GitHub, it changes nothing. |
23
24
 
24
25
  The three relationship arguments take ticket references in the project's own form (`#123`, `ABC-123`), comma-separated when more than one applies. Each is optional, and each overrides the inference in step 4 for its own relationship. `--label` takes label names, comma-separated, exactly as the repository spells them.
25
26
 
@@ -107,6 +108,10 @@ Decide which apply from the reason this ticket is being created, narrowed by `br
107
108
 
108
109
  For a [target repository](#another-repository), do not infer any relationship from `branch_ticket_id`, which identifies a ticket in the session's repository; apply only those that the arguments state. A reference resolves in the target, so pass a ticket in any other repository as its URL.
109
110
 
111
+ On Jira, an `--umbrella` ticket does not take a parent that this step infers: An umbrella is an epic by default, and Jira rejects a level-0 work item or another epic as an epic's parent, which would fail the creation itself. Report the inferred parent skipped in the completion output. A parent given through `--parent` is passed through, because the caller may name a higher-level item, such as an initiative.
112
+
113
+ On Jira, a parent decides the child's issue type, because Jira places a child exactly one level below its parent: Under a level-0 parent, such as a `Task`, the child is created as a subtask, at the type that `integrations.jira.subtask_issue_type` sets (`Subtask` by default). This applies to an inferred parent and a passed one alike. A parent at a level that cannot take the child, such as a subtask, is skipped and reported, and the ticket is created without it. Step 6 states how each client applies this.
114
+
110
115
  **Most tickets have none, and for those, say nothing.** When nothing applies, continue to step 5 without asking.
111
116
 
112
117
  When one or more apply, state each relationship and its target in the project's own reference form and confirm before anything is created, so that a wrong target is visible while it is still free to correct. A relationship supplied through an argument is one that the caller has already confirmed: State it in the completion output and do not ask about it; the confirmation covers the inferred relationships alone. If the platform resolved in step 3 cannot express one of them, say so here rather than reporting it as a skip in step 7.
@@ -173,10 +178,10 @@ Construct the ticket ID from `ticket_ref_prefix` (step 1) and `number`:
173
178
  ##### Resolve the target
174
179
 
175
180
  ```bash
176
- node {harness_home_dir}/scripts/manage-jira-ticket.mjs resolve-target --work-type {type}
181
+ node {harness_home_dir}/scripts/manage-jira-ticket.mjs resolve-target --work-type {type} {umbrella_flag}
177
182
  ```
178
183
 
179
- `{type}` is the work type decided in step 2. The helper reads `integrations.jira` and `project.ticket_ref_prefix` from the repository's `.agents/preferences.yaml`, never from the global file, and prints `{"projectKey": "...", "issueType": "..."}`. Use both values as printed: Never infer a key from the repository name or from a ticket reference seen elsewhere in the session, and never choose an issue type from the ticket's content, because a project need not define `Story` or `Bug`.
184
+ `{type}` is the work type decided in step 2, and `{umbrella_flag}` is `--umbrella` when the caller passed it, and empty otherwise. The helper reads `integrations.jira` and `project.ticket_ref_prefix` from the repository's `.agents/preferences.yaml`, never from the global file, and prints `{"projectKey": "...", "issueType": "..."}`. Use both values as printed: Never infer a key from the repository name or from a ticket reference seen elsewhere in the session, and never choose an issue type from the ticket's content, because a project need not define `Story` or `Bug`.
180
185
 
181
186
  When the preferences do not name a project, the helper prints `{"fallback": "no-project-key", "warning": "..."}` instead. Take the [no-remote fallback](#fallback-no-remote-platform) with that warning.
182
187
 
@@ -186,17 +191,19 @@ Identify the client per {skill?:update-jira-ticket}, which ranks the three clien
186
191
 
187
192
  <!-- include: ../_partials/jira-task-list-flattening.md / -->
188
193
 
194
+ **A parent on a connected tool.** When step 4 decided a parent, read its `issuetype.hierarchyLevel` before creating, through the Jira read tool that [ticket source resolution](../_data/ticket-source-resolution.md#platform-specific-fetch) ranks for Jira, asked for the `issuetype` field. Pass it to `resolve-target` as `--parent-level {level}`, which then also prints `parentAllowed`, and create with the `issueType` that it prints. When it prints `parentAllowed: false`, or the read fails, report the parent skipped per step 7. When the type is a subtask, pass the parent in the creation call, because a subtask cannot exist without one; a tool that does not take a parent at creation cannot create the child, so report the parent skipped and create at the type that `resolve-target` prints without `--parent-level`.
195
+
189
196
  - **`contentFormat` tool** (e.g. `createJiraIssue`): `projectKey`, `issueTypeName`, `summary` (`ticket_title`), and the step-2 body as a top-level `description` with `contentFormat: "markdown"`. Take any further required argument from the tool's own schema, which a connected server may extend.
190
197
  - **HTML tool** (e.g. `create_jira_issue`): The same target and summary, with the body as `description_html`, rendered to the allowlist and passed through that skill's pre-flight checker before the call.
191
198
  - **`acli`**: Write the step-2 body as Markdown to a scratch file per [gh body file](#gh-body-file), naming it `jira-body-{timestamp}.md`, and run the helper once:
192
199
 
193
200
  ```bash
194
- node {harness_home_dir}/scripts/manage-jira-ticket.mjs create --summary "{ticket_title}" --body-file {absolute body path} --work-type {type} {parent_flag}
201
+ node {harness_home_dir}/scripts/manage-jira-ticket.mjs create --summary "{ticket_title}" --body-file {absolute body path} --work-type {type} {parent_flag} {umbrella_flag}
195
202
  ```
196
203
 
197
- `{parent_flag}` is `--parent {parent}` when step 4 decided a parent, and empty otherwise. Pass the body path as the literal absolute path, unquoted, without a shell variable or a guard: The helper refuses a missing or empty file before it calls `acli`.
204
+ `{parent_flag}` is `--parent {parent}` when step 4 decided a parent, and empty otherwise; `{umbrella_flag}` is as for `resolve-target`. Pass the body path as the literal absolute path, unquoted, without a shell variable or a guard: The helper refuses a missing or empty file before it calls `acli`.
198
205
 
199
- When `ticket.base_url` is set, in the repository's preferences or the global file, the helper first compares `acli`'s active site with the base URL's host, because `acli` creates on whichever site it is signed in to. It then converts the body to ADF, checks a parent with `acli jira workitem view`, and runs `acli jira workitem create` exactly once. It prints `{"key": "ABC-123", "rawOutput": "...", "parentSkipped": false, "activeSite": "..."}`, in which `activeSite` is null when `ticket.base_url` is unset. `parentSkipped: true` means that Jira rejected the parent reference and the work item was created without it; report the parent skipped per step 7.
206
+ When `ticket.base_url` is set, in the repository's preferences or the global file, the helper first compares `acli`'s active site with the base URL's host, because `acli` creates on whichever site it is signed in to. It then converts the body to ADF, reads a parent's hierarchy level with `acli jira workitem view`, and runs `acli jira workitem create` exactly once. It prints `{"issueType": "Task", "key": "ABC-123", "rawOutput": "...", "parentSkipped": false, "activeSite": "..."}`, in which `issueType` is the type with which the work item was created and `activeSite` is null when `ticket.base_url` is unset. `parentSkipped: true` means that Jira rejected the parent reference, or that the parent's level could not be read or cannot take the work item, and the work item was created without it; report the parent skipped per step 7, with the reason that stderr states. Report a child created at the subtask type as a subtask.
200
207
 
201
208
  On a non-zero exit, read what it printed:
202
209
  - `{"fallback": "no-project-key"}`: As under [Resolve the target](#resolve-the-target), and `acli` was not called.
@@ -254,7 +261,7 @@ These flags are native to `gh` 2.94 and later. They are not the REST dependencie
254
261
 
255
262
  #### Jira path
256
263
 
257
- **Parent.** On a connected tool the parent is set here, after the work item exists, through the update tool's `fields`, which takes it as an object rather than a bare key: `"parent": { "key": "{parent}" }`. A reference rejected by Jira then fails only the relationship, as this step's general rule intends. Report the parent skipped when the update tool does not expose a parent field.
264
+ **Parent.** On a connected tool the parent is set here, after the work item exists, through the update tool's `fields`, which takes it as an object rather than a bare key: `"parent": { "key": "{parent}" }`. A reference rejected by Jira then fails only the relationship, as this step's general rule intends. Report the parent skipped when the update tool does not expose a parent field. A subtask is the exception: Its parent is set in the creation call, per step 6.
258
265
 
259
266
  `acli` is the exception, and the only one: `acli jira workitem edit` does not have a `--parent` flag, so the step-6 helper sets the parent in the creation call, after checking the reference. Report the parent skipped when the helper printed `parentSkipped: true`.
260
267
 
@@ -273,10 +280,10 @@ node {harness_home_dir}/scripts/manage-jira-ticket.mjs check-site --target {tick
273
280
  Then:
274
281
 
275
282
  ```bash
276
- acli jira workitem link create --out "{blocker}" --in "{blocked}" --type Blocks --yes
283
+ acli jira workitem link create --out "{blocked}" --in "{blocker}" --type Blocks --yes
277
284
  ```
278
285
 
279
- Because `--out` names the blocker, the two relationships differ only in which side the new key occupies: blocked-by puts the referenced key in `--out`, and blocking puts the new key there.
286
+ `--in` names the blocker, although the confirmation that `acli` prints names the `--out` side as the blocker. The two relationships differ only in which side the new key occupies: blocked-by puts the referenced key in `--in`, and blocking puts the new key there.
280
287
 
281
288
  If the available clients do not offer a link surface, report each link as skipped, naming the client.
282
289