codeassembly-guidance 0.1.0 → 0.2.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 +757 -0
- package/CHANGELOG.md +181 -0
- package/README.md +125 -95
- package/bin/codeassembly-validate-preferences.js +18 -0
- package/content/_partials/README.md +2 -2
- package/content/_partials/code-style.md +1 -1
- package/content/_partials/comment-discipline.md +1 -1
- package/content/_partials/plain-speech-calibration.md +4 -0
- package/content/_partials/technical-recommendations.md +1 -0
- package/content/codeassembly-content.yaml +11 -1
- package/content/collections/all.md +2 -2
- package/content/collections/atlassian.md +2 -1
- package/content/collections/recommended.md +9 -2
- package/content/collections/triage.md +3 -67
- package/content/collections/williamthorsen.md +2 -1
- package/content/guidance/README.md +1 -1
- package/content/guidance/rulebooks/accessibility-conventions.md +23 -5
- package/content/guidance/rulebooks/cli-conventions.md +192 -0
- package/content/guidance/rulebooks/codeassembly-content-specification.md +32 -9
- package/content/guidance/rulebooks/commit-conventions.md +2 -2
- package/content/guidance/rulebooks/live-worktree-policy.md +3 -2
- package/content/guidance/rulebooks/readme-conventions.md +3 -3
- package/content/guidance/rulebooks/shared-data-conventions.md +2 -2
- package/content/guidance/rulebooks/shell-conventions.md +17 -23
- package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +14 -12
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -3
- package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +6 -6
- package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +1 -1
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +7 -7
- package/content/guidance/shared/AGENTS.md +8 -0
- package/content/scripts/README.md +5 -2
- package/content/scripts/check-branch-currency.mjs +11 -0
- package/content/scripts/check-prose.mjs +171 -0
- package/content/scripts/describe-change.mjs +97 -97
- package/content/scripts/manage-jira-ticket.mjs +99 -94
- package/content/scripts/resolve-frontmatter.sh +1 -1
- package/content/scripts/resolve-review-run.mjs +9 -9
- package/content/scripts/select-lede-exemplars.mjs +87 -87
- package/content/scripts/validate-preferences.mjs +146 -0
- package/content/skills/_data/artifact-conventions.md +46 -14
- package/content/skills/_data/branch-currency.md +36 -0
- package/content/skills/_data/change-record.md +2 -2
- package/content/skills/_data/design-priorities.md +3 -3
- package/content/skills/_data/project-stage.md +32 -0
- package/content/skills/_data/recommendation-gradient.md +9 -7
- package/content/skills/_data/scope-and-deferral.md +1 -1
- package/content/skills/_data/spike-conventions.md +1 -1
- package/content/skills/_data/ticket-evaluation.md +2 -2
- package/content/skills/_data/ticket-source-resolution.md +36 -3
- package/content/skills/_data/title-templates.md +19 -11
- package/content/skills/_partials/action-items.md +2 -2
- package/content/skills/_partials/commit-title-rendering.md +1 -1
- package/content/skills/_partials/jira-task-list-flattening.md +1 -0
- package/content/skills/_partials/next-steps-after-plan.md +10 -10
- package/content/skills/_partials/next-steps-after-review.md +9 -9
- package/content/skills/_partials/option-format.md +18 -17
- package/content/skills/_partials/plan-template.md +5 -5
- package/content/skills/_partials/split-ticket-compose.md +1 -1
- package/content/skills/_partials/split-ticket-create.md +1 -1
- package/content/skills/_partials/ticket-and-plan-completeness.md +2 -2
- package/content/skills/_partials/ticket-criteria-conventions.md +3 -3
- package/content/skills/add-change-record/SKILL.md +2 -2
- package/content/skills/align-ticket-with-implementation/SKILL.md +2 -2
- package/content/skills/anti-patterns/SKILL.md +1 -1
- package/content/skills/assess-usability/SKILL.md +96 -0
- package/content/skills/capture-event/SKILL.md +2 -2
- package/content/skills/capture-event/capture-event.mjs +89 -89
- package/content/skills/capture-lede-decision/SKILL.md +4 -4
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +98 -98
- package/content/skills/collaborate/SKILL.md +1 -1
- package/content/skills/create-gh-pr/SKILL.md +24 -9
- package/content/skills/create-pr/SKILL.md +5 -5
- package/content/skills/create-ticket/SKILL.md +61 -16
- package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +95 -94
- package/content/skills/design-and-plan/SKILL.md +13 -10
- package/content/skills/groom-backlog/SKILL.md +8 -6
- package/content/skills/groom-backlog/groom-backlog.mjs +64 -62
- package/content/skills/implement-plan/SKILL.md +25 -21
- package/content/skills/index-prototypes/SKILL.md +85 -30
- package/content/skills/index-prototypes/index-prototypes.mjs +76 -16
- package/content/skills/kb-add/SKILL.md +2 -1
- package/content/skills/kb-add/kb-add.mjs +128 -128
- package/content/skills/kb-curate/SKILL.md +9 -7
- package/content/skills/kb-curate/kb-curate.mjs +103 -103
- package/content/skills/kb-edit/SKILL.md +3 -3
- package/content/skills/kb-edit/kb-edit.mjs +94 -94
- package/content/skills/kb-retrieve/kb-retrieve.mjs +78 -77
- package/content/skills/kb-retrieve-events/SKILL.md +1 -1
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +78 -77
- package/content/skills/kb-update-events/SKILL.md +2 -2
- package/content/skills/kb-update-events/kb-update-events.mjs +108 -108
- package/content/skills/merge-bb-pr/SKILL.md +1 -1
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +5 -5
- package/content/skills/merge-pr/SKILL.md +11 -11
- package/content/skills/migrate-feedback-memories/SKILL.md +3 -2
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +76 -76
- package/content/skills/plan/SKILL.md +1 -1
- package/content/skills/prepare-prototype-brief/SKILL.md +66 -14
- package/content/skills/pull-from-backlog/SKILL.md +3 -3
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +83 -82
- package/content/skills/refine-plan/SKILL.md +7 -3
- package/content/skills/refine-prototype/SKILL.md +113 -0
- package/content/skills/respond-to-review/SKILL.md +1 -1
- package/content/skills/review-bb-pr/SKILL.md +1 -1
- package/content/skills/review-branch/SKILL.md +4 -2
- package/content/skills/review-criteria/SKILL.md +36 -3
- package/content/skills/review-gh-pr/select-pr-ticket.mjs +6 -6
- package/content/skills/revise-comments/SKILL.md +38 -5
- package/content/skills/revise-prose/SKILL.md +1 -1
- package/content/skills/revise-prose/revise-prose.mjs +119 -119
- package/content/skills/save-artifact/SKILL.md +2 -0
- package/content/skills/streamline-guidance/SKILL.md +1 -1
- package/content/skills/streamline-guidance/streamline-guidance.mjs +86 -86
- package/content/skills/summarize-change/SKILL.md +22 -13
- package/content/skills/testing-conventions/SKILL.md +74 -7
- package/content/skills/triage-spike-findings/SKILL.md +113 -0
- package/content/skills/triage-spike-findings/triage-spike-findings.mjs +71 -0
- package/content/skills/typescript-testing-conventions/SKILL.md +50 -1
- package/content/skills/update-jira-ticket/SKILL.md +20 -8
- package/content/skills/update-jira-ticket/update-jira-ticket.mjs +7 -7
- package/content/skills/update-project-guidance/SKILL.md +2 -2
- package/content/subagents/_data/claude.yaml +6 -0
- package/content/subagents/_data/rovo.yaml +12 -2
- package/content/subagents/canary.md +2 -1
- package/content/subagents/disposition-challenger.md +78 -0
- package/content/subagents/entry-drafter.md +14 -10
- package/content/subagents/handoff-reviewer.md +2 -2
- package/content/subagents/plan-reviewer.md +1 -1
- package/content/subagents/prose-reviser.md +4 -2
- package/content/subagents/ticket-assessor.md +9 -6
- package/content/subagents/usability-assessor.md +157 -0
- package/package.json +15 -11
- package/schemas/preferences.v1.json +29 -2
- package/schemas/work-types.v1.json +1 -1
- package/content/skills/testing-conventions/mistakes.md +0 -1
|
@@ -17,7 +17,7 @@ This skill is invoked by a directive in the harness's global guidance during int
|
|
|
17
17
|
- Don't let refactoring grow beyond the task; recommend the scope call, build on it, and raise it at the checkpoint.
|
|
18
18
|
- Ask for guidance on naming and approach when the choice turns on the developer's preference; when a convention or the merits already settle it, state the decision with its reason and proceed.
|
|
19
19
|
- Proceed provisionally: Decide what the gate lets you decide, record it, and collect the surviving asks into one review at the checkpoint.
|
|
20
|
-
- Do every step yourself, verification included; the `## Handoffs` section of the collaboration preferences states when
|
|
20
|
+
- Do every step yourself, verification included; the `## Handoffs` section of the collaboration preferences states when you may hand a step over.
|
|
21
21
|
- When instructions have undiscussed implications, and you see flaws or meaningful improvements, raise them before proceeding.
|
|
22
22
|
|
|
23
23
|
## Concision by default
|
|
@@ -42,23 +42,36 @@ gh pr create \
|
|
|
42
42
|
--body-file "$body_path" \
|
|
43
43
|
--base "{base_branch}" \
|
|
44
44
|
--draft \
|
|
45
|
+
--assignee "@me" \
|
|
45
46
|
{label_flags}
|
|
46
47
|
```
|
|
47
48
|
|
|
48
|
-
|
|
49
|
+
`--assignee "@me"` assigns the pull request to the authenticated `gh` user, who is the developer creating it.
|
|
49
50
|
|
|
50
|
-
|
|
51
|
+
`gh pr create` prints the pull-request URL. Read it from the command's output and include it in step 5's artifact and the completion line; never capture it into a shell variable.
|
|
51
52
|
|
|
52
|
-
|
|
53
|
+
### 3. Handle label and assignee failures
|
|
53
54
|
|
|
54
|
-
|
|
55
|
-
2. Remove the failing labels from the `--label` flags.
|
|
56
|
-
3. Retry `gh pr create` without the failing labels, re-stating the assignment and the guard for the same scratch file; do not rewrite the body or inline it.
|
|
57
|
-
4. Record which labels were skipped.
|
|
55
|
+
If `gh pr create` fails and the error indicates that one or more labels are invalid, or that the assignee cannot be assigned:
|
|
58
56
|
|
|
59
|
-
|
|
57
|
+
1. Identify the failing labels, the assignee, or both from the error message.
|
|
58
|
+
2. Remove the failing `--label` flags, and remove `--assignee` if the assignee failed.
|
|
59
|
+
3. Retry `gh pr create` once without them, re-stating the `body_path` assignment and the guard for the same scratch file; do not rewrite the body or inline it.
|
|
60
|
+
4. Record which labels were skipped, and whether the assignee was skipped, with the reason from the error.
|
|
60
61
|
|
|
61
|
-
|
|
62
|
+
If the failure is unrelated to labels and the assignee, report the error and stop.
|
|
63
|
+
|
|
64
|
+
### 4. Read back the assignee
|
|
65
|
+
|
|
66
|
+
`gh` can create the pull request without applying an assignee that it cannot assign, so read the applied assignee from the created pull request rather than assuming it:
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
gh pr view {PR URL} --json assignees --jq '[.assignees[].login] | join(", ")'
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
An empty result means that the pull request has no assignee: Record the assignee as skipped, with the reason "not applied by GitHub" unless step 3 already recorded one.
|
|
73
|
+
|
|
74
|
+
### 5. Save PR artifact
|
|
62
75
|
|
|
63
76
|
Save a `pull-request` artifact in the ticket directory.
|
|
64
77
|
|
|
@@ -86,6 +99,7 @@ Created: {YYYY-MM-DD HH:MMZ}
|
|
|
86
99
|
Labels attempted: {comma-separated list, or "none"}
|
|
87
100
|
Labels applied: {comma-separated list, or "none"}
|
|
88
101
|
Labels skipped: {comma-separated list, or "none"}
|
|
102
|
+
Assignee: {login read back in step 4, or "none"}
|
|
89
103
|
|
|
90
104
|
## Body
|
|
91
105
|
|
|
@@ -98,6 +112,7 @@ Labels skipped: {comma-separated list, or "none"}
|
|
|
98
112
|
PR created: {URL}
|
|
99
113
|
Labels applied: {list} <- only if labels were requested
|
|
100
114
|
Labels skipped: {list} <- only if any labels failed
|
|
115
|
+
Assignee skipped: {reason} <- only if the pull request has no assignee
|
|
101
116
|
Artifact saved: {artifact path}
|
|
102
117
|
```
|
|
103
118
|
|
|
@@ -8,7 +8,7 @@ user-invocable: true
|
|
|
8
8
|
|
|
9
9
|
Create a pull request on the appropriate platform. This is the user-facing entry point that orchestrates the full PR creation flow, delegating platform-specific API calls to internal skills (`create-gh-pr`, `create-bitbucket-pr`).
|
|
10
10
|
|
|
11
|
-
The pull request
|
|
11
|
+
The pull request contains the change's entries and overrides in the `change-record` block that the change summary's body ends with, as [the change record](../_data/change-record.md) states them.
|
|
12
12
|
|
|
13
13
|
## Optional arguments
|
|
14
14
|
|
|
@@ -111,15 +111,15 @@ Read `scm` from the session context manifest:
|
|
|
111
111
|
|
|
112
112
|
### 9. Insert the closing line above the record block
|
|
113
113
|
|
|
114
|
-
The body copied from the change summary already ends with the rendered `change-record` block, which `summarize-change` writes from the change entries.
|
|
114
|
+
The body copied from the change summary already ends with the rendered `change-record` block, which `summarize-change` writes from the change entries. Keep it unchanged: Do not render a block here, and never re-render one from the frontmatter, which does not record any entries.
|
|
115
115
|
|
|
116
|
-
If `ticket_ref` is non-null, insert `Closes {ticket_ref}` above that block, separated from the text before it and from the block by one blank line each. The `Closes` keyword auto-closes the linked ticket when the PR merges (GitHub for numeric same-repo refs; Jira/Linear for prefixed IDs when their respective integrations are configured). Even when an auto-close integration is not
|
|
116
|
+
If `ticket_ref` is non-null, insert `Closes {ticket_ref}` above that block, separated from the text before it and from the block by one blank line each. The `Closes` keyword auto-closes the linked ticket when the PR merges (GitHub for numeric same-repo refs; Jira/Linear for prefixed IDs when their respective integrations are configured). Even when an auto-close integration is not configured, the line documents the linkage and gives reviewers a clickable cross-reference.
|
|
117
117
|
|
|
118
118
|
If `ticket_ref` is null, skip: no closing line.
|
|
119
119
|
|
|
120
|
-
The closing line goes above the block rather than below it because the block is the body's last element, as [The `change-record` block](../_data/change-record.md#the-change-record-block) states. A merge reads the last `change-record` fence wherever it
|
|
120
|
+
The closing line goes above the block rather than below it because the block is the body's last element, as [The `change-record` block](../_data/change-record.md#the-change-record-block) states. A merge reads the last `change-record` fence wherever it is in the body, so keeping this order does not affect the merge, and the convention stays true.
|
|
121
121
|
|
|
122
|
-
If the change summary's body does not end with a block, append the closing line as the body's last line and say that the pull request does not contain a change record, naming `{skill:add-change-record}` as the skill that adds one.
|
|
122
|
+
If the change summary's body does not end with a block, append the closing line as the body's last line and say that the pull request does not contain a change record, naming `{skill:add-change-record}` as the skill that adds one. The change summary's body does not end with a block when `summarize-change` reported that `render-block` was unavailable or failed.
|
|
123
123
|
|
|
124
124
|
### 10. Call delegate
|
|
125
125
|
|
|
@@ -18,8 +18,24 @@ Create a ticket on the appropriate platform. The remote platform (e.g., GitHub)
|
|
|
18
18
|
| `--parent <ref>` | Make the new ticket a child of the referenced ticket. One reference; a ticket has one parent. |
|
|
19
19
|
| `--blocked-by <refs>` | Mark the new ticket as blocked by the referenced tickets. |
|
|
20
20
|
| `--blocking <refs>` | Mark the new ticket as blocking the referenced tickets. |
|
|
21
|
+
| `--label <labels>` | Apply these labels with the ones that step 5 resolves. GitHub only. |
|
|
22
|
+
| `--repo <OWNER/REPO>` | File the ticket in this GitHub repository. See [Another repository](#another-repository). |
|
|
21
23
|
|
|
22
|
-
|
|
24
|
+
The three relationship arguments take ticket references in the project's own form (`#123`, `ABC-123`), comma-separated when more than one applies. Each is optional, and each overrides the inference in step 4 for its own relationship. `--label` takes label names, comma-separated, exactly as the repository spells them.
|
|
25
|
+
|
|
26
|
+
### Another repository
|
|
27
|
+
|
|
28
|
+
`--repo` files the ticket in another GitHub repository, and every step resolves against that repository rather than the session's: its configuration, its issues, and its artifact directory. Compare the value with `gh repo view --json nameWithOwner --jq .nameWithOwner`, ignoring case; when the two name the same repository, drop `--repo` and run as though it were absent. When the command fails, as it does in a session whose repository is not on GitHub, the two are different repositories.
|
|
29
|
+
|
|
30
|
+
Otherwise, resolve the target before step 1:
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
node {harness_home_dir}/skills/create-ticket/resolve-ticket-target.mjs --repo {OWNER/REPO}
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
It prints `{"repo": "...", "projectRoot": "...", "projectSlug": "...", "ticketRefPrefix": "...", "missing": [...]}`. `repo` is the canonical `OWNER/REPO`, used as `{target_repo}` below. `projectRoot` is a directory that contains the target's `.meta/label-map.json` and `.agents/preferences.yaml` as they appear on its default branch; `missing` names each that it does not contain, and the completion output reports each. On a non-zero exit, nothing has been created: Report the helper's stderr and stop.
|
|
37
|
+
|
|
38
|
+
The steps below state what changes for a target repository. A step that does not mention it runs unchanged.
|
|
23
39
|
|
|
24
40
|
<!-- guidance-hook: ticketing-preferences -->
|
|
25
41
|
|
|
@@ -33,6 +49,8 @@ Get `project_slug` and `artifact_base_dir` -- but NOT the new ticket's `ticket_i
|
|
|
33
49
|
- From the same manifest JSON, also read `ticket_id` as `branch_ticket_id`, the ticket from which the current branch is derived (empty when the branch name does not encode a ticket). The step-4 inference and the step-6 guard both read it; the new ticket's authoritative `ticket_id` still comes from the platform in step 6. Read `branch_name` and `default_branch` too, which the step-6 guard compares.
|
|
34
50
|
- Read `project.ticket_ref_prefix` from `.agents/preferences.yaml` (e.g., `CODY-`); if absent, default to empty string
|
|
35
51
|
|
|
52
|
+
For a [target repository](#another-repository), take `project_slug` from the helper's `projectSlug` and `ticket_ref_prefix` from its `ticketRefPrefix` instead. `artifact_base_dir` stays the session's.
|
|
53
|
+
|
|
36
54
|
### 2. Write ticket content
|
|
37
55
|
|
|
38
56
|
Create the ticket body describing WHAT needs to be done: problem, context, and acceptance criteria. Do NOT include the plan inline. Do NOT include the ticket ID in the heading yet (it's not known until step 6).
|
|
@@ -61,8 +79,12 @@ Then decide the ticket's scope and type, for use in steps 5 and 6. The type is t
|
|
|
61
79
|
|
|
62
80
|
<!-- include: ../../_partials/work-type-choice.md / -->
|
|
63
81
|
|
|
82
|
+
For a [target repository](#another-repository), the scope is a key of the `scopes` section in `{projectRoot}/.meta/label-map.json`, or `*` when the target does not have a label map.
|
|
83
|
+
|
|
64
84
|
### 3. Resolve platform
|
|
65
85
|
|
|
86
|
+
For a [target repository](#another-repository), the platform is GitHub: Skip this step.
|
|
87
|
+
|
|
66
88
|
Determine where to create the remote ticket:
|
|
67
89
|
|
|
68
90
|
1. **Preferences**: Check `.agents/preferences.yaml` → `integrations`:
|
|
@@ -70,12 +92,12 @@ Determine where to create the remote ticket:
|
|
|
70
92
|
- If exactly one integration is enabled → use it
|
|
71
93
|
- If multiple enabled → ask
|
|
72
94
|
|
|
73
|
-
2. **Git remote**:
|
|
95
|
+
2. **Git remote**: If the preferences do not explicitly enable any integration:
|
|
74
96
|
|
|
75
97
|
- `git remote get-url origin` pointing to `github.com` → GitHub
|
|
76
98
|
- Other hosts → ask
|
|
77
99
|
|
|
78
|
-
3. **Ask**:
|
|
100
|
+
3. **Ask**: If platform cannot be determined
|
|
79
101
|
|
|
80
102
|
### 4. Decide relationships
|
|
81
103
|
|
|
@@ -87,9 +109,11 @@ Three relationships are available, each stated from the new ticket's side:
|
|
|
87
109
|
|
|
88
110
|
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
111
|
|
|
112
|
+
For a [target repository](#another-repository), do not infer any relationship from `branch_ticket_id`, which identifies a ticket in the session's repository; apply only those that the arguments state. A reference resolves in the target, so pass a ticket in any other repository as its URL.
|
|
113
|
+
|
|
90
114
|
**Most tickets have none, and for those, say nothing.** When nothing applies, continue to step 5 without asking.
|
|
91
115
|
|
|
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
|
|
116
|
+
When one or more apply, state each relationship and its target in the project's own reference form and confirm before anything is created, so that a wrong target is visible while it is still free to correct. A relationship supplied through an argument is one that the caller has already confirmed: State it in the completion output and do not ask about it; the confirmation covers the inferred relationships alone. If the platform resolved in step 3 cannot express one of them, say so here rather than reporting it as a skip in step 7.
|
|
93
117
|
|
|
94
118
|
<!-- include: ../_partials/action-items.md / -->
|
|
95
119
|
|
|
@@ -101,9 +125,13 @@ If the platform resolved in step 3 is GitHub, resolve the labels from the scope
|
|
|
101
125
|
node {harness_home_dir}/scripts/describe-change.mjs resolve-labels --scope "{scope}" --type "{type}"
|
|
102
126
|
```
|
|
103
127
|
|
|
128
|
+
For a [target repository](#another-repository), add `--project-root "{projectRoot}"`, so that the labels come from the target's label map.
|
|
129
|
+
|
|
104
130
|
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
131
|
|
|
106
|
-
|
|
132
|
+
Append the labels given through `--label` to the returned list; they add to the resolved scope and type labels and never replace them. `gh issue create` fails on a label that the repository does not have, so the caller of `--label` checks that each label exists before invoking this skill. On the Jira path, `--label` is not applied: Report it skipped in the completion output.
|
|
133
|
+
|
|
134
|
+
Render one `--label "{label_name}"` flag per label in the combined list, and write them into the create call in step 6 as literal text. Because a shell variable does not survive the Bash invocation that assigns it, a call that reads one from an earlier call does not apply any labels at all.
|
|
107
135
|
|
|
108
136
|
### 6. Create remote ticket
|
|
109
137
|
|
|
@@ -118,6 +146,8 @@ node {harness_home_dir}/scripts/describe-change.mjs render-titles --title "{titl
|
|
|
118
146
|
| python3 -c "import sys,json; print(json.load(sys.stdin).get('ticket_title',''))"
|
|
119
147
|
```
|
|
120
148
|
|
|
149
|
+
For a [target repository](#another-repository), add `--project-root "{projectRoot}"`, so that the title follows the target's `ticket.title_format`.
|
|
150
|
+
|
|
121
151
|
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
152
|
|
|
123
153
|
The pipeline prints the rendered title. Read it from the command's output and write it into the create call below as literal text, as the GitHub issue title or the Jira summary; it already includes any prefix (per the configured `ticket.title_format`) and the bare title text. Assigning the parse instead prints nothing, and a shell variable does not survive to the create call, so a call that reads `$ticket_title` submits an empty title. If the script is not found, fall back to the bare `{title}`.
|
|
@@ -129,9 +159,11 @@ Write the body to a scratch file per [gh body file](#gh-body-file), naming it `g
|
|
|
129
159
|
```bash
|
|
130
160
|
body_path="{absolute path from the write step}"
|
|
131
161
|
[ -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}
|
|
162
|
+
gh issue create --title "{ticket_title}" --body-file "$body_path" {label_flags} {repo_flag}
|
|
133
163
|
```
|
|
134
164
|
|
|
165
|
+
`{repo_flag}` is `--repo {target_repo}` for a [target repository](#another-repository), and empty otherwise; steps 7 and 9 pass it to `gh` the same way.
|
|
166
|
+
|
|
135
167
|
`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
168
|
|
|
137
169
|
Construct the ticket ID from `ticket_ref_prefix` (step 1) and `number`:
|
|
@@ -156,6 +188,8 @@ When the preferences do not name a project, the helper prints `{"fallback": "no-
|
|
|
156
188
|
|
|
157
189
|
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
190
|
|
|
191
|
+
<!-- include: ../_partials/jira-task-list-flattening.md / -->
|
|
192
|
+
|
|
159
193
|
- **`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
194
|
- **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
195
|
- **`acli`**: Write the step-2 body as Markdown to a scratch file per [gh body file](#gh-body-file), naming it `jira-body-{timestamp}.md`, and run the helper once:
|
|
@@ -166,10 +200,11 @@ Identify the client per {skill?:update-jira-ticket}, which ranks the three clien
|
|
|
166
200
|
|
|
167
201
|
`{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
202
|
|
|
169
|
-
|
|
203
|
+
When `ticket.base_url` is set, in the repository's preferences or the global file, the helper first compares `acli`'s active site with the base URL's host, because `acli` creates on whichever site it is signed in to. It then converts the body to ADF, checks a parent with `acli jira workitem view`, and runs `acli jira workitem create` exactly once. It prints `{"key": "ABC-123", "rawOutput": "...", "parentSkipped": false, "activeSite": "..."}`, in which `activeSite` is null when `ticket.base_url` is unset. `parentSkipped: true` means that Jira rejected the parent reference and the work item was created without it; report the parent skipped per step 7.
|
|
170
204
|
|
|
171
205
|
On a non-zero exit, read what it printed:
|
|
172
|
-
- `{"fallback":
|
|
206
|
+
- `{"fallback": "no-project-key"}`: As under [Resolve the target](#resolve-the-target), and `acli` was not called.
|
|
207
|
+
- `{"fallback": "wrong-site"}` or `{"fallback": "site-unreadable"}`: `acli` is signed in to another site, or its site could not be read, and nothing was created. Create through the next client that {skill?:update-jira-ticket} ranks, including a client that the machine adds. When none remains, take the [no-remote fallback](#fallback-no-remote-platform) with the helper's warning, which names both sites and the `acli jira auth switch` command. Never run that command, because the active site is shared by every session on the machine.
|
|
173
208
|
- `"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
209
|
- Nothing: An argument or the body file was rejected before any `acli` call, as stderr states. Fix it and run the helper again.
|
|
175
210
|
|
|
@@ -181,6 +216,8 @@ Identify the client per {skill?:update-jira-ticket}, which ranks the three clien
|
|
|
181
216
|
|
|
182
217
|
#### Persist the branch association
|
|
183
218
|
|
|
219
|
+
For a [target repository](#another-repository), skip this section and report the skip, e.g. `Ticket {target_repo}#{number} filed in another repository; skipped branch-manifest association.` The `ticket_id` comparison below would match a target issue whose number equals the branch's ticket ID.
|
|
220
|
+
|
|
184
221
|
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
222
|
|
|
186
223
|
- When the branch is not the default branch, and `branch_ticket_id` is either empty (the branch name does not encode a ticket) or equal to `ticket_id` (the branch is already linked to this ticket), persist:
|
|
@@ -195,7 +232,7 @@ Persist the new ticket's URL into the branch manifest so that later sessions reu
|
|
|
195
232
|
|
|
196
233
|
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
234
|
|
|
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
|
|
235
|
+
Compare `ticket_id` rather than a bare issue number. `branch_ticket_id` comes from the same deriver logic that the GitHub path's construction mirrors, so the two agree in form on every project: bare when `ticket_ref_prefix` is `#` or absent, prefixed when it is a project key. Comparing a bare number works only in the first case and silently skips every persist in the second.
|
|
199
236
|
|
|
200
237
|
Skip this section entirely when step 6 did not resolve a URL; there is nothing to store.
|
|
201
238
|
|
|
@@ -203,7 +240,7 @@ Skip this section entirely when step 6 did not resolve a URL; there is nothing t
|
|
|
203
240
|
|
|
204
241
|
Skip this step when step 4 decided none.
|
|
205
242
|
|
|
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.
|
|
243
|
+
When step 6 did not create a remote ticket (the [no-remote fallback](#fallback-no-remote-platform)), there is nothing to link. Skip every relationship that step 4 decided, each with that as its reason, and report them. Never drop a relationship confirmed by the user without a line in the completion output.
|
|
207
244
|
|
|
208
245
|
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
246
|
|
|
@@ -212,12 +249,12 @@ Otherwise apply relationships after the ticket exists rather than as part of cre
|
|
|
212
249
|
One call applies every relationship decided:
|
|
213
250
|
|
|
214
251
|
```bash
|
|
215
|
-
gh issue edit {number} --parent "{parent}" --add-blocked-by "{blocked_by}" --add-blocking "{blocking}"
|
|
252
|
+
gh issue edit {number} --parent "{parent}" --add-blocked-by "{blocked_by}" --add-blocking "{blocking}" {repo_flag}
|
|
216
253
|
```
|
|
217
254
|
|
|
218
255
|
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
256
|
|
|
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;
|
|
257
|
+
These flags are native to `gh` 2.94 and later. They are not the REST dependencies endpoint, which takes an issue's database `id` rather than its number; using that endpoint is the mistake that this note exists to prevent.
|
|
221
258
|
|
|
222
259
|
#### Jira path
|
|
223
260
|
|
|
@@ -231,7 +268,13 @@ Through a connected tool, use the link type named `Blocks`, falling back to a ty
|
|
|
231
268
|
|
|
232
269
|
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
270
|
|
|
234
|
-
|
|
271
|
+
After a create through `acli`, the work item is on the active site; link through `acli` without a further check. After a create through another client, first compare the active site with `ticket_base_url` (step 1) when it is set, and report each link skipped with the helper's stderr line when it exits non-zero:
|
|
272
|
+
|
|
273
|
+
```bash
|
|
274
|
+
node {harness_home_dir}/scripts/manage-jira-ticket.mjs check-site --target {ticket_base_url}
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
Then:
|
|
235
278
|
|
|
236
279
|
```bash
|
|
237
280
|
acli jira workitem link create --out "{blocker}" --in "{blocked}" --type Blocks --yes
|
|
@@ -299,12 +342,12 @@ Then attach it as a comment on the remote ticket, through the platform resolved
|
|
|
299
342
|
```bash
|
|
300
343
|
body_path="{absolute path from the write step}"
|
|
301
344
|
[ -s "$body_path" ] || { echo "Body file missing or empty: $body_path" >&2; exit 1; }
|
|
302
|
-
gh issue comment {number} --body-file "$body_path"
|
|
345
|
+
gh issue comment {number} --body-file "$body_path" {repo_flag}
|
|
303
346
|
```
|
|
304
347
|
|
|
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.
|
|
348
|
+
**Jira.** Comment through the client that created the work item, in the format assigned to that client by {skill?:update-jira-ticket}: a connected tool's own comment surface, or `acli` reading the comment as ADF from a scratch file. Flatten task lists for a connected tool as [Create the work item](#create-the-work-item) states.
|
|
306
349
|
|
|
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
|
|
350
|
+
The scratch file follows [gh body file](#gh-body-file), whose rules are about the path rather than the platform: `acli` reads a file the same way `gh` does, and a path passed between Bash invocations resolves to nothing either way.
|
|
308
351
|
|
|
309
352
|
```bash
|
|
310
353
|
adf_path="{absolute path from the write step}"
|
|
@@ -342,7 +385,9 @@ Plan saved: {plan artifact path} <- only if plan existed
|
|
|
342
385
|
Plan comment skipped: {reason} <- only if a plan was saved but not attached
|
|
343
386
|
Relationships: {list} <- only if any were created
|
|
344
387
|
Relationships skipped: {list with reasons} <- only if any were skipped
|
|
388
|
+
Labels skipped: {labels} <- only when `--label` was given on the Jira path
|
|
345
389
|
Branch association skipped: {reason} <- only when the step-6 guard skipped the persist
|
|
390
|
+
Target configuration missing: {files} <- only when the target's default branch lacks a file in `missing`
|
|
346
391
|
```
|
|
347
392
|
|
|
348
393
|
Nothing else.
|