@skitterbyte/skitterspec 15.0.5 → 16.1.0

package/assets/rules/spec-planning.md

@@ -113,6 +113,9 @@ status.
 
 Every spec header carries:
 
+- `> **Name:**` — the spec's folder name (`feat-`/`bug-`/`hotfix-<kebab-name>`).
+  It's the handle you pass to `/spec-go` and the other lifecycle skills, surfaced
+  in the header so it's copy-pasteable without digging for the folder name.
 - `> **Author:**` — who created the spec (set at `/spec` / `/spec-bug`, defaults
   to `git config user.name`).
 - `> **Developer:**` — who implements it (`—` until `/spec-go` starts work, then

package/assets/skills/spec/SKILL.md

@@ -14,6 +14,8 @@ Lifecycle (the governing skills) — status in parentheses:
 `/spec-cancel` (Cancelled). See `.claude/rules/spec-planning.md`. (There is no
 separate grooming command — `/spec` grills to a Ready spec directly.)
 
+
+
 ## Phase A — reach a clear shared understanding (grill first)
 
 Interview the user until requirement AND proposed solution are unambiguous. Do
@@ -73,6 +75,7 @@ the codebase, link rather than duplicate):
 # <Feature title>
 
 > **Type:** Feature
+> **Name:** feat-<kebab-name> (the spec folder name — the handle you paste into `/spec-go`)
 > **Status:** Ready — not started
 > **Author:** <git user.name — `git config user.name`>
 > **Developer:** —
@@ -225,3 +228,5 @@ while the repo stays the source of truth — follow the provider's link steps
 below (nothing to do here without one).
 
 
+
+

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

@@ -13,6 +13,8 @@ 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:
@@ -95,6 +97,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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec",
-  "version": "15.0.5",
+  "version": "16.1.0",
   "description": "Spec-driven development for Claude Code — a tracker-free filesystem workflow: lifecycle skills and per-spec isolation. For Linear sync, install @skitterbyte/skitterspec-linear instead.",
   "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,