@eskoubar95/spec 0.1.0 → 0.1.2

package/template/.cursor/commands/_shared/git-workflow.md

@@ -0,0 +1,288 @@
+---
+helper_id: git-workflow
+load_when:
+  - task_start
+  - task_validate
+  - commit_needed
+  - pr_creation_needed
+sections:
+  commit_generation:
+    title: "Commit Message Generation"
+    lines: [13, 80]
+  state_detection:
+    title: "State Detection"
+    lines: [81, 150]
+  next_steps:
+    title: "Next Step Logic"
+    lines: [151, 220]
+always_load: false
+---
+
+# Git Workflow Automation
+
+This helper provides logic for automatic commit message generation, state detection, and next step determination for Git/GitHub workflows.
+
+## Purpose
+
+Automate Git workflow operations:
+- Generate meaningful commit messages based on changes
+- Detect current state (branch, PR, deployment)
+- Determine next steps automatically
+- Track state transitions
+
+## Commit Message Generation
+
+### Format
+
+**Standard format:** `[task-id] type: description`
+
+**Examples:**
+- `[T1.2] feat: add user authentication`
+- `[T2.3] fix: resolve database connection issue`
+- `[T3.1] refactor: extract payment logic to service`
+- `[T4.5] docs: update API documentation`
+
+### Commit Types
+
+**feat:** New feature
+- New functionality added
+- New components, pages, features
+- New API endpoints
+
+**fix:** Bug fix
+- Fixes existing bugs
+- Resolves errors or issues
+- Corrects broken functionality
+
+**refactor:** Code refactoring
+- Code restructuring without changing functionality
+- Improving code organization
+- Extracting logic to services/utilities
+
+**docs:** Documentation
+- Documentation updates
+- README changes
+- Code comments
+
+**test:** Tests
+- Adding or updating tests
+- Test infrastructure changes
+
+**chore:** Maintenance
+- Dependency updates
+- Build configuration changes
+- Tooling changes
+
+**style:** Code style
+- Formatting changes
+- Linting fixes
+- Code style improvements
+
+### Type Detection Logic
+
+**Analyze git diff to determine type:**
+
+1. **Check file patterns:**
+   - `*.test.ts`, `*.spec.ts` → `test`
+   - `*.md`, `README*`, `docs/*` → `docs`
+   - `package.json`, `*.config.*` → `chore`
+
+2. **Check diff content:**
+   - New files with `export function`, `export class` → `feat`
+   - Changes to error handling, try-catch → `fix`
+   - Large structural changes → `refactor`
+   - Formatting-only changes → `style`
+
+3. **Check commit context:**
+   - If task description mentions "fix" or "bug" → `fix`
+   - If task description mentions "refactor" → `refactor`
+   - If task description mentions "add" or "implement" → `feat`
+
+### Description Generation
+
+**From task spec:**
+- Use task description as base
+- Extract key action: "Add user authentication" → "add user authentication"
+- Keep concise (max 72 characters for first line)
+
+**From git diff:**
+- Summarize changed files
+- Identify main change: "Modified 3 files: added auth service, updated routes, added tests"
+- Extract key functionality added/changed
+
+**Combined:**
+- Task description + key changes
+- Format: `[task-id] type: task description (key changes)`
+
+## State Detection
+
+### State Structure
+
+**State file:** `.sdd/git-state.json`
+
+**State format:**
+```json
+{
+  "branch": {
+    "name": "task/t1.2-setup-database",
+    "exists": true,
+    "pushed": false,
+    "commits": 3,
+    "last_commit": "abc123"
+  },
+  "pr": {
+    "exists": false,
+    "number": null,
+    "url": null,
+    "status": null,
+    "merged": false
+  },
+  "deployment": {
+    "provider": null,
+    "preview_url": null,
+    "status": null
+  },
+  "validated": false,
+  "last_updated": "2026-01-07T12:00:00Z"
+}
+```
+
+### Branch State Detection
+
+**Check branch status:**
+1. Get current branch: `git branch --show-current`
+2. Check if branch exists: `git rev-parse --verify <branch-name>`
+3. Check if pushed: `git ls-remote --heads origin <branch-name>`
+4. Count commits: `git rev-list --count main..<branch-name>`
+5. Get last commit: `git rev-parse HEAD`
+
+### PR State Detection
+
+**Priority 1: GitHub MCP**
+- Use `mcp_github_list_pull_requests` to find PR for branch
+- Check if PR exists and get PR number/URL
+
+**Priority 2: GitHub CLI**
+- Use `gh pr list --head <branch-name> --json number,url,state`
+- Parse JSON output for PR info
+
+**Priority 3: Local Mode**
+- Check state file for cached PR info
+- If not found → assume no PR exists
+
+### Deployment State Detection
+
+**Check deployment provider:**
+- Use deployment detection helper (see `deployment-detection.md`)
+- Check provider-specific status
+- Get preview URL if available
+
+## Next Step Detection
+
+### Decision Logic
+
+**Based on current state, determine next action:**
+
+1. **Branch created, no commits:**
+   - Next step: "Start implementing task"
+   - State: `{branch: exists, commits: 0, pr: null}`
+
+2. **Commits made, not validated:**
+   - Next step: "Run validation (/task/validate)"
+   - State: `{branch: exists, commits: N, pr: null, validated: false}`
+
+3. **Validated, no PR:**
+   - Next step: "Create PR"
+   - State: `{branch: exists, commits: N, pr: null, validated: true}`
+
+4. **PR created, not pushed:**
+   - Next step: "Push branch to remote"
+   - State: `{branch: exists, pushed: false, pr: null}`
+
+5. **PR exists, not deployed:**
+   - Next step: "Deploy to preview (if available)"
+   - State: `{branch: exists, pr: {exists: true}, deployed: false}`
+
+6. **PR merged:**
+   - Next step: "Cleanup branch"
+   - State: `{pr: {merged: true}}`
+
+### State Transitions
+
+**Track transitions:**
+1. Branch created → Initialize state
+2. First commit → Update commit count
+3. Validation passed → Set validated: true
+4. PR created → Update PR info
+5. Deployment triggered → Update deployment info
+6. PR merged → Update merged status
+7. Branch deleted → Mark branch as deleted
+
+## Integration Points
+
+### In `/task/start`:
+
+**After branch creation:**
+1. Initialize state tracking
+2. Set state: `{branch: {exists: true, commits: 0}, pr: null, validated: false}`
+3. Store in `.sdd/git-state.json`
+
+### In `/task/validate`:
+
+**Before validation:**
+1. Read current state
+2. Check if branch exists and has commits
+3. If no commits → suggest committing changes first
+
+**After validation:**
+1. Update state: `validated: true`
+2. Determine next step based on state
+3. If validated and no PR → suggest creating PR
+4. Update state file
+
+### When Committing:
+
+**Generate commit message:**
+1. Analyze git diff
+2. Determine commit type
+3. Generate description from task/changes
+4. Format: `[task-id] type: description`
+5. Use generated message for commit
+
+## Error Handling
+
+- **Git operations fail:** Report error, continue without state update
+- **State file not writable:** Continue without state tracking (degraded mode)
+- **PR detection fails:** Assume no PR exists, continue workflow
+- **Deployment detection fails:** Skip deployment, continue workflow
+
+## Best Practices
+
+1. **Always check state before actions:** Avoid duplicate operations
+2. **Update state after each transition:** Keep state file current
+3. **Generate meaningful messages:** Commit messages should be clear and descriptive
+4. **Graceful degradation:** Work even if state tracking unavailable
+5. **Auto-detect everything:** Minimize manual state management
+
+## Examples
+
+### Example 1: First Commit
+
+**State before:** `{branch: exists, commits: 0}`
+**Changes:** Added `src/auth/service.ts`
+**Generated message:** `[T1.2] feat: add user authentication service`
+**State after:** `{branch: exists, commits: 1}`
+
+### Example 2: Bug Fix
+
+**State before:** `{branch: exists, commits: 2, validated: false}`
+**Changes:** Fixed database connection error
+**Generated message:** `[T2.3] fix: resolve database connection timeout`
+**State after:** `{branch: exists, commits: 3, validated: false}`
+
+### Example 3: Ready for PR
+
+**State:** `{branch: exists, commits: 3, validated: true, pr: null}`
+**Next step:** "Create PR"
+**Action:** Generate PR description and create PR
+

package/template/.cursor/commands/_shared/github-helpers.md

@@ -0,0 +1,337 @@
+---
+helper_id: github-helpers
+load_when:
+  - pr_exists
+  - github_operation_needed
+  - coderabbit_integration
+sections:
+  detection:
+    title: "GitHub Integration Detection"
+    lines: [1, 50]
+  pr_comments:
+    title: "Read PR Conversations"
+    lines: [51, 100]
+  resolve:
+    title: "Resolve Conversations"
+    lines: [101, 150]
+always_load: false
+---
+
+# GitHub Helpers
+
+This helper provides logic for GitHub PR conversation resolution and argumentation logging, with fallback support for GitHub CLI and local mode.
+
+## Purpose
+
+Handle GitHub PR operations with fallback strategy:
+- Detect GitHub integration availability (MCP → CLI → Local)
+- Read PR conversations
+- Resolve conversations
+- Track resolved issues
+- Log argumentation when issues shouldn't be resolved
+
+## GitHub Integration Detection
+
+### Detection Process
+
+**Step 1: Check GitHub MCP**
+1. Try to call GitHub MCP function (e.g., `mcp_github_get_pull_request_comments`)
+2. If function available → MCP is available
+3. If function not available → proceed to Step 2
+
+**Step 2: Check GitHub CLI**
+1. Check if `gh` is installed: `gh --version`
+2. If installed → CLI is available
+3. If not installed → proceed to Step 3
+
+**Step 3: Local Mode**
+1. If both MCP and CLI unavailable → use local mode
+2. Log operations to `work/backlog/tasks.local.md`
+
+### Integration Priority
+
+**Priority 1: GitHub MCP**
+- Use MCP functions when available
+- Most reliable and feature-rich
+- Direct API access
+
+**Priority 2: GitHub CLI**
+- Use `gh` commands when MCP unavailable
+- Requires CLI installation
+- Parse CLI output
+
+**Priority 3: Local Mode**
+- Log to local files when both unavailable
+- No GitHub integration, but workflow continues
+
+## Reading PR Conversations
+
+### Via GitHub MCP
+
+**Function:** `mcp_github_get_pull_request_comments`
+
+**Usage:**
+- Get PR number from current branch or user input
+- Call MCP function with PR number
+- Parse returned comments
+
+**Example:**
+```typescript
+// Pseudo-code
+const comments = await mcp_github_get_pull_request_comments({
+  owner: "username",
+  repo: "repo-name",
+  pull_number: 123
+});
+```
+
+### Via GitHub CLI
+
+**Command:** `gh pr view --comments <pr-number>`
+
+**Usage:**
+1. Get PR number from current branch: `gh pr view --json number`
+2. Get comments: `gh pr view <pr-number> --comments`
+3. Parse JSON output for comments
+
+**Example:**
+```bash
+# Get PR number from current branch
+PR_NUMBER=$(gh pr view --json number -q .number)
+
+# Get comments
+gh pr view $PR_NUMBER --comments --json comments
+```
+
+### Via Local Mode
+
+**Fallback:**
+- If both MCP and CLI unavailable
+- Log to `work/backlog/tasks.local.md`
+- Format: "CodeRabbit comment on PR #X: [comment text]"
+
+## Resolving Conversations
+
+### Via GitHub MCP
+
+**If MCP has resolve function:**
+- Use MCP function to resolve conversation
+- Mark conversation as resolved with comment
+
+**If MCP doesn't have resolve function:**
+- Use review comments to mark as resolved
+- Add comment: "Issue resolved in code"
+
+### Via GitHub CLI
+
+**Command:** `gh pr comment <pr-number> --body "<comment>"`
+
+**Usage:**
+1. Add comment indicating resolution
+2. Use review comments if available: `gh pr review --comment`
+
+**Example:**
+```bash
+# Add resolution comment
+gh pr comment $PR_NUMBER --body "Issue resolved in code. Changes applied."
+
+# Or use review comment
+gh pr review $PR_NUMBER --comment --body "Issue resolved"
+```
+
+### Via Local Mode
+
+**Fallback:**
+- Log resolution to `work/backlog/tasks.local.md`
+- Format: "Resolved CodeRabbit comment on PR #X: [comment text]"
+- Include timestamp and resolution reason
+
+## Tracking Resolved Issues
+
+### Purpose
+
+Avoid duplicate resolution attempts and track what's been resolved.
+
+### Tracking Method
+
+**Local tracking file:** `.sdd/github-resolved-issues.json`
+
+**Structure:**
+```json
+{
+  "resolved": [
+    {
+      "pr_number": 123,
+      "comment_id": "abc123",
+      "resolved_at": "2026-01-07T12:00:00Z",
+      "resolved_by": "system",
+      "resolution_reason": "Issue fixed in code"
+    }
+  ]
+}
+```
+
+### Check Before Resolution
+
+1. Read tracking file
+2. Check if comment already resolved
+3. If already resolved → skip
+4. If not resolved → proceed with resolution
+
+### Update After Resolution
+
+1. Add entry to tracking file
+2. Include PR number, comment ID, timestamp
+3. Save tracking file
+
+## Argumentation Logging
+
+### When Issue Shouldn't Be Resolved
+
+**Provide argumentation:**
+- Explain why issue won't be resolved
+- Reference project patterns or decisions
+- Include context and reasoning
+
+### Logging Methods
+
+**Priority 1: Linear Issue**
+- If Linear available → create issue or add comment
+- Include argumentation and CodeRabbit comment reference
+
+**Priority 2: GitHub Issue**
+- If GitHub available → create issue or add comment
+- Include argumentation and PR reference
+
+**Priority 3: Local Mode**
+- Log to `work/backlog/tasks.local.md`
+- Format: "CodeRabbit issue deferred: [reason]"
+
+### Argumentation Format
+
+**Structure:**
+- **Issue:** Brief description
+- **CodeRabbit suggestion:** What was suggested
+- **Decision:** Why not resolving
+- **Reasoning:** Detailed explanation
+- **Reference:** Project patterns, decisions, or context
+
+**Example:**
+```
+Issue: CodeRabbit suggests using Map instead of Object
+CodeRabbit suggestion: "Consider using Map for better performance"
+Decision: Deferring this optimization
+Reasoning: Current Object usage is sufficient for this use case (small dataset, infrequent access). Performance gain would be minimal and not worth the refactoring effort at this time.
+Reference: spec/05-decisions.md - Performance optimization guidelines
+```
+
+## GitHub CLI Commands Reference
+
+### PR Operations
+
+**View PR:**
+```bash
+gh pr view <pr-number>
+gh pr view --json number,title,comments
+```
+
+**Get PR comments:**
+```bash
+gh pr view <pr-number> --comments
+gh pr view <pr-number> --comments --json comments
+```
+
+**Add PR comment:**
+```bash
+gh pr comment <pr-number> --body "<comment text>"
+```
+
+**Create PR review:**
+```bash
+gh pr review <pr-number> --approve
+gh pr review <pr-number> --request-changes --body "<comment>"
+gh pr review <pr-number> --comment --body "<comment>"
+```
+
+### Issue Operations
+
+**Create issue:**
+```bash
+gh issue create --title "<title>" --body "<body>"
+```
+
+**Add issue comment:**
+```bash
+gh issue comment <issue-number> --body "<comment>"
+```
+
+**List issues:**
+```bash
+gh issue list
+gh issue list --json number,title,state
+```
+
+## Integration Points
+
+### In `/task/validate`:
+
+**After validation:**
+1. Check if PR exists (from current branch)
+2. If PR exists → read conversations via helpers
+3. For each CodeRabbit comment:
+   - Check if resolved (via tracking)
+   - If resolved → skip
+   - If not resolved → check if issue fixed in code
+   - If fixed → resolve conversation
+   - If not fixed → evaluate and take action
+
+### In `/tools/refactor`:
+
+**After refactoring:**
+1. Check if PR exists
+2. If PR exists → read conversations
+3. For refactoring-related comments:
+   - Check if refactoring applied
+   - If applied → resolve conversation
+   - If not applied → provide argumentation
+
+## Error Handling
+
+- **GitHub MCP not available:** Try GitHub CLI, then local mode
+- **GitHub CLI not available:** Use local mode
+- **PR not found:** Skip PR integration, continue workflow
+- **Comment parsing fails:** Log error, continue with next comment
+- **Resolution fails:** Log error, continue workflow
+
+## Best Practices
+
+1. **Always check tracking:** Avoid duplicate resolution attempts
+2. **Provide clear argumentation:** When deferring issues, explain why
+3. **Don't block workflow:** If GitHub integration fails, continue without it
+4. **Log operations:** Track what's been resolved for future reference
+5. **Respect user decisions:** If user explicitly ignores issue, don't re-raise
+
+## Examples
+
+### Example 1: Resolve via MCP
+
+1. Detect MCP available
+2. Get PR comments via MCP
+3. Resolve conversation via MCP
+4. Update tracking file
+
+### Example 2: Resolve via CLI
+
+1. Detect MCP not available
+2. Check CLI available
+3. Get PR comments via CLI
+4. Add resolution comment via CLI
+5. Update tracking file
+
+### Example 3: Local Mode Fallback
+
+1. Detect MCP not available
+2. Detect CLI not available
+3. Log to `work/backlog/tasks.local.md`
+4. Continue workflow
+