@skitterbyte/skitterspec-linear 2.0.0 → 3.0.1

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-linear",
-  "version": "2.0.0",
+  "version": "3.0.1",
   "description": "Spec-driven development for Claude Code, with Linear hybrid-sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus git-like /spec-status · /spec-pull · /spec-push and the spec-sync CLI. Install this OR the base, not both.",
   "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,6 +212,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:`)
@@ -331,26 +343,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(
@@ -359,14 +368,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`)
@@ -583,6 +597,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,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,
   }
 }

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,