@skitterbyte/skitterspec 16.8.0 → 17.0.0

package/src/env/teardown.js

@@ -105,7 +105,7 @@ function planDown(spec, config, flags, ctx) {
   // different question from ours: it also declines a branch that is ahead of its
   // upstream ref, reporting `not yet merged to refs/remotes/origin/<branch>,
   // even though it is merged to HEAD`. That fires on the ordinary spec flow —
-  // `/spec-go` pushes the branch when it provisions, and the phase commits after
+  // `/spec-start` pushes the branch when it provisions, and the phase commits after
   // it are landed locally rather than pushed — so teardown meets a branch whose
   // every commit is on `main` and `-d` refuses it. `merged` (HEAD is an ancestor
   // of base) already establishes what we actually care about, and establishes it
@@ -122,7 +122,7 @@ function planDown(spec, config, flags, ctx) {
 
   // --- delete the branch on the remote (planned, never run here) ---
   //
-  // `/spec-go` pushes the branch at provision time, so a completed spec otherwise
+  // `/spec-start` pushes the branch at provision time, so a completed spec otherwise
   // leaves a merged branch on the remote forever. Cleaning that up is the goal;
   // doing it safely is the constraint.
   //
@@ -185,4 +185,42 @@ function blocked(reason) {
   }
 }
 
-module.exports = { planDown }
+/**
+ * Pure teardown planner for CHECKOUT mode.
+ *
+ * There is no worktree to remove, no slot and no volumes — the only thing a
+ * finished spec leaves behind is its branch, and the checkout standing on it.
+ *
+ * Order is load-bearing: git refuses to delete the branch you are on, so the
+ * switch to base must come first. It is also what returns the checkout to a
+ * state the next `spec-env up` will accept.
+ *
+ * The same "are these commits recoverable?" question decides `-d` vs `-D`, and
+ * it is asked exactly as worktree-mode teardown asks it — a landed branch is
+ * safe to force-delete because its commits are on base (or under a tag); an
+ * unlanded one is not, and is refused rather than quietly dropped.
+ *
+ * ctx: { dirty, landed, onBranch, base, checkoutPath }
+ */
+function planDownCheckout(spec, config, flags, ctx) {
+  const { dirty, landed, onBranch, base, checkoutPath } = ctx || {}
+  const force = Boolean(flags && flags.force)
+  const result = { mode: 'checkout', blocked: false, reason: null, commands: [], branch: spec.branch }
+  const block = (reason) => ({ ...result, blocked: true, reason })
+
+  if (!force) {
+    if (config.guards.refuseTeardownIfDirty && dirty) {
+      return block('the checkout has uncommitted changes')
+    }
+    if (!landed) {
+      return block(`${spec.branch} is not merged into ${base} — landing it first is what makes the delete safe`)
+    }
+  }
+
+  const commands = []
+  if (onBranch !== false) commands.push(`git -C ${checkoutPath} switch ${base}`)
+  commands.push(`git -C ${checkoutPath} branch ${landed ? '-D' : '-d'} ${spec.branch}`)
+  return { ...result, commands }
+}
+
+module.exports = { planDown, planDownCheckout }

package/src/init.js

@@ -423,18 +423,24 @@ function installCore(dir, opts) {
 }
 
 // Activate opt-in per-spec isolation: write specs/.core/env.config.json from the
-// example asset so /spec-go provisions a worktree for every in-progress spec.
+// example asset so /spec-start provisions a worktree for every in-progress spec.
 // Only called when the operator opts in, and never on `update` (adopting isolation
 // is a deliberate choice, not something a re-sync flips on). Idempotent: writeFile
 // never clobbers an existing env.config.json without --force.
-function installIsolation(dir, { enabled }, opts) {
+function installIsolation(dir, { enabled, workspaceMode }, opts) {
   if (!enabled) return
-  copyAsset(
-    dir,
-    path.join('core', 'env.config.json.example'),
-    path.join(dir, 'specs', '.core', 'env.config.json'),
-    opts,
-  )
+  const target = path.join(dir, 'specs', '.core', 'env.config.json')
+  copyAsset(dir, path.join('core', 'env.config.json.example'), target, opts)
+
+  // Only 'checkout' is written; 'worktree' is already what the template says and
+  // what the loader defaults to, so the common path leaves the file untouched.
+  // Guarded by existsSync because copyAsset legitimately declines to overwrite a
+  // config the operator already customized — rewriting it here would undo that.
+  if (workspaceMode === 'checkout' && fs.existsSync(target)) {
+    const parsed = JSON.parse(fs.readFileSync(target, 'utf8'))
+    parsed.mode = 'checkout'
+    fs.writeFileSync(target, `${JSON.stringify(parsed, null, 2)}\n`)
+  }
   trustWorktreeRoot(dir)
 }
 
@@ -673,7 +679,7 @@ function printReport(dir, mode, { diff = false } = {}) {
   const isolationOn = fs.existsSync(path.join(dir, 'specs', '.core', 'env.config.json'))
   const isolationNote = isolationOn
     ? 'Per-spec isolation is ON: every in-progress spec gets its own git worktree' +
-      ' at /spec-go (Docker is a per-spec escalation — set > **Stack:** in the spec).\n'
+      ' at /spec-start (Docker is a per-spec escalation — set > **Stack:** in the spec).\n'
     : 'Per-spec isolation is opt-in: re-run with --isolation (or copy' +
       ' specs/.core/env.config.json.example → env.config.json) to enable it.\n'
   // A provider superset ships its own `spec-<provider>-setup` skill; the base
@@ -696,7 +702,7 @@ function printReport(dir, mode, { diff = false } = {}) {
         ' (it discovers your workspace and writes the config), or see' +
         ' specs/.core/SETUP.md.\n'
   process.stdout.write(
-    '\nDone. Skills resolve as /spec, /spec-go, /spec-complete, /spec-cancel,' +
+    '\nDone. Skills resolve as /spec, /spec-start, /spec-next, /spec-complete,' +
       ' /spec-bug, /spec-review, /spec-init, /spec-connect.\n' +
       'Next: tailor .claude/rules/spec-planning.md + the CLAUDE.md section to this' +
       " project's stack, then run /spec.\n" +
@@ -705,7 +711,10 @@ function printReport(dir, mode, { diff = false } = {}) {
   )
 }
 
-async function init({ dir, force, claudeMd, mode, isolation }) {
+// `mode` here is the INSTALL mode ('init' | 'update'), long-standing and
+// unrelated to the config's own `mode` key — which arrives as `workspaceMode`
+// precisely so the two cannot be confused at a call site.
+async function init({ dir, force, claudeMd, mode, isolation, workspaceMode }) {
   if (!fs.existsSync(dir)) throw new Error(`target dir does not exist: ${dir}`)
   resetReport()
 
@@ -716,7 +725,7 @@ async function init({ dir, force, claudeMd, mode, isolation }) {
   removeRetiredFiles(dir)
   installCore(dir, { force })
   // Adopting isolation writes the live env.config.json — init only, never update.
-  if (mode !== 'update') installIsolation(dir, { enabled: isolation }, { force })
+  if (mode !== 'update') installIsolation(dir, { enabled: isolation, workspaceMode }, { force })
   if (claudeMd) installClaudeMd(dir, { mode })
 
   // Record what we wrote (and migrate a pre-manifest repo) so a later resync can

package/src/prompts.js

@@ -7,7 +7,8 @@
  * test suite never imports the interactive UI.
  *
  * `isolationSeed` pre-fills the per-spec isolation question. Returns
- * `{ isolation }`.
+ * `{ isolation, mode }` — `mode` is only asked when isolation is enabled, and
+ * is `'worktree'` otherwise (the value the config defaults to anyway).
  */
 
 async function promptSetup({ isolationSeed = false } = {}) {
@@ -23,15 +24,42 @@ async function promptSetup({ isolationSeed = false } = {}) {
     {
       type: 'confirm',
       name: 'isolation',
-      message: 'Enable per-spec isolation — a git worktree per spec?',
+      message: 'Enable per-spec isolation — build each spec on its own branch?',
       initial: isolationSeed,
     },
+    {
+      // Only reachable when isolation was accepted: `prev` is the previous
+      // answer, and returning null skips the question entirely.
+      type: (prev) => (prev ? 'select' : null),
+      name: 'mode',
+      message: 'Where should a spec be built?',
+      hint: '- this is the trade, not a preference',
+      initial: 0,
+      choices: [
+        {
+          title: 'Its own worktree (default)',
+          value: 'worktree',
+          description: 'several specs at once, main left free — one terminal session per spec',
+        },
+        {
+          title: 'The checkout you are in',
+          value: 'checkout',
+          description: 'one spec at a time, no second session — your terminal follows the work',
+        },
+      ],
+    },
   ]
 
   const ans = await prompts(questions, { onCancel })
   if (cancelled) throw new Error('Setup cancelled')
 
-  return { isolation: Boolean(ans.isolation) }
+  // Anything other than an explicit 'checkout' resolves to the default, so a
+  // skipped or cancelled-into-default answer can never select the mode that
+  // puts a spec's work in the primary checkout.
+  return {
+    isolation: Boolean(ans.isolation),
+    mode: ans.mode === 'checkout' ? 'checkout' : 'worktree',
+  }
 }
 
 /**

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

@@ -1,190 +0,0 @@
----
-name: spec-go
-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 the **user**
-types — `/spec-connect` (a slash command, not a skill you can invoke).
-
-## 1. Identify the target spec
-
-- If a name/path is given as an argument, use it.
-- Otherwise use the spec **currently in context** (the one just created or
-  discussed). If neither is clear, ask which spec.
-- Locate it by searching `specs/` (check `specs/backlog/` first, then the other
-  buckets). A spec is a `<name>/` folder whose entry point is `00-overview.md`,
-  with **one file per phase** alongside it (`01-<slug>.md`, `02-…`). Legacy specs
-  may be a bare `<name>.md`, or a `00-overview.md` with inline phases — handle
-  those too.
-
-## 2. Move it into development
-
-**Live check first (isolation only).** If per-spec isolation is enabled, before
-provisioning run `skitterspec spec-env live status <name>` and read its `live:`
-line. If it says **`live: yes`**, this spec is already checked out in the
-**primary checkout** (you took it live with `/spec-live`) — **do not provision,
-do not run `spec-env up`, and do not "work in the worktree"**. Its branch lives
-in the primary checkout and its worktree is on a **detached HEAD**, so a commit
-made in the worktree would strand on that detached HEAD and never reach the
-branch. Instead skip the provisioning bullets and step 2b, leave the spec where
-it is, and go straight to **step 4**, implementing the phase **in the primary
-checkout on the branch** — edits and commits there advance the branch, and
-`/spec-complete` lands them. (`spec-env up` refuses while live and says the same.
-To return to an isolated worktree instead, ask the user to type `/spec-live main`
-first, then re-run `/spec-go`.)
-
-**If per-spec isolation is enabled** (`specs/.core/env.config.json` exists), the
-spec **isn't already live** (the check above), and it doesn't already have a
-worktree, provision it **first**, so all the housekeeping below lands on the
-spec's branch and never on `main`:
-
-**Opt-out:** if the user passes `--no-worktree` (or explicitly asks to work in
-place), skip the provisioning bullets below and build on the current branch — the
-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 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 **`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
-  install command). With neither configured there's nothing to run; add
-  `seedFiles`/`setup` if agents keep stalling on a missing `.env` or 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,
-  so run `/add-dir <trusted root>` before editing into the worktree, or the
-  first edits will prompt.
-- **Do the rest in the worktree**, on the branch: open it (the printed opener, or
-  a fresh Claude session rooted there) or, staying in this session, act on the
-  worktree path with absolute paths / `git -C <worktreePath>`. The spec move,
-  header edits **and** the phase's code all happen on the branch — so the spec's
-  evolution travels with the code it describes and lands in one PR. `main` changes
-  only when that branch merges (at `/spec-complete`).
-
-Then move the spec (in the worktree when isolated, in place otherwise):
-
-- If it isn't already under `specs/in-progress/`, move the whole spec folder
-  there. **Use `git mv`** to keep history:
-  `git mv "specs/backlog/<name>" "specs/in-progress/<name>"`.
-  `mkdir -p specs/in-progress` first if needed.
-- Update the **Status** header in the entry point:
-  `> **Status:** In Progress — Phase 1 (started <YYYY-MM-DD>)`.
-- Set the **Developer** header field if it's still `—`: use `git config user.name`.
-- Append a **State log** row:
-  `| <YYYY-MM-DD> | In Progress | in-progress | <git user.name> |`.
-- **When isolated:** commit the move and **push the branch** now — that records
-  the in-progress state for everyone and fires the tracker's automation (when a
-  ticketing provider is linked).
-
-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.)
-
-## 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, the **user** types **`/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. For a **code-only** spec,
-  the lighter **`/spec-live <name>`** reuses the already-running dev server (a
-  branch-switch, no second stack) — `/spec-live main` hands it back. Both are
-  user-only slash commands: tell the user to run one, never try to invoke it.
-
-## 3. Pre-flight — commit prior work
-
-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
-  the numerically previous one) should already be committed. If prior-phase work
-  is still uncommitted, **stop and suggest committing it first** (e.g. via
-  `/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.)
-
-## 4. Implement the phase
-
-Identify the **first unfinished phase** from the `00-overview.md` phase index,
-then open its phase file (`0N-<slug>.md`) — that file holds the tasks. Mark it
-started: set the phase-file heading to `🔄` and its `> **Status:**` to
-`In progress`, and flip the matching row in the overview phase index to `🔄`.
-
-**Then sync with the tracker (only if a provider is installed).** The phase has
-just changed state, so refresh the mirror before the build starts — that is what
-makes the phase show as in progress *while* it is being built rather than only
-once it is over. Without a provider this is a no-op and nothing below changes.
-
-
-
-Then build it, following the project rules in `.claude/rules/*.md` and `CLAUDE.md`:
-
-- Work task by task through the phase file. Make focused edits that match
-  surrounding code.
-- Honour the project's conventions (see `.claude/rules/spec-planning.md` and the
-  rules it links).
-- **Tests are part of the phase, not after it.** Create/extend tests for the
-  work, then run the project's typecheck and test commands. Do not declare the
-  phase done until green.
-- Never hardcode dates in tests; never run destructive commands against a real
-  database — use the project's test database only.
-
-## 5. Record progress
-
-- In the **phase file**: tick completed tasks (`- [x]`), flip its heading to `✅`,
-  and set its `> **Status:**` to `Done`.
-- In **`00-overview.md`**: flip the matching phase-index row to `✅`.
-- If anything changed from the plan (a decision, a deviation, a discovered
-  constraint), add a dated **Changelog** entry in `00-overview.md`.
-- If new work surfaced, add it as tasks to the appropriate phase file (or add a
-  new phase file + index row) rather than doing it silently.
-
-**Then refresh the mirror (only if a provider is installed).** The phase is done
-in the repo now; leaving the tracker to catch up at `/spec-complete` is what makes
-a mirror lag a whole spec behind. Without a provider this is a no-op.
-
-
-
-## 6. Report
-
-Summarise what was implemented, the test result (quote failures if any), and
-which phase is next. Do **not** `git commit` unless the user asks — finish,
-verify, and wait.