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,92 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: classify-complexity
|
|
3
|
+
description: Classify a ticket's complexity against the current codebase using the 4-level rubric
|
|
4
|
+
user-invocable: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Classify complexity
|
|
8
|
+
|
|
9
|
+
Classify a ticket's complexity by examining the described work against the current codebase. Produces a structured assessment with a verdict, scope breakdown, drivers, and risks.
|
|
10
|
+
|
|
11
|
+
**Announce at start:** "Using classify-complexity to classify {ticket reference}."
|
|
12
|
+
|
|
13
|
+
## Arguments
|
|
14
|
+
|
|
15
|
+
- **Ticket source** (optional): Issue URL, shorthand reference (`#99`, `issue 99`), file path, or plain text. When omitted, auto-resolved from the environment (see [ticket source resolution](../_data/ticket-source-resolution.md#auto-resolve)).
|
|
16
|
+
|
|
17
|
+
## Process
|
|
18
|
+
|
|
19
|
+
### 1. Resolve ticket source
|
|
20
|
+
|
|
21
|
+
Resolve the ticket source using the [ticket source resolution](../_data/ticket-source-resolution.md) table. Store the resolved metadata (platform, repo, issue number, ticket content). When the source resolves to a URL, persist it to the branch manifest per [Stored ticket URL](../_data/ticket-source-resolution.md#stored-ticket-url) so that a later session does not need a ticket argument.
|
|
22
|
+
|
|
23
|
+
### 2. Identify the work surface
|
|
24
|
+
|
|
25
|
+
Extract from the ticket what needs to change:
|
|
26
|
+
|
|
27
|
+
- Files, modules, and packages mentioned or implied
|
|
28
|
+
- New files or directories that need to be created
|
|
29
|
+
- APIs, interfaces, or data structures that are added or modified
|
|
30
|
+
- Dependencies that are added, removed, or changed
|
|
31
|
+
|
|
32
|
+
Verify against the codebase; the ticket may reference things that have moved or no longer exist.
|
|
33
|
+
|
|
34
|
+
### 3. Assess cross-cutting extent
|
|
35
|
+
|
|
36
|
+
- How many modules or packages are touched?
|
|
37
|
+
- Do changes cross package boundaries?
|
|
38
|
+
- Are shared interfaces, types, or data structures affected?
|
|
39
|
+
- Are there downstream consumers that need updating?
|
|
40
|
+
|
|
41
|
+
### 4. Assess decision density
|
|
42
|
+
|
|
43
|
+
- Does the work follow an established pattern, or does it require new patterns?
|
|
44
|
+
- Are there design choices that could go multiple ways?
|
|
45
|
+
- Does the work introduce new abstractions, interfaces, or module boundaries?
|
|
46
|
+
|
|
47
|
+
### 5. Classify
|
|
48
|
+
|
|
49
|
+
Map the findings to the [complexity classification](../_data/complexity-classification.md) rubric. When characteristics span two levels, prefer the higher level.
|
|
50
|
+
|
|
51
|
+
### 6. Output
|
|
52
|
+
|
|
53
|
+
Obtain the base SHA via `git rev-parse --short HEAD`.
|
|
54
|
+
|
|
55
|
+
```markdown
|
|
56
|
+
## Complexity: {ticket title} (#{number})
|
|
57
|
+
|
|
58
|
+
Assessed at {YYYYMMDD-HHMMSSZ} against {short SHA}
|
|
59
|
+
|
|
60
|
+
🧩 **Complexity:** {emoji} `{label}`
|
|
61
|
+
|
|
62
|
+
### Scope
|
|
63
|
+
|
|
64
|
+
- **Modules affected:** {list of modules or packages touched}
|
|
65
|
+
- **New files:** {count and brief description, or "None"}
|
|
66
|
+
- **Modified files:** {count and brief description}
|
|
67
|
+
|
|
68
|
+
### Drivers
|
|
69
|
+
|
|
70
|
+
- {What places the classification at this level}
|
|
71
|
+
- {Key factor}
|
|
72
|
+
|
|
73
|
+
### Risks
|
|
74
|
+
|
|
75
|
+
- {Known unknowns or complications, or "None identified"}
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
## Verdict mapping
|
|
79
|
+
|
|
80
|
+
| Level | Label | Emoji |
|
|
81
|
+
| ----- | --------------- | ----- |
|
|
82
|
+
| 1 | `trivial` | ⚪ |
|
|
83
|
+
| 2 | `mechanical` | 🟢 |
|
|
84
|
+
| 3 | `involved` | 🟠 |
|
|
85
|
+
| 4 | `architectural` | 🔴 |
|
|
86
|
+
|
|
87
|
+
## Key principles
|
|
88
|
+
|
|
89
|
+
- **Evidence over opinion**: Every classification must cite specific codebase evidence (file paths, module counts, dependency references)
|
|
90
|
+
- **Prefer the higher level**: When characteristics span two levels, classify at the higher one
|
|
91
|
+
- **No action, just assessment**: This skill produces output; it does not modify tickets, save artifacts, or post comments
|
|
92
|
+
- **Scale to ticket complexity**: A simple ticket gets a brief assessment; a complex ticket with many moving parts gets a thorough one
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: collaborate
|
|
3
|
+
description: 'Interactive collaboration rules: decide what the gate allows, batch asks at checkpoints, discuss before implementing'
|
|
4
|
+
user-invocable: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Collaborate
|
|
8
|
+
|
|
9
|
+
Rules for interactive work with the user. These do not apply to dispatched subagent sessions.
|
|
10
|
+
|
|
11
|
+
This skill is invoked by a directive in the harness's global guidance during interactive sessions, and can also be invoked directly with `{skill:collaborate}`. It is not triggered by other skills.
|
|
12
|
+
|
|
13
|
+
## Principles
|
|
14
|
+
|
|
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.
|
|
17
|
+
- Don't let refactoring grow beyond the task; recommend the scope call, build on it, and raise it at the checkpoint.
|
|
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
|
+
- Proceed provisionally: Decide what the gate lets you decide, record it, and collect the surviving asks into one review at the checkpoint.
|
|
20
|
+
- Do every step yourself, verification included; the `## Handoffs` section of the collaboration preferences states when a step may leave your hands.
|
|
21
|
+
- When instructions have undiscussed implications, and you see flaws or meaningful improvements, raise them before proceeding.
|
|
22
|
+
|
|
23
|
+
## Concision by default
|
|
24
|
+
|
|
25
|
+
Reason silently and present a concise answer or recommendation; deep-dive only on request. This applies the [concision principle](../_data/concision.md) to interactive replies, with the ambient `## Concision` guidance as the always-on backstop.
|
|
26
|
+
|
|
27
|
+
Concise never means partial: A flaw, risk, or dissent worth raising is signal (see "Critical evaluation when invited"), so cut the walk-through, never the conclusion on which the user must act.
|
|
28
|
+
|
|
29
|
+
## Critical evaluation when invited
|
|
30
|
+
|
|
31
|
+
When the developer invites your opinion ("WDYT?", "Is this right?", "Any concerns?", "Should we…?"), they are asking for critical evaluation, not validation. The developer relies on you as a sounding board; sycophancy wastes their time and erodes trust. When invited:
|
|
32
|
+
|
|
33
|
+
- **Engage with the merits.** Raise the flaws, gaps, risks, and trade-offs that you actually see. If you agree, say so with substantive reasoning, not affirmation.
|
|
34
|
+
- **Broaden the lens.** Don't stay narrowly inside the framing that the developer offered. Ask:
|
|
35
|
+
- What are the modern best practices for this kind of problem?
|
|
36
|
+
- Is this problem already solved by an existing tool, library, or pattern?
|
|
37
|
+
- How do similar systems in this codebase, or comparable codebases, handle it?
|
|
38
|
+
- What constraints, edge cases, or downstream effects could change the answer?
|
|
39
|
+
- **Verify when uncertain.** If your knowledge may be stale, say so and look it up rather than presenting a guess as the answer.
|
|
40
|
+
- **Push back when warranted.** Disagreement, civilly expressed and substantively reasoned, is more valuable than agreement.
|
|
41
|
+
|
|
42
|
+
If the right answer depends on context that you don't yet have, get it before weighing in and name what you consulted; ask first only when the gathering is substantial enough that the developer would want to authorize the spend of their time.
|
|
43
|
+
|
|
44
|
+
## Asking questions
|
|
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.
|
|
47
|
+
|
|
48
|
+
When you do ask, prefer forms that the user can answer unambiguously:
|
|
49
|
+
|
|
50
|
+
- **A confirmation prompt** (end with `👍🏼👎🏼`). A fixed comprehension contract applies to the marker: On a clear affirmation, proceed; on a clear negation, don't; treat anything else as conversation. Full spec in `AGENTS.md` under "Prompt formatting". (Reinforces the rule in `AGENTS.md`: intentional redundancy.)
|
|
51
|
+
- **A numbered options list.** Include a "some other approach (describe)" option if alternatives should stay open.
|
|
52
|
+
- When asking option-style questions, follow [option format](#option-format). (Reinforces the rule in `AGENTS.md`: intentional redundancy.)
|
|
53
|
+
|
|
54
|
+
**Never use an interactive selector to pose the question.** `{tool:AskUserQuestion}` (or any pop-up / arrow-key picker) cannot render the strength markers or pros and cons that the gradient requires, so it silently discards the convention. Always write the choice as plain text in the message body.
|
|
55
|
+
|
|
56
|
+
Not this (an interactive picker, flat label plus description, no markers):
|
|
57
|
+
|
|
58
|
+
> `{tool:AskUserQuestion}`: "Which config layout?" with options "Single file" / "Two configs".
|
|
59
|
+
|
|
60
|
+
This (a numbered gradient list, in the action-items block that closes the turn):
|
|
61
|
+
|
|
62
|
+
> ---
|
|
63
|
+
>
|
|
64
|
+
> **Action items**
|
|
65
|
+
>
|
|
66
|
+
> Want me to:
|
|
67
|
+
>
|
|
68
|
+
> 1. ■■□ Keep a single config file:
|
|
69
|
+
> - ➕ the deploy script reads one fixed path, and changing it touches three repositories
|
|
70
|
+
> 2. ■■□ Split into two configs:
|
|
71
|
+
> - ➕ runtime settings then reload without a restart, which #640 asks for
|
|
72
|
+
|
|
73
|
+
<!-- include: ../_partials/action-items.md / -->
|
|
74
|
+
|
|
75
|
+
## Efficient context usage
|
|
76
|
+
|
|
77
|
+
When you deem appropriate, proactively dispatch subagents to perform tasks. Good examples:
|
|
78
|
+
|
|
79
|
+
- A substantive out-of-scope issue has arisen, and a separate ticket is the right disposition under the three-lane model in [`_data/scope-and-deferral.md`](../_data/scope-and-deferral.md) (the trivial **do now** and **batch later** lanes have already been ruled out, and the ticket content is already known). Dispatch a subagent to create the ticket while you and the developer move on.
|
|
80
|
+
- You are discussing multiple issues with the developer, and some of them would benefit from research. Dispatch subagents for the research while you and the developer continue to discuss the other issues.
|
|
81
|
+
|
|
82
|
+
## Skill improvement
|
|
83
|
+
|
|
84
|
+
- When the user corrects the agent, or specifies a new desired behavior, that feedback is evidence for refining a skill, subagent, rulebook, general guidance, or helper. Invoke the `{skill:capture-feedback}` skill: It applies the immediate fix when there is something concrete and records a generalized `feedback` event (tagged `mistake` when existing guidance was missed) for a later refinement pass to read.
|
|
85
|
+
|
|
86
|
+
<!-- include: ../_partials/option-format.md / -->
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: condense-branch
|
|
3
|
+
description: Squash branch commits into a single well-described commit
|
|
4
|
+
user-invocable: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Condense branch
|
|
8
|
+
|
|
9
|
+
Condense the current branch into a single commit with a comprehensive message.
|
|
10
|
+
|
|
11
|
+
## Process
|
|
12
|
+
|
|
13
|
+
1. **Stash changes** if working tree is dirty
|
|
14
|
+
|
|
15
|
+
2. **Analyze branch** to create a good commit message, and consolidate it while its commits still exist:
|
|
16
|
+
- Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash to obtain `default_branch` from the manifest JSON that it emits on stdout.
|
|
17
|
+
- Consolidate the range into a scratch file, created per the path rules of [gh body file](#gh-body-file) and named `consolidation-{timestamp}.json`:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
consolidation_path="{absolute path from the scratch-directory step}"
|
|
21
|
+
node {harness_home_dir}/scripts/describe-change.mjs consolidate-branch --base {default_branch} > "$consolidation_path" && cat "$consolidation_path"
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
If the call fails, as it does when `commit.title_format` is empty, it leaves the file empty. Relay its error and continue without a consolidated record: The subject renders without a scope or type, and the message does not contain a trailer.
|
|
25
|
+
|
|
26
|
+
- Report each `unmatched` subject and each `violations` entry to the developer. An unmatched subject does not get a trailer in step 4, so it drops out of the entries that the condensed commit declares.
|
|
27
|
+
|
|
28
|
+
[The change record](../_data/change-record.md) states the consolidated record and the `Change:` trailer.
|
|
29
|
+
|
|
30
|
+
3. **Create backup branch**:
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
git branch $(git branch --show-current)-v1
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
If branch exists, increment version number.
|
|
37
|
+
|
|
38
|
+
4. **Condense commits**:
|
|
39
|
+
|
|
40
|
+
Write the title, a blank line, and the body to a scratch file per [gh body file](#gh-body-file), naming it `commit-message-{timestamp}.md`; do not inline the message into the shell command.
|
|
41
|
+
|
|
42
|
+
The call below composes the final message from that file and the step-2 consolidation: the body, a blank line, and one `Change: {change}` trailer per entry, oldest first, as the last paragraph. The trailers are read from the consolidation file inside the call, so the agent does not retype any entry into a command, and a retry rebuilds the message rather than appending to it. If the consolidation did not find any entry, or failed and left the file empty, the message does not contain a trailer.
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
body_path="{absolute path from the write step}"
|
|
46
|
+
consolidation_path="{absolute path of the step-2 consolidation file}"
|
|
47
|
+
[ -s "$body_path" ] || { echo "Body file missing or empty: $body_path" >&2; exit 1; }
|
|
48
|
+
message_path="${body_path%.md}-with-trailers.md"
|
|
49
|
+
{
|
|
50
|
+
cat "$body_path"
|
|
51
|
+
if [ -s "$consolidation_path" ]; then
|
|
52
|
+
printf '\n\n'
|
|
53
|
+
jq -r '.entries[] | "Change: " + .change' "$consolidation_path"
|
|
54
|
+
fi
|
|
55
|
+
} > "$message_path"
|
|
56
|
+
git reset --soft $(git merge-base {default_branch} HEAD)
|
|
57
|
+
git add --all
|
|
58
|
+
git commit --file "$message_path" --no-gpg-sign --no-verify
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Commit message creation
|
|
62
|
+
|
|
63
|
+
### If commits have detailed descriptions
|
|
64
|
+
|
|
65
|
+
Synthesize existing descriptions to describe the final result. Lead the first paragraph with what the branch accomplishes as a whole; use subsequent paragraphs for implementation details. Omit information that's no longer relevant (e.g., changes made then reversed).
|
|
66
|
+
|
|
67
|
+
### If commits lack detail
|
|
68
|
+
|
|
69
|
+
Use `{skill:summarize-change}` to compose a good commit message. Save the description per standard artifact conventions.
|
|
70
|
+
|
|
71
|
+
## Commit format
|
|
72
|
+
|
|
73
|
+
Compose the message per `{rulebook:commit-conventions}`. Use `describe-change.mjs` to render the full commit title (see [title-templates.md](../_data/title-templates.md) for syntax), taking `{scope}` and `{type}` from the step-2 `consolidated_record` and appending `!` to the type if it is breaking. If the consolidation failed, or a field is `null`, omit that flag:
|
|
74
|
+
|
|
75
|
+
<!-- include: ../_partials/commit-title-rendering.md / -->
|
|
76
|
+
|
|
77
|
+
## Safety
|
|
78
|
+
|
|
79
|
+
- Always create a backup branch before condensing
|
|
80
|
+
- Increment version numbers if backup already exists
|
|
81
|
+
- Use `--no-gpg-sign --no-verify` to avoid hook issues
|
|
82
|
+
|
|
83
|
+
<!-- include: ../_partials/gh-body-file.md / -->
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: create-bitbucket-pr
|
|
3
|
+
description: Create a Bitbucket pull request using the delegate interface from create-pr
|
|
4
|
+
user-invocable: false
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Create Bitbucket pull request
|
|
8
|
+
|
|
9
|
+
Internal delegate that creates a pull request on Bitbucket. Called by `create-pr` with fully prepared inputs; this skill does not resolve prefixes, labels, or scope/type.
|
|
10
|
+
|
|
11
|
+
## Delegate interface
|
|
12
|
+
|
|
13
|
+
This skill receives the following inputs from the orchestrator:
|
|
14
|
+
|
|
15
|
+
| Input | Type | Description |
|
|
16
|
+
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------ |
|
|
17
|
+
| `title` | string | Final PR title, already prefixed if applicable |
|
|
18
|
+
| `body` | string | PR body: `## What` onward from the change summary, then the closing line and the `change-record` block |
|
|
19
|
+
| `labels` | string[] | Resolved label names (may be empty) |
|
|
20
|
+
| `base_branch` | string | Bare branch name (e.g., `main`, not `origin/main`) |
|
|
21
|
+
| `ticket_id` | string | Ticket ID for artifact path resolution |
|
|
22
|
+
| `project_slug` | string | Project slug for artifact path resolution |
|
|
23
|
+
| `artifact_base_dir` | string | Base directory for artifact storage |
|
|
24
|
+
|
|
25
|
+
## Process
|
|
26
|
+
|
|
27
|
+
### 1. Create the pull request
|
|
28
|
+
|
|
29
|
+
Call `action: "create"` on the tool named in [Bitbucket pull-request access](../_data/bitbucket-pr-access.md). The pull-request URL does not exist yet, so the coordinates come from that document's second source, the git remote.
|
|
30
|
+
|
|
31
|
+
- **Title**: Use `title` as provided.
|
|
32
|
+
- **Description**: Use `body` as provided.
|
|
33
|
+
- **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
|
+
- **Destination branch**: Use `base_branch`.
|
|
35
|
+
- **Draft/WIP**: Create as draft if the platform supports it.
|
|
36
|
+
|
|
37
|
+
### 2. Report every label as skipped
|
|
38
|
+
|
|
39
|
+
Bitbucket pull requests do not have labels, and the tool does not expose a label parameter on any action. Do not attempt a call. Report every name in `labels` under `Labels skipped:` in the completion output, and leave `Labels applied:` as `none`.
|
|
40
|
+
|
|
41
|
+
Labels matter to `merge-pr` only for a PR whose body does not contain a readable `change-record` block, and a Bitbucket PR contributes none there; this step makes that true.
|
|
42
|
+
|
|
43
|
+
The artifact's label lines keep `create-gh-pr`'s three-field shape: `Labels attempted:` lists the requested set, `Labels applied:` is always `none`, and `Labels skipped:` repeats the requested set.
|
|
44
|
+
|
|
45
|
+
### 3. Save PR artifact
|
|
46
|
+
|
|
47
|
+
Save a `pull-request` artifact in the ticket directory.
|
|
48
|
+
|
|
49
|
+
Ticket directory: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
|
|
50
|
+
|
|
51
|
+
Follow [artifact conventions](../_data/artifact-conventions.md).
|
|
52
|
+
|
|
53
|
+
When the lede is needed and the artifact does not contain it, `capture-lede-decision` takes `--agent-lede-file`; the artifact is not edited to supply it.
|
|
54
|
+
|
|
55
|
+
Filename format:
|
|
56
|
+
|
|
57
|
+
```
|
|
58
|
+
{timestamp}_{slug}_pull-request.md
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Artifact content:
|
|
62
|
+
|
|
63
|
+
```markdown
|
|
64
|
+
<!-- include: ../../_partials/record-marker.md / -->
|
|
65
|
+
|
|
66
|
+
# {title}
|
|
67
|
+
|
|
68
|
+
URL: {PR URL}
|
|
69
|
+
Created: {YYYY-MM-DD HH:MMZ}
|
|
70
|
+
Labels attempted: {comma-separated list, or "none"}
|
|
71
|
+
Labels applied: {comma-separated list, or "none"}
|
|
72
|
+
Labels skipped: {comma-separated list, or "none"}
|
|
73
|
+
|
|
74
|
+
## Body
|
|
75
|
+
|
|
76
|
+
{PR body as submitted, not as the pull request later reads}
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
## Completion
|
|
80
|
+
|
|
81
|
+
```
|
|
82
|
+
PR created: {URL}
|
|
83
|
+
Labels skipped: {list} <- only if labels were requested
|
|
84
|
+
Artifact saved: {artifact path}
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Nothing else.
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: create-commit
|
|
3
|
+
description: Compose and record a commit for one logical unit of work. Pass the paths to stage and a one-line statement of the change's purpose.
|
|
4
|
+
background: false
|
|
5
|
+
context: fork
|
|
6
|
+
model: sonnet
|
|
7
|
+
user-invocable: true
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Create commit
|
|
11
|
+
|
|
12
|
+
Record finished work as a commit: stage one logical unit, render its title, compose its body, and commit.
|
|
13
|
+
|
|
14
|
+
The conventions to which the message is composed -- title format, body voice and mechanics, the work-type taxonomy, and branch naming -- are stated in `{rulebook:commit-conventions}`. Consult it before composing; this skill states the procedure alone.
|
|
15
|
+
|
|
16
|
+
## Arguments
|
|
17
|
+
|
|
18
|
+
- **Paths**: The paths that this commit records. When the arguments do not name any, the candidates are every changed path in the working tree.
|
|
19
|
+
- **Purpose**: One line stating why the change was made. The diff shows what changed; the purpose is the only source of why. When the arguments do not state one, compose the body from the diff alone, and never state a reason that the diff does not show.
|
|
20
|
+
|
|
21
|
+
Everything else comes from the repository: This procedure may run without the conversation that produced the change, so it never relies on anything that only that conversation contains.
|
|
22
|
+
|
|
23
|
+
## What one commit contains
|
|
24
|
+
|
|
25
|
+
One logical unit of work, together with whatever that unit needs to stand on its own. Work that does not stand alone -- a scaffold filled in by a later change -- goes into the change that completes it rather than becoming a commit of its own.
|
|
26
|
+
|
|
27
|
+
Record each unit as it is finished. Several single-concern commits read better than one that bundles them, and each can be reverted without taking the others with it.
|
|
28
|
+
|
|
29
|
+
## Process
|
|
30
|
+
|
|
31
|
+
1. **Read what changed.** Run `git status --short` for which paths changed, then `git diff` and `git diff --cached` for what changed in them. The message reports the diff, so compose it from the diff rather than from what the work set out to do.
|
|
32
|
+
|
|
33
|
+
2. **Stage the unit.** Stage the paths that the arguments name, then confirm that the message will describe exactly the staged set. When the arguments do not name any, stage every changed path, but only if those changes form one unit per [What one commit contains](#what-one-commit-contains); if they don't, stop without committing and report the units that you found.
|
|
34
|
+
|
|
35
|
+
3. **Resolve the title's fields.** The scope and the work type per the conventions, choosing the type by [Work type test](#work-type-test); the title text per [`title-voice.md`](../_data/title-voice.md), with any backticks stripped.
|
|
36
|
+
|
|
37
|
+
4. **Render the title** per [Rendering the title](#rendering-the-title).
|
|
38
|
+
|
|
39
|
+
5. **Compose the body** from the staged diff, taking its reason from the stated purpose. The conventions state its voice and its mechanics; [Line breaks](#line-breaks) below states the one mechanic that binds only while the body is being written.
|
|
40
|
+
|
|
41
|
+
6. **Commit** from a message file, never through `--message`. Write the title, a blank line, and the body to a scratch file per [gh body file](#gh-body-file), naming it `commit-message-{timestamp}.md`; do not inline the message into the shell command.
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
body_path="{absolute path from the write step}"
|
|
45
|
+
[ -s "$body_path" ] || { echo "Body file missing or empty: $body_path" >&2; exit 1; }
|
|
46
|
+
git commit --file "$body_path"
|
|
47
|
+
```
|
|
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.
|
|
50
|
+
|
|
51
|
+
## Work type test
|
|
52
|
+
|
|
53
|
+
<!-- include: ../../_partials/work-type-choice.md / -->
|
|
54
|
+
|
|
55
|
+
## Rendering the title
|
|
56
|
+
|
|
57
|
+
Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash for `ticket_ref`, then render:
|
|
58
|
+
|
|
59
|
+
<!-- include: ../_partials/commit-title-rendering.md / -->
|
|
60
|
+
|
|
61
|
+
## Line breaks
|
|
62
|
+
|
|
63
|
+
<!-- include: ../../_partials/prose-line-breaks.md / -->
|
|
64
|
+
|
|
65
|
+
<!-- include: ../_partials/gh-body-file.md / -->
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: create-devlog
|
|
3
|
+
description: Create a devlog entry summarizing recent work
|
|
4
|
+
user-invocable: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Create devlog entry
|
|
8
|
+
|
|
9
|
+
Summarize changes made in recent commits or the working tree.
|
|
10
|
+
|
|
11
|
+
## Arguments
|
|
12
|
+
|
|
13
|
+
- No arguments: Summarize the last commit
|
|
14
|
+
- `<n>`: Summarize the last N commits
|
|
15
|
+
- `working-tree`: Summarize uncommitted changes
|
|
16
|
+
|
|
17
|
+
## Output format
|
|
18
|
+
|
|
19
|
+
The devlog file begins with YAML frontmatter conforming to the canonical schema; see the canonical example in [artifact-conventions.md](../_data/artifact-conventions.md#universal-artifact-frontmatter) and the devlog-specific extensions in [Devlog frontmatter](../_data/artifact-conventions.md#devlog-frontmatter). The body following the frontmatter has this structure:
|
|
20
|
+
|
|
21
|
+
```markdown
|
|
22
|
+
# Devlog: {Concise description}
|
|
23
|
+
|
|
24
|
+
**Date**: {YYYY-MM-DD HH:MM UTC}
|
|
25
|
+
**Task**: {Brief task description}
|
|
26
|
+
|
|
27
|
+
## Problem
|
|
28
|
+
|
|
29
|
+
{What issue was being addressed}
|
|
30
|
+
|
|
31
|
+
## Solution
|
|
32
|
+
|
|
33
|
+
{How it was solved}
|
|
34
|
+
|
|
35
|
+
## Lessons learned
|
|
36
|
+
|
|
37
|
+
{Key insights, especially wrong turns that were corrected}
|
|
38
|
+
|
|
39
|
+
## Work done
|
|
40
|
+
|
|
41
|
+
{Summary of changes made}
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Guidance
|
|
45
|
+
|
|
46
|
+
- Compose tight from the start ([concision principle](../_data/concision.md)): A devlog records the lessons and outcome, not a step-by-step account
|
|
47
|
+
- Include code snippets only for important lessons learned
|
|
48
|
+
- Never include lengthy code snippets
|
|
49
|
+
- Focus on the most important findings
|
|
50
|
+
- Use only sections appropriate for the task
|
|
51
|
+
|
|
52
|
+
## Saving
|
|
53
|
+
|
|
54
|
+
Resolve session context and the artifact directory before writing.
|
|
55
|
+
|
|
56
|
+
### Path resolution
|
|
57
|
+
|
|
58
|
+
1. 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`, `project_slug`, `artifact_base_dir`, `artifact_paths`, and `branch_name` from it.
|
|
59
|
+
2. If `ticket_id` is non-null: Save as a ticket-level artifact at:
|
|
60
|
+
|
|
61
|
+
```
|
|
62
|
+
{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/{filename}
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Filename uses the ticket-level shape: `{YYYYMMDD-HHMMSSZ}_{slug}_devlog.md`.
|
|
66
|
+
|
|
67
|
+
3. Else (no ticket; research/exploration sessions): Save to the project-scoped fallback at:
|
|
68
|
+
|
|
69
|
+
```
|
|
70
|
+
{artifact_base_dir}/projects/{project_slug}/{artifact_paths.devlogs}/{filename}
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Filename uses the ticket-level timestamp and slug without the artifact-type segment: `{YYYYMMDD-HHMMSSZ}_{slug}.md`.
|
|
74
|
+
|
|
75
|
+
4. `mkdir -p` the target directory before writing.
|
|
76
|
+
|
|
77
|
+
The bundled session-context deriver returns `ticket_id: null` for branches without a recognizable ticket prefix (e.g., `experiment/foo`). Treat null as "no ticket"; never produce a path containing `tickets/null/`.
|
|
78
|
+
|
|
79
|
+
Follow [artifact conventions](../_data/artifact-conventions.md).
|
|
80
|
+
|
|
81
|
+
### Frontmatter
|
|
82
|
+
|
|
83
|
+
The devlog frontmatter conforms to the [universal artifact frontmatter](../_data/artifact-conventions.md#universal-artifact-frontmatter) schema plus the devlog-specific extensions listed in [Devlog frontmatter](../_data/artifact-conventions.md#devlog-frontmatter).
|
|
84
|
+
|
|
85
|
+
Resolve `{commits}` according to the mode:
|
|
86
|
+
|
|
87
|
+
- No argument (last commit): The output of `git log -n 1 --format=%h`.
|
|
88
|
+
- `<n>` (last N commits): The output of `git log -n N --format=%h | paste -sd, -`.
|
|
89
|
+
- `working-tree`: No value.
|
|
90
|
+
|
|
91
|
+
Run via Bash, writing each resolved value into the call as literal text:
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
{harness_home_dir}/scripts/resolve-frontmatter.sh \
|
|
95
|
+
--skill create-devlog \
|
|
96
|
+
--interactive true \
|
|
97
|
+
--model "{model_id}" \
|
|
98
|
+
--extra-list "commits={commits}"
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Drop the `--extra-list` flag entirely in `working-tree` mode, in which `{commits}` does not have a value; passing it empty emits `commits: []`.
|
|
102
|
+
|
|
103
|
+
Prepend the script's output verbatim to the artifact body. Source `{model_id}` from your system-prompt environment block: the line `model named ... model ID is ...`.
|
|
104
|
+
|
|
105
|
+
### Filename examples
|
|
106
|
+
|
|
107
|
+
- Ticket-scoped: `20260418-153000Z_make-devlogs-ticket-scoped_devlog.md`
|
|
108
|
+
- Project-scoped fallback: `20250809-143000Z_fix-csp-violation-preventing-script-injection.md`
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: create-gh-pr
|
|
3
|
+
description: Create a GitHub pull request using the delegate interface from create-pr
|
|
4
|
+
user-invocable: false
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Create GitHub pull request
|
|
8
|
+
|
|
9
|
+
Internal delegate that creates a pull request on GitHub. Called by `create-pr` with fully prepared inputs; this skill does not resolve prefixes, labels, or scope/type.
|
|
10
|
+
|
|
11
|
+
## Delegate interface
|
|
12
|
+
|
|
13
|
+
This skill receives the following inputs from the orchestrator:
|
|
14
|
+
|
|
15
|
+
| Input | Type | Description |
|
|
16
|
+
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------ |
|
|
17
|
+
| `title` | string | Final PR title, already prefixed if applicable |
|
|
18
|
+
| `body` | string | PR body: `## What` onward from the change summary, then the closing line and the `change-record` block |
|
|
19
|
+
| `labels` | string[] | Resolved label names (may be empty) |
|
|
20
|
+
| `base_branch` | string | Bare branch name (e.g., `main`, not `origin/main`) |
|
|
21
|
+
| `ticket_id` | string | Ticket ID for artifact path resolution |
|
|
22
|
+
| `project_slug` | string | Project slug for artifact path resolution |
|
|
23
|
+
| `artifact_base_dir` | string | Base directory for artifact storage |
|
|
24
|
+
|
|
25
|
+
## Process
|
|
26
|
+
|
|
27
|
+
### 1. Construct label flags
|
|
28
|
+
|
|
29
|
+
If `labels` is empty, skip this step; the create call does not need any `--label` flags.
|
|
30
|
+
|
|
31
|
+
Otherwise render one `--label "{label_name}"` flag per label in the `labels` list, and write them into the create call below 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.
|
|
32
|
+
|
|
33
|
+
### 2. Create the pull request
|
|
34
|
+
|
|
35
|
+
Write the body to a scratch file per [gh body file](#gh-body-file); do not inline the body into the shell command. Name it `gh-body-pr-{timestamp}.md`, since the PR does not have a number until this step returns one.
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
body_path="{absolute path from the write step}"
|
|
39
|
+
[ -s "$body_path" ] || { echo "Body file missing or empty: $body_path" >&2; exit 1; }
|
|
40
|
+
gh pr create \
|
|
41
|
+
--title "{title}" \
|
|
42
|
+
--body-file "$body_path" \
|
|
43
|
+
--base "{base_branch}" \
|
|
44
|
+
--draft \
|
|
45
|
+
{label_flags}
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
`gh pr create` prints the pull-request URL. Read it from the command's output and include it in step 4's artifact and the completion line; never capture it into a shell variable.
|
|
49
|
+
|
|
50
|
+
### 3. Handle label failures
|
|
51
|
+
|
|
52
|
+
If `gh pr create` fails and the error indicates one or more labels are invalid:
|
|
53
|
+
|
|
54
|
+
1. Identify the failing label(s) from the error message.
|
|
55
|
+
2. Remove the failing labels from the `--label` flags.
|
|
56
|
+
3. Retry `gh pr create` without the failing labels, re-stating the assignment and the guard for the same scratch file; do not rewrite the body or inline it.
|
|
57
|
+
4. Record which labels were skipped.
|
|
58
|
+
|
|
59
|
+
If the failure is unrelated to labels, report the error and stop.
|
|
60
|
+
|
|
61
|
+
### 4. Save PR artifact
|
|
62
|
+
|
|
63
|
+
Save a `pull-request` artifact in the ticket directory.
|
|
64
|
+
|
|
65
|
+
Ticket directory: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
|
|
66
|
+
|
|
67
|
+
Follow [artifact conventions](../_data/artifact-conventions.md).
|
|
68
|
+
|
|
69
|
+
When the lede is needed and the artifact does not contain it, `capture-lede-decision` takes `--agent-lede-file`; the artifact is not edited to supply it.
|
|
70
|
+
|
|
71
|
+
Filename format:
|
|
72
|
+
|
|
73
|
+
```
|
|
74
|
+
{timestamp}_{slug}_pull-request.md
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Artifact content:
|
|
78
|
+
|
|
79
|
+
```markdown
|
|
80
|
+
<!-- include: ../../_partials/record-marker.md / -->
|
|
81
|
+
|
|
82
|
+
# {title}
|
|
83
|
+
|
|
84
|
+
URL: {PR URL returned by gh}
|
|
85
|
+
Created: {YYYY-MM-DD HH:MMZ}
|
|
86
|
+
Labels attempted: {comma-separated list, or "none"}
|
|
87
|
+
Labels applied: {comma-separated list, or "none"}
|
|
88
|
+
Labels skipped: {comma-separated list, or "none"}
|
|
89
|
+
|
|
90
|
+
## Body
|
|
91
|
+
|
|
92
|
+
{PR body as submitted, not as the pull request later reads}
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
## Completion
|
|
96
|
+
|
|
97
|
+
```
|
|
98
|
+
PR created: {URL}
|
|
99
|
+
Labels applied: {list} <- only if labels were requested
|
|
100
|
+
Labels skipped: {list} <- only if any labels failed
|
|
101
|
+
Artifact saved: {artifact path}
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Nothing else.
|
|
105
|
+
|
|
106
|
+
<!-- include: ../_partials/gh-body-file.md / -->
|