@skitterbyte/skitterspec 0.1.0 → 1.0.1

package/README.md

@@ -38,8 +38,6 @@ never clobbers customised files. It writes:
 .claude/rules/spec-planning.md  # governing rule (the single source of truth)
 .claude/rules/commit-messages.md # commit message + release-note grammar
 specs/{.core,backlog,in-progress,complete,cancelled}/
-specs/backlog/00-index.md            # live backlog view (skill-maintained)
-specs/complete/00-index.md           # append-only completion log
 CLAUDE.md                       # adds a "## Spec workflow" section (created if absent)
 ```
 
@@ -60,6 +58,7 @@ npx @skitterbyte/skitterspec init ./path/to/project   # target a dir (default: c
 npx @skitterbyte/skitterspec init --yes               # accept defaults, skip the prompts
 npx @skitterbyte/skitterspec init --force             # overwrite existing skill/rule/script files
 npx @skitterbyte/skitterspec init --no-claude-md      # don't touch CLAUDE.md
+npx @skitterbyte/skitterspec init --isolation         # adopt per-spec isolation (worktree per spec)
 npx @skitterbyte/skitterspec update                   # re-copy skills + rule + scripts, leave specs/ + config alone
 ```
 
@@ -135,6 +134,102 @@ phase file with its status (`⬜`/`🔄`/`✅`). **Each phase is its own file**
 easy to dive into one phase without wading through the whole spec. The lifecycle
 skills keep the index and phase files in sync.
 
+## Per-spec isolation — worktree by default, Docker on demand
+
+Work several specs in parallel without them stepping on each other. **Adopt it
+once** with `npx @skitterbyte/skitterspec init --isolation` (or copy
+`specs/.core/env.config.json.example` → `specs/.core/env.config.json`; every field
+is documented in `specs/.core/env.config.md`). While the config is absent the
+feature is simply unused.
+
+Once adopted it's the **default policy**, not a per-spec chore:
+
+- **Worktree — automatic for every in-progress spec.** `/spec-go` gives each spec
+  its own sibling git worktree on its own branch, so you never stash or rebuild to
+  switch specs and `main` stays free for hotfixes. All housekeeping (the
+  backlog→in-progress move, header edits, the code) happens on that branch and
+  lands in one PR; `main` changes only when it merges.
+- **Docker — a per-spec escalation.** `/spec` records `> **Stack:** worktree`
+  (default) or `worktree + docker` when the spec touches the DB / stateful
+  services. Only an escalated spec gets a **namespaced stack** — a per-spec
+  `COMPOSE_PROJECT_NAME` isolates containers, networks, and **named volumes**, and
+  a `PORT_OFFSET` reserves a distinct port block, so N stacks run at once with no
+  clashes. A worktree-only spec takes **no** slot, port block, or `.env`.
+- an optional **opener** — a single, editor/terminal-agnostic `open.command`
+  (e.g. `code {worktreePath}`, a `tmux` command, or a `warp://` deeplink).
+
+The machine-local slot registry and volume backups live under `/.spec-env/`
+(gitignored). `docker.enabled` in the config is the project **master switch**
+("is Docker escalation available?"), not "always run Docker".
+
+`/spec-env` · `/spec-env-down` remain the **manual engine** behind the automation
+— use them to escalate Docker onto an existing worktree, re-attach, or tear down:
+
+```
+/spec-env <spec>        # worktree (+ stack iff Stack: worktree + docker) + opener
+                        #   (idempotent; re-run attaches)
+/spec-env-down <spec>   # stop stack, drop volumes (backed up first), remove worktree,
+                        #   free the slot. Guards refuse a dirty/unpushed worktree
+                        #   unless --force; --keep-volumes preserves data.
+```
+
+Your `docker-compose.yml` must reference `${PORT_OFFSET}` on each published port
+so services land in the spec's reserved block. Two adoption modes:
+
+- **Standalone** (`linkLinear: false`) — plain `{type}/{slug}` branch names; pure
+  worktree + Docker + opener. No Linear needed.
+- **Linear-linked** (`linkLinear: true` + `specs/.core/linear.config.json`) —
+  branch names follow Linear's pattern so pushing fires Linear's GitHub
+  automation.
+
+`/spec-complete` and `/spec-cancel` will *offer* to tear down when the config is
+present — never forced.
+
+## Linear hybrid sync — git-like `/spec-status` · `/spec-pull` · `/spec-push`
+
+Let **Linear own status and discussion** while the repo stays the **co-authoring
+surface for spec content**. The sync is bidirectional but git-like: explicit
+commands, a committed **base sidecar** for three-way merge, and no blind
+overwrites. It's **opt-in** — everything below is inert until
+`specs/.core/linear.config.json` exists (copy `linear.config.json.example` and
+fill in your team / initiative IDs; every field is documented in
+`specs/.core/linear.config.md`). Without it, `/spec`, `/spec-go`, and the CLI
+behave exactly as before.
+
+**Mapping** (config-driven): a spec folder → Linear **Project**; each phase
+(`01-…`, `02-…`) → a **Milestone**; tasks → **Issues**; an optional **Initiative**
+groups specs. When linked, `/spec` creates the project + a milestone per phase and
+writes the linking frontmatter into `00-overview.md`.
+
+**The git-like lifecycle:**
+
+```
+/spec-status          # read-only — per-field divergence (local-only / remote-only
+                      #   / conflict / in-sync). Changes nothing.
+/spec-pull [--force]  # Linear → repo. Applies remote-only fields; refuses to
+                      #   clobber a conflicting local edit unless --force.
+   …refine the spec locally (the repo is the co-authoring surface)…
+/spec-push [--force]  # repo → Linear. Ownership-respecting, concurrency-checked;
+                      #   refuses if Linear moved since base unless --force.
+```
+
+**Field ownership** collapses conflicts: each field is `both` (co-authored,
+can conflict), `pull` (Linear owns it — e.g. status/priority/labels), or `push`
+(the repo owns it). Only a `both` field that moved on **both** sides is a real
+conflict. `--force` never destroys blindly — it backs up the losing side into
+`sync.backupDir` (a local reflog) first, then wins. After any successful
+pull/push the engine **rewrites the base** so the next compare starts clean.
+
+`/spec-go` on a linked spec runs `/spec-pull` first, so you always build against
+the current shared state. **Base sidecars** (`sync.baseDir`, default
+`specs/.core/linear-base/`) are **committed** — each worktree carries its own
+base. **Backups** (`sync.backupDir`, default `specs/.core/linear-backups/`) are
+local recovery and **gitignored**.
+
+This supersedes the earlier one-way `/spec-from-issue` intake design (cancelled):
+because both sides author, the sync had to be bidirectional and three-way, not a
+blind import.
+
 ## After install — tailor it
 
 The shipped skills are **stack-agnostic**. They say things like "run the

package/assets/claude-md-section.md

@@ -32,3 +32,14 @@ tests, then write a conventional-commit message with a `Release-Note:` footer
 for user-visible changes (grammar in `.claude/rules/commit-messages.md`). If the
 release tooling is enabled (`skitterspec.config.json`), those footers feed the
 generated `CHANGELOG.md`/`RELEASES.md` at `npm version`.
+
+**Per-spec isolation (adopt once, then default):** with isolation adopted
+(`skitterspec init --isolation`, or `specs/.core/env.config.json` present),
+**`/spec-go`** gives every in-progress spec its own git worktree automatically —
+parallel specs, no stashing, `main` left free. Docker is a **per-spec
+escalation**: `/spec` sets `> **Stack:** worktree` (default) or `worktree +
+docker` when the spec touches the DB / stateful services, and only the latter
+gets a namespaced stack (isolated volumes + reserved port block). **`/spec-env`**
+· **`/spec-env-down`** are the manual engine (escalate Docker later, re-attach,
+tear down — guarding dirty/unpushed work, backing up volumes first). Independent
+of lifecycle status; inactive when `env.config.json` is absent.

package/assets/core/env.config.json.example

@@ -0,0 +1,24 @@
+{
+  "worktree": {
+    "root": "../{repo}-wt",
+    "folderPattern": "{slug}"
+  },
+  "docker": {
+    "enabled": true,
+    "composeFile": "docker-compose.yml",
+    "projectNamePattern": "{repoSlug}_{slug}",
+    "portBase": 3000,
+    "portsPerSpec": 10,
+    "envFile": ".env",
+    "backupCommand": ""
+  },
+  "open": {
+    "command": ""
+  },
+  "registry": ".spec-env/registry.json",
+  "linkLinear": true,
+  "guards": {
+    "refuseTeardownIfDirty": true,
+    "refuseTeardownIfUnpushed": true
+  }
+}

package/assets/core/env.config.md

@@ -0,0 +1,83 @@
+# `env.config.json` — per-spec isolation config
+
+Opt-in config for per-spec isolation (git worktree + optional namespaced Docker
+stack + an optional opener per in-progress spec), driven by `/spec-go` and the
+`/spec-env` · `/spec-env-down` skills.
+
+**Once this file is present, isolation is the default policy:** `/spec-go` gives
+**every** in-progress spec its own git worktree automatically. Docker is a **per-
+spec escalation** — a spec brings up a stack only when its `> **Stack:**` header
+is `worktree + docker` (set at `/spec` when it touches the DB / stateful
+services). A `worktree`-only spec takes no registry slot, no port block, and no
+`.env`.
+
+**Adopt it** with `skitterspec init --isolation` (or copy
+`env.config.json.example` → `env.config.json` here) and edit the values. While
+`env.config.json` is absent the feature is simply unused — every skill behaves
+exactly as it does today.
+
+The loader (`src/env/config.js` → `loadEnvConfig`) merges your file over the
+frozen defaults below and returns `{ config, present }`; `present:false` means
+no live `env.config.json` was found.
+
+## Fields
+
+```jsonc
+{
+  // Where sibling worktrees are created and how their dirs are named.
+  "worktree": {
+    "root": "../{repo}-wt",   // dir that holds all spec worktrees; sibling of
+                              // the primary checkout, never nested inside it.
+    "folderPattern": "{slug}" // per-spec worktree dir name.
+  },
+
+  // Per-spec Docker stack. COMPOSE_PROJECT_NAME namespaces containers,
+  // networks, and named volumes; PORT_OFFSET shifts the spec's port block.
+  "docker": {
+    // Master switch: "is Docker escalation available on this project?" — NOT
+    // "always run Docker". true = specs MAY escalate (a spec still needs
+    // `Stack: worktree + docker` to actually get a stack); the default stack is
+    // worktree-only. false = every spec is worktree-only and the escalation is
+    // hidden. (Was "always provision Docker" in the pre-Stack engine.)
+    "enabled": true,
+    "composeFile": "docker-compose.yml",
+    "projectNamePattern": "{repoSlug}_{slug}", // → COMPOSE_PROJECT_NAME
+    "portBase": 3000,          // first port of slot 0's block
+    "portsPerSpec": 10,        // block width; slot n → portBase + n*portsPerSpec
+    "envFile": ".env",         // written into the worktree
+    "backupCommand": ""        // optional pre-teardown backup (e.g. pg_dump);
+                              // empty = no backup, volumes dropped directly.
+  },
+
+  // Optional, editor/terminal-agnostic opener run after `spec-env up`. The
+  // template is expanded with {worktreePath}, {slug}, {branch}, {projectName},
+  // {portOffset}. Empty = nothing is opened (the path is just printed).
+  // Examples: "code {worktreePath}", "tmux new-window -c {worktreePath}",
+  // or a "warp://..." deeplink for Warp users.
+  "open": {
+    "command": ""
+  },
+
+  // Machine-local slot registry (spec → slot index). Resolved against the
+  // primary checkout root, shared by all worktrees, gitignored.
+  "registry": ".spec-env/registry.json",
+
+  // When true and specs/.core/linear.config.json is present, derive branch
+  // names from Linear's branch.pattern so pushing fires Linear's GitHub
+  // automation. Otherwise branches fall back to {type}/{slug}.
+  "linkLinear": true,
+
+  // Teardown safety. --force overrides both.
+  "guards": {
+    "refuseTeardownIfDirty": true,
+    "refuseTeardownIfUnpushed": true
+  }
+}
+```
+
+## Token expansion
+
+- `{repo}` — primary checkout dir basename (e.g. `skitterspec`).
+- `{repoSlug}` — `{repo}` lower-cased, non-alphanumerics collapsed to `-`
+  (safe for a `COMPOSE_PROJECT_NAME`).
+- `{slug}` — the spec slug (folder name minus its `feat-`/`bug-` prefix).

package/assets/core/linear.config.json.example

@@ -0,0 +1,39 @@
+{
+  "linear": {
+    "teamKey": "",
+    "teamId": "",
+    "initiativeId": ""
+  },
+  "mapping": {
+    "specFolder": "project",
+    "phases": "milestone",
+    "tasks": "issue"
+  },
+  "states": {
+    "backlog": "Backlog",
+    "in-progress": "In Progress",
+    "complete": "Done",
+    "cancelled": "Cancelled"
+  },
+  "snapshot": {
+    "overviewFile": "00-overview.md"
+  },
+  "branch": {
+    "pattern": "{type}/{slug}"
+  },
+  "sync": {
+    "baseDir": "specs/.core/linear-base",
+    "backupDir": "specs/.core/linear-backups",
+    "fieldOwnership": {
+      "description": "both",
+      "milestones": "both",
+      "phaseBodies": "both",
+      "acceptanceCriteria": "both",
+      "taskBreakdown": "both",
+      "workflowState": "pull",
+      "priority": "pull",
+      "labels": "pull"
+    },
+    "localOnlySections": ["State log", "Changelog", "Open questions"]
+  }
+}

package/assets/core/linear.config.md

@@ -0,0 +1,121 @@
+# `linear.config.json` — Linear hybrid-sync config
+
+Opt-in config for the git-like Linear sync (`/spec-status`, `/spec-pull`,
+`/spec-push`, and the Linear-aware paths of `/spec` and `/spec-go`). Linear owns
+**status and discussion**; the repo stays the **co-authoring surface for spec
+content**. Sync is bidirectional but git-like: explicit commands, a committed
+**base sidecar** for three-way merge, and no blind overwrites.
+
+**Every Linear step is gated on this file.** While `specs/.core/linear.config.json`
+is absent the feature is simply unused — `/spec`, `/spec-go`, and the CLI's
+`spec-sync` subcommands behave exactly as they do today (local-only). Adopt it by
+copying `linear.config.json.example` → `linear.config.json` here and filling in
+your team / initiative IDs.
+
+The loader (`src/sync/config.js` → `loadLinearConfig`) merges your file over the
+frozen defaults below and returns `{ config, present }`; `present:false` means no
+live `linear.config.json` was found (the opt-in gate — it never throws on
+absence). A `sync.fieldOwnership` value outside `both|pull|push` is a hard error.
+
+## Fields
+
+```jsonc
+{
+  // Which Linear team/initiative specs sync into. IDs are read by the Phase 2
+  // MCP adapter; leave blank until you connect the `linear` MCP server.
+  "linear": {
+    "teamKey": "",        // human-facing key, e.g. "ENG" (optional)
+    "teamId": "",         // Linear team UUID (create target)
+    "initiativeId": ""    // optional Initiative that groups these specs
+  },
+
+  // How a spec's parts map onto Linear objects. Defaults mirror Decision 7:
+  // spec folder → Project, phases → Milestones, tasks → Issues. `phases` may be
+  // switched to "issue" if your workspace doesn't expose project milestones.
+  "mapping": {
+    "specFolder": "project",
+    "phases": "milestone",   // "milestone" | "issue"
+    "tasks": "issue"
+  },
+
+  // Map the spec's lifecycle bucket → the Linear workflow-state name. Used when
+  // translating workflowState across the boundary (Linear owns status → `pull`).
+  "states": {
+    "backlog": "Backlog",
+    "in-progress": "In Progress",
+    "complete": "Done",
+    "cancelled": "Cancelled"
+  },
+
+  // The spec's entry-point file the local snapshot + frontmatter live in.
+  "snapshot": {
+    "overviewFile": "00-overview.md"
+  },
+
+  // Git branch name derived for a linked spec. Tokens: {type}, {slug},
+  // {identifier} (the Linear issue/project identifier, e.g. ENG-123). Shared
+  // with the isolation engine's branch derivation (src/env/resolve.js).
+  "branch": {
+    "pattern": "{type}/{slug}"
+  },
+
+  // The three-way merge engine's on-disk state.
+  "sync": {
+    // Committed base sidecar dir: the last-synced snapshot per spec, as
+    // {baseDir}/{identifier}.base.json. Committed so each worktree carries its
+    // own base and the divergence check stays accurate.
+    "baseDir": "specs/.core/linear-base",
+
+    // Backup-before-force lands the about-to-be-clobbered side here (the
+    // reflog). --force never destroys without first writing a copy.
+    "backupDir": "specs/.core/linear-backups",
+
+    // Per-field sync direction — collapses which fields can ever conflict:
+    //   "both" — co-authored: push + pull, may conflict (both moved off base).
+    //   "pull" — Linear→local only (e.g. status/priority); a local edit never
+    //            pushes and a conflict resolves to remote-wins.
+    //   "push" — local→Linear only; a remote edit never pulls and a conflict
+    //            resolves to local-wins.
+    // Any field key you add here joins the compared field set; a value outside
+    // both|pull|push is rejected at load time.
+    "fieldOwnership": {
+      "description": "both",
+      "milestones": "both",
+      "phaseBodies": "both",
+      "acceptanceCriteria": "both",
+      "taskBreakdown": "both",
+      "workflowState": "pull",
+      "priority": "pull",
+      "labels": "pull"
+    },
+
+    // Markdown sections of 00-overview.md that are local-only scaffolding and
+    // are stripped from the pushed `description` (never sent to Linear).
+    "localOnlySections": ["State log", "Changelog", "Open questions"]
+  }
+}
+```
+
+## Field ownership & conflicts
+
+The spec is a set of structured fields, most written by only one side. Marking a
+field's owner collapses which fields can genuinely conflict:
+
+- A `pull` field (Linear owns it) never reports as **pushable** — a stray local
+  edit is informational and gets reverted on the next pull.
+- A `push` field (the repo owns it) never reports as **pullable**.
+- Only a `both` field where **both** sides moved off the committed base is a real
+  `conflict` — `/spec-push` / `/spec-pull` refuse it unless `--force` (which
+  backs up the losing side into `sync.backupDir` first).
+
+After any successful pull/push/force the engine **rewrites the base** so the next
+three-way compare starts clean.
+
+## What to commit
+
+- **`sync.baseDir`** (default `specs/.core/linear-base/`) — **commit it.** The base
+  sidecar is the last-synced snapshot the three-way merge compares against; each
+  worktree carries its own base, so it must travel with the branch.
+- **`sync.backupDir`** (default `specs/.core/linear-backups/`) — **gitignore it.**
+  These are `--force` recovery copies (a local reflog), per-machine and not shared.
+  Add `specs/.core/linear-backups/` to your `.gitignore`.

package/assets/rules/spec-planning.md

@@ -20,6 +20,29 @@ state). `/spec-ready` is a grooming gate only — it does not move the folder.
 `/spec-bug` is test-first and starts straight in `In Progress` (work begins
 immediately), so it skips Draft/Ready.
 
+**Per-spec isolation (opt-in to adopt, then the default policy).** When a project
+adopts isolation (`skitterspec init --isolation`, or `specs/.core/env.config.json`
+present), `/spec-go` gives **every** in-progress spec its own git worktree
+automatically — several specs run side by side without stashing or clashing, and
+`main` stays free. Docker is a **per-spec escalation**: `/spec` records
+`> **Stack:** worktree` (default) or `worktree + docker` when the spec touches the
+DB / stateful services, and `/spec-go` brings up a namespaced stack only for the
+latter. All housekeeping (the backlog→in-progress move, header edits, the code)
+happens on the spec's branch in the worktree; `main` changes only when it merges.
+`/spec-env` · `/spec-env-down` remain the manual engine (escalate Docker later,
+re-attach, tear down). Isolation is **orthogonal to lifecycle status** and
+inactive when `env.config.json` is absent — every skill then behaves as it does
+today.
+
+**Linear hybrid sync (opt-in).** When `specs/.core/linear.config.json` is present,
+three git-like skills sync a spec with its linked Linear project: `/spec-status`
+(read-only per-field divergence), `/spec-pull` (Linear→repo), and `/spec-push`
+(repo→Linear) — three-way merged against a committed base sidecar, with
+field-ownership collapsing conflicts and a `--force` + backup escape hatch. Linked
+`/spec` also creates the Linear Project + a Milestone per phase, and `/spec-go`
+pulls first. All of it is inert without the config — every skill then behaves as
+it does today. Full model + field reference: `specs/.core/linear.config.md`.
+
 ## Project conventions (fill this in)
 
 The spec skills tell you to run "your project's typecheck and test commands" and
@@ -107,18 +130,13 @@ Keep the index and the phase files in sync (`⬜`/`🔄`/`✅`). Legacy specs ma
 bare `<name>.md`, or a `00-overview.md` with inline phases — the skills read
 those, but new specs always use the folder + phase-file form.
 
-## Folder indexes (`00-index.md`)
-
-Two folders keep a skill-maintained `00-index.md` file (never hand-edit):
-
-- `specs/backlog/00-index.md` — **live view** of the backlog (`Added | Spec | Type |
-  Status`, newest first). `/spec` prepends a row; `/spec-ready` updates its
-  status; `/spec-go` and `/spec-cancel` remove the row when the spec leaves.
-- `specs/complete/00-index.md` — **append-only completion log** (`Completed | Spec |
-  Type`, newest first). `/spec-complete` prepends a row — use it to find the
-  latest completed specs.
+## Finding specs
 
-`/spec-init` ensures both exist. No index for `in-progress` or `cancelled`.
+The **folder buckets are the source of truth** — a spec's bucket is its status.
+To see the backlog, list `specs/backlog/`; for the latest completed specs, use
+`git log`/mtime on `specs/complete/` or each spec's dated **State log**. Live
+status also lives in Linear when it's linked. (There are no `00-index.md`
+summary files — the folder tree, headers, and State logs are queried directly.)
 
 ## Rules
 

package/assets/skills/spec/SKILL.md

@@ -35,7 +35,13 @@ not write the spec until this is resolved.
   6. **Security & multi-tenancy** — authz, tenant scoping, untrusted input.
   7. **Edge cases & failure modes.**
   8. **Testing approach** — what proves each phase correct.
-  9. **Open questions** — anything still undecided.
+  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.
@@ -71,6 +77,8 @@ the codebase, link rather than duplicate):
 > **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
 
@@ -159,18 +167,58 @@ Rules for the spec body:
   absolute.
 - Keep it tight. If a section adds no information, delete it.
 
-## Phase C — index the spec
-
-Prepend a row to `specs/backlog/00-index.md` (newest first — directly under the table
-header row, above existing rows):
-
-```
-| <YYYY-MM-DD> | <feat-name> | Feature | Draft |
-```
-
-This is the live view of the backlog; `/spec-go` / `/spec-cancel` remove the row
-when the spec leaves. Create `00-index.md` from a header if it's somehow missing
-(`/spec-init` normally ensures 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 Linear (only if configured)
+
+**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

@@ -103,10 +103,6 @@ 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.
 
-It starts in `in-progress`, so it does **not** touch `specs/backlog/00-index.md`
-(there is no index for in-progress). When `/spec-complete` later finishes it,
-that skill logs it to `specs/complete/00-index.md`.
-
 ## 5. Report
 
 Summarise: root cause, the failing→passing test, the fix, and the full test

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

@@ -47,10 +47,15 @@ Add a **Changelog** entry:
 `git mv "specs/<bucket>/<name>" "specs/cancelled/<name>"` (preserve history;
 move the whole folder).
 
-If the spec was in `backlog`, **remove its row from `specs/backlog/00-index.md`**
-(it has left the backlog). There is no index for `cancelled`.
-
 ## 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

@@ -43,18 +43,18 @@ Before marking complete, confirm the work is actually finished:
 
 `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).
-
-Then **prepend a row to `specs/complete/00-index.md`** (newest first — directly under
-the table header, above existing rows):
-
-```
-| <YYYY-MM-DD> | <name> | Feature|Bug |
-```
-
-This is the append-only completion log used to find the latest completed specs.
+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. 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, 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.