@skitterbyte/skitterspec 8.0.0 → 8.1.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-go/SKILL.md

@@ -31,12 +31,16 @@ housekeeping below lands on the spec's branch and never on `main`:
   `> **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.0",
+  "version": "8.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

@@ -17,7 +17,14 @@ const {
   freeSlot,
   portOffset,
 } = require('./env/registry.js')
-const { resolveSpec, resolveBaseBranch, repoInfo, expandTokens, splitPrefix } = require('./env/resolve.js')
+const {
+  resolveSpec,
+  resolveBaseBranch,
+  resolvePrimaryCheckout,
+  repoInfo,
+  expandTokens,
+  splitPrefix,
+} = require('./env/resolve.js')
 const { ensureWorktreeDirTrusted } = require('./env/trust.js')
 const { planUp } = require('./env/provision.js')
 const { planDown } = require('./env/teardown.js')
@@ -205,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('')
@@ -336,26 +346,23 @@ function specEnvIntegrate(dir, config, specArg) {
     return
   }
 
-  // /spec-complete runs this from inside the worktree, but the spec's coordinates
-  // (worktreePath via {repo}, the base branch) must resolve against the PRIMARY
-  // checkout. Resolve it first (parent of the shared git dir) and anchor
-  // everything to it, so integrate works whether invoked from main or a worktree.
-  const commonDir = gitReader(dir)(['rev-parse', '--git-common-dir'])
-  const mainRepoPath = commonDir ? path.dirname(path.resolve(dir, commonDir)) : dir
-
+  // `dir` is already anchored on the primary checkout by the dispatch, so it is
+  // both where the spec resolves and the target of the fast-forward — /spec-complete
+  // can run this from inside the worktree and still land on main.
+  //
   // A spec authored entirely on its branch may not exist in the primary
   // checkout's specs/** (it was never committed to base) — but its worktree
   // does, and the worktree path is derivable from config without the folder.
   // Offer it as a fallback search location so integrate can still find the spec.
   const { slug } = splitPrefix(path.basename(specArg))
-  const { repo, repoSlug } = repoInfo(mainRepoPath)
+  const { repo, repoSlug } = repoInfo(dir)
   const wtTokens = { repo, repoSlug, slug }
   const worktreeGuess = path.resolve(
-    mainRepoPath,
+    dir,
     expandTokens(config.worktree.root, wtTokens),
     expandTokens(config.worktree.folderPattern, wtTokens),
   )
-  const spec = resolveSpec(specArg, mainRepoPath, config, { searchDirs: [worktreeGuess] })
+  const spec = resolveSpec(specArg, dir, config, { searchDirs: [worktreeGuess] })
 
   if (!fs.existsSync(spec.worktreePath)) {
     process.stdout.write(
@@ -364,14 +371,19 @@ function specEnvIntegrate(dir, config, specArg) {
     return
   }
 
-  const base = resolveBaseBranch(config, gitReader(mainRepoPath))
+  const base = resolveBaseBranch(config, gitReader(dir))
   const wtGit = gitReader(spec.worktreePath)
   const status = wtGit(['status', '--porcelain'])
   const dirty = status !== null && status.length > 0
   const ahead = wtGit(['rev-list', '--count', `${base}..HEAD`])
   const aheadOfBase = ahead !== null && Number(ahead) > 0
 
-  const plan = planIntegrate(spec, config, { worktreeState: { dirty }, base, aheadOfBase, mainRepoPath })
+  const plan = planIntegrate(spec, config, {
+    worktreeState: { dirty },
+    base,
+    aheadOfBase,
+    mainRepoPath: dir,
+  })
 
   if (plan.blocked) {
     process.stdout.write(`spec-env integrate: blocked — ${plan.reason}.\n`)
@@ -588,6 +600,9 @@ async function specEnv(rest) {
     else positional.push(args[i])
   }
   dir = path.resolve(dir)
+  // Anchor on the primary checkout so every subcommand resolves {repo}, worktree
+  // paths, and the registry identically whether run from main or a worktree.
+  dir = resolvePrimaryCheckout(dir, gitReader(dir))
 
   const { config, present } = loadEnvConfig(dir)
   if (!present) {

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 }

package/src/env/resolve.js

@@ -151,6 +151,20 @@ function resolveBaseBranch(config, git) {
   return 'main'
 }
 
+/**
+ * Resolve `dir` to the primary checkout root — the parent of the shared git dir.
+ * From the primary checkout `git rev-parse --git-common-dir` is `.git` (relative),
+ * so the parent is `dir`; from a linked worktree it's the absolute `<main>/.git`,
+ * so the parent is `<main>`. Anchoring every `spec-env` command here means they
+ * resolve `{repo}` / worktree paths / the registry identically whether run from
+ * `main` or a worktree. `git(args)` returns trimmed stdout or `null` (not a repo)
+ * — injected for testability; a `null` degrades to `dir` (today's behaviour).
+ */
+function resolvePrimaryCheckout(dir, git) {
+  const common = git(['rev-parse', '--git-common-dir'])
+  return common ? path.dirname(path.resolve(dir, common)) : dir
+}
+
 /**
  * Resolve a spec argument to its identity + isolation coordinates.
  * Throws a clear Error when the spec folder can't be found.
@@ -193,6 +207,7 @@ function resolveSpec(specArg, dir, config, opts = {}) {
 module.exports = {
   resolveSpec,
   resolveBaseBranch,
+  resolvePrimaryCheckout,
   branchFor,
   splitPrefix,
   repoInfo,