@skitterbyte/skitterspec-linear 10.5.2 → 10.7.0

package/src/cli.js

@@ -185,23 +185,48 @@ async function cleanupReleaseTooling(dir, opts) {
 
 // --- spec-env: per-spec isolation engine (Phase 1: status + resolve) --------
 
-// Print provisioned specs, their slots, and port blocks from the registry.
+/**
+ * Print what is provisioned: every spec that owns a git worktree, with its slot
+ * and port block when it has one.
+ *
+ * The worktree — not the slot registry — is what "provisioned" means. `specEnvUp`
+ * allocates a slot only when `wantsDocker`, so a `Stack: worktree` spec never
+ * enters the registry and a project with `docker.enabled: false` has an
+ * permanently empty one. Reading the registry alone reported `no provisioned
+ * specs` while worktrees were standing.
+ *
+ * The registry is still read, but only to ANNOTATE a spec that has a slot — it
+ * is the authority on port blocks and nothing else.
+ *
+ * BLIND SPOT: a worktree removed behind git's back (`rm -rf` without
+ * `git worktree prune`) stays listed until pruned. That over-reports, which is
+ * the harmless direction for a read-only report.
+ */
 function specEnvStatus(dir, config) {
-  const registry = readRegistry(dir, config)
-  const names = Object.keys(registry.slots)
-  if (!names.length) {
+  const worktreePaths = liveWorktreePaths(dir)
+  const provisioned = allSpecs(dir, config, worktreePaths)
+    .map((s) => ({ folder: s.folder, wt: path.resolve(s.worktreePath) }))
+    // The primary checkout is itself in `git worktree list`; a spec is
+    // provisioned only when it has its OWN worktree, separate from it.
+    .filter((s) => s.wt !== dir && worktreePaths.has(s.wt))
+    .sort((a, b) => a.folder.localeCompare(b.folder))
+
+  if (!provisioned.length) {
     process.stdout.write('spec-env: no provisioned specs.\n')
     return
   }
+
+  const registry = readRegistry(dir, config)
   process.stdout.write('Provisioned specs:\n')
-  names
-    .sort((a, b) => registry.slots[a] - registry.slots[b])
-    .forEach((name) => {
-      const slot = registry.slots[name]
+  for (const { folder, wt } of provisioned) {
+    const slot = registry.slots[folder]
+    let ports = ''
+    if (slot !== undefined) {
       const off = portOffset(slot, config)
-      const hi = off + config.docker.portsPerSpec - 1
-      process.stdout.write(`  ${name}  slot ${slot}  ports ${off}-${hi}\n`)
-    })
+      ports = `  slot ${slot}  ports ${off}-${off + config.docker.portsPerSpec - 1}`
+    }
+    process.stdout.write(`  ${folder}${ports}\n    ${path.relative(dir, wt) || wt}\n`)
+  }
 }
 
 // Plan a provision: allocate the slot, persist the registry, and print the plan
@@ -209,10 +234,6 @@ function specEnvStatus(dir, config) {
 // opener). This creates no worktree and starts no stack — the caller runs the
 // printed commands. Keep the output's verb honest about that.
 function specEnvUp(dir, config, specArg) {
-  if (!specArg) {
-    process.stdout.write('Usage: skitterspec spec-env up <spec>\n')
-    return
-  }
   const spec = resolveSpecWithWorktree(dir, config, specArg)
 
   // Live-safe: if this spec is already live on the primary checkout (its branch was
@@ -328,7 +349,7 @@ function gitReader(cwd) {
 // ancestor of it (fully landed), which lets teardown skip the unpushed guard.
 function worktreeGitState(worktreePath, base) {
   if (!fs.existsSync(worktreePath)) {
-    return { dirty: false, unpushed: false, merged: true, reachableFromTag: false }
+    return { dirty: false, unpushed: false, merged: true, reachableFromTag: false, remoteBranch: null }
   }
   const git = gitReader(worktreePath)
 
@@ -357,7 +378,41 @@ function worktreeGitState(worktreePath, base) {
   const pointing = git(['tag', '--points-at', 'HEAD'])
   const reachableFromTag = pointing !== null && pointing.length > 0
 
-  return { dirty, unpushed, merged, reachableFromTag }
+  // remoteBranch = the remote-tracking ref for this worktree's branch when one
+  // actually exists here (e.g. "origin/feat/thing"), else null. Teardown plans a
+  // remote delete off it, so it has to be a ref we can SEE — never an inference
+  // from the branch name, and never a bare assumption that `origin` has it.
+  //
+  // WHAT WOULD FOOL THIS, both left open deliberately:
+  //   * A STALE ref — the branch was deleted from another clone and this one
+  //     hasn't pruned. We plan a delete that no-ops: `git push --delete` errors
+  //     on a branch that isn't there, which is loud, not destructive.
+  //   * A branch pushed FROM ANOTHER MACHINE has no remote-tracking ref here, so
+  //     teardown misses it and the remote branch survives. That is the safe
+  //     direction — under-cleaning. Closing it means `git ls-remote`, which makes
+  //     every teardown network-dependent for what is cosmetic cleanup. Not done.
+  //
+  // Upstream first, so a non-`origin` remote is honoured; `--abbrev-ref` gives the
+  // short ref, and the verify catches an upstream configured for a ref that is
+  // gone. With no upstream (the branch was pushed without `-u`), ask each remote
+  // in turn rather than guessing a name.
+  let remoteBranch = null
+  const upstream = git(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}'])
+  if (upstream && git(['rev-parse', '--verify', '--quiet', `refs/remotes/${upstream}`]) !== null) {
+    remoteBranch = upstream
+  } else {
+    const branch = git(['rev-parse', '--abbrev-ref', 'HEAD'])
+    if (branch && branch !== 'HEAD') {
+      for (const remote of (git(['remote']) || '').split('\n').map((r) => r.trim()).filter(Boolean)) {
+        if (git(['rev-parse', '--verify', '--quiet', `refs/remotes/${remote}/${branch}`]) !== null) {
+          remoteBranch = `${remote}/${branch}`
+          break
+        }
+      }
+    }
+  }
+
+  return { dirty, unpushed, merged, reachableFromTag, remoteBranch }
 }
 
 // A deterministic-enough compact timestamp for backup filenames (CLI-only; the
@@ -376,10 +431,6 @@ function compactTimestamp() {
 // the shared parent of every spec's worktree and harmless when empty; removing it
 // would just re-prompt on the next /spec-go (see spec: isolation-trusts-worktree-dir).
 function specEnvDown(dir, config, specArg, flags) {
-  if (!specArg) {
-    process.stdout.write('Usage: skitterspec spec-env down <spec> [--keep-volumes] [--force]\n')
-    return
-  }
   const spec = resolveSpecWithWorktree(dir, config, specArg)
 
   // A worktree-only spec never held a slot but its worktree still needs removing,
@@ -419,6 +470,15 @@ function specEnvDown(dir, config, specArg, flags) {
   out.push('')
   out.push('  run these:')
   for (const cmd of plan.commands) out.push(`    ${cmd}`)
+  // Kept out of `run these:` on purpose — everything above is local and
+  // reversible-ish, while this reaches a shared remote. The skills ask before
+  // running it; a project that never wants to be asked sets
+  // `teardown.deleteRemoteBranch: "always"`, which folds it in above instead.
+  if (plan.remoteCommands && plan.remoteCommands.length) {
+    out.push('')
+    out.push('  remote branch — confirm with the user first:')
+    for (const cmd of plan.remoteCommands) out.push(`    ${cmd}`)
+  }
   process.stdout.write(out.join('\n') + '\n')
 }
 
@@ -482,6 +542,77 @@ function liveWorktreePaths(dir) {
   return paths
 }
 
+/**
+ * The spec to act on when the caller named none.
+ *
+ * Two signals, strongest first:
+ *
+ *   1. **The worktree you are standing in.** A spec-env verb run from inside a
+ *      spec's worktree means that spec — there is nothing to infer. This is the
+ *      case that carries the feature in practice: several worktrees at once is
+ *      the normal shape of this workflow, so "the only one" rarely resolves.
+ *   2. **The only spec that has a worktree**, when cwd says nothing (you are in
+ *      the primary checkout, or somewhere else entirely).
+ *
+ * `git worktree list` is the authority for both, and deliberately so. Two
+ * nearer-looking signals are wrong here:
+ *
+ *   - The **slot registry** covers only Docker specs — `specEnvUp` allocates a
+ *     slot exclusively when `wantsDocker`, so a `Stack: worktree` spec never
+ *     appears in it and a project with `docker.enabled: false` has a permanently
+ *     empty registry. Absence there says nothing about provisioning.
+ *   - The **`specs/in-progress/` bucket** says a spec is being worked on, not
+ *     that it has a worktree — and git does not track an empty directory, so the
+ *     bucket disappears the moment it empties.
+ *
+ * Three outcomes, never two: resolved → that spec; several candidates and no cwd
+ * hint → throw, listing them; none → throw, pointing at /spec-go. *Cannot tell*
+ * never becomes a guess.
+ *
+ * BLIND SPOT: a spec taken live with `/spec-live` has had its branch moved into
+ * the primary checkout and its worktree left on a detached HEAD — it still has a
+ * worktree, so it is still a candidate, which is correct. What would fool this is
+ * a worktree removed behind git's back (`rm -rf` without `git worktree prune`);
+ * git keeps listing it as prunable. That over-reports rather than under-reports,
+ * so the failure is an ambiguity error, never a wrong spec.
+ */
+function soleProvisionedSpec(dir, config, cwd = process.cwd()) {
+  const worktreePaths = liveWorktreePaths(dir)
+  const provisioned = allSpecs(dir, config, worktreePaths)
+    .map((s) => ({ folder: s.folder, wt: path.resolve(s.worktreePath) }))
+    // The primary checkout is itself in `git worktree list`; a spec is
+    // provisioned only when it has its OWN worktree, separate from it.
+    .filter((s) => s.wt !== dir && worktreePaths.has(s.wt))
+    .sort((a, b) => a.folder.localeCompare(b.folder))
+
+  // 1. Standing inside a spec's worktree names it outright. Deepest match wins,
+  //    so a nested worktree is not shadowed by an ancestor one.
+  let here
+  try {
+    here = fs.realpathSync(path.resolve(cwd))
+  } catch {
+    here = path.resolve(cwd)
+  }
+  const inside = provisioned
+    .filter((s) => here === s.wt || here.startsWith(s.wt + path.sep))
+    .sort((a, b) => b.wt.length - a.wt.length)[0]
+  if (inside) return inside.folder
+
+  // 2. Otherwise only an unambiguous set answers.
+  if (provisioned.length === 1) return provisioned[0].folder
+  if (provisioned.length === 0) {
+    throw new Error(
+      'no spec given, and no spec has a worktree — name one explicitly, or run ' +
+        '/spec-go to provision it.',
+    )
+  }
+  throw new Error(
+    `no spec given, and ${provisioned.length} specs have worktrees — name the one ` +
+      `you mean, or run this from inside one:\n` +
+      provisioned.map((s, i) => `  ${i + 1}. ${s.folder}`).join('\n'),
+  )
+}
+
 // Resolve a spec argument the ONE way every spec-env subcommand resolves it:
 // against the primary checkout first, then the spec's own worktree, then every
 // other checkout git knows about. An in-progress spec is git-mv'd into
@@ -493,6 +624,10 @@ function liveWorktreePaths(dir) {
 // coordinate tokens always expand against `dir` (the primary checkout), so the
 // answer is identical whether the command was run from main or a worktree.
 function resolveSpecWithWorktree(dir, config, specArg) {
+  // Fill in a missing argument first: everything below (starting with
+  // path.basename) assumes a string, and every subcommand that reaches here is
+  // one where a missing spec was previously a usage error.
+  specArg = specArg || soleProvisionedSpec(dir, config)
   const { slug } = splitPrefix(path.basename(specArg))
   const { repo, repoSlug } = repoInfo(dir)
   const wtTokens = { repo, repoSlug, slug }
@@ -604,6 +739,15 @@ function specEnvPrune(dir, config, flags) {
   out.push('')
   out.push('  run these:')
   for (const cmd of plan.commands) out.push(`    ${cmd}`)
+  // Kept out of `run these:` on purpose — everything above is local and
+  // reversible-ish, while this reaches a shared remote. The skills ask before
+  // running it; a project that never wants to be asked sets
+  // `teardown.deleteRemoteBranch: "always"`, which folds it in above instead.
+  if (plan.remoteCommands && plan.remoteCommands.length) {
+    out.push('')
+    out.push('  remote branch — confirm with the user first:')
+    for (const cmd of plan.remoteCommands) out.push(`    ${cmd}`)
+  }
   process.stdout.write(out.join('\n') + '\n')
 }
 
@@ -611,10 +755,6 @@ function specEnvPrune(dir, config, flags) {
 // Queries git for the facts, prints the plan / block / no-op. The /spec-complete
 // skill executes the printed commands (and aborts a conflicting rebase).
 function specEnvIntegrate(dir, config, specArg) {
-  if (!specArg) {
-    process.stdout.write('Usage: skitterspec spec-env integrate <spec>\n')
-    return
-  }
 
   // `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
@@ -734,8 +874,9 @@ function specEnvIntegrate(dir, config, specArg) {
 function specEnvHotfix(dir, config, positional, flags) {
   const action = positional[0]
   const specArg = positional[1]
-  if (action !== 'land' || !specArg) {
-    process.stdout.write('Usage: skitterspec spec-env hotfix land <spec> [--also <tag>]...\n')
+  // The action must be named; the spec may be omitted (resolved from the registry).
+  if (action !== 'land') {
+    process.stdout.write('Usage: skitterspec spec-env hotfix land [spec] [--also <tag>]...\n')
     return
   }
 
@@ -815,10 +956,6 @@ function specEnvHotfix(dir, config, positional, flags) {
 
 // Print the resolved identity/coordinates for a single spec.
 function specEnvResolve(dir, config, specArg) {
-  if (!specArg) {
-    process.stdout.write('Usage: skitterspec spec-env resolve <spec>\n')
-    return
-  }
   const r = resolveSpecWithWorktree(dir, config, specArg)
   process.stdout.write(
     `spec:       ${r.folder} (${r.bucket})\n` +
@@ -836,8 +973,9 @@ function specEnvResolve(dir, config, specArg) {
 async function specEnvDev(dir, config, positional) {
   const action = positional[0]
   const specArg = positional[1]
-  if ((action !== 'up' && action !== 'down') || !specArg) {
-    process.stdout.write('Usage: skitterspec spec-env dev <up|down> <spec>\n')
+  // The action must be named; the spec may be omitted (resolved from the registry).
+  if (action !== 'up' && action !== 'down') {
+    process.stdout.write('Usage: skitterspec spec-env dev <up|down> [spec]\n')
     return
   }
   const spec = resolveSpecWithWorktree(dir, config, specArg)
@@ -1035,11 +1173,6 @@ async function specEnvLive(dir, config, positional) {
 // Take the running instance: rebase the spec's branch onto base, free it from its
 // worktree, and check it out in the primary checkout so the dev server reloads it.
 async function specEnvLiveTake(dir, config, specArg) {
-  if (!specArg) {
-    process.stdout.write('Usage: skitterspec spec-env live take <spec>\n')
-    return
-  }
-
   const spec = resolveSpecWithWorktree(dir, config, specArg)
 
   // Probe the primary checkout's git state (IO stays here; the planner is pure).
@@ -1329,7 +1462,11 @@ async function specEnv(rest) {
       break
     default:
       process.stdout.write(
-        'Usage: skitterspec spec-env <up|down|prune|dev|connect|integrate|hotfix|live|status|resolve> [spec] [--keep-volumes] [--force] [--also <tag>] [--older-than <days>]\n',
+        'Usage: skitterspec spec-env <up|down|prune|dev|connect|integrate|hotfix|live|status|resolve> [spec] [--keep-volumes] [--force] [--also <tag>] [--older-than <days>]\n' +
+          '  [spec] is optional for up/down/dev/integrate/hotfix/resolve and live take:\n' +
+          '  omit it and the sole provisioned spec is used (several -> it lists them).\n' +
+          '  NOTE connect and live status keep their own meaning for a missing spec:\n' +
+          '  connect disconnects (= main), live status reports on the whole repo.\n',
       )
   }
 }

package/src/env/config.js

@@ -29,6 +29,7 @@
  *     branch:   { pattern, identifierField },  // git branch naming (provider-neutral)
  *     baseBranch: "",          // "" = auto-detect (origin/HEAD → main → master)
  *     guards:   { refuseTeardownIfDirty, refuseTeardownIfUnpushed },
+ *     teardown: { deleteRemoteBranch },
  *     live:     { migrations: [ "glob", ... ] }  // migration globs → `live take`
  *               // refuses a branch that changes them (code-only v1)
  *     hotfix:   { bump, cherryPickMain, targets }  // `hotfix land`: patch-bump the
@@ -79,6 +80,12 @@ const DEFAULT_CONFIG = Object.freeze({
   // Integration base branch. Empty = auto-detect (origin/HEAD → main → master).
   baseBranch: '',
   guards: Object.freeze({ refuseTeardownIfDirty: true, refuseTeardownIfUnpushed: true }),
+  // Teardown cleanup beyond this machine. `deleteRemoteBranch` decides what
+  // `spec-env down` does about the branch `/spec-go` pushed: "prompt" (default)
+  // plans the delete in its own confirm-first section for the skill to ask about,
+  // "never" omits it, "always" folds it into the run-blind command list. Only ever
+  // planned for a LANDED branch — see teardown.js.
+  teardown: Object.freeze({ deleteRemoteBranch: 'prompt' }),
   // Live overlay (`spec-env live`). `migrations` is a list of globs marking
   // migration files; a branch that changes any of them is treated as stateful and
   // `live take` refuses it (code-only v1). Default: none (nothing is stateful).
@@ -109,6 +116,7 @@ function defaults() {
     branch: { ...DEFAULT_CONFIG.branch },
     baseBranch: DEFAULT_CONFIG.baseBranch,
     guards: { ...DEFAULT_CONFIG.guards },
+    teardown: { ...DEFAULT_CONFIG.teardown },
     live: { migrations: [] },
     hotfix: { ...DEFAULT_CONFIG.hotfix, targets: [] },
   }
@@ -254,6 +262,17 @@ function mergeConfig(base, parsed) {
     assign(base.guards, parsed.guards, 'refuseTeardownIfUnpushed', 'boolean')
   }
 
+  // An unrecognised policy falls through to the default rather than erroring or
+  // being taken literally — a typo ("Always", "yes") must not silently become a
+  // stronger setting than the author typed, and "prompt" is the one value that
+  // cannot act without a human first.
+  if (isObject(parsed.teardown)) {
+    const policy = parsed.teardown.deleteRemoteBranch
+    if (policy === 'prompt' || policy === 'never' || policy === 'always') {
+      base.teardown.deleteRemoteBranch = policy
+    }
+  }
+
   if (isObject(parsed.live) && Array.isArray(parsed.live.migrations)) {
     base.live.migrations = normalizeFileList(parsed.live.migrations)
   }

package/src/env/teardown.js

@@ -13,6 +13,12 @@
  * Volumes are the only destructive action — dropped by default (reclaims disk)
  * unless `--keep-volumes`, and always backed up first when a `backupCommand` is
  * configured.
+ *
+ * `commands` is safe for a caller to run BLIND — that is the property the remote
+ * delete must not break. A remote branch delete reaches outside this machine, so
+ * it is returned in a separate `remoteCommands` array that the skills confirm
+ * with the user before running, and it never enters `commands` unless the
+ * project has opted in with `teardown.deleteRemoteBranch: "always"`.
  */
 
 const { expandTokens } = require('./resolve.js')
@@ -21,9 +27,10 @@ const { expandTokens } = require('./resolve.js')
  * @param {object} spec  resolved spec: { slug, branch, worktreePath, projectName, ... }
  * @param {object} config normalised env config.
  * @param {object} flags { keepVolumes, force }
- * @param {object} ctx   { worktreeState: { dirty, unpushed, merged, reachableFromTag }, timestamp }
- * @returns {object} { blocked, reason, commands, backupCommand, backupPath,
- *                     volumesDropped }
+ * @param {object} ctx   { worktreeState: { dirty, unpushed, merged, reachableFromTag,
+ *                     remoteBranch }, timestamp }
+ * @returns {object} { blocked, reason, commands, remoteCommands, backupCommand,
+ *                     backupPath, volumesDropped }
  */
 function planDown(spec, config, flags, ctx) {
   const { worktreeState = {}, timestamp } = ctx || {}
@@ -113,7 +120,57 @@ function planDown(spec, config, flags, ctx) {
     commands.push(`git branch ${landed ? '-D' : '-d'} ${spec.branch}`)
   }
 
-  return { blocked: false, reason: null, commands, backupCommand, backupPath, volumesDropped }
+  // --- delete the branch on the remote (planned, never run here) ---
+  //
+  // `/spec-go` 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.
+  //
+  // Gated on `landed` because until the branch is merged (or captured by a tag)
+  // the remote copy is the ONLY backup of the work — that is the whole reason
+  // `refuseTeardownIfUnpushed` exists, and deleting the remote branch of an
+  // unlanded spec would defeat it. `--force` deliberately does NOT enable this:
+  // force is for "I accept losing this worktree", not "also reach out and delete
+  // the backup". The same `landed` that decides `-D` vs `-d` decides this, so the
+  // two can never disagree about whether the commits are recoverable.
+  //
+  // A null `remoteBranch` plans nothing. An absence is not evidence — the branch
+  // may well be on a remote this clone cannot see (pushed from another machine),
+  // and the honest answer to "is there a remote branch?" is then "cannot tell",
+  // which routes to doing nothing.
+  const remoteCommands = []
+  const policy = (config.teardown && config.teardown.deleteRemoteBranch) || 'prompt'
+  if (spec.branch && landed && worktreeState.remoteBranch && policy !== 'never') {
+    // `remoteBranch` is a short ref like "origin/feat/thing" and the branch name
+    // itself contains slashes, so the remote is what remains once the exact
+    // "/<branch>" suffix is stripped — not the text before the first slash.
+    //
+    // If it does not end that way the ref maps to a differently-named branch on
+    // the remote (a push refspec, or push.default set to something exotic). We
+    // cannot tell what to delete, so we plan nothing rather than guess at a
+    // branch name on someone's shared remote.
+    const suffix = `/${spec.branch}`
+    if (worktreeState.remoteBranch.endsWith(suffix)) {
+      const remote = worktreeState.remoteBranch.slice(0, -suffix.length)
+      if (remote) {
+        const cmd = `git push ${remote} --delete ${spec.branch}`
+        // "always" is the project saying it never wants to be asked, so the push
+        // joins the run-blind list. Everything else keeps it quarantined.
+        if (policy === 'always') commands.push(cmd)
+        else remoteCommands.push(cmd)
+      }
+    }
+  }
+
+  return {
+    blocked: false,
+    reason: null,
+    commands,
+    remoteCommands,
+    backupCommand,
+    backupPath,
+    volumesDropped,
+  }
 }
 
 function blocked(reason) {
@@ -121,6 +178,7 @@ function blocked(reason) {
     blocked: true,
     reason,
     commands: [],
+    remoteCommands: [],
     backupCommand: null,
     backupPath: null,
     volumesDropped: false,

package/src/init.js

@@ -23,6 +23,21 @@ function listSkills() {
     .sort()
 }
 
+// Slash commands shipped as `assets/commands/*.md`, installed to
+// `.claude/commands/`. Discovered from the bundled tree exactly like skills, so
+// each distribution installs precisely what it ships.
+function listCommands() {
+  const dir = path.join(ASSETS, 'commands')
+  try {
+    return fs
+      .readdirSync(dir)
+      .filter((f) => f.endsWith('.md'))
+      .sort()
+  } catch {
+    return [] // a distribution may ship no commands
+  }
+}
+
 function listRules() {
   return fs
     .readdirSync(path.join(ASSETS, 'rules'))
@@ -42,6 +57,8 @@ function listCoreTemplates() {
 
 const SKILLS = listSkills()
 
+const COMMANDS = listCommands()
+
 const RULES = listRules()
 
 const SPEC_FOLDERS = ['.core', 'backlog', 'in-progress', 'complete', 'cancelled']
@@ -50,6 +67,89 @@ const SPEC_FOLDERS = ['.core', 'backlog', 'in-progress', 'complete', 'cancelled'
 // env.config isolation templates; a provider superset also ships its own).
 const CORE_FILES = listCoreTemplates()
 
+// The CLI is a local devDependency and never on PATH, so a command file that
+// pre-executes it must carry a literal, working invocation. Detect the runner
+// from the lockfile and bake it in at write time.
+//
+// The lockfile is a POSITIVE signal — a file that must be present for the answer
+// to be yes — rather than an absence. When none is found we do not guess a
+// package manager we have no evidence for; `npx` is the fallback because it is
+// the one runner that works across all three installs.
+const PACKAGE_MANAGERS = [
+  ['pnpm-lock.yaml', 'pnpm exec'],
+  ['yarn.lock', 'yarn'],
+  ['package-lock.json', 'npx'],
+  ['bun.lockb', 'bunx'],
+]
+
+function detectPackageManager(dir) {
+  for (const [lockfile, exec] of PACKAGE_MANAGERS) {
+    if (fs.existsSync(path.join(dir, lockfile))) return exec
+  }
+  return 'npx'
+}
+
+// Fill a command file's `{{exec}}` placeholders. Kept a pure function of
+// (content, dir) so `managedTargets` can compare against exactly what
+// `installCommands` would write — otherwise every install would hash as
+// customized on the next run.
+function renderCommand(content, dir) {
+  return content.split('{{exec}}').join(detectPackageManager(dir))
+}
+
+// --- composed-assets guard -------------------------------------------------
+//
+// A source package's `assets/` is PRE-composition: `<!-- seam:NAME -->` is still
+// literal text that scripts/build-dist.js replaces — with a provider's fragment
+// for the provider distribution, with nothing for the base. Only a built
+// distribution's assets are installable.
+//
+// This is a POSITIVE signal, not an absence: a seam marker must be **present**
+// for the guard to fire, so it cannot misfire on a tree it simply failed to read.
+// And it refuses rather than repairing — installing the wrong thing is the
+// expensive mistake here. In a dev-linked checkout the installed skills are
+// symlinks to the composed distribution, so a `--force` install would write
+// these markers straight through the link and into the built assets.
+const SEAM_RE = /<!--\s*seam:[A-Za-z0-9_-]+\s*-->/
+
+function assetFiles(dir) {
+  const out = []
+  const walk = (d) => {
+    let entries
+    try {
+      entries = fs.readdirSync(d, { withFileTypes: true })
+    } catch {
+      return // a distribution need not ship every asset kind
+    }
+    for (const e of entries) {
+      const p = path.join(d, e.name)
+      if (e.isDirectory()) walk(p)
+      else if (e.name.endsWith('.md')) out.push(p)
+    }
+  }
+  walk(dir)
+  return out
+}
+
+// Throws when this package's assets are uncomposed. Called from the **bins** —
+// the outermost boundary, and the only way a real install happens — never from
+// init()/resync()/run(), which the unit tests legitimately drive against this
+// source tree. Guarding any deeper would make the library untestable while
+// protecting nothing extra.
+function assertComposedAssets() {
+  const offenders = assetFiles(ASSETS)
+    .filter((f) => SEAM_RE.test(fs.readFileSync(f, 'utf8')))
+    .map((f) => path.relative(ASSETS, f))
+  if (!offenders.length) return
+  throw new Error(
+    `refusing to install: this package's assets are uncomposed (${offenders.length} ` +
+      `file(s) still carry a <!-- seam:… --> marker, e.g. ${offenders[0]}).\n` +
+      '  These are a workspace source package\'s assets, not a distribution\'s. ' +
+      'Run "npm run build" in the skitterspec repo, then run the command again ' +
+      'from the built distribution.',
+  )
+}
+
 const SPEC_MARKER_START = '<!-- skitterspec:start -->'
 const SPEC_MARKER_END = '<!-- skitterspec:end -->'
 
@@ -99,13 +199,15 @@ function sha1(content) {
 // the bundled content that ships in this distribution's assets.
 function managedTargets(dir) {
   const out = []
-  const add = (assetRel, targetAbs) =>
+  const add = (assetRel, targetAbs, render = (c) => c) =>
     out.push({
       relPath: rel(dir, targetAbs),
       abs: targetAbs,
-      bundled: fs.readFileSync(path.join(ASSETS, assetRel), 'utf8'),
+      bundled: render(fs.readFileSync(path.join(ASSETS, assetRel), 'utf8'), dir),
     })
   for (const name of SKILLS) add(path.join('skills', name, 'SKILL.md'), path.join(dir, '.claude', 'skills', name, 'SKILL.md'))
+  for (const name of COMMANDS)
+    add(path.join('commands', name), path.join(dir, '.claude', 'commands', name), renderCommand)
   for (const name of RULES) add(path.join('rules', name), path.join(dir, '.claude', 'rules', name))
   for (const asset of CORE_FILES) add(asset, path.join(dir, 'specs', '.core', path.basename(asset)))
   return out
@@ -230,6 +332,16 @@ function installSkills(dir, opts) {
   }
 }
 
+function installCommands(dir, opts) {
+  for (const name of COMMANDS) {
+    const content = renderCommand(
+      fs.readFileSync(path.join(ASSETS, 'commands', name), 'utf8'),
+      dir,
+    )
+    writeFile(dir, path.join(dir, '.claude', 'commands', name), content, opts)
+  }
+}
+
 function installRule(dir, opts) {
   for (const name of RULES) {
     copyAsset(
@@ -519,6 +631,7 @@ function reset(dir, { claudeMd = true } = {}) {
   }
   if (claudeMd) stripClaudeMdSection(dir)
   installSkills(dir, { force: true })
+  installCommands(dir, { force: true })
   installRule(dir, { force: true })
   installFolders(dir)
   removeRetiredFiles(dir)
@@ -597,6 +710,7 @@ async function init({ dir, force, claudeMd, mode, isolation }) {
   resetReport()
 
   installSkills(dir, { force })
+  installCommands(dir, { force })
   installRule(dir, { force })
   installFolders(dir)
   removeRetiredFiles(dir)
@@ -615,6 +729,7 @@ async function init({ dir, force, claudeMd, mode, isolation }) {
 module.exports = {
   init,
   SKILLS,
+  COMMANDS,
   RULES,
   SPEC_FOLDERS,
   MANIFEST_FILE,
@@ -627,4 +742,7 @@ module.exports = {
   resync,
   reset,
   assertSafeToDelete,
+  assertComposedAssets,
+  detectPackageManager,
+  renderCommand,
 }