@eskoubar95/spec 0.1.0 → 0.1.3

package/template/.cursor/commands/_shared/coderabbit-integration.md

@@ -0,0 +1,278 @@
+---
+helper_id: coderabbit-integration
+load_when:
+  - pr_exists
+  - code_review_needed
+  - task_validate
+  - refactoring_analysis
+dependencies:
+  - github-helpers
+sections:
+  detection:
+    title: "CodeRabbit Detection"
+    lines: [14, 60]
+  categorization:
+    title: "Issue Categorization"
+    lines: [61, 120]
+  resolution:
+    title: "Conversation Resolution"
+    lines: [121, 180]
+  argumentation:
+    title: "Argumentation Logging"
+    lines: [181, 234]
+always_load: false
+---
+
+# CodeRabbit Integration
+
+This helper provides logic for detecting, reading, and handling CodeRabbit code review comments from GitHub PRs.
+
+## Purpose
+
+Automatically handle CodeRabbit comments by:
+- Detecting CodeRabbit comments in PRs
+- Categorizing issues (Minor, Major, Bottleneck, Optimization)
+- Evaluating if issues are already resolved in code
+- Resolving conversations when issues are fixed
+- Providing argumentation when issues shouldn't be resolved
+
+## CodeRabbit Detection
+
+### Detection Methods
+
+**Method 1: Pattern Search**
+- Search for patterns in comment text:
+  - "CodeRabbit"
+  - "code rabbit"
+  - "CodeRabbit AI"
+  - "coderabbit"
+  - Case-insensitive matching
+
+**Method 2: Author Check**
+- Check if comment author is CodeRabbit bot
+- Common bot usernames:
+  - "coderabbitai"
+  - "coderabbit[bot]"
+  - "code-rabbit"
+  - "CodeRabbit"
+
+**Combined Detection:**
+- Use both methods for reliable detection
+- If either method matches → treat as CodeRabbit comment
+
+## Reading PR Comments
+
+### GitHub Integration Fallback Strategy
+
+**Priority 1: GitHub MCP**
+- Use `mcp_github_get_pull_request_comments` if available
+- Check MCP availability first
+
+**Priority 2: GitHub CLI**
+- If MCP not available → use GitHub CLI `gh pr view --comments`
+- Check if `gh` is installed: `gh --version`
+- Parse CLI output for comments
+
+**Priority 3: Local Mode**
+- If both fail → log to local mode
+- Store in `work/backlog/tasks.local.md` for manual review
+
+### Comment Structure
+
+CodeRabbit comments typically include:
+- **Issue type:** Minor, Major, Bottleneck, Optimization
+- **File path:** Which file has the issue
+- **Line numbers:** Specific lines affected
+- **Suggestion:** What should be changed
+- **Reason:** Why the change is suggested
+
+## Issue Categorization
+
+### Categories
+
+**Minor:**
+- Styling issues (formatting, spacing)
+- Naming conventions
+- Code style preferences
+- Minor optimizations
+
+**Major:**
+- Performance issues
+- Security vulnerabilities
+- Bugs or potential bugs
+- Architecture concerns
+
+**Bottleneck:**
+- Performance bottlenecks
+- Slow operations
+- Resource-intensive code
+- Scalability issues
+
+**Optimization:**
+- Code optimization suggestions
+- Efficiency improvements
+- Better algorithms
+- Reduced complexity
+
+### Categorization Logic
+
+1. **Read comment text:**
+   - Look for keywords: "minor", "major", "bottleneck", "optimization"
+   - Check CodeRabbit labels/markers
+
+2. **Analyze suggestion:**
+   - If performance-related → Bottleneck or Optimization
+   - If security-related → Major
+   - If styling-related → Minor
+   - If bug-related → Major
+
+3. **Default categorization:**
+   - If unclear → treat as Minor (less disruptive)
+
+## Evaluating Resolution
+
+### Step 1: Check if Issue Already Resolved
+
+**For each CodeRabbit comment:**
+1. **Read file mentioned in comment:**
+   - Get file path from comment
+   - Read current file content
+
+2. **Check if issue is fixed:**
+   - Compare comment suggestion with current code
+   - If suggestion already implemented → mark as resolved
+   - If code changed but issue persists → mark as unresolved
+
+3. **Verify resolution:**
+   - Check if the specific issue mentioned is addressed
+   - Don't assume all changes resolve the issue
+
+### Step 2: Evaluate if Issue Should Be Resolved
+
+**If issue not resolved:**
+1. **Assess importance:**
+   - Minor issues: Can be deferred
+   - Major issues: Should be addressed
+   - Bottlenecks: Should be addressed if performance-critical
+   - Optimizations: Can be deferred if not critical
+
+2. **Check refactoring rules:**
+   - Compare with refactoring rules (see `/tools/refactor`)
+   - If aligns with refactoring rules → should be resolved
+   - If conflicts with project patterns → may not need resolution
+
+3. **Consider project context:**
+   - Is this a critical path?
+   - Is this blocking other work?
+   - Is this a known pattern in the project?
+
+## Resolution Actions
+
+### When Issue is Resolved
+
+1. **Resolve conversation:**
+   - Use GitHub helpers (see `github-helpers.md`)
+   - Mark conversation as resolved
+   - Add comment: "Issue resolved in code"
+
+2. **Track resolution:**
+   - Log to tracking system (avoid duplicate resolution)
+   - Update local tracking if needed
+
+### When Issue Should Be Resolved (But Not Yet)
+
+1. **Create task:**
+   - Add to `work/backlog/tasks.local.md` or Linear
+   - Reference CodeRabbit comment
+   - Set appropriate priority
+
+2. **Add comment to PR:**
+   - Acknowledge the issue
+   - Explain when it will be addressed
+   - Reference created task
+
+### When Issue Shouldn't Be Resolved
+
+1. **Provide argumentation:**
+   - Explain why the issue won't be resolved
+   - Reference project patterns or decisions
+   - Log to Linear issue or GitHub issue comment
+
+2. **Log to local mode:**
+   - If Linear/GitHub not available → log to `work/backlog/tasks.local.md`
+   - Include argumentation for future reference
+
+## Integration Points
+
+### In `/task/validate`:
+
+**After validation:**
+1. Check if PR exists (from current branch)
+2. If PR exists → read CodeRabbit comments
+3. For each CodeRabbit comment:
+   - Check if issue resolved
+   - If resolved → resolve conversation
+   - If not resolved → evaluate and take action
+
+### In `/tools/refactor`:
+
+**After refactoring:**
+1. Check if PR exists
+2. If PR exists → read CodeRabbit comments
+3. For each refactoring-related comment:
+   - Evaluate against refactoring rules
+   - If refactoring needed → apply refactoring
+   - If not needed → provide argumentation
+
+## Error Handling
+
+- **GitHub MCP not available:** Try GitHub CLI, then local mode
+- **GitHub CLI not available:** Use local mode
+- **CodeRabbit not found:** Skip CodeRabbit integration, continue workflow
+- **PR not found:** Skip PR integration, continue workflow
+- **Comment parsing fails:** Log error, continue with next comment
+
+## Best Practices
+
+1. **Don't block workflow:** If CodeRabbit integration fails, continue without it
+2. **Respect user decisions:** If user explicitly ignores an issue, don't re-raise it
+3. **Track resolutions:** Avoid duplicate resolution attempts
+4. **Provide context:** When arguing against resolution, provide clear reasoning
+5. **Prioritize correctly:** Address Major issues before Minor issues
+
+## Examples
+
+### Example 1: Minor Issue Resolved
+
+**CodeRabbit comment:**
+- "Consider using const instead of let for variable that's never reassigned"
+- File: `src/utils/helpers.ts`, Line 42
+
+**Action:**
+- Check if code already uses `const`
+- If yes → resolve conversation
+- If no → check if should be changed (usually yes for Minor)
+
+### Example 2: Major Issue Not Resolved
+
+**CodeRabbit comment:**
+- "Potential security vulnerability: SQL injection risk"
+- File: `src/api/users.ts`, Line 15
+
+**Action:**
+- Check if code uses parameterized queries
+- If no → create task to fix (Major issue)
+- Add comment to PR acknowledging issue
+- Log to Linear or local backlog
+
+### Example 3: Optimization Deferred
+
+**CodeRabbit comment:**
+- "Consider using Map instead of Object for better performance"
+- File: `src/data/processor.ts`, Line 89
+
+**Action:**
+- Evaluate if performance is critical
+- If not critical → add comment explaining deferral
+- Log to backlog for future optimization
+

package/template/.cursor/commands/_shared/command-stacks.md

@@ -0,0 +1,124 @@
+---
+helper_id: command-stacks
+load_when:
+  - command_invocation
+  - workflow_automation
+sections:
+  invocation:
+    title: "Command Invocation"
+    lines: [1, 50]
+  stacks:
+    title: "Command Stacks"
+    lines: [51, 100]
+always_load: false
+---
+
+# Command Stacks
+
+Command stacks allow commands to invoke other commands in sequence, enabling automated workflows.
+
+## Purpose
+
+Command stacks provide:
+- **Automated Workflows**: Execute multiple commands in sequence
+- **Auto-Proceed Logic**: Optionally proceed without user confirmation between steps
+- **Error Handling**: Stop on error, allow resume after fix
+- **Stack Tracking**: Track progress through stack execution
+
+## Available Command Stacks
+
+### Full Project Initialization
+**Stack:** `/spec/init` → `/spec/refine` → `/spec/plan`
+**Purpose:** Complete project setup from idea to execution plan
+**When to use:** New project initialization
+**Auto-proceed:** Optional (ask user)
+**Error handling:** Stop on error, allow resume
+
+### Feature Development
+**Stack:** `/spec/refine` → `/spec/plan` → `/task/start` → `/task/validate`
+**Purpose:** Add new feature to existing project
+**When to use:** Adding features to existing project
+**Auto-proceed:** Optional (ask user)
+**Error handling:** Stop on error, allow resume
+
+### Task Execution
+**Stack:** `/task/start` → `/task/validate`
+**Purpose:** Execute and validate single task
+**When to use:** Standard task execution workflow
+**Auto-proceed:** Optional (ask user)
+**Error handling:** Stop on error, allow resume
+
+### Spec Evolution
+**Stack:** `/spec/evolve` → `/spec/refine` → `/spec/plan`
+**Purpose:** Update spec as project grows
+**When to use:** Spec needs updating as project evolves
+**Auto-proceed:** Optional (ask user)
+**Error handling:** Stop on error, allow resume
+
+### Legacy Project Onboarding
+**Stack:** `/spec/audit` → `/spec/sync` → `/spec/refine`
+**Purpose:** Onboard existing codebase into SDD
+**When to use:** Working with legacy/existing codebase
+**Auto-proceed:** Optional (ask user)
+**Error handling:** Stop on error, allow resume
+
+## Stack Execution
+
+**Stack Invocation:**
+Commands can invoke stacks using:
+```markdown
+**Command Stack:** /spec/init → /spec/refine → /spec/plan
+**Auto-proceed:** [Yes | No]
+```
+
+**Execution Flow:**
+1. Execute first command in stack
+2. Wait for completion (or auto-proceed if enabled)
+3. Execute next command in stack
+4. Continue until all commands complete
+5. Stop on error (report issue, allow resume)
+
+**Error Handling:**
+- If command fails → stop stack execution
+- Report error clearly
+- Allow user to fix issue
+- Resume from failed command with same stack
+
+**Progress Tracking:**
+- Track which command is executing
+- Show progress (e.g., "Step 2 of 4")
+- Allow user to skip remaining steps
+- Allow user to cancel stack
+
+## Auto-Proceed Logic
+
+**When Auto-Proceed is Enabled:**
+- Commands execute in sequence
+- No user confirmation between steps
+- Stop only on errors
+- Report completion at end
+
+**When Auto-Proceed is Disabled:**
+- Ask user before each step
+- Wait for confirmation
+- Allow user to skip steps
+- Allow user to cancel stack
+
+## Stack Definition Format
+
+Stacks are defined in this file with:
+- Stack name
+- Command sequence
+- Purpose
+- When to use
+- Auto-proceed default
+- Error handling strategy
+
+## Usage in Commands
+
+Commands can:
+- Invoke stacks at the end (suggest next steps)
+- Invoke stacks at the beginning (pre-workflow)
+- Invoke stacks conditionally (based on detection results)
+- Allow user to choose stack or single command
+

package/template/.cursor/commands/_shared/deployment-detection.md

@@ -0,0 +1,294 @@
+---
+helper_id: deployment-detection
+load_when:
+  - pr_created
+  - pr_updated
+  - validation_step
+sections:
+  detection:
+    title: "Provider Detection"
+    lines: [32, 91]
+  preview:
+    title: "Preview Deployment Logic"
+    lines: [111, 194]
+  status:
+    title: "Deployment Status Checking"
+    lines: [214, 217]
+always_load: false
+---
+
+# Deployment Detection & Automation
+
+This helper provides logic for detecting deployment providers and automating preview deployments for PRs.
+
+## Purpose
+
+Automatically detect deployment providers and handle preview deployments:
+- Detect deployment provider (Vercel, Railway, Netlify, etc.)
+- Trigger preview deployments when PRs are created
+- Check deployment status
+- Add preview URLs to PR descriptions
+
+## Section: Provider Detection (Lines 13-91)
+
+### Detection Methods
+
+**Method 1: Config Files**
+- Check for provider-specific config files
+- Vercel: `vercel.json`, `.vercel/` folder
+- Railway: `railway.json`, `railway.toml`
+- Netlify: `netlify.toml`
+- AWS: `amplify.yml`, `serverless.yml`, `sam.yaml`, `appspec.yml`, `buildspec.yml`
+- GCP: `app.yaml`, `cloudbuild.yaml`
+- Azure: `azure-pipelines.yml`, `.github/workflows/azure-*.yml`
+- Docker: `Dockerfile`, `docker-compose.yml`
+- Kubernetes: `kubernetes/`, `k8s/` directories, `*.yaml` manifests
+
+**Method 2: Spec Files**
+- Read `spec/08-infrastructure.md`
+- Check "Hosting" section for provider
+- Check "CI/CD" section for deployment config
+
+**Method 3: Environment Variables**
+- Check for provider-specific env vars
+- Vercel: `VERCEL`, `VERCEL_URL`
+- Railway: `RAILWAY_ENVIRONMENT`
+- Netlify: `NETLIFY`
+
+**Method 4: Git Remote**
+- Check git remote URLs
+- `*.vercel.app` → Vercel
+- `*.railway.app` → Railway
+- `*.netlify.app` → Netlify
+- `*.amplifyapp.com` → AWS Amplify
+- `*.run.app` → GCP Cloud Run
+- `*.appspot.com` → GCP App Engine
+- `*.web.app` → Firebase Hosting
+- `*.azurewebsites.net` → Azure App Service
+- `*.azurestaticapps.net` → Azure Static Web Apps
+
+### Provider-Specific Detection
+
+#### Vercel
+
+**Detection:**
+- Check for `vercel.json` file
+- Check for `.vercel/` directory
+- Check for `VERCEL` environment variable
+- Check git remote for `vercel.app`
+
+**Preview Deployment:**
+- Vercel automatically creates preview deployments for PRs
+- Preview URL format: `https://[project-name]-[hash].vercel.app`
+- Get preview URL from Vercel API or git remote
+
+#### Railway
+
+**Detection:**
+- Check for `railway.json` file
+- Check for `railway.toml` file
+- Check for `RAILWAY_ENVIRONMENT` environment variable
+- Check git remote for `railway.app`
+
+**Preview Deployment:**
+- Railway can create preview environments for PRs
+- Requires Railway CLI or API integration
+- Preview URL from Railway dashboard or API
+
+#### Netlify
+
+**Detection:**
+- Check for `netlify.toml` file
+- Check for `netlify/` directory
+- Check for `NETLIFY` environment variable
+- Check git remote for `netlify.app`
+
+**Preview Deployment:**
+- Netlify automatically creates preview deployments for PRs
+- Preview URL format: `https://[branch-name]--[project-name].netlify.app`
+- Get preview URL from Netlify API or build logs
+
+## Section: Preview Deployment Logic (Lines 92-194)
+
+### When to Deploy
+
+**Trigger conditions:**
+1. PR created (after PR creation)
+2. PR updated (new commits pushed)
+3. Manual trigger (if user requests)
+
+**Skip conditions:**
+1. Provider not detected
+2. Preview deployment not configured
+3. Deployment already in progress
+4. User explicitly skips deployment
+
+### Deployment Process
+
+**Step 1: Detect Provider**
+1. Run provider detection
+2. If provider detected → proceed
+3. If no provider → skip deployment
+
+**Step 2: Check Deployment Status**
+1. Check if deployment already exists for PR
+2. If exists → get preview URL
+3. If not exists → trigger deployment
+
+**Step 3: Trigger Deployment**
+
+**Vercel:**
+- Vercel auto-deploys on PR creation (if connected to GitHub)
+- Get preview URL from Vercel API or wait for webhook
+- Alternative: Use Vercel CLI `vercel --prod=false`
+
+**Railway:**
+- Use Railway CLI: `railway up`
+- Or trigger via Railway API
+- Get preview URL from Railway dashboard
+
+**Netlify:**
+- Netlify auto-deploys on PR creation (if connected to GitHub)
+- Get preview URL from Netlify API
+- Alternative: Use Netlify CLI `netlify deploy --branch=<branch-name>`
+
+**AWS Amplify:**
+- Amplify auto-deploys on PR creation (if connected to GitHub)
+- Get preview URL from Amplify API or console
+- Alternative: Use Amplify CLI `amplify publish --branch=<branch-name>`
+
+**AWS Lambda (Serverless):**
+- Use Serverless Framework: `serverless deploy --stage=preview`
+- Or use AWS SAM: `sam deploy --stack-name preview-<branch>`
+- Get preview URL from API Gateway or Lambda function URL
+
+**GCP Cloud Run:**
+- Deploy to preview service: `gcloud run deploy <service>-preview --source .`
+- Get preview URL from Cloud Run service URL
+- Or use Cloud Build for automated deployment
+
+**GCP App Engine:**
+- Deploy preview version: `gcloud app deploy --version=<branch-name>`
+- Get preview URL from App Engine version URL
+
+**Firebase Hosting:**
+- Auto-deploys on PR creation (if connected to GitHub)
+- Get preview URL from Firebase Hosting API
+- Alternative: Use Firebase CLI `firebase hosting:channel:deploy <branch-name>`
+
+**Azure App Service:**
+- Deploy to staging slot: `az webapp deployment slot swap --slot staging`
+- Get preview URL from staging slot URL
+- Or use Azure CLI for preview deployment
+
+**Azure Static Web Apps:**
+- Auto-deploys on PR creation (if connected to GitHub)
+- Get preview URL from Azure Static Web Apps API
+- Preview URL format: `https://[branch-name].[app-name].azurestaticapps.net`
+
+**Docker:**
+- Build image: `docker build -t <image>:<branch-name> .`
+- Push to registry: `docker push <image>:<branch-name>`
+- Deploy to preview environment (provider-specific)
+
+**Kubernetes:**
+- Apply manifests to preview namespace: `kubectl apply -f k8s/ -n preview-<branch>`
+- Get preview URL from ingress or service
+- Or use Helm for preview deployment: `helm install preview-<branch> ./chart`
+
+**Self-Hosted:**
+- Execute custom deployment script
+- Or trigger via CI/CD pipeline
+- Get preview URL from deployment output or config
+
+**Step 4: Wait for Deployment**
+1. Poll deployment status
+2. Wait for deployment to complete (or timeout)
+3. Get preview URL when ready
+
+**Step 5: Update PR**
+1. Add preview URL to PR description
+2. Format: `### Preview\n[Preview URL](url)`
+3. Update PR via GitHub helpers
+
+## Section: Deployment Status Checking (Lines 195-217)
+
+### Vercel
+
+**Check status:**
+- Use Vercel API: `GET /v1/deployments`
+- Check deployment status: `ready`, `building`, `error`
+- Get preview URL from deployment object
+
+### Railway
+
+**Check status:**
+- Use Railway API or CLI
+- Check service status
+- Get preview URL from service URL
+
+### Netlify
+
+**Check status:**
+- Use Netlify API: `GET /api/v1/sites/[site_id]/deploys`
+- Check deploy status: `ready`, `building`, `error`
+- Get preview URL from deploy object
+
+## Integration Points
+
+### In `/task/validate`:
+
+**After PR created:**
+1. Detect deployment provider
+2. If provider detected → trigger preview deployment
+3. Wait for deployment (with timeout)
+4. Get preview URL
+5. Update PR description with preview URL
+6. Update state tracking
+
+### In GitHub Workflow:
+
+**If GitHub Actions configured:**
+- GitHub Actions can handle deployment
+- This helper can check deployment status
+- Get preview URL from GitHub Actions output or provider API
+
+## Error Handling
+
+- **Provider not detected:** Skip deployment, continue workflow
+- **Deployment fails:** Report error, continue without preview URL
+- **Deployment timeout:** Report timeout, continue workflow
+- **API unavailable:** Skip deployment, continue workflow
+- **Preview URL not available:** Continue without preview URL
+
+## Best Practices
+
+1. **Auto-detect provider:** Don't require manual configuration
+2. **Graceful degradation:** Work even if deployment unavailable
+3. **Update PR description:** Always add preview URL when available
+4. **Handle timeouts:** Don't block workflow waiting for deployment
+5. **Cache preview URLs:** Store in state file for quick access
+
+## Examples
+
+### Example 1: Vercel Auto-Deployment
+
+**Detection:** `vercel.json` found
+**Action:** Wait for Vercel auto-deployment
+**Result:** Get preview URL from Vercel API
+**Update PR:** Add preview URL to PR description
+
+### Example 2: Railway Manual Deployment
+
+**Detection:** `railway.json` found
+**Action:** Trigger deployment via Railway CLI
+**Result:** Get preview URL from Railway
+**Update PR:** Add preview URL to PR description
+
+### Example 3: No Provider Detected
+
+**Detection:** No provider config found
+**Action:** Skip deployment
+**Result:** Continue workflow without preview URL
+**Update PR:** No preview URL added
+