codeassembly-guidance 0.0.0 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (204) hide show
  1. package/.meta/changelog.json +563 -0
  2. package/CHANGELOG.md +134 -0
  3. package/LICENSE +7 -0
  4. package/README.md +165 -1
  5. package/content/_partials/README.md +192 -0
  6. package/content/_partials/code-descriptions.md +4 -0
  7. package/content/_partials/code-style.md +7 -0
  8. package/content/_partials/comment-discipline.md +89 -0
  9. package/content/_partials/concision.md +3 -0
  10. package/content/_partials/diff-audit-checklist.md +9 -0
  11. package/content/_partials/file-access.md +4 -0
  12. package/content/_partials/live-repo-writes.md +13 -0
  13. package/content/_partials/plain-speech-calibration.md +66 -0
  14. package/content/_partials/plain-speech.md +13 -0
  15. package/content/_partials/prose-line-breaks.md +3 -0
  16. package/content/_partials/record-marker.md +1 -0
  17. package/content/_partials/reduced-object-relative.md +28 -0
  18. package/content/_partials/shell-commands.md +3 -0
  19. package/content/_partials/target-file-set-resolution.md +22 -0
  20. package/content/_partials/technical-recommendations.md +5 -0
  21. package/content/_partials/test-structure-audit-checklist.md +7 -0
  22. package/content/_partials/ticket-assessment-baseline.md +12 -0
  23. package/content/_partials/ticket-assessment.md +202 -0
  24. package/content/_partials/work-type-choice.md +13 -0
  25. package/content/codeassembly-content.yaml +49 -0
  26. package/content/collections/all.md +11 -0
  27. package/content/collections/atlassian.md +16 -0
  28. package/content/collections/recommended.md +34 -0
  29. package/content/collections/triage.md +77 -0
  30. package/content/collections/williamthorsen.md +25 -0
  31. package/content/guidance/README.md +22 -0
  32. package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
  33. package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
  34. package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
  35. package/content/guidance/rulebooks/accessibility-conventions.md +20 -0
  36. package/content/guidance/rulebooks/codeassembly-content-specification.md +161 -0
  37. package/content/guidance/rulebooks/command-output-conventions.md +14 -0
  38. package/content/guidance/rulebooks/commit-conventions.md +72 -0
  39. package/content/guidance/rulebooks/generated-content-policy.md +10 -0
  40. package/content/guidance/rulebooks/live-worktree-policy.md +18 -0
  41. package/content/guidance/rulebooks/readme-conventions.md +74 -0
  42. package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
  43. package/content/guidance/rulebooks/shell-conventions.md +279 -0
  44. package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
  45. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +58 -0
  46. package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
  47. package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
  48. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
  49. package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
  50. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
  51. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
  52. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
  53. package/content/guidance/shared/AGENTS.md +43 -0
  54. package/content/scripts/README.md +41 -0
  55. package/content/scripts/describe-change.mjs +165 -0
  56. package/content/scripts/get-ticket-id.sh +131 -0
  57. package/content/scripts/manage-jira-ticket.mjs +209 -0
  58. package/content/scripts/resolve-frontmatter.sh +540 -0
  59. package/content/scripts/resolve-review-run.mjs +12 -0
  60. package/content/scripts/select-lede-exemplars.mjs +208 -0
  61. package/content/skills/_data/action-items.md +83 -0
  62. package/content/skills/_data/artifact-conventions.md +969 -0
  63. package/content/skills/_data/bitbucket-pr-access.md +89 -0
  64. package/content/skills/_data/branch-format.md +34 -0
  65. package/content/skills/_data/change-record.md +163 -0
  66. package/content/skills/_data/complexity-classification.md +58 -0
  67. package/content/skills/_data/concision.md +23 -0
  68. package/content/skills/_data/deployed-file-provenance.md +46 -0
  69. package/content/skills/_data/design-priorities.md +76 -0
  70. package/content/skills/_data/gh-body-file.md +30 -0
  71. package/content/skills/_data/git-commands.md +39 -0
  72. package/content/skills/_data/naming-conventions.md +50 -0
  73. package/content/skills/_data/pr-resolution.md +25 -0
  74. package/content/skills/_data/pr-source-resolution.md +36 -0
  75. package/content/skills/_data/recommendation-gradient.md +90 -0
  76. package/content/skills/_data/scope-and-deferral.md +83 -0
  77. package/content/skills/_data/spike-conventions.md +89 -0
  78. package/content/skills/_data/ticket-evaluation.md +13 -0
  79. package/content/skills/_data/ticket-id-extraction.md +43 -0
  80. package/content/skills/_data/ticket-source-resolution.md +147 -0
  81. package/content/skills/_data/title-templates.md +624 -0
  82. package/content/skills/_data/title-voice.md +17 -0
  83. package/content/skills/_data/work-types.json +168 -0
  84. package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
  85. package/content/skills/_partials/action-items.md +22 -0
  86. package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
  87. package/content/skills/_partials/commit-title-rendering.md +14 -0
  88. package/content/skills/_partials/gh-body-file.md +22 -0
  89. package/content/skills/_partials/nested-list-indent.md +9 -0
  90. package/content/skills/_partials/next-steps-after-plan.md +99 -0
  91. package/content/skills/_partials/next-steps-after-review.md +350 -0
  92. package/content/skills/_partials/option-format.md +84 -0
  93. package/content/skills/_partials/plan-template.md +97 -0
  94. package/content/skills/_partials/split-launch-prompts.md +5 -0
  95. package/content/skills/_partials/split-ticket-compose.md +5 -0
  96. package/content/skills/_partials/split-ticket-create.md +3 -0
  97. package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
  98. package/content/skills/_partials/ticket-concision.md +18 -0
  99. package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
  100. package/content/skills/_partials/ticket-placement.md +14 -0
  101. package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
  102. package/content/skills/_partials/ticket-skeleton.md +13 -0
  103. package/content/skills/add-change-record/SKILL.md +136 -0
  104. package/content/skills/add-test-ids/SKILL.md +51 -0
  105. package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
  106. package/content/skills/anti-patterns/SKILL.md +57 -0
  107. package/content/skills/assess-ticket/SKILL.md +46 -0
  108. package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
  109. package/content/skills/brainstorming/SKILL.md +107 -0
  110. package/content/skills/capture-event/SKILL.md +108 -0
  111. package/content/skills/capture-event/capture-event.mjs +216 -0
  112. package/content/skills/capture-feedback/SKILL.md +71 -0
  113. package/content/skills/capture-lede-decision/SKILL.md +163 -0
  114. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
  115. package/content/skills/classify-complexity/SKILL.md +92 -0
  116. package/content/skills/collaborate/SKILL.md +86 -0
  117. package/content/skills/condense-branch/SKILL.md +83 -0
  118. package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
  119. package/content/skills/create-commit/SKILL.md +65 -0
  120. package/content/skills/create-devlog/SKILL.md +108 -0
  121. package/content/skills/create-gh-pr/SKILL.md +106 -0
  122. package/content/skills/create-pr/SKILL.md +150 -0
  123. package/content/skills/create-ticket/SKILL.md +350 -0
  124. package/content/skills/derive-session-context/derive-session-context.mjs +148 -0
  125. package/content/skills/design-and-plan/SKILL.md +194 -0
  126. package/content/skills/development-workflows/SKILL.md +41 -0
  127. package/content/skills/get-ticket-id/SKILL.md +67 -0
  128. package/content/skills/groom-backlog/SKILL.md +245 -0
  129. package/content/skills/groom-backlog/groom-backlog.mjs +106 -0
  130. package/content/skills/implement-plan/SKILL.md +164 -0
  131. package/content/skills/index-prototypes/SKILL.md +145 -0
  132. package/content/skills/index-prototypes/index-prototypes.mjs +328 -0
  133. package/content/skills/kb-add/SKILL.md +156 -0
  134. package/content/skills/kb-add/kb-add.mjs +216 -0
  135. package/content/skills/kb-curate/SKILL.md +117 -0
  136. package/content/skills/kb-curate/kb-curate.mjs +213 -0
  137. package/content/skills/kb-edit/SKILL.md +128 -0
  138. package/content/skills/kb-edit/kb-edit.mjs +219 -0
  139. package/content/skills/kb-retrieve/SKILL.md +100 -0
  140. package/content/skills/kb-retrieve/kb-retrieve.mjs +206 -0
  141. package/content/skills/kb-retrieve-events/SKILL.md +98 -0
  142. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +206 -0
  143. package/content/skills/kb-update-events/SKILL.md +77 -0
  144. package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
  145. package/content/skills/merge-bb-pr/SKILL.md +136 -0
  146. package/content/skills/merge-gh-pr/SKILL.md +167 -0
  147. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
  148. package/content/skills/merge-pr/SKILL.md +368 -0
  149. package/content/skills/migrate-feedback-memories/SKILL.md +136 -0
  150. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
  151. package/content/skills/people-report/SKILL.md +208 -0
  152. package/content/skills/plan/SKILL.md +87 -0
  153. package/content/skills/prepare-prototype-brief/SKILL.md +126 -0
  154. package/content/skills/pull-from-backlog/SKILL.md +83 -0
  155. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +208 -0
  156. package/content/skills/refine-plan/SKILL.md +259 -0
  157. package/content/skills/respond-to-review/SKILL.md +292 -0
  158. package/content/skills/review-bb-pr/SKILL.md +161 -0
  159. package/content/skills/review-branch/SKILL.md +301 -0
  160. package/content/skills/review-criteria/SKILL.md +108 -0
  161. package/content/skills/review-gh-pr/SKILL.md +155 -0
  162. package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
  163. package/content/skills/review-permissions/SKILL.md +39 -0
  164. package/content/skills/review-pr/SKILL.md +123 -0
  165. package/content/skills/revise-comments/SKILL.md +115 -0
  166. package/content/skills/revise-prose/SKILL.md +197 -0
  167. package/content/skills/revise-prose/revise-prose.mjs +229 -0
  168. package/content/skills/save-artifact/SKILL.md +69 -0
  169. package/content/skills/save-plan/SKILL.md +55 -0
  170. package/content/skills/software-engineering/SKILL.md +74 -0
  171. package/content/skills/streamline-guidance/SKILL.md +174 -0
  172. package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
  173. package/content/skills/summarize-change/SKILL.md +308 -0
  174. package/content/skills/summarize-chat/SKILL.md +100 -0
  175. package/content/skills/systematic-debugging/SKILL.md +308 -0
  176. package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
  177. package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
  178. package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
  179. package/content/skills/systematic-debugging/find-polluter.sh +68 -0
  180. package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
  181. package/content/skills/systematic-debugging/test-academic.md +16 -0
  182. package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
  183. package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
  184. package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
  185. package/content/skills/testing-conventions/SKILL.md +168 -0
  186. package/content/skills/testing-conventions/mistakes.md +1 -0
  187. package/content/skills/typescript-testing-conventions/SKILL.md +129 -0
  188. package/content/skills/update-jira-ticket/SKILL.md +245 -0
  189. package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
  190. package/content/skills/update-project-guidance/SKILL.md +300 -0
  191. package/content/skills/upgrade-dependencies/SKILL.md +139 -0
  192. package/content/skills/wrap-up/SKILL.md +431 -0
  193. package/content/subagents/_data/claude.yaml +19 -0
  194. package/content/subagents/_data/rovo.yaml +31 -0
  195. package/content/subagents/canary.md +11 -0
  196. package/content/subagents/entry-drafter.md +187 -0
  197. package/content/subagents/handoff-reviewer.md +75 -0
  198. package/content/subagents/plan-reviewer.md +184 -0
  199. package/content/subagents/plan-reviser.md +88 -0
  200. package/content/subagents/prose-reviser.md +130 -0
  201. package/content/subagents/ticket-assessor.md +139 -0
  202. package/package.json +70 -2
  203. package/schemas/preferences.v1.json +294 -0
  204. package/schemas/work-types.v1.json +142 -0
@@ -0,0 +1,150 @@
1
+ ---
2
+ name: create-pr
3
+ description: Create a pull request by orchestrating change summary, title rendering, label resolution, and platform delegation
4
+ user-invocable: true
5
+ ---
6
+
7
+ # Create pull request
8
+
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
+
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.
12
+
13
+ ## Optional arguments
14
+
15
+ - `--scope {scope}`: Override the scope that `summarize-change` derives.
16
+ - `--type {type}`: Override the work type that `summarize-change` derives. A `!` on it (`feat!`) also adds the breaking marker.
17
+
18
+ Both are passed to `summarize-change`, which records them as overrides beside the consolidated record.
19
+
20
+ ## Process
21
+
22
+ ### 1. Get session context
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.
25
+
26
+ ### 2. Check branch sync
27
+
28
+ Verify the current branch is up to date with remote:
29
+
30
+ ```bash
31
+ git fetch origin
32
+ git status
33
+ ```
34
+
35
+ If the branch is not up to date with remote, **STOP THIS TASK** and notify the user. Do not proceed to `summarize-change` or any later step. Otherwise, continue.
36
+
37
+ ### 3. Call `summarize-change`
38
+
39
+ Invoke the `{skill:summarize-change}` skill to produce a change summary, passing `--scope` and `--type` when either was provided. The change summary's frontmatter contains the fields that [Change-summary frontmatter](../_data/artifact-conventions.md#change-summary-frontmatter) lists.
40
+
41
+ ### 4. Read frontmatter
42
+
43
+ Read the YAML frontmatter from the change summary. Extract `title`, the consolidated record's `scope`, `type`, and `breaking`, and the `override_scope`, `override_type`, and `override_breaking` fields. Any of the last six may be absent.
44
+
45
+ ### 5. Resolve the effective record
46
+
47
+ Resolve the effective record from the frontmatter:
48
+
49
+ ```bash
50
+ node {harness_home_dir}/scripts/describe-change.mjs resolve-effective-record \
51
+ --title "{title}" \
52
+ --scope "{scope}" \
53
+ --type "{type}" \
54
+ --breaking \
55
+ --override-scope "{override_scope}" \
56
+ --override-type "{override_type}" \
57
+ --override-breaking
58
+ ```
59
+
60
+ Omit each flag whose field is absent from the frontmatter, and pass `--breaking` and `--override-breaking` only if that field is `true`. Read `effective_record` from the output; [`resolve-effective-record`](../_data/title-templates.md#resolve-effective-record) states its fields. Steps 6 and 7 use the effective record, and step 9 records the consolidated record and the overrides apart.
61
+
62
+ If the call fails, stop and report its error: The title and the labels both depend on the effective record.
63
+
64
+ ### 6. Render PR title
65
+
66
+ Call `describe-change.mjs` to render the PR title from the configured `pr.title_format` template. Pass every input that is available, from the effective record; the template controls which tokens are required:
67
+
68
+ ```bash
69
+ node {harness_home_dir}/scripts/describe-change.mjs render-titles \
70
+ --title "{title}" \
71
+ --scope "{scope}" \
72
+ --type "{type}" \
73
+ --breaking \
74
+ --ticket-ref "{ticket_ref}" \
75
+ | python3 -c "import sys,json; print(json.load(sys.stdin).get('pr_title',''))"
76
+ ```
77
+
78
+ Omit any flag whose value is empty or null (e.g., omit `--ticket-ref` when `ticket_ref` from session context is `null`), and pass `--breaking` only if the effective record is breaking. Quote `--title` so that titles with spaces and shell-special characters are preserved. Render and parse in one Bash invocation, as the pipeline does, and let the parse print: A shell variable does not survive to a second call, and an assignment prints nothing for the next step to read.
79
+
80
+ Use a JSON parser (python3 above; `jq -r '.pr_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.
81
+
82
+ Read the rendered title from the command's output and use it directly as the final PR title. Do not concatenate with `title` separately; the rendered output already includes it.
83
+
84
+ If the script is not found, fall back to the bare `title` from the change summary.
85
+
86
+ See [title-templates.md](../_data/title-templates.md) for the title-format model and supported tokens.
87
+
88
+ ### 7. Resolve labels
89
+
90
+ Resolve the labels from the change summary's entries and from the effective record in step 5:
91
+
92
+ ```bash
93
+ node {harness_home_dir}/scripts/describe-change.mjs resolve-labels \
94
+ --body-file "{change_summary_path}" \
95
+ --scope "{scope}" \
96
+ --type "{type}" \
97
+ --breaking
98
+ ```
99
+
100
+ Pass the change summary written in step 3 as `--body-file`. Omit `--scope` and `--type` when the effective record's field is `null`, and pass `--breaking` only if the effective record is breaking. Read `labels` from the output; [`resolve-labels`](../_data/title-templates.md#resolve-labels) states what it contains. Relay any warning that the run writes to stderr.
101
+
102
+ If the call fails, relay its error and continue with labels = [].
103
+
104
+ ### 8. Detect platform and select delegate
105
+
106
+ Read `scm` from the session context manifest:
107
+
108
+ - `"github"` -> delegate to `{skill:create-gh-pr}`
109
+ - `"bitbucket"` -> delegate to `{skill?:create-bitbucket-pr}`
110
+ - Unknown or missing -> ask the user which platform to use.
111
+
112
+ ### 9. Insert the closing line above the record block
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.
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.
117
+
118
+ If `ticket_ref` is null, skip: no closing line.
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.
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.
123
+
124
+ ### 10. Call delegate
125
+
126
+ Pass the following inputs to the selected delegate per the delegate interface:
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, 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
+
138
+ ### 11. Persist the PR URL
139
+
140
+ The delegate reports the created PR's URL (its `PR created: {URL}` line). Persist it into the branch manifest so that PR-aware skills reuse it on later sessions (see [PR source resolution](../_data/pr-source-resolution.md#stored-pr-url)):
141
+
142
+ ```bash
143
+ node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs --set-pr-url "{URL}"
144
+ ```
145
+
146
+ ## Important
147
+
148
+ - The orchestrator makes all decisions (scope, type, title rendering, labels). Delegates only make the platform API calls.
149
+ - Strip the remote prefix from `default_branch` (e.g., `origin/main` -> `main`) before passing to the delegate.
150
+ - Never list automated checks (formatting, linting, typechecking, unit tests) in a test plan. They run automatically in CI.
@@ -0,0 +1,350 @@
1
+ ---
2
+ name: create-ticket
3
+ description: Create a ticket on the appropriate platform from conversation context
4
+ user-invocable: true
5
+ dependencies:
6
+ skills:
7
+ - testing-conventions
8
+ ---
9
+
10
+ # Create ticket
11
+
12
+ Create a ticket on the appropriate platform. The remote platform (e.g., GitHub) is the source of truth for the ticket number. Local artifacts are saved after the remote ticket exists, using the platform-assigned ID.
13
+
14
+ ## Arguments
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
+
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.
23
+
24
+ <!-- guidance-hook: ticketing-preferences -->
25
+
26
+ ## Process
27
+
28
+ ### 1. Resolve project metadata
29
+
30
+ Get `project_slug` and `artifact_base_dir` -- but NOT the new ticket's `ticket_id` (that comes from the platform in step 6).
31
+
32
+ - Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash to obtain `project_slug`, `artifact_base_dir`, and `ticket_base_url` from the manifest JSON emitted on stdout
33
+ - 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
+ - Read `project.ticket_ref_prefix` from `.agents/preferences.yaml` (e.g., `CODY-`); if absent, default to empty string
35
+
36
+ ### 2. Write ticket content
37
+
38
+ 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).
39
+
40
+ ```markdown
41
+ <!-- include: ../_partials/ticket-skeleton.md / -->
42
+ ```
43
+
44
+ **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
+
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 / -->
53
+
54
+ `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
+
56
+ <!-- include: ../_partials/ticket-criteria-conventions.md / -->
57
+
58
+ Also draft the ticket string, per [`title-voice.md`](../_data/title-voice.md), for use in step 6.
59
+
60
+ 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
+
62
+ <!-- include: ../../_partials/work-type-choice.md / -->
63
+
64
+ ### 3. Resolve platform
65
+
66
+ Determine where to create the remote ticket:
67
+
68
+ 1. **Preferences**: Check `.agents/preferences.yaml` → `integrations`:
69
+
70
+ - If exactly one integration is enabled → use it
71
+ - If multiple enabled → ask
72
+
73
+ 2. **Git remote**: if the preferences do not explicitly enable any integration:
74
+
75
+ - `git remote get-url origin` pointing to `github.com` → GitHub
76
+ - Other hosts → ask
77
+
78
+ 3. **Ask**: if platform cannot be determined
79
+
80
+ ### 4. Decide relationships
81
+
82
+ Three relationships are available, each stated from the new ticket's side:
83
+
84
+ - **parent**: The new ticket is a child of an existing ticket.
85
+ - **blocked-by**: The new ticket cannot proceed until the work of an existing ticket is merged.
86
+ - **blocking**: An existing ticket cannot proceed until the work of the new ticket is merged.
87
+
88
+ 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
+
90
+ **Most tickets have none, and for those, say nothing.** When nothing applies, continue to step 5 without asking.
91
+
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.
93
+
94
+ <!-- include: ../_partials/action-items.md / -->
95
+
96
+ ### 5. Resolve labels (GitHub only)
97
+
98
+ If the platform resolved in step 3 is GitHub, resolve the labels from the scope and type decided in step 2:
99
+
100
+ ```bash
101
+ node {harness_home_dir}/scripts/describe-change.mjs resolve-labels --scope "{scope}" --type "{type}"
102
+ ```
103
+
104
+ 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
+
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.
107
+
108
+ ### 6. Create remote ticket
109
+
110
+ The title and the branch association are the same for both platforms; only creation itself differs. Render the title, follow the path resolved in step 3, then finish at [Persist the branch association](#persist-the-branch-association).
111
+
112
+ #### Render the ticket title
113
+
114
+ Render with `describe-change.mjs`. Do **not** pass `--ticket-ref` when creating a ticket; the new ticket does not have a ref yet (that's what this step assigns).
115
+
116
+ ```bash
117
+ node {harness_home_dir}/scripts/describe-change.mjs render-titles --title "{title}" --scope "{scope}" --type "{type}" \
118
+ | python3 -c "import sys,json; print(json.load(sys.stdin).get('ticket_title',''))"
119
+ ```
120
+
121
+ 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
+
123
+ 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}`.
124
+
125
+ #### GitHub path
126
+
127
+ Write the body to a scratch file per [gh body file](#gh-body-file), naming it `gh-body-issue-{timestamp}.md`, since the issue does not have a number until this step returns one; do not inline the body into the shell command. Include `--label` flags if labels were resolved in step 5:
128
+
129
+ ```bash
130
+ body_path="{absolute path from the write step}"
131
+ [ -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}
133
+ ```
134
+
135
+ `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
+
137
+ Construct the ticket ID from `ticket_ref_prefix` (step 1) and `number`:
138
+
139
+ - If `ticket_ref_prefix` is `#`: `ticket_id` = `{number}`; the `#` is display-only and is added only when forming `ticket_ref` (step 8), e.g. `123` → `#123`
140
+ - If `ticket_ref_prefix` is any other value (e.g., `ABC-`): `ticket_id` = `{ticket_ref_prefix}{number}` (e.g., `ABC-` + `123` → `ABC-123`)
141
+ - If `ticket_ref_prefix` is empty: `ticket_id` = `{number}` (e.g., `123`)
142
+
143
+ #### Jira path
144
+
145
+ ##### Resolve the target
146
+
147
+ ```bash
148
+ node {harness_home_dir}/scripts/manage-jira-ticket.mjs resolve-target --work-type {type}
149
+ ```
150
+
151
+ `{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`.
152
+
153
+ 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.
154
+
155
+ ##### Create the work item
156
+
157
+ 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
+
159
+ - **`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
+ - **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
+ - **`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:
162
+
163
+ ```bash
164
+ node {harness_home_dir}/scripts/manage-jira-ticket.mjs create --summary "{ticket_title}" --body-file {absolute body path} --work-type {type} {parent_flag}
165
+ ```
166
+
167
+ `{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
+
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.
170
+
171
+ On a non-zero exit, read what it printed:
172
+ - `{"fallback": ...}`: As under [Resolve the target](#resolve-the-target), and `acli` was not called.
173
+ - `"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
+ - Nothing: An argument or the body file was rejected before any `acli` call, as stderr states. Fix it and run the helper again.
175
+
176
+ ##### Record the identifiers
177
+
178
+ `ticket_id` is the returned key verbatim (e.g. `ABC-123`). The key already includes its project prefix, so the `ticket_ref_prefix` reconstruction performed by the GitHub path does not apply here.
179
+
180
+ `url` is the URL returned by the client. If the client returns none, join `ticket_base_url` (step 1) to the key. If neither yields one, the work item still exists: Report it created by key without a URL, and skip the persist below.
181
+
182
+ #### Persist the branch association
183
+
184
+ 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
+
186
+ - 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:
187
+
188
+ ```bash
189
+ node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs --set-ticket-url "{url}"
190
+ ```
191
+
192
+ - When the branch is the default branch, the new ticket is a backlog ticket by construction: That branch is not derived from any ticket, so it does not have an association to record. Skip the persist and report it, e.g. `Ticket {ticket_id} created on default branch {branch_name}; skipped branch-manifest association.`
193
+
194
+ - Otherwise the new ticket is a backlog/follow-up ticket created from an unrelated branch. Skip the persist so that it does not overwrite the branch → ticket link, and report the skip in the completion output, e.g. `Backlog ticket {ticket_id} created while on a branch linked to ticket {branch_ticket_id}; skipped branch-manifest association.`
195
+
196
+ 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
+
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.
199
+
200
+ Skip this section entirely when step 6 did not resolve a URL; there is nothing to store.
201
+
202
+ ### 7. Apply relationships
203
+
204
+ Skip this step when step 4 decided none.
205
+
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.
207
+
208
+ 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
+
210
+ #### GitHub path
211
+
212
+ One call applies every relationship decided:
213
+
214
+ ```bash
215
+ gh issue edit {number} --parent "{parent}" --add-blocked-by "{blocked_by}" --add-blocking "{blocking}"
216
+ ```
217
+
218
+ 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
+
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.
221
+
222
+ #### Jira path
223
+
224
+ **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.
225
+
226
+ `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`.
227
+
228
+ **blocked-by and blocking.** Both are Jira links, and the client that creates them is ranked as step 6 ranks the creation clients: a connected issue-link tool when one is available, `acli` next, a reported skip only when neither is. The link client need not be the one that created the work item, because a link call does not include a description and the creation client's format contract does not apply to it.
229
+
230
+ Through a connected tool, use the link type named `Blocks`, falling back to a type whose outward description reads `blocks` when the site does not define a type of that name; `getIssueLinkTypes` lists them. Place the blocker in `inwardIssue` and the blocked work item in `outwardIssue`, the mapping stated by the tool's own argument documentation and confirmed by a live call.
231
+
232
+ 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
+
234
+ Through `acli`:
235
+
236
+ ```bash
237
+ acli jira workitem link create --out "{blocker}" --in "{blocked}" --type Blocks --yes
238
+ ```
239
+
240
+ 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.
241
+
242
+ If the available clients do not offer a link surface, report each link as skipped, naming the client.
243
+
244
+ #### Other platforms
245
+
246
+ Use whatever the platform's own tooling offers for parent and blocking relationships.
247
+
248
+ #### When a relationship cannot be established
249
+
250
+ A relationship that the platform cannot express, and a call that fails, are each recorded and skipped. Never abort the run over one: The ticket already exists by this point, and losing the link does less harm than losing the ticket. Include every skipped relationship and its reason in the completion output; that report makes a platform's missing relationship surface visible.
251
+
252
+ ### 8. Save local artifacts
253
+
254
+ Compute `ticket_ref` for the heading from `ticket_id` and `ticket_ref_prefix` (both already in scope from step 1) using the same logic applied by the bundled deriver:
255
+
256
+ - If `ticket_ref_prefix == '#'`: `ticket_ref = '#' + ticket_id`
257
+ - Otherwise: `ticket_ref = ticket_id`
258
+
259
+ Ticket directory: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
260
+
261
+ `mkdir -p` the target directory before writing.
262
+
263
+ Save the ticket as a ticket-level artifact:
264
+
265
+ ```
266
+ {YYYYMMDD-HHMMSSZ}_{slug}_ticket.md
267
+ ```
268
+
269
+ The artifact begins with YAML frontmatter conforming to the [universal artifact frontmatter](../_data/artifact-conventions.md#universal-artifact-frontmatter) schema. Resolve fields per [Frontmatter resolution](#frontmatter-resolution) below. The body heading should include the ticket reference: `# {ticket_ref}: {title}`. On a GitHub-style project (`ticket_ref_prefix: '#'`) with issue number `461`, this renders as `# #461: {title}`.
270
+
271
+ Example: `20260226-213000Z_role-type-architecture_ticket.md`
272
+
273
+ If a plan is also saved in step 9, it uses the same frontmatter shape with `provenance.skill: create-ticket`.
274
+
275
+ ### Frontmatter resolution
276
+
277
+ The artifact's frontmatter conforms to the [universal artifact frontmatter](../_data/artifact-conventions.md#universal-artifact-frontmatter) schema.
278
+
279
+ Source `{model_id}` from your system-prompt environment block: the line `model named ... model ID is ...`.
280
+
281
+ Run `{harness_home_dir}/scripts/resolve-frontmatter.sh --skill create-ticket --interactive true --model "{model_id}" --override ticket_id="{ticket_id}" --override ticket_ref="{ticket_ref}"` via Bash, substituting the just-created ticket's `ticket_id` (step 6) and `ticket_ref` (computed above). Prepend the output verbatim to the artifact body.
282
+
283
+ The `--override` flags force the frontmatter to the new ticket's own `ticket_id`/`ticket_ref` (the same values that its directory and `# {ticket_ref}:` heading use). Without them, `resolve-frontmatter.sh` resolves these from the current branch's manifest, so a ticket created from an unrelated branch would take the branch's id instead of its own. `branch` is left un-overridden so that it stays as authoring provenance. This applies to both the ticket artifact (step 8) and the plan artifact (step 9).
284
+
285
+ Append `--extra copies_remote=true` to the ticket artifact's invocation, and to that one alone, when step 6 created a remote ticket. It records that the saved body is a copy of the ticket of record; see [ticket frontmatter](../_data/artifact-conventions.md#ticket-frontmatter). Omit it on the [no-remote fallback](#fallback-no-remote-platform) alone, which saves a snapshot without a ticket of record to copy.
286
+
287
+ ### 9. Save plan (if present)
288
+
289
+ If a plan exists in conversation context, save it as a ticket-scoped artifact in the same directory:
290
+
291
+ ```
292
+ {YYYYMMDD-HHMMSSZ}_{slug}_plan.md
293
+ ```
294
+
295
+ Then attach it as a comment on the remote ticket, through the platform resolved in step 3.
296
+
297
+ **GitHub.** Write the comment body to a scratch file per [gh body file](#gh-body-file), naming it `gh-body-issue{number}-{timestamp}.md`; do not inline the comment into the shell command:
298
+
299
+ ```bash
300
+ body_path="{absolute path from the write step}"
301
+ [ -s "$body_path" ] || { echo "Body file missing or empty: $body_path" >&2; exit 1; }
302
+ gh issue comment {number} --body-file "$body_path"
303
+ ```
304
+
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.
306
+
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.
308
+
309
+ ```bash
310
+ adf_path="{absolute path from the write step}"
311
+ [ -s "$adf_path" ] || { echo "Comment file missing or empty: $adf_path" >&2; exit 1; }
312
+ acli jira workitem comment create --key "{ticket_id}" --body-file "$adf_path"
313
+ ```
314
+
315
+ **Neither.** When the client does not offer a comment surface, or the [no-remote fallback](#fallback-no-remote-platform) left nothing to comment on, the plan is saved locally alone. Report that in the completion output rather than passing over the attachment in silence.
316
+
317
+ Plan comment format:
318
+
319
+ ```markdown
320
+ **Implementation notes** (from planning session, {YYYY-MM-DD})
321
+
322
+ _These notes capture initial exploration and a proposed approach.
323
+ The implementer should verify assumptions and adapt as needed._
324
+
325
+ {plan content}
326
+
327
+ ---
328
+
329
+ Plan artifact: `{saved plan path}`
330
+ ```
331
+
332
+ ### Fallback: No remote platform
333
+
334
+ If remote ticket creation fails or a remote platform is not available, fall back to an auto-generated ticket ID: `{YYYYMMDD}-{4 random hex}` (e.g., `20260226-a3f2`). Save local artifacts using this ID. Log a warning that the remote ticket was not created, and report every relationship that step 4 decided as skipped per step 7.
335
+
336
+ ## Completion
337
+
338
+ ```
339
+ Remote ticket created: {URL} <- only if remote creation succeeded; {ticket_id} when no URL resolved
340
+ Ticket saved: {ticket artifact path}
341
+ Plan saved: {plan artifact path} <- only if plan existed
342
+ Plan comment skipped: {reason} <- only if a plan was saved but not attached
343
+ Relationships: {list} <- only if any were created
344
+ Relationships skipped: {list with reasons} <- only if any were skipped
345
+ Branch association skipped: {reason} <- only when the step-6 guard skipped the persist
346
+ ```
347
+
348
+ Nothing else.
349
+
350
+ <!-- include: ../_partials/gh-body-file.md / -->