codeassembly-guidance 0.1.0 → 0.3.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 (165) hide show
  1. package/.meta/changelog.json +984 -0
  2. package/CHANGELOG.md +240 -0
  3. package/README.md +45 -99
  4. package/bin/codeassembly-validate-preferences.js +18 -0
  5. package/content/_partials/README.md +21 -5
  6. package/content/_partials/comment-discipline.md +1 -1
  7. package/content/_partials/diff-audit-checklist.md +1 -0
  8. package/content/_partials/kb-standard-tags.md +7 -0
  9. package/content/_partials/plain-speech-calibration.md +4 -0
  10. package/content/_partials/technical-recommendations.md +1 -0
  11. package/content/codeassembly-content.yaml +17 -1
  12. package/content/collections/all.md +2 -2
  13. package/content/collections/atlassian.md +2 -1
  14. package/content/collections/recommended.md +9 -2
  15. package/content/collections/triage.md +3 -67
  16. package/content/collections/williamthorsen.md +2 -1
  17. package/content/guidance/README.md +1 -1
  18. package/content/guidance/rulebooks/accessibility-conventions.md +23 -5
  19. package/content/guidance/rulebooks/cli-conventions.md +206 -0
  20. package/content/guidance/rulebooks/codeassembly-content-specification.md +50 -10
  21. package/content/guidance/rulebooks/commit-conventions.md +5 -4
  22. package/content/guidance/rulebooks/live-worktree-policy.md +3 -2
  23. package/content/guidance/rulebooks/readme-conventions.md +3 -3
  24. package/content/guidance/rulebooks/shared-data-conventions.md +2 -2
  25. package/content/guidance/rulebooks/shell-conventions.md +17 -23
  26. package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
  27. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +18 -12
  28. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -3
  29. package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +6 -6
  30. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +1 -1
  31. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +7 -7
  32. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +28 -1
  33. package/content/guidance/shared/AGENTS.md +39 -4
  34. package/content/scripts/README.md +5 -2
  35. package/content/scripts/check-branch-currency.mjs +11 -0
  36. package/content/scripts/check-prose.mjs +171 -0
  37. package/content/scripts/describe-change.mjs +98 -98
  38. package/content/scripts/manage-jira-ticket.mjs +99 -94
  39. package/content/scripts/resolve-frontmatter.sh +1 -1
  40. package/content/scripts/resolve-review-run.mjs +9 -9
  41. package/content/scripts/select-lede-exemplars.mjs +87 -87
  42. package/content/scripts/validate-preferences.mjs +146 -0
  43. package/content/skills/_data/action-items.md +2 -0
  44. package/content/skills/_data/artifact-conventions.md +64 -16
  45. package/content/skills/_data/branch-currency.md +36 -0
  46. package/content/skills/_data/change-record.md +2 -2
  47. package/content/skills/_data/complexity-classification.md +1 -1
  48. package/content/skills/_data/design-priorities.md +15 -4
  49. package/content/skills/_data/project-stage.md +32 -0
  50. package/content/skills/_data/recommendation-gradient.md +9 -7
  51. package/content/skills/_data/scope-and-deferral.md +1 -1
  52. package/content/skills/_data/spike-conventions.md +21 -6
  53. package/content/skills/_data/ticket-evaluation.md +2 -2
  54. package/content/skills/_data/ticket-source-resolution.md +36 -3
  55. package/content/skills/_data/title-templates.md +22 -12
  56. package/content/skills/_partials/action-items.md +2 -2
  57. package/content/skills/_partials/apply-guidance-edits.md +5 -0
  58. package/content/skills/_partials/commit-title-rendering.md +1 -1
  59. package/content/skills/_partials/jira-task-list-flattening.md +1 -0
  60. package/content/skills/_partials/next-steps-after-plan.md +11 -11
  61. package/content/skills/_partials/option-format.md +18 -17
  62. package/content/skills/_partials/plan-template.md +7 -5
  63. package/content/skills/_partials/split-ticket-compose.md +1 -1
  64. package/content/skills/_partials/split-ticket-create.md +1 -1
  65. package/content/skills/_partials/ticket-and-plan-completeness.md +2 -2
  66. package/content/skills/_partials/ticket-composition.md +40 -0
  67. package/content/skills/_partials/ticket-criteria-conventions.md +3 -3
  68. package/content/skills/_partials/ticket-skeleton.md +15 -1
  69. package/content/skills/add-change-record/SKILL.md +2 -2
  70. package/content/skills/align-ticket-with-implementation/SKILL.md +3 -7
  71. package/content/skills/anti-patterns/SKILL.md +1 -1
  72. package/content/skills/assess-code-health/SKILL.md +127 -0
  73. package/content/skills/assess-code-health/assess-code-health.mjs +77 -0
  74. package/content/skills/assess-usability/SKILL.md +98 -0
  75. package/content/skills/capture-event/SKILL.md +4 -2
  76. package/content/skills/capture-event/capture-event.mjs +89 -89
  77. package/content/skills/capture-feedback/SKILL.md +1 -1
  78. package/content/skills/capture-lede-decision/SKILL.md +4 -4
  79. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +98 -98
  80. package/content/skills/collaborate/SKILL.md +3 -3
  81. package/content/skills/create-bitbucket-pr/SKILL.md +2 -1
  82. package/content/skills/create-commit/SKILL.md +1 -1
  83. package/content/skills/create-gh-pr/SKILL.md +28 -10
  84. package/content/skills/create-pr/SKILL.md +7 -6
  85. package/content/skills/create-ticket/SKILL.md +64 -23
  86. package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
  87. package/content/skills/derive-session-context/derive-session-context.mjs +83 -82
  88. package/content/skills/design-and-plan/SKILL.md +17 -18
  89. package/content/skills/groom-backlog/SKILL.md +8 -6
  90. package/content/skills/groom-backlog/groom-backlog.mjs +64 -62
  91. package/content/skills/implement-plan/SKILL.md +27 -23
  92. package/content/skills/index-prototypes/SKILL.md +86 -31
  93. package/content/skills/index-prototypes/index-prototypes.mjs +76 -16
  94. package/content/skills/kb-add/SKILL.md +4 -1
  95. package/content/skills/kb-add/kb-add.mjs +128 -128
  96. package/content/skills/kb-curate/SKILL.md +9 -7
  97. package/content/skills/kb-curate/kb-curate.mjs +103 -103
  98. package/content/skills/kb-edit/SKILL.md +5 -3
  99. package/content/skills/kb-edit/kb-edit.mjs +94 -94
  100. package/content/skills/kb-retrieve/kb-retrieve.mjs +86 -85
  101. package/content/skills/kb-retrieve-events/SKILL.md +20 -11
  102. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +86 -85
  103. package/content/skills/kb-update-events/SKILL.md +10 -7
  104. package/content/skills/kb-update-events/kb-update-events.mjs +110 -109
  105. package/content/skills/lesson-clusters/lesson-clusters.mjs +209 -0
  106. package/content/skills/merge-bb-pr/SKILL.md +1 -1
  107. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +5 -5
  108. package/content/skills/merge-pr/SKILL.md +11 -11
  109. package/content/skills/migrate-feedback-memories/SKILL.md +3 -2
  110. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +76 -76
  111. package/content/skills/plan/SKILL.md +2 -2
  112. package/content/skills/prepare-prototype-brief/SKILL.md +66 -14
  113. package/content/skills/pull-from-backlog/SKILL.md +3 -3
  114. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +83 -82
  115. package/content/skills/refine-guidance/SKILL.md +97 -0
  116. package/content/skills/refine-plan/SKILL.md +7 -3
  117. package/content/skills/refine-prototype/SKILL.md +113 -0
  118. package/content/skills/respond-to-review/SKILL.md +1 -1
  119. package/content/skills/review-bb-pr/SKILL.md +1 -1
  120. package/content/skills/review-branch/SKILL.md +354 -3
  121. package/content/skills/review-criteria/SKILL.md +36 -3
  122. package/content/skills/review-gh-pr/select-pr-ticket.mjs +6 -6
  123. package/content/skills/revise-comments/SKILL.md +38 -5
  124. package/content/skills/revise-prose/SKILL.md +1 -1
  125. package/content/skills/revise-prose/revise-prose.mjs +119 -119
  126. package/content/skills/save-artifact/SKILL.md +3 -1
  127. package/content/skills/streamline-guidance/SKILL.md +11 -16
  128. package/content/skills/streamline-guidance/streamline-guidance.mjs +86 -86
  129. package/content/skills/summarize-change/SKILL.md +23 -14
  130. package/content/skills/testing-conventions/SKILL.md +81 -8
  131. package/content/skills/triage-feedback/SKILL.md +150 -0
  132. package/content/skills/triage-feedback/triage-feedback.mjs +70 -0
  133. package/content/skills/triage-spike-findings/SKILL.md +113 -0
  134. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +73 -0
  135. package/content/skills/typescript-testing-conventions/SKILL.md +50 -1
  136. package/content/skills/update-jira-ticket/SKILL.md +20 -8
  137. package/content/skills/update-jira-ticket/update-jira-ticket.mjs +7 -7
  138. package/content/skills/update-project-guidance/SKILL.md +12 -12
  139. package/content/subagents/_data/claude.yaml +6 -0
  140. package/content/subagents/_data/rovo.yaml +12 -2
  141. package/content/subagents/canary.md +2 -1
  142. package/content/subagents/code-health-assessor.md +98 -0
  143. package/content/subagents/disposition-challenger.md +78 -0
  144. package/content/subagents/entry-drafter.md +14 -10
  145. package/content/subagents/feedback-triage-challenger.md +81 -0
  146. package/content/subagents/handoff-reviewer.md +2 -2
  147. package/content/subagents/lesson-clusterer.md +68 -0
  148. package/content/subagents/plan-reviewer.md +1 -1
  149. package/content/subagents/prose-reviser.md +4 -2
  150. package/content/subagents/ticket-assessor.md +9 -6
  151. package/content/subagents/usability-assessor.md +157 -0
  152. package/package.json +21 -17
  153. package/schemas/preferences.v1.json +50 -7
  154. package/schemas/work-types.v1.json +1 -1
  155. package/content/_partials/code-descriptions.md +0 -4
  156. package/content/_partials/code-style.md +0 -7
  157. package/content/_partials/live-repo-writes.md +0 -13
  158. package/content/_partials/reduced-object-relative.md +0 -28
  159. package/content/_partials/test-structure-audit-checklist.md +0 -7
  160. package/content/skills/_partials/acceptance-criteria-scaffold.md +0 -15
  161. package/content/skills/_partials/next-steps-after-review.md +0 -350
  162. package/content/skills/_partials/ticket-concision.md +0 -18
  163. package/content/skills/_partials/ticket-placement.md +0 -14
  164. package/content/skills/_partials/ticket-skeleton-tiers.md +0 -6
  165. package/content/skills/testing-conventions/mistakes.md +0 -1
@@ -13,11 +13,11 @@ This skill is invoked by a directive in the harness's global guidance during int
13
13
  ## Principles
14
14
 
15
15
  - Act as a conscientious collaborator, not a mindless code generator.
16
- - **Never make changes unless asked.** If the developer asks a question, answer it. If they comment on your work, address the comment. They are engaging in discussion.
16
+ - **Never make changes unless asked.** If the developer asks a question, answer it with an answer, not a procedure for them to run, and run any check that the answer needs. If they comment on your work, address the comment. They are engaging in discussion.
17
17
  - Don't let refactoring grow beyond the task; recommend the scope call, build on it, and raise it at the checkpoint.
18
18
  - Ask for guidance on naming and approach when the choice turns on the developer's preference; when a convention or the merits already settle it, state the decision with its reason and proceed.
19
19
  - Proceed provisionally: Decide what the gate lets you decide, record it, and collect the surviving asks into one review at the checkpoint.
20
- - Do every step yourself, verification included; the `## Handoffs` section of the collaboration preferences states when a step may leave your hands.
20
+ - Do every step yourself, verification included; the `## Handoffs` section of the collaboration preferences states when you may hand a step over.
21
21
  - When instructions have undiscussed implications, and you see flaws or meaningful improvements, raise them before proceeding.
22
22
 
23
23
  ## Concision by default
@@ -43,7 +43,7 @@ If the right answer depends on context that you don't yet have, get it before we
43
43
 
44
44
  ## Asking questions
45
45
 
46
- Not every response needs to end with a question. When you're ready to continue without a decision, a brief acknowledgment ("Ready for more.", "Got it.") is often better than inventing a question to fill the slot. A question that you could answer from evidence that you already hold is the same failure in a more diligent form: Answer it, give the reason in a clause, and carry on.
46
+ Not every response needs to end with a question. When you're ready to continue without a decision, a brief acknowledgment ("Ready for more.", "Got it.") is often better than inventing a question to fill the slot. A question that you could answer from evidence that you already hold is the same failure in a more diligent form: Answer it, give the reason in a clause, and carry on. When the developer signals overload, stop asking until they ask for something, per the "Prompt formatting" section of the collaboration preferences.
47
47
 
48
48
  When you do ask, prefer forms that the user can answer unambiguously:
49
49
 
@@ -21,6 +21,7 @@ This skill receives the following inputs from the orchestrator:
21
21
  | `ticket_id` | string | Ticket ID for artifact path resolution |
22
22
  | `project_slug` | string | Project slug for artifact path resolution |
23
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 |
24
25
 
25
26
  ## Process
26
27
 
@@ -32,7 +33,7 @@ Call `action: "create"` on the tool named in [Bitbucket pull-request access](../
32
33
  - **Description**: Use `body` as provided.
33
34
  - **Source branch**: Use the current branch, `git rev-parse --abbrev-ref HEAD`. The action requires it, and the delegate interface does not have a head-branch input.
34
35
  - **Destination branch**: Use `base_branch`.
35
- - **Draft/WIP**: Create as draft if the platform supports it.
36
+ - **Draft/WIP**: When `initial_state` is `draft`, create as draft if the platform supports it. When it is `ready`, create an open pull request.
36
37
 
37
38
  ### 2. Report every label as skipped
38
39
 
@@ -46,7 +46,7 @@ Record each unit as it is finished. Several single-concern commits read better t
46
46
  git commit --file "$body_path"
47
47
  ```
48
48
 
49
- 7. **Report the result**: the new commit's short SHA and title, or, when step 2 stopped or the commit failed, why nothing was committed.
49
+ 7. **Report the result**: the new commit's short SHA and title, or, when step 2 stopped or the commit failed, why nothing was committed. Do not comment on the title's format. The template sets which tokens the title contains, a ticket reference among them, so neither a token that the title omits nor a difference from earlier commits is a finding.
50
50
 
51
51
  ## Work type test
52
52
 
@@ -21,6 +21,7 @@ This skill receives the following inputs from the orchestrator:
21
21
  | `ticket_id` | string | Ticket ID for artifact path resolution |
22
22
  | `project_slug` | string | Project slug for artifact path resolution |
23
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 |
24
25
 
25
26
  ## Process
26
27
 
@@ -41,24 +42,39 @@ gh pr create \
41
42
  --title "{title}" \
42
43
  --body-file "$body_path" \
43
44
  --base "{base_branch}" \
44
- --draft \
45
+ {draft_flag} \
46
+ --assignee "@me" \
45
47
  {label_flags}
46
48
  ```
47
49
 
48
- `gh pr create` prints the pull-request URL. Read it from the command's output and include it in step 4's artifact and the completion line; never capture it into a shell variable.
50
+ `{draft_flag}` is `--draft` when `initial_state` is `draft`, and is left out of the call entirely when it is `ready`. Write it into the call as literal text, as the label flags are.
49
51
 
50
- ### 3. Handle label failures
52
+ `--assignee "@me"` assigns the pull request to the authenticated `gh` user, who is the developer creating it.
51
53
 
52
- If `gh pr create` fails and the error indicates one or more labels are invalid:
54
+ `gh pr create` prints the pull-request URL. Read it from the command's output and include it in step 5's artifact and the completion line; never capture it into a shell variable.
53
55
 
54
- 1. Identify the failing label(s) from the error message.
55
- 2. Remove the failing labels from the `--label` flags.
56
- 3. Retry `gh pr create` without the failing labels, re-stating the assignment and the guard for the same scratch file; do not rewrite the body or inline it.
57
- 4. Record which labels were skipped.
56
+ ### 3. Handle label and assignee failures
58
57
 
59
- If the failure is unrelated to labels, report the error and stop.
58
+ If `gh pr create` fails and the error indicates that one or more labels are invalid, or that the assignee cannot be assigned:
60
59
 
61
- ### 4. Save PR artifact
60
+ 1. Identify the failing labels, the assignee, or both from the error message.
61
+ 2. Remove the failing `--label` flags, and remove `--assignee` if the assignee failed.
62
+ 3. Retry `gh pr create` once without them, re-stating the `body_path` assignment and the guard for the same scratch file; do not rewrite the body or inline it.
63
+ 4. Record which labels were skipped, and whether the assignee was skipped, with the reason from the error.
64
+
65
+ If the failure is unrelated to labels and the assignee, report the error and stop.
66
+
67
+ ### 4. Read back the assignee
68
+
69
+ `gh` can create the pull request without applying an assignee that it cannot assign, so read the applied assignee from the created pull request rather than assuming it:
70
+
71
+ ```bash
72
+ gh pr view {PR URL} --json assignees --jq '[.assignees[].login] | join(", ")'
73
+ ```
74
+
75
+ An empty result means that the pull request has no assignee: Record the assignee as skipped, with the reason "not applied by GitHub" unless step 3 already recorded one.
76
+
77
+ ### 5. Save PR artifact
62
78
 
63
79
  Save a `pull-request` artifact in the ticket directory.
64
80
 
@@ -86,6 +102,7 @@ Created: {YYYY-MM-DD HH:MMZ}
86
102
  Labels attempted: {comma-separated list, or "none"}
87
103
  Labels applied: {comma-separated list, or "none"}
88
104
  Labels skipped: {comma-separated list, or "none"}
105
+ Assignee: {login read back in step 4, or "none"}
89
106
 
90
107
  ## Body
91
108
 
@@ -98,6 +115,7 @@ Labels skipped: {comma-separated list, or "none"}
98
115
  PR created: {URL}
99
116
  Labels applied: {list} <- only if labels were requested
100
117
  Labels skipped: {list} <- only if any labels failed
118
+ Assignee skipped: {reason} <- only if the pull request has no assignee
101
119
  Artifact saved: {artifact path}
102
120
  ```
103
121
 
@@ -8,7 +8,7 @@ user-invocable: true
8
8
 
9
9
  Create a pull request on the appropriate platform. This is the user-facing entry point that orchestrates the full PR creation flow, delegating platform-specific API calls to internal skills (`create-gh-pr`, `create-bitbucket-pr`).
10
10
 
11
- The pull request carries the change's entries and overrides in the `change-record` block that the change summary's body ends with, as [the change record](../_data/change-record.md) states them.
11
+ The pull request contains the change's entries and overrides in the `change-record` block that the change summary's body ends with, as [the change record](../_data/change-record.md) states them.
12
12
 
13
13
  ## Optional arguments
14
14
 
@@ -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`, and `artifact_base_dir` 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`, `project_slug`, `scm`, `default_branch`, `branch_name`, `artifact_base_dir`, and `pr_initial_state` from it.
25
25
 
26
26
  ### 2. Check branch sync
27
27
 
@@ -111,15 +111,15 @@ Read `scm` from the session context manifest:
111
111
 
112
112
  ### 9. Insert the closing line above the record block
113
113
 
114
- The body copied from the change summary already ends with the rendered `change-record` block, which `summarize-change` writes from the change entries. Carry it through unchanged: Do not render a block here, and never re-render one from the frontmatter, which does not record any entries.
114
+ The body copied from the change summary already ends with the rendered `change-record` block, which `summarize-change` writes from the change entries. Keep it unchanged: Do not render a block here, and never re-render one from the frontmatter, which does not record any entries.
115
115
 
116
- If `ticket_ref` is non-null, insert `Closes {ticket_ref}` above that block, separated from the text before it and from the block by one blank line each. The `Closes` keyword auto-closes the linked ticket when the PR merges (GitHub for numeric same-repo refs; Jira/Linear for prefixed IDs when their respective integrations are configured). Even when an auto-close integration is not wired up, the line documents the linkage and gives reviewers a clickable cross-reference.
116
+ If `ticket_ref` is non-null, insert `Closes {ticket_ref}` above that block, separated from the text before it and from the block by one blank line each. The `Closes` keyword auto-closes the linked ticket when the PR merges (GitHub for numeric same-repo refs; Jira/Linear for prefixed IDs when their respective integrations are configured). Even when an auto-close integration is not configured, the line documents the linkage and gives reviewers a clickable cross-reference.
117
117
 
118
118
  If `ticket_ref` is null, skip: no closing line.
119
119
 
120
- The closing line goes above the block rather than below it because the block is the body's last element, as [The `change-record` block](../_data/change-record.md#the-change-record-block) states. A merge reads the last `change-record` fence wherever it sits, so the order costs nothing to keep and the convention stays true.
120
+ The closing line goes above the block rather than below it because the block is the body's last element, as [The `change-record` block](../_data/change-record.md#the-change-record-block) states. A merge reads the last `change-record` fence wherever it is in the body, so keeping this order does not affect the merge, and the convention stays true.
121
121
 
122
- If the change summary's body does not end with a block, append the closing line as the body's last line and say that the pull request does not contain a change record, naming `{skill:add-change-record}` as the skill that adds one. A body reaches this step without one when `summarize-change` reported that `render-block` was unavailable or failed.
122
+ If the change summary's body does not end with a block, append the closing line as the body's last line and say that the pull request does not contain a change record, naming `{skill:add-change-record}` as the skill that adds one. The change summary's body does not end with a block when `summarize-change` reported that `render-block` was unavailable or failed.
123
123
 
124
124
  ### 10. Call delegate
125
125
 
@@ -134,6 +134,7 @@ Pass the following inputs to the selected delegate per the delegate interface:
134
134
  | `ticket_id` | From session context |
135
135
  | `project_slug` | From session context |
136
136
  | `artifact_base_dir` | From session context |
137
+ | `initial_state` | `pr_initial_state` from session context: `draft` or `ready` |
137
138
 
138
139
  ### 11. Persist the PR URL
139
140
 
@@ -18,8 +18,24 @@ Create a ticket on the appropriate platform. The remote platform (e.g., GitHub)
18
18
  | `--parent <ref>` | Make the new ticket a child of the referenced ticket. One reference; a ticket has one parent. |
19
19
  | `--blocked-by <refs>` | Mark the new ticket as blocked by the referenced tickets. |
20
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). |
21
23
 
22
- Each takes ticket references in the project's own form (`#123`, `ABC-123`), comma-separated when more than one applies. All three are optional, and each overrides the inference in step 4 for its own relationship.
24
+ 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
+ ### Another repository
27
+
28
+ `--repo` files the ticket in another GitHub repository, and every step resolves against that repository rather than the session's: its configuration, its issues, and its artifact directory. Compare the value with `gh repo view --json nameWithOwner --jq .nameWithOwner`, ignoring case; when the two name the same repository, drop `--repo` and run as though it were absent. When the command fails, as it does in a session whose repository is not on GitHub, the two are different repositories.
29
+
30
+ Otherwise, resolve the target before step 1:
31
+
32
+ ```bash
33
+ node {harness_home_dir}/skills/create-ticket/resolve-ticket-target.mjs --repo {OWNER/REPO}
34
+ ```
35
+
36
+ It prints `{"repo": "...", "projectRoot": "...", "projectSlug": "...", "ticketRefPrefix": "...", "missing": [...]}`. `repo` is the canonical `OWNER/REPO`, used as `{target_repo}` below. `projectRoot` is a directory that contains the target's `.meta/label-map.json` and `.agents/preferences.yaml` as they appear on its default branch; `missing` names each that it does not contain, and the completion output reports each. On a non-zero exit, nothing has been created: Report the helper's stderr and stop.
37
+
38
+ The steps below state what changes for a target repository. A step that does not mention it runs unchanged.
23
39
 
24
40
  <!-- guidance-hook: ticketing-preferences -->
25
41
 
@@ -33,6 +49,8 @@ Get `project_slug` and `artifact_base_dir` -- but NOT the new ticket's `ticket_i
33
49
  - From the same manifest JSON, also read `ticket_id` as `branch_ticket_id`, the ticket from which the current branch is derived (empty when the branch name does not encode a ticket). The step-4 inference and the step-6 guard both read it; the new ticket's authoritative `ticket_id` still comes from the platform in step 6. Read `branch_name` and `default_branch` too, which the step-6 guard compares.
34
50
  - Read `project.ticket_ref_prefix` from `.agents/preferences.yaml` (e.g., `CODY-`); if absent, default to empty string
35
51
 
52
+ For a [target repository](#another-repository), take `project_slug` from the helper's `projectSlug` and `ticket_ref_prefix` from its `ticketRefPrefix` instead. `artifact_base_dir` stays the session's.
53
+
36
54
  ### 2. Write ticket content
37
55
 
38
56
  Create the ticket body describing WHAT needs to be done: problem, context, and acceptance criteria. Do NOT include the plan inline. Do NOT include the ticket ID in the heading yet (it's not known until step 6).
@@ -43,26 +61,26 @@ Create the ticket body describing WHAT needs to be done: problem, context, and a
43
61
 
44
62
  **Spike mode.** If the ticket describes a spike, use the spike ticket template in [spike conventions](../_data/spike-conventions.md) in place of the skeleton above.
45
63
 
46
- <!-- include: ../_partials/ticket-skeleton-tiers.md / -->
47
-
48
- <!-- include: ../_partials/ticket-concision.md / -->
49
-
50
- <!-- include: ../../_partials/prose-line-breaks.md / -->
51
-
52
- <!-- include: ../_partials/ticket-placement.md / -->
64
+ <!-- include: ../_partials/ticket-composition.md / -->
53
65
 
54
66
  `create-ticket` does not produce a plan, so _the implementation_ is derived when the work is later planned; state the subject and outcomes, and leave mechanism for that step.
55
67
 
56
68
  <!-- include: ../_partials/ticket-criteria-conventions.md / -->
57
69
 
70
+ <!-- include: ../../_partials/prose-line-breaks.md / -->
71
+
58
72
  Also draft the ticket string, per [`title-voice.md`](../_data/title-voice.md), for use in step 6.
59
73
 
60
74
  Then decide the ticket's scope and type, for use in steps 5 and 6. The type is the [work type](../_data/work-types.json) of the change that the ticket asks for: a ticket reporting a defect is `fix`, and one asking for a new capability is `feat`. Append `!` only when the proposed change breaks consumers and the type's `breakingPolicy` admits the marker. The scope is the workspace that the change belongs to, per [Scope values](../_data/title-templates.md#scope-values); a change spanning more than one takes `*`, which does not render or label any scope. The pull request that implements the ticket compares its derived type with the type label applied here.
61
75
 
62
76
  <!-- include: ../../_partials/work-type-choice.md / -->
63
77
 
78
+ For a [target repository](#another-repository), the scope is a key of the `scopes` section in `{projectRoot}/.meta/label-map.json`, or `*` when the target does not have a label map.
79
+
64
80
  ### 3. Resolve platform
65
81
 
82
+ For a [target repository](#another-repository), the platform is GitHub: Skip this step.
83
+
66
84
  Determine where to create the remote ticket:
67
85
 
68
86
  1. **Preferences**: Check `.agents/preferences.yaml` → `integrations`:
@@ -70,12 +88,12 @@ Determine where to create the remote ticket:
70
88
  - If exactly one integration is enabled → use it
71
89
  - If multiple enabled → ask
72
90
 
73
- 2. **Git remote**: if the preferences do not explicitly enable any integration:
91
+ 2. **Git remote**: If the preferences do not explicitly enable any integration:
74
92
 
75
93
  - `git remote get-url origin` pointing to `github.com` → GitHub
76
94
  - Other hosts → ask
77
95
 
78
- 3. **Ask**: if platform cannot be determined
96
+ 3. **Ask**: If platform cannot be determined
79
97
 
80
98
  ### 4. Decide relationships
81
99
 
@@ -87,9 +105,11 @@ Three relationships are available, each stated from the new ticket's side:
87
105
 
88
106
  Decide which apply from the reason this ticket is being created, narrowed by `branch_ticket_id` (step 1): Work split out of the current branch's ticket relates to it, and a backlog idea raised in passing does not. An argument supplied by the caller replaces the inference for its own relationship.
89
107
 
108
+ 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
+
90
110
  **Most tickets have none, and for those, say nothing.** When nothing applies, continue to step 5 without asking.
91
111
 
92
- 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. If the platform resolved in step 3 cannot express one of them, say so here rather than leaving it to appear as a skip in step 7.
112
+ 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.
93
113
 
94
114
  <!-- include: ../_partials/action-items.md / -->
95
115
 
@@ -101,9 +121,13 @@ If the platform resolved in step 3 is GitHub, resolve the labels from the scope
101
121
  node {harness_home_dir}/scripts/describe-change.mjs resolve-labels --scope "{scope}" --type "{type}"
102
122
  ```
103
123
 
124
+ For a [target repository](#another-repository), add `--project-root "{projectRoot}"`, so that the labels come from the target's label map.
125
+
104
126
  Read `labels` from the output, `{"labels":["feature","breaking","scope:agents"]}`; [`resolve-labels`](../_data/title-templates.md#resolve-labels) states what it contains. When the list is empty, the create call does not apply any labels. Relay any warning that the run writes to stderr.
105
127
 
106
- Render one `--label "{label_name}"` flag per returned label, and write them into the create call in step 6 as literal text. A shell variable does not survive the Bash invocation that assigns it, so a call that reads one from an earlier call does not apply any labels at all.
128
+ Append the labels given through `--label` to the returned list; they add to the resolved scope and type labels and never replace them. `gh issue create` fails on a label that the repository does not have, so the caller of `--label` checks that each label exists before invoking this skill. On the Jira path, `--label` is not applied: Report it skipped in the completion output.
129
+
130
+ Render one `--label "{label_name}"` flag per label in the combined list, and write them into the create call in step 6 as literal text. Because a shell variable does not survive the Bash invocation that assigns it, a call that reads one from an earlier call does not apply any labels at all.
107
131
 
108
132
  ### 6. Create remote ticket
109
133
 
@@ -118,6 +142,8 @@ node {harness_home_dir}/scripts/describe-change.mjs render-titles --title "{titl
118
142
  | python3 -c "import sys,json; print(json.load(sys.stdin).get('ticket_title',''))"
119
143
  ```
120
144
 
145
+ For a [target repository](#another-repository), add `--project-root "{projectRoot}"`, so that the title follows the target's `ticket.title_format`.
146
+
121
147
  Use a JSON parser (python3 above; `jq -r '.ticket_title'` if `jq` is available) instead of `grep`/`cut` because rendered titles may contain backslash-escaped double quotes (`\"`), which a regex extractor would silently truncate.
122
148
 
123
149
  The pipeline prints the rendered title. Read it from the command's output and write it into the create call below as literal text, as the GitHub issue title or the Jira summary; it already includes any prefix (per the configured `ticket.title_format`) and the bare title text. Assigning the parse instead prints nothing, and a shell variable does not survive to the create call, so a call that reads `$ticket_title` submits an empty title. If the script is not found, fall back to the bare `{title}`.
@@ -129,9 +155,11 @@ Write the body to a scratch file per [gh body file](#gh-body-file), naming it `g
129
155
  ```bash
130
156
  body_path="{absolute path from the write step}"
131
157
  [ -s "$body_path" ] || { echo "Body file missing or empty: $body_path" >&2; exit 1; }
132
- gh issue create --title "{ticket_title}" --body-file "$body_path" {label_flags}
158
+ gh issue create --title "{ticket_title}" --body-file "$body_path" {label_flags} {repo_flag}
133
159
  ```
134
160
 
161
+ `{repo_flag}` is `--repo {target_repo}` for a [target repository](#another-repository), and empty otherwise; steps 7 and 9 pass it to `gh` the same way.
162
+
135
163
  `gh issue create` prints the issue URL. Read it from the command's output; the issue number is its final path segment. Never capture either into a shell variable.
136
164
 
137
165
  Construct the ticket ID from `ticket_ref_prefix` (step 1) and `number`:
@@ -156,6 +184,8 @@ When the preferences do not name a project, the helper prints `{"fallback": "no-
156
184
 
157
185
  Identify the client per {skill?:update-jira-ticket}, which ranks the three client shapes and states the description format that each one takes. If it identifies none, take the [no-remote fallback](#fallback-no-remote-platform), naming the absent client in the warning.
158
186
 
187
+ <!-- include: ../_partials/jira-task-list-flattening.md / -->
188
+
159
189
  - **`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.
160
190
  - **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.
161
191
  - **`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:
@@ -166,10 +196,11 @@ Identify the client per {skill?:update-jira-ticket}, which ranks the three clien
166
196
 
167
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`.
168
198
 
169
- The helper 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}`. `parentSkipped: true` means that Jira rejected the parent reference and the work item was created without it; report the parent skipped per step 7.
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.
170
200
 
171
201
  On a non-zero exit, read what it printed:
172
- - `{"fallback": ...}`: As under [Resolve the target](#resolve-the-target), and `acli` was not called.
202
+ - `{"fallback": "no-project-key"}`: As under [Resolve the target](#resolve-the-target), and `acli` was not called.
203
+ - `{"fallback": "wrong-site"}` or `{"fallback": "site-unreadable"}`: `acli` is signed in to another site, or its site could not be read, and nothing was created. Create through the next client that {skill?:update-jira-ticket} ranks, including a client that the machine adds. When none remains, take the [no-remote fallback](#fallback-no-remote-platform) with the helper's warning, which names both sites and the `acli jira auth switch` command. Never run that command, because the active site is shared by every session on the machine.
173
204
  - `"key": null`: The create call ran, and stderr says why the key is missing. Read the key from `rawOutput` when it contains one, and otherwise check Jira for the work item. Never run `create` again: A second call creates a second work item.
174
205
  - Nothing: An argument or the body file was rejected before any `acli` call, as stderr states. Fix it and run the helper again.
175
206
 
@@ -181,6 +212,8 @@ Identify the client per {skill?:update-jira-ticket}, which ranks the three clien
181
212
 
182
213
  #### Persist the branch association
183
214
 
215
+ For a [target repository](#another-repository), skip this section and report the skip, e.g. `Ticket {target_repo}#{number} filed in another repository; skipped branch-manifest association.` The `ticket_id` comparison below would match a target issue whose number equals the branch's ticket ID.
216
+
184
217
  Persist the new ticket's URL into the branch manifest so that later sessions reuse it (see [ticket source resolution](../_data/ticket-source-resolution.md#stored-ticket-url)), but only when the new ticket belongs to the current branch. Compare `branch_ticket_id` (step 1) against the `ticket_id` produced by the path above, and `branch_name` against `default_branch` (both step 1). The second comparison strips `default_branch`'s remote first, taking everything after its first `/`, since `default_branch` is remote-qualified (`origin/main`) whereas `branch_name` is bare (`main`). Comparing the two as written does not match on any branch and silently disables the guard.
185
218
 
186
219
  - When the branch is not the default branch, and `branch_ticket_id` is either empty (the branch name does not encode a ticket) or equal to `ticket_id` (the branch is already linked to this ticket), persist:
@@ -195,7 +228,7 @@ Persist the new ticket's URL into the branch manifest so that later sessions reu
195
228
 
196
229
  The deriver refuses the write on the default branch regardless, per [Stored ticket URL](../_data/ticket-source-resolution.md#stored-ticket-url). Deciding it here produces the reported skip rather than a stderr diagnostic that never appears in the completion output.
197
230
 
198
- Compare `ticket_id` rather than a bare issue number. `branch_ticket_id` comes from the same deriver logic that the GitHub path's construction mirrors, so the two agree in form on every project: bare when `ticket_ref_prefix` is `#` or absent, prefixed when it is a project key. Comparing a bare number holds only in the first case and silently skips every persist in the second.
231
+ Compare `ticket_id` rather than a bare issue number. `branch_ticket_id` comes from the same deriver logic that the GitHub path's construction mirrors, so the two agree in form on every project: bare when `ticket_ref_prefix` is `#` or absent, prefixed when it is a project key. Comparing a bare number works only in the first case and silently skips every persist in the second.
199
232
 
200
233
  Skip this section entirely when step 6 did not resolve a URL; there is nothing to store.
201
234
 
@@ -203,7 +236,7 @@ Skip this section entirely when step 6 did not resolve a URL; there is nothing t
203
236
 
204
237
  Skip this step when step 4 decided none.
205
238
 
206
- When step 6 did not create a remote ticket (the [no-remote fallback](#fallback-no-remote-platform)), there is nothing to link. Skip every relationship that step 4 decided, each with that as its reason, and report them. A relationship confirmed by the user never disappears without a line in the completion output.
239
+ When step 6 did not create a remote ticket (the [no-remote fallback](#fallback-no-remote-platform)), there is nothing to link. Skip every relationship that step 4 decided, each with that as its reason, and report them. Never drop a relationship confirmed by the user without a line in the completion output.
207
240
 
208
241
  Otherwise apply relationships after the ticket exists rather than as part of creating it. A reference rejected by the platform then fails only the link; the same reference passed to the creation call would fail the creation of the ticket. Jira's clients force an exception for the parent, and the Jira path below states what replaces the guarantee there.
209
242
 
@@ -212,12 +245,12 @@ Otherwise apply relationships after the ticket exists rather than as part of cre
212
245
  One call applies every relationship decided:
213
246
 
214
247
  ```bash
215
- gh issue edit {number} --parent "{parent}" --add-blocked-by "{blocked_by}" --add-blocking "{blocking}"
248
+ gh issue edit {number} --parent "{parent}" --add-blocked-by "{blocked_by}" --add-blocking "{blocking}" {repo_flag}
216
249
  ```
217
250
 
218
251
  Omit the flag for any relationship that step 4 did not decide. Each takes issue numbers or URLs, comma-separated for the two that accept several.
219
252
 
220
- These flags are native to `gh` 2.94 and later. They are not the REST dependencies endpoint, which takes an issue's database `id` rather than its number; reaching for that endpoint is the detour that this note exists to prevent.
253
+ These flags are native to `gh` 2.94 and later. They are not the REST dependencies endpoint, which takes an issue's database `id` rather than its number; using that endpoint is the mistake that this note exists to prevent.
221
254
 
222
255
  #### Jira path
223
256
 
@@ -231,7 +264,13 @@ Through a connected tool, use the link type named `Blocks`, falling back to a ty
231
264
 
232
265
  The two clients take opposite argument orders for the same relationship: `acli --out` names the blocker, whereas a connected tool's `inwardIssue` does. A link type's inward and outward descriptions describe how Jira stores the link, and only `acli`'s argument names follow that orientation, so take each client's mapping from its own documentation and the descriptions only to select the type.
233
266
 
234
- Through `acli`:
267
+ After a create through `acli`, the work item is on the active site; link through `acli` without a further check. After a create through another client, first compare the active site with `ticket_base_url` (step 1) when it is set, and report each link skipped with the helper's stderr line when it exits non-zero:
268
+
269
+ ```bash
270
+ node {harness_home_dir}/scripts/manage-jira-ticket.mjs check-site --target {ticket_base_url}
271
+ ```
272
+
273
+ Then:
235
274
 
236
275
  ```bash
237
276
  acli jira workitem link create --out "{blocker}" --in "{blocked}" --type Blocks --yes
@@ -299,12 +338,12 @@ Then attach it as a comment on the remote ticket, through the platform resolved
299
338
  ```bash
300
339
  body_path="{absolute path from the write step}"
301
340
  [ -s "$body_path" ] || { echo "Body file missing or empty: $body_path" >&2; exit 1; }
302
- gh issue comment {number} --body-file "$body_path"
341
+ gh issue comment {number} --body-file "$body_path" {repo_flag}
303
342
  ```
304
343
 
305
- **Jira.** Comment through the client that created the work item, in the format assigned to that client by {skill?:update-jira-ticket}: a connected tool's own comment surface, or `acli` reading the comment as ADF from a scratch file.
344
+ **Jira.** Comment through the client that created the work item, in the format assigned to that client by {skill?:update-jira-ticket}: a connected tool's own comment surface, or `acli` reading the comment as ADF from a scratch file. Flatten task lists for a connected tool as [Create the work item](#create-the-work-item) states.
306
345
 
307
- The scratch file follows [gh body file](#gh-body-file), whose rules are about the path rather than the platform: `acli` reads a file the same way `gh` does, and a path carried between Bash invocations resolves to nothing either way.
346
+ The scratch file follows [gh body file](#gh-body-file), whose rules are about the path rather than the platform: `acli` reads a file the same way `gh` does, and a path passed between Bash invocations resolves to nothing either way.
308
347
 
309
348
  ```bash
310
349
  adf_path="{absolute path from the write step}"
@@ -342,7 +381,9 @@ Plan saved: {plan artifact path} <- only if plan existed
342
381
  Plan comment skipped: {reason} <- only if a plan was saved but not attached
343
382
  Relationships: {list} <- only if any were created
344
383
  Relationships skipped: {list with reasons} <- only if any were skipped
384
+ Labels skipped: {labels} <- only when `--label` was given on the Jira path
345
385
  Branch association skipped: {reason} <- only when the step-6 guard skipped the persist
386
+ Target configuration missing: {files} <- only when the target's default branch lacks a file in `missing`
346
387
  ```
347
388
 
348
389
  Nothing else.