@eskoubar95/spec 0.1.4 → 0.1.5

package/template/work/linear/SETUP.md

@@ -0,0 +1,75 @@
+# Linear Setup Guide
+
+This guide walks you through setting up Linear integration with the SDD workflow.
+
+## Prerequisites
+
+- A Linear workspace + team
+- Linear MCP configured in Cursor
+- Access to Linear Settings
+
+## Hard stop (recommended)
+
+If you enable Linear mode (`MODE=linear`), `/spec/plan` treats missing required status mappings as a **hard stop** for Linear sync:
+
+- Required keys in `work/linear/sync-config.md`:
+  - `STATUS_BACKLOG`
+  - `STATUS_IN_PROGRESS`
+  - `STATUS_DONE`
+  - `STATUS_BLOCKED`
+
+## Step 1: Create/choose a Linear team
+
+1. Create a team (if needed)
+2. Note the team ID for `work/linear/sync-config.md` (optional)
+
+## Step 2: Ensure statuses exist
+
+1. Go to Linear Settings → Statuses
+2. Ensure you have statuses that match your desired mapping (defaults: Backlog, In Progress, Done, Blocked)
+3. Use status **names** in `sync-config.md` (recommended), or IDs if you need fixed UUIDs
+
+## Step 3: Ensure labels exist (optional)
+
+Labels can be created automatically when missing, but you can also create them manually in Linear Settings → Labels.
+
+## Step 4: Configure sync config
+
+1. Create/update `work/linear/sync-config.md`
+2. Set `MODE=linear`
+3. Optionally set:
+   - `MCP_CONNECTION_NAME` (if you have multiple Linear MCP connections)
+   - `DEFAULT_TEAM_ID`
+4. Set status mapping keys:
+   - `STATUS_BACKLOG`, `STATUS_IN_PROGRESS`, `STATUS_DONE`, `STATUS_BLOCKED`
+5. Enable optional automation:
+   - `AUTO_ASSIGN_LABELS=true`
+   - `AUTO_CREATE_PROJECTS=true`
+   - `AUTO_CREATE_DOCUMENTS=true`
+
+## Step 5: Tag-driven label mapping (recommended)
+
+Use `**Tags:**` in `work/backlog/tasks.local.md` to drive labels:
+- See `work/linear/LABEL-MAPPING-GUIDE.md`
+
+## Step 6: Test
+
+- Run `/spec/plan` (creates projects/issues/docs if enabled)
+- Run `/task/start` and `/task/validate` on a Linear issue ID to verify status + comments
+
+## Troubleshooting
+
+- Fallback behavior: `work/linear/FALLBACK-STRATEGY.md`
+
+## What SDD can do automatically (once configured)
+
+- **/spec/plan**: create milestone projects (optional), create/update task issues, create/update spec documents (optional)
+- **/task/start**: update status + add a structured “Started …” comment
+- **/task/validate**: update status + add a structured “Validated …” comment
+
+## What the user must do manually
+
+- Configure the Linear MCP connection in Cursor (and provide `MCP_CONNECTION_NAME` if multiple)
+- Ensure your desired statuses exist in Linear (or adjust mappings)
+- Decide label taxonomy (recommended: `**Tags:**` in `work/backlog/tasks.local.md` → labels; see `LABEL-MAPPING-GUIDE.md`)
+

package/template/work/linear/sync-config.md

@@ -0,0 +1,86 @@
+# Linear Sync Configuration
+
+This file configures Linear MCP integration with the SDD workflow.
+
+## Mode
+
+Create this file and set:
+
+```
+MODE=linear
+```
+
+If the file does not exist (or MODE is not `linear`), the system runs in local mode only.
+
+## MCP Connection Configuration (optional)
+
+If you have multiple Linear MCP connections in Cursor, specify which one to use:
+
+```
+MCP_CONNECTION_NAME=linear
+```
+
+## Team Configuration (optional)
+
+Assign projects/issues to a default team:
+
+```
+DEFAULT_TEAM_ID=[team-id]
+```
+
+## Status Mapping
+
+Map SDD statuses to Linear statuses (names recommended):
+
+**Required when `MODE=linear` (hard requirement for `/spec/plan` Linear sync):**
+- `STATUS_BACKLOG`
+- `STATUS_IN_PROGRESS`
+- `STATUS_DONE`
+- `STATUS_BLOCKED`
+
+```
+STATUS_BACKLOG=Backlog
+STATUS_IN_PROGRESS=In Progress
+STATUS_DONE=Done
+STATUS_BLOCKED=Blocked
+```
+
+## Labels
+
+Enable tag-driven label assignment:
+
+```
+AUTO_ASSIGN_LABELS=true
+LABEL_PREFIX=
+```
+
+See `work/linear/LABEL-MAPPING-GUIDE.md`.
+
+## Projects
+
+Enable milestone → Linear project automation:
+
+```
+AUTO_CREATE_PROJECTS=true
+```
+
+## Documents
+
+Enable spec → Linear document automation:
+
+```
+AUTO_CREATE_DOCUMENTS=true
+```
+
+## Cycles (optional)
+
+```
+USE_CYCLES=false
+ACTIVE_CYCLE_ID=[cycle-id]
+```
+
+## Fallbacks + troubleshooting
+
+- `work/linear/FALLBACK-STRATEGY.md`
+- `work/linear/SETUP.md`
+