@skitterbyte/skitterspec 1.0.1 → 2.0.1

package/README.md

@@ -1,259 +1,42 @@
 # @skitterbyte/skitterspec
 
-Spec-driven-development (SDD) workflow for [Claude Code](https://claude.com/claude-code),
-packaged so you can drop the same spec lifecycle into any project.
+Spec-driven development for [Claude Code](https://claude.com/claude-code) — a
+**tracker-free** filesystem workflow. Ships the spec-lifecycle skills (`/spec`,
+`/spec-ready`, `/spec-go`, `/spec-complete`, `/spec-cancel`, `/spec-bug`,
+`/spec-init`) and per-spec **isolation** (a git worktree per in-progress spec,
+Docker on demand).
 
-It installs the **eight spec-lifecycle skills** plus a general **`/commit`**
-skill, two governing rules, and the `specs/` folder structure. The lifecycle is
-`backlog → in-progress → complete / cancelled`, with `.core` holding always-apply
-project rules.
-
-| Skill | Action | Status | Folder |
-|-------|--------|--------|--------|
-| `/spec` | (Feature) Grill to a shared understanding, then write a concise spec | `Draft` | `specs/backlog/` |
-| `/spec-bug` | (Bug) Reproduce with a failing test, capture spec, drive red→green | `In Progress` | `specs/in-progress/` |
-| `/spec-ready` | Confirm the spec is groomed | `Ready` | `specs/backlog/` |
-| `/spec-review` | Re-validate a spec against the codebase; refresh stale parts | `—` | (unchanged) |
-| `/spec-go` | Implement the next phase (with tests) | `In Progress` | `specs/in-progress/` |
-| `/spec-complete` | Verify all phases done + tests green | `Complete` | `specs/complete/` |
-| `/spec-cancel` | Record progress, stamp a reason | `Cancelled` | `specs/cancelled/` |
-| `/spec-init` | Bootstrap/repair the workflow (manual path) | — | — |
-| `/commit` | Stage the task's files, run typecheck + tests, write a conventional commit (+ release-note footer) | — | (unchanged) |
-
-## Install into a project
-
-From the root of the target project:
-
-```bash
+```sh
 npx @skitterbyte/skitterspec init
 ```
 
-On a terminal it runs an **interactive setup** (skip it with `--yes` or drive it
-with the flags below). It's idempotent — it creates only what's missing and
-never clobbers customised files. It writes:
-
-```
-.claude/skills/spec*/SKILL.md   # the 8 spec-lifecycle skills
-.claude/skills/commit/SKILL.md  # the /commit skill
-.claude/rules/spec-planning.md  # governing rule (the single source of truth)
-.claude/rules/commit-messages.md # commit message + release-note grammar
-specs/{.core,backlog,in-progress,complete,cancelled}/
-CLAUDE.md                       # adds a "## Spec workflow" section (created if absent)
-```
-
-If you enable the **release tooling** (see below) it also writes:
-
-```
-skitterspec.config.json         # which artifacts to generate, filenames, scope→area map
-scripts/generate-changelog.js   # dev-facing CHANGELOG generator   (if changelog enabled)
-scripts/generate-releases.js    # user-facing RELEASES generator    (if releases enabled)
-scripts/lib/                     # shared git + config helpers
-package.json                    # adds a "version" hook + changelog/releases npm scripts
-```
-
-### Options
-
-```bash
-npx @skitterbyte/skitterspec init ./path/to/project   # target a dir (default: cwd)
-npx @skitterbyte/skitterspec init --yes               # accept defaults, skip the prompts
-npx @skitterbyte/skitterspec init --force             # overwrite existing skill/rule/script files
-npx @skitterbyte/skitterspec init --no-claude-md      # don't touch CLAUDE.md
-npx @skitterbyte/skitterspec init --isolation         # adopt per-spec isolation (worktree per spec)
-npx @skitterbyte/skitterspec update                   # re-copy skills + rule + scripts, leave specs/ + config alone
-```
-
-Release-tooling flags (drive setup without the prompts):
-
-```bash
---changelog / --no-changelog        # enable/disable CHANGELOG generation
---releases  / --no-releases         # enable/disable user-facing release notes
---changelog-file=NAME               # changelog filename (default CHANGELOG.md)
---releases-file=NAME                # release-notes filename (default RELEASES.md)
---product-name=NAME                 # product name shown in the release-notes header
---version-hook / --no-version-hook  # wire (or skip) the npm "version" hook
-```
-
-`update` pulls newer skill/rule/script versions after upgrading the package,
-without disturbing your specs or `skitterspec.config.json`. The CLAUDE.md section
-is wrapped in `<!-- skitterspec:start -->`…`<!-- skitterspec:end -->` markers so
-`update` can refresh it in place.
-
-## Changelog & release-note tooling (opt-in)
-
-Conventional commits already say what changed; skitterspec can turn them into two
-generated artifacts at `npm version`:
-
-- **`CHANGELOG.md`** — dev-facing, built from commit **subjects** (Keep a Changelog
-  format: feat→Added, fix→Fixed, perf/refactor→Changed, breaking→Changed).
-- **`RELEASES.md`** — user-facing, built **only** from `Release-Note:` commit
-  **footers**, grouped by area and bucket (New / Improved / Fixed / Action
-  required). The `/commit` skill writes these footers; the grammar lives in
-  `.claude/rules/commit-messages.md`.
-
-Both walk *commits since the last version tag*. Generation is opt-in per artifact
-and recorded in **`skitterspec.config.json`** at the repo root:
-
-```json
-{
-  "version": 1,
-  "changelog": { "enabled": true, "file": "CHANGELOG.md" },
-  "releases":  { "enabled": true, "file": "RELEASES.md",
-                 "productName": "My App", "scopeAreas": {} },
-  "versionHook": true
-}
-```
-
-`scopeAreas` maps a commit scope to a user-facing area (e.g. `{"reqs":
-"Requisitions"}`); unmapped scopes fall back to Title-Case, and a `Release-Area:`
-footer overrides per-commit. When `versionHook` is on, `init` wires npm scripts:
-
-```bash
-npm run changelog          # regenerate CHANGELOG.md from commits since last tag
-npm run releases           # regenerate RELEASES.md
-npm run changelog:retro -- 5   # backfill the last 5 tagged releases
-npm version <patch|minor|major>  # bumps, regenerates both, and stages them
-```
-
-The generators are plain Node (no `tsx`/`ts-node`); the only runtime dependency
-the package itself adds is [`prompts`](https://www.npmjs.com/package/prompts) for
-the interactive `init`.
-
-## Spec structure
-
-Every spec is a **folder**, never a bare file:
-
-```
-specs/backlog/feat-<name>/
-  00-overview.md     # dashboard: problem, decisions, solution, phase index, logs
-  01-<phase-slug>.md # phase 1 — goal + task checkboxes (tests included)
-  02-<phase-slug>.md # phase 2 …
-```
-
-`00-overview.md` is the index — it carries a **phase table** linking to each
-phase file with its status (`⬜`/`🔄`/`✅`). **Each phase is its own file** so it's
-easy to dive into one phase without wading through the whole spec. The lifecycle
-skills keep the index and phase files in sync.
-
-## Per-spec isolation — worktree by default, Docker on demand
-
-Work several specs in parallel without them stepping on each other. **Adopt it
-once** with `npx @skitterbyte/skitterspec init --isolation` (or copy
-`specs/.core/env.config.json.example` → `specs/.core/env.config.json`; every field
-is documented in `specs/.core/env.config.md`). While the config is absent the
-feature is simply unused.
-
-Once adopted it's the **default policy**, not a per-spec chore:
-
-- **Worktree — automatic for every in-progress spec.** `/spec-go` gives each spec
-  its own sibling git worktree on its own branch, so you never stash or rebuild to
-  switch specs and `main` stays free for hotfixes. All housekeeping (the
-  backlog→in-progress move, header edits, the code) happens on that branch and
-  lands in one PR; `main` changes only when it merges.
-- **Docker — a per-spec escalation.** `/spec` records `> **Stack:** worktree`
-  (default) or `worktree + docker` when the spec touches the DB / stateful
-  services. Only an escalated spec gets a **namespaced stack** — a per-spec
-  `COMPOSE_PROJECT_NAME` isolates containers, networks, and **named volumes**, and
-  a `PORT_OFFSET` reserves a distinct port block, so N stacks run at once with no
-  clashes. A worktree-only spec takes **no** slot, port block, or `.env`.
-- an optional **opener** — a single, editor/terminal-agnostic `open.command`
-  (e.g. `code {worktreePath}`, a `tmux` command, or a `warp://` deeplink).
-
-The machine-local slot registry and volume backups live under `/.spec-env/`
-(gitignored). `docker.enabled` in the config is the project **master switch**
-("is Docker escalation available?"), not "always run Docker".
-
-`/spec-env` · `/spec-env-down` remain the **manual engine** behind the automation
-— use them to escalate Docker onto an existing worktree, re-attach, or tear down:
-
-```
-/spec-env <spec>        # worktree (+ stack iff Stack: worktree + docker) + opener
-                        #   (idempotent; re-run attaches)
-/spec-env-down <spec>   # stop stack, drop volumes (backed up first), remove worktree,
-                        #   free the slot. Guards refuse a dirty/unpushed worktree
-                        #   unless --force; --keep-volumes preserves data.
-```
-
-Your `docker-compose.yml` must reference `${PORT_OFFSET}` on each published port
-so services land in the spec's reserved block. Two adoption modes:
-
-- **Standalone** (`linkLinear: false`) — plain `{type}/{slug}` branch names; pure
-  worktree + Docker + opener. No Linear needed.
-- **Linear-linked** (`linkLinear: true` + `specs/.core/linear.config.json`) —
-  branch names follow Linear's pattern so pushing fires Linear's GitHub
-  automation.
-
-`/spec-complete` and `/spec-cancel` will *offer* to tear down when the config is
-present — never forced.
-
-## Linear hybrid sync — git-like `/spec-status` · `/spec-pull` · `/spec-push`
-
-Let **Linear own status and discussion** while the repo stays the **co-authoring
-surface for spec content**. The sync is bidirectional but git-like: explicit
-commands, a committed **base sidecar** for three-way merge, and no blind
-overwrites. It's **opt-in** — everything below is inert until
-`specs/.core/linear.config.json` exists (copy `linear.config.json.example` and
-fill in your team / initiative IDs; every field is documented in
-`specs/.core/linear.config.md`). Without it, `/spec`, `/spec-go`, and the CLI
-behave exactly as before.
-
-**Mapping** (config-driven): a spec folder → Linear **Project**; each phase
-(`01-…`, `02-…`) → a **Milestone**; tasks → **Issues**; an optional **Initiative**
-groups specs. When linked, `/spec` creates the project + a milestone per phase and
-writes the linking frontmatter into `00-overview.md`.
-
-**The git-like lifecycle:**
-
-```
-/spec-status          # read-only — per-field divergence (local-only / remote-only
-                      #   / conflict / in-sync). Changes nothing.
-/spec-pull [--force]  # Linear → repo. Applies remote-only fields; refuses to
-                      #   clobber a conflicting local edit unless --force.
-   …refine the spec locally (the repo is the co-authoring surface)…
-/spec-push [--force]  # repo → Linear. Ownership-respecting, concurrency-checked;
-                      #   refuses if Linear moved since base unless --force.
-```
-
-**Field ownership** collapses conflicts: each field is `both` (co-authored,
-can conflict), `pull` (Linear owns it — e.g. status/priority/labels), or `push`
-(the repo owns it). Only a `both` field that moved on **both** sides is a real
-conflict. `--force` never destroys blindly — it backs up the losing side into
-`sync.backupDir` (a local reflog) first, then wins. After any successful
-pull/push the engine **rewrites the base** so the next compare starts clean.
+This installs the skills + rules into `.claude/`, scaffolds `specs/`, and patches
+`CLAUDE.md`. See `.claude/rules/spec-planning.md` after install to set your
+project's typecheck/test/lint commands.
 
-`/spec-go` on a linked spec runs `/spec-pull` first, so you always build against
-the current shared state. **Base sidecars** (`sync.baseDir`, default
-`specs/.core/linear-base/`) are **committed** — each worktree carries its own
-base. **Backups** (`sync.backupDir`, default `specs/.core/linear-backups/`) are
-local recovery and **gitignored**.
+## Pick one distribution
 
-This supersedes the earlier one-way `/spec-from-issue` intake design (cancelled):
-because both sides author, the sync had to be bidirectional and three-way, not a
-blind import.
+Ticketing sync is a **separate superset you install instead of this one**:
 
-## After install — tailor it
+| Install | You get |
+|---------|---------|
+| `@skitterbyte/skitterspec` | The base filesystem workflow. No tracker. |
+| `@skitterbyte/skitterspec-linear` | Everything here **plus** Linear hybrid-sync (`/spec-status` · `/spec-pull` · `/spec-push`, the `spec-sync` CLI). |
 
-The shipped skills are **stack-agnostic**. They say things like "run the
-project's typecheck and test commands" and "honour the project's conventions".
-Make those concrete once, in **`.claude/rules/spec-planning.md`** (the
-*Project conventions* section): set your real typecheck/test/lint commands and
-link your other `.claude/rules/*.md`. The skills point at that file, so you don't
-edit seven files per project.
+Install exactly one — the superset is a strict superset of this package.
 
-## How it's distributed
+## v2 — Linear removed from the base
 
-The skills, rule, and generator scripts are plain assets under
-[`assets/`](./assets). The CLI ([`bin/skitterspec.js`](./bin/skitterspec.js) →
-[`src/`](./src)) copies them into place, patches `CLAUDE.md`, and (for the release
-tooling) writes `skitterspec.config.json` and npm scripts. It needs Node 18+ and
-one runtime dependency, [`prompts`](https://www.npmjs.com/package/prompts), used
-only for the interactive `init`. The copied generator scripts are dependency-free
-and read their config from `skitterspec.config.json` — they never call back into
-this package.
+`@skitterbyte/skitterspec` **2.0** is tracker-free: the Linear sync skills, the
+`spec-sync` CLI, and the `linear.config.*` templates moved to
+`@skitterbyte/skitterspec-linear`. If you used Linear sync on v1, see
+[MIGRATION.md](../../MIGRATION.md) — switching is one install + re-`init`.
 
-Because the files are copied into the consumer repo (not symlinked), each project
-pins its own version and can diverge. Re-run `update` to re-sync from a newer
-package release.
+## How it's built
 
-## License
+This distribution is composed from the private workspace packages by
+`scripts/build-dist.js`: the base fills the shared skills' provider seams with
+nothing, so it's self-contained and depends only on
+[`prompts`](https://www.npmjs.com/package/prompts) (for interactive `init`).
 
-MIT
+MIT © Reuben Greaves

package/assets/claude-md-section.md

@@ -27,12 +27,6 @@ State log.
 > Tailor the per-phase test commands and project conventions referenced by the
 > spec skills to this project's stack (see `.claude/rules/spec-planning.md`).
 
-Also installed: **`/commit`** — stage only the task's files, run typecheck +
-tests, then write a conventional-commit message with a `Release-Note:` footer
-for user-visible changes (grammar in `.claude/rules/commit-messages.md`). If the
-release tooling is enabled (`skitterspec.config.json`), those footers feed the
-generated `CHANGELOG.md`/`RELEASES.md` at `npm version`.
-
 **Per-spec isolation (adopt once, then default):** with isolation adopted
 (`skitterspec init --isolation`, or `specs/.core/env.config.json` present),
 **`/spec-go`** gives every in-progress spec its own git worktree automatically —

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

@@ -16,7 +16,11 @@
     "command": ""
   },
   "registry": ".spec-env/registry.json",
-  "linkLinear": true,
+  "branch": {
+    "pattern": "{type}/{slug}",
+    "identifierField": ""
+  },
+  "baseBranch": "",
   "guards": {
     "refuseTeardownIfDirty": true,
     "refuseTeardownIfUnpushed": true

package/assets/core/env.config.md

@@ -62,12 +62,28 @@ no live `env.config.json` was found.
   // primary checkout root, shared by all worktrees, gitignored.
   "registry": ".spec-env/registry.json",
 
-  // When true and specs/.core/linear.config.json is present, derive branch
-  // names from Linear's branch.pattern so pushing fires Linear's GitHub
-  // automation. Otherwise branches fall back to {type}/{slug}.
-  "linkLinear": true,
+  // Git branch naming, provider-neutral. `pattern` expands {type} and {slug}
+  // (e.g. "feat/add-widget"). When a ticketing provider is linked and you want
+  // tracker ids in branch names, use {identifier} in the pattern and point
+  // `identifierField` at the 00-overview.md frontmatter field the provider
+  // writes the id into — pushing that branch can then fire the tracker's
+  // automation. Empty `identifierField` (or a spec missing that field) makes a
+  // pattern with {identifier} fall back to {type}/{slug}.
+  "branch": {
+    "pattern": "{type}/{slug}",
+    "identifierField": ""
+  },
+
+  // Integration base branch — the branch specs fork from and land back onto
+  // (used by the teardown "merged?" guard and, later, the integrate step).
+  // Empty = auto-detect: origin/HEAD → main → master. Set it when your default
+  // branch isn't discoverable (e.g. no remote) or differs (trunk, develop).
+  "baseBranch": "",
 
-  // Teardown safety. --force overrides both.
+  // Teardown safety. --force overrides both. refuseTeardownIfUnpushed only
+  // blocks when the commits are ALSO unmerged into the base branch — a branch
+  // already landed on base tears down (and its branch is deleted) without
+  // --force, even with no remote.
   "guards": {
     "refuseTeardownIfDirty": true,
     "refuseTeardownIfUnpushed": true

package/assets/rules/spec-planning.md

@@ -34,14 +34,17 @@ re-attach, tear down). Isolation is **orthogonal to lifecycle status** and
 inactive when `env.config.json` is absent — every skill then behaves as it does
 today.
 
-**Linear hybrid sync (opt-in).** When `specs/.core/linear.config.json` is present,
-three git-like skills sync a spec with its linked Linear project: `/spec-status`
-(read-only per-field divergence), `/spec-pull` (Linear→repo), and `/spec-push`
-(repo→Linear) — three-way merged against a committed base sidecar, with
-field-ownership collapsing conflicts and a `--force` + backup escape hatch. Linked
-`/spec` also creates the Linear Project + a Milestone per phase, and `/spec-go`
-pulls first. All of it is inert without the config — every skill then behaves as
-it does today. Full model + field reference: `specs/.core/linear.config.md`.
+**Ticketing-provider sync (opt-in, a separate package).** The base is
+tracker-free: it knows nothing about any specific ticketing system. A
+ticketing provider is installed as its own distribution that plugs into two named
+**seams** in the shared skills (`/spec` Phase E, `/spec-go` step 3b) and fulfils a
+skill-name + CLI contract — it ships `/spec-status` (read-only per-field
+divergence), `/spec-pull` (tracker→repo), and `/spec-push` (repo→tracker), backed
+by a `spec-sync` CLI, three-way merged against a committed base sidecar. When a
+provider is present, `/spec` also links the spec to the tracker and `/spec-go`
+pulls first. With no provider installed the seams are empty and every skill
+behaves as a plain filesystem workflow. See the provider package's own docs for
+its config and field reference.
 
 ## Project conventions (fill this in)
 
@@ -135,8 +138,9 @@ those, but new specs always use the folder + phase-file form.
 The **folder buckets are the source of truth** — a spec's bucket is its status.
 To see the backlog, list `specs/backlog/`; for the latest completed specs, use
 `git log`/mtime on `specs/complete/` or each spec's dated **State log**. Live
-status also lives in Linear when it's linked. (There are no `00-index.md`
-summary files — the folder tree, headers, and State logs are queried directly.)
+status also lives in the tracker when a ticketing provider is linked. (There are
+no `00-index.md` summary files — the folder tree, headers, and State logs are
+queried directly.)
 
 ## Rules
 

package/assets/skills/spec/SKILL.md

@@ -184,41 +184,14 @@ run `/spec-env <name>` to add Docker to an existing worktree). If
 `env.config.json` is absent, isolation is off — leave the default `worktree` and
 finish as above.
 
-## Phase E — link to Linear (only if configured)
-
-**Only when `specs/.core/linear.config.json` exists** (Linear sync is opted in).
-If it's absent, skip this phase entirely — the spec stays local-only and `/spec`
-behaves exactly as above. When present, after writing the spec, link it to Linear
-so status and discussion live there while the repo stays the co-authoring surface:
-
-- **Discover the Linear MCP tools at runtime** (don't hardcode names). If Linear
-  isn't connected/authed, relay the fix and stop — leave the spec written and
-  local; the user can link it later with `/spec-push`. Do nothing destructive.
-- **Create the Project** from the spec: name from the title, description from the
-  `00-overview.md` plan. Attach the `initiativeId` from `linear.config.json` when
-  one is set.
-- **Create a Milestone per phase** (the `mapping.phases` target — milestones by
-  default), named from each phase file, in execution order.
-- **Add the frontmatter block** to `00-overview.md` (above the `#` title) so the
-  spec is linkable:
-
-  ```yaml
-  ---
-  linear_project_id: "<uuid>"
-  linear_identifier: "<TEAM-123>"
-  linear_url: "https://linear.app/..."
-  spec_status: "backlog"
-  last_synced_at: "<ISO-8601 now>"
-  ---
-  ```
-
-- **Write the initial base sidecar** so the spec starts clean and non-diverged —
-  run `skitterspec spec-sync normalize <spec>` to capture the local snapshot as the
-  committed base (`sync.baseDir`). `/spec-status` should report in-sync right after.
-- **Echo the branch name** from `branch.pattern` so the user knows what `/spec-go`
-  will fork.
-
-Leave committing to the existing convention (the user commits the spec as usual)
-and **never auto-push git** — Linear's own automation reacts to real branch/PR
-events later. Report the Linear project URL and the base as part of Phase C's
-finish-up message.
+## Phase E — link to a ticketing provider (only if one is installed)
+
+**Only when a ticketing provider is installed and configured** (it ships the
+`/spec-push` · `/spec-pull` · `/spec-status` skills and a provider config under
+`specs/.core/`). If none is present, skip this phase entirely — the spec stays
+local-only and `/spec` behaves exactly as above. When a provider is present, link
+the spec to the tracker after writing it, so status and discussion live there
+while the repo stays the co-authoring surface — follow the provider's link steps
+below (nothing to do here without one).
+
+

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

@@ -51,10 +51,37 @@ specs — `git log`/the per-spec State log give the completion order.
 Confirm the move, the final test result, and list anything deferred. Do **not**
 `git commit` unless the user asks.
 
-## 6. Offer teardown (opt-in, only if configured)
+## 6. Integrate onto the base branch (opt-in, only if isolated)
+
+**Only when `specs/.core/env.config.json` exists and the spec is on a worktree**
+(it was provisioned by `/spec-go`). Otherwise skip this entirely — a non-isolated
+spec has nothing to land, and `/spec-complete` behaves exactly as before. When it
+applies, offer to land the finished branch on the base branch so the work reaches
+`main` (or your configured `baseBranch`) in one flow:
+
+1. **Require a clean worktree.** The completion edits (status flip, the
+   `git mv` to `complete/`) must be committed first — integrate refuses a dirty
+   tree. If it's dirty, offer `/commit` and **stop**; don't auto-commit.
+2. **Plan + execute.** Run `skitterspec spec-env integrate <name>` and run the
+   printed commands **in order**:
+   - `git -C <worktree> rebase <base>` — replay the branch onto base.
+   - `git -C <mainRepoPath> merge --ff-only <branch>` — fast-forward base.
+   On a **rebase conflict** (non-zero exit), run
+   `git -C <worktree> rebase --abort`, relay the conflict, and **stop** — leave it
+   to the user; do not offer teardown.
+   On a **no-op** ("already landed"), just say so and continue.
+3. **Re-test on base.** Run the project's test command from the primary checkout;
+   it must be **green** before you call the landing done.
+4. **Report** the landing (base branch, fast-forward result). It **never pushes** —
+   mention the user can `git push` the base branch themselves.
+
+## 7. Offer teardown (opt-in, only if configured)
 
 **Only when `specs/.core/env.config.json` exists**, offer — don't force — to
 reclaim the finished spec's environment: "Want me to run `/spec-env-down <name>`
-to remove its worktree, stack, volumes, and free its slot?" It respects the
-teardown guards (won't destroy a dirty/unpushed worktree without `--force`). If
-`env.config.json` is absent, skip this entirely — behave exactly as before.
+to remove its worktree, delete its branch, stack, volumes, and free its slot?"
+Post-integrate the branch is merged into base, so teardown needs **no `--force`**
+and deletes the branch (`git branch -d`) as part of the plan. It still respects
+the guards (won't destroy a dirty or unpushed-and-unmerged worktree without
+`--force`). If `env.config.json` is absent, skip this entirely — behave exactly as
+before.

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

@@ -47,6 +47,12 @@ Run the printed commands **in order**, exactly as printed:
    namespaced stack up in the spec's reserved port block.
 4. **Opener** — if an `open.command` line was printed, run it (e.g. opens the
    worktree in your editor/terminal). Skipped silently when unset.
+5. **Trust the worktree root for this session** — the engine already wrote the
+   printed `trusted:` root into `.claude/settings.local.json` (gitignored, so it
+   persists for future sessions). That file likely won't hot-reload mid-session,
+   so also run `/add-dir <trusted root>` now to lift `Edit`/`Write` prompts for
+   the **current** session. (If the engine printed a `trusted: ! …` warning,
+   `settings.local.json` isn't valid JSON — fix it, then re-run.)
 
 ## 4. Report
 

package/assets/skills/spec-env-down/SKILL.md

@@ -31,10 +31,13 @@ skitterspec spec-env down <spec> [--keep-volumes] [--force]
 
 ## 3. Handle a guard block
 
-If the CLI reports **blocked** (the worktree has uncommitted changes or unpushed
-commits), **relay the reason and stop** — do not destroy unreviewed work. Offer
-the user `--force` (and suggest committing/pushing first). Only re-run with
-`--force` when the user explicitly asks.
+If the CLI reports **blocked** (the worktree has uncommitted changes, or unpushed
+commits that aren't yet merged into the base branch), **relay the reason and
+stop** — do not destroy unreviewed work. Offer the user `--force` (and suggest
+committing/pushing first). Only re-run with `--force` when the user explicitly
+asks. **A branch already merged into the base needs no `--force`** — the unpushed
+guard treats "landed on base" as safe, so a completed spec (post-`/spec-complete`
+integrate) tears down cleanly even with no remote.
 
 ## 4. Execute the printed side effects
 
@@ -45,12 +48,17 @@ When not blocked, run the printed commands **in order**, exactly as printed:
    destroyed.
 2. **`docker compose … down`** — with `--volumes` unless `--keep-volumes`.
 3. **`git worktree remove …`** — removes the sibling worktree.
+4. **`git branch -d <branch>`** — deletes the spec's branch (freed by the worktree
+   removal above). It's `-d` (merged-only), never `-D`: if it reports the branch
+   isn't fully merged, **relay that and stop** — don't `-D` it. That only happens
+   on a `--force` teardown of unmerged work; the user can delete it by hand if
+   they're sure.
 
 The slot is already freed by the CLI.
 
 ## 5. Report
 
-Confirm what happened: worktree removed, containers down, volumes
-**dropped|kept**, slot freed, and the backup path (if any). If the spec wasn't
-provisioned / was already torn down, the CLI reports a clean **no-op** — relay
-that; it's not an error.
+Confirm what happened: worktree removed, branch deleted, containers down, volumes
+**dropped|kept**, slot freed, and the backup path (if any). If a `git branch -d`
+was refused (unmerged), say so. If the spec wasn't provisioned / was already torn
+down, the CLI reports a clean **no-op** — relay that; it's not an error.

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

@@ -26,6 +26,11 @@ 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.
+- **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,
+  so run `/add-dir <trusted root>` before editing into the worktree, or the
+  first edits will prompt.
 - **Do the rest in the worktree**, on the branch: open it (the printed opener, or
   a fresh Claude session rooted there) or, staying in this session, act on the
   worktree path with absolute paths / `git -C <worktreePath>`. The spec move,
@@ -45,7 +50,8 @@ Then move the spec (in the worktree when isolated, in place otherwise):
 - Append a **State log** row:
   `| <YYYY-MM-DD> | In Progress | in-progress | <git user.name> |`.
 - **When isolated:** commit the move and **push the branch** now — that records
-  the in-progress state for everyone and fires Linear's automation (when linked).
+  the in-progress state for everyone and fires the tracker's automation (when a
+  ticketing provider is linked).
 
 A spec ideally reaches here as `Ready` (via `/spec-ready`), but `/spec-go` works
 on a `Draft` too — just sanity-check it's well-formed before building.
@@ -71,22 +77,14 @@ Before writing any code for this phase, get the workspace and context clean:
   the spec file on disk is the source of truth, so nothing is lost. Pause for the
   `/compact`, then implement the phase.
 
-## 3b. Sync from Linear first (opt-in)
-
-**Only when `specs/.core/linear.config.json` exists** and the spec carries a
-`linear_project_id` in its `00-overview.md` frontmatter. Otherwise skip this
-step — no config means zero change to the flow below.
-
-- **Run `/spec-pull` first.** Bring down anything Linear changed since the last
-  sync (status, priority, discussion-driven fields) so you build against the
-  current shared state, not a stale snapshot. On a conflict it refuses — relay
-  that and let the user resolve before continuing; do not `--force` for them.
-- **Commit the refreshed snapshot** into the feature branch (a small
-  `chore(spec): pull latest from Linear`-style commit) so the frozen spec rides
-  in the PR alongside the code it describes.
-- Linear's GitHub branch/PR automation may now drive status transitions off the
-  branch and PR you pushed in step 2 — expect state to move on the Linear side;
-  keep any manual status edits minimal to avoid fighting it.
+## 3b. Pull from the tracker first (only if a provider is installed)
+
+**Only when a ticketing provider with a `/spec-pull` skill is installed** and the
+spec is linked to the tracker. Otherwise skip this step — no provider means zero
+change to the flow below. Follow the provider's pull steps below (nothing to do
+here without one).
+
+
 
 ## 4. Implement the phase
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@skitterbyte/skitterspec",
-  "version": "1.0.1",
-  "description": "Spec-driven-development workflow for Claude Code — installs the spec lifecycle skills, rule, and specs/ folders into any project.",
+  "version": "2.0.1",
+  "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",
     "claude-code",
@@ -27,16 +27,11 @@
   "dependencies": {
     "prompts": "^2.4.2"
   },
+  "scripts": {
+    "prepack": "node ../../scripts/build-dist.js skitterspec"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/skitterbyte/skitterspec.git"
-  },
-  "scripts": {
-    "test": "node --test",
-    "changelog": "node scripts/generate-changelog.js",
-    "changelog:retro": "node scripts/generate-changelog.js --retro",
-    "releases": "node scripts/generate-releases.js",
-    "releases:retro": "node scripts/generate-releases.js --retro",
-    "version": "node scripts/generate-changelog.js && node scripts/generate-releases.js && git add CHANGELOG.md RELEASES.md"
   }
-}
+}