@skitterbyte/skitterspec 3.0.0 → 7.0.0

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

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

package/assets/core/env.config.md

@@ -52,6 +52,16 @@ 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.

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

@@ -30,6 +30,13 @@ housekeeping below lands on the spec's branch and never on `main`:
   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,

package/package.json

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

package/src/cli.js

@@ -205,6 +205,11 @@ 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) {
+    out.push('')
+    out.push('  in the worktree, run:')
+    for (const cmd of plan.setupCommands) out.push(`    ${cmd}`)
+  }
   if (plan.envContents) {
     out.push('')
     out.push(`  write ${config.docker.envFile} in the worktree:`)

package/src/env/config.js

@@ -16,6 +16,8 @@
  *     worktree: { root, folderPattern },
  *     docker:   { enabled, composeFile, projectNamePattern, portBase,
  *                 portsPerSpec, envFile, backupCommand },
+ *     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
  *               // servers started on the spec's port block (empty = none)
  *     proxy:    { enabled, host },  // bundled front-door proxy (spec-env connect)
@@ -43,6 +45,10 @@ const DEFAULT_CONFIG = Object.freeze({
     envFile: '.env',
     backupCommand: '',
   }),
+  // 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.
+  setup: Object.freeze([]),
   // Host dev servers started on the spec's port block by `spec-env dev up`.
   // Each: { name, command, portVar, health?, frontPort? }. Default: none.
   dev: Object.freeze([]),
@@ -70,6 +76,7 @@ function defaults() {
   return {
     worktree: { ...DEFAULT_CONFIG.worktree },
     docker: { ...DEFAULT_CONFIG.docker },
+    setup: [],
     dev: [],
     proxy: { ...DEFAULT_CONFIG.proxy },
     open: { ...DEFAULT_CONFIG.open },
@@ -120,6 +127,21 @@ function normalizeDev(parsed) {
   return out
 }
 
+/**
+ * Normalise a parsed `setup` array into bootstrap commands: keep only trimmed,
+ * non-empty strings, drop everything else (lenient, like `normalizeDev`) so a
+ * stray entry can't crash provisioning.
+ */
+function normalizeSetup(parsed) {
+  const out = []
+  for (const raw of parsed) {
+    if (typeof raw !== 'string') continue
+    const cmd = raw.trim()
+    if (cmd) out.push(cmd)
+  }
+  return out
+}
+
 /**
  * Merge a parsed config over the defaults. Only known keys are copied (unknown
  * keys ignored for forward-compat). Nested objects are merged field-by-field.
@@ -142,6 +164,10 @@ function mergeConfig(base, parsed) {
     assign(base.docker, parsed.docker, 'backupCommand', 'string?')
   }
 
+  if (Array.isArray(parsed.setup)) {
+    base.setup = normalizeSetup(parsed.setup)
+  }
+
   if (Array.isArray(parsed.dev)) {
     base.dev = normalizeDev(parsed.dev)
   }

package/src/env/provision.js

@@ -13,6 +13,7 @@
 
 const { portOffset } = require('./registry.js')
 const { renderEnvFile, expandOpenCommand } = require('./render.js')
+const { expandTokens } = require('./resolve.js')
 
 /**
  * Plan a provisioning run.
@@ -23,7 +24,8 @@ const { renderEnvFile, expandOpenCommand } = require('./render.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, attached }
+ *                     envContents, openCommand, commands, setupCommands,
+ *                     attached }
  */
 function planUp(spec, alloc, config) {
   const { slot, attached } = alloc
@@ -41,13 +43,21 @@ function planUp(spec, alloc, config) {
     ? renderEnvFile({ projectName: spec.projectName, portOffset: offset })
     : null
 
-  const openCommand = expandOpenCommand(config.open.command, {
+  const tokens = {
     worktreePath: spec.worktreePath,
     slug: spec.slug,
     branch: spec.branch,
     projectName: spec.projectName,
     portOffset: offset === null ? '' : String(offset),
-  })
+  }
+
+  const openCommand = expandOpenCommand(config.open.command, tokens)
+
+  // 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 commands = []
   // Fresh branch → -b; attach an existing branch/slot → plain form (never clobber).
@@ -69,6 +79,7 @@ function planUp(spec, alloc, config) {
     envContents,
     openCommand,
     commands,
+    setupCommands,
     attached,
   }
 }