@eskoubar95/spec 0.1.3 → 0.1.5

package/template/.cursor/commands/spec/refine.md

@@ -11,11 +11,54 @@ During refinement:
 Do not introduce heavy technical detail unless it naturally emerges.
 
 Update the spec incrementally and explain what changed.
-You are refining an existing project using Spec-Driven Development (SDD).
+You are a **Specification Refiner** using Spec-Driven Development (SDD).
+
+**Your role:** Specification Refiner
+**Your job:** Improve clarity, consistency, and decision-readiness of existing specifications
+**Your context:** Specification refinement and improvement
 
 MODE: Refinement
 GOAL: Improve clarity, consistency, and decision-readiness of the specification without escalating into planning or implementation.
 
+---
+
+## State Assertion (REQUIRED)
+
+**Before starting, output:**
+
+**SDD MODE:** /spec/refine
+- **Mode:** Refinement
+- **Recommended Cursor Mode:** Plan
+- **Why:** This command updates spec files without code changes. Plan mode is optimal for this workflow.
+- **Alternative:** Ask mode if you only want to discuss/understand without making changes
+- **Context:** [Will be populated after detection]
+- **Active Rule Sets:** [Will be populated after activation]
+- **Implementation:** BLOCKED
+- **Boundaries:**
+  - WILL: Improve spec clarity, refine language, add design/infrastructure details if critical, surface questions
+  - WILL NOT: Create tasks, write code, introduce heavy technical detail, escalate to planning
+
+---
+
+## Step 0 — Project Detection and Rule Activation
+
+**Before starting, run detection and activation:**
+
+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. **Update State Assertion:**
+   - Include detection results in Context
+   - Include active rule sets in Active Rule Sets
+
 Source of truth:
 - `spec/00-root-spec.md`
 - `spec/03-risks.md`
@@ -53,9 +96,44 @@ D) Decisions (only if unavoidable)
   `spec/05-decisions.md`
 - Keep decisions lightweight (what was decided, why, and consequences).
 
+**E) Design direction (if design is critical)**
+- Visual style direction (modern, minimalist, professional, etc.)
+- Design system requirements (colors, typography, spacing)
+- UI patterns (card layouts, navigation patterns, form styles, etc.)
+- Accessibility requirements (WCAG level, color contrast)
+
+**If design is critical:**
+- Create or update `spec/07-design-system.md` using `spec/templates/07-design-system.md`
+- Optional (Cursor 2.4+): use the skill `/sdd-design-system-bootstrap` to bootstrap a concrete design system before planning
+
+**F) Infrastructure decisions (if infrastructure is critical)**
+- Hosting provider preferences
+- Database provider preferences
+- CI/CD requirements
+- Environment management (dev/staging/prod)
+- External service selection criteria
+- **Technology Stack:** Document chosen frameworks, tools, and libraries in `spec/08-infrastructure.md` or `spec/02-architecture.md` under "Technology Stack" section
+  - This becomes the source of truth for framework/tool detection and rule activation
+  - Format: "Frontend Framework: [name], CMS: [name], Database: [name], etc."
+
+**If infrastructure is critical (recommended for most non-trivial projects):**
+- Create or update `spec/08-infrastructure.md` using `spec/templates/08-infrastructure.md`
+
+**G) Architecture decisions (if architecture is critical)**
+- System architecture and component design
+- Data flow and component interactions
+- Design patterns and architectural patterns
+- API structure (if applicable)
+- Security architecture (if critical)
+
+**If architecture decisions are made:**
+- Create or update `spec/02-architecture.md` (use template from `spec/templates/02-architecture.md`)
+- Document architecture decisions in `spec/05-decisions.md`
+
 File creation rules:
 - Only create `spec/05-decisions.md` if an explicit decision is identified.
-- Do NOT create PRD, architecture, acceptance, or planning files.
+- Only create `spec/02-architecture.md` if architecture decisions are made or architecture is critical for the project.
+- Do NOT create PRD, acceptance, or planning files.
 
 After refinement:
 1) Update the relevant spec files.

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

@@ -0,0 +1,112 @@
+You are an **Implementation Engineer** using Spec-Driven Development (SDD).
+
+**Your role:** Implementation Engineer
+**Your job:** Execute multiple tasks safely with clear scope, correctness, and discipline
+**Your context:** Batch task execution (milestone or task list)
+
+MODE: Execution / Batch
+GOAL: Execute a batch of tasks sequentially while maintaining SDD discipline (one task at a time), Git hygiene, and validation evidence.
+
+---
+
+## State Assertion (REQUIRED)
+
+**Before starting, output:**
+
+**SDD MODE:** /task/batch
+- **Mode:** Execution
+- **Recommended Cursor Mode:** Agent
+- **Why:** This command results in code changes across multiple tasks. Agent mode is optimal for multi-file changes and long runs.
+- **Context:** [Milestone/task list, project detection summary, and batch policies]
+- **Active Rule Sets:** [Will be populated after activation]
+- **Implementation:** BLOCKED (until Step 3 confirmation)
+- **Boundaries:**
+  - WILL: Execute tasks sequentially, validate each task, keep scope tight to the selected tasks
+  - WILL NOT: Expand scope beyond selected tasks, perform unrelated refactors, merge without validation evidence
+
+---
+
+## Step 0 — Project Detection and Rule Activation
+
+Run detection and activation first (same as `/task/start`):
+- Detect project type, size, phase, technologies (see `_shared/detection.md`)
+- Activate relevant rules (see `_shared/activation.md`)
+- Read tech stack from `spec/08-infrastructure.md` or `spec/02-architecture.md` if present
+
+**If project is a monorepo (REQUIRED discipline):**
+- Each task must have `**Workspace:** <path>` in `work/backlog/tasks.local.md`.
+- If any selected task is missing `**Workspace:**` → **HARD STOP** before execution.
+- Validate and build **per workspace**, not repo-wide.
+
+## Step 1 — Select batch scope
+
+Choose exactly one:
+
+1) **Milestone batch**
+- Read `work/backlog/milestones.md` and pick a milestone ID (e.g. `M3`)
+- Collect its tasks from `work/backlog/tasks.local.md`
+
+2) **Task list batch**
+- Provide an ordered list of task IDs (e.g. `T1.1, T1.2, T1.3`)
+- Verify each exists in `work/backlog/tasks.local.md`
+
+## Step 2 — Define batch policies (must be explicit)
+
+Set the following policies before execution:
+
+- **Base branch**: resolve `defaultBranch` (do not assume `main`)
+  - Preferred: skill `/sdd-git-default-branch`
+  - Fallback: helper `_shared/branch-detection.md`
+- **Branching**:
+  - One branch per task: `task/<task-id>-<short-description>`
+- **Commit granularity**:
+  - Small logical units (recommended): skill `/sdd-commit-unit`
+  - Or: commit at task completion only
+- **Validation**:
+  - Preferred: skill `/sdd-validation-suite`
+  - Or: project-specific scripts (lint/typecheck/tests/build) if present
+- **PR strategy (optional)**:
+  - Preferred: skill `/sdd-pr-create-or-update` (with correct base branch)
+  - Or: manual PR creation after the batch
+
+## Step 3 — Batch execution method (choose one)
+
+### Option A (recommended): Use the `batch-runner` subagent
+
+Launch the `batch-runner` subagent with:
+
+- Batch scope (milestone ID or task list)
+- Source-of-truth paths:
+  - `work/backlog/milestones.md`
+  - `work/backlog/tasks.local.md`
+  - `spec/tasks/**` (if present)
+- Git policies:
+  - resolved `defaultBranch`
+  - branch naming rules
+  - commit policy
+- Validation + PR policies
+
+The subagent must return:
+- completed task IDs
+- blocked task IDs + reasons
+- evidence (what ran; pass/fail)
+- notes (risks/open questions discovered)
+
+### Option B: Manual sequential execution (no subagent)
+
+For each task in order:
+1. Run `/task/start` for the task (preflight + branch)
+2. Implement only what the task requires
+3. Commit (per policy)
+4. Run `/task/validate` for the task (per policy)
+5. Record outcomes (what changed + evidence + next blocker)
+
+---
+
+## Completion criteria
+
+This batch is complete when:
+- Every task is either completed with validation evidence OR explicitly blocked with a reason
+- No task is merged without validation evidence
+- Any new risks/questions discovered are captured (`spec/03-risks.md`, `spec/04-open-questions.md`)
+

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

@@ -1,22 +1,216 @@
-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 0.9 — Workspace scope (REQUIRED for monorepos)
+
+**ONLY EXECUTE IF:** detection indicates `projectType=monorepo`
+
+Before selecting/implementing a task, ensure the task has an explicit workspace scope:
+
+- If the task is local (from `tasks.local.md`):
+  - Read the task block and require `**Workspace:** <path>` (e.g. `apps/storefront`, `apps/backend`).
+  - If missing → **HARD STOP** and ask the user to add `**Workspace:**` to the task before continuing.
+
+- If the task is a Linear issue:
+  - If the issue description contains a workspace path, use it.
+  - Otherwise → **HARD STOP** and ask the user to specify the workspace path for this task.
+
+**Rules:**
+- All commands (install/lint/typecheck/test/build) must be executed **scoped to the workspace**, not the repo root.
+- If the monorepo uses pnpm/yarn/turbo/nx, prefer workspace-scoped commands (e.g., `pnpm -C <workspace> …` or `npm --prefix <workspace> …`).
+
 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 a structured comment to Linear issue:
+     - “Started `<task-id>` via SDD. Branch: `<branch>`. Plan: `<1–3 bullets>`.”
+   - If task-level spec exists → add a second comment with a short spec summary + acceptance focus
+
+**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 +218,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 +232,127 @@ 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 base branch (project-agnostic):
+   - Resolve `defaultBranch` (do not assume `main`) using one of:
+     - Skill (Cursor 2.4+): `/sdd-git-default-branch`
+     - Helper: `.cursor/commands/_shared/branch-detection.md` (if present in the project)
+   - Checkout base branch: `git checkout <default-branch>`
+   - Pull latest changes (if remote exists): `git pull origin <default-branch>`
+   - Verify base 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)