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