@skitterbyte/skitterspec 0.1.0 → 1.0.0

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

@@ -0,0 +1,57 @@
+---
+name: spec-env
+description: Provision an isolated environment for a spec — a git worktree on its own branch + a namespaced Docker stack (isolated containers/networks/volumes + a reserved port block), plus an optional editor/terminal opener. Runs `skitterspec spec-env up` and executes the printed git/docker/open commands. Opt-in — needs specs/.core/env.config.json. Use when the user says "/spec-env", "spin up an environment for <spec>", "give this spec its own worktree/stack", or "isolate <spec>".
+---
+
+# /spec-env — provision an isolated environment for a spec
+
+Give an in-progress spec its own **git worktree** (a sibling directory on its own
+branch, no stashing) + a **namespaced Docker stack** (`COMPOSE_PROJECT_NAME`
+isolates containers/networks/volumes; `PORT_OFFSET` reserves a port block), so N
+specs run side by side and `main` stays clean. An optional `open.command` then
+opens the worktree however you like.
+
+This skill is **opt-in**: it only works when `specs/.core/env.config.json` exists
+(copy `env.config.json.example` to adopt it). If it's absent, tell the user how
+to enable it and stop.
+
+## 1. Identify the target spec
+
+- Use the spec named as an argument, else the spec **currently in context**. If
+  neither is clear, ask which spec.
+
+## 2. Plan the environment
+
+Run the engine — it allocates the slot (idempotent), persists the registry, and
+**prints** the plan (worktree path, branch, project name, port block, the exact
+commands, the `.env` contents, and the opener):
+
+```
+skitterspec spec-env up <spec>
+```
+
+If it reports the feature isn't enabled, relay that and stop — do not hand-roll a
+worktree/stack.
+
+## 3. Execute the printed side effects
+
+Run the printed commands **in order**, exactly as printed:
+
+1. **`git worktree add …`** — creates the sibling worktree on its branch. It is a
+   **sibling** of this checkout, **never nested** inside it. If the worktree
+   already exists, the engine prints the *attach* form (no `-b`) — do not clobber
+   an existing worktree/branch.
+2. **Write the `.env`** — write the printed `.env` contents into the new
+   worktree's env file (default `.env`). Do this *after* the worktree exists.
+3. **`docker compose … up -d`** — only printed when Docker is enabled. Brings the
+   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.
+
+## 4. Report
+
+Echo the summary: worktree path, branch, project name, the allocated slot + port
+block, and whether the stack was brought up. **Idempotent** — re-running attaches
+to the existing slot/worktree and never reallocates.
+
+Tear down later with `/spec-env-down <spec>`.

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

@@ -0,0 +1,56 @@
+---
+name: spec-env-down
+description: Tear down a spec's isolated environment — stop and remove its namespaced Docker stack (optionally backing up + dropping volumes), remove its git worktree, and free its slot. Guards refuse teardown on a dirty or unpushed worktree unless --force. Runs `skitterspec spec-env down` and executes the printed commands. Opt-in — needs specs/.core/env.config.json. Use when the user says "/spec-env-down", "tear down <spec>'s environment", "clean up the worktree/stack for <spec>", or "reclaim <spec>'s slot".
+---
+
+# /spec-env-down — tear down a spec's isolated environment
+
+Reverse `/spec-env`: stop + remove the spec's Docker stack, remove its git
+worktree, and free its slot so the ports/slot are reclaimed. **Volumes are the
+only destructive part** — dropped by default (to reclaim disk) unless
+`--keep-volumes`, and always backed up first when `docker.backupCommand` is set.
+
+Opt-in: only works when `specs/.core/env.config.json` exists. If absent, say so
+and stop.
+
+## 1. Identify the target spec
+
+- Use the spec named as an argument, else the spec **currently in context**. If
+  neither is clear, ask which spec.
+
+## 2. Plan the teardown
+
+Run the engine — it checks the guards, frees the slot, and **prints** the plan:
+
+```
+skitterspec spec-env down <spec> [--keep-volumes] [--force]
+```
+
+- **`--keep-volumes`** — keep the stack's data (plain `down`, no backup, no drop).
+- **`--force`** — override the guards below.
+
+## 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.
+
+## 4. Execute the printed side effects
+
+When not blocked, run the printed commands **in order**, exactly as printed:
+
+1. **Backup** (only when a `docker.backupCommand` is configured and volumes are
+   being dropped) — writes a dump under `.spec-env/backups/` before anything is
+   destroyed.
+2. **`docker compose … down`** — with `--volumes` unless `--keep-volumes`.
+3. **`git worktree remove …`** — removes the sibling worktree.
+
+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.

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

@@ -18,6 +18,23 @@ description: Promote a spec into active development and implement its first phas
 
 ## 2. Move it into development
 
+**If per-spec isolation is enabled** (`specs/.core/env.config.json` exists) and
+the spec doesn't already have a worktree, provision it **first**, so all the
+housekeeping below lands on the spec's branch and never on `main`:
+
+- Run `skitterspec spec-env up <name>` (the `/spec-env` engine). It adds a git
+  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.
+- **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,
+  header edits **and** the phase's code all happen on the branch — so the spec's
+  evolution travels with the code it describes and lands in one PR. `main` changes
+  only when that branch merges (at `/spec-complete`).
+
+Then move the spec (in the worktree when isolated, in place otherwise):
+
 - If it isn't already under `specs/in-progress/`, move the whole spec folder
   there. **Use `git mv`** to keep history:
   `git mv "specs/backlog/<name>" "specs/in-progress/<name>"`.
@@ -27,14 +44,16 @@ description: Promote a spec into active development and implement its first phas
 - Set the **Developer** header field if it's still `—`: use `git config user.name`.
 - Append a **State log** row:
   `| <YYYY-MM-DD> | In Progress | in-progress | <git user.name> |`.
-- **Remove the spec's row from `specs/backlog/00-index.md`** — it has left the backlog
-  (there is no index for `in-progress`).
+- **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).
 
 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.
 
 If the spec is already in `in-progress`, skip the move and implement the **next
-unfinished phase** instead of Phase 1.
+unfinished phase** instead of Phase 1. (When isolated, subsequent `/spec-go` runs
+happen from inside the worktree — where the spec already sits in `in-progress` on
+the branch — and a re-run of `spec-env up` just re-attaches it.)
 
 ## 3. Pre-flight — commit prior work, then compact
 
@@ -52,6 +71,23 @@ 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.
+
 ## 4. Implement the phase
 
 Identify the **first unfinished phase** from the `00-overview.md` phase index,

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

@@ -27,14 +27,6 @@ empty so git keeps them:
 - `specs/.core/` — project rules (always apply; never moved)
 - `specs/backlog/` `specs/in-progress/` `specs/complete/` `specs/cancelled/`
 
-Also ensure the two index files exist (create with just their header comment +
-table header if missing — do not regenerate if present):
-
-- `specs/backlog/00-index.md` — live view of backlog (`Added | Spec | Type | Status`);
-  `/spec` adds rows, `/spec-go` and `/spec-cancel` remove them.
-- `specs/complete/00-index.md` — append-only completion log (`Completed | Spec | Type`),
-  newest first; `/spec-complete` prepends a row.
-
 ## 2. Version control — keep specs tracked
 
 The whole lifecycle lives in git — **everything under `specs/` is tracked**, so

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

@@ -0,0 +1,46 @@
+---
+name: spec-pull
+description: Pull a spec's linked Linear project into the local spec (Linear → repo), three-way aware. Applies remote-only fields; refuses to clobber local edits on a conflict unless --force (which backs up the local side first). Fetches Linear over MCP and runs `skitterspec spec-sync pull`. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-pull", "pull from Linear", "sync Linear changes down", or "update this spec from Linear".
+---
+
+# /spec-pull — bring Linear changes into the spec
+
+Linear → repo. Applies fields Linear changed since the last sync (status,
+priority, labels, and co-authored fields), rewrites the committed base, and
+stamps `last_synced_at`. It **refuses** to overwrite a local edit that conflicts
+with a Linear edit unless you pass `--force`.
+
+**Opt-in**: only runs when `specs/.core/linear.config.json` exists. If absent,
+tell the user how to enable Linear sync and stop.
+
+## 1. Identify the target spec
+
+Use the argument, else the spec in context; ask if unclear.
+
+## 2. Fetch the Linear project
+
+- Read `linear_project_id` from `00-overview.md` frontmatter; if missing, the
+  spec isn't linked — stop and point at `/spec`.
+- Discover the Linear MCP project-read tool at runtime. If Linear isn't
+  connected, relay the fix and stop — **do nothing destructive**.
+- Call it and write the project JSON to a temp file.
+
+## 3. Run the engine
+
+```
+skitterspec spec-sync pull <spec> --remote <tempfile> [--force]
+```
+
+- **No conflict** — the engine applies remote-only fields to the local snapshot,
+  rewrites the base, and stamps the sync. Body fields with no local home yet are
+  reported as `deferred` (apply them by hand from Linear if needed).
+- **Conflict** (a co-authored field changed on both sides) — the engine
+  **refuses** and lists the fields. Relay that; do not force on the user's behalf.
+- **`--force`** — only when the user explicitly asks. Remote wins after the engine
+  backs up the local side under `sync.backupDir` (the reflog). Relay the backup
+  path.
+
+## 4. Report
+
+Relay the git-like summary (applied / deferred / conflicts / backup / base). If
+fields were applied, remind the user to review and commit the refreshed snapshot.

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

@@ -0,0 +1,53 @@
+---
+name: spec-push
+description: Push a spec's local content up to its linked Linear project (repo → Linear), three-way aware and ownership-respecting. Never pushes pull-owned fields or local-only sections; aborts if Linear moved since the last sync unless --force (which backs up the remote side first). Runs `skitterspec spec-sync push` then applies the blessed writes over MCP. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-push", "push to Linear", "sync my spec up to Linear", or "update the Linear project from this spec".
+---
+
+# /spec-push — send spec content up to Linear
+
+Repo → Linear. Sends the fields the repo owns/co-authors (description, phases,
+tasks per config) up to the linked project. It **never** writes `pull`-owned
+fields (status/priority/labels) or `localOnlySections`, and it **aborts** if
+Linear moved since the last sync (pull first) unless you `--force`.
+
+**Opt-in**: only runs when `specs/.core/linear.config.json` exists. If absent,
+tell the user how to enable Linear sync and stop.
+
+## 1. Identify the target spec
+
+Use the argument, else the spec in context; ask if unclear.
+
+## 2. Fetch the Linear project
+
+- Read `linear_project_id` from `00-overview.md` frontmatter; if missing, stop
+  (link via `/spec` first).
+- Discover the Linear MCP tools at runtime (project read **and** update). If
+  Linear isn't connected — or the update tool is missing — relay the fix and stop,
+  **writing nothing**.
+- Call the read tool and write the project JSON to a temp file.
+
+## 3. Run the engine (the guard)
+
+```
+skitterspec spec-sync push <spec> --remote <tempfile> --out <mergedfile> [--force]
+```
+
+- **Refused** (`remote-moved` / `concurrent-write` / conflict) — relay the message
+  and **stop**. Do not write to Linear. Suggest `/spec-pull` first.
+- **OK** — the engine has confirmed it's safe, rewritten the base, and stamped
+  `last_synced_at`. Its summary lists the `written` fields (and any `skipped`
+  because they're not pushable).
+- **`--force`** — only when the user explicitly asks. Local wins after the engine
+  backs up the remote side under `sync.backupDir`. Relay the backup path.
+
+## 4. Apply the blessed writes to Linear
+
+Only when step 3 returned OK: for each `written` field, call the Linear update
+tool with that field's local value (e.g. `description` → the project description).
+The engine has already vetted the change and moved the base — so if a Linear
+write fails, re-run `/spec-pull` to reconcile rather than retrying blindly.
+
+## 5. Report
+
+Relay the git-like summary (written / skipped / backup / base) plus which Linear
+fields you updated.

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

@@ -42,8 +42,6 @@ Offer to fix small gaps inline if the user wants; otherwise leave it `Draft`.
   `> **Status:** Ready (<YYYY-MM-DD>)`.
 - Append a **State log** row: `| <YYYY-MM-DD> | Ready | backlog | <git user.name> |`
   (no folder change — Ready stays in `backlog`).
-- Update the spec's row in `specs/backlog/00-index.md` — set its Status column to
-  `Ready` (the row stays; the spec is still in backlog).
 - Optionally add a **Changelog** note if grooming changed anything substantive.
 
 ## 4. Report

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

@@ -59,8 +59,8 @@ reading the code, do that instead of asking.
   Reviewed vs codebase: retargeted Phase 2 onto X, dropped Y (removed), ticked Z
   (already done)`).
 - **Status:** if drift is minor, leave status as-is. If a `Ready` spec needs real
-  re-grooming, knock it back to `Draft` (set `> **Status:** Draft`, append a
-  **State log** row, and reset its row in `specs/backlog/00-index.md` to `Draft`).
+  re-grooming, knock it back to `Draft` (set `> **Status:** Draft` and append a
+  **State log** row).
 
 ## 5. Report
 

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

@@ -0,0 +1,46 @@
+---
+name: spec-status
+description: Show a spec's sync status against its linked Linear project — a read-only, git-status-style per-field divergence (local-only / remote-only / conflict / in-sync). Fetches the Linear project over MCP and runs `skitterspec spec-sync status`. Changes nothing. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-status", "is this spec in sync with Linear", "what's diverged from Linear", or "show spec sync status".
+---
+
+# /spec-status — show a spec's divergence from Linear
+
+Read-only. Prints, per field, whether the spec and its linked Linear project have
+diverged since the last sync — the `git status` of the hybrid sync. Writes
+nothing to either side.
+
+This skill is **opt-in**: it only runs when `specs/.core/linear.config.json`
+exists. If it's absent, tell the user to copy `linear.config.json.example` →
+`linear.config.json` to enable Linear sync, and stop.
+
+## 1. Identify the target spec
+
+Use the spec named as an argument, else the spec **currently in context**. If
+neither is clear, ask which spec.
+
+## 2. Fetch the Linear project (read-only)
+
+- Read the spec's `linear_project_id` from `00-overview.md` frontmatter. If it's
+  missing, the spec isn't linked yet — say so and stop (link it via `/spec`).
+- Discover the connected Linear MCP tools at runtime (the project-read tool). If
+  Linear isn't connected, relay "connect the `linear` MCP server" and stop — do
+  nothing else.
+- Call the project-read tool for that id and write the returned JSON to a temp
+  file (e.g. under the OS temp dir).
+
+## 3. Run the engine
+
+```
+skitterspec spec-sync status <spec> --remote <tempfile>
+```
+
+The engine does the three-way compare (local vs Linear vs the committed base) and
+prints each diverged field with its classification and sync direction. Without
+`--remote` it falls back to a local-vs-base comparison (still read-only).
+
+## 4. Report
+
+Relay the engine's summary verbatim, then offer the natural next step:
+`/spec-pull` for remote-only changes, `/spec-push` for local-only, and — for a
+`conflict` — resolve locally or use `--force` (which backs up the losing side).
+Never write anything from this skill.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "Spec-driven-development workflow for Claude Code — installs the spec lifecycle skills, rule, and specs/ folders into any project.",
   "keywords": [
     "claude",
@@ -27,6 +27,10 @@
   "dependencies": {
     "prompts": "^2.4.2"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/skitterbyte/skitterspec.git"
+  },
   "scripts": {
     "test": "node --test",
     "changelog": "node scripts/generate-changelog.js",
@@ -34,9 +38,5 @@
     "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"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/skitterbyte/skitterspec.git"
   }
-}
+}