@skitterbyte/skitterspec 2.0.1 → 7.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Reuben Greaves
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,10 +1,18 @@
 # @skitterbyte/skitterspec
 
 Spec-driven development for [Claude Code](https://claude.com/claude-code) — a
-**tracker-free** filesystem workflow. Ships the spec-lifecycle skills (`/spec`,
-`/spec-ready`, `/spec-go`, `/spec-complete`, `/spec-cancel`, `/spec-bug`,
-`/spec-init`) and per-spec **isolation** (a git worktree per in-progress spec,
-Docker on demand).
+**tracker-free** filesystem workflow. The everyday loop is five verbs:
+
+```
+/spec  →  /spec-go  →  /spec-connect  →  /commit  →  /spec-complete
+ plan      build it     test it live      save it     finish + land
+```
+
+Ships the spec-lifecycle skills (`/spec`, `/spec-go`, `/spec-complete`,
+`/spec-cancel`, `/spec-bug`, `/spec-review`, `/spec-init`) plus per-spec
+**isolation** — a git worktree per in-progress spec, Docker on demand, host dev
+servers on reserved ports, and `/spec-connect` to test a worktree at your normal
+`localhost` URL.
 
 ```sh
 npx @skitterbyte/skitterspec init
@@ -25,6 +33,25 @@ Ticketing sync is a **separate superset you install instead of this one**:
 
 Install exactly one — the superset is a strict superset of this package.
 
+## Testing UI/API worktrees — `/spec-connect`
+
+When your app runs from `main` on `localhost`, a worktree's changes are
+unreachable. Add a `dev` block to `specs/.core/env.config.json` listing your host
+dev servers (each `{ name, command, portVar, health?, frontPort? }`); `/spec-go`
+starts them on the spec's reserved ports, and **`/spec-connect <name>`** points
+your canonical `localhost` ports at that spec (via a small bundled reverse proxy —
+no external install), so you test at the exact URL you always use.
+`/spec-connect main` hands the ports back. Exclusive: one spec at a time. See
+`specs/.core/env.config.md` for the `dev`/`proxy` config.
+
+## v3 — slimmer surface + `/spec-connect`
+
+**3.0** folds provisioning into `/spec-go`, teardown into
+`/spec-complete`·`/spec-cancel`, and grooming into `/spec` — removing the
+`/spec-env`, `/spec-env-down`, and `/spec-ready` skills (the `skitterspec
+spec-env` CLI engine stays). It adds `/spec-connect` and the `dev`/`proxy` config
+blocks. See [MIGRATION.md](../../MIGRATION.md).
+
 ## v2 — Linear removed from the base
 
 `@skitterbyte/skitterspec` **2.0** is tracker-free: the Linear sync skills, the

package/assets/claude-md-section.md

@@ -1,17 +1,18 @@
 ## Spec workflow
 
-Spec-driven development runs through eight skills — use them so structure and
-lifecycle stay consistent (see `.claude/rules/spec-planning.md`):
+Spec-driven development runs through seven lifecycle skills (plus `/spec-connect`
+when isolation is on) — use them so structure and lifecycle stay consistent (see
+`.claude/rules/spec-planning.md`). The everyday loop is
+**`spec → go → connect → commit → complete`**:
 
 | Skill | Action | Status | Folder |
 |-------|--------|--------|--------|
-| `/spec` | (Feature) Grill to a clear shared understanding, then write a concise spec | `Draft` | `specs/backlog/` |
+| `/spec` | (Feature) Grill to a shared understanding, then write a groomed spec | `Ready` (or `Draft`) | `specs/backlog/` |
 | `/spec-bug` | (Bug) Reproduce with a failing test, capture spec, drive red→green | `In Progress` | `specs/in-progress/` |
-| `/spec-ready` | Confirm the spec is groomed (no open questions, phases + tests defined) | `Ready` | `specs/backlog/` |
 | `/spec-review` | Re-validate a spec against the codebase; refresh stale parts | `—` | (unchanged) |
-| `/spec-go` | Implement the next phase (with tests) | `In Progress` | `specs/in-progress/` |
-| `/spec-complete` | Verify all phases done + tests green | `Complete` | `specs/complete/` |
-| `/spec-cancel` | Record progress, stamp a reason on the header | `Cancelled` | `specs/cancelled/` |
+| `/spec-go` | Provision the env, bring dev servers up, implement the next phase | `In Progress` | `specs/in-progress/` |
+| `/spec-complete` | Verify all phases done + tests green; land + tear down | `Complete` | `specs/complete/` |
+| `/spec-cancel` | Record progress, stamp a reason; tear down | `Cancelled` | `specs/cancelled/` |
 | `/spec-init` | Bootstrap/repair this workflow in a project (idempotent) | — | — |
 
 Every spec has a **type** (`> **Type:** Feature\|Bug`) and a filename prefix
@@ -30,10 +31,13 @@ State log.
 **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.
+parallel specs, no stashing, `main` left free — and brings up the project's host
+**dev servers** (`env.config` → `dev`) on the spec's ports. **`/spec-connect
+<name>`** then exposes that spec on your canonical `localhost` ports so you can
+test it at the normal URL (`/spec-connect main` hands them back). 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. Teardown is folded into **`/spec-complete`** ·
+**`/spec-cancel`**; beneath the skills, `skitterspec spec-env
+<up|down|dev|connect|integrate>` is the CLI engine. Independent of lifecycle
+status; inactive when `env.config.json` is absent.

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

@@ -12,6 +12,12 @@
     "envFile": ".env",
     "backupCommand": ""
   },
+  "setup": [],
+  "dev": [],
+  "proxy": {
+    "enabled": true,
+    "host": "127.0.0.1"
+  },
   "open": {
     "command": ""
   },

package/assets/core/env.config.md

@@ -1,8 +1,11 @@
 # `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.
+stack + host dev servers + a front-door proxy + an optional opener per
+in-progress spec). Provisioning is folded into `/spec-go`, teardown into
+`/spec-complete` · `/spec-cancel`, and traffic diversion is `/spec-connect`; the
+`skitterspec spec-env <up|down|dev|connect|integrate>` CLI is the engine beneath
+them.
 
 **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-
@@ -49,6 +52,40 @@ no live `env.config.json` was found.
                               // empty = no backup, volumes dropped directly.
   },
 
+  // Bootstrap commands `spec-env up <spec>` runs IN the worktree, right after
+  // `git worktree add` (before Docker/dev), on every provision including
+  // re-attach — so a fresh worktree's dependencies exist and git hooks,
+  // typechecks, builds and tests work immediately instead of failing on a
+  // missing node_modules. An array, run in order; [] = none. Each string is a
+  // shell command; {slug}/{branch}/{worktreePath}/{projectName}/{portOffset}
+  // expand (the cwd is already the worktree, so {worktreePath} is usually
+  // redundant). Example: ["pnpm install --frozen-lockfile"].
+  "setup": [],
+
+  // Host dev servers `spec-env dev up <spec>` starts on the spec's port block
+  // (for apps that run via `pnpm dev` on the host, not inside the Docker stack).
+  // An array so UI + API (or more) are supervised independently; [] = none.
+  // Each entry:
+  //   name       label used in logs/pid files (.spec-env/{logs,pids}/<spec>-<name>).
+  //   command    the launch command, run detached in the worktree. {portVar} and
+  //              {port} expand to the process's resolved port.
+  //   portVar    env var the command reads for its port; injected into its env.
+  //              Process i in the block gets portBase + slot*portsPerSpec + i.
+  //   health     optional URL polled until it answers before reporting ready;
+  //              {portVar}/{port} expand here too. Omit for no health gate.
+  //   frontPort  optional canonical origin this process fronts (e.g. 3000 for the
+  //              UI, 8080 for the API) — used by the proxy to route to it.
+  "dev": [],
+
+  // Front-door proxy for `spec-env connect <spec>` — a small bundled Node
+  // reverse proxy (no external install) that exposes ONE connected spec's
+  // frontPort dev servers on the canonical ports. Exclusive: one target at a
+  // time. `connect main` stops it so the primary checkout owns the ports again.
+  "proxy": {
+    "enabled": true,        // false = the connect command is unavailable
+    "host": "127.0.0.1"     // bind host for the canonical ports
+  },
+
   // 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).

package/assets/rules/spec-planning.md

@@ -1,22 +1,23 @@
 # Spec Planning
 
-Spec-driven development is driven by eight skills — use them rather than
-hand-rolling specs so the structure and lifecycle stay consistent. Each sets a
-status on the spec header (`> **Status:** …`):
+Spec-driven development is driven by seven lifecycle skills (plus `/spec-connect`
+when isolation is on) — use them rather than hand-rolling specs so the structure
+and lifecycle stay consistent. Each sets a status on the spec header
+(`> **Status:** …`):
 
 | Skill | Purpose | Status | Folder |
 |-------|---------|--------|--------|
-| `/spec` | (Feature) Grill to a clear shared understanding, then write a new spec | `Draft` | `specs/backlog/` |
+| `/spec` | (Feature) Grill to a clear shared understanding, then write a groomed spec | `Ready` (or `Draft`) | `specs/backlog/` |
 | `/spec-bug` | (Bug) Reproduce with a failing test, capture spec, drive red→green | `In Progress` | `specs/in-progress/` |
-| `/spec-ready` | Confirm it's groomed (no open questions, phases + tests defined) | `Ready` | `specs/backlog/` |
 | `/spec-review` | Re-validate a spec against the codebase; refresh stale parts | `—` | (unchanged) |
-| `/spec-go` | Implement the next phase (with tests) | `In Progress` | `specs/in-progress/` |
-| `/spec-complete` | Verify all phases done + tests green | `Complete` | `specs/complete/` |
-| `/spec-cancel` | Record progress, stamp a reason on the header | `Cancelled` | `specs/cancelled/` |
+| `/spec-go` | Provision the env, bring dev servers up, implement the next phase | `In Progress` | `specs/in-progress/` |
+| `/spec-complete` | Verify all phases done + tests green; land + tear down | `Complete` | `specs/complete/` |
+| `/spec-cancel` | Record progress, stamp a reason on the header; tear down | `Cancelled` | `specs/cancelled/` |
 | `/spec-init` | Bootstrap/repair this workflow in a project (idempotent) | — | — |
 
-Status flow: `Draft → Ready → In Progress → Complete` (or `Cancelled` from any
-state). `/spec-ready` is a grooming gate only — it does not move the folder.
+Status flow: `Ready → In Progress → Complete` (or `Cancelled` from any state).
+`/spec` grills to a **Ready** spec directly — there is no separate grooming
+command; it writes `Draft` only when open questions are deliberately left.
 `/spec-bug` is test-first and starts straight in `In Progress` (work begins
 immediately), so it skips Draft/Ready.
 
@@ -27,12 +28,16 @@ automatically — several specs run side by side without stashing or clashing, a
 `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.
+latter. `/spec-go` also starts the project's host **dev servers** (`env.config`
+→ `dev`) on the spec's ports; **`/spec-connect <name>`** then exposes that spec on
+your canonical `localhost` ports so you can test it at the normal URL
+(`/spec-connect main` hands them back). 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. Teardown is folded into `/spec-complete` ·
+`/spec-cancel`. Beneath the skills, `skitterspec spec-env
+<up|down|dev|connect|integrate>` is the CLI engine. Isolation is **orthogonal to
+lifecycle status** and inactive when `env.config.json` is absent — every skill
+then behaves as it does today.
 
 **Ticketing-provider sync (opt-in, a separate package).** The base is
 tracker-free: it knows nothing about any specific ticketing system. A
@@ -110,7 +115,7 @@ When asked for a plan, implementation strategy, or feature breakdown:
 ## Lifecycle folders
 
 ```
-specs/backlog/       Draft + Ready specs (/spec, /spec-ready)
+specs/backlog/       Ready (or Draft) specs (/spec)
 specs/in-progress/   under active implementation (/spec-go, /spec-bug)
 specs/complete/      finished (/spec-complete)
 specs/cancelled/     abandoned, with a reason on the header (/spec-cancel)

package/assets/skills/spec/SKILL.md

@@ -9,9 +9,10 @@ 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`
+`/spec` (writes **Ready** when fully groomed, else Draft; backlog) → `/spec-go`
 (In Progress, in-progress; implement phase 1) → `/spec-complete` (Complete) /
-`/spec-cancel` (Cancelled). See `.claude/rules/spec-planning.md`.
+`/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)
 
@@ -72,7 +73,7 @@ the codebase, link rather than duplicate):
 # <Feature title>
 
 > **Type:** Feature
-> **Status:** Draft — not started
+> **Status:** Ready — not started
 > **Author:** <git user.name — `git config user.name`>
 > **Developer:** —
 > **Raised:** <YYYY-MM-DD (today)>
@@ -113,7 +114,7 @@ Each phase lives in its own file in this folder. Status: ⬜ not started ·
 
 | Date | Status | Folder | By |
 |------|--------|--------|----|
-| <YYYY-MM-DD> | Draft | backlog | <author> |
+| <YYYY-MM-DD> | Ready | backlog | <author> |
 
 ## Changelog
 
@@ -147,9 +148,9 @@ 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.
+lifecycle skill (`/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:
 
@@ -169,8 +170,10 @@ Rules for the spec body:
 
 ## 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.
+After writing, tell the user the path and that it's **`Ready`** in `backlog`
+(grilling in Phase A resolved the open questions). If you deliberately left open
+questions unresolved, write `Draft` instead and say what still needs deciding.
+Either way, the next step is `/spec-go` to start building.
 
 ## Phase D — record the isolation stack (only if configured)
 
@@ -180,7 +183,7 @@ 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
+run `skitterspec spec-env up <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.
 

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

@@ -52,10 +52,17 @@ move the whole folder).
 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)
+## 7. Tear down the environment (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`).
+reclaim the cancelled spec's environment. On confirmation, run the `spec-env` CLI
+directly (the old `/spec-env-down` skill is gone — teardown is folded in here):
+
+1. If `.spec-env/connected` names this spec, run `skitterspec spec-env connect
+   main` first to free the canonical ports.
+2. `skitterspec spec-env dev down <name>` — stop its host dev servers.
+3. `skitterspec spec-env down <name>` — then execute the printed commands to
+   remove the worktree/stack and free the 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

@@ -75,13 +75,21 @@ applies, offer to land the finished branch on the base branch so the work reache
 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)
+## 7. Tear down the environment (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.
+reclaim the finished spec's environment. On confirmation, run the `spec-env` CLI
+directly (the old `/spec-env-down` skill is gone — teardown is folded in here):
+
+1. **Disconnect the proxy if this spec is connected.** If `.spec-env/connected`
+   names this spec, run `skitterspec spec-env connect main` first so the
+   canonical ports go back to the primary checkout.
+2. **Stop its host dev servers:** `skitterspec spec-env dev down <name>` (a
+   no-op when none are running / configured).
+3. **Remove worktree + stack + slot:** run `skitterspec spec-env down <name>`
+   and execute the commands it prints, in order. 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-connect/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: spec-connect
+description: Point your local canonical origin (localhost:3000/:8080) at a spec's running dev servers so you can test a worktree's UI/API changes at the normal URL — or `spec-connect main` to hand the ports back to your main checkout. Runs `skitterspec spec-env connect` (a small bundled reverse proxy). Opt-in — needs specs/.core/env.config.json with a `dev` block. Use when the user says "/spec-connect", "test <spec> locally", "point local at <spec>", or "connect to <spec>".
+---
+
+# /spec-connect — expose one spec on the canonical ports
+
+Make `http://localhost:<frontPort>` serve a **spec's** warm dev servers instead of
+your main checkout's, so you can test a worktree's UI/API at the exact URL you
+always use — no bookmark, base-URL, or OAuth-callback changes. **Exclusive:** one
+spec is exposed at a time. `spec-connect main` stops the proxy and hands the ports
+back to your primary checkout.
+
+This skill is **opt-in**: it needs `specs/.core/env.config.json` with a `dev`
+block (host dev servers + their `frontPort`s). If isolation or `dev` is absent,
+say so and stop.
+
+## 1. Identify the target
+
+- Use the spec named as an argument. The literal `main` means **disconnect**
+  (hand the ports back to the primary checkout). Else use the spec **currently in
+  context**; if unclear, ask.
+
+## 2. Make sure the spec's dev servers are running
+
+`connect` proxies to a spec's dev servers on its reserved port block — it does
+**not** start them. If they aren't up yet, start them first:
+
+```
+skitterspec spec-env dev up <spec>
+```
+
+(This is automatic under `/spec-go`; run it by hand only when connecting a spec
+whose servers you stopped.)
+
+## 3. Connect (or disconnect)
+
+```
+skitterspec spec-env connect <spec>     # expose <spec> on the canonical ports
+skitterspec spec-env connect main       # stop the proxy — main owns the ports
+```
+
+The engine (re)starts a small bundled Node reverse proxy and **prints** the
+canonical URL → spec-port mapping. **If it reports a canonical port is in use**,
+your **main dev server still holds it** — stop main on that port, then re-run
+(the proxy can't share a port main is bound to). Relay the printed message.
+
+## 4. Report
+
+Echo which spec is now on the canonical ports (and the URLs), or that the proxy
+was stopped and main owns them again. Switching to a different spec is just
+`spec-connect <other>` — the dev servers stay warm, so it's a near-instant
+re-point.

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

@@ -1,10 +1,14 @@
 ---
 name: spec-go
-description: Promote a spec into active development and implement its first phase. Moves the spec from backlog into specs/in-progress/, then builds phase 1 with tests. Targets a spec by name (arg) or the spec currently in context. Use when the user says "/spec-go", "start this spec", "begin implementing <spec>", or "let's build the next phase".
+description: Promote a spec into active development and build the next phase — provisions its worktree, brings up its host dev servers (confirm first), then implements the phase with tests. Targets a spec by name (arg) or the spec currently in context. Use when the user says "/spec-go", "start this spec", "begin implementing <spec>", or "let's build the next phase".
 ---
 
 # /spec-go — start (or continue) implementing a spec
 
+The "up" button: it promotes the spec, provisions its worktree, brings its host
+dev servers up on the spec's reserved ports (with your OK), then builds the phase.
+Diverting your browser to the spec is a separate explicit step — `/spec-connect`.
+
 ## 1. Identify the target spec
 
 - If a name/path is given as an argument, use it.
@@ -22,10 +26,17 @@ description: Promote a spec into active development and implement its first phas
 the spec doesn't already have a worktree, provision it **first**, so all the
 housekeeping below lands on the spec's branch and never on `main`:
 
-- Run `skitterspec spec-env up <name>` (the `/spec-env` engine). It adds a git
+- 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.
   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 — so git hooks, typechecks, builds and
+  tests fail until they're installed. `spec-env up` prints the project's
+  configured **`in the worktree, run:`** commands (from `env.config.json` →
+  `setup`, e.g. an install command) — run them in the worktree before doing
+  anything else. With no `setup` configured there's nothing to run; set one up if
+  agents keep stalling on missing dependencies.
 - **Trust the worktree for this session.** The engine wrote the printed
   `trusted:` root into `.claude/settings.local.json` (gitignored) so future
   sessions trust it automatically — but that file likely won't hot-reload now,
@@ -53,17 +64,35 @@ Then move the spec (in the worktree when isolated, in place otherwise):
   the in-progress state for everyone and fires the tracker's automation (when a
   ticketing provider is linked).
 
-A spec ideally reaches here as `Ready` (via `/spec-ready`), but `/spec-go` works
-on a `Draft` too — just sanity-check it's well-formed before building.
+A spec ideally reaches here already `Ready` (written by `/spec`), but `/spec-go`
+works on a `Draft` too — just sanity-check it's well-formed before building.
 
 If the spec is already in `in-progress`, skip the move and implement the **next
 unfinished phase** instead of Phase 1. (When isolated, subsequent `/spec-go` runs
 happen from inside the worktree — where the spec already sits in `in-progress` on
 the branch — and a re-run of `spec-env up` just re-attaches it.)
 
-## 3. Pre-flight — commit prior work, then compact
+## 2b. Bring the spec's dev servers up — confirm before heavy steps
+
+**Only when isolation is enabled and the project configures host dev servers**
+(`env.config.json` → a non-empty `dev` array). This is what makes the spec
+runnable — its UI/API on the spec's reserved port block, isolated from `main`.
+
+- **Show the plan and get a yes first.** List what will start: the per-process
+  dev commands, the ports they'll bind (the spec's slot block), and any Docker
+  stack. Don't start heavy processes silently. If the user passed **`--plan`**,
+  print this plan and **stop** (preview only).
+- On confirmation, run `skitterspec spec-env dev up <name>` — it launches each
+  dev process detached on its port, logs to `.spec-env/logs/`, and waits on each
+  `health` check. With no `dev` configured it's a clean no-op; skip this step.
+- **Diverting your browser is a separate step.** To test the spec at your normal
+  `localhost` URL, run **`/spec-connect <name>`** (exclusive — it exposes this
+  spec on the canonical ports; `/spec-connect main` hands them back). `/spec-go`
+  never seizes the canonical ports on its own.
+
+## 3. Pre-flight — commit prior work
 
-Before writing any code for this phase, get the workspace and context clean:
+Before writing any code for this phase, get the workspace clean:
 
 - **Confirm the last-worked phase is committed.** Run `git status` and
   `git log --oneline -5`. The most recently *implemented* phase (not necessarily
@@ -72,10 +101,6 @@ Before writing any code for this phase, get the workspace and context clean:
   `/commit`) so each phase lands as its own reviewable commit — don't build the
   next phase on top of an uncommitted one. (Skip if this is the first phase —
   there's nothing prior to commit.)
-- **Compact, then continue.** Recommend the user run `/compact` now. A fresh,
-  minimal context keeps the phase focused and avoids drift from earlier turns;
-  the spec file on disk is the source of truth, so nothing is lost. Pause for the
-  `/compact`, then implement the phase.
 
 ## 3b. Pull from the tracker first (only if a provider is installed)
 

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

@@ -65,5 +65,5 @@ reading the code, do that instead of asking.
 ## 5. Report
 
 Summarise the drift found, what you changed, any questions still open, and
-whether the spec is now safe to `/spec-go` (or needs `/spec-ready` again). Do
-**not** `git commit` unless the user asks.
+whether the spec is now safe to `/spec-go` (or should drop back to `Draft` until
+the open questions are resolved). Do **not** `git commit` unless the user asks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec",
-  "version": "2.0.1",
+  "version": "7.0.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",
@@ -27,11 +27,9 @@
   "dependencies": {
     "prompts": "^2.4.2"
   },
-  "scripts": {
-    "prepack": "node ../../scripts/build-dist.js skitterspec"
-  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/skitterbyte/skitterspec.git"
-  }
-}
+  },
+  "scripts": {}
+}