@skitterbyte/skitterspec-linear 8.0.5 → 9.1.0

package/README.md

@@ -4,7 +4,7 @@ Spec-driven development for [Claude Code](https://claude.com/claude-code), **wit
 one-way Linear sync**. A strict **superset** of
 [`@skitterbyte/skitterspec`](https://www.npmjs.com/package/@skitterbyte/skitterspec):
 everything in the base filesystem workflow, plus one-way sync from a spec up to
-its linked Linear project — the repo is canonical, Linear is a generated mirror.
+its linked Linear issue — the repo is canonical, Linear is a generated mirror.
 
 ```sh
 npx @skitterbyte/skitterspec-linear init
@@ -46,7 +46,7 @@ fuller guide):
    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 push** — `/spec` creates a linked Linear Project (a Milestone per
+4. **Link and push** — `/spec` creates a linked Linear issue (a sub-issue per
    phase) and stamps the id; then `/spec-push` publishes the spec up and
    `/spec-status` reports what would push. Sync is **one-way**: the repo is the
    source of truth and Linear is a generated mirror.
@@ -58,14 +58,17 @@ On top of the base skills (`/spec`, `/spec-go`, isolation, …):
 - **`/spec-status`** — read-only drift report: what the next push would create /
   update, plus any workflow-state drift. Changes nothing.
 - **`/spec-push`** — repo → Linear, one-way. Diffs the spec against a committed
-  last-pushed snapshot and applies only what changed (project description +
-  status, milestones, issues), stamping the returned ids back into the spec.
+  last-pushed snapshot and applies only what changed (issue description + state,
+  phase sub-issues), stamping the returned ids back into the spec.
 - **`spec-sync` CLI** (`skitterspec-linear spec-sync …`) — the deterministic
   engine behind the skills, for CI / local runs.
 
-The shared `/spec` and `/spec-go` skills come composed with the Linear steps
-filled in: `/spec` links a new spec to a Linear Project (a Milestone per phase).
-There is no pull — the repo is already canonical, so `/spec-go` just builds.
+The shared `/spec`, `/spec-bug` and `/spec-go` skills come composed with the
+Linear steps filled in: `/spec` asks which Linear **Project** the spec belongs to,
+then links it to a Linear issue (a sub-issue per phase). `/spec` and `/spec-bug`
+can also start **from** an existing issue — `/spec SKI-123`, or `/spec
+--from-issue` to browse the ones your web app filed. There is no pull — the repo
+is already canonical, so `/spec-go` just builds.
 
 ## Opt-in
 
@@ -77,15 +80,30 @@ 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 pushes:** the spec body travels as the Linear Project **`description`**,
-phases as **Milestones**, tasks as **Issues** (a short first-sentence title, the
-full task text as the description), and the lifecycle bucket sets the project's
-**workflow state**. Priority, labels, cycles and comments are **Linear-native
-triage** — the PM's to set in Linear; one-way sync neither pushes nor reads them,
-so they're never clobbered. A workflow-state a teammate moves in Linear is
-surfaced by `/spec-status` as drift and overwritten on the next push. **Last-pushed
-snapshots** (`specs/.core/linear-base/`, content hashes) are committed so push
-sends only what changed.
+**What pushes:** the spec is one Linear **issue** — the spec body travels as its
+**`description`**, each phase as a **sub-issue** (phase name → title, `**Goal:**`
+→ description, phase emoji → state), and the spec's lifecycle folder sets the
+issue's **workflow state**. Tasks are **not** synced — they stay in the repo phase
+files. Priority, labels, cycles and comments are **Linear-native triage** — the
+PM's to set in Linear; one-way sync neither pushes nor reads them, so they're
+never clobbered. A workflow-state a teammate moves in Linear is surfaced by
+`/spec-status` as drift and overwritten on the next push. **Last-pushed snapshots**
+(`specs/.core/linear-base/`, content hashes) are committed so push sends only what
+changed.
+
+**Which Project a spec lands in** is asked once, when the issue is first created
+— a filterable list of your team's projects, defaulting to `linear.projectId` and
+always offering *None*. It's passed on the create call only and never stored, so
+re-homing a spec issue in Linear sticks: it won't read as drift and won't be moved
+back on the next push.
+
+**Starting from an issue** (`intake.label` / `intake.bugLabels` in the config):
+`/spec SKI-123` adopts that issue, `/spec --from-issue [query]` browses the inbox.
+The issue *becomes* the spec's issue — the reporter's thread, comments and links
+stay put, their words are carried into the spec's **Problem**, and the first push
+replaces the description with the spec. A bug-labelled issue routes to
+`/spec-bug`, which adopts it the same way. `skitterspec-linear spec-sync linked`
+lists what's already adopted, so an issue never becomes two specs.
 
 Branch naming that embeds the Linear id lives in the isolation config
 (`env.config.json` → `branch.pattern` with `{identifier}`, `branch.identifierField:

package/assets/core/SETUP.md

@@ -2,10 +2,10 @@
 
 A start-to-finish guide to getting `/spec-status` and `/spec-push` working against
 a real Linear workspace. Sync is **one-way**: the repo is the source of truth and
-the linked Linear project is a **generated mirror** — content is pushed up, never
-read back or merged. Covers the **Linear side** (connecting the MCP server,
-finding your team) that the config reference (`linear.config.md`) assumes you
-already have.
+the linked Linear **issue** is a **generated mirror** — content is pushed up, never
+read back or merged. A spec is a Linear issue and each phase a sub-issue; tasks are
+not synced. Covers the **Linear side** (connecting the MCP server, finding your
+team) that the config reference (`linear.config.md`) assumes you already have.
 
 > The whole feature is **opt-in**: until `specs/.core/linear.config.json` exists,
 > everything below is inert and the package behaves exactly like the base
@@ -65,9 +65,10 @@ It calls the Linear `list_teams` tool and returns rows like:
 Skitterspec — e07c2b54-dcf6-4b6e-81bd-175a9bc79868  (key: SKI)
 ```
 
-Copy the `id` (the UUID). The `key` (e.g. `SKI`) is the short human handle. If you
-want an **Initiative** to group your specs, ask "list my Linear initiatives" and
-copy that id too (optional).
+Copy the `id` (the UUID). The `key` (e.g. `SKI`) is the short human handle. If most
+of your specs belong to one **Project**, ask "list my Linear projects" and copy
+that id into `linear.projectId` — it becomes the *default* the project picker
+pre-selects, not a fixed destination.
 
 ## 4. Scaffold the config
 
@@ -80,7 +81,11 @@ ids from step 3 — the team id is the only required field:
   "linear": {
     "teamKey": "SKI",
     "teamId": "e07c2b54-dcf6-4b6e-81bd-175a9bc79868",
-    "initiativeId": ""            // optional
+    "projectId": ""              // optional: the project picker's default
+  },
+  "intake": {                    // optional: starting a spec from an issue
+    "label": "web-app",          // the inbox `/spec --from-issue` browses
+    "bugLabels": ["bug"]         // issues with these route to /spec-bug
   }
 }
 ```
@@ -89,20 +94,25 @@ Everything else (state names, field ownership) has sensible defaults — see
 `linear.config.md` to customise. The moment this file exists, the Linear steps in
 `/spec` and `/spec-go` and the three sync skills switch on.
 
-## 5. Link a spec to a Linear project
+## 5. Link a spec to a Linear issue
 
-A spec syncs once its `00-overview.md` frontmatter carries a `linear_project_id`.
+A spec syncs once its `00-overview.md` frontmatter carries a `linear_identifier`.
 Two ways to get there:
 
-- **New spec:** run `/spec` — with Linear configured it offers to create a linked
-  Linear **Project** (one Milestone per phase) and stamps the id for you.
-- **Existing spec / existing Linear project:** add the id by hand. Ask Claude to
-  "create a Linear project for this spec" (or find an existing one's id via
-  `list_projects`), then set the frontmatter:
+- **New spec:** run `/spec` — with Linear configured it asks which Project the
+  spec belongs to, creates a linked Linear **issue** (one sub-issue per phase) and
+  stamps the id for you.
+- **From an existing issue:** run `/spec SKI-123` to adopt that issue, or
+  `/spec --from-issue` to browse the `intake.label` inbox and pick one. The issue
+  becomes the spec's issue — nothing is duplicated. A bug-labelled issue routes to
+  `/spec-bug` instead.
+- **Existing spec / existing Linear issue:** add the id by hand. Ask Claude to
+  "create a Linear issue for this spec" (or find an existing one's id), then set
+  the frontmatter:
 
   ```yaml
   ---
-  linear_project_id: "640bcb1a-28cd-46b5-b2f8-ff47ce494ed1"
+  linear_identifier: "SKI-123"
   ---
   ```
 
@@ -111,7 +121,7 @@ Two ways to get there:
 | Command | Direction | What it does |
 |---------|-----------|--------------|
 | `/spec-status` | — | Read-only drift report: what would push (create/update), and whether Linear's workflow-state drifted from the spec. Writes nothing. |
-| `/spec-push`   | repo → Linear | Computes a create/update plan vs the last-pushed snapshot and applies it (project description/status, milestones, issues), stamping new ids back into the spec. |
+| `/spec-push`   | repo → Linear | Computes a create/update plan vs the last-pushed snapshot and applies it (issue description/state, phase sub-issues), stamping new ids back into the spec. |
 
 Typical loop: edit the spec in-repo → `/spec-status` (what's pending) →
 `/spec-push` (send it up). There is no pull — Linear is a generated mirror.
@@ -120,20 +130,20 @@ Typical loop: edit the spec in-repo → `/spec-status` (what's pending) →
 
 | Field | What |
 |-------|------|
-| `description` | the spec body (problem, solution, acceptance criteria) as the project description |
-| `milestones` | one per phase (name + goal) |
-| `issues` | one per task — first-sentence **title**, full task text as the **description** |
-| `workflowState` → project status | the spec's lifecycle bucket, mapped via `states` |
+| `description` | the spec body (problem, solution) as the issue description |
+| `subIssues` | one per phase — phase name as **title**, `**Goal:**` as the **description**, phase emoji → **state** |
+| `workflowState` → issue state | the spec's lifecycle folder bucket, mapped via `states` |
 
-Priority, labels, cycles and comments are **Linear-native triage** — the PM's to
-set in Linear. One-way sync neither pushes nor reads them, so they're never
-clobbered. A workflow-state a teammate moves in Linear is surfaced by
-`/spec-status` as drift and overwritten on the next push.
+Tasks, priority, labels, cycles and comments are **Linear-native triage** (or
+repo-only) — never pushed, so they're never clobbered. A workflow-state a teammate
+moves in Linear is surfaced by `/spec-status` as drift and overwritten on the next
+push.
 
-Phases push as **Milestones** and tasks as **Issues** by default. The link ids
-live in the phase-file frontmatter (`linear_milestone_id`) and inline on task
-lines (`- [ ] do it (SKI-123)`); `/spec-push` stamps them the first time it
-creates each object, so later pushes update instead of recreate.
+The spec is one issue and each phase a **sub-issue** (`parentId` = the spec
+issue). The link ids live in frontmatter — `linear_identifier` on the overview,
+`linear_issue_id` on each phase file; `/spec-push` stamps them the first time it
+creates each object, so later pushes update instead of recreate. Set
+`linear.projectId` to add every spec issue to a grouping Linear Project.
 
 Sections listed in `sync.localOnlySections` (default: **State log**, **Changelog**,
 **Open questions**) are stripped from the pushed description — they never leave
@@ -150,22 +160,22 @@ the repo.
 With a linked spec, confirm push end-to-end:
 
 1. `/spec-status` → shows what would push (`pending — N to create, M to update`).
-2. `/spec-push` → creates the project's milestones/issues and sets the
-   description/status; ids are stamped back into the spec.
+2. `/spec-push` → creates the spec issue and its phase sub-issues and sets the
+   description/state; ids are stamped back into the spec.
 3. `/spec-status` again → **up to date** (nothing changed since the last push).
-4. Edit a task locally, `/spec-push` → the matching issue updates;
+4. Edit a phase goal locally, `/spec-push` → the matching sub-issue updates;
    `/spec-status` returns to **up to date**.
 
 ## Troubleshooting
 
 - **"connect the `linear` MCP server"** — the server isn't connected/authed for
   this session. Re-run step 2; remember a fresh add needs a Claude Code restart.
-- **"missing required tools: projectUpdate"** — you're on the read-only endpoint
+- **"missing required tools: issueCreate"** — you're on the read-only endpoint
   (or a restricted API key). Use `https://mcp.linear.app/mcp` for push.
-- **A configured status name silently does nothing** — Linear ignores an unknown
-  project status. Run `/spec-status` (it validates the `states` names against the
-  workspace) and fix `linear.config.json` to the real project-status names
-  (`Backlog / Planned / In Progress / Completed / Canceled`).
+- **A configured state name silently does nothing** — Linear ignores an unknown
+  issue state. Run `/spec-status` (it validates the `states` names against the
+  workspace) and fix `linear.config.json` to the real issue-state names
+  (`Backlog / Todo / In Progress / Done / Canceled`).
 - **Reconnecting doesn't switch workspace** — Linear ties the OAuth session to one
   workspace. Remove and re-add the server to authenticate against another.
 - **Bold around an inline code span renders oddly in Linear** — Linear moves the

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

@@ -2,17 +2,21 @@
   "linear": {
     "teamKey": "",
     "teamId": "",
-    "initiativeId": ""
+    "projectId": ""
+  },
+  "intake": {
+    "label": "",
+    "bugLabels": []
   },
   "mapping": {
-    "specFolder": "project",
-    "phases": "milestone",
-    "tasks": "issue"
+    "specFolder": "issue",
+    "phases": "subissue",
+    "tasks": "none"
   },
   "states": {
     "backlog": "Backlog",
     "in-progress": "In Progress",
-    "complete": "Completed",
+    "complete": "Done",
     "cancelled": "Canceled"
   },
   "snapshot": {
@@ -25,8 +29,7 @@
     "baseDir": "specs/.core/linear-base",
     "fieldOwnership": {
       "description": "push",
-      "milestones": "push",
-      "tasks": "push",
+      "subIssues": "push",
       "workflowState": "push"
     },
     "localOnlySections": ["State log", "Changelog", "Open questions"],

package/assets/core/linear.config.md

@@ -2,7 +2,8 @@
 
 Opt-in config for the Linear sync (`/spec-status`, `/spec-push`, and the
 Linear-aware paths of `/spec` and `/spec-go`). Sync is **one-way**: the repo is
-the source of truth and the Linear project is a **generated mirror**. Content is
+the source of truth and the Linear **issue** is a **generated mirror**. A spec is
+a Linear issue and each phase a sub-issue; tasks are not synced. Content is
 pushed up and never read back or merged — `/spec-push` diffs the spec against a
 committed **last-pushed snapshot** and applies only what changed; `/spec-status`
 is a read-only drift report. The `sync.fieldOwnership` map now just selects the
@@ -12,7 +13,7 @@ projection field set (every field is repo-owned and pushed).
 is absent the feature is simply unused — `/spec`, `/spec-go`, and the CLI's
 `spec-sync` subcommands behave exactly as they do today (local-only). Adopt it by
 copying `linear.config.json.example` → `linear.config.json` here and filling in
-your team / initiative IDs.
+your team ID (and an optional grouping project).
 
 The loader (`src/sync/config.js` → `loadLinearConfig`) merges your file over the
 frozen defaults below and returns `{ config, present }`; `present:false` means no
@@ -23,30 +24,38 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push` is a hard error
 
 ```jsonc
 {
-  // Which Linear team/initiative specs sync into. IDs are read by the Phase 2
-  // MCP adapter; leave blank until you connect the `linear` MCP server.
+  // Which Linear team specs sync into, and an optional Project to group them.
+  // IDs are read by the MCP adapter; leave blank until you connect the `linear`
+  // MCP server.
   "linear": {
     "teamKey": "",        // human-facing key, e.g. "ENG" (optional)
-    "teamId": "",         // Linear team UUID (create target)
-    "initiativeId": ""    // optional Initiative that groups these specs
+    "teamId": "",         // Linear team UUID (the issue's team)
+    "projectId": ""       // DEFAULT for the project picker (see below)
   },
 
-  // How a spec's parts map onto Linear objects. Defaults mirror Decision 7:
-  // spec folder → Project, phases → Milestones, tasks → Issues. `phases` may be
-  // switched to "issue" if your workspace doesn't expose project milestones.
+  // Issue intake: `/spec <ISSUE-REF>` adopts any issue; `/spec --from-issue`
+  // browses the inbox. Both optional.
+  "intake": {
+    "label": "",          // inbox filter — the label the web app files under
+    "bugLabels": []       // e.g. ["bug"] — these route to /spec-bug instead
+  },
+
+  // How a spec's parts map onto Linear objects: a spec is an Issue, each phase a
+  // sub-issue (a child issue), tasks are not synced. These are the defaults.
   "mapping": {
-    "specFolder": "project",
-    "phases": "milestone",   // "milestone" | "issue"
-    "tasks": "issue"
+    "specFolder": "issue",
+    "phases": "subissue",
+    "tasks": "none"
   },
 
-  // Map the spec's lifecycle bucket → the Linear workflow-state name. Used when
-  // translating workflowState across the boundary (Linear owns status → `pull`).
+  // Map the spec's lifecycle bucket → the Linear ISSUE workflow-state name. Used
+  // for the spec issue's state (from its folder) AND each sub-issue's state (from
+  // the phase emoji). Names must match the workspace's issue states exactly.
   "states": {
     "backlog": "Backlog",
     "in-progress": "In Progress",
     "complete": "Done",
-    "cancelled": "Cancelled"
+    "cancelled": "Canceled"
   },
 
   // The spec's entry-point file the local snapshot + frontmatter live in.
@@ -69,15 +78,14 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push` is a hard error
     "baseDir": "specs/.core/linear-base",
 
     // The pushed projection field set (repo → Linear, one-way). The `push` marker
-    // is retained for shape; there is no pull. The default set is the project
-    // `description`, `milestones` (one per phase), `tasks` (one issue each), and
-    // the lifecycle `workflowState`. Priority, labels, cycles and comments are
-    // Linear-native triage — deliberately NOT here, so a PM's triage is never
-    // touched. Any key you add joins the pushed projection.
+    // is retained for shape; there is no pull. The default set is the spec
+    // issue's `description`, its `subIssues` (one per phase — name + goal +
+    // state), and the lifecycle `workflowState`. Tasks, priority, labels, cycles
+    // and comments are NOT here, so a PM's triage is never touched. Any key you
+    // add joins the pushed projection.
     "fieldOwnership": {
       "description": "push",
-      "milestones": "push",
-      "tasks": "push",
+      "subIssues": "push",
       "workflowState": "push"
     },
 
@@ -85,31 +93,65 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push` is a hard error
     // are stripped from the pushed `description` (never sent to Linear).
     "localOnlySections": ["State log", "Changelog", "Open questions"],
 
-    // Reserved. Milestones and tasks are always projected per item (each phase →
-    // a Milestone, each task → an Issue), so this no longer needs setting; it is
-    // validated but unused. Leave it `{}`.
+    // Reserved. Sub-issues are always projected per phase, so this no longer
+    // needs setting; it is validated but unused. Leave it `{}`.
     "keyedFields": {}
   }
 }
 ```
 
-## Phases → Milestones, tasks → Issues
+## Spec → Issue, phases → sub-issues
 
 Push maps the spec's structure to Linear's, keyed by id so it updates rather than
 recreates:
 
-- **Phases → Milestones.** Each phase file maps to a Linear Milestone. The link id
-  lives in the phase file's frontmatter (`linear_milestone_id`); its name ← the
-  phase h1, its description ← the phase `**Goal:**` line. The `Phases` index is
-  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)`. The issue
-  **title** is the task's first sentence; the **description** is the full task
-  text; `[x]`/`[ ]` ↔ a completed / non-completed issue state.
-
-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.
+- **Spec → Issue.** The spec is one Linear issue. Its id lives in the overview
+  frontmatter (`linear_identifier`); its `description` ← the overview plan (with
+  the `Phases` index and local-only sections stripped); its workflow-state ← the
+  spec's lifecycle folder (`specs/<bucket>/`).
+- **Phases → sub-issues.** Each phase file maps to a child issue (`parentId` = the
+  spec issue). The link id lives in the phase file's frontmatter
+  (`linear_issue_id`); its title ← the phase h1, its description ← the phase
+  `**Goal:**` line, its state ← the phase heading emoji (⬜/🔄/✅).
+- **Tasks are not synced.** Task checkboxes stay in the repo phase files only.
+
+Unlinked local items (a spec with no `linear_identifier`, a phase with no
+`linear_issue_id`) are created in Linear on the next `/spec-push`, which stamps
+the new id back so they link from then on.
+
+## Which Project a spec issue belongs to
+
+`linear.projectId` is the **default**, not a mandate. When a spec issue is first
+created — by `/spec`, or by the first `/spec-push` if the spec was authored
+offline — you're offered the team's projects, filterable by name, with an explicit
+**None (team only)** option and this id pre-selected.
+
+The choice is passed on the **create call only**. It is never written into the
+spec, never recorded in the snapshot, and never sent on an update. So once the
+issue exists, where it lives is Linear's business: move it between projects and
+`/spec-status` will not call it drift and `/spec-push` will not move it back.
+
+A spec that **adopted** an existing issue (see below) skips the picker entirely —
+it was filed somewhere deliberately.
+
+## Starting a spec from an existing issue
+
+With `intake` configured, a spec can begin life as a Linear issue someone else
+filed:
+
+- `/spec SKI-123` — adopt that issue.
+- `/spec --from-issue [query]` — browse issues labelled `intake.label` (what your
+  web app or feedback form files under), optionally filtered by title.
+
+The issue **becomes** the spec's issue: its identifier is stamped as
+`linear_identifier`, phases become its sub-issues, and the first `/spec-push`
+replaces its description with the spec. The reporter's comments, links and
+subscribers stay on the one issue everyone is already watching; their original
+words are carried into the spec's **Problem** section.
+
+An issue already stamped on a spec can't be adopted twice — `skitterspec spec-sync
+linked` is the list that's checked. An issue labelled with one of
+`intake.bugLabels` routes to `/spec-bug` instead, which adopts it identically.
 
 ## One direction — nothing to reconcile
 

package/assets/rules/spec-planning.md

@@ -113,6 +113,9 @@ status.
 
 Every spec header carries:
 
+- `> **Name:**` — the spec's folder name (`feat-`/`bug-`/`hotfix-<kebab-name>`).
+  It's the handle you pass to `/spec-go` and the other lifecycle skills, surfaced
+  in the header so it's copy-pasteable without digging for the folder name.
 - `> **Author:**` — who created the spec (set at `/spec` / `/spec-bug`, defaults
   to `git config user.name`).
 - `> **Developer:**` — who implements it (`—` until `/spec-go` starts work, then

package/assets/skills/spec/SKILL.md

@@ -14,6 +14,66 @@ Lifecycle (the governing skills) — status in parentheses:
 `/spec-cancel` (Cancelled). See `.claude/rules/spec-planning.md`. (There is no
 separate grooming command — `/spec` grills to a Ready spec directly.)
 
+## Phase 0 — start from a Linear issue (only when asked)
+
+**Only when `specs/.core/linear.config.json` exists** *and* the invocation names an
+issue. Otherwise skip this phase entirely and grill from the user's own words.
+
+Two ways in:
+
+- **`<ISSUE-REF>`** (`SKI-123`, an issue URL, or a bare id anywhere in the
+  arguments) — adopt that issue.
+- **`--from-issue [query]`** — browse the intake inbox: issues carrying
+  `intake.label` (what the web app files under). With a `query`, filter that list
+  case-insensitively by title. Show the shortlist and let the user pick one.
+
+Then:
+
+1. **Exclude what's already adopted.** Run `skitterspec spec-sync linked --json`
+   and drop any issue whose identifier is already stamped on a spec. If the user
+   named such an issue directly, **stop** and point them at that spec — one issue
+   never becomes two specs.
+2. **Read the issue** with the discovered issue-read tool: title, description,
+   labels, reporter, URL. If Linear isn't connected, say so and offer to carry on
+   without it — a spec written from the user's own description is still a spec.
+3. **Route bugs away — in `/spec` only.** If any of the issue's labels matches
+   `intake.bugLabels` (case-insensitive), this is a bug report, not a feature
+   request. Say so, name the matching label, and tell the user to run
+   **`/spec-bug <ISSUE-REF>`** — then stop, without authoring a Feature spec.
+   With `intake.bugLabels` unset nothing is routed and every issue is treated as a
+   feature request.
+
+   **In `/spec-bug` this step is skipped** — you are already in the bug path.
+   Adopt the issue, then reproduce it as usual: the issue body is your repro
+   material, and the failing test comes before the spec exactly as normal.
+4. **Seed, don't skip, the grill.** The issue's title becomes the working spec
+   title and its description the starting material for **Problem** — quote the
+   reporter's words rather than paraphrasing them away. Note the reporter and the
+   issue URL for context. Everything after this runs exactly as normal: an issue
+   is a *request*, not a groomed spec, so grill it as hard as anything else.
+
+### Adopting the issue
+
+The issue **becomes** the spec's issue — it is not copied and no second issue is
+minted. This is identical in `/spec` and `/spec-bug`; only *when* it happens
+differs (`/spec` writes the spec in Phase B, `/spec-bug` in its step 4). Once the
+spec file exists:
+
+- **Stamp `linear_identifier` and `linear_url`** in `00-overview.md` frontmatter
+  from the adopted issue. That is the whole link: every later skill
+  (`/spec-push`, `/spec-status`, `/spec-go`) keys off it being present.
+- **Do not run the project picker** and never send `project`. The issue was filed
+  somewhere deliberately — where it lives is Linear's business, and adoption is
+  not a mint.
+- **Do not write a base sidecar.** Leaving `sync.baseDir` empty for this spec is
+  what makes the first `/spec-push` push the spec over the reporter's original
+  description (an **update** to the existing issue, plus a sub-issue per phase).
+  Recording a snapshot here would declare the mirror already in sync and strand
+  the issue showing the raw report forever.
+- **Say what will happen** in the finish-up message: the first `/spec-push` will
+  overwrite the issue's description with the spec, and the original report is
+  preserved in the spec's **Problem** section.
+
 ## Phase A — reach a clear shared understanding (grill first)
 
 Interview the user until requirement AND proposed solution are unambiguous. Do
@@ -73,6 +133,7 @@ the codebase, link rather than duplicate):
 # <Feature title>
 
 > **Type:** Feature
+> **Name:** feat-<kebab-name> (the spec folder name — the handle you paste into `/spec-go`)
 > **Status:** Ready — not started
 > **Author:** <git user.name — `git config user.name`>
 > **Developer:** —
@@ -227,36 +288,71 @@ below (nothing to do here without one).
 **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:
+so status and discussion live there while the repo stays the co-authoring surface.
+A spec is a Linear **issue**; each phase is a **sub-issue**; tasks are not synced:
 
 - **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.
+- **Pick the Project** — run the picker in **Picking the Linear Project** below,
+  then **create the Issue** from the spec: `title` from the spec title,
+  `description` from the `00-overview.md` plan, `team` = `linear.teamId`, and
+  `project` = the picked id (omitted when the user chose None).
+- **Create a sub-issue per phase** (the `mapping.phases` target — `subissue` by
+  default): a child issue with `parentId` = the spec issue, 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>"
   ---
   ```
 
+  Stamp each phase file's `linear_issue_id` with its sub-issue id. (Status is not
+  stored in frontmatter — it comes from the spec's lifecycle folder.)
 - **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
+  run `skitterspec spec-sync record <spec>` to capture the local snapshot as the
   committed base (`sync.baseDir`). `/spec-status` should report in-sync right after.
+  (`record` is the writer; `normalize` only *prints* the projection.) Skip this
+  when the spec **adopted** an existing issue — see Phase 0 — because the issue's
+  description is still the reporter's, not the spec.
 - **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
+events later. Report the Linear issue URL and the base as part of Phase C's
 finish-up message.
+
+### Picking the Linear Project
+
+Run this **only when minting a spec issue** — creating it for the first time. On
+an update the issue already has a project (or deliberately has none), and that
+placement is **Linear's to own**: never send `project` on an update, and never
+record the choice in the spec file or the snapshot. A PM re-homing a spec issue
+must not show up as drift or be overwritten on the next push.
+
+1. **List the candidates.** Call the discovered project-list tool for
+   `linear.teamId`. Drop archived / completed projects — they can't take new work.
+2. **Offer them.** Show the names (most recently updated first is fine), plus an
+   explicit **None (team only)** option. Pre-select `linear.projectId` from
+   `linear.config.json` when it's set and still in the list; otherwise pre-select
+   **None**.
+3. **Narrow on request.** If the user types a fragment rather than choosing, filter
+   the list case-insensitively by name and re-offer. Don't re-fetch.
+4. **Never offer to create a project.** Projects are the PM's surface — if none
+   fits, that's **None (team only)**, and someone makes the project in Linear.
+5. **Pass it once.** Include `project: <chosen id>` on the issue-create call.
+   Chose None → omit the key entirely (do not send an empty string).
+
+**Degrade, never block.** If Linear isn't connected, or the server exposes no
+project-list tool, say so in one line — *"project picker unavailable; creating the
+issue without a project"* — and carry on with `linear.projectId` if it's set, else
+no project at all. A missing picker must never fail `/spec` or `/spec-push`.
+
+If `linear.projectId` is set but that Project is archived or missing, relay
+Linear's error and stop rather than silently minting an unparented issue.