From 2433f5e78e5c9ec1d4d85a90c010e03ee342dc30 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Tue, 10 Nov 2026 20:46:21 -0500 Subject: [PATCH 1/3] Add design spec: Follow a companion skill when creating a ticket --- ...-skill-for-project-specific-tick-design.md | 129 ++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 docs/superpowers/specs/2026-11-11-follow-the-team-s-own-ticket-skill-for-project-specific-tick-design.md diff --git a/docs/superpowers/specs/2026-11-11-follow-the-team-s-own-ticket-skill-for-project-specific-tick-design.md b/docs/superpowers/specs/2026-11-11-follow-the-team-s-own-ticket-skill-for-project-specific-tick-design.md new file mode 100644 index 000000000..5aef61156 --- /dev/null +++ b/docs/superpowers/specs/2026-11-11-follow-the-team-s-own-ticket-skill-for-project-specific-tick-design.md @@ -0,0 +1,129 @@ +# Follow a companion skill for project-specific ticket details — design + +Change 0591 — Follow a companion skill when creating a ticket + +## Intent + +Many people who use a ticket system already have an agent skill for their ticket project. It might come from their company, their team, or themselves. This design calls it a **companion skill**. It knows things docket doesn't: the title format, which sprint new tickets go into, which custom fields must be set and their ids, the default labels, the ticket type the project uses, and limits such as making one ticket-system call at a time. + +Docket's create path (`docket-link-ticket`, `references/create.md`) knows none of this. Today a ticket docket creates lands with the wrong title format, no sprint, no custom fields, and none of the default labels, and someone fixes it by hand. This change makes the create path find the companion skill and follow it for those details. Docket keeps everything it owns today. + +## Goals + +- A ticket docket creates gets the project's title format, sprint, required and default field values, default labels, and ticket type, without fixing them by hand afterwards. +- The person names the companion skill once, in config, at whatever layer fits: global for a skill installed for the user, or the repository for a per-project choice. +- With no config and no matching skill, creating a ticket works exactly as it does today. + +## Non-goals + +- Linking an existing ticket, importing a change from a ticket, and `docket-update-ticket` (comments) do not use the companion skill in this change. The key's name is generic, so a later change can extend it to updates without renaming anything. +- Naming, shipping, or describing any particular companion skill or its values. Docket ships no provider- or team-specific metadata. +- Syncing sprint, assignee, status, or any other field after creation. +- Provider API code or credentials in docket. Any ticket-system call from this repository. +- Automatic creation with nobody present (`tickets.auto.change_created`, change 587). That change decides how the companion skill behaves when no one can be asked. + +## Anti-goals + +- A companion skill that overrides docket's own contract: the readiness check, the description body, the person's approval of the draft, or recording only after the connector confirms. +- A ticket-system action the person never saw in the draft, whether it sets a field or runs after creation. +- A missing or misconfigured companion skill that stops ticket creation. It is a warning and a fallback, never a new blocking gate. + +## Decisions + +### 1. The config key `tickets.companion_skill` + +A new optional string key, `tickets.companion_skill`, default `""` (unset). It names a skill by the name the session's skill list shows. + +Unlike its `tickets.*` siblings, which are repository-only, this key is **any layer** (`scopeAny`): global user config, repo `.docket.yml`, and `.docket.local.yml`, with the more local one winning per the normal precedence. The difference is deliberate. A companion skill is usually installed for the user, so it shows up in every repository, and the global config is where a user-wide default belongs. The siblings describe the repository itself (which system, which site, which project). This key describes the person's tooling, so it gets normal layering. + +- Schema leaf: `kind: kindString`, `merge: mergeScalar`, `scope: scopeAny`, `disp: dispSupported`, `validate: singleLineStringLeaf()`, beside the other `tickets.*` leaves in `internal/config/schema.go`. +- `Tickets` struct gains `CompanionSkill Value[string] \`json:"companion_skill"\``, resolved in `internal/config/resolve.go` like its siblings, so `diagnostic.config` reports it at `effective.tickets.companion_skill.value`. +- The schema comment above the ticket leaves, and the `Tickets` struct comment ("Every leaf is repository-only"), are corrected to name the one any-layer leaf and why. +- `docs/reference/config-keys.md` gains a row: `tickets.companion_skill` | `""` (unset) | any layer | the skill to follow for project-specific details when creating a ticket (title format, sprint, fields, labels, type). +- Docket's own `.docket.yml` still declares no `tickets` block (`TestDocketYMLDeclaresNoTicketsKey` is unchanged). + +### 2. Finding the companion skill (create path only) + +Before its first ticket-system call, the create path reads `tickets.companion_skill` from `diagnostic.config` at `effective.tickets.companion_skill.value`, the same way it reads `tickets.project`. + +- **Key set and the skill is available in the session:** load it and follow it (decisions 3 and 4). Docket does not check whether the skill covers this project. The key is the person's explicit choice. +- **Key set but the skill is not available:** say so in one line (`tickets.companion_skill names , which isn't available in this session`), then fall through to matching by description. +- **Key unset, or fell through:** look through the skills available in the session for one whose description says it handles this ticket project (`tickets.project`, or the project the person gave for this run). The companion skill's own description decides which projects it covers, one or several. Docket never assumes a one-to-one pairing. + - One match: load it and follow it. + - Several: ask the person which one (the create path always has a person present). + - None: create the ticket exactly as today. + +Docket never names a particular skill, and never records which one was used anywhere except the draft and the report. + +### 3. What the companion skill decides + +When a companion skill is in use, it wins on: + +- **Ticket type, only when the companion skill states one.** If the companion skill itself prescribes a ticket type (one fixed type, or its own mapping from the change), docket uses it. Otherwise docket chooses the type with its current logic (`fix` → bug, `feat` → story or feature, anything else → task, asking the person when nothing matches). Docket never infers a type from the companion skill's examples or defaults for other things. +- **Title format.** When it prescribes a format, docket fills the format's summary part with the change's title (the export's H1). Docket still supplies the words. The companion skill supplies the shape. +- **Required and default field values**, such as the current sprint, a team field, or other custom fields, with the field ids and any lookups the skill says to make through the connector. +- **Default labels.** +- **Any other field on the new ticket**: assignee, priority, components, fix version, an epic or parent link, story points, acceptance criteria copied into a custom field, and the like. +- **What it does after the ticket exists**: moving it to a status, adding watchers, posting a comment, or any other follow-up the companion skill prescribes for a new ticket. Docket lets it. +- **How to make the calls**: pacing (for example one ticket-system call at a time), and any call sequence it prescribes, including setting a field with an edit after creation when the provider can't take it in the create call. + +### 4. What docket always decides + +Docket's rules stand, with or without a companion skill: + +- the already-linked and broken-link stops; +- the readiness check and refinement; +- **the description body**: docket's export of the change, plus the spec line or attachment, written once and never rewritten. A companion skill's own description template does not replace it. +- the draft the person approves before anything is created; +- recording the link only after the connector confirms the ticket, and never creating a second ticket. + +When a companion skill's instruction conflicts with one of these, docket's rule stands and the agent says so in one line in the draft (` asks for ; docket keeps `). For example, an after-creation step that would replace the description is not run. + +### 5. The draft shows everything the companion skill will do + +The draft (create.md step 7) adds what comes from the companion skill: its name, the formatted title, each field it sets (type, sprint, custom fields, labels, and any other field), and each action it will take after the ticket exists. Nothing from the companion skill reaches the ticket without the person seeing it in the draft first. The report (step 11) names the companion skill used, if any. + +### 6. Order of calls once the person says go + +1. Create the ticket (step 8), with every companion field the create call accepts. +2. Apply the companion's remaining fields with edits, then its after-creation actions, in the order and pace it prescribes. +3. Attach the exported spec, when step 6 chose an attachment (step 9). +4. Record the link (step 10). + +Once the connector confirms the ticket exists, a later failure in steps 2 or 3 never stops the record. The ticket stays, and the link is still recorded. The report names each field or action that didn't land, with what the person needs to finish it by hand. This is the same treatment a failed attachment gets today. There is still no retry loop and never a second ticket. + +### 7. Ticket skills may edit the ticket they work on + +The rule that a created ticket's description is written once and never rewritten is removed. Editing the ticket is allowed when the work requires it: setting fields after creation, a companion skill's follow-up actions, or another edit the person asks for. Three places in `create.md` change: + +- **Step 6** keeps the branch link (not one pinned to a commit), with a new reason: a branch link stays current after a later spec revision. The "the description is written once" clause goes. +- **Step 8** drops "The description is written once and never rewritten." The `change_0584_link_ticket_skill` contract line pinning it (`internal/repoguard/prose_contracts_test.go`) is removed in the same commit, with no replacement that would forbid edits. +- **Step 9** keeps "the ticket stays" on a failed upload and drops "since its description cannot be rewritten". + +Nothing here adds syncing. Docket still never updates a ticket on its own after creation (out of scope above). `docket-update-ticket` has no such rule and is untouched. Its private delivery's "never delete from a ticket" (leaving already-landed attachments in place after a failed upload) concerns deleting, not editing, and stays. + +## Where it lands + +- `skills/docket-link-ticket/references/create.md`: a step before the ticket-type step that finds the companion skill (decision 2). The ticket-type step defers to it (decision 3). The draft and create steps carry the companion values and actions (decisions 3, 5, and 6). One sentence lists what docket always keeps (decision 4). The never-rewritten wording is removed (decision 7). The existing step text pinned by the `change_0584_link_ticket_skill` contracts stays; where wording must change, update the contract in the same commit. +- `skills/docket-link-ticket/SKILL.md`: only if the shared *Where tickets go* rule needs a pointer. The companion rules live in `create.md`, since only creation uses them. +- The config schema, struct, resolver, and `docs/reference/config-keys.md` (decision 1). +- The embedded skill tree is regenerated (`go generate ./internal/assets/`), and the `docket-link-ticket/references/create.md` line/word budget in `internal/repoguard/budgets_test.go` is raised with a change-tagged note, per that table's convention. + +## Tests + +- A new prose contract (sentinel for this change) in `internal/repoguard/prose_contracts_test.go` on `create.md` pins: when to look (before the first ticket-system call); the key read path; the missing-skill warning and fallback; description matching with the one, several, and none outcomes; what the companion skill decides; that docket keeps the description body, the readiness check, the approval, and record-after-confirm; that the draft shows companion-set values and after-creation actions; and that a failed field edit or action after creation still records the link and reports what didn't land. +- The `change_0584_link_ticket_skill` contract no longer pins "The description is written once and never rewritten."; an absent-clause assertion pins that `create.md` carries no "never rewritten" / "cannot be rewritten" wording. It is mutation-tested: deleting each pinned clause turns it red. +- Config tests: `tickets.companion_skill` resolves from the global layer, the repo layer, and the local layer with normal precedence, and is not warned-and-ignored at a machine layer the way its siblings are. `diagnostic.config` reports it at the documented path. +- The whole suite runs at the build gate. With the key unset, no existing test's expectations change. + +## Acceptance criteria + +- `create.md` says when to look for a companion skill, how it is found, what to take from it, and which docket rules always win; the prose contract pins that text. +- `tickets.companion_skill` is accepted at every config layer with normal precedence and documented in the config-keys reference. +- With the key unset and no matching skill, creating a ticket behaves as before, except that the never-rewritten wording is gone. +- The results list an **Important** live check from another repository with a companion skill installed: create a ticket from a change, once with the key set and once relying on description matching. Confirm the title format, sprint, custom fields, labels, type, and any after-creation actions match the companion skill, and that the draft showed them before creation. Also confirm the missing-skill warning appears when the key names a skill that isn't installed. + +## Left to the builder + +- Exact step numbering and wording in `create.md`, within the decisions above. +- Whether the description-matching rule names the provider and site as well as the project when judging a match. From 77c17e1a077beeaa963e308eeee927b01a9f0159 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Tue, 10 Nov 2026 20:54:14 -0500 Subject: [PATCH 2/3] feat(config): add tickets.companion_skill, settable at any layer --- .docket.example.yml | 15 +++++- docs/reference/config-keys.md | 1 + internal/app/config.go | 1 + internal/app/config_test.go | 6 ++- internal/assets/embedded/manifest.json | 6 +-- .../assets/embedded/tree/.docket.example.yml | 15 +++++- internal/config/config.go | 13 +++-- internal/config/decode_test.go | 3 ++ internal/config/defaults.go | 7 +-- internal/config/defaults_test.go | 1 + internal/config/fixtures_test.go | 1 + internal/config/resolve.go | 1 + internal/config/resolve_test.go | 47 +++++++++++++++++++ internal/config/schema.go | 9 +++- internal/config/schema_test.go | 5 +- internal/config/setting_paths_test.go | 2 +- 16 files changed, 113 insertions(+), 20 deletions(-) diff --git a/.docket.example.yml b/.docket.example.yml index db74ff7cd..01edc32c5 100644 --- a/.docket.example.yml +++ b/.docket.example.yml @@ -270,13 +270,24 @@ change_types: [chore, docs, feat, fix, refactor, perf] # request opens, its pull request merges, or its results are complete. All are off by default, # and like the settings above, docket does not act on them yet. # -# These settings belong to the repository: a value in the global config or `.docket.local.yml` is -# ignored with a warning. +# These settings belong to the repository, except `companion_skill`: any other value in the global +# config or `.docket.local.yml` is ignored with a warning. # scope: repo-only (shared-setting guarded) tickets: provider: "" site: "" project: "" + + # companion_skill — a skill you already have for your ticket project (from your company, your + # team, or yourself), named the way your session's skill list shows it. When a ticket is created + # from a change, docket follows it for the project's title format, sprint, fields, labels, and + # ticket type. Empty (the default) means docket looks for a skill whose description covers the + # project, and creates the ticket as usual when there is none. Unlike the other ticket settings, + # it may be set in the global config, since a skill is usually installed for you rather than for + # one repository. + # scope: any layer + companion_skill: "" + auto: change_created: false spec_written: false diff --git a/docs/reference/config-keys.md b/docs/reference/config-keys.md index ede81668a..03dfad743 100644 --- a/docs/reference/config-keys.md +++ b/docs/reference/config-keys.md @@ -60,6 +60,7 @@ Each key has one scope: | `tickets.provider` | `""` (unset) | repo-only | the ticket system this repository's changes link to (jira, linear, …); used when linking or creating a ticket | | `tickets.site` | `""` (unset) | repo-only | where that ticket system lives; used when linking a ticket by URL or id | | `tickets.project` | `""` (unset) | repo-only | where new tickets go (a project, team, repository, or board, by tool); used when creating a ticket | +| `tickets.companion_skill` | `""` (unset) | any layer | the skill to follow for project-specific details when creating a ticket (title format, sprint, fields, labels, type) | | `tickets.auto.change_created` | `false` | repo-only | a switch for when a change is created; no effect yet | | `tickets.auto.spec_written` | `false` | repo-only | a switch for when a change's spec is written; no effect yet | | `tickets.auto.pr_opened` | `false` | repo-only | a switch for when a change's pull request opens; no effect yet | diff --git a/internal/app/config.go b/internal/app/config.go index d02a29d9b..1e7eaad3d 100644 --- a/internal/app/config.go +++ b/internal/app/config.go @@ -276,6 +276,7 @@ func effectiveLines(eff *config.Effective) []effectiveLine { leafLine("tickets.provider", textValue(eff.Tickets.Provider.Value), eff.Tickets.Provider.Provenance), leafLine("tickets.site", textValue(eff.Tickets.Site.Value), eff.Tickets.Site.Provenance), leafLine("tickets.project", textValue(eff.Tickets.Project.Value), eff.Tickets.Project.Provenance), + leafLine("tickets.companion_skill", textValue(eff.Tickets.CompanionSkill.Value), eff.Tickets.CompanionSkill.Provenance), leafLine("tickets.auto.change_created", strconv.FormatBool(eff.Tickets.Auto.ChangeCreated.Value), eff.Tickets.Auto.ChangeCreated.Provenance), leafLine("tickets.auto.spec_written", strconv.FormatBool(eff.Tickets.Auto.SpecWritten.Value), eff.Tickets.Auto.SpecWritten.Provenance), leafLine("tickets.auto.pr_opened", strconv.FormatBool(eff.Tickets.Auto.PROpened.Value), eff.Tickets.Auto.PROpened.Provenance), diff --git a/internal/app/config_test.go b/internal/app/config_test.go index b7291de74..14e3634c6 100644 --- a/internal/app/config_test.go +++ b/internal/app/config_test.go @@ -909,6 +909,7 @@ func TestConfigDiagnosticsTicketsSurface(t *testing.T) { "tickets.provider = (unset) [built-in]", "tickets.site = (unset) [built-in]", "tickets.project = (unset) [built-in]", + "tickets.companion_skill = (unset) [built-in]", "tickets.auto.change_created = false [built-in]", "tickets.auto.spec_written = false [built-in]", "tickets.auto.pr_opened = false [built-in]", @@ -925,6 +926,7 @@ func TestConfigDiagnosticsTicketsSurface(t *testing.T) { src := []config.Source{{Layer: config.LayerRepository, Name: ".docket.yml", Data: []byte( "tickets:\n provider: jira\n site: tickets.example.com\n project: CLOUD\n" + + " companion_skill: team-tickets\n" + " auto:\n change_created: true\n spec_written: true\n pr_opened: true\n" + " pr_merged: true\n results_completed: true\n")}} r := DiagnosticConfig(src, mainCtx(), false) @@ -933,6 +935,7 @@ func TestConfigDiagnosticsTicketsSurface(t *testing.T) { } tk := r.Effective.Tickets if tk.Provider.Value != "jira" || tk.Site.Value != "tickets.example.com" || tk.Project.Value != "CLOUD" || + tk.CompanionSkill.Value != "team-tickets" || !tk.Auto.ChangeCreated.Value || !tk.Auto.SpecWritten.Value || !tk.Auto.PROpened.Value || !tk.Auto.PRMerged.Value || !tk.Auto.ResultsCompleted.Value { t.Errorf("effective tickets = %+v, want every declared value", tk) @@ -942,6 +945,7 @@ func TestConfigDiagnosticsTicketsSurface(t *testing.T) { "tickets.provider = jira [repository .docket.yml:2]", "tickets.site = tickets.example.com", "tickets.project = CLOUD", + "tickets.companion_skill = team-tickets", "tickets.auto.change_created = true", "tickets.auto.spec_written = true", "tickets.auto.pr_opened = true", @@ -956,7 +960,7 @@ func TestConfigDiagnosticsTicketsSurface(t *testing.T) { if err != nil { t.Fatal(err) } - for _, want := range []string{`"tickets":`, `"provider":`, `"auto":`, `"change_created":`, `"results_completed":`} { + for _, want := range []string{`"tickets":`, `"provider":`, `"companion_skill":`, `"auto":`, `"change_created":`, `"results_completed":`} { if !strings.Contains(string(raw), want) { t.Errorf("effective JSON lacks %s: %s", want, raw) } diff --git a/internal/assets/embedded/manifest.json b/internal/assets/embedded/manifest.json index f05cbfeae..0657221ea 100644 --- a/internal/assets/embedded/manifest.json +++ b/internal/assets/embedded/manifest.json @@ -1,14 +1,14 @@ { "format_version": 1, "asset_protocol": 1, - "asset_set_id": "sha256:3953fb0eec7f0d1ccdbaddf904a81445076c3224ebf80406a5ab2da15b037039", + "asset_set_id": "sha256:6c5aeadcccace9c887aed5629f3c8ab3c88c775dc9f5fe25f1b137623f098bdc", "entries": [ { "path": ".docket.example.yml", "role": "config-schema", "mode": 420, - "size": 23821, - "sha256": "935b3626d0228caebe341ab1704376e84d631a0712f026f5ba9a25bbdca72cb6" + "size": 24509, + "sha256": "895433aad374061e9cbc530f39655714a2b7d0a414a89d54ce320e7e95f755d5" }, { "path": "agents/docket-adr.md", diff --git a/internal/assets/embedded/tree/.docket.example.yml b/internal/assets/embedded/tree/.docket.example.yml index db74ff7cd..01edc32c5 100644 --- a/internal/assets/embedded/tree/.docket.example.yml +++ b/internal/assets/embedded/tree/.docket.example.yml @@ -270,13 +270,24 @@ change_types: [chore, docs, feat, fix, refactor, perf] # request opens, its pull request merges, or its results are complete. All are off by default, # and like the settings above, docket does not act on them yet. # -# These settings belong to the repository: a value in the global config or `.docket.local.yml` is -# ignored with a warning. +# These settings belong to the repository, except `companion_skill`: any other value in the global +# config or `.docket.local.yml` is ignored with a warning. # scope: repo-only (shared-setting guarded) tickets: provider: "" site: "" project: "" + + # companion_skill — a skill you already have for your ticket project (from your company, your + # team, or yourself), named the way your session's skill list shows it. When a ticket is created + # from a change, docket follows it for the project's title format, sprint, fields, labels, and + # ticket type. Empty (the default) means docket looks for a skill whose description covers the + # project, and creates the ticket as usual when there is none. Unlike the other ticket settings, + # it may be set in the global config, since a skill is usually installed for you rather than for + # one repository. + # scope: any layer + companion_skill: "" + auto: change_created: false spec_written: false diff --git a/internal/config/config.go b/internal/config/config.go index 72169cd60..9763e95b4 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -147,12 +147,15 @@ type Effective struct { } // Tickets names the repository's ticket system and where new tickets go, plus -// the per-event automation switches. Every leaf is repository-only. +// the per-event automation switches. Every leaf is repository-only except +// CompanionSkill, which may be set at any layer because it names the person's +// own tooling (the skill to follow when creating a ticket), not the repository. type Tickets struct { - Provider Value[string] `json:"provider"` - Site Value[string] `json:"site"` - Project Value[string] `json:"project"` - Auto TicketsAuto `json:"auto"` + Provider Value[string] `json:"provider"` + Site Value[string] `json:"site"` + Project Value[string] `json:"project"` + CompanionSkill Value[string] `json:"companion_skill"` + Auto TicketsAuto `json:"auto"` } // TicketsAuto holds the switches that let docket act on a linked ticket on diff --git a/internal/config/decode_test.go b/internal/config/decode_test.go index aa4fc4687..07bc9a434 100644 --- a/internal/config/decode_test.go +++ b/internal/config/decode_test.go @@ -146,6 +146,9 @@ func decodeAcceptanceCases() []decodeCase { flow: "tickets: {site: tickets.example.com}\n", value: "tickets.example.com"}, {row: "tickets.project", path: "tickets.project", block: "tickets:\n project: CLOUD\n", flow: "tickets: {project: CLOUD}\n", value: "CLOUD"}, + {row: "tickets.companion_skill", path: "tickets.companion_skill", + block: "tickets:\n companion_skill: team-tickets\n", + flow: "tickets: {companion_skill: team-tickets}\n", value: "team-tickets"}, {row: "tickets.auto.change_created", path: "tickets.auto.change_created", block: "tickets:\n auto:\n change_created: true\n", flow: "tickets: {auto: {change_created: true}}\n", value: true}, diff --git a/internal/config/defaults.go b/internal/config/defaults.go index 589fdce2f..5b89a2f73 100644 --- a/internal/config/defaults.go +++ b/internal/config/defaults.go @@ -58,9 +58,10 @@ func builtinEffective() Effective { }, ChangeTypes: builtinValue([]string{"chore", "docs", "feat", "fix", "refactor", "perf"}), Tickets: Tickets{ - Provider: builtinValue(""), - Site: builtinValue(""), - Project: builtinValue(""), + Provider: builtinValue(""), + Site: builtinValue(""), + Project: builtinValue(""), + CompanionSkill: builtinValue(""), Auto: TicketsAuto{ ChangeCreated: builtinValue(false), SpecWritten: builtinValue(false), diff --git a/internal/config/defaults_test.go b/internal/config/defaults_test.go index 9661de5a6..58441225a 100644 --- a/internal/config/defaults_test.go +++ b/internal/config/defaults_test.go @@ -179,6 +179,7 @@ func TestBuiltinEffectiveMatchesRegistryDefaults(t *testing.T) { "tickets.provider": eff.Tickets.Provider.Value, "tickets.site": eff.Tickets.Site.Value, "tickets.project": eff.Tickets.Project.Value, + "tickets.companion_skill": eff.Tickets.CompanionSkill.Value, "tickets.auto.change_created": eff.Tickets.Auto.ChangeCreated.Value, "tickets.auto.spec_written": eff.Tickets.Auto.SpecWritten.Value, "tickets.auto.pr_opened": eff.Tickets.Auto.PROpened.Value, diff --git a/internal/config/fixtures_test.go b/internal/config/fixtures_test.go index d479590c8..1d802fa50 100644 --- a/internal/config/fixtures_test.go +++ b/internal/config/fixtures_test.go @@ -190,6 +190,7 @@ func TestFixtureSparseDefaults(t *testing.T) { {"tickets.provider", eff.Tickets.Provider.Explicit, eff.Tickets.Provider.Provenance.Layer}, {"tickets.site", eff.Tickets.Site.Explicit, eff.Tickets.Site.Provenance.Layer}, {"tickets.project", eff.Tickets.Project.Explicit, eff.Tickets.Project.Provenance.Layer}, + {"tickets.companion_skill", eff.Tickets.CompanionSkill.Explicit, eff.Tickets.CompanionSkill.Provenance.Layer}, {"tickets.auto.change_created", eff.Tickets.Auto.ChangeCreated.Explicit, eff.Tickets.Auto.ChangeCreated.Provenance.Layer}, {"tickets.auto.spec_written", eff.Tickets.Auto.SpecWritten.Explicit, eff.Tickets.Auto.SpecWritten.Provenance.Layer}, {"tickets.auto.pr_opened", eff.Tickets.Auto.PROpened.Explicit, eff.Tickets.Auto.PROpened.Provenance.Layer}, diff --git a/internal/config/resolve.go b/internal/config/resolve.go index 6bb458d47..f3bc2a272 100644 --- a/internal/config/resolve.go +++ b/internal/config/resolve.go @@ -333,6 +333,7 @@ func (r *resolution) assemble(byLayer map[LayerKind]map[string]leafDecl) (Effect set(assign(&eff.Tickets.Provider, r.declared, "tickets.provider")) set(assign(&eff.Tickets.Site, r.declared, "tickets.site")) set(assign(&eff.Tickets.Project, r.declared, "tickets.project")) + set(assign(&eff.Tickets.CompanionSkill, r.declared, "tickets.companion_skill")) set(assign(&eff.Tickets.Auto.ChangeCreated, r.declared, "tickets.auto.change_created")) set(assign(&eff.Tickets.Auto.SpecWritten, r.declared, "tickets.auto.spec_written")) set(assign(&eff.Tickets.Auto.PROpened, r.declared, "tickets.auto.pr_opened")) diff --git a/internal/config/resolve_test.go b/internal/config/resolve_test.go index 61641c12f..f34613f8e 100644 --- a/internal/config/resolve_test.go +++ b/internal/config/resolve_test.go @@ -109,6 +109,8 @@ func effectiveLeaf(t *testing.T, eff Effective, path string) (any, Provenance, b return eff.Tickets.Site.Value, eff.Tickets.Site.Provenance, eff.Tickets.Site.Explicit case "tickets.project": return eff.Tickets.Project.Value, eff.Tickets.Project.Provenance, eff.Tickets.Project.Explicit + case "tickets.companion_skill": + return eff.Tickets.CompanionSkill.Value, eff.Tickets.CompanionSkill.Provenance, eff.Tickets.CompanionSkill.Explicit case "tickets.auto.change_created": return eff.Tickets.Auto.ChangeCreated.Value, eff.Tickets.Auto.ChangeCreated.Provenance, eff.Tickets.Auto.ChangeCreated.Explicit case "tickets.auto.spec_written": @@ -697,6 +699,7 @@ func TestTicketsStringSingleLine(t *testing.T) { "tickets:\n site: \"a\\nb\"\n", "tickets:\n project: \"a\\rb\"\n", "tickets:\n provider: \"jira\\n\"\n", + "tickets:\n companion_skill: \"a\\nb\"\n", } { _, diags := decodeDoc(t, doc) if len(diags) != 1 || diags[0].Code != CodeInvalidValue { @@ -1518,6 +1521,50 @@ func TestOpenArtifactsIsAnOrdinaryLayeredKey(t *testing.T) { } } +// TestTicketsCompanionSkillAnyLayer pins tickets.companion_skill as the one +// ticket leaf settable at any layer (change 0591): it names the person's own +// tooling, so a global or local declaration is honoured with ordinary +// precedence and never draws the shared-setting warning its repo-only +// siblings get, even when declared in the same block. +func TestTicketsCompanionSkillAnyLayer(t *testing.T) { + doc := func(v string) string { return "tickets:\n companion_skill: " + v + "\n" } + if v := mustSnapshot(t).Effective.Tickets.CompanionSkill; v.Value != "" || v.Provenance.Layer != LayerBuiltIn || v.Explicit { + t.Fatalf("default = %+v, want non-explicit built-in empty", v) + } + for _, tc := range []struct { + name string + sources []Source + want string + layer LayerKind + }{ + {"global", []Source{srcG(doc("a"))}, "a", LayerGlobal}, + {"local", []Source{srcL(doc("a"))}, "a", LayerRepositoryLocal}, + {"repository over global", []Source{srcG(doc("a")), srcR(doc("b"))}, "b", LayerRepository}, + {"local over repository", []Source{srcR(doc("b")), srcL(doc("c"))}, "c", LayerRepositoryLocal}, + {"local over global", []Source{srcG(doc("a")), srcL(doc("c"))}, "c", LayerRepositoryLocal}, + } { + snap := mustSnapshot(t, tc.sources...) + if v := snap.Effective.Tickets.CompanionSkill; v.Value != tc.want || v.Provenance.Layer != tc.layer || !v.Explicit { + t.Errorf("%s: companion_skill = %+v, want explicit %q from %q", tc.name, v, tc.want, tc.layer) + } + if diagPathSet(snap, CodeSharedSettingIgnored)["tickets.companion_skill"] { + t.Errorf("%s: companion_skill drew %s", tc.name, CodeSharedSettingIgnored) + } + } + + snap := mustSnapshot(t, srcG("tickets:\n provider: jira\n companion_skill: team-tickets\n")) + ignored := diagPathSet(snap, CodeSharedSettingIgnored) + if !ignored["tickets.provider"] || snap.Effective.Tickets.Provider.Value != "" { + t.Errorf("mixed block: provider = %+v, ignored=%v; want the global provider warned about and dropped", snap.Effective.Tickets.Provider, ignored) + } + if ignored["tickets.companion_skill"] { + t.Errorf("mixed block: companion_skill drew %s", CodeSharedSettingIgnored) + } + if v := snap.Effective.Tickets.CompanionSkill; v.Value != "team-tickets" || v.Provenance.Layer != LayerGlobal || !v.Explicit { + t.Errorf("mixed block: companion_skill = %+v, want explicit team-tickets from global", v) + } +} + // The shipped implement-next TTL obeys the same per-field layering as model and // effort: a model-only override keeps it, and a global `auto` or `5m` replaces it. func TestAgentsShippedCacheTTLLayering(t *testing.T) { diff --git a/internal/config/schema.go b/internal/config/schema.go index 4f5462feb..a24c63a95 100644 --- a/internal/config/schema.go +++ b/internal/config/schema.go @@ -383,9 +383,11 @@ func buildRegistry() []pathSpec { })}, // The ticket settings: which ticket system a repository links to, where - // new tickets go, and the per-event automation switches. All belong to + // new tickets go, and the per-event automation switches. They belong to // the repository, so a machine layer's declaration is ignored with a - // warning. + // warning. The one exception is companion_skill, which names the + // person's own tooling (a skill usually installed for the user, in every + // repository) and so is set at any layer. {path: "tickets.provider", kind: kindString, def: "", merge: mergeScalar, scope: scopeRepoOnly, disp: dispSupported, validate: singleLineStringLeaf()}, @@ -395,6 +397,9 @@ func buildRegistry() []pathSpec { {path: "tickets.project", kind: kindString, def: "", merge: mergeScalar, scope: scopeRepoOnly, disp: dispSupported, validate: singleLineStringLeaf()}, + {path: "tickets.companion_skill", kind: kindString, def: "", + merge: mergeScalar, scope: scopeAny, disp: dispSupported, + validate: singleLineStringLeaf()}, {path: "tickets.auto.change_created", kind: kindBool, def: false, merge: mergeScalar, scope: scopeRepoOnly, disp: dispSupported, validate: boolLeaf()}, {path: "tickets.auto.spec_written", kind: kindBool, def: false, diff --git a/internal/config/schema_test.go b/internal/config/schema_test.go index 7a8040401..f270c0907 100644 --- a/internal/config/schema_test.go +++ b/internal/config/schema_test.go @@ -39,7 +39,7 @@ func TestRegistryPathSetMatchesV092(t *testing.T) { "board.sorting.deferred.by", "board.sorting.deferred.direction", "github_project", "terminal_publish", "auto_groom", "change_types", - "tickets.provider", "tickets.site", "tickets.project", + "tickets.provider", "tickets.site", "tickets.project", "tickets.companion_skill", "tickets.auto.change_created", "tickets.auto.spec_written", "tickets.auto.pr_opened", "tickets.auto.pr_merged", "tickets.auto.results_completed", "auto_capture.enabled", "auto_capture.types", @@ -149,6 +149,7 @@ func TestRegistryDefaults(t *testing.T) { "tickets.provider": "", "tickets.site": "", "tickets.project": "", + "tickets.companion_skill": "", "tickets.auto.change_created": false, "tickets.auto.spec_written": false, "tickets.auto.pr_opened": false, @@ -405,6 +406,8 @@ func TestLeafValidators(t *testing.T) { {"tickets site empty ok", "tickets.site", `""`, "", ""}, {"tickets project with space ok", "tickets.project", `"Cloud Team"`, "Cloud Team", ""}, {"tickets site not a string", "tickets.site", "[a]", nil, CodeInvalidType}, + {"tickets companion skill ok", "tickets.companion_skill", "team-tickets", "team-tickets", ""}, + {"tickets companion skill not a string", "tickets.companion_skill", "[a]", nil, CodeInvalidType}, {"tickets auto bool", "tickets.auto.pr_opened", "true", true, ""}, {"tickets auto not a bool", "tickets.auto.pr_merged", "yes-please", nil, CodeInvalidType}, diff --git a/internal/config/setting_paths_test.go b/internal/config/setting_paths_test.go index 9e98c720f..278ef7243 100644 --- a/internal/config/setting_paths_test.go +++ b/internal/config/setting_paths_test.go @@ -55,7 +55,7 @@ func TestSettingPathsSupportSplit(t *testing.T) { "gate_observation_budget", "board_surfaces", "board.section_order", "change_types", "agent_harnesses", - "tickets.provider", "tickets.site", "tickets.project", + "tickets.provider", "tickets.site", "tickets.project", "tickets.companion_skill", "tickets.auto.change_created", "tickets.auto.spec_written", "tickets.auto.pr_opened", "tickets.auto.pr_merged", "tickets.auto.results_completed", "agents.*.*.model", "agents.*.*.effort", "agents.*.*.cache_ttl", From bd2cbdcbaf279b83c853d8b098f6550eede5d55d Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Tue, 10 Nov 2026 20:56:21 -0500 Subject: [PATCH 3/3] feat(skills): follow a companion skill when creating a ticket --- internal/assets/embedded/manifest.json | 6 ++--- .../docket-link-ticket/references/create.md | 27 ++++++++++++------- internal/repoguard/budgets_test.go | 2 +- internal/repoguard/prose_contracts_test.go | 27 ++++++++++++++++++- .../docket-link-ticket/references/create.md | 27 ++++++++++++------- 5 files changed, 64 insertions(+), 25 deletions(-) diff --git a/internal/assets/embedded/manifest.json b/internal/assets/embedded/manifest.json index 0657221ea..e31ab1cff 100644 --- a/internal/assets/embedded/manifest.json +++ b/internal/assets/embedded/manifest.json @@ -1,7 +1,7 @@ { "format_version": 1, "asset_protocol": 1, - "asset_set_id": "sha256:6c5aeadcccace9c887aed5629f3c8ab3c88c775dc9f5fe25f1b137623f098bdc", + "asset_set_id": "sha256:db8870e2ba32c5fde8ed4698ddb53a478d6b49cb2493ed05973aa28ff1df169c", "entries": [ { "path": ".docket.example.yml", @@ -427,8 +427,8 @@ "path": "skills/docket-link-ticket/references/create.md", "role": "skill", "mode": 420, - "size": 5259, - "sha256": "79f5cfa7d582cc125fd8a7e679c3db5d684b5e36c9674f98939b2298667546b5" + "size": 8266, + "sha256": "1319635f866ea850ffe64a65240420be81ce5100e348810084295fa49156304a" }, { "path": "skills/docket-link-ticket/references/import.md", diff --git a/internal/assets/embedded/tree/skills/docket-link-ticket/references/create.md b/internal/assets/embedded/tree/skills/docket-link-ticket/references/create.md index aa829fdf1..2a49fff55 100644 --- a/internal/assets/embedded/tree/skills/docket-link-ticket/references/create.md +++ b/internal/assets/embedded/tree/skills/docket-link-ticket/references/create.md @@ -16,20 +16,27 @@ Loaded from `SKILL.md` when the person asks to create a ticket from a change. Th 3. **Refinement, only if needed.** When the check finds gaps, ask the person targeted questions about what is missing — nothing more. Write the answers through `change.groom` with `outcome: revise` and its owned sections, which works only while the change is `proposed`. `## Acceptance criteria` is one of those sections. Past `proposed`, build the ticket from the change as it stands: name what is missing and let the person decide whether to go ahead. Never invent scope or acceptance criteria, and never promote an unreviewed solution into a requirement. -4. **Ticket type.** Read the ticket types the project actually has through the connector (in Jira, `listJiraProjectIssueTypesMetadata`). `fix` maps to the bug type, `feat` to the story or feature type, and any other type to the task type. With no obvious match, ask the person. A tool without ticket types (Linear, Asana, Trello) gets none. +4. **Companion skill.** Before the first ticket-system call, look for a companion skill: a skill the person already has for this ticket project, from their company, their team, or themselves, that knows its title format, sprint, fields, labels, ticket type, and call limits. Read `tickets.companion_skill` from `diagnostic.config` at `effective.tickets.companion_skill.value`. + - **Set, and the skill is available in this session:** load it and follow it. Do not check whether it covers this project: the key is the person's choice. + - **Set, but the skill is not available:** say so in one line (`tickets.companion_skill names , which isn't available in this session`), then look for one as if the key were unset. + - **Unset:** look through the skills available in this session for one whose description says it handles this ticket project (`tickets.project`, or the project the person gave for this run). Its description decides which projects it covers. One match: load it and follow it. Several: ask the person which one. None: create the ticket without one, as the steps below describe. -5. **Export the body.** Invoke the `docket-export` skill as a **file request** — its rules are its own; do not restate or re-run them — **DIRECTED to:** export `change ` with `--output-path` set to a fresh directory from `mktemp -d "${TMPDIR:-/tmp}/docket-link-ticket.XXXXXX"`, return the path and, in a private repository, the before → after list, and post nothing. The export's H1 is the title; its body keeps Why, What changes, Acceptance criteria, Out of scope, and Open questions. + A companion skill decides the ticket type, only when it states one; the title format, filled with the change's title; the field values, such as the sprint, custom fields, labels, assignee, and priority, with any lookups it prescribes; anything it does after the ticket exists; and how the calls are made, such as one ticket-system call at a time. Docket always keeps the already-linked and broken-link stops, the readiness check, the description body, the person's approval of the draft, and recording the link only after the connector confirms the ticket. The description body is docket's export of the change plus the spec line or attachment; a companion skill's own description template never replaces it. When the companion skill asks for something that conflicts with one of those, docket's rule stands: say so in one line in the draft (` asks for ; docket keeps `) and do not do it. -6. **Spec, when the change has a `spec:`.** The spec is always included, labeled as the proposed approach, never as requirements. There is no separate question: the person's go on the draft is the only approval. - - **Shared repository:** resolve the `open` operation's argv from the capability catalog, never hard-coded, and run it as ` spec --print --json`. When `target_kind` is `url`, the body ends with one line, `Proposed approach: `. That is a branch link, not one pinned to a commit: the description is written once, so a pinned link would go stale after a later spec revision. - - **No URL, or a private repository:** A local path never goes into a ticket. When `target_kind` is `file`, or the repository is private, export the spec through `docket-export` as a file request (as in step 5) and attach it after the ticket exists (step 9). The body ends with `Proposed approach: see the attached `. +5. **Ticket type.** When the companion skill states a ticket type, use it. Otherwise read the ticket types the project actually has through the connector (in Jira, `listJiraProjectIssueTypesMetadata`). `fix` maps to the bug type, `feat` to the story or feature type, and any other type to the task type. With no obvious match, ask the person. A tool without ticket types (Linear, Asana, Trello) gets none. Never infer a type from the companion skill's examples or its defaults for other fields. -7. **Draft and approval.** Show the person, in one message, the title, the project, the mapped type, the body as it will be posted, the spec line or attachment name, and in a private repository the before → after list for the body and the spec. Create only on their go. A `docket-export` word-check hit stops the draft the way `docket-export` does: show the lines and post nothing until the person decides. +6. **Export the body.** Invoke the `docket-export` skill as a **file request** — its rules are its own; do not restate or re-run them — **DIRECTED to:** export `change ` with `--output-path` set to a fresh directory from `mktemp -d "${TMPDIR:-/tmp}/docket-link-ticket.XXXXXX"`, return the path and, in a private repository, the before → after list, and post nothing. The export's H1 is the title; its body keeps Why, What changes, Acceptance criteria, Out of scope, and Open questions. -8. **Create** the ticket through the connector in `tickets.project`: the summary is the export's H1, and the description is the rest. When the provider needs its own markup, convert formatting only, never words. The description is written once and never rewritten. +7. **Spec, when the change has a `spec:`.** The spec is always included, labeled as the proposed approach, never as requirements. There is no separate question: the person's go on the draft is the only approval. + - **Shared repository:** resolve the `open` operation's argv from the capability catalog, never hard-coded, and run it as ` spec --print --json`. When `target_kind` is `url`, the body ends with one line, `Proposed approach: `. That is a branch link, not one pinned to a commit: a branch link stays current after a later spec revision. + - **No URL, or a private repository:** A local path never goes into a ticket. When `target_kind` is `file`, or the repository is private, export the spec through `docket-export` as a file request (as in step 6) and attach it after the ticket exists (step 10). The body ends with `Proposed approach: see the attached `. -9. **Attach** the exported spec, when step 6 chose an attachment. Never assume a one-call upload, and never substitute a local path for an attachment. Some connectors attach in two steps: the Atlassian connector's `uploadAttachmentToJiraIssue` returns an upload command to run from the shell, and the file id it returns is then attached. If the upload fails, the ticket stays, since its description cannot be rewritten: report the failure and the exported file's path so the person can attach it by hand. +8. **Draft and approval.** Show the person, in one message, the title, the project, the mapped type, the body as it will be posted, the spec line or attachment name, and in a private repository the before → after list for the body and the spec. With a companion skill, the draft also names it and shows the formatted title, each field it sets (the type, the sprint, custom fields, labels, and any other field), and each action it will take after the ticket exists; nothing from the companion skill reaches the ticket unless the draft showed it, and any conflict line from step 4 appears here. Create only on their go. A `docket-export` word-check hit stops the draft the way `docket-export` does: show the lines and post nothing until the person decides. -10. **Record** the link with the `change.link-ticket` operation — the provider, the created ticket's id, and its URL — once the connector has confirmed the ticket was created. If recording fails, report the created ticket's URL and retry the link with a fresh `path` and `revision`; never create a second ticket. +9. **Create** the ticket through the connector in `tickets.project`: the summary is the export's H1, or the companion skill's title format with the export's H1 as its summary part, and the description is the rest. When the provider needs its own markup, convert formatting only, never words. Set every companion field the create call accepts. Then set the companion skill's remaining fields with edits, and run its after-creation actions, in the order and pace it prescribes. Once the connector confirms the ticket exists, a field or action that fails afterwards never stops the record: the ticket stays, the link is still recorded (step 11), and the report names each field or action that did not land, with what the person needs to finish it by hand. -11. **Report** the ticket link, its type, whether the spec was linked or attached, and any before → after list. +10. **Attach** the exported spec, when step 7 chose an attachment. Never assume a one-call upload, and never substitute a local path for an attachment. Some connectors attach in two steps: the Atlassian connector's `uploadAttachmentToJiraIssue` returns an upload command to run from the shell, and the file id it returns is then attached. If the upload fails, the ticket stays: report the failure and the exported file's path so the person can attach it by hand. + +11. **Record** the link with the `change.link-ticket` operation — the provider, the created ticket's id, and its URL — once the connector has confirmed the ticket was created. If recording fails, report the created ticket's URL and retry the link with a fresh `path` and `revision`; never create a second ticket. + +12. **Report** the ticket link, its type, whether the spec was linked or attached, the companion skill used, if any, each companion field or action that did not land, and any before → after list. diff --git a/internal/repoguard/budgets_test.go b/internal/repoguard/budgets_test.go index 38506c598..5dd1f419c 100644 --- a/internal/repoguard/budgets_test.go +++ b/internal/repoguard/budgets_test.go @@ -216,7 +216,7 @@ var skillBudgets = []skillBudget{ {"docket-implement-next/references/results-artifact.md", 76, 737}, // 0360: no claim refreshes; change.complete pins a locally looked-up revision (79/765 -> 76/737); 0573: trivial retired (79/775 -> 79/765); 0559: new — the results-artifact ending (no plan, build, or PR; review, complete, clean up) {"docket-implement-next/results-template.md", 70, 543}, // 0573: trivial retired (70/545 -> 70/543); 0502 rebase onto 0510: carried the backlog verdict and next action in the Known issues placeholder (68/506 -> 70/545); 0502: inline review replaces the custom review skill (68/511 -> 68/510); 0498: +whole-branch review summary line in Verification performed (64/446 -> 68/511); 0440: reader-first template — action statement + merged Known issues (see note above); 0502: drop change citations and Go v1 narration (68/510 -> 68/506) {"docket-link-ticket/SKILL.md", 39, 819}, // 0585: update and comment requests route to docket-update-ticket (39/816 -> 39/819); 0584 review: an id-only link takes the provider from tickets.provider and the URL from the connector (39/788 -> 39/816); 0584: new — the inline ticket-linking skill - {"docket-link-ticket/references/create.md", 35, 853}, // 0584 review: the open argv is resolved from the capability catalog (35/843 -> 35/853); 0584: new — the push path + {"docket-link-ticket/references/create.md", 42, 1348}, // 0591: the companion-skill step, its draft and create fields, and the never-rewritten rule removed (35/853 -> 42/1348); 0584 review: the open argv is resolved from the capability catalog (35/843 -> 35/853); 0584: new — the push path {"docket-link-ticket/references/import.md", 15, 323}, // 0584: new — the import path {"docket-review/SKILL.md", 127, 1054}, // 0573: trivial retired (127/1059 -> 127/1054); 0559: the results-artifact mode (114/966 -> 127/1049); 0559: Inputs and evidence sections defer to results-artifact mode (127/1049 -> 127/1059); 0531: the metadata worktree and remote come from the repository.prepare context (114/965 -> 114/966); 0502: the evidence rule keys on the payload's build.gate value; gate-off skipped records are expected (110/913 -> 114/965); 0410: +findings-return capture contract (see note above) {"docket-new-change/SKILL.md", 48, 1552}, // 0582: optional acceptance_criteria body (48/1538 -> 48/1552); 0573: trivial retired; the trivial path is deleted and the brainstorm is told the artifact is always a spec (53/1636 -> 48/1538); 0560: suggest a hold; it rides change.create or change.groom (53/1598 -> 53/1636); 0559: the create request carries deliverable: results-artifact for findings-only work (57/1635 -> 53/1598); 0532: the private-repository writing rule and visibility hand-off (57/1603 -> 57/1635); 0531: the metadata worktree and remote come from the repository.prepare context (57/1596 -> 57/1603); 0502 review: omitted draft-time scalars are described exactly (57/1591 -> 57/1596); 0502: "loop" means /loop only (57/1593 -> 57/1591); 0502: one metadata layout — the docket branch and the .docket/ worktree (57/1590 -> 57/1593); 0502: terminal-publication narration and the repository auto_groom default are deleted (57/1609 -> 57/1590); 0502: invoke superpowers:brainstorming by name (57/1636 -> 57/1609); 0502: the dummy-mode pointer is deleted (59/1674 -> 57/1636); 0445: +pointer to the docket-groom-next revise path after landing (word ceiling 1700 -> 1706); 0382: draft-time scalars moved into change.create (ceiling 1706 -> 1675) diff --git a/internal/repoguard/prose_contracts_test.go b/internal/repoguard/prose_contracts_test.go index 2ebcd7ea4..0802f83cf 100644 --- a/internal/repoguard/prose_contracts_test.go +++ b/internal/repoguard/prose_contracts_test.go @@ -1603,7 +1603,6 @@ var alignmentContracts = []proseContract{ "A local path never goes into a ticket.", "Show the person, in one message, the title, the project, the mapped type, the body as it will be posted, the spec line or attachment name, and in a private repository the before → after list for the body and the spec.", "Create only on their go.", - "The description is written once and never rewritten.", "Never assume a one-call upload, and never substitute a local path for an attachment.", "If recording fails, report the created ticket's URL and retry the link with a fresh `path` and `revision`; never create a second ticket.", }}, @@ -1741,6 +1740,32 @@ var alignmentContracts = []proseContract{ "; used when creating a ticket |", }, absent: []string{"(jira, linear, …); no effect yet |"}}, + // change 0591 — the create path finds a companion skill before its first ticket-system call, follows it for type, title, fields, after-creation actions, and pacing, keeps docket's own rules, shows everything in the draft, and records even when a later field or action fails; the never-rewritten rule is gone. + {sentinel: "change_0591_companion_skill", file: "skills/docket-link-ticket/references/create.md", + present: []string{ + "Before the first ticket-system call, look for a companion skill", + "Read `tickets.companion_skill` from `diagnostic.config` at `effective.tickets.companion_skill.value`.", + "Do not check whether it covers this project: the key is the person's choice.", + "(`tickets.companion_skill names , which isn't available in this session`), then look for one as if the key were unset.", + "look through the skills available in this session for one whose description says it handles this ticket project", + "One match: load it and follow it. Several: ask the person which one. None: create the ticket without one", + "A companion skill decides the ticket type, only when it states one; the title format, filled with the change's title;", + "anything it does after the ticket exists; and how the calls are made", + "Docket always keeps the already-linked and broken-link stops, the readiness check, the description body, the person's approval of the draft, and recording the link only after the connector confirms the ticket.", + "a companion skill's own description template never replaces it", + "docket's rule stands", + "When the companion skill states a ticket type, use it.", + "Never infer a type from the companion skill's examples", + "each field it sets (the type, the sprint, custom fields, labels, and any other field), and each action it will take after the ticket exists", + "nothing from the companion skill reaches the ticket unless the draft showed it", + "Then set the companion skill's remaining fields with edits, and run its after-creation actions, in the order and pace it prescribes.", + "a field or action that fails afterwards never stops the record: the ticket stays, the link is still recorded", + "the report names each field or action that did not land", + "a branch link stays current after a later spec revision", + }, + absent: []string{"never rewritten", "cannot be rewritten", "written once"}}, + {sentinel: "change_0591_companion_skill", file: "docs/reference/config-keys.md", + present: []string{"| `tickets.companion_skill` | `\"\"` (unset) | any layer |"}}, } // oneLayoutAbsent are the retired metadata-layout spellings. diff --git a/skills/docket-link-ticket/references/create.md b/skills/docket-link-ticket/references/create.md index aa829fdf1..2a49fff55 100644 --- a/skills/docket-link-ticket/references/create.md +++ b/skills/docket-link-ticket/references/create.md @@ -16,20 +16,27 @@ Loaded from `SKILL.md` when the person asks to create a ticket from a change. Th 3. **Refinement, only if needed.** When the check finds gaps, ask the person targeted questions about what is missing — nothing more. Write the answers through `change.groom` with `outcome: revise` and its owned sections, which works only while the change is `proposed`. `## Acceptance criteria` is one of those sections. Past `proposed`, build the ticket from the change as it stands: name what is missing and let the person decide whether to go ahead. Never invent scope or acceptance criteria, and never promote an unreviewed solution into a requirement. -4. **Ticket type.** Read the ticket types the project actually has through the connector (in Jira, `listJiraProjectIssueTypesMetadata`). `fix` maps to the bug type, `feat` to the story or feature type, and any other type to the task type. With no obvious match, ask the person. A tool without ticket types (Linear, Asana, Trello) gets none. +4. **Companion skill.** Before the first ticket-system call, look for a companion skill: a skill the person already has for this ticket project, from their company, their team, or themselves, that knows its title format, sprint, fields, labels, ticket type, and call limits. Read `tickets.companion_skill` from `diagnostic.config` at `effective.tickets.companion_skill.value`. + - **Set, and the skill is available in this session:** load it and follow it. Do not check whether it covers this project: the key is the person's choice. + - **Set, but the skill is not available:** say so in one line (`tickets.companion_skill names , which isn't available in this session`), then look for one as if the key were unset. + - **Unset:** look through the skills available in this session for one whose description says it handles this ticket project (`tickets.project`, or the project the person gave for this run). Its description decides which projects it covers. One match: load it and follow it. Several: ask the person which one. None: create the ticket without one, as the steps below describe. -5. **Export the body.** Invoke the `docket-export` skill as a **file request** — its rules are its own; do not restate or re-run them — **DIRECTED to:** export `change ` with `--output-path` set to a fresh directory from `mktemp -d "${TMPDIR:-/tmp}/docket-link-ticket.XXXXXX"`, return the path and, in a private repository, the before → after list, and post nothing. The export's H1 is the title; its body keeps Why, What changes, Acceptance criteria, Out of scope, and Open questions. + A companion skill decides the ticket type, only when it states one; the title format, filled with the change's title; the field values, such as the sprint, custom fields, labels, assignee, and priority, with any lookups it prescribes; anything it does after the ticket exists; and how the calls are made, such as one ticket-system call at a time. Docket always keeps the already-linked and broken-link stops, the readiness check, the description body, the person's approval of the draft, and recording the link only after the connector confirms the ticket. The description body is docket's export of the change plus the spec line or attachment; a companion skill's own description template never replaces it. When the companion skill asks for something that conflicts with one of those, docket's rule stands: say so in one line in the draft (` asks for ; docket keeps `) and do not do it. -6. **Spec, when the change has a `spec:`.** The spec is always included, labeled as the proposed approach, never as requirements. There is no separate question: the person's go on the draft is the only approval. - - **Shared repository:** resolve the `open` operation's argv from the capability catalog, never hard-coded, and run it as ` spec --print --json`. When `target_kind` is `url`, the body ends with one line, `Proposed approach: `. That is a branch link, not one pinned to a commit: the description is written once, so a pinned link would go stale after a later spec revision. - - **No URL, or a private repository:** A local path never goes into a ticket. When `target_kind` is `file`, or the repository is private, export the spec through `docket-export` as a file request (as in step 5) and attach it after the ticket exists (step 9). The body ends with `Proposed approach: see the attached `. +5. **Ticket type.** When the companion skill states a ticket type, use it. Otherwise read the ticket types the project actually has through the connector (in Jira, `listJiraProjectIssueTypesMetadata`). `fix` maps to the bug type, `feat` to the story or feature type, and any other type to the task type. With no obvious match, ask the person. A tool without ticket types (Linear, Asana, Trello) gets none. Never infer a type from the companion skill's examples or its defaults for other fields. -7. **Draft and approval.** Show the person, in one message, the title, the project, the mapped type, the body as it will be posted, the spec line or attachment name, and in a private repository the before → after list for the body and the spec. Create only on their go. A `docket-export` word-check hit stops the draft the way `docket-export` does: show the lines and post nothing until the person decides. +6. **Export the body.** Invoke the `docket-export` skill as a **file request** — its rules are its own; do not restate or re-run them — **DIRECTED to:** export `change ` with `--output-path` set to a fresh directory from `mktemp -d "${TMPDIR:-/tmp}/docket-link-ticket.XXXXXX"`, return the path and, in a private repository, the before → after list, and post nothing. The export's H1 is the title; its body keeps Why, What changes, Acceptance criteria, Out of scope, and Open questions. -8. **Create** the ticket through the connector in `tickets.project`: the summary is the export's H1, and the description is the rest. When the provider needs its own markup, convert formatting only, never words. The description is written once and never rewritten. +7. **Spec, when the change has a `spec:`.** The spec is always included, labeled as the proposed approach, never as requirements. There is no separate question: the person's go on the draft is the only approval. + - **Shared repository:** resolve the `open` operation's argv from the capability catalog, never hard-coded, and run it as ` spec --print --json`. When `target_kind` is `url`, the body ends with one line, `Proposed approach: `. That is a branch link, not one pinned to a commit: a branch link stays current after a later spec revision. + - **No URL, or a private repository:** A local path never goes into a ticket. When `target_kind` is `file`, or the repository is private, export the spec through `docket-export` as a file request (as in step 6) and attach it after the ticket exists (step 10). The body ends with `Proposed approach: see the attached `. -9. **Attach** the exported spec, when step 6 chose an attachment. Never assume a one-call upload, and never substitute a local path for an attachment. Some connectors attach in two steps: the Atlassian connector's `uploadAttachmentToJiraIssue` returns an upload command to run from the shell, and the file id it returns is then attached. If the upload fails, the ticket stays, since its description cannot be rewritten: report the failure and the exported file's path so the person can attach it by hand. +8. **Draft and approval.** Show the person, in one message, the title, the project, the mapped type, the body as it will be posted, the spec line or attachment name, and in a private repository the before → after list for the body and the spec. With a companion skill, the draft also names it and shows the formatted title, each field it sets (the type, the sprint, custom fields, labels, and any other field), and each action it will take after the ticket exists; nothing from the companion skill reaches the ticket unless the draft showed it, and any conflict line from step 4 appears here. Create only on their go. A `docket-export` word-check hit stops the draft the way `docket-export` does: show the lines and post nothing until the person decides. -10. **Record** the link with the `change.link-ticket` operation — the provider, the created ticket's id, and its URL — once the connector has confirmed the ticket was created. If recording fails, report the created ticket's URL and retry the link with a fresh `path` and `revision`; never create a second ticket. +9. **Create** the ticket through the connector in `tickets.project`: the summary is the export's H1, or the companion skill's title format with the export's H1 as its summary part, and the description is the rest. When the provider needs its own markup, convert formatting only, never words. Set every companion field the create call accepts. Then set the companion skill's remaining fields with edits, and run its after-creation actions, in the order and pace it prescribes. Once the connector confirms the ticket exists, a field or action that fails afterwards never stops the record: the ticket stays, the link is still recorded (step 11), and the report names each field or action that did not land, with what the person needs to finish it by hand. -11. **Report** the ticket link, its type, whether the spec was linked or attached, and any before → after list. +10. **Attach** the exported spec, when step 7 chose an attachment. Never assume a one-call upload, and never substitute a local path for an attachment. Some connectors attach in two steps: the Atlassian connector's `uploadAttachmentToJiraIssue` returns an upload command to run from the shell, and the file id it returns is then attached. If the upload fails, the ticket stays: report the failure and the exported file's path so the person can attach it by hand. + +11. **Record** the link with the `change.link-ticket` operation — the provider, the created ticket's id, and its URL — once the connector has confirmed the ticket was created. If recording fails, report the created ticket's URL and retry the link with a fresh `path` and `revision`; never create a second ticket. + +12. **Report** the ticket link, its type, whether the spec was linked or attached, the companion skill used, if any, each companion field or action that did not land, and any before → after list.