@skitterbyte/skitterspec 8.0.1 → 8.3.0

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

@@ -12,6 +12,10 @@
     "envFile": ".env",
     "backupCommand": ""
   },
+  "seedFiles": {
+    "mode": "symlink",
+    "files": [".env"]
+  },
   "setup": [],
   "dev": [],
   "proxy": {

package/assets/core/env.config.md

@@ -52,6 +52,28 @@ no live `env.config.json` was found.
                               // empty = no backup, volumes dropped directly.
   },
 
+  // Gitignored files seeded from the primary checkout into a fresh worktree by
+  // `spec-env up`, right after `git worktree add` and BEFORE `setup` runs — so a
+  // fresh linked worktree (which starts with none of the repo's gitignored files)
+  // has the .env / local secret overrides / local config that setup steps and
+  // git hooks depend on. Without this a step like `prisma generate` hard-fails in
+  // the new worktree because .env (its datasource URL) isn't there.
+  //   mode   "symlink" (default) points the worktree file at the main file, so it
+  //          stays in sync; "copy" makes an independent copy.
+  //   files  repo-relative paths to seed. A source absent in main is a printed
+  //          no-op (not an error); a target that already exists is left untouched
+  //          (idempotent — safe when `spec-env up` re-attaches an existing
+  //          worktree). The main checkout is resolved robustly at run time via
+  //          `git rev-parse --git-common-dir` — no hardcoded repo name or path.
+  // Shorthand: `"seedFiles": [".env", …]` == `{ "mode": "symlink", "files": […] }`.
+  // Seeded files are gitignored, so they never make the worktree "dirty" and
+  // never block teardown; they vanish with the worktree at `spec-env down`.
+  // [] (or absent) = seed nothing (current behaviour).
+  "seedFiles": {
+    "mode": "symlink",
+    "files": [".env"]
+  },
+
   // 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,

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

@@ -1,6 +1,6 @@
 ---
 name: spec-bug
-description: Investigate a bug, capture it as a Bug-type spec, and drive it red→green. ALWAYS starts by reproducing the bug with a failing test, then writes the spec and works the test to green. Creates specs/in-progress/bug-<name>/00-overview.md. Use when the user reports a bug, says "/spec-bug", "investigate this bug", "this is broken — find and fix it", or pastes an error/stack trace.
+description: Investigate a bug, capture it as a Bug-type spec, and drive it red→green. When per-spec isolation is enabled it provisions a worktree first, so the failing test and fix land on the bug's own branch, never on main. ALWAYS starts by reproducing the bug with a failing test, then writes the spec and works the test to green. Creates specs/in-progress/bug-<name>/00-overview.md. Use when the user reports a bug, says "/spec-bug", "investigate this bug", "this is broken — find and fix it", or pastes an error/stack trace.
 ---
 
 # /spec-bug — investigate a bug, prove it with a failing test, fix it
@@ -24,7 +24,49 @@ Bugs are concrete — confirm, don't over-grill. Establish:
   against the broken one (the bug usually lives in the differential). Do NOT
   patch a symptom before you understand the cause.
 
-## 2. Write the failing test FIRST (RED) — mandatory
+## 2. Isolate the fix in a worktree — when isolation is enabled
+
+**Only when per-spec isolation is enabled** (`specs/.core/env.config.json`
+exists). Skip this whole section otherwise — the fix happens in place, on the
+current branch.
+
+**Opt-out:** if the user passes `--no-worktree` (or explicitly asks to work in
+place), skip this whole section and fix on the current branch — same as when
+isolation is off. Warn that the fix will land wherever you currently are (usually
+`main`); reserve it for a trivial one-liner or an explicit request.
+
+A bug fix changes real source, so — exactly like `/spec-go` — it belongs on the
+bug's **own branch**, never directly on `main`. Provision the worktree **now**,
+before the failing test, so the test, the fix, and the spec all land together and
+arrive as one reviewable PR.
+
+The engine resolves a spec by its folder, so seed a **minimal stub** for it to
+provision from — you'll flesh it out in §4:
+
+- From the base branch (`main`), create
+  `specs/in-progress/bug-<name>/00-overview.md` with just the header block and the
+  `## Symptom` you established above.
+- Run `skitterspec spec-env up bug-<name>` (the `spec-env` CLI engine). It prints
+  the `git worktree add … -b bug/<name>` command (a branch forked from `main`),
+  the worktree path, the opener, and any `in the worktree, run:` bootstrap steps.
+- Run the printed `git worktree add`. **The worktree forks from `main`'s last
+  commit, so your uncommitted stub doesn't travel with it** — move it across so
+  `main` is left pristine:
+  `mv specs/in-progress/bug-<name> <worktreePath>/specs/in-progress/`.
+- **Bootstrap the worktree.** A fresh worktree has no installed dependencies and
+  none of the repo's gitignored files (`.env`, local overrides). Run the printed
+  `in the worktree, run:` steps (file seeding, then `setup`) in order, before
+  anything else.
+- **Trust the worktree for this session.** The engine wrote the printed
+  `trusted:` root into `.claude/settings.local.json`, but it won't hot-reload now
+  — run `/add-dir <trusted root>` before editing into the worktree, or the first
+  edits will prompt.
+- **Do everything below in the worktree**, on the branch — the red test, the fix,
+  and the rest of the spec. Act on the worktree with absolute paths /
+  `git -C <worktreePath>`, or open a fresh session rooted there (the printed
+  opener). `main` changes only when the branch merges (at `/spec-complete`).
+
+## 3. Write the failing test FIRST (RED) — mandatory
 
 Encode the **correct** (expected) behaviour as a test, then run it and confirm it
 **fails for the right reason**:
@@ -36,10 +78,13 @@ Encode the **correct** (expected) behaviour as a test, then run it and confirm i
   passes before the fix proves nothing — keep refining the assertion until it
   genuinely captures the bug.
 
-## 3. Write the Bug spec
+## 4. Write the Bug spec
 
-Create the spec **folder** `specs/in-progress/bug-<kebab-name>/` with its entry
-point `00-overview.md` (every spec is a folder — never a bare file). A bug is
+Fill in the spec's entry point `00-overview.md`. **When isolated**, you already
+seeded this stub in §2 and moved it into the worktree — flesh it out there.
+**When not isolated**, create the spec **folder**
+`specs/in-progress/bug-<kebab-name>/` with its entry point `00-overview.md` now
+(every spec is a folder — never a bare file). A bug is
 usually a single-pass fix, so the `## Fix` block can live directly in
 `00-overview.md`. **If the fix needs phasing** (large/uncertain root cause),
 split it into phase files (`01-<slug>.md`, `02-…`) with a phase index in
@@ -90,7 +135,7 @@ The **State log** is the folder/status audit trail; later transitions
 (`/spec-complete`, `/spec-cancel`) append a row. The **Changelog** is for the
 fix narrative and decisions — keep them separate.
 
-## 4. Drive to GREEN
+## 5. Drive to GREEN
 
 - Implement the **minimal, root-cause** fix. Match surrounding code; honour all
   project rules (see `.claude/rules/`).
@@ -103,8 +148,10 @@ test, split the fix into phase files (`01-<slug>.md` …) with a phase index in
 `00-overview.md`, and leave the spec in `in-progress` for `/spec-go` to continue.
 Say so explicitly — don't fake green.
 
-## 5. Report
+## 6. Report
 
 Summarise: root cause, the failing→passing test, the fix, and the full test
 result. The spec stays in `in-progress`; suggest `/spec-complete` to verify and
-archive it. Do **not** `git commit` unless the user asks.
+archive it (**when isolated**, the fix lives on the bug's branch, and
+`/spec-complete` merges it back to `main`). Do **not** `git commit` unless the
+user asks.

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

@@ -26,17 +26,27 @@ Diverting your browser to the spec is a separate explicit step — `/spec-connec
 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`:
 
+**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 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.
+  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
+  **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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec",
-  "version": "8.0.1",
+  "version": "8.3.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

@@ -212,10 +212,13 @@ function specEnvUp(dir, config, specArg) {
   out.push('  run these:')
   for (const cmd of plan.commands) out.push(`    ${cmd}`)
   if (plan.openCommand) out.push(`    ${plan.openCommand}`)
-  if (plan.setupCommands.length) {
+  // Seed files first (setup may depend on them), then the setup commands —
+  // both run in the worktree, under one heading.
+  const worktreeSteps = [...plan.seedCommands, ...plan.setupCommands]
+  if (worktreeSteps.length) {
     out.push('')
     out.push('  in the worktree, run:')
-    for (const cmd of plan.setupCommands) out.push(`    ${cmd}`)
+    for (const cmd of worktreeSteps) out.push(`    ${cmd}`)
   }
   if (plan.envContents) {
     out.push('')

package/src/env/config.js

@@ -16,6 +16,9 @@
  *     worktree: { root, folderPattern },
  *     docker:   { enabled, composeFile, projectNamePattern, portBase,
  *                 portsPerSpec, envFile, backupCommand },
+ *     seedFiles:{ mode, files } | [ ".env", ... ],  // gitignored files copied/
+ *               // symlinked from the main checkout into a fresh worktree before
+ *               // setup runs (mode: "symlink" default | "copy"); empty = none
  *     setup:    [ "cmd", ... ],  // bootstrap commands run in the worktree right
  *               // after `git worktree add` (e.g. install deps); empty = none
  *     dev:      [ { name, command, portVar, health?, frontPort? } ],  // host dev
@@ -45,6 +48,12 @@ const DEFAULT_CONFIG = Object.freeze({
     envFile: '.env',
     backupCommand: '',
   }),
+  // Gitignored files seeded from the main checkout into a fresh worktree by
+  // `spec-env up`, right after `git worktree add` and before `setup` runs — so a
+  // fresh worktree has the .env / local overrides that setup steps depend on.
+  // `mode` is "symlink" (default, stays in sync with main) or "copy" (an
+  // independent copy). `files` is a list of repo-relative paths. Default: none.
+  seedFiles: Object.freeze({ mode: 'symlink', files: Object.freeze([]) }),
   // Bootstrap commands run in the worktree by `spec-env up`, right after
   // `git worktree add` (before Docker/dev), on every provision. Array of shell
   // strings (e.g. "pnpm install"); {slug}/{branch}/… expand. Default: none.
@@ -76,6 +85,7 @@ function defaults() {
   return {
     worktree: { ...DEFAULT_CONFIG.worktree },
     docker: { ...DEFAULT_CONFIG.docker },
+    seedFiles: { mode: DEFAULT_CONFIG.seedFiles.mode, files: [] },
     setup: [],
     dev: [],
     proxy: { ...DEFAULT_CONFIG.proxy },
@@ -127,6 +137,34 @@ function normalizeDev(parsed) {
   return out
 }
 
+// Keep only trimmed, non-empty strings from an array of file paths (lenient).
+function normalizeFileList(parsed) {
+  const out = []
+  for (const raw of parsed) {
+    if (typeof raw !== 'string') continue
+    const file = raw.trim()
+    if (file) out.push(file)
+  }
+  return out
+}
+
+/**
+ * Normalise a parsed `seedFiles` value into `{ mode, files }`. Accepts two forms:
+ *   - the array shorthand `[".env", ...]` → { mode: 'symlink', files: [...] }
+ *   - the object form `{ mode?, files? }` — `mode` is 'copy' or 'symlink'
+ *     (anything else falls back to 'symlink'); `files` is a list of paths.
+ * Malformed entries are dropped (lenient, like `normalizeSetup`) so a stray
+ * value can't crash provisioning.
+ */
+function normalizeSeedFiles(parsed) {
+  if (Array.isArray(parsed)) {
+    return { mode: 'symlink', files: normalizeFileList(parsed) }
+  }
+  const mode = parsed.mode === 'copy' ? 'copy' : 'symlink'
+  const files = Array.isArray(parsed.files) ? normalizeFileList(parsed.files) : []
+  return { mode, files }
+}
+
 /**
  * Normalise a parsed `setup` array into bootstrap commands: keep only trimmed,
  * non-empty strings, drop everything else (lenient, like `normalizeDev`) so a
@@ -164,6 +202,10 @@ function mergeConfig(base, parsed) {
     assign(base.docker, parsed.docker, 'backupCommand', 'string?')
   }
 
+  if (Array.isArray(parsed.seedFiles) || isObject(parsed.seedFiles)) {
+    base.seedFiles = normalizeSeedFiles(parsed.seedFiles)
+  }
+
   if (Array.isArray(parsed.setup)) {
     base.setup = normalizeSetup(parsed.setup)
   }

package/src/env/provision.js

@@ -15,6 +15,31 @@ const { portOffset } = require('./registry.js')
 const { renderEnvFile, expandOpenCommand } = require('./render.js')
 const { expandTokens } = require('./resolve.js')
 
+/**
+ * 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).
+ *
+ * The main checkout is resolved at run time from inside the worktree via
+ * `git rev-parse --git-common-dir` (absolute `<main>/.git` in a linked worktree)
+ * and its dirname — never a hardcoded repo name or a `../..` hop. The command is
+ * safe to re-run: a source absent in main is a printed no-op, an already-seeded
+ * target (real file or symlink) is left untouched, and only a genuinely missing
+ * target is created. `mode` is 'symlink' (points at main, stays in sync) or
+ * 'copy' (an independent copy). Output mirrors the setup style: `seeded <f> → …`.
+ */
+function seedCommandFor(file, mode) {
+  const op =
+    mode === 'copy'
+      ? `cp "$m/${file}" "${file}"`
+      : `ln -s "$m/${file}" "${file}"`
+  return (
+    'm="$(dirname "$(git rev-parse --git-common-dir)")"; ' +
+    `if [ ! -e "$m/${file}" ]; then echo "seed ${file}: not in main — skipped"; ` +
+    `elif [ -e "${file}" ] || [ -L "${file}" ]; then echo "seed ${file}: exists — skipped"; ` +
+    `else mkdir -p "$(dirname "${file}")" && ${op} && echo "seeded ${file} → $m/${file}"; fi`
+  )
+}
+
 /**
  * Plan a provisioning run.
  *
@@ -24,8 +49,8 @@ const { expandTokens } = require('./resolve.js')
  *                       existed in the registry (re-run → attach, don't clobber).
  * @param {object} config normalised env config.
  * @returns {object} { worktreePath, branch, projectName, slot, portOffset,
- *                     envContents, openCommand, commands, setupCommands,
- *                     attached }
+ *                     envContents, openCommand, commands, seedCommands,
+ *                     setupCommands, attached }
  */
 function planUp(spec, alloc, config) {
   const { slot, attached } = alloc
@@ -53,6 +78,14 @@ function planUp(spec, alloc, config) {
 
   const openCommand = expandOpenCommand(config.open.command, tokens)
 
+  // File seeding runs *in the worktree* after `git worktree add`, before the
+  // setup commands (which may depend on the seeded .env). Each entry becomes an
+  // idempotent shell command resolving the main checkout at run time. Absent
+  // 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))
+
   // 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
@@ -79,9 +112,10 @@ function planUp(spec, alloc, config) {
     envContents,
     openCommand,
     commands,
+    seedCommands,
     setupCommands,
     attached,
   }
 }
 
-module.exports = { planUp }
+module.exports = { planUp, seedCommandFor }