@skitterbyte/skitterspec-linear 8.0.4 → 9.0.0

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

@@ -13,6 +13,66 @@ 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`).
 
+## Phase 0 — start from a Linear issue (only when asked)
+
+**Only when `specs/.core/linear.config.json` exists** *and* the invocation names an
+issue. Otherwise skip this phase entirely and grill from the user's own words.
+
+Two ways in:
+
+- **`<ISSUE-REF>`** (`SKI-123`, an issue URL, or a bare id anywhere in the
+  arguments) — adopt that issue.
+- **`--from-issue [query]`** — browse the intake inbox: issues carrying
+  `intake.label` (what the web app files under). With a `query`, filter that list
+  case-insensitively by title. Show the shortlist and let the user pick one.
+
+Then:
+
+1. **Exclude what's already adopted.** Run `skitterspec spec-sync linked --json`
+   and drop any issue whose identifier is already stamped on a spec. If the user
+   named such an issue directly, **stop** and point them at that spec — one issue
+   never becomes two specs.
+2. **Read the issue** with the discovered issue-read tool: title, description,
+   labels, reporter, URL. If Linear isn't connected, say so and offer to carry on
+   without it — a spec written from the user's own description is still a spec.
+3. **Route bugs away — in `/spec` only.** If any of the issue's labels matches
+   `intake.bugLabels` (case-insensitive), this is a bug report, not a feature
+   request. Say so, name the matching label, and tell the user to run
+   **`/spec-bug <ISSUE-REF>`** — then stop, without authoring a Feature spec.
+   With `intake.bugLabels` unset nothing is routed and every issue is treated as a
+   feature request.
+
+   **In `/spec-bug` this step is skipped** — you are already in the bug path.
+   Adopt the issue, then reproduce it as usual: the issue body is your repro
+   material, and the failing test comes before the spec exactly as normal.
+4. **Seed, don't skip, the grill.** The issue's title becomes the working spec
+   title and its description the starting material for **Problem** — quote the
+   reporter's words rather than paraphrasing them away. Note the reporter and the
+   issue URL for context. Everything after this runs exactly as normal: an issue
+   is a *request*, not a groomed spec, so grill it as hard as anything else.
+
+### Adopting the issue
+
+The issue **becomes** the spec's issue — it is not copied and no second issue is
+minted. This is identical in `/spec` and `/spec-bug`; only *when* it happens
+differs (`/spec` writes the spec in Phase B, `/spec-bug` in its step 4). Once the
+spec file exists:
+
+- **Stamp `linear_identifier` and `linear_url`** in `00-overview.md` frontmatter
+  from the adopted issue. That is the whole link: every later skill
+  (`/spec-push`, `/spec-status`, `/spec-go`) keys off it being present.
+- **Do not run the project picker** and never send `project`. The issue was filed
+  somewhere deliberately — where it lives is Linear's business, and adoption is
+  not a mint.
+- **Do not write a base sidecar.** Leaving `sync.baseDir` empty for this spec is
+  what makes the first `/spec-push` push the spec over the reporter's original
+  description (an **update** to the existing issue, plus a sub-issue per phase).
+  Recording a snapshot here would declare the mirror already in sync and strand
+  the issue showing the raw report forever.
+- **Say what will happen** in the finish-up message: the first `/spec-push` will
+  overwrite the issue's description with the spec, and the original report is
+  preserved in the spec's **Problem** section.
+
 ## 1. Reproduce & isolate (light investigation)
 
 Bugs are concrete — confirm, don't over-grill. Establish:
@@ -95,6 +155,7 @@ because work is already underway. Keep it lean:
 # Bug: <short title>
 
 > **Type:** Bug
+> **Name:** bug-<kebab-name> (the spec folder name — the handle you paste into `/spec-go`)
 > **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>

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

@@ -25,6 +25,10 @@ it verbatim/condensed for the header.
   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.
+- **Check for pre-existing uncommitted changes — before you touch anything.**
+  Run `git status`. Anything already uncommitted is the *user's* work and must not
+  be swept into the cancellation commit: offer `/commit` and **stop**. Everything
+  this skill writes in steps 4–5 is its own, and step 5 commits that.
 
 ## 4. Stamp the spec
 
@@ -41,16 +45,27 @@ Append a **State log** row:
 Add a **Changelog** entry:
 `- <YYYY-MM-DD> — Cancelled: <reason>.`
 
-## 5. Move to cancelled
+## 5. Move to cancelled — and commit it
 
 `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).
 
+Then **commit the cancellation edits** — this skill wrote them, so it commits
+them:
+
+```
+git add specs/ && git commit -m "chore(spec): cancel <name>"
+```
+
+**This matters more here than anywhere else.** Teardown (step 7) refuses a dirty
+worktree and offers `--force` as the way through — and forcing would destroy the
+cancellation record this skill just wrote. Committing first means teardown never
+needs `--force`. Do not `git push`.
+
 ## 6. Report
 
-Confirm the cancellation, the reason recorded, and the new location. Do **not**
-`git commit` unless the user asks.
+Confirm the cancellation, the reason recorded, the new location, and the commit.
 
 ## 7. Tear down the environment (opt-in, only if configured)
 

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

@@ -27,6 +27,12 @@ Before marking complete, confirm the work is actually finished:
 - 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.
+- **Check for pre-existing uncommitted changes — before you touch anything.**
+  Run `git status`. Anything already uncommitted is the *user's* work (a
+  half-finished phase, a stray fix) and must not be swept into the completion
+  commit: offer `/commit` and **stop**. Everything this skill writes in steps 3–4
+  is its own, and step 4 commits that.
+
 
 ## 3. Update the spec
 
@@ -40,17 +46,28 @@ Before marking complete, confirm the work is actually finished:
   `- <YYYY-MM-DD> — Completed; all phases done, tests green.`
   (Note any consciously-deferred items here too.)
 
-## 4. Move to complete
+## 4. Move to complete — and commit it
 
 `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.
 
+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:
+
+```
+git add specs/ && git commit -m "chore(spec): complete <name>"
+```
+
+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`.
+
 ## 5. Report
 
-Confirm the move, the final test result, and list anything deferred. Do **not**
-`git commit` unless the user asks.
+Confirm the move, the commit, the final test result, and list anything deferred.
 
 ## 6. Land the branch (opt-in, only if isolated)
 
@@ -65,8 +82,9 @@ destination in one flow. **How it lands depends on the spec type:**
 A hotfix is built on an old release **tag**, so it can't fast-forward onto `main`.
 Use the hotfix landing instead of the integrate steps below:
 
-1. **Require a clean worktree** — the completion edits (status flip, `git mv` to
-   `complete/`) must be committed first. If dirty, offer `/commit` and **stop**.
+1. **Require a clean worktree.** Step 4 already committed the completion edits, so
+   this should pass. If the tree is *still* dirty, that's unrelated work — offer
+   `/commit` and **stop**.
 2. **Plan + execute.** Run `skitterspec spec-env hotfix land <name>` — add
    `--also <tag>` for each extra release line to patch (test/demo on their own
    versions). Run the printed commands **in order**. It:
@@ -92,9 +110,9 @@ is finished — e.g. to run a later phase in CI or a shared test env? Use
 **`/spec-to-main`**: same rebase + fast-forward, but it leaves the spec
 `In Progress` and the worktree standing, and it's repeatable.)
 
-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.
+1. **Require a clean worktree.** Step 4 already committed the completion edits, so
+   integrate's dirty-tree guard should pass. If the tree is *still* dirty, that's
+   unrelated work — offer `/commit` and **stop**; don't sweep it in.
    **If the spec is live** (you took the running instance with `/spec-live`):
    `integrate` is live-aware — it ends the live session first (releases the branch
    back to base, re-isolates it into its worktree, clears the receipt), then prints

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

@@ -47,16 +47,26 @@ same "in place otherwise" path used when isolation is off. Warn that the work
 will land wherever you currently are (usually `main`); reserve it for a trivial
 change or an explicit request.
 
-- Run `skitterspec spec-env up <name>` (the `spec-env` CLI engine). It adds a git
-  worktree on a branch forked from `main`, and — only when the spec's
-  `> **Stack:**` header is `worktree + docker` — also brings up its Docker stack.
+- Run `skitterspec spec-env up <name>` (the `spec-env` CLI engine). It is a
+  **planner: it prints commands and creates nothing itself.** Under
+  `to provision, run:` it emits the `git worktree add` on a branch forked from
+  `main` and — only when the spec's `> **Stack:**` header is
+  `worktree + docker` — the Docker bring-up.
+  **Run those commands and confirm they succeeded** before anything below: every
+  later step assumes the worktree exists, and the header line says
+  `(plan — nothing created yet)` precisely because at that point it doesn't.
   Print the worktree path and the opener command it emits.
 - **Bootstrap the worktree's dependencies.** A fresh worktree has an empty
   working tree — no installed dependencies, and none of the repo's gitignored
   files (`.env`, local secret/config overrides) — so git hooks, typechecks,
   builds and tests fail until they're in place. `spec-env up` prints the
-  project's configured **`in the worktree, run:`** commands — run them in the
-  worktree, in order, before doing anything else. Those commands are: first any
+  project's configured **`then, in the worktree, run:`** commands — run them in
+  order, before doing anything else. Each one begins by `cd`-ing into the
+  worktree, so it works from any cwd and cannot quietly act on the main
+  checkout; if the worktree is missing it prints
+  **`no worktree at … — run the provisioning commands first`** and exits
+  non-zero. Seeing that means the `git worktree add` above didn't run or didn't
+  work — fix that before going on. Those commands are: first any
   **file seeding** (from `env.config.json` → `seedFiles`), which symlinks or
   copies the configured gitignored files from the main checkout into the fresh
   worktree so setup can rely on them; then the **`setup`** commands (e.g. an
@@ -136,7 +146,7 @@ tracker. Otherwise skip this step — no provider means zero change to the flow
 below. Follow the provider's steps below (nothing to do here without one).
 
 **Only when `specs/.core/linear.config.json` exists** and the spec carries a
-`linear_project_id`. Otherwise skip this step — no config means zero change.
+`linear_identifier`. Otherwise skip this step — no config means zero change.
 
 - **No pull.** Linear is a generated mirror in one-way sync, so there is nothing
   to bring down before building — the repo is already the source of truth. (A

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

@@ -89,6 +89,7 @@ is usually a single-pass fix, so the `## Fix` block can live directly in
 # Hotfix: <short title>
 
 > **Type:** Hotfix
+> **Name:** hotfix-<kebab-name> (the spec folder name — the handle you paste into `/spec-go`)
 > **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>

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

@@ -1,14 +1,16 @@
 ---
 name: spec-push
-description: Push a spec up to its linked Linear project (repo → Linear, one-way). The repo is the source of truth; Linear is a generated mirror. Runs `skitterspec spec-sync push` to get a create/update plan, applies it over MCP (project description/status, milestones, issues), stamps the returned ids back into the spec, then records the snapshot. Never reads Linear content back. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-push", "push to Linear", "update the Linear project from this spec".
+description: Push a spec up to its linked Linear issue (repo → Linear, one-way). The repo is the source of truth; Linear is a generated mirror. A spec is a Linear issue and each phase a sub-issue; tasks are not synced. Runs `skitterspec spec-sync push` to get a create/update plan, applies it over MCP (issue description/state, phase sub-issues), stamps the returned ids back into the spec, then records the snapshot. Never reads Linear content back. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-push", "push to Linear", "update the Linear issue from this spec".
 ---
 
 # /spec-push — send a spec up to Linear (one-way)
 
 Repo → Linear. The repo is the **source of truth**; Linear is a **generated
-mirror**. This skill computes what changed since the last push and applies it —
-it never reads Linear content back or merges. A person editing the mirror in
-Linear will see it overwritten on the next push.
+mirror**. A spec is a Linear **issue**; each phase is a **sub-issue** (a child
+issue). Tasks are not synced — they live only in the repo phase files. This skill
+computes what changed since the last push and applies it — it never reads Linear
+content back or merges. A person editing the mirror in Linear will see it
+overwritten on the next push.
 
 **Opt-in**: only runs when `specs/.core/linear.config.json` exists. If absent,
 tell the user how to enable Linear sync and stop.
@@ -27,40 +29,51 @@ The engine prints a JSON **plan** (no network, no remote read):
 
 ```json
 {
-  "project": { "description": "…", "status": "in-progress", "priority": 2, "labels": ["…"] },
-  "milestones": { "create": [{ "ref": "01-outbox", "name": "…", "goal": "…" }], "update": [{ "id": "…", "name": "…", "goal": "…" }] },
-  "issues": { "create": [{ "ref": "<task text>", "title": "…", "description": "…", "done": false, "milestoneRef": "01-outbox" }], "update": [{ "id": "SKI-1", "title": "…", "description": "…", "done": true }] }
+  "issue": { "description": "…", "state": "in-progress" },
+  "subIssues": {
+    "create": [{ "ref": "01-outbox", "name": "Outbox", "goal": "…", "state": "backlog" }],
+    "update": [{ "id": "REU-2", "name": "…", "goal": "…", "state": "in-progress" }]
+  }
 }
 ```
 
-An empty plan (no project, no create/update) means the mirror is up to date —
-say so and stop.
+An empty plan (no `issue`, no sub-issue create/update) means the mirror is up to
+date — say so and stop. `state` values are local buckets
+(`backlog`/`in-progress`/`complete`/`cancelled`); map each to the Linear
+issue-state NAME via `config.states` at apply time.
 
 ## 3. Discover the Linear MCP tools
 
-Discover project + milestone + issue **create/update** tools at runtime. If
-Linear isn't connected or a needed tool is missing, relay the fix and stop,
-**writing nothing**.
+Discover the issue **read + create/update** tools at runtime (`get_issue`,
+`save_issue` — a single upsert covers create and update), plus the **project
+list** tool if this push will mint the spec issue (see the picker below — it is
+optional; without it the picker is skipped, not failed). If Linear isn't
+connected or a needed tool is missing, relay the fix and stop, **writing
+nothing**.
 
-**Validate the project states first.** Fetch the workspace's project-status
+**Validate the issue states first.** Fetch the workspace's issue workflow-state
 names and run `skitterspec spec-sync status <spec> --workspace-states <file>`; if
 it errors (a configured `states` name isn't in the workspace), stop and fix the
-config — Linear silently ignores an unknown project status.
+config — Linear silently ignores an unknown issue state.
 
 ## 4. Apply the plan (order matters)
 
-1. **Milestones create** → create each in Linear; for each, stamp the returned id
-   into its phase file: the `ref` is the phase-file basename.
-2. **Issues create** → create each (link to its milestone by `milestoneRef`,
-   resolving a `create` ref to the id just minted); stamp the returned identifier
-   back onto the matching task line (`ref` is the task's text).
-3. **Milestones/issues update** → save by `id`.
-4. **Project** → set description + status (map `status` — the local bucket — to
-   the Linear project-status name via `config.states`). Priority, labels, cycles
-   and comments are Linear-native triage — do **not** push them; they're the PM's.
-
-Map the local status bucket to Linear's project status through `config.states`
-(e.g. `complete → Completed`).
+1. **Spec issue** → if the overview has no `linear_identifier`, this push
+   **mints** it: run the picker in **Picking the Linear Project** below, then
+   create it with `save_issue` (`team` = `linear.teamId`; `project` = the picked
+   id; `title` from the spec title; `description` from `plan.issue.description`;
+   state from `plan.issue.state` via `config.states`). Stamp the returned
+   identifier into `00-overview.md` frontmatter as `linear_identifier` (and
+   `linear_url`). If it already exists and `plan.issue` is present, **update it by
+   id and send no `project`** — its placement is Linear's from then on.
+2. **Sub-issues create** → for each, `save_issue` with `parentId` = the spec
+   issue id (`name` → title, `goal` → description, `state` via `config.states`);
+   stamp the returned id into its phase file as `linear_issue_id` (`ref` is the
+   phase-file basename).
+3. **Sub-issues update** → `save_issue` by `id` (title/description/state).
+
+Priority, labels, cycles and comments are Linear-native triage — do **not** push
+them; they're the PM's.
 
 ## 5. Record the snapshot
 
@@ -76,5 +89,35 @@ branch so the mirror-link rides in the PR.
 
 ## 6. Report
 
-Summarise what was created/updated in Linear and confirm the snapshot was
-recorded. There is no pull — Linear is a generated mirror.
+Summarise what was created/updated in Linear (the spec issue and its
+sub-issues) and confirm the snapshot was recorded. There is no pull — Linear is
+a generated mirror.
+
+### Picking the Linear Project
+
+Run this **only when minting a spec issue** — creating it for the first time. On
+an update the issue already has a project (or deliberately has none), and that
+placement is **Linear's to own**: never send `project` on an update, and never
+record the choice in the spec file or the snapshot. A PM re-homing a spec issue
+must not show up as drift or be overwritten on the next push.
+
+1. **List the candidates.** Call the discovered project-list tool for
+   `linear.teamId`. Drop archived / completed projects — they can't take new work.
+2. **Offer them.** Show the names (most recently updated first is fine), plus an
+   explicit **None (team only)** option. Pre-select `linear.projectId` from
+   `linear.config.json` when it's set and still in the list; otherwise pre-select
+   **None**.
+3. **Narrow on request.** If the user types a fragment rather than choosing, filter
+   the list case-insensitively by name and re-offer. Don't re-fetch.
+4. **Never offer to create a project.** Projects are the PM's surface — if none
+   fits, that's **None (team only)**, and someone makes the project in Linear.
+5. **Pass it once.** Include `project: <chosen id>` on the issue-create call.
+   Chose None → omit the key entirely (do not send an empty string).
+
+**Degrade, never block.** If Linear isn't connected, or the server exposes no
+project-list tool, say so in one line — *"project picker unavailable; creating the
+issue without a project"* — and carry on with `linear.projectId` if it's set, else
+no project at all. A missing picker must never fail `/spec` or `/spec-push`.
+
+If `linear.projectId` is set but that Project is archived or missing, relay
+Linear's error and stop rather than silently minting an unparented issue.

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

@@ -1,15 +1,15 @@
 ---
 name: spec-status
-description: Show a spec's one-way sync status against Linear — a read-only drift report. Reports whether the spec changed since the last push (there's something to push) and, optionally, whether Linear's workflow-state differs from the spec's. Fetches the Linear project over MCP and runs `skitterspec spec-sync status`. Changes nothing. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-status", "is this spec in sync with Linear", "what would push", or "show spec sync status".
+description: Show a spec's one-way sync status against Linear — a read-only drift report. Reports whether the spec changed since the last push (there's something to push) and, optionally, whether Linear's issue workflow-state differs from the spec's. Fetches the Linear issue over MCP and runs `skitterspec spec-sync status`. Changes nothing. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-status", "is this spec in sync with Linear", "what would push", or "show spec sync status".
 ---
 
 # /spec-status — one-way sync drift report
 
 Read-only. Reports two things and writes nothing:
 
-1. **Pending push** — has the spec changed since the last push (are there
-   milestones/issues/description to create or update)?
-2. **State drift** — does Linear's project workflow-state differ from the spec's
+1. **Pending push** — has the spec changed since the last push (is there an issue
+   description/state or any phase sub-issue to create or update)?
+2. **State drift** — does Linear's issue workflow-state differ from the spec's
    status? (The repo wins on the next push; this is just a heads-up, e.g. a card
    moved in Linear.)
 
@@ -24,24 +24,25 @@ tell the user how to enable Linear sync and stop.
 
 Use the argument, else the spec in context; ask if unclear.
 
-## 2. Fetch the Linear project (optional, for drift)
+## 2. Fetch the Linear issue (optional, for drift)
 
-If the spec has a `linear_project_id`, discover the Linear MCP read tool and write
-the project JSON to a temp file — this lets the report compare workflow-state. If
-Linear isn't connected, skip the drift line (still report pending-push).
+If the spec has a `linear_identifier`, discover the Linear MCP read tool
+(`get_issue`) and write the issue JSON to a temp file — this lets the report
+compare workflow-state. If Linear isn't connected, skip the drift line (still
+report pending-push).
 
-Optionally fetch the workspace project-status names to a file to validate the
+Optionally fetch the workspace issue-state names to a file to validate the
 configured `states` at the same time.
 
 ## 3. Run the engine
 
 ```
-skitterspec spec-sync status <spec> [--remote <projectfile>] [--workspace-states <statesfile>]
+skitterspec spec-sync status <spec> [--remote <issuefile>] [--workspace-states <statesfile>]
 ```
 
 - Reports `push: pending — N to create, M to update` or `up to date`.
-- With `--remote`, adds a `drift:` line comparing Linear's workflow-state to the
-  spec's status.
+- With `--remote`, adds a `drift:` line comparing Linear's issue workflow-state
+  to the spec's status.
 - With `--workspace-states`, fails loudly if a configured state name isn't in the
   workspace (Linear would silently no-op it).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec-linear",
-  "version": "8.0.4",
+  "version": "9.0.0",
   "description": "Spec-driven development for Claude Code, with one-way Linear sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Linear is a generated mirror. Install this OR the base, not both.",
   "keywords": [
     "claude",

package/src/cli.js

@@ -60,7 +60,8 @@ Usage:
                               .core config alone.
   skitterspec spec-env <cmd>  Per-spec isolation engine (opt-in; needs
                               specs/.core/env.config.json). Subcommands:
-                                up <spec>         plan a worktree + Docker stack + opener
+                                up <spec>         print the plan to provision a worktree +
+                                                  Docker stack (prints commands; creates nothing)
                                 down <spec>       tear down (guards; --keep-volumes, --force)
                                 prune             reap orphaned test-DB volumes (--older-than <days>)
                                 dev up <spec>     start host dev servers on the spec's ports
@@ -176,8 +177,10 @@ function specEnvStatus(dir, config) {
     })
 }
 
-// Provision: allocate the slot, persist the registry, and print the plan the
-// /spec-env skill executes (git worktree add, docker compose up, .env, opener).
+// Plan a provision: allocate the slot, persist the registry, and print the plan
+// the /spec-env skill executes (git worktree add, docker compose up, .env,
+// opener). This creates no worktree and starts no stack — the caller runs the
+// printed commands. Keep the output's verb honest about that.
 function specEnvUp(dir, config, specArg) {
   if (!specArg) {
     process.stdout.write('Usage: skitterspec spec-env up <spec>\n')
@@ -224,7 +227,16 @@ function specEnvUp(dir, config, specArg) {
   const plan = planUp(spec, { slot, attached }, config)
 
   const out = []
-  out.push(`spec-env up: ${spec.folder} ${attached ? '(attached — existing)' : '(provisioned)'}`)
+  // `up` is a planner: it prints commands for the caller to run and creates no
+  // worktree or stack itself (the registry slot and the trust entry, both reported
+  // separately below, are its only writes). Say so in the verb — a past-tense
+  // "(provisioned)" reads as a completed state change, and a caller that believes
+  // it skips the commands and works on `main`, which is what isolation exists to
+  // prevent.
+  out.push(
+    `spec-env up: ${spec.folder} ` +
+      (attached ? '(plan — worktree exists; will attach)' : '(plan — nothing created yet)'),
+  )
   out.push('')
   out.push(`  worktree:  ${plan.worktreePath}`)
   out.push(`  branch:    ${plan.branch}`)
@@ -247,7 +259,7 @@ function specEnvUp(dir, config, specArg) {
     )
   }
   out.push('')
-  out.push('  run these:')
+  out.push('  to provision, run:')
   for (const cmd of plan.commands) out.push(`    ${cmd}`)
   if (plan.openCommand) out.push(`    ${plan.openCommand}`)
   // Seed files first (setup may depend on them), then the setup commands —
@@ -255,7 +267,7 @@ function specEnvUp(dir, config, specArg) {
   const worktreeSteps = [...plan.seedCommands, ...plan.setupCommands]
   if (worktreeSteps.length) {
     out.push('')
-    out.push('  in the worktree, run:')
+    out.push('  then, in the worktree, run:')
     for (const cmd of worktreeSteps) out.push(`    ${cmd}`)
   }
   if (plan.envContents) {

package/src/env/provision.js

@@ -15,6 +15,37 @@ const { portOffset } = require('./registry.js')
 const { renderEnvFile, expandOpenCommand } = require('./render.js')
 const { expandTokens } = require('./resolve.js')
 
+/**
+ * Build the POSIX-sh prefix that puts a command in the spec's worktree, or stops.
+ *
+ * Every command under the "then, in the worktree, run:" heading carries this.
+ * Without it those commands stay silent when run from the wrong place: in the
+ * primary checkout `$m` resolves to the checkout itself, so a seed's source and
+ * target are the same path and it prints `exists — skipped` — indistinguishable
+ * from a correctly-provisioned re-run — while a setup command like an install
+ * runs against the main checkout and "succeeds" too. Three layers then agree that
+ * nothing is wrong, and the caller carries on committing to `main`.
+ *
+ * A `cd` is deliberately chosen over comparing `git rev-parse --show-toplevel`
+ * against `worktreePath`: the planned path is a lexical `path.resolve` while git
+ * reports the symlink-resolved one (`/tmp` vs `/private/tmp` on macOS), so a
+ * string compare would refuse a perfectly good worktree. `cd` sidesteps that, and
+ * does better than refusing — it *positions* the command, so a caller who is in
+ * the wrong directory still gets correct behaviour. When the worktree was never
+ * created — the reported case — the `cd` fails and takes the whole command with
+ * it, non-zero and loud.
+ *
+ * Per-command, not once at the top of the block: a single leading `cd` only
+ * protects the sequence if the caller chains it with `&&`, and the reported
+ * failure is precisely a caller that ran the steps as separate statements.
+ */
+function worktreeCd(worktreePath) {
+  return (
+    `cd "${worktreePath}" 2>/dev/null || ` +
+    `{ echo "no worktree at ${worktreePath} — run the provisioning commands first"; exit 1; }`
+  )
+}
+
 /**
  * Build one idempotent POSIX-sh command that seeds a gitignored file from the
  * main checkout into the current worktree (the cwd when the skill runs it).
@@ -84,13 +115,18 @@ function planUp(spec, alloc, config) {
   // config ⇒ no commands ⇒ current behaviour.
   const seed = config.seedFiles || { mode: 'symlink', files: [] }
   const seedMode = seed.mode === 'copy' ? 'copy' : 'symlink'
-  const seedCommands = (seed.files || []).map((file) => seedCommandFor(file, seedMode))
+  const guard = worktreeCd(spec.worktreePath)
+  const seedCommands = (seed.files || []).map(
+    (file) => `${guard}; ${seedCommandFor(file, seedMode)}`,
+  )
 
   // Bootstrap commands run *in the worktree* after `git worktree add` (before
   // Docker/dev), on every provision including re-attach — deps must exist for
   // the worktree to be usable. Kept separate from `commands` (run from the
   // primary checkout root); the CLI prints them under an "in the worktree" head.
-  const setupCommands = (config.setup || []).map((cmd) => expandTokens(cmd, tokens))
+  const setupCommands = (config.setup || []).map(
+    (cmd) => `${guard}; ${expandTokens(cmd, tokens)}`,
+  )
 
   const commands = []
   // Fresh branch → -b; attach an existing branch/slot → plain form (never clobber).
@@ -122,4 +158,4 @@ function planUp(spec, alloc, config) {
   }
 }
 
-module.exports = { planUp, seedCommandFor }
+module.exports = { planUp, seedCommandFor, worktreeCd }

package/src/env/resolve.js

@@ -251,6 +251,7 @@ function resolveSpec(specArg, dir, config, opts = {}) {
 }
 
 module.exports = {
+  BUCKETS,
   resolveSpec,
   resolveBaseBranch,
   resolvePrimaryCheckout,