@skitterbyte/skitterspec-linear 1.0.0

package/assets/skills/spec/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: spec
+description: Create a new spec-driven-development spec. Grills the user to a clear, shared understanding of the requirement AND the proposed solution FIRST, then writes one concise, phased, test-included, change-logged spec into specs/backlog/. Use when the user wants to plan a feature, write a spec, capture a requirement, or says "/spec" or "spec this out".
+---
+
+# /spec — author a new spec
+
+Produce ONE concise spec in `specs/backlog/`. Do not start coding — this skill
+plans only. Implementation happens later via `/spec-go`.
+
+Lifecycle (the governing skills) — status in parentheses:
+`/spec` (Draft, backlog) → `/spec-ready` (Ready, still backlog) → `/spec-go`
+(In Progress, in-progress; implement phase 1) → `/spec-complete` (Complete) /
+`/spec-cancel` (Cancelled). See `.claude/rules/spec-planning.md`.
+
+## Phase A — reach a clear shared understanding (grill first)
+
+Interview the user until requirement AND proposed solution are unambiguous. Do
+not write the spec until this is resolved.
+
+- Break the problem into **distinctive areas** and work them in logical order,
+  resolving dependencies between decisions one at a time.
+- Ask **one question at a time**. For each, give your **recommended answer**.
+- If a question can be answered by **reading the codebase, read it** instead of
+  asking. Verify endpoints/models/files actually exist before relying on them.
+- Cover, at minimum, the areas that apply:
+  1. **Problem & why** — what's broken/missing, who feels it, why now.
+  2. **Scope & non-goals** — explicit out-of-scope items.
+  3. **Affected areas** — concrete files/modules/packages this touches.
+  4. **Proposed solution shape** — the chosen approach and the alternatives
+     rejected, with the reason (this becomes "Decisions").
+  5. **Data / API impact** — schema/model changes, new endpoints, and
+     **backward compatibility** (additive = safe; breaking = needs explicit
+     permission and coordination).
+  6. **Security & multi-tenancy** — authz, tenant scoping, untrusted input.
+  7. **Edge cases & failure modes.**
+  8. **Testing approach** — what proves each phase correct.
+  9. **Isolation stack** *(only when `specs/.core/env.config.json` exists)* — does
+     this spec touch the DB / stateful services (so its worktree needs a Docker
+     stack), or is a plain worktree enough? Default `worktree`; escalate to
+     `worktree + docker` only when it must. This sets the `> **Stack:**` header
+     that `/spec-go` acts on (it can be escalated later). Skip when isolation
+     isn't enabled — leave the default `worktree`.
+  10. **Open questions** — anything still undecided.
+
+Stop grilling when there are no unresolved branches that would change the spec.
+Briefly play back the agreed understanding before writing.
+
+## Phase B — write the spec
+
+This skill is for **features**. For bugs, use `/spec-bug` (test-first, red→green).
+
+- **Every spec is a folder** — never a bare file, even for a one-line change:
+  `specs/backlog/feat-<kebab-name>/`. Create it with `mkdir -p`.
+- The entry point is **always `00-overview.md`** — the index/dashboard for the
+  spec. It holds the header block, Problem, Decisions, Solution overview, the
+  **phase index** (a table linking to each phase file), Open questions, State
+  log, and Changelog. It does **not** hold the per-phase task lists.
+- **Each phase is its own file** — `01-<phase-slug>.md`, `02-<phase-slug>.md`, …
+  numbered in execution order; the slug is a short kebab description of the phase
+  goal (e.g. `01-data-model.md`, `02-api-endpoints.md`). The phase file holds
+  that phase's goal, its task checkboxes (tests included), and any phase-specific
+  notes. **Even a single-phase spec gets `01-….md`** — never lump phase tasks
+  into `00-overview.md`. This keeps each phase easy to dive into on its own.
+- Choose a short kebab-case name and **prefix it `feat-`** (the bug counterpart
+  uses `bug-`).
+
+Use this template (keep it **as concise as possible** — no filler, no restating
+the codebase, link rather than duplicate):
+
+```markdown
+# <Feature title>
+
+> **Type:** Feature
+> **Status:** Draft — not started
+> **Author:** <git user.name — `git config user.name`>
+> **Developer:** —
+> **Raised:** <YYYY-MM-DD (today)>
+> **Area:** <comma-separated files/modules this touches>
+> **Stack:** <worktree — or "worktree + docker" if it touches the DB/stateful
+> services; only acted on when isolation is enabled — see Phase A item 9>
+
+## Problem
+
+<2–6 sentences: what's wrong/missing and why it matters. No fluff.>
+
+## Decisions
+
+<Numbered, confirmed decisions from Phase A. Each: the choice + one-line why,
+and the rejected alternative when it sharpens the choice. This is the heart of
+the spec — be specific.>
+
+## Solution overview
+
+<Short prose or bullets describing the chosen shape end-to-end. Optional small
+schema/grammar/output snippets where they remove ambiguity.>
+
+## Phases
+
+Each phase lives in its own file in this folder. Status: ⬜ not started ·
+🔄 in progress · ✅ done.
+
+| # | Phase | Status | File |
+|---|-------|--------|------|
+| 1 | <goal> | ⬜ | [01-<phase-slug>.md](01-<phase-slug>.md) |
+| 2 | <goal> | ⬜ | [02-<phase-slug>.md](02-<phase-slug>.md) |
+
+## Open questions
+
+- [ ] <anything deferred — or "None">
+
+## State log
+
+| Date | Status | Folder | By |
+|------|--------|--------|----|
+| <YYYY-MM-DD> | Draft | backlog | <author> |
+
+## Changelog
+
+- <YYYY-MM-DD> — Spec created.
+```
+
+Then create **one file per phase** (`01-<phase-slug>.md`, `02-…`, in execution
+order). Each phase file uses this template:
+
+```markdown
+# Phase 1 — <goal> ⬜
+
+> Spec: [00-overview.md](00-overview.md) · **Status:** Not started
+
+**Goal:** <one line — what this phase delivers and how it's proven>.
+
+## Tasks
+
+- [ ] <clear, verb-first task>
+- [ ] <clear, verb-first task>
+- [ ] Add/extend tests covering this phase; run the project's typecheck and
+      test commands (see `.claude/rules/spec-planning.md`) — green before the
+      phase is done.
+
+## Notes
+
+<Phase-specific decisions, gotchas, or context. Delete if empty.>
+```
+
+Keep the `00-overview.md` phase index and the phase files in sync: the index row
+is the one-line summary + status; the phase file is the detail.
+
+The **State log** is the audit trail of folder/status transitions — every
+lifecycle skill (`/spec-ready`, `/spec-go`, `/spec-complete`, `/spec-cancel`)
+appends one row when it moves the spec. The **Changelog** is for decisions and
+course-corrections only — keep the two separate.
+
+Rules for the spec body:
+
+- **Every phase is independently shippable and ends with tests.** A phase is
+  not "done" until its tests are written and the suite is green. Bake a test
+  task into each phase — never a separate "testing phase" at the end only.
+- **Tasks are checkboxes** (`- [ ]`), clear, verb-first, and granular enough to
+  finish in one session. They live in the **phase files**, not the overview. Use
+  `⬜`/`🔄`/`✅` on each phase-file heading and mirror it in the `00-overview.md`
+  phase index.
+- **Honour project conventions** when writing tasks — reference the relevant
+  `.claude/rules/*.md` rather than re-explaining them.
+- **Changelog** is mandatory and lives in the spec. Every later decision or
+  course-correction gets a dated one-line entry. Convert relative dates to
+  absolute.
+- Keep it tight. If a section adds no information, delete it.
+
+## Phase C — finish up
+
+After writing, tell the user the path and that it's a `Draft` in `backlog`. Next
+step is `/spec-ready` once it's groomed, then `/spec-go` to start building.
+
+## Phase D — record the isolation stack (only if configured)
+
+**Only when `specs/.core/env.config.json` exists** (per-spec isolation is
+enabled), make sure the `> **Stack:**` header reflects the Phase A item 9
+decision — `worktree` (default) or `worktree + docker` when it touches the DB /
+stateful services. Nothing to provision now: `/spec-go` gives every in-progress
+spec its own worktree automatically, and brings up Docker only when the Stack
+says so. Mention the operator can escalate the Stack later (edit the header, or
+run `/spec-env <name>` to add Docker to an existing worktree). If
+`env.config.json` is absent, isolation is off — leave the default `worktree` and
+finish as above.
+
+## Phase E — link to a ticketing provider (only if one is installed)
+
+**Only when a ticketing provider is installed and configured** (it ships the
+`/spec-push` · `/spec-pull` · `/spec-status` skills and a provider config under
+`specs/.core/`). If none is present, skip this phase entirely — the spec stays
+local-only and `/spec` behaves exactly as above. When a provider is present, link
+the spec to the tracker after writing it, so status and discussion live there
+while the repo stays the co-authoring surface — follow the provider's link steps
+below (nothing to do here without one).
+
+**Only when `specs/.core/linear.config.json` exists** (Linear sync is opted in).
+If it's absent, skip this phase entirely — the spec stays local-only and `/spec`
+behaves exactly as above. When present, after writing the spec, link it to Linear
+so status and discussion live there while the repo stays the co-authoring surface:
+
+- **Discover the Linear MCP tools at runtime** (don't hardcode names). If Linear
+  isn't connected/authed, relay the fix and stop — leave the spec written and
+  local; the user can link it later with `/spec-push`. Do nothing destructive.
+- **Create the Project** from the spec: name from the title, description from the
+  `00-overview.md` plan. Attach the `initiativeId` from `linear.config.json` when
+  one is set.
+- **Create a Milestone per phase** (the `mapping.phases` target — milestones by
+  default), named from each phase file, in execution order.
+- **Add the frontmatter block** to `00-overview.md` (above the `#` title) so the
+  spec is linkable:
+
+  ```yaml
+  ---
+  linear_project_id: "<uuid>"
+  linear_identifier: "<TEAM-123>"
+  linear_url: "https://linear.app/..."
+  spec_status: "backlog"
+  last_synced_at: "<ISO-8601 now>"
+  ---
+  ```
+
+- **Write the initial base sidecar** so the spec starts clean and non-diverged —
+  run `skitterspec spec-sync normalize <spec>` to capture the local snapshot as the
+  committed base (`sync.baseDir`). `/spec-status` should report in-sync right after.
+- **Echo the branch name** from `branch.pattern` so the user knows what `/spec-go`
+  will fork.
+
+Leave committing to the existing convention (the user commits the spec as usual)
+and **never auto-push git** — Linear's own automation reacts to real branch/PR
+events later. Report the Linear project URL and the base as part of Phase C's
+finish-up message.

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

@@ -0,0 +1,110 @@
+---
+name: spec-bug
+description: Investigate a bug, capture it as a Bug-type spec, and drive it red→green. ALWAYS starts by reproducing the bug with a failing test, then writes the spec and works the test to green. Creates specs/in-progress/bug-<name>/00-overview.md. Use when the user reports a bug, says "/spec-bug", "investigate this bug", "this is broken — find and fix it", or pastes an error/stack trace.
+---
+
+# /spec-bug — investigate a bug, prove it with a failing test, fix it
+
+This is the **bug** counterpart to `/spec` (which is for **features**, plan-only).
+Unlike `/spec`, this skill is hands-on and test-first: it reproduces the bug as a
+**failing test (RED)**, captures a lean Bug spec, then works the test to **GREEN**.
+
+Spec type convention (see `.claude/rules/spec-planning.md`):
+- Bug specs are named `bug-<kebab-name>`; feature specs `feat-<kebab-name>`.
+- Every spec header carries `> **Type:** Bug` (or `Feature`).
+
+## 1. Reproduce & isolate (light investigation)
+
+Bugs are concrete — confirm, don't over-grill. Establish:
+
+- **Repro:** exact steps / input that triggers it. Ask only if you can't derive it.
+- **Expected vs actual:** what *should* happen vs what does.
+- **Scope & blast radius:** which module(s)/endpoint(s)/package; one tenant or all.
+- **Root cause:** read the code, trace it to `file:line`. Compare a working path
+  against the broken one (the bug usually lives in the differential). Do NOT
+  patch a symptom before you understand the cause.
+
+## 2. Write the failing test FIRST (RED) — mandatory
+
+Encode the **correct** (expected) behaviour as a test, then run it and confirm it
+**fails for the right reason**:
+
+- Put it where the suite already covers that area. Reuse existing test helpers /
+  factories; follow the project's test rules (see `.claude/rules/`). Never
+  hardcode dates — compute them relative to now.
+- Run it with the project's test command. Quote the red output. A test that
+  passes before the fix proves nothing — keep refining the assertion until it
+  genuinely captures the bug.
+
+## 3. Write the Bug spec
+
+Create the spec **folder** `specs/in-progress/bug-<kebab-name>/` with its entry
+point `00-overview.md` (every spec is a folder — never a bare file). A bug is
+usually a single-pass fix, so the `## Fix` block can live directly in
+`00-overview.md`. **If the fix needs phasing** (large/uncertain root cause),
+split it into phase files (`01-<slug>.md`, `02-…`) with a phase index in
+`00-overview.md`, exactly like a feature spec. It starts in `in-progress`
+because work is already underway. Keep it lean:
+
+```markdown
+# Bug: <short title>
+
+> **Type:** Bug
+> **Status:** In Progress — fixing (red test added)
+> **Author:** <git user.name — who reported/captured it>
+> **Developer:** <git user.name — you, since you're fixing it now>
+> **Raised:** <YYYY-MM-DD (today)>
+> **Area:** <files/modules>
+
+## Symptom
+
+<observed wrong behaviour + repro steps; paste the error/stack if any>
+
+## Root cause
+
+<the actual cause, at `file:line`. One paragraph — be specific.>
+
+## Failing test (red)
+
+<test name + path; what it asserts. How to run it. Paste the red failure line.>
+
+## Fix
+
+- [ ] <the minimal change that addresses the root cause, not the symptom>
+- [ ] Failing test now passes (GREEN); run the project's typecheck and test
+      commands — confirm no regressions.
+- [ ] <any follow-up hardening, or "None">
+
+## State log
+
+| Date | Status | Folder | By |
+|------|--------|--------|----|
+| <YYYY-MM-DD> | In Progress | in-progress | <developer> |
+
+## Changelog
+
+- <YYYY-MM-DD> — Bug reproduced; failing test added (red).
+```
+
+The **State log** is the folder/status audit trail; later transitions
+(`/spec-complete`, `/spec-cancel`) append a row. The **Changelog** is for the
+fix narrative and decisions — keep them separate.
+
+## 4. Drive to GREEN
+
+- Implement the **minimal, root-cause** fix. Match surrounding code; honour all
+  project rules (see `.claude/rules/`).
+- Re-run the failing test → it must pass. Then run the project's typecheck and
+  test commands to confirm no regressions. Quote results.
+- Tick the Fix tasks, add a Changelog line (`- <date> — Fixed: <one line>; test green`).
+
+If the root cause is large/uncertain and can't be fixed in one pass: keep the red
+test, split the fix into phase files (`01-<slug>.md` …) with a phase index in
+`00-overview.md`, and leave the spec in `in-progress` for `/spec-go` to continue.
+Say so explicitly — don't fake green.
+
+## 5. Report
+
+Summarise: root cause, the failing→passing test, the fix, and the full test
+result. The spec stays in `in-progress`; suggest `/spec-complete` to verify and
+archive it. Do **not** `git commit` unless the user asks.

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

@@ -0,0 +1,61 @@
+---
+name: spec-cancel
+description: Cancel a spec — capture the reason, record final progress, stamp the reason on the spec header, then move it into specs/cancelled/. Targets a spec by name (arg) or the spec currently in context. Use when the user says "/spec-cancel", "drop this spec", "we're not doing this spec", or "shelve <spec>".
+---
+
+# /spec-cancel — record, stamp a reason, archive a spec
+
+## 1. Identify the target spec
+
+- Use the name/path argument if given, else the spec **in context**. If unclear,
+  ask which spec.
+- Locate it under `specs/` (any bucket — `backlog/`, `in-progress/`, …). Entry point
+  is its `00-overview.md`; phases are separate files (`01-<slug>.md`, `02-…`) listed
+  in its phase index (legacy specs may be a bare `<name>.md`).
+
+## 2. Ask for the cancellation reason — required
+
+Ask the user **why** it's being cancelled (e.g. superseded by X, descoped, no
+longer needed, blocked indefinitely). Do not proceed without a reason; capture
+it verbatim/condensed for the header.
+
+## 3. Double-check and record progress
+
+- Read the overview and every phase file and reconcile task state with reality:
+  tick anything that was actually completed before cancelling so the record is
+  honest about what landed.
+- Note any partial/abandoned work so it isn't mistaken for unstarted.
+
+## 4. Stamp the spec
+
+Update the **Status** header in the entry point so the reason is visible at the
+top:
+
+```
+> **Status:** Cancelled (<YYYY-MM-DD>) — <reason>
+```
+
+Append a **State log** row:
+`| <YYYY-MM-DD> | Cancelled | cancelled | <git user.name> |`.
+
+Add a **Changelog** entry:
+`- <YYYY-MM-DD> — Cancelled: <reason>.`
+
+## 5. Move to cancelled
+
+`mkdir -p specs/cancelled` then **`git mv`** the file or folder:
+`git mv "specs/<bucket>/<name>" "specs/cancelled/<name>"` (preserve history;
+move the whole folder).
+
+## 6. Report
+
+Confirm the cancellation, the reason recorded, and the new location. Do **not**
+`git commit` unless the user asks.
+
+## 7. Offer teardown (opt-in, only if configured)
+
+**Only when `specs/.core/env.config.json` exists**, offer — don't force — to
+reclaim the cancelled spec's environment: "Want me to run `/spec-env-down
+<name>` to remove its worktree, stack, volumes, and free its slot?" It respects
+the teardown guards (won't destroy a dirty/unpushed worktree without `--force`).
+If `env.config.json` is absent, skip this entirely — behave exactly as before.

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

@@ -0,0 +1,87 @@
+---
+name: spec-complete
+description: Finish a spec — verify all phases are genuinely done, update progress, then move it into specs/complete/. Targets a spec by name (arg) or the spec currently in context. Use when the user says "/spec-complete", "mark this spec done", or "this spec is complete".
+---
+
+# /spec-complete — verify, finalise, archive a spec
+
+## 1. Identify the target spec
+
+- Use the name/path argument if given, else the spec **in context**. If unclear,
+  ask which spec.
+- Locate the spec folder under `specs/` (usually `specs/in-progress/`). Entry
+  point is its `00-overview.md`; phases are separate files (`01-<slug>.md`, `02-…`)
+  listed in its phase index (legacy specs may be a bare `<name>.md`).
+
+## 2. Double-check progress — don't rubber-stamp
+
+Before marking complete, confirm the work is actually finished:
+
+- Read every phase file. For each **unchecked** task, check whether it is in fact
+  done in the code — tick it (`- [x]`) if so, or surface it if not.
+- Run the project's typecheck and test commands. The suite must be **green** to
+  call a spec complete.
+- For a **Bug** spec (`Type: Bug`), confirm the originally-failing test named in
+  the spec now passes — that test is the proof the bug is fixed.
+- If genuinely incomplete work remains, **stop and tell the user** rather than
+  forcing completion. Offer to finish it (`/spec-go`) or to complete with the
+  remaining items explicitly listed as deferred.
+
+## 3. Update the spec
+
+- Tick all completed tasks in the phase files; flip every finished phase-file
+  heading **and** every row in the `00-overview.md` phase index to `✅`.
+- Set the **Status** header in the entry point:
+  `> **Status:** Complete (<YYYY-MM-DD>)`.
+- Append a **State log** row:
+  `| <YYYY-MM-DD> | Complete | complete | <git user.name> |`.
+- Add a **Changelog** entry:
+  `- <YYYY-MM-DD> — Completed; all phases done, tests green.`
+  (Note any consciously-deferred items here too.)
+
+## 4. Move to complete
+
+`mkdir -p specs/complete` then **`git mv`** the file or folder:
+`git mv "specs/in-progress/<name>" "specs/complete/<name>"` (preserve history;
+move the whole folder). The `specs/complete/` folder is the record of finished
+specs — `git log`/the per-spec State log give the completion order.
+
+## 5. Report
+
+Confirm the move, the final test result, and list anything deferred. Do **not**
+`git commit` unless the user asks.
+
+## 6. Integrate onto the base branch (opt-in, only if isolated)
+
+**Only when `specs/.core/env.config.json` exists and the spec is on a worktree**
+(it was provisioned by `/spec-go`). Otherwise skip this entirely — a non-isolated
+spec has nothing to land, and `/spec-complete` behaves exactly as before. When it
+applies, offer to land the finished branch on the base branch so the work reaches
+`main` (or your configured `baseBranch`) in one flow:
+
+1. **Require a clean worktree.** The completion edits (status flip, the
+   `git mv` to `complete/`) must be committed first — integrate refuses a dirty
+   tree. If it's dirty, offer `/commit` and **stop**; don't auto-commit.
+2. **Plan + execute.** Run `skitterspec spec-env integrate <name>` and run the
+   printed commands **in order**:
+   - `git -C <worktree> rebase <base>` — replay the branch onto base.
+   - `git -C <mainRepoPath> merge --ff-only <branch>` — fast-forward base.
+   On a **rebase conflict** (non-zero exit), run
+   `git -C <worktree> rebase --abort`, relay the conflict, and **stop** — leave it
+   to the user; do not offer teardown.
+   On a **no-op** ("already landed"), just say so and continue.
+3. **Re-test on base.** Run the project's test command from the primary checkout;
+   it must be **green** before you call the landing done.
+4. **Report** the landing (base branch, fast-forward result). It **never pushes** —
+   mention the user can `git push` the base branch themselves.
+
+## 7. Offer teardown (opt-in, only if configured)
+
+**Only when `specs/.core/env.config.json` exists**, offer — don't force — to
+reclaim the finished spec's environment: "Want me to run `/spec-env-down <name>`
+to remove its worktree, delete its branch, stack, volumes, and free its slot?"
+Post-integrate the branch is merged into base, so teardown needs **no `--force`**
+and deletes the branch (`git branch -d`) as part of the plan. It still respects
+the guards (won't destroy a dirty or unpushed-and-unmerged worktree without
+`--force`). If `env.config.json` is absent, skip this entirely — behave exactly as
+before.

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

@@ -0,0 +1,63 @@
+---
+name: spec-env
+description: Provision an isolated environment for a spec — a git worktree on its own branch + a namespaced Docker stack (isolated containers/networks/volumes + a reserved port block), plus an optional editor/terminal opener. Runs `skitterspec spec-env up` and executes the printed git/docker/open commands. Opt-in — needs specs/.core/env.config.json. Use when the user says "/spec-env", "spin up an environment for <spec>", "give this spec its own worktree/stack", or "isolate <spec>".
+---
+
+# /spec-env — provision an isolated environment for a spec
+
+Give an in-progress spec its own **git worktree** (a sibling directory on its own
+branch, no stashing) + a **namespaced Docker stack** (`COMPOSE_PROJECT_NAME`
+isolates containers/networks/volumes; `PORT_OFFSET` reserves a port block), so N
+specs run side by side and `main` stays clean. An optional `open.command` then
+opens the worktree however you like.
+
+This skill is **opt-in**: it only works when `specs/.core/env.config.json` exists
+(copy `env.config.json.example` to adopt it). If it's absent, tell the user how
+to enable it and stop.
+
+## 1. Identify the target spec
+
+- Use the spec named as an argument, else the spec **currently in context**. If
+  neither is clear, ask which spec.
+
+## 2. Plan the environment
+
+Run the engine — it allocates the slot (idempotent), persists the registry, and
+**prints** the plan (worktree path, branch, project name, port block, the exact
+commands, the `.env` contents, and the opener):
+
+```
+skitterspec spec-env up <spec>
+```
+
+If it reports the feature isn't enabled, relay that and stop — do not hand-roll a
+worktree/stack.
+
+## 3. Execute the printed side effects
+
+Run the printed commands **in order**, exactly as printed:
+
+1. **`git worktree add …`** — creates the sibling worktree on its branch. It is a
+   **sibling** of this checkout, **never nested** inside it. If the worktree
+   already exists, the engine prints the *attach* form (no `-b`) — do not clobber
+   an existing worktree/branch.
+2. **Write the `.env`** — write the printed `.env` contents into the new
+   worktree's env file (default `.env`). Do this *after* the worktree exists.
+3. **`docker compose … up -d`** — only printed when Docker is enabled. Brings the
+   namespaced stack up in the spec's reserved port block.
+4. **Opener** — if an `open.command` line was printed, run it (e.g. opens the
+   worktree in your editor/terminal). Skipped silently when unset.
+5. **Trust the worktree root for this session** — the engine already wrote the
+   printed `trusted:` root into `.claude/settings.local.json` (gitignored, so it
+   persists for future sessions). That file likely won't hot-reload mid-session,
+   so also run `/add-dir <trusted root>` now to lift `Edit`/`Write` prompts for
+   the **current** session. (If the engine printed a `trusted: ! …` warning,
+   `settings.local.json` isn't valid JSON — fix it, then re-run.)
+
+## 4. Report
+
+Echo the summary: worktree path, branch, project name, the allocated slot + port
+block, and whether the stack was brought up. **Idempotent** — re-running attaches
+to the existing slot/worktree and never reallocates.
+
+Tear down later with `/spec-env-down <spec>`.

package/assets/skills/spec-env-down/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: spec-env-down
+description: Tear down a spec's isolated environment — stop and remove its namespaced Docker stack (optionally backing up + dropping volumes), remove its git worktree, and free its slot. Guards refuse teardown on a dirty or unpushed worktree unless --force. Runs `skitterspec spec-env down` and executes the printed commands. Opt-in — needs specs/.core/env.config.json. Use when the user says "/spec-env-down", "tear down <spec>'s environment", "clean up the worktree/stack for <spec>", or "reclaim <spec>'s slot".
+---
+
+# /spec-env-down — tear down a spec's isolated environment
+
+Reverse `/spec-env`: stop + remove the spec's Docker stack, remove its git
+worktree, and free its slot so the ports/slot are reclaimed. **Volumes are the
+only destructive part** — dropped by default (to reclaim disk) unless
+`--keep-volumes`, and always backed up first when `docker.backupCommand` is set.
+
+Opt-in: only works when `specs/.core/env.config.json` exists. If absent, say so
+and stop.
+
+## 1. Identify the target spec
+
+- Use the spec named as an argument, else the spec **currently in context**. If
+  neither is clear, ask which spec.
+
+## 2. Plan the teardown
+
+Run the engine — it checks the guards, frees the slot, and **prints** the plan:
+
+```
+skitterspec spec-env down <spec> [--keep-volumes] [--force]
+```
+
+- **`--keep-volumes`** — keep the stack's data (plain `down`, no backup, no drop).
+- **`--force`** — override the guards below.
+
+## 3. Handle a guard block
+
+If the CLI reports **blocked** (the worktree has uncommitted changes, or unpushed
+commits that aren't yet merged into the base branch), **relay the reason and
+stop** — do not destroy unreviewed work. Offer the user `--force` (and suggest
+committing/pushing first). Only re-run with `--force` when the user explicitly
+asks. **A branch already merged into the base needs no `--force`** — the unpushed
+guard treats "landed on base" as safe, so a completed spec (post-`/spec-complete`
+integrate) tears down cleanly even with no remote.
+
+## 4. Execute the printed side effects
+
+When not blocked, run the printed commands **in order**, exactly as printed:
+
+1. **Backup** (only when a `docker.backupCommand` is configured and volumes are
+   being dropped) — writes a dump under `.spec-env/backups/` before anything is
+   destroyed.
+2. **`docker compose … down`** — with `--volumes` unless `--keep-volumes`.
+3. **`git worktree remove …`** — removes the sibling worktree.
+4. **`git branch -d <branch>`** — deletes the spec's branch (freed by the worktree
+   removal above). It's `-d` (merged-only), never `-D`: if it reports the branch
+   isn't fully merged, **relay that and stop** — don't `-D` it. That only happens
+   on a `--force` teardown of unmerged work; the user can delete it by hand if
+   they're sure.
+
+The slot is already freed by the CLI.
+
+## 5. Report
+
+Confirm what happened: worktree removed, branch deleted, containers down, volumes
+**dropped|kept**, slot freed, and the backup path (if any). If a `git branch -d`
+was refused (unmerged), say so. If the spec wasn't provisioned / was already torn
+down, the CLI reports a clean **no-op** — relay that; it's not an error.