@skitterbyte/skitterspec-linear 3.4.0 → 5.0.0

package/README.md

@@ -12,6 +12,45 @@ npx @skitterbyte/skitterspec-linear init
 
 Install **this OR the base**, never both — this package contains the entire base.
 
+## Quick start
+
+Get sync working in four steps (the scaffolded `specs/.core/SETUP.md` is the
+fuller guide):
+
+1. **Install** into your repo:
+
+   ```sh
+   npx @skitterbyte/skitterspec-linear init
+   ```
+
+2. **Connect the Linear MCP server** (once per machine) — the skills talk to
+   Linear over MCP, so this is the prerequisite people miss:
+
+   ```sh
+   claude mcp add --transport http linear https://mcp.linear.app/mcp
+   ```
+
+   Then, in Claude Code, run `/mcp` → select **linear** → **Authenticate** (a
+   browser opens; pick your workspace). A freshly added server only shows up after
+   Claude Code restarts — relaunch with `claude --continue` if you don't see it.
+   Verify with `claude mcp list` (want `linear … ✓`).
+
+3. **Configure** — copy the scaffolded example and fill in your team id (ask
+   Claude "list my Linear teams" once connected to get it):
+
+   ```jsonc
+   // specs/.core/linear.config.json
+   { "linear": { "teamId": "<your-team-uuid>" } }
+   ```
+
+   That file is the opt-in gate — until it exists, everything below is inert and
+   the package behaves exactly like the base.
+
+4. **Link and sync** — `/spec` now creates a linked Linear Project (a Milestone
+   per phase) and stamps the id; then `/spec-status`, `/spec-pull`, `/spec-push`
+   keep the spec and its project in step. Optionally turn on the per-Milestone /
+   per-Issue **body round-trip** (see below).
+
 ## What the superset adds
 
 On top of the base skills (`/spec`, `/spec-go`, isolation, …):
@@ -39,14 +78,15 @@ behaves exactly like the base.
 setup guide — connecting the `linear` MCP server, finding your team id, linking a
 spec, and a smoke test. Per-field docs live in `specs/.core/linear.config.md`.
 
-**What syncs today:** the whole spec body travels as the Linear Project
+**What syncs:** by default the whole spec body travels as the Linear Project
 **`description`** (co-authored, push + pull); **status / priority / labels** are
 Linear-owned (pull only). **Field ownership** (`both` / `pull` / `push`) collapses
 conflicts — only a `both` field that moved on both sides is a real conflict, and
-`--force` backs up the losing side before winning. A per-**Milestone** /
-per-**Issue** round-trip (phases and tasks as first-class Linear objects) is a
-planned extension — see `linear.config.md`. **Base sidecars**
-(`specs/.core/linear-base/`) are committed; **backups**
+`--force` backs up the losing side before winning. **Opt into a per-Milestone /
+per-Issue body round-trip** — phases ↔ Linear Milestones and tasks ↔ Issues,
+compared per item — by adding `milestones`/`tasks` to `sync.keyedFields` (see the
+"Body round-trip" section of `linear.config.md`); deletions there are report-only.
+**Base sidecars** (`specs/.core/linear-base/`) are committed; **backups**
 (`specs/.core/linear-backups/`) are gitignored.
 
 Branch naming that embeds the Linear id lives in the isolation config

package/assets/core/SETUP.md

@@ -124,11 +124,17 @@ in-repo → `/spec-push` (send content up).
 | `priority` | Linear | pull only |
 | `labels` | Linear | pull only |
 
-The **entire spec body travels as the project `description`** — phases and
-acceptance criteria included. A separate per-milestone / per-issue round-trip
-(editing an individual phase in Linear and pulling just that back) is **not yet
-implemented**; opt in later by adding `milestones`/`phaseBodies`/`taskBreakdown`
-to `sync.fieldOwnership` once that write path exists.
+By default the **entire spec body travels as the project `description`** — phases
+and acceptance criteria included.
+
+**Optional: body round-trip.** Opt in — add `milestones`/`tasks` to
+`sync.keyedFields` (and `sync.fieldOwnership`) — and phases sync as **Milestones**
+and tasks as **Issues**, compared per item: edit an individual phase or task in
+Linear and pull just that back into the right phase file / task line, or push
+local changes up. The link ids live in the phase file frontmatter
+(`linear_milestone_id`) and inline on task lines (`- [ ] do it (SKI-123)`).
+Deletions are report-only (surfaced by `/spec-status`, never auto-applied). Full
+details in the "Body round-trip" section of `linear.config.md`.
 
 Sections listed in `sync.localOnlySections` (default: **State log**, **Changelog**,
 **Open questions**) are stripped from the pushed description — they never leave

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

@@ -34,5 +34,8 @@
   "guards": {
     "refuseTeardownIfDirty": true,
     "refuseTeardownIfUnpushed": true
+  },
+  "live": {
+    "migrations": []
   }
 }

package/assets/core/env.config.md

@@ -146,6 +146,15 @@ no live `env.config.json` was found.
   "guards": {
     "refuseTeardownIfDirty": true,
     "refuseTeardownIfUnpushed": true
+  },
+
+  // Live overlay (`spec-env live` / `/spec-live`): test a spec on the already-
+  // running dev server by checking its branch out in the primary checkout.
+  // `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 — use `/spec-connect` for those). Default: none.
+  "live": {
+    "migrations": []
   }
 }
 ```

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

@@ -30,6 +30,7 @@
       "priority": "pull",
       "labels": "pull"
     },
-    "localOnlySections": ["State log", "Changelog", "Open questions"]
+    "localOnlySections": ["State log", "Changelog", "Open questions"],
+    "keyedFields": {}
   }
 }

package/assets/core/linear.config.md

@@ -92,11 +92,48 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push` is a hard error
 
     // Markdown sections of 00-overview.md that are local-only scaffolding and
     // are stripped from the pushed `description` (never sent to Linear).
-    "localOnlySections": ["State log", "Changelog", "Open questions"]
+    "localOnlySections": ["State log", "Changelog", "Open questions"],
+
+    // OPT-IN body round-trip. Map a keyed collection field → its item id key to
+    // sync it per item (each phase ↔ a Milestone, each task ↔ an Issue) instead of
+    // as one description blob. Empty by default. See "Body round-trip" below.
+    "keyedFields": {}
   }
 }
 ```
 
+## Body round-trip (milestones & tasks) — opt-in
+
+By default the whole spec body travels as the project **`description`**. Opt a
+workspace into a finer-grained, bidirectional sync by adding the keyed fields:
+
+```jsonc
+"sync": {
+  "fieldOwnership": { "milestones": "both", "tasks": "both" },
+  "keyedFields": { "milestones": "id", "tasks": "id" }
+}
+```
+
+With this on:
+
+- **Phases ↔ Milestones.** Each phase file maps to a Linear Milestone. The link id
+  lives in the phase file's frontmatter (`linear_milestone_id`); its title ← the
+  phase h1, its description ← the phase `**Goal:**` line. The `Phases` index is
+  then stripped from the pushed `description` (no duplication).
+- **Tasks ↔ Issues.** Each `- [ ]` task line maps to a Linear Issue. The link id
+  is carried **inline** on the line — `- [ ] do the thing (SKI-123)`. Text ↔ the
+  issue title; `[x]`/`[ ]` ↔ a completed / non-completed issue state.
+- **Per-item merge.** Items are compared by id, so editing milestone A locally and
+  milestone B in Linear both apply; only the *same* item moving on both sides is a
+  conflict.
+- **Deletions are report-only.** A phase/milestone or task/issue removed on either
+  side is surfaced by `/spec-status` (and the pull/push summaries) for you to
+  resolve by hand — it is never auto-deleted.
+
+Unlinked local items (a new phase with no `linear_milestone_id`, a task with no
+inline id) are created in Linear on the next `/spec-push`, which stamps the new id
+back so they link from then on.
+
 ## Field ownership & conflicts
 
 The spec is a set of structured fields, most written by only one side. Marking a

package/assets/rules/spec-planning.md

@@ -39,6 +39,20 @@ changes only when it merges. Teardown is folded into `/spec-complete` ·
 lifecycle status** and inactive when `env.config.json` is absent — every skill
 then behaves as it does today.
 
+**Live overlay (`/spec-live`) — the light way to test a spec.** `/spec-connect`
+runs a spec's *own* dev stack and proxies the canonical ports to it (one stack per
+spec). **Live overlay** instead reuses the one dev server you already have running:
+`/spec-live <spec>` rebases the branch onto base, frees it from its worktree, and
+checks it out **in the primary checkout**, so your running server hot-reloads the
+feature at the normal URL — no second stack, no proxy. The branch checked out in
+the primary checkout **is** the lock: exactly one spec is live at a time, and
+`/spec-live main` hands the instance back (fixes you make while live commit
+straight onto the branch; `/spec-complete` is live-aware and lands them). Rule of
+thumb: **live overlay is the light default for code-only specs**; it *refuses*
+stateful ones (`Stack: worktree + docker`, or a branch touching migrations) — keep
+`/spec-connect` + a Docker stack for those, and for genuinely parallel testing.
+Beneath it, `skitterspec spec-env live <take|release|abort|status>` is the engine.
+
 **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

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

@@ -62,6 +62,12 @@ applies, offer to land the finished branch on the base branch so the work reache
 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.
+   **If the spec is live** (you took the running instance with `/spec-live`):
+   `integrate` is live-aware — it ends the live session first (releases the branch
+   back to base, re-isolates it into its worktree, clears the receipt), then prints
+   the normal landing plan. Commit any live fixes to the branch first; it refuses
+   if the primary checkout is dirty, or if a *different* spec holds it (release that
+   one with `/spec-live main`). Teardown (step 7) is unchanged.
 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.

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

@@ -15,6 +15,12 @@ This skill is **opt-in**: it needs `specs/.core/env.config.json` with a `dev`
 block (host dev servers + their `frontPort`s). If isolation or `dev` is absent,
 say so and stop.
 
+**Lighter alternative for a code-only spec:** `/spec-live` reuses the dev server
+you already have running (it branch-switches the primary checkout) instead of
+starting a second stack — no proxy, one process. Prefer it for code-only specs;
+use `/spec-connect` when a spec has its own Docker stack, or to run several stacks
+in parallel.
+
 ## 1. Identify the target
 
 - Use the spec named as an argument. The literal `main` means **disconnect**

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

@@ -98,7 +98,9 @@ runnable — its UI/API on the spec's reserved port block, isolated from `main`.
 - **Diverting your browser is a separate step.** To test the spec at your normal
   `localhost` URL, run **`/spec-connect <name>`** (exclusive — it exposes this
   spec on the canonical ports; `/spec-connect main` hands them back). `/spec-go`
-  never seizes the canonical ports on its own.
+  never seizes the canonical ports on its own. For a **code-only** spec, the
+  lighter **`/spec-live <name>`** reuses your already-running dev server (a
+  branch-switch, no second stack) — `/spec-live main` hands it back.
 
 ## 3. Pre-flight — commit prior work
 

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

@@ -13,6 +13,14 @@ clobber customised content. Finish with a summary of created vs already-present.
 > all of the below mechanically. This skill is the manual/repair path and is
 > useful when the package isn't available or you only need to fix part of the
 > setup.
+>
+> **Re-running on an already-set-up repo is safe.** `init` detects the existing
+> setup (via the committed `specs/.core/.skitterspec-manifest.json` of installed
+> file hashes) and, interactively, offers three paths — **Resync** (update managed
+> skills/rules to the latest but keep files you've edited), **Start again** (reset
+> the managed scaffolding fresh — never your specs or config, with a confirm), or
+> **Leave alone**. Non-interactively it only adds what's missing; `--resync` /
+> `--reset` (reset needs `--yes`) drive the stronger actions.
 
 The system is **eight skills**: `spec` (feature), `spec-bug` (bug), `spec-ready`,
 `spec-review`, `spec-go`, `spec-complete`, `spec-cancel`, and this `spec-init`. The lifecycle is

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

@@ -0,0 +1,70 @@
+---
+name: spec-live
+description: Test a spec on your already-running dev server by checking its branch out in the primary checkout — no second stack, no proxy. `spec-live <spec>` takes the running instance for that spec; `spec-live main` releases it. Runs `skitterspec spec-env live`. Opt-in — needs specs/.core/env.config.json. Code-only specs; stateful (Docker/migration) specs use /spec-connect. Use when the user says "/spec-live", "go live with <spec>", "take the instance for <spec>", or "test <spec> on the running server".
+---
+
+# /spec-live — put one spec live on the running instance
+
+Instead of running a second dev stack for a spec (that's `/spec-connect`), **reuse
+the one instance you already have**: rebase the spec's branch onto base, hand it
+from its worktree to the **primary checkout**, and let your running dev server
+hot-reload it. You test at your normal URL, with one process. The branch that's
+checked out in the primary checkout **is** the lock — exactly one spec is live at
+a time, and `/spec-live main` hands the instance back.
+
+This skill is **opt-in**: it needs `specs/.core/env.config.json`. If isolation is
+absent, say so and stop.
+
+**Code-only.** Live overlay refuses a **stateful** spec — one whose `> **Stack:**`
+is `worktree + docker`, or whose branch changes migrations (per
+`env.config.json` → `live.migrations`). Those keep their isolated stack; use
+`/spec-connect` for them. The engine enforces this and prints why.
+
+## 1. Identify the target
+
+- Use the spec named as an argument. The literal `main` means **release** (hand
+  the instance back to base). Else use the spec **currently in context**; if
+  unclear, ask.
+
+## 2. Make sure a dev server is running
+
+`live take` **verifies** a dev server is up on your canonical ports and switches
+the branch under it — it does **not** start one. If nothing is listening it
+refuses; start your dev server first (however you normally run it, or
+`skitterspec spec-env dev up <spec>`). (Projects with no `dev` servers configured
+have nothing to hot-reload — the switch still happens, with a warning.)
+
+## 3. Take (or release)
+
+```
+skitterspec spec-env live take <spec>   # rebase → detach worktree → checkout in primary
+skitterspec spec-env live release        # hand the instance back to base, re-isolate the branch
+skitterspec spec-env live abort          # crash recovery (see below)
+skitterspec spec-env live status         # who's live (branch in the primary checkout + receipt)
+```
+
+**Take** rebases the branch onto base, frees it from its worktree
+(`switch --detach`), checks it out in the primary checkout, then writes a receipt
+(`.spec-env/live.json`). Relay its output. **If it reports the rebase hit
+conflicts**, it left everything untouched — rebase the branch in its worktree,
+resolve, then retry. **If it says a spec already holds the instance**, release it
+first. If it warns dependencies changed, restart your dev server after the switch.
+
+**Release** (`/spec-live main`) is the graceful exit of an unfinished session:
+`skitterspec spec-env live release` reads the live spec from the receipt, checks
+base back out in the primary checkout, re-attaches the branch to its worktree, and
+clears the receipt. Commit any fixes to the branch first — it refuses on a dirty
+tree rather than discard them. (To *finish* a live spec instead of releasing it,
+use `/spec-complete`, which is live-aware.)
+
+**Abort** is crash recovery, for when a session died mid-take and left the primary
+checkout on a feature branch: `skitterspec spec-env live abort` restores base from
+the receipt and re-isolates. It refuses if the primary checkout has uncommitted
+changes (it won't discard them) — commit or stash first.
+
+## 4. Report
+
+Echo which spec is now live on the primary checkout (and any warning), that it was
+released / recovered, or — for `status` — which branch the primary checkout is on
+and whether the instance is free. Fixes you make while live commit straight onto
+the spec's branch.

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

@@ -23,7 +23,10 @@ Use the argument, else the spec in context; ask if unclear.
   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.
+- Call it (include milestones) and write the project JSON to a temp file. When
+  tasks are keyed, also list the project's issues and add them as an `issues`
+  array on that JSON (each `{ identifier, title, state }`) so the engine can
+  reconcile task lines.
 
 ## 3. Run the engine
 

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

@@ -47,6 +47,27 @@ tool with that field's local value (e.g. `description` → the project descripti
 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.
 
+**Milestones (`milestonesPush` in the result).** When milestones are keyed, the
+engine can't write them itself — apply the plan over MCP:
+
+- `update`: for each `{ id, name, goal }`, call the milestone-save tool with that
+  `id` (name → milestone name, goal → its description).
+- `create`: for each `{ name, goal }`, call the milestone-save tool with no id to
+  create it under the project, then **stamp the returned milestone id** into the
+  matching phase file's frontmatter (`linear_milestone_id`) so it links on the
+  next sync. Match the phase file by its title.
+
+Progress is Linear-derived — never push it.
+
+**Issues (`issuesPush` in the result).** When tasks are keyed:
+
+- `update`: for each `{ id, text, done }`, call the issue-save tool with that `id`
+  (text → title; `done` → a completed state, else a non-completed state — leave an
+  already-non-completed issue's exact state untouched).
+- `create`: for each `{ text, done }`, create an issue under the project (attach it
+  to the milestone of the phase the task lives in when known), then **stamp the new
+  issue identifier inline** on that task line (`… (SKI-123)`), matching by text.
+
 ## 5. Report
 
 Relay the git-like summary (written / skipped / backup / base) plus which Linear

package/package.json

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