@eskoubar95/spec 0.1.2 → 0.1.4

package/template/.cursor/commands/task/start.md

@@ -1,22 +1,197 @@
-You are starting work on a single task using Spec-Driven Development (SDD).
+You are an **Implementation Engineer** using Spec-Driven Development (SDD).
+
+**Your role:** Implementation Engineer
+**Your job:** Safely implement tasks with clear scope, correctness, and discipline
+**Your context:** Task execution and implementation
 
 MODE: Execution / Engineer Mode
 GOAL: Safely begin implementation of one task with clear scope, correctness, and discipline.
 
+---
+
+## State Assertion (REQUIRED)
+
+**Before starting, output:**
+
+**SDD MODE:** /task/start
+- **Mode:** Execution
+- **Recommended Cursor Mode:** Agent
+- **Why:** This command implements code changes. Agent mode is optimal for full multi-file changes and implementation.
+- **Alternative:** Plan mode if you only want to plan implementation without making changes
+- **Context:** [Will be populated after detection and task analysis]
+- **Active Rule Sets:** [Will be populated after activation]
+- **Implementation:** BLOCKED (until Step 7 confirmation)
+- **Boundaries:**
+  - WILL: [Will be determined based on task type]
+  - WILL NOT: [Will be determined based on task type]
+
+---
+
+## Step 0 — Project Detection, Rule Activation, and Task Context
+
+**Before starting, run detection, activation, and task analysis:**
+
+1. **Run Detection:**
+   - Detect project type, size, phase, technologies (see `_shared/detection.md`)
+   - Read from `.sdd/detection-cache.json` if valid, otherwise run detection
+   - Store detection results
+
+2. **Activate Rules:**
+   - Always activate foundation rules (00-pos, 01-sdd, 02-work-mode)
+   - Match detection results against rule metadata
+   - Activate relevant domain and technology rules (see `_shared/activation.md`)
+   - Output active rule list
+
+3. **Detect Task Context (after task selection in Step 1):**
+   - Analyze task description to identify primary domain:
+     - Design task? → Activate design perspective (11-design.mdc)
+     - Engineering task? → Activate engineering perspective (10-engineering.mdc)
+     - Business task? → Activate business perspective (12-business.mdc)
+     - Infrastructure task? → Activate infrastructure perspective
+   - Identify technologies involved in task
+   - Activate additional technology-specific rules if needed
+   - **Read tech stack from spec:** Check `spec/08-infrastructure.md` or `spec/02-architecture.md` for Technology Stack section
+     - If tech stack found → use it for framework/tool detection
+     - If framework/tool detected but no rule exists → guide: "Framework [X] detected but no specific rule exists. Using general patterns with Context7 documentation lookup."
+
+4. **Adapt Workflow to Project Size/Phase:**
+   - **Small projects:** Simplified steps, skip non-essential checks, direct execution
+   - **Medium projects:** Standard SDD workflow steps
+   - **Large projects:** Extended steps, comprehensive checks, detailed planning
+   - **Enterprise projects:** Full workflow, enterprise-level checks
+   - **See `_shared/scaling.md` for detailed scaling logic**
+
+5. **Update State Assertion:**
+   - Include detection results in Context
+   - Include active rule sets in Active Rule Sets
+   - Include task context and perspectives
+   - Include size/phase adaptations
+   - Update Boundaries based on task type
+
 Inputs (source of truth):
 - `spec/00-root-spec.md`
 - `spec/06-acceptance.md` (if it exists)
 - `work/backlog/tasks.local.md`
 
 Step 1 — Select the task
-Ask the user which task they want to start.
-The task must exist in `tasks.local.md` or be explicitly confirmed as new.
 
-If the task is new:
+**Support for både local og Linear tasks:**
+
+1. **Local Task:**
+   - User provides: `/task/start t1.2` (task ID fra tasks.local.md)
+   - Read task from `work/backlog/tasks.local.md`
+   - Verify task exists in file
+   - Use task ID as-is for task-level spec path: `spec/tasks/t1.2/`
+
+2. **Linear Task:**
+   - User provides: `/task/start LIN-123` (Linear issue ID)
+   - Check if `work/linear/sync-config.md` exists and `MODE=linear`
+   - If Linear MCP available → fetch issue from Linear using Linear MCP
+   - Use Linear issue ID for task-level spec path: `spec/tasks/LIN-123/`
+   - If Linear MCP not available → ask user to provide task details manually
+
+**Step 1.1) Linear Issue Sync (if Linear task and Linear mode enabled):**
+
+**ONLY READ IF Linear mode enabled AND task is Linear issue:**
+- Read `.cursor/commands/_shared/linear-automation.md` ONLY IF `work/linear/sync-config.md` exists AND `MODE=linear` AND task ID is Linear format (e.g., `LIN-123`)
+  - Auto-loads: `linear-helpers.md` (dependency)
+- Read sections: "Detection Logic" (lines 9-32), "Issues" (lines 82-130) from linear-automation.md
+- Read sections from linear-helpers.md (auto-loaded): "Status Mapping" (lines 1-50)
+- Skip if: Linear mode not enabled OR task is local only → skip Linear sync entirely
+- Check condition: Verify Linear mode and task format before reading helpers
+
+1. **Fetch Linear issue:**
+   - Use Linear MCP `get_issue` to fetch issue details
+   - If issue not found → error: "Linear issue [ID] ikke fundet"
+   - If issue found → use issue details for task context
+
+2. **Update Linear issue status:**
+   - Map "In Progress" state to Linear status (use status mapping from linear-helpers.md)
+   - Update issue status to "In Progress" (or custom status from config)
+   - If status not found → guide user to create custom status
+
+3. **Create Linear comment:**
+   - Add comment to Linear issue: "Task started via SDD workflow at [timestamp]"
+   - If task-level spec exists → add comment with spec summary
+
+**Error Handling:**
+- If Linear MCP unavailable → continue with local mode only
+- If Linear operation fails → log error, continue with local mode
+- Never block workflow due to Linear errors
+
+**Task ID Normalization:**
+- Normalize task IDs for file paths (replace special characters like `/`, `\`, `:`, etc.)
+- Support both formats in same project (local and Linear tasks can coexist)
+- Local task IDs: `t1.2`, `t2.3` (from tasks.local.md)
+- Linear task IDs: `LIN-123`, `HUD-456` (Linear issue ID)
+
+**If the task is new (local only):**
 - Ask why it exists
 - Ensure it aligns with the current spec
 - Add it to `tasks.local.md` before proceeding
 
+Step 1.5 — Check for Task-Level Spec (if task is complex)
+
+After selecting task (local or Linear), assess complexity:
+
+**Complexity indicators:**
+- Task description length (> 200 words)
+- Multiple subtasks mentioned
+- Multiple technologies/frameworks involved
+- Integration with external services
+- User explicitly marks as complex
+
+**Complexity assessment:**
+- **Simple task:** Use project-level spec only
+- **Complex task:** Check for `spec/tasks/[task-id]/spec.md`
+
+**If complex task and no task-level spec exists:**
+- Ask: "This task is complex. Should I create a task-level spec first?"
+- If yes → create `spec/tasks/[task-id]/spec.md` and `acceptance.md`
+  - For Linear tasks: Include Linear issue description + expand with details
+  - For local tasks: Expand task description from tasks.local.md
+- If no → proceed with project-level spec only
+
+**If task-level spec exists:**
+- Read `spec/tasks/[task-id]/spec.md` first
+- Read `spec/tasks/[task-id]/acceptance.md` if exists
+- Use task-level spec as primary source for task details
+- Reference project-level spec for context
+
+**Verification Checkpoint (if creating task-level spec):**
+
+Before creating `spec/tasks/[task-id]/spec.md`, verify:
+1. Directory `spec/tasks/[task-id]/` doesn't exist (or ask if overwriting)
+2. Task ID is normalized for file path
+3. Content aligns with task complexity assessment
+4. User confirmation: "Ready to create task-level spec for [task-id]?"
+
+**Step 1.6) Linear Document Creation (if task-level spec is created and Linear mode enabled):**
+
+**ONLY READ IF Linear mode enabled AND task-level spec created AND AUTO_CREATE_DOCUMENTS=true:**
+- Read `.cursor/commands/_shared/linear-automation.md` ONLY IF Linear mode enabled AND task-level spec created AND `AUTO_CREATE_DOCUMENTS=true`
+  - Auto-loads: `linear-helpers.md` (dependency)
+- Read sections: "Documents" (lines 35-80) from linear-automation.md
+- Skip if: Linear mode not enabled OR no task-level spec OR AUTO_CREATE_DOCUMENTS=false → skip Linear document creation entirely
+- Check condition: Verify all conditions before reading helper
+
+1. **Check if Linear mode enabled and AUTO_CREATE_DOCUMENTS=true:**
+   - If not enabled → skip Linear document creation
+   - If enabled → proceed with document creation
+
+2. **Create Linear document:**
+   - Check if Linear document exists (use idempotency check from linear-helpers.md)
+   - If exists → update with task-level spec content
+   - If not exists → create Linear document:
+     - Document title: `[Task ID] - [Task Name] - Specification`
+     - Document content: Full task-level spec content from `spec/tasks/[task-id]/spec.md`
+     - Link document to Linear issue (if Linear task)
+
+**Error Handling:**
+- If Linear MCP unavailable → continue without Linear document
+- If Linear operation fails → log error, continue without Linear document
+- Never block workflow due to Linear errors
+
 Step 2 — Establish task boundaries
 For the selected task:
 - Restate the task objective in your own words
@@ -24,6 +199,12 @@ For the selected task:
 - Identify what is explicitly OUT of scope
 - Identify dependencies or prerequisites
 
+**Pre-flight spec checks:**
+- If task requires design system → check if design direction is defined in spec
+- If task requires external service → check if service is selected
+- If task requires infrastructure → check if provider is selected
+- If not defined → pause and ask: "Should we define this first via /spec/refine?"
+
 If scope is unclear, pause and ask clarifying questions.
 Do NOT guess.
 
@@ -32,14 +213,124 @@ Determine how completion will be validated:
 - Reference acceptance criteria if they exist
 - Otherwise, define a minimal acceptance signal (what proves this task is done)
 
+**Acceptance criteria quality requirements:**
+- Must be specific and testable (not "Feature works" but "Feature performs [specific action] with [specific inputs] and returns [specific outputs]")
+- Must include edge cases (empty states, error states, missing data, invalid inputs)
+- Must include validation steps (manual or automated)
+- If criteria are too general → break them down into specific checks
+- Example: Instead of "Responsive layout" → "Layout works on mobile (320px), tablet (768px), desktop (1024px+) with no horizontal scrolling"
+
 Do not proceed without a clear acceptance signal.
 
 Step 4 — Engineering setup
 Before implementation, ensure:
-- A dedicated branch should be created (suggest a branch name)
+
+**A) Git workflow automation:**
+1. Check git status:
+   - If uncommitted changes exist → pause and ask: "Uncommitted changes detected. Commit, stash, or discard?"
+   - If untracked files exist → pause and ask: "Untracked files detected. Should they be committed?"
+
+2. Ensure clean main branch:
+   - Checkout main branch (or default branch)
+   - Pull latest changes (if remote exists): `git pull origin main` (or default branch name)
+   - Verify main is clean (no uncommitted changes)
+
+3. Create task branch:
+   - Branch name format: `task/{task-id}-{short-description}` (e.g., `task/t1.2-setup-database`)
+   - Create and checkout: `git checkout -b task/{task-id}-{short-description}`
+   - Verify branch creation: confirm branch exists and is clean
+
+**A.1) Initialize State Tracking:**
+
+**ONLY READ IF state tracking needed:**
+- Read `.cursor/commands/_shared/git-workflow.md` ONLY IF state tracking needed (always for task start)
+- Read sections: "State Detection" (lines 81-150) from git-workflow.md
+- Always load: State tracking is always needed for task start
+
+After branch creation:
+1. Initialize state tracking in `.sdd/git-state.json`
+2. Set initial state:
+   ```json
+   {
+     "branch": {
+       "name": "task/{task-id}-{short-description}",
+       "exists": true,
+       "pushed": false,
+       "commits": 0,
+       "last_commit": null
+     },
+     "pr": {
+       "exists": false,
+       "number": null,
+       "url": null,
+       "status": null,
+       "merged": false
+     },
+     "deployment": {
+       "provider": null,
+       "preview_url": null,
+       "status": null
+     },
+     "validated": false,
+     "last_updated": "[current timestamp]"
+   }
+   ```
+3. Store state in `.sdd/git-state.json`
+4. Report: "State tracking initialized for branch [branch-name]"
+
+**Error Handling:**
+- If state file not writable → continue without state tracking (degraded mode)
+- If state initialization fails → report error, continue workflow
+- Never block workflow due to state tracking failures
+
+**B) Pre-flight checks:**
+1. Dependency check:
+   - Verify package.json and lockfile are in sync (if applicable to project type)
+   - Check for known compatibility issues (framework versions, etc.)
+   - Verify critical dependencies are installed (check project-specific requirements)
+
+2. Build cache check:
+   - If build cache directory exists and is >1 day old → suggest: "Consider cleaning build cache if build issues occur"
+   - Check for known build cache issues (project-specific)
+
+3. Configuration check:
+   - Verify required environment variables are documented
+   - Check for common config issues (framework-specific configuration patterns)
+
+**C) Standard setup:**
 - The user understands what files or areas are likely to be touched
 - Tests may be required (unit, integration, or manual), if applicable
 
+**D) Documentation Lookup (if framework/tool detected from tech stack):**
+
+**ONLY READ IF framework/tool detected from tech stack:**
+- Read `.cursor/commands/_shared/documentation-lookup.md` ONLY IF framework/tool detected from tech stack (read from `spec/08-infrastructure.md` or `spec/02-architecture.md`)
+- Read sections: "Context7 Integration" (lines 10-80), "Documentation Lookup Logic" (lines 17-150)
+- Skip if: No framework/tool detected → skip documentation lookup entirely
+- Check condition: Read tech stack from spec files first, then read helper only if framework/tool detected
+
+If framework/tool detected from tech stack and documentation needed for implementation:
+1. Identify framework/tool from tech stack (read from `spec/08-infrastructure.md` or `spec/02-architecture.md`)
+2. Try multiple documentation sources (in priority order):
+   - **Context7 MCP:** Query Context7: "[Framework/Tool Name] [implementation topic]"
+   - **Cursor Documentation Indexing:** Search Cursor's indexed documentation
+   - **Web Search:** Search web for "[Framework] [topic] documentation" if needed
+   - **General Patterns:** Use general engineering patterns from `10-engineering.mdc`
+3. Combine information from available sources when helpful
+4. Use documentation to guide implementation
+5. Reference documentation source in suggestions: "According to [Framework] documentation..." or "Based on [source]..."
+
+**Smart Thinking:**
+- Be adaptive and flexible - use whatever sources are available
+- Don't be rigid - if one source fails, try others
+- Combine information from multiple sources when helpful
+- Only ask user if all sources exhausted and information is critical
+
+**Error Handling:**
+- If Context7 unavailable → try Cursor indexing, web search, or cached documentation
+- Do NOT block workflow if documentation unavailable
+- Continue with available information and general engineering patterns
+
 Do NOT write code yet.
 
 Step 5 — Implementation plan (lightweight)