@eskoubar95/spec 0.1.4 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/dist/lib/copy-template.js +6 -6
  2. package/dist/lib/copy-template.js.map +1 -1
  3. package/package.json +2 -2
  4. package/template/.cursor/MCP-SETUP.md +16 -0
  5. package/template/.cursor/agents/batch-runner.md +52 -0
  6. package/template/.cursor/agents/verifier.md +40 -0
  7. package/template/.cursor/commands/_shared/branch-detection.md +78 -0
  8. package/template/.cursor/commands/_shared/git-workflow.md +3 -1
  9. package/template/.cursor/commands/_shared/github-workflows.md +7 -5
  10. package/template/.cursor/commands/_shared/helper-metadata.md +20 -0
  11. package/template/.cursor/commands/_shared/linear-automation.md +14 -6
  12. package/template/.cursor/commands/_shared/linear-helpers.md +26 -14
  13. package/template/.cursor/commands/_shared/pr-description.md +11 -2
  14. package/template/.cursor/commands/spec/init.md +33 -0
  15. package/template/.cursor/commands/spec/plan.md +43 -9
  16. package/template/.cursor/commands/spec/refine.md +7 -0
  17. package/template/.cursor/commands/task/batch.md +112 -0
  18. package/template/.cursor/commands/task/start.md +28 -6
  19. package/template/.cursor/commands/task/validate.md +19 -15
  20. package/template/.cursor/scripts/{validate-helpers.js → validate-helpers.cjs} +30 -32
  21. package/template/.cursor/skills/sdd-commit-unit/SKILL.md +42 -0
  22. package/template/.cursor/skills/sdd-design-system-bootstrap/SKILL.md +35 -0
  23. package/template/.cursor/skills/sdd-git-default-branch/SKILL.md +49 -0
  24. package/template/.cursor/skills/sdd-pr-create-or-update/SKILL.md +41 -0
  25. package/template/.cursor/skills/sdd-task-preflight/SKILL.md +47 -0
  26. package/template/.cursor/skills/sdd-validation-suite/SKILL.md +47 -0
  27. package/template/spec/00-root-spec.md +9 -0
  28. package/template/spec/templates/02-architecture.md +64 -0
  29. package/template/spec/templates/06-acceptance.md +59 -0
  30. package/template/spec/templates/07-design-system.md +145 -0
  31. package/template/spec/templates/08-infrastructure.md +76 -0
  32. package/template/spec/templates/09-sitemap.md +50 -0
  33. package/template/work/backlog/tasks.local.md +6 -0
  34. package/template/work/linear/FALLBACK-STRATEGY.md +84 -0
  35. package/template/work/linear/LABEL-MAPPING-GUIDE.md +72 -0
  36. package/template/work/linear/SETUP.md +75 -0
  37. package/template/work/linear/sync-config.md +86 -0
@@ -9,19 +9,19 @@ const __dirname = path.dirname(__filename);
9
9
  * Works in both development (template at repo root) and published (template at package root)
10
10
  */
11
11
  async function getTemplateDir() {
12
- // Try package root first (for published package)
13
- const packageRoot = path.resolve(__dirname, '../..');
14
- const templateInPackage = path.join(packageRoot, 'template');
15
12
  // Try repo root (for development)
16
13
  const repoRoot = path.resolve(__dirname, '../../../..');
17
14
  const templateInRepo = path.join(repoRoot, 'template');
15
+ // Try package root (for published package)
16
+ const packageRoot = path.resolve(__dirname, '../..');
17
+ const templateInPackage = path.join(packageRoot, 'template');
18
18
  // Return the first path that exists
19
- if (await fs.pathExists(templateInPackage)) {
20
- return templateInPackage;
21
- }
22
19
  if (await fs.pathExists(templateInRepo)) {
23
20
  return templateInRepo;
24
21
  }
22
+ if (await fs.pathExists(templateInPackage)) {
23
+ return templateInPackage;
24
+ }
25
25
  // Fallback to package root (will fail with clear error in copyTemplate)
26
26
  return templateInPackage;
27
27
  }
@@ -1 +1 @@
1
- {"version":3,"file":"copy-template.js","sourceRoot":"","sources":["../../src/lib/copy-template.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"copy-template.js","sourceRoot":"","sources":["../../src/lib/copy-template.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@eskoubar95/spec",
3
- "version": "0.1.4",
3
+ "version": "0.1.5",
4
4
  "private": false,
5
5
  "bin": {
6
6
  "spec": "dist/index.js"
@@ -15,7 +15,7 @@
15
15
  "build": "tsc",
16
16
  "dev": "tsc --watch",
17
17
  "start": "node dist/index.js",
18
- "prepublishOnly": "cp -r ../template . || true"
18
+ "prepack": "node scripts/sync-template.mjs"
19
19
  },
20
20
  "dependencies": {
21
21
  "inquirer": "^9.2.0",
@@ -31,4 +31,20 @@ If you're using Linear task mode, you may want to configure the Linear MCP serve
31
31
  }
32
32
  ```
33
33
 
34
+ ## Known Issue: MCP Routing Conflicts
35
+
36
+ ⚠️ **If you have both GitHub-MCP and Linear-MCP enabled:**
37
+
38
+ There is a known bug in Cursor where tools with the same name (e.g., `update_issue`, `list_issues`) from different MCP servers can cause routing conflicts. Cursor may route calls to the wrong server, resulting in errors like:
39
+
40
+ ```
41
+ missing required parameter 'owner'
42
+ ```
43
+
44
+ This happens because GitHub-MCP tools require an `owner` parameter, while Linear-MCP tools don't. When Cursor routes a Linear operation to GitHub-MCP by mistake, you'll see this error.
45
+
46
+ **Workaround:** If you encounter this issue when working with Linear tasks, temporarily disable GitHub-MCP in your MCP settings while using Linear operations. You can re-enable it when needed.
47
+
48
+ This is a known issue in the Cursor forum related to tool name collisions between MCP servers.
49
+
34
50
  For more details, see [MCP Documentation](https://modelcontextprotocol.io).
@@ -0,0 +1,52 @@
1
+ ---
2
+ name: batch-runner
3
+ description: Runs long multi-task batches with minimal main-context noise. Use for /task/batch style orchestration: execute tasks sequentially, run validation, and report concise per-task summaries.
4
+ ---
5
+
6
+ # Batch Runner Subagent
7
+
8
+ You are a specialized subagent that executes **long-running batch workflows** without bloating the parent conversation.
9
+
10
+ ## Input contract (the parent must include)
11
+
12
+ - Batch scope:
13
+ - milestone ID (e.g., `M4`) OR a list of task IDs
14
+ - Source-of-truth paths:
15
+ - `work/backlog/milestones.md`
16
+ - `work/backlog/tasks.local.md`
17
+ - optionally `spec/tasks/**`
18
+ - Git rules:
19
+ - base branch must be resolved (do not assume `main`)
20
+ - branch naming convention
21
+ - commit granularity rules
22
+ - Validation rules:
23
+ - what to run (or the “validation suite” skill to use)
24
+ - PR rules (optional):
25
+ - when to create/update PRs and what base branch to use
26
+
27
+ ## Behavior
28
+
29
+ - Execute tasks sequentially, keeping scope tight.
30
+ - For each task:
31
+ - confirm task context from backlog/spec
32
+ - run preflight (clean tree + base branch + task branch)
33
+ - implement the minimum needed
34
+ - commit in small logical units (when requested)
35
+ - run validation
36
+ - report a concise summary (what changed, evidence, next risk)
37
+
38
+ ## Output contract (what you must return)
39
+
40
+ Return a compact report:
41
+
42
+ - `completed`: [task IDs]
43
+ - `blocked`: [task IDs + reason]
44
+ - `notes`: important cross-task discoveries (risks/questions)
45
+ - `evidence`: what validation ran + results
46
+
47
+ ## Boundaries
48
+
49
+ - Respect POS/SDD modes: do not do planning inside task execution.
50
+ - Do not expand scope beyond the specified milestone/tasks.
51
+ - Never assume the base branch is `main` (resolve it via config/remote HEAD/fallbacks).
52
+
@@ -0,0 +1,40 @@
1
+ ---
2
+ name: verifier
3
+ description: Independent quality gate: verify acceptance, scope boundaries, branch/base correctness, and evidence (lint/tests/build). Use before PR creation or merging.
4
+ ---
5
+
6
+ # Verifier Subagent
7
+
8
+ You are an independent verifier. Your job is to **validate completed work** and report what passed vs what is incomplete.
9
+
10
+ ## Input contract (the parent must include)
11
+
12
+ - Task context:
13
+ - task ID(s)
14
+ - acceptance criteria (from `work/backlog/tasks.local.md` and/or `spec/06-acceptance.md`)
15
+ - Git context:
16
+ - base branch (resolved; do not assume `main`)
17
+ - current branch name
18
+ - Evidence:
19
+ - validation outputs (lint/tests/build), or instructions on what to run
20
+
21
+ ## Verification checklist
22
+
23
+ - **Scope**: changes map to the task acceptance criteria; no unrelated refactors
24
+ - **Git hygiene**:
25
+ - correct base branch used
26
+ - sensible branch name
27
+ - commits are small/reviewable and task-linked
28
+ - **Evidence**:
29
+ - validation suite ran (or clear explanation why not)
30
+ - **Docs/spec alignment**:
31
+ - if new risk/question emerged, it is captured in `spec/03-risks.md` or `spec/04-open-questions.md`
32
+
33
+ ## Output contract
34
+
35
+ Return:
36
+ - `pass`: yes/no
37
+ - `gaps`: bullets of what is missing
38
+ - `evidence`: bullets of what was checked
39
+ - `recommendation`: next step (PR creation, more fixes, spec update, etc.)
40
+
@@ -0,0 +1,78 @@
1
+ ---
2
+ helper_id: branch-detection
3
+ load_when:
4
+ - task_start
5
+ - task_validate
6
+ - pr_creation_needed
7
+ - git_operation_needed
8
+ sections:
9
+ detection:
10
+ title: "Default Branch Detection"
11
+ lines: [1, 140]
12
+ usage:
13
+ title: "Usage in Commands"
14
+ lines: [141, 220]
15
+ always_load: false
16
+ ---
17
+
18
+ # Default Branch Detection
19
+
20
+ This helper defines a **project-agnostic** way to detect the base branch to use for:
21
+ - creating task branches
22
+ - generating diffs and commit counts
23
+ - creating PRs
24
+ - merging (when applicable)
25
+
26
+ ## Detection logic (priority order)
27
+
28
+ **Priority 0 — Project config (preferred):**
29
+ - If `.sdd/git-config.json` exists, read:
30
+ - `default_branch` OR `development_branch` → base branch
31
+ - optional: `production_branch`
32
+
33
+ Example config:
34
+
35
+ ```json
36
+ {
37
+ "default_branch": "main",
38
+ "development_branch": "main",
39
+ "production_branch": "main"
40
+ }
41
+ ```
42
+
43
+ **Priority 1 — Remote HEAD:**
44
+ - If `origin` exists, resolve remote default branch (HEAD branch).
45
+
46
+ **Priority 2 — Conventional fallbacks (local or remote):**
47
+ - `main`
48
+ - `master`
49
+ - `develop`
50
+
51
+ **Priority 3 — Last resort:**
52
+ - Use `main` and log a warning that branch detection failed.
53
+
54
+ ## Notes
55
+
56
+ - Do **not** assume `staging` exists. If a project uses `staging` (or any non-standard branch), it must be configured in `.sdd/git-config.json`.
57
+ - Never hardcode `main` in commands or helpers. Always use `<default-branch>` resolved by this helper (or the Cursor 2.4+ skill `/sdd-git-default-branch`).
58
+
59
+ ## Usage in Commands
60
+
61
+ ### In `/task/start`
62
+
63
+ 1. Resolve `<default-branch>` using the detection logic above.
64
+ 2. Checkout and update base branch:
65
+ - `git checkout <default-branch>`
66
+ - `git pull origin <default-branch>` (if remote exists)
67
+ 3. Create task branch from base:
68
+ - `git checkout -b task/<task-id>-<kebab-description>`
69
+
70
+ ### In PR creation
71
+
72
+ - Always set PR base to `<default-branch>`.
73
+
74
+ ### For diff and commit counts
75
+
76
+ - Diff: `git diff <default-branch>...HEAD`
77
+ - Commit list: `git log <default-branch>..HEAD`
78
+ - Commit count: `git rev-list --count <default-branch>..HEAD`
@@ -153,7 +153,9 @@ Automate Git workflow operations:
153
153
  1. Get current branch: `git branch --show-current`
154
154
  2. Check if branch exists: `git rev-parse --verify <branch-name>`
155
155
  3. Check if pushed: `git ls-remote --heads origin <branch-name>`
156
- 4. Count commits: `git rev-list --count main..<branch-name>`
156
+ 4. Count commits:
157
+ - Resolve `defaultBranch` (do not assume `main`) using `/sdd-git-default-branch` or `branch-detection.md`
158
+ - Count: `git rev-list --count <default-branch>..<branch-name>`
157
159
  5. Get last commit: `git rev-parse HEAD`
158
160
 
159
161
  ### PR State Detection
@@ -145,9 +145,11 @@ name: CI
145
145
 
146
146
  on:
147
147
  push:
148
- branches: [main, develop]
148
+ # Replace with your repository's base branches (do not assume `main`).
149
+ # Prefer the resolved default branch (see: /sdd-git-default-branch or branch-detection.md).
150
+ branches: [<default-branch>]
149
151
  pull_request:
150
- branches: [main, develop]
152
+ branches: [<default-branch>]
151
153
 
152
154
  jobs:
153
155
  test:
@@ -184,9 +186,9 @@ name: CI
184
186
 
185
187
  on:
186
188
  push:
187
- branches: [main, develop]
189
+ branches: [<default-branch>]
188
190
  pull_request:
189
- branches: [main, develop]
191
+ branches: [<default-branch>]
190
192
 
191
193
  jobs:
192
194
  test:
@@ -248,7 +250,7 @@ name: Deploy
248
250
 
249
251
  on:
250
252
  push:
251
- branches: [main]
253
+ branches: [<default-branch>]
252
254
 
253
255
  jobs:
254
256
  deploy:
@@ -154,6 +154,26 @@ sections:
154
154
  always_load: false
155
155
  ```
156
156
 
157
+ ### branch-detection.md
158
+
159
+ ```yaml
160
+ helper_id: branch-detection
161
+ file: branch-detection.md
162
+ load_when:
163
+ - task_start
164
+ - task_validate
165
+ - pr_creation_needed
166
+ - git_operation_needed
167
+ sections:
168
+ detection:
169
+ title: "Default Branch Detection"
170
+ lines: [1, 140]
171
+ usage:
172
+ title: "Usage in Commands"
173
+ lines: [141, 220]
174
+ always_load: false
175
+ ```
176
+
157
177
  ### git-workflow.md
158
178
 
159
179
  ```yaml
@@ -60,8 +60,14 @@ Automate Linear operations based on SDD workflow events, ensuring seamless integ
60
60
  - Report fallback to user but continue workflow normally
61
61
 
62
62
  4. **Check configuration completeness:**
63
- - If Linear mode is enabled but status mapping is missing → guide user to setup
64
- - Reference `work/linear/SETUP.md` for setup instructions
63
+ - Required keys (when `MODE=linear`):
64
+ - `STATUS_BACKLOG`, `STATUS_IN_PROGRESS`, `STATUS_DONE`, `STATUS_BLOCKED`
65
+ - **Hard stop policy (planning):** during `/spec/plan`, if any required key is missing → **BLOCK Linear sync** until the user fixes `work/linear/sync-config.md`.
66
+ - **Execution policy (tasks):** during `/task/*`, if config is incomplete → **skip Linear operations** for this run and continue in local mode (do not block code execution).
67
+ - Reference:
68
+ - `work/linear/SETUP.md` (setup)
69
+ - `work/linear/LABEL-MAPPING-GUIDE.md` (tags → labels + comment templates)
70
+ - `work/linear/FALLBACK-STRATEGY.md` (availability/operation failure fallback)
65
71
 
66
72
  ## Linear MCP Functions and Automation Rules
67
73
 
@@ -112,11 +118,11 @@ IF Linear mode enabled AND AUTO_CREATE_DOCUMENTS=true AND spec file created/upda
112
118
 
113
119
  **A) During `/spec/plan`:**
114
120
  - **Create issues:** For each task in `work/backlog/tasks.local.md` → create Linear issue
115
- - **Issue title:** Task description (first line)
121
+ - **Issue title:** `[task-id] – [task description]` (include the task ID for stable idempotency)
116
122
  - **Issue description:** Full task details (description, acceptance, dependencies, estimate)
117
123
  - **Issue status:** Map to "Backlog" (or custom status from config)
118
124
  - **Issue priority:** Map from task estimate (S=Low, M=Medium, L=High)
119
- - **Issue labels:** Auto-assign labels based on task type (see Labels section)
125
+ - **Issue labels:** Prefer task tags labels (see `work/linear/LABEL-MAPPING-GUIDE.md`)
120
126
  - **Issue project:** Link to Linear project (if milestone project exists)
121
127
  - **Issue team:** Assign to default team (if configured)
122
128
  - **Ask before creating:** Always ask user: "Skal jeg oprette Linear issues for tasks?"
@@ -124,7 +130,8 @@ IF Linear mode enabled AND AUTO_CREATE_DOCUMENTS=true AND spec file created/upda
124
130
  **B) During `/task/start`:**
125
131
  - **Get issue:** Fetch Linear issue details (if Linear task ID provided)
126
132
  - **Update issue:** Set status to "In Progress" (or custom status from config)
127
- - **Update issue:** Add comment: "Task started via SDD workflow at [timestamp]"
133
+ - **Update issue:** Add comment (recommended format):
134
+ - “Started `<task-id>` via SDD. Branch: `<branch>`. Plan: `<1–3 bullets>`.”
128
135
  - **If issue not found:** Error: "Linear issue [ID] ikke fundet"
129
136
 
130
137
  **C) During `/task/validate`:**
@@ -132,7 +139,8 @@ IF Linear mode enabled AND AUTO_CREATE_DOCUMENTS=true AND spec file created/upda
132
139
  - **Approved:** "Done" (or custom status from config)
133
140
  - **Requires fixes:** "In Progress" (or custom status from config)
134
141
  - **Requires spec refinement:** "Blocked" (or custom status from config)
135
- - **Update issue:** Add comment with validation summary
142
+ - **Update issue:** Add comment with validation summary (recommended format):
143
+ - “Validated `<task-id>` via SDD: `<pass/fail>`. Evidence: `<lint/tests/build>`. PR: `<url>` (if any).”
136
144
 
137
145
  **D) During `/spec/refine` or `/spec/evolve`:**
138
146
  - **Update issues:** If spec changes affect tasks → update related Linear issues
@@ -60,13 +60,13 @@ This document contains helper logic for Linear operations, including status mapp
60
60
 
61
61
  ## Label Detection
62
62
 
63
- **Purpose:** Auto-detect task type and map to Linear labels.
63
+ **Purpose:** Determine Linear labels for a task (prefer task tags; fallback to heuristics).
64
64
 
65
65
  **Logic:**
66
- 1. Analyze task description and title
67
- 2. Detect task type based on keywords
68
- 3. Map task type to label names
69
- 4. Check if labels exist, create if missing
66
+ 1. If the task exists in `work/backlog/tasks.local.md`, prefer `**Tags:**` as label names.
67
+ 2. If no tags found (or task not found), fallback to keyword-based task type detection.
68
+ 3. Check if labels exist; create if missing (when permitted).
69
+ 4. Assign labels to issue.
70
70
 
71
71
  **Task Type Detection:**
72
72
  ```markdown
@@ -91,14 +91,24 @@ Task type priority (if multiple matches):
91
91
 
92
92
  **Label Mapping:**
93
93
  ```markdown
94
- **Map Task Type to Labels:**
95
-
96
- - Design tasks → ["design", "ui", "frontend"]
97
- - Engineering tasks → ["engineering", "backend" or "frontend", "infrastructure" (if applicable)]
98
- - Business tasks → ["business", "requirements"]
99
- - Infrastructure tasks ["infrastructure", "devops", "deployment"]
100
- - External service tasks → ["external-service", "integration"]
101
- - Risk mitigation tasks ["risk", "mitigation"]
94
+ **Map Task Tags / Type to Labels:**
95
+
96
+ Priority order:
97
+
98
+ 1) **Task tags (preferred):**
99
+ - Read task block in `work/backlog/tasks.local.md` (by task ID).
100
+ - Parse `**Tags:**` (comma-separated).
101
+ - Use each tag as a label name (optionally prefix with `LABEL_PREFIX` from `work/linear/sync-config.md`).
102
+ - Do not invent type labels; only add `feature`, `bug`, `improvement` if explicitly present in tags.
103
+
104
+ 2) **Fallback (heuristics):**
105
+ - If tags are unavailable, use task type detection and map:
106
+ - Design → ["design", "ui", "frontend"]
107
+ - Engineering → ["engineering", "backend" or "frontend"]
108
+ - Business → ["business", "requirements"]
109
+ - Infrastructure → ["infrastructure", "devops", "deployment"]
110
+ - External service → ["external-service", "integration"]
111
+ - Risk mitigation → ["risk", "mitigation"]
102
112
  ```
103
113
 
104
114
  **Function:**
@@ -206,7 +216,9 @@ Task type priority (if multiple matches):
206
216
  **Handle Configuration Error:**
207
217
 
208
218
  1. IF sync-config.md missing → guide user to create it
209
- 2. IF MODE=linear but status mapping missing guide user to setup
219
+ 2. IF MODE=linear but required status mapping keys are missing:
220
+ - During `/spec/plan`: **HARD STOP** Linear sync until `work/linear/sync-config.md` is completed
221
+ - During `/task/*`: skip Linear operations for this run and continue in local mode (do not block code execution)
210
222
  3. IF team ID invalid → guide user to update sync-config.md
211
223
  ```
212
224
 
@@ -78,6 +78,15 @@ Generate comprehensive PR descriptions that include:
78
78
 
79
79
  ## Auto-Generation Process
80
80
 
81
+ ### Step 0: Resolve the base branch
82
+
83
+ Do NOT assume the base branch is `main`.
84
+
85
+ 1. Resolve `defaultBranch` using one of:
86
+ - Skill (Cursor 2.4+): `/sdd-git-default-branch`
87
+ - Helper: `.cursor/commands/_shared/branch-detection.md` (if present in the project)
88
+ 2. Use `defaultBranch` consistently for diff, commit history, and PR base.
89
+
81
90
  ### Step 1: Read Task Information
82
91
 
83
92
  **From task spec:**
@@ -93,8 +102,8 @@ Generate comprehensive PR descriptions that include:
93
102
  ### Step 2: Generate Changes Summary
94
103
 
95
104
  **From git diff:**
96
- 1. Get diff summary: `git diff main...HEAD --stat`
97
- 2. Get commit history: `git log main..HEAD --oneline`
105
+ 1. Get diff summary: `git diff <default-branch>...HEAD --stat`
106
+ 2. Get commit history: `git log <default-branch>..HEAD --oneline`
98
107
  3. Analyze changed files:
99
108
  - Count files changed
100
109
  - Identify file types (components, services, tests, etc.)
@@ -132,6 +132,10 @@ After the pitch, ask these 5 strategic questions in sequence. After each answer,
132
132
  - What can users not do without?
133
133
  - **Follow-up (if needed):** Ask 1-2 clarifying questions about features, then proceed to Question 3
134
134
 
135
+ **Scope locking (important if the initial pitch includes “future vision”):**
136
+ - What is the smallest **MVP scope** we can ship first?
137
+ - Which items mentioned are explicitly **future ideas** (out of MVP scope) and should be parked for later?
138
+
135
139
  **Question 3: Technical Requirements**
136
140
  - Are there any technical requirements or constraints?
137
141
  - Any specific technologies, frameworks, or platforms required?
@@ -165,11 +169,24 @@ After the pitch, ask these 5 strategic questions in sequence. After each answer,
165
169
  - External services: Newsletter platform, payment processing, analytics, etc.?
166
170
  - CI/CD requirements: Automatic deployments, manual approval?
167
171
 
172
+ **Task management / Linear (if the team wants Linear sync):**
173
+ - Will this project use **Linear** for task tracking, or **local mode** only?
174
+ - If Linear:
175
+ - Can you provide (or will you set up) the Linear MCP connection in Cursor?
176
+ - Do you want SDD to auto-create: **milestone projects**, **task issues**, and **spec documents** in Linear?
177
+ - Do you use any non-standard statuses or labels in Linear (or should we use defaults)?
178
+ - If you have multiple Linear connections in Cursor: what is the `MCP_CONNECTION_NAME`?
179
+
168
180
  **Design questions (if applicable and not already covered):**
169
181
  - Design direction: Do you have existing brand guidelines, design system, or should it be defined?
170
182
  - Visual style: Modern/minimalist/professional? Examples or references?
171
183
  - Design constraints: Colors, typography preferences, accessibility requirements?
172
184
 
185
+ **Design system bootstrap (if design is critical):**
186
+ - If the project will ship UI and design choices will affect implementation quality, create `spec/07-design-system.md`.
187
+ - Use template: `spec/templates/07-design-system.md`
188
+ - Optional (Cursor 2.4+): use the skill `/sdd-design-system-bootstrap` to produce a concrete, non-placeholder design system early.
189
+
173
190
  **Principles:**
174
191
  - Ask the 5 structured questions first
175
192
  - Allow 1-2 follow-up questions per structured question if clarification needed
@@ -206,6 +223,22 @@ Create or update the following files:
206
223
  - `spec/04-open-questions.md` - Open questions (always create)
207
224
  - `spec/01-prd.md` - Product Requirements Document (optional, create if detailed PRD is needed)
208
225
 
226
+ Create or update the following files ONLY IF relevant and confirmed:
227
+ - `spec/08-infrastructure.md` - Technology stack and infrastructure (use template: `spec/templates/08-infrastructure.md`)
228
+ - **Note:** This file is the source of truth for framework/tool detection and rule activation.
229
+ - `spec/07-design-system.md` - Design system (use template: `spec/templates/07-design-system.md`)
230
+
231
+ **If Linear is desired (recommendation before `/spec/plan`):**
232
+ - Create `work/linear/sync-config.md` and set `MODE=linear` (see `work/linear/SETUP.md`)
233
+ - **Required (hard requirement for Linear sync in `/spec/plan`)**: provide status mapping keys:
234
+ - `STATUS_BACKLOG`, `STATUS_IN_PROGRESS`, `STATUS_DONE`, `STATUS_BLOCKED`
235
+ - Optional:
236
+ - `MCP_CONNECTION_NAME` (if multiple Linear MCP connections)
237
+ - `DEFAULT_TEAM_ID`
238
+ - `AUTO_ASSIGN_LABELS=true` (recommended; uses task tags → labels)
239
+ - `AUTO_CREATE_PROJECTS=true` (milestones → projects)
240
+ - `AUTO_CREATE_DOCUMENTS=true` (specs → documents)
241
+
209
242
  **Populate files as follows:**
210
243
 
211
244
  **spec/00-root-spec.md:**
@@ -67,7 +67,21 @@ Planning outputs
67
67
  A) Spec artifacts (create only if needed by planning)
68
68
  - Create or update `spec/01-prd.md` if the feature set needs to be made explicit.
69
69
  - Create or update `spec/06-acceptance.md` with high-level acceptance criteria / definition of done.
70
+ - Use template: `spec/templates/06-acceptance.md` (MVP ship checklist + quality gates)
70
71
  - Create or update `spec/02-architecture.md` if architecture decisions are made or needed for planning.
72
+ - Use template: `spec/templates/02-architecture.md`
73
+
74
+ - Create or update `spec/08-infrastructure.md` if technology, environments, CI/CD, or hosting choices will affect the task breakdown.
75
+ - Use template: `spec/templates/08-infrastructure.md`
76
+ - **Note:** This file is the source of truth for framework/tool detection and rule activation.
77
+
78
+ - Create or update `spec/07-design-system.md` if UI/design decisions will materially affect planning or acceptance criteria.
79
+ - Use template: `spec/templates/07-design-system.md`
80
+ - Optional (Cursor 2.4+): use the skill `/sdd-design-system-bootstrap` before splitting design tasks
81
+
82
+ - Create or update `spec/09-sitemap.md` if the project ships UI (recommended for `projectType=web-app`).
83
+ - Use template: `spec/templates/09-sitemap.md`
84
+ - This is the source of truth for required pages, so tasks don’t “miss a screen” mid-implementation.
71
85
 
72
86
  **When to create architecture.md:**
73
87
  - Architecture decisions are made during planning
@@ -183,16 +197,36 @@ D) Optional: Linear integration (ONLY if configured)
183
197
  - Continue workflow with local mode only
184
198
 
185
199
  3. **Check configuration completeness (if Linear mode enabled):**
186
- - If status mapping is missing guide user:
200
+ - **HARD STOP (planning) if config is incomplete.** If `MODE=linear` is enabled but any of the required keys are missing, stop and require the user to fix `work/linear/sync-config.md` before continuing Linear sync:
201
+ - Required keys:
202
+ - `STATUS_BACKLOG`
203
+ - `STATUS_IN_PROGRESS`
204
+ - `STATUS_DONE`
205
+ - `STATUS_BLOCKED`
206
+ - Provide a recommended minimal snippet (names are fine; IDs optional):
187
207
  ```
188
- "Linear mode er aktiveret. Før vi kan synkronisere, skal du:
189
- 1. Gå ind i Linear og oprette custom statuser (hvis nødvendigt)
190
- 2. Gå ind i Linear og oprette custom labels (hvis nødvendigt)
191
- 3. Opdater sync-config.md med status IDs eller names
192
-
193
- Se work/linear/SETUP.md for detaljerede instruktioner."
208
+ MODE=linear
209
+ STATUS_BACKLOG=Backlog
210
+ STATUS_IN_PROGRESS=In Progress
211
+ STATUS_DONE=Done
212
+ STATUS_BLOCKED=Blocked
213
+ AUTO_ASSIGN_LABELS=true
214
+ AUTO_CREATE_PROJECTS=true
215
+ AUTO_CREATE_DOCUMENTS=true
194
216
  ```
195
- - Reference `work/linear/SETUP.md` for setup instructions
217
+ - Explain what the system can do automatically once config is complete:
218
+ - Create milestone projects (if `AUTO_CREATE_PROJECTS=true`)
219
+ - Create/update task issues (status + labels + project linkage)
220
+ - Create/update spec documents (if `AUTO_CREATE_DOCUMENTS=true`)
221
+ - Add structured comments on task start/validate
222
+ - Ask the user what they need to provide manually (if not known):
223
+ - `MCP_CONNECTION_NAME` (if multiple Linear MCP connections)
224
+ - `DEFAULT_TEAM_ID` (optional)
225
+ - Whether they use custom status names (otherwise defaults)
226
+ - Reference:
227
+ - `work/linear/SETUP.md` (setup)
228
+ - `work/linear/LABEL-MAPPING-GUIDE.md` (tags → labels; avoid “feature everywhere”)
229
+ - `work/linear/FALLBACK-STRATEGY.md` (failures fallback; do not block)
196
230
 
197
231
  **D.2) Linear Projects Creation (if Linear mode enabled and AUTO_CREATE_PROJECTS=true):**
198
232
 
@@ -214,7 +248,7 @@ D) Optional: Linear integration (ONLY if configured)
214
248
  - If exists → skip or update (ask user)
215
249
  - If not exists → ask user: "Skal jeg oprette Linear issues for tasks?"
216
250
  - If yes → create Linear issue:
217
- - Issue title: Task description (first line)
251
+ - Issue title: `[task-id] – [task description]` (include task ID for stable idempotency)
218
252
  - Issue description: Full task details (description, acceptance, dependencies, estimate)
219
253
  - Issue status: Map to "Backlog" (use status mapping from linear-helpers.md)
220
254
  - Issue priority: Map from estimate (S=Low, M=Medium, L=High)
@@ -102,6 +102,10 @@ D) Decisions (only if unavoidable)
102
102
  - UI patterns (card layouts, navigation patterns, form styles, etc.)
103
103
  - Accessibility requirements (WCAG level, color contrast)
104
104
 
105
+ **If design is critical:**
106
+ - Create or update `spec/07-design-system.md` using `spec/templates/07-design-system.md`
107
+ - Optional (Cursor 2.4+): use the skill `/sdd-design-system-bootstrap` to bootstrap a concrete design system before planning
108
+
105
109
  **F) Infrastructure decisions (if infrastructure is critical)**
106
110
  - Hosting provider preferences
107
111
  - Database provider preferences
@@ -112,6 +116,9 @@ D) Decisions (only if unavoidable)
112
116
  - This becomes the source of truth for framework/tool detection and rule activation
113
117
  - Format: "Frontend Framework: [name], CMS: [name], Database: [name], etc."
114
118
 
119
+ **If infrastructure is critical (recommended for most non-trivial projects):**
120
+ - Create or update `spec/08-infrastructure.md` using `spec/templates/08-infrastructure.md`
121
+
115
122
  **G) Architecture decisions (if architecture is critical)**
116
123
  - System architecture and component design
117
124
  - Data flow and component interactions