@eskoubar95/spec 0.1.3 → 0.1.4

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

@@ -1,8 +1,51 @@
-You are validating the completion of a single task using Spec-Driven Development (SDD).
+You are a **Quality Auditor** using Spec-Driven Development (SDD).
+
+**Your role:** Quality Auditor
+**Your job:** Validate task completion, ensure correctness and quality before integration
+**Your context:** Task validation and quality assurance
 
 MODE: Validation / Quality Gate
 GOAL: Ensure the task is correct, complete, and safe to integrate before commit or PR.
 
+---
+
+## State Assertion (REQUIRED)
+
+**Before starting, output:**
+
+**SDD MODE:** /task/validate
+- **Mode:** Validation
+- **Recommended Cursor Mode:** Debug
+- **Why:** This command validates completion and can debug issues. Debug mode is optimal for runtime analysis and debugging.
+- **Alternative:** Plan mode for validation only (without debugging)
+- **Context:** [Will be populated after detection]
+- **Active Rule Sets:** [Will be populated after activation]
+- **Implementation:** BLOCKED (validation only, fixes allowed)
+- **Boundaries:**
+  - WILL: Validate correctness, check scope, verify spec alignment, run automated checks, suggest fixes
+  - WILL NOT: Implement new features, expand scope, skip validation steps
+
+---
+
+## 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
+
 Inputs (source of truth):
 - `spec/00-root-spec.md`
 - `spec/06-acceptance.md` (if it exists)
@@ -35,6 +78,87 @@ Ask what evidence exists:
 - Manual verification steps
 - Screenshots, logs, or other proof
 
+**Documentation Lookup (if framework-specific issue found):**
+
+**ONLY READ IF framework/tool detected or documentation needed:**
+- Read `.cursor/commands/_shared/documentation-lookup.md` ONLY IF framework/tool detected in Step 0 OR debugging framework-specific issues
+- Read sections: "Context7 Integration" (lines 10-80), "Documentation Lookup Logic" (lines 17-150)
+- Skip if: No framework/tool detected and no documentation needed → skip documentation lookup entirely
+- Check condition: Run detection first, then read helper only if condition met
+
+If framework-specific issue found during validation:
+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] [issue topic]"
+   - **Cursor Documentation Indexing:** Search Cursor's indexed documentation
+   - **Web Search:** Search web for "[Framework] [issue] troubleshooting" if needed
+   - **General Patterns:** Use general engineering patterns from `10-engineering.mdc`
+3. Combine information from available sources when helpful
+4. Use documentation to verify correct usage
+5. Suggest fixes based on documentation from available sources
+
+**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
+- Search for understanding if needed - use web search to understand framework better
+
+**Error Handling:**
+- If Context7 unavailable → try Cursor indexing, web search, or cached documentation
+- Do NOT block workflow if documentation unavailable
+- Continue with available information
+
+**Automated validation (run before asking user):**
+1. Pre-commit checks:
+   - Run linter (if configured): use project's lint command
+   - Run build (if applicable): use project's build command
+   - Check type errors: use project's type checking command (if TypeScript/typed project)
+   - Verify no console errors (if possible)
+
+2. **Test Execution (if test framework detected):**
+
+**ONLY READ IF test framework detected:**
+- Read `.cursor/commands/_shared/test-automation.md` ONLY IF test framework detected in Step 0
+- Read sections: "Test Framework Detection" (lines 14-67), "Test Execution" (lines 68-154)
+- Skip if: No test framework found → skip test automation entirely
+- Check condition: Run detection first, then read helper only if condition met
+
+**Test Automation:**
+- Detect test framework (Jest, Vitest, Playwright, Cypress, etc.)
+- If framework detected → run tests automatically
+- Parse test results (pass/fail count, failures)
+- Collect test coverage (if enabled)
+- Report test status:
+  - If tests pass → "✅ Tests passed (X tests)"
+  - If tests fail → "❌ Tests failed (X failed, Y passed)" + list failures
+  - If no framework detected → "⚠️ No test framework detected. Skipping test execution."
+
+**Test Failure Handling:**
+- If tests fail → report failures clearly
+- Block validation if `REQUIRE_TESTS_PASS=true` (optional, default: false)
+- If blocking disabled → warn but continue validation
+
+**Test Coverage:**
+- Collect coverage metrics (if enabled)
+- Compare with previous coverage (if available)
+- Report coverage percentage
+- Flag significant coverage decrease (> 10%)
+
+3. Automated validation checklist:
+   - [ ] Linter passes
+   - [ ] Build succeeds
+   - [ ] Type checking passes (if applicable)
+   - [ ] Tests pass (if test framework detected)
+   - [ ] Test coverage acceptable (if coverage enabled)
+   - [ ] No console errors (if applicable)
+   - [ ] Manual testing completed (user confirms)
+
+**Present validation checklist based on task type:**
+- For UI tasks: "Test on mobile/tablet/desktop, verify responsive breakpoints, check accessibility"
+- For API tasks: "Test endpoints, verify error handling, check response formats"
+- For config tasks: "Verify functionality, check logs, test configuration changes"
+- For design tasks: "Verify visual consistency, check accessibility, test on different devices"
+
 If testing is missing but appropriate, flag it explicitly.
 Do not write tests unless asked.
 
@@ -49,6 +173,27 @@ Assess whether the task is:
 - Ready for PR
 - Requires follow-up work
 
+**Automated merge workflow (if user prefers):**
+1. Pre-merge checks:
+   - Verify all changes are committed
+   - Run build/test (if applicable)
+   - Check for merge conflicts with main: `git fetch origin main && git merge-base HEAD origin/main`
+
+2. Merge to main:
+   - Checkout main (or default branch): `git checkout main`
+   - Pull latest (if remote exists): `git pull origin main`
+   - Merge task branch: `git merge task/{task-id}-{short-description}`
+   - Push to remote (if configured): `git push origin main`
+
+3. Post-merge cleanup:
+   - Delete local task branch (optional, ask first): `git branch -d task/{task-id}-{short-description}`
+   - Verify main is clean
+
+**Ask user preference:**
+- "Should I auto-commit on task completion?" (if not already committed)
+- "Should I auto-merge to main on validation?" (if validated)
+- "Should I delete task branch after merge?" (optional)
+
 If follow-up is required:
 - Propose new tasks and add them to `tasks.local.md`
 
@@ -58,6 +203,252 @@ Conclude with one of the following outcomes:
 - Requires fixes (clearly listed)
 - Requires spec refinement (`/spec/refine`)
 
+**Step 7.1) Linear Issue Update (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 update entirely
+- Check condition: Verify Linear mode and task format before reading helpers
+
+1. **Check if task is Linear issue:**
+   - If task ID is Linear format (e.g., `LIN-123`) → proceed with Linear update
+   - If task is local only → skip Linear update
+
+2. **Update Linear issue status:**
+   - Map validation result to Linear status (use status mapping from linear-helpers.md):
+     - **Approved:** "Done" (or `STATUS_DONE` from config)
+     - **Requires fixes:** "In Progress" (or `STATUS_IN_PROGRESS` from config)
+     - **Requires spec refinement:** "Blocked" (or `STATUS_BLOCKED` from config)
+   - Update issue status using Linear MCP
+   - If status not found → guide user to create custom status
+
+3. **Create Linear comment with validation summary:**
+   - Add comment to Linear issue:
+     ```
+     "Task validated: [result]
+     Acceptance criteria: [summary]
+     Issues found: [list] (if any)
+     Next steps: [list] (if any)"
+     ```
+   - Include relevant context from validation
+
+**Error Handling:**
+- If Linear MCP unavailable → continue without Linear update
+- If Linear operation fails → log error, continue without Linear update
+- Never block workflow due to Linear errors
+
+**Step 7.2) Linear Document Update (if task-level spec exists and Linear mode enabled):**
+
+**ONLY READ IF Linear mode enabled AND task-level spec exists AND AUTO_CREATE_DOCUMENTS=true:**
+- Read `.cursor/commands/_shared/linear-automation.md` ONLY IF Linear mode enabled AND `spec/tasks/[task-id]/spec.md` exists 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 update entirely
+- Check condition: Verify all conditions before reading helper
+
+1. **Check if task-level spec exists:**
+   - If `spec/tasks/[task-id]/spec.md` exists → proceed with document update
+   - If not exists → skip document update
+
+2. **Check if Linear mode enabled and AUTO_CREATE_DOCUMENTS=true:**
+   - If not enabled → skip Linear document update
+   - If enabled → proceed with document update
+
+3. **Update 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 (same as Step 1.6 in `/task/start`)
+
+**Error Handling:**
+- If Linear MCP unavailable → continue without Linear document update
+- If Linear operation fails → log error, continue without Linear document update
+- Never block workflow due to Linear errors
+
+**Step 7.3) CodeRabbit Integration (if PR exists):**
+
+**ONLY READ IF PR exists:**
+- Read `.cursor/commands/_shared/coderabbit-integration.md` ONLY IF PR exists for current branch
+  - Auto-loads: `github-helpers.md` (dependency)
+- Read sections: "CodeRabbit Detection" (lines 14-60), "Conversation Resolution" (lines 121-180) from coderabbit-integration.md
+- Read sections from github-helpers.md (auto-loaded): "Read PR Conversations" (lines 51-100), "Resolve Conversations" (lines 101-150)
+- Skip if: No PR exists → skip CodeRabbit integration entirely
+- Check condition: Verify PR exists via GitHub MCP/CLI before reading helpers
+
+1. **Check if PR exists:**
+   - Get current branch name
+   - Check if PR exists for current branch (via GitHub MCP or CLI)
+   - If no PR exists → skip CodeRabbit integration
+   - If PR exists → proceed with CodeRabbit handling
+
+2. **Read CodeRabbit comments:**
+   - Use GitHub helpers to read PR comments (MCP → CLI → Local fallback)
+   - Detect CodeRabbit comments (pattern search + author check)
+   - Filter to only CodeRabbit comments
+
+3. **For each CodeRabbit comment:**
+   - **Check if already resolved:**
+     - Read tracking file (`.sdd/github-resolved-issues.json`)
+     - If comment already resolved → skip
+   
+   - **Check if issue is fixed in code:**
+     - Read file mentioned in comment
+     - Compare comment suggestion with current code
+     - If issue already fixed → mark for resolution
+   
+   - **If issue fixed:**
+     - Resolve conversation via GitHub helpers
+     - Update tracking file with resolution
+     - Add comment: "Issue resolved in code"
+   
+   - **If issue not fixed:**
+     - Evaluate if issue should be resolved (check importance, refactoring rules)
+     - If should be resolved → create task in backlog
+     - If shouldn't be resolved → provide argumentation (log to Linear/GitHub/local)
+
+4. **Report CodeRabbit handling:**
+   - Summarize: "X CodeRabbit comments processed, Y resolved, Z deferred"
+   - List any deferred issues with reasoning
+
+**Error Handling:**
+- If GitHub MCP/CLI unavailable → skip CodeRabbit integration, continue workflow
+- If PR not found → skip CodeRabbit integration, continue workflow
+- If comment parsing fails → log error, continue with next comment
+- Never block workflow due to CodeRabbit integration failures
+
+**ONLY READ IF validated and ready for PR:**
+- Read `.cursor/commands/_shared/git-workflow.md` ONLY IF task validated AND ready for PR
+- Read `.cursor/commands/_shared/pr-description.md` ONLY IF PR creation/update needed
+- Read `.cursor/commands/_shared/deployment-detection.md` ONLY IF deployment provider detected
+- Read sections: "State Detection" (lines 81-150), "Next Step Logic" (lines 151-220) from git-workflow.md; "PR Description Template" (lines 1-100) from pr-description.md; "Provider Detection" (lines 13-91), "Preview Deployment Logic" (lines 92-194) from deployment-detection.md
+- Skip if: Task not validated OR not ready for PR → skip Git workflow automation entirely
+- Check condition: Verify validation status and PR readiness before reading helpers
+
+1. **Update State Tracking:**
+   - Read current state from `.sdd/git-state.json`
+   - Update state: `validated: true`
+   - Update commit count if commits were made
+   - Update last commit hash
+   - Save updated state
+
+2. **Check if PR Already Exists:**
+   - Get current branch name
+   - Check if PR exists for branch (via GitHub MCP or CLI)
+   - If PR exists → skip to Step 3 (update PR if needed)
+   - If no PR → proceed to Step 2.1 (create PR)
+
+3. **Generate Commit Message (if changes not committed):**
+   - If uncommitted changes exist → generate commit message
+   - Use git-workflow.md helper:
+     - Analyze git diff for changed files
+     - Determine commit type (feat/fix/refactor/etc.)
+     - Generate description from task/changes
+     - Format: `[task-id] type: description`
+   - Ask user: "Should I commit these changes with message: '[generated message]'?"
+   - If yes → commit with generated message
+   - Update state: increment commit count
+
+4. **Create PR (if no PR exists and validated):**
+   
+   **4.1) Generate PR Description:**
+   - Use pr-description.md helper:
+     - Read task spec (from `work/backlog/tasks.local.md` or task-level spec)
+     - Generate changes summary from git diff and commit history
+     - Extract acceptance criteria from task
+     - Include testing notes
+     - Reference related Linear issues (if Linear enabled)
+   - Generate PR description using template
+
+   **4.2) Push Branch (if not pushed):**
+   - Check if branch is pushed to remote
+   - If not pushed → push branch: `git push -u origin <branch-name>`
+   - Update state: `branch.pushed: true`
+
+   **4.3) Create PR:**
+   - Use GitHub helpers (MCP → CLI → Local fallback)
+   - Create PR with generated description
+   - Set PR title: `[task-id] [task description]`
+   - Link to Linear issue (if Linear enabled and task is Linear issue)
+   - Get PR number and URL
+   - Update state: `pr: {exists: true, number: X, url: Y, status: 'open'}`
+
+5. **Handle Deployment (if PR created):**
+   
+   **5.1) Detect Deployment Provider:**
+   - Use deployment-detection.md helper:
+     - Check for provider config files (vercel.json, railway.json, netlify.toml)
+     - Read spec/08-infrastructure.md for deployment config
+     - Detect provider (Vercel, Railway, Netlify, etc.)
+
+   **5.2) Trigger Preview Deployment (if provider detected):**
+   - If provider supports auto-deployment → wait for deployment
+   - If manual deployment needed → trigger deployment (if possible)
+   - Check deployment status (with timeout)
+   - Get preview URL when deployment completes
+
+   **5.3) Update PR with Preview URL:**
+   - If preview URL available → add to PR description
+   - Format: `### Preview\n[Preview URL](url)`
+   - Update PR via GitHub helpers
+   - Update state: `deployment: {provider: X, preview_url: Y, status: 'success'}`
+
+6. **Determine Next Step:**
+   - Based on current state, determine next action:
+     - "PR created, deployed → Ready for review"
+     - "PR created, deployment pending → Waiting for deployment"
+     - "PR created, no deployment → PR ready (no preview available)"
+   - Report next step to user
+
+**ONLY READ IF preview URL available OR performance enabled:**
+- Read `.cursor/commands/_shared/performance-monitoring.md` ONLY IF preview URL available OR performance monitoring enabled
+- Read sections: "Performance Metrics Collection" (lines 14-80), "Lighthouse Integration" (lines 199-250)
+- Skip if: No preview URL AND performance not enabled → skip performance monitoring entirely
+- Check condition: Verify preview URL availability or performance config before reading helper
+
+1. **Collect Performance Metrics (if enabled):**
+   - Measure bundle size (if build output available)
+   - Track load time metrics (if preview URL available)
+   - Monitor API response times (if applicable)
+   - Store metrics in `.sdd/performance-metrics.json`
+
+2. **Run Lighthouse Audit (if preview URL available):**
+   - Run Lighthouse audit on preview URL
+   - Collect performance, accessibility, SEO, best practices scores
+   - Parse Lighthouse JSON output
+   - Compare scores with baseline (if available)
+
+3. **Detect Performance Regressions:**
+   - Compare current metrics with previous build/commit
+   - Flag significant regressions (> 20% degradation)
+   - Check performance budgets (if configured)
+   - Report performance status
+
+4. **Add Performance Report to PR (if PR exists):**
+   - Add performance metrics to PR comment
+   - Show Lighthouse scores
+   - Highlight regressions
+   - Suggest optimizations (if needed)
+
+**Error Handling:**
+- If performance monitoring unavailable → skip monitoring, continue workflow
+- If Lighthouse audit fails → skip Lighthouse, continue workflow
+- If metrics collection fails → skip metrics, continue workflow
+- Never block workflow due to performance monitoring failures
+
+**Error Handling:**
+- If state file not writable → continue without state tracking (degraded mode)
+- If PR creation fails → report error, allow manual PR creation
+- If deployment fails → report error, continue without preview URL
+- If GitHub MCP/CLI unavailable → skip PR creation, continue workflow
+- Never block workflow due to automation failures
+
+**User Preferences:**
+- Ask user: "Should I auto-create PR after validation?" (if not already configured)
+- Ask user: "Should I auto-deploy to preview?" (if deployment available)
+- Respect user preferences for automation level
+
 PRINCIPLES:
 - Validation is about confidence, not perfection
 - Evidence beats assumptions

package/template/.cursor/rules/02-work-mode.mdc

@@ -63,3 +63,74 @@ A task is only considered complete when:
 
 ## Goal
 Enable focused, professional execution that aligns implementation with intent.
+
+## Error recovery automation
+**Common error patterns and automatic recovery:**
+- If build fails with undefined property errors → automatically suggest: "Try cleaning build cache and rebuilding"
+- If lockfile outdated → automatically suggest: "Run package manager install to sync lockfile"
+- If dependency missing → automatically suggest: "Add to package.json (or equivalent) and run install"
+- If config error → check against known patterns for the framework/library and suggest fix
+- Document solutions in openmemory.md for future reference
+
+**Error recovery workflow:**
+1. Identify error type (build, dependency, config, runtime)
+2. Check openmemory.md for known solutions
+3. If known solution exists → apply automatically (with user confirmation)
+4. If unknown → document in openmemory.md after solving
+
+## Memory storage automation
+**Automatic memory storage triggers:**
+- Before task completion → automatically check if memory should be stored
+- If 3+ files changed OR new component created → store memory
+- If design pattern emerges → store in spec/05-decisions.md AND memory
+- If infrastructure decision made → store in spec/05-decisions.md AND memory
+
+**Memory storage checklist (before task completion):**
+- [ ] Memory stored? (if applicable)
+- [ ] openmemory.md updated? (if memory stored)
+- [ ] Spec updated? (if decision/pattern emerged)
+- [ ] Decisions documented in spec/05-decisions.md? (if applicable)
+
+**Always update openmemory.md before storing memory:**
+- Review content → check namespaces → assign namespace if applicable
+- Update Components section if new component
+- Update Patterns section if new pattern
+- Update Architecture section if architecture change
+
+## Spec update automation
+**Automatic spec update triggers:**
+- If design pattern emerges → update spec/05-decisions.md
+- If infrastructure decision made → update spec/05-decisions.md
+- If new risk discovered → update spec/03-risks.md
+- If new question emerges → update spec/04-open-questions.md
+
+**Spec update checklist (before task completion):**
+- [ ] Design pattern documented? (if applicable)
+- [ ] Infrastructure decision documented? (if applicable)
+- [ ] New risk added? (if applicable)
+- [ ] New question added? (if applicable)
+- [ ] Spec still accurate? (verify and update if needed)
+
+## Spec health checks
+**Automatic spec health monitoring:**
+- Detect spec-code divergence (features in code not in spec, features in spec not in code)
+- Warn when spec is outdated (spec not updated recently, implementation changed significantly)
+- Suggest spec updates when discrepancies found
+- Track spec evolution (spec age, update frequency, completeness)
+
+**Spec health check triggers:**
+- Before task start → check if spec is up-to-date
+- After task completion → check if spec needs update
+- Periodically → suggest spec sync if divergence detected
+
+**Spec health indicators:**
+- Spec age: How long since last update
+- Spec completeness: Are all features documented?
+- Spec accuracy: Does spec match implementation?
+- Spec traceability: Can requirements be traced to code?
+
+**When spec health issues detected:**
+- Suggest `/spec/sync` if divergence found
+- Suggest `/spec/evolve` if spec needs updating
+- Suggest `/spec/audit` if compliance check needed
+- Warn user about outdated spec

package/template/.cursor/rules/openmemory.mdc

@@ -14,7 +14,7 @@ entire session.
 
 Memory = accumulated understanding of codebase + user preferences. Like a colleague who's worked here months.
 
-**project_id:** spec-driven-development
+**project_id:** eskoubar95/spec
 
 ## NON-NEGOTIABLE: Memory-First Development