@skitterbyte/skitterspec-linear 11.0.0 → 13.0.0

package/assets/skills/spec-claim/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: spec-claim
+description: Take ownership of a spec, hand it back, or give it to a teammate — the spec records who is building it and its Linear issue is assigned to them. Opt-in — needs specs/.core/linear.config.json with assignee in sync.fieldOwnership. Use when the user says "/spec-claim", "claim this spec", "take ownership of this", "I'm picking this up", "hand this back", or "assign this spec to someone".
+disable-model-invocation: true
+---
+
+# /spec-claim — take a spec, hand it back, or hand it over
+
+> Stay silent while this runs — speak only to ask something you cannot answer
+> yourself, or to report a failure at the moment it happens. Read
+> `.claude/rules/spec-reports.md` before reporting; it defines the block this
+> skill ends with.
+
+Ownership lives in the repo: the spec's frontmatter records who is building it,
+and the push that follows tells Linear. This skill is how that record changes
+after `/spec-start` has set it — a hand-off mid-flight, a spec picked up from
+someone who moved on, or work a lead is distributing.
+
+**Opt-in.** Needs `specs/.core/linear.config.json` *and* `assignee` in its
+`sync.fieldOwnership`. If either is missing, say which one and stop — without the
+field the stamp would sit in the file doing nothing.
+
+## 1. Identify the target spec
+
+The argument, else the spec in flight for this session, else ask. Unlike
+`/spec-next` this does not refuse a spec you are not standing in: reassigning a
+colleague's spec from your own checkout is a normal thing to want, and it writes
+no code.
+
+## 2. Work out the mode
+
+| Invocation | Mode |
+|------------|------|
+| `/spec-claim [<spec>]` | **take** — you are building it |
+| `/spec-claim [<spec>] --release` | **release** — nobody is |
+| `/spec-claim [<spec>] --to <name-or-email>` | **hand over** — they are |
+
+### take
+
+1. `skitterspec spec-sync whoami --json`. If it answers, use that `id`/`name`.
+   If it reports `transport = mcp`, call the user-read tool with `me` and cache
+   the answer with `whoami --set <id> --name "<name>"`.
+2. **If the spec already records someone else, confirm before taking it** —
+   name them and say what will happen. Taking a colleague's spec by accident is
+   the one mistake here worth a round trip; every other path is reversible with
+   a second `/spec-claim`.
+3. Stamp it: `skitterspec spec-sync assign <spec> --to <id> --name "<name>"`.
+4. Set `> **Developer:**` to **`git config user.name`** — not the Linear display
+   name. You are taking this spec yourself, so the header should name you the
+   way `Author:`, the **State log** and your commits already do. The Linear name
+   belongs to the *assignment*, which step 3 just recorded; the two answer
+   different questions.
+
+### release
+
+`skitterspec spec-sync assign <spec> --release`. This removes the stamp and, on
+the next push, unassigns the Linear issue.
+
+**It does not clear `> **Developer:**`** — that header records who *actioned*
+the work, which outlives who is currently holding it. If nobody will pick the
+spec up, `/spec-cancel` is the honest move; releasing only says "not me, for
+now".
+
+### hand over (`--to`)
+
+1. **Resolve the person through a search, never a typed id.** Run
+   `skitterspec spec-sync users <name-or-email>` (or the user-list tool on MCP)
+   and **confirm the match** before writing. This is the one path where the repo
+   writes into somebody else's Linear inbox, so a mistyped id would assign a
+   stranger and nothing downstream would notice.
+2. On several matches, show them and let the user pick. On none, say so and
+   stop — do not fall back to the raw argument as an id.
+3. Stamp it with the resolved id and display name.
+4. Set `> **Developer:**` to that person's **Linear display name**.
+
+   This is the **one** place the tracker's name reaches the header, and the
+   exception is the whole reason it exists: there is no `git config user.name`
+   for somebody else's machine, so without it the header would go on crediting
+   you for work you just gave away. Everywhere else — `/spec-start`, the
+   `/spec-next` backfill, and taking a spec above — the git name wins, because
+   there the person *is* you and the rest of the spec already names you that way.
+
+## 3. Record it in the spec
+
+Add a dated line to the **Changelog** in `00-overview.md` — who it moved to (or
+from), and why if the user said. Ownership is a course-correction, not a
+lifecycle transition, so it belongs there and **not** in the State log.
+
+## 4. Push
+
+Run `/spec-push`. The stamp is repo state, and the mirror catches up like any
+other edit.
+
+**If the push fails, the claim still stands.** Say so and stop: the repo is
+correct, the mirror is disposable, and the next push repairs it. Do not roll the
+stamp back — that would throw away the one durable half of the change.
+
+## 5. Report
+
+End with the block defined in `.claude/rules/spec-reports.md`. That file carries
+the shape; this section carries only what is specific here.
+
+**Verdicts**
+
+- `✅` — the spec records the new owner and Linear agrees.
+- `⚠️` — the spec records it; Linear does not yet. The spec file is the record
+  and the ticket is the mirror, so this is a lag rather than a conflict — say
+  which way round it is.
+- `⏸` — nothing to claim, or no provider configured.
+
+**Fields:** `Tracker` · `Follow-ups` · `Next`
+
+`Tracker` is who owns it now and whether Linear agrees yet — the whole answer,
+in one row.

package/assets/skills/spec-complete/SKILL.md

@@ -5,6 +5,11 @@ description: Finish a spec — verify all phases are genuinely done, update prog
 
 # /spec-complete — verify, finalise, archive a spec
 
+> Stay silent while this runs — speak only to ask something you cannot answer
+> yourself, or to report a failure at the moment it happens. Read
+> `.claude/rules/spec-reports.md` before reporting; it defines the block this
+> skill ends with.
+
 ## 1. Identify the target spec
 
 - Use the name/path argument if given, else the spec **in context**. If unclear,
@@ -34,6 +39,23 @@ Before marking complete, confirm the work is actually finished:
   is its own, and step 4 commits that.
 
 
+### Release gating (only when configured)
+
+**Only when `specs/.core/gating.config.json` exists.** Run
+`skitterspec gating check <spec>` and report what it says. This is the last point
+at which the question can still be answered cheaply, which is exactly why it is
+asked here — a spec that reaches `Complete` with no decision recorded is the gap
+the feature exists to close.
+
+**Never refuse to complete over it.** Say plainly that no decision was recorded,
+offer to record one now, and finish either way. The work is done; withholding the
+status flip would punish the wrong thing.
+
+**This check is advisory.** It reports; it never refuses, and nothing below is
+conditional on it. A spec written before the project adopted gating has no header
+and is not broken — turning this into a gate would accuse the very specs the
+feature was designed not to disturb.
+
 ## 3. Update the spec
 
 - Tick all completed tasks in the phase files; flip every finished phase-file
@@ -73,6 +95,12 @@ Linear API key is set (see `apply.transport` in `linear.config.md`).
   Do not roll anything back, and do not stop to ask.
 - **Say what happened** in the skill's report: mirror updated, skipped as
   unlinked, or failed with the reason.
+- **There is no unassign step, and that is not an omission.** With `assignee` in
+  `sync.fieldOwnership`, the projection derives it from the spec's lifecycle
+  bucket — so moving the folder to `complete`/`cancelled` is *itself* what
+  releases the issue, and the push above carries it like any other field. The
+  `linear_assignee_id` stamp and the `> **Developer:**` header both stay put:
+  they record who actioned the work, which outlives who is holding it.
 
 ### Why it sits here
 
@@ -83,25 +111,74 @@ In `/spec-complete` and `/spec-cancel` this step is deliberately pinned
   its folder bucket. Push while the folder is still in `in-progress/` and the
   issue is set to the state the spec is *leaving*.
 - **Before the commit**, because the push stamps ids into the spec and writes a
-  snapshot under `specs/.core/`. The `git add specs/` that follows sweeps both up
-  with the status change; push after it instead and those files are left
+  snapshot under `specs/.core/`. Push after the commit instead and both are left
   uncommitted, which makes `spec-env integrate` refuse to land the branch.
 
+The snapshot is reached **by name**, not by breadth. It is a declared
+`spec.companionPaths` entry (`specs/.core/linear-base/{identifier}.base.json`),
+so `spec-env stage` returns it among this spec's owned paths and the commit below
+names it. This is why the commit no longer stages `specs/` wholesale: the one
+file outside the spec's folder that had to be swept up is addressable, so the
+breadth bought nothing and cost another session's work.
+
 Then **commit the completion edits** — steps 3–4 are this skill's own output, so
-it finishes its own work rather than handing you a dirty tree:
+it finishes its own work rather than handing you a dirty tree. Ask the engine
+which paths are this spec's, then stage and commit **exactly those**:
 
 ```
-git add specs/ && git commit -m "chore(spec): complete <name>"
+skitterspec spec-env stage <name>     # lists them; --json to consume
+git add -- <the owned paths>
+git commit -m "chore(spec): complete <name>" -- <the owned paths>
 ```
 
-Step 2 established the tree was otherwise clean, so this commits exactly the
-status flip and the move — nothing of yours rides along. **This is what lets step
-6 land:** `integrate` refuses a dirty worktree, so without committing here the
-skill would block on the very edits it just made. Do not `git push`.
+**Never `git add specs/`.** That stages a *directory*, so a spec another
+session is part-way through writing lands in this commit under this spec's
+ticket. The `--` on the **commit** is the other half: a checkout has one
+`.git/index`, shared by every session standing in it, so a bare `git commit`
+takes whatever else is staged there however carefully you staged your own.
+`.claude/rules/spec-planning.md` carries the full account.
+
+So this commits exactly the status flip and the move, and nothing of yours — or
+of anyone else's — rides along.
+**This is what lets step 6 land:** `integrate` refuses a dirty worktree, so
+without committing here the skill would block on the very edits it just made.
+Do not `git push`.
 
 ## 5. Report
 
-Confirm the move, the commit, the final test result, and list anything deferred.
+**The block is emitted when the run ends, not where this section sits.** The
+sections below run after it, so their outcome belongs in the block — write it
+once, at the end, with what actually happened.
+
+End with the block defined in `.claude/rules/spec-reports.md`. That file carries
+the shape; this section carries only what is specific here.
+
+**Verdicts**
+
+- `✅` — every phase done, tests green, landed, torn down.
+- `⚠️` — finished, with something worth knowing: teardown declined, a tracker
+  refresh that failed, a hotfix tag still waiting to be pushed.
+- `❌` — it acted and stopped part-way — a conflicted rebase, a failed
+  cherry-pick, a red base after landing. Say what state the repo is in and quote
+  the failure; there is a mess to clear and the reader needs to know where.
+- `⏸` — phases are unfinished, tests are red, or the tree is dirty. Nothing
+  moved.
+
+**Fields:** `Tracker` · `Spec` · `Tests` · `Landed` · `Worktree` ·
+`Follow-ups` · `Next`
+
+**Report this spec and no other.** A completion is the moment it is most
+tempting to survey what is left — what else is in flight, what is in the
+backlog, which worktrees are still standing — and it is the moment it helps
+least: the reader has just finished something and cannot tell whether a line
+about another spec followed from it. `Next` is one action for this spec, and
+`/spec-list` is where the wider picture lives if they want it.
+
+`Landed` says how, because the two ways differ: a fast-forward names the base
+and the commit, a hotfix names the deploy tag and the `main` cherry-pick — and
+a deploy tag that has not been pushed is a `⚠️`, not a `✅`. `Worktree` says
+what was reclaimed, including any orphaned volumes swept, or that teardown was
+declined and the worktree still stands.
 
 ## 6. Land the branch (opt-in, only if isolated)
 
@@ -203,9 +280,23 @@ worktree and branch are being kept, and go straight to sub-step 4. Mention
    canonical ports go back to the primary checkout.
 2. **Stop its host dev servers:** `skitterspec spec-env dev down <name>` (a
    no-op when none are running / configured).
-**Standing in the worktree? Leave it before you tear it down.** If this
-session's cwd is inside the spec's own worktree, `cd` to the primary checkout
-**first**, then run the teardown commands.
+**Standing in the worktree? Leave it before you tear it down.** If this session's
+cwd is inside the spec's own worktree — the normal case in `worktree` mode, since
+`/spec-start` moves you there — get out **first**, then run the teardown commands.
+One instruction covers it:
+
+```
+cd <primary checkout>
+```
+
+That is the whole mechanism, and it does not matter how you got in: the session
+was moved by a `cd` and it leaves by one. There is no tool to call here, and none
+should be reached for — the move in is a plain `cd` precisely because a tool that
+asks for approval is unusable on a phone.
+
+**`spec-env down` stays the single thing that deletes a worktree.** The plan
+below is the only deleter, because a second one is how the teardown guards get
+bypassed.
 
 Not because git refuses — it does not. `git worktree remove` **succeeds** on the
 tree you are standing in, and that is the problem: the directory vanishes under
@@ -224,16 +315,26 @@ only ordering that survives.
    worktree without `--force`), so if it *does* refuse, relay that and stop
    rather than reaching for `--force`.
 
-   **If the plan prints a `remote branch — confirm with the user first:`
-   section, ask before running it.** `/spec-start` pushed this branch when it
-   provisioned, so the remote copy outlives teardown unless someone deletes it.
-   The planner only ever offers this for a branch that has **landed**, so say so
-   plainly when you ask — the commits are on the base branch (or captured by the
-   deploy tag), so deleting the remote branch loses nothing. On a yes, run the
-   printed `git push <remote> --delete <branch>`; on a no, leave it and say the
-   remote branch is still there. Never fold it into the `run these:` batch — a
-   project that wants it unattended sets `teardown.deleteRemoteBranch: "always"`
-   in `env.config.json`, and then it appears in `run these:` instead of here.
+   **The unpushed half of that guard cannot fire here, by construction.**
+   Step 6 landed the branch, so `merged` is true and `planDown` skips the check
+   entirely (`env/teardown.js`) — completing a spec never meets it, however the
+   branch was or was not published. `/spec-cancel` is where it does fire, because
+   a cancelled spec is unlanded and its worktree really is the only copy; the
+   publish-or-`--force` path therefore lives in that skill and this one needs no
+   equivalent. A refusal reaching this step is about a **dirty tree** instead,
+   which means something wrote into the worktree after the landing — read it,
+   don't force it.
+
+   **If the plan prints a `remote branch — confirm with the user first:` section, ask before running it.**
+   Nothing published this branch for you, so a remote copy exists only because
+   you pushed it by hand — and it outlives teardown unless someone deletes it. The planner only ever offers
+   this for a branch that has **landed**, so say so plainly when you ask — the
+   commits are on the base branch (or captured by the deploy tag), so deleting
+   the remote branch loses nothing. On a yes, run the printed
+   `git push <remote> --delete <branch>`; on a no, leave it and say the remote
+   branch is still there. Never fold it into the `run these:` batch — a project
+   that wants it unattended sets `teardown.deleteRemoteBranch: "always"` in
+   `env.config.json`, and then it appears in `run these:` instead of here.
 4. **Reap orphaned test-DB volumes:** run `skitterspec spec-env prune`. It lists
    Docker volumes in the repo namespace that belong to **no live spec** (no
    worktree) — leftovers from declined/aborted teardowns, manual