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