@mallardbay/cursor-rules 1.0.14 → 1.0.16

package/.cursor/skills/review-pr/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: review-pr
+description: Review a pull request systematically, checking code quality, functionality, security, and adherence to project standards. Use when reviewing PRs, providing code review feedback, or checking someone else's changes.
+version: 1.0.0
+tags:
+  - pr
+  - review
+  - code-quality
+  - workflow
+---
+
+# Review PR
+
+Systematically review a pull request, checking code quality, functionality, security, tests, and adherence to project standards. Provide constructive feedback and approve or request changes.
+
+## When to Use
+
+- User wants to review a pull request
+- User mentions code review, PR review, or checking someone else's changes
+- User provides a PR URL, number, or branch name
+- When asked to review code before merge
+
+## Instructions
+
+### Step 1: Get PR Information
+
+```bash
+# If PR number provided
+gh pr view <pr-number> --json number,title,body,author,headRefName,baseRefName,files,commits
+
+# If PR URL provided, extract number from URL
+# Format: github.com/{owner}/{repo}/pull/{number}
+
+# If branch name provided
+gh pr list --head <branch-name> --json number,title,url
+```
+
+**Key information to extract:**
+- PR number, title, description
+- Author and branch names
+- Changed files and commit history
+- Current review status
+
+### Step 2: Review PR Scope
+
+- [ ] PR size is reasonable (see [code-review.mdc](mdc:.cursor/rules/code-review.mdc) - max 400 lines)
+- [ ] PR description is clear and explains purpose
+- [ ] Related issues/tickets are referenced
+- [ ] Changes align with PR description
+- [ ] No unrelated changes included
+
+### Step 3: Code Quality Review
+
+Reference project standards:
+- [general-best-practices.mdc](mdc:.cursor/rules/general-best-practices.mdc) - DRY, patterns, semantic clarity, cognitive complexity
+- [code-quality.mdc](mdc:.cursor/rules/code-quality.mdc) - Structure, naming, reuse
+- [testing.mdc](mdc:.cursor/rules/testing.mdc) - Test requirements
+
+**Check for:**
+
+**Functionality & Logic**
+- [ ] Code does what it's supposed to do
+- [ ] Edge cases are handled
+- [ ] Error handling is comprehensive
+- [ ] Integration with existing code is smooth
+- [ ] No obvious bugs or logic errors
+
+**Code Quality**
+- [ ] Follows existing patterns (see [general-best-practices.mdc](mdc:.cursor/rules/general-best-practices.mdc))
+- [ ] Reuses existing logic where possible
+- [ ] Function names are semantic and clear
+- [ ] Cognitive complexity is low
+- [ ] Separation of concerns is maintained
+- [ ] No code duplication (DRY principle)
+
+**Security**
+- [ ] No obvious security vulnerabilities
+- [ ] Input validation and sanitization
+- [ ] Authentication/authorization checks
+- [ ] No sensitive data exposed
+- [ ] Dependencies are up-to-date and secure
+
+**Performance**
+- [ ] No obvious performance bottlenecks
+- [ ] Efficient algorithms and data structures
+- [ ] No unnecessary re-renders/re-computations
+- [ ] Resource cleanup (memory, connections)
+
+**Style & Consistency**
+- [ ] Follows project naming conventions
+- [ ] Consistent with codebase style
+- [ ] No commented-out code or debug statements
+- [ ] Proper formatting
+
+### Step 4: Test Coverage Review
+
+- [ ] New code has tests (see [testing.mdc](mdc:.cursor/rules/testing.mdc))
+- [ ] Tests cover happy path, error cases, edge cases
+- [ ] Test quality is good (clear, focused, maintainable)
+- [ ] No duplicate or redundant tests
+- [ ] Tests follow project patterns
+
+### Step 5: Breaking Changes Analysis
+
+Check for breaking changes that could affect clients:
+
+- [ ] API endpoints, request/response formats, or signatures changed?
+- [ ] Public functions/interfaces modified or removed?
+- [ ] Database schema changes that aren't backward compatible?
+- [ ] Behavioral changes that alter existing functionality?
+- [ ] Configuration options changed or removed?
+
+**If breaking changes found:** Flag as **Blocking** unless properly handled with version bump, deprecation notices, migration guides, and CHANGELOG entries.
+
+### Step 6: Documentation Review
+
+- [ ] Complex logic is documented
+- [ ] Function/class documentation where needed
+- [ ] README updated if needed
+- [ ] Code comments explain "why" not "what"
+
+### Step 7: Architecture & Design
+
+- [ ] Aligns with system architecture
+- [ ] Follows established design patterns
+- [ ] No unnecessary abstractions
+- [ ] Proper separation of concerns
+- [ ] Changes are maintainable
+
+### Step 8: Provide Feedback
+
+**For each issue found:**
+
+1. **Categorize feedback:**
+   - **Blocking** - Must fix before merge (bugs, security, breaking changes)
+   - **Important** - Should fix (code quality, maintainability)
+   - **Suggestion** - Nice to have (style, minor improvements)
+   - **Question** - Need clarification
+
+2. **Write constructive comments:**
+   - Be specific about the issue
+   - Explain why it matters
+   - Suggest solutions when possible
+   - Reference project standards
+   - Use positive, respectful language
+
+3. **Post comments on GitHub:**
+
+```bash
+# Post review comment on specific line
+gh pr comment <pr-number> --body "Comment text" --file <file-path> --line <line-number>
+
+# Or use API: POST /repos/{owner}/{repo}/pulls/{pull_number}/comments
+# Body: {"body": "...", "path": "file.ts", "line": 42}
+```
+
+**Comment format:**
+```markdown
+**Issue:** [Brief description]
+
+**Why:** [Why this matters - reference to standards if applicable]
+
+**Suggestion:** [How to fix or improve]
+```
+
+### Step 9: Submit Review
+
+**After reviewing:**
+
+1. **Summarize findings:**
+   - List blocking issues
+   - List important issues
+   - Note positive aspects
+
+2. **Submit review:**
+
+```bash
+# Request changes (blocking issues)
+gh pr review <pr-number> --request-changes --body "Review summary"
+
+# Approve (no blocking issues)
+gh pr review <pr-number> --approve --body "LGTM! Minor suggestions in comments."
+
+# Comment only (suggestions but not blocking)
+gh pr review <pr-number> --comment --body "Review summary"
+```
+
+**API endpoint:** `POST /repos/{owner}/{repo}/pulls/{pull_number}/reviews`
+```json
+{
+  "body": "Review summary",
+  "event": "APPROVE" | "REQUEST_CHANGES" | "COMMENT",
+  "comments": [
+    {
+      "path": "file.ts",
+      "line": 42,
+      "body": "Comment text"
+    }
+  ]
+}
+```
+
+### Step 10: Follow Up
+
+- [ ] Respond to author's questions
+- [ ] Re-review after changes are made
+- [ ] Update review status if issues are resolved
+
+## Review Checklist Summary
+
+**Must Check:**
+- ✅ Functionality works correctly
+- ✅ Security vulnerabilities
+- ✅ Test coverage adequate
+- ✅ Follows project patterns
+- ✅ PR size reasonable
+- ✅ Breaking changes identified and properly handled
+
+**Should Check:**
+- Code quality and maintainability
+- Performance considerations
+- Documentation completeness
+- Error handling
+
+**Nice to Check:**
+- Code style consistency
+- Minor optimizations
+- Documentation improvements
+
+## Output Format
+
+Provide:
+
+1. **Review Summary:**
+   - Overall assessment
+   - Number of blocking/important/suggestion comments
+   - Key findings
+
+2. **Comments Posted:**
+   - List of comments with file:line references
+   - Categorization (blocking/important/suggestion)
+
+3. **Review Decision:**
+   - Approve / Request Changes / Comment
+   - Rationale
+
+4. **Positive Feedback:**
+   - What was done well
+   - Appreciate good patterns or solutions
+
+## Notes
+
+- **Read every line** of changed code
+- **Understand context** before commenting
+- **Be constructive** - focus on code, not person
+- **Ask questions** rather than making demands
+- **Reference standards** from project rules
+- **Test locally** if possible for complex changes
+- **Focus on scope** - don't request out-of-scope changes
+- Use the ask questions tool if PR context is unclear
+
+## References
+
+- [code-review.mdc](mdc:.cursor/rules/code-review.mdc) - PR review standards
+- [general-best-practices.mdc](mdc:.cursor/rules/general-best-practices.mdc) - Code quality standards
+- [testing.mdc](mdc:.cursor/rules/testing.mdc) - Test requirements
+- [code-quality.mdc](mdc:.cursor/rules/code-quality.mdc) - Code structure standards

package/README.md

@@ -4,10 +4,12 @@ A tool for managing Cursor IDE rules and Claude Code configuration across differ
 
 ## Overview
 
-This project provides a structured way to manage AI agent rules for different development environments while maintaining a shared base configuration. It generates:
+This project provides a structured way to manage AI agent rules and skills for different development environments while maintaining a shared base configuration. It generates:
 
-- **Cursor IDE**: `.cursor/rules/*.mdc` files
-- **Claude Code**: A combined `CLAUDE.md` file at project root
+- **Cursor IDE**: `.cursor/rules/*.mdc` files and `.cursor/skills/*/SKILL.md` files
+- **Claude Code**: A combined `CLAUDE.md` file and `.claude/skills/*/SKILL.md` files
+- **Codex**: `.codex/skills/*/SKILL.md` files
+- **Cross-platform Skills**: Skills are automatically copied to all three platform directories for maximum compatibility
 
 It supports three main environment types:
 
@@ -50,12 +52,13 @@ npx @mallardbay/cursor-rules backend
 
 ## Project Structure
 
-The rules are organized in the following directory structure:
+The rules and skills are organized in the following directory structure:
 
 ```
 .cursor/
 ├── shared/
-│   └── rules/     # Shared base rules
+│   ├── rules/     # Shared base rules
+│   └── skills/    # Shared skills (installable workflows)
 ├── frontend/
 │   └── rules/     # Frontend-specific rules
 ├── frontend-lib/
@@ -78,15 +81,40 @@ Running the setup script generates:
 ```
 your-project/
 ├── .cursor/
-│   └── rules/          # Cursor IDE rules (*.mdc files)
-│       ├── code-quality.mdc
-│       ├── testing.mdc
-│       └── ...
+│   ├── rules/          # Cursor IDE rules (*.mdc files)
+│   │   ├── code-quality.mdc
+│   │   ├── testing.mdc
+│   │   └── ...
+│   └── skills/         # Cursor Skills (installable workflows)
+│       ├── prep-for-pr/
+│       │   └── SKILL.md
+│       ├── review-pr/
+│       │   └── SKILL.md
+│       └── address-pr-feedback/
+│           └── SKILL.md
+├── .claude/
+│   └── skills/         # Claude Code Skills (same skills)
+│       ├── prep-for-pr/
+│       │   └── SKILL.md
+│       ├── review-pr/
+│       │   └── SKILL.md
+│       └── address-pr-feedback/
+│           └── SKILL.md
+├── .codex/
+│   └── skills/         # Codex Skills (same skills)
+│       ├── prep-for-pr/
+│       │   └── SKILL.md
+│       ├── review-pr/
+│       │   └── SKILL.md
+│       └── address-pr-feedback/
+│           └── SKILL.md
 └── CLAUDE.md           # Claude Code configuration (combined rules)
 ```
 
 The `CLAUDE.md` file combines all applicable rules into a single file, with YAML frontmatter stripped for compatibility with Claude Code.
 
+Skills are automatically discovered by Cursor, Claude Code, and Codex, and can be invoked with `/skill-name` in chat. The setup script copies skills to all three platform directories for cross-platform compatibility.
+
 ## Development
 
 ### Adding New Rules
@@ -94,14 +122,37 @@ The `CLAUDE.md` file combines all applicable rules into a single file, with YAML
 1. Create `.mdc` files in the appropriate rules directory
 2. Rules will be automatically copied to `.cursor/rules/` when running the setup script
 
+### Adding New Skills
+
+1. Create a skill directory in `.cursor/shared/skills/your-skill-name/`
+2. Add a `SKILL.md` file with YAML frontmatter and instructions
+3. Optionally add `scripts/`, `references/`, or `assets/` directories
+4. Skills will be automatically copied to `.cursor/skills/`, `.claude/skills/`, and `.codex/skills/` when running the setup script for cross-platform compatibility
+5. See [SKILLS.md](SKILLS.md) for detailed documentation
+
 ### Directory Structure
 
 -   `bin/setup-cursor.sh`: Main setup script
 -   `.cursor/shared/rules/`: Shared base rules
+-   `.cursor/shared/skills/`: Shared skills (installable workflows)
 -   `.cursor/frontend/rules/`: Frontend-specific rules
 -   `.cursor/frontend-lib/rules/`: Frontend library-specific rules
 -   `.cursor/backend/rules/`: Backend-specific rules
 
+## Skills
+
+This repository includes example Cursor Skills that can be installed:
+
+- **prep-for-pr**: Prepare your branch for a PR by checking and fixing code quality issues
+- **review-pr**: Systematically review someone else's PR with code quality, security, and standards checks
+- **address-pr-feedback**: Find PR by branch, review feedback, create plan, implement fixes, and resolve GitHub conversations
+
+See [SKILLS.md](SKILLS.md) for complete documentation on:
+- Creating new skills
+- Installing skills from GitHub
+- Skill structure and format
+- Best practices
+
 ## License
 
 [Add your license information here]

package/bin/setup-cursor.sh

@@ -12,27 +12,29 @@ if [ -z "$ENV_TYPE" ]; then
   exit 1
 fi
 
-# Get the real path of the script (portable across Mac/Linux, follows symlinks)
-resolve_path() {
-  local target="$1"
-  # Follow symlinks until we get to the real file
-  while [ -L "$target" ]; do
-    local link_dir="$(cd "$(dirname "$target")" && pwd -P)"
-    target="$(readlink "$target")"
-    # Handle relative symlinks
-    [[ "$target" != /* ]] && target="$link_dir/$target"
-  done
-  cd "$(dirname "$target")" && echo "$(pwd -P)/$(basename "$target")"
+# Ensure we're in the project directory (where npx runs from)
+PROJECT_DIR="$(pwd)"
+echo "Setting up in project directory: $PROJECT_DIR"
+
+# Get the real path of the script (portable across Mac/Linux)
+get_real_path() {
+  local path="$1"
+  cd "$(dirname "$path")" && echo "$(pwd -P)/$(basename "$path")"
 }
-SCRIPT_PATH="$(resolve_path "$0")"
+SCRIPT_PATH="$(get_real_path "$0")"
 SRC_DIR="$(cd "$(dirname "$SCRIPT_PATH")/.." && pwd -P)"
 
 SHARED_DIR="$SRC_DIR/.cursor/shared/rules"
 FRONTEND_DIR="$SRC_DIR/.cursor/frontend/rules"
 FRONTEND_LIB_DIR="$SRC_DIR/.cursor/frontend-lib/rules"
 BACKEND_DIR="$SRC_DIR/.cursor/backend/rules"
+SHARED_SKILLS_DIR="$SRC_DIR/.cursor/shared/skills"
 
-mkdir -p .cursor/rules
+# Create directories in project root
+mkdir -p "$PROJECT_DIR/.cursor/rules"
+mkdir -p "$PROJECT_DIR/.cursor/skills"
+mkdir -p "$PROJECT_DIR/.claude/skills"
+mkdir -p "$PROJECT_DIR/.codex/skills"
 
 # Temporary file to collect CLAUDE.md content
 CLAUDE_MD_TEMP=$(mktemp)
@@ -42,7 +44,53 @@ copy_rules() {
   local DIR="$1"
   if [ -d "$DIR" ]; then
     echo "Copying rules from: $DIR"
-    cp "$DIR"/*.mdc .cursor/rules/ 2>/dev/null || true
+    cp "$DIR"/*.mdc "$PROJECT_DIR/.cursor/rules/" 2>/dev/null || true
+  fi
+}
+
+copy_skills() {
+  local DIR="$1"
+  echo "DEBUG: Checking skills directory: $DIR"
+  if [ -d "$DIR" ]; then
+    echo "Copying skills from: $DIR"
+    # Ensure target directories exist
+    mkdir -p "$PROJECT_DIR/.cursor/skills" "$PROJECT_DIR/.claude/skills" "$PROJECT_DIR/.codex/skills"
+    # Copy each skill directory to all three locations for cross-platform compatibility
+    local skill_count=0
+    for skill_dir in "$DIR"/*; do
+      if [ -d "$skill_dir" ] && [ -f "$skill_dir/SKILL.md" ]; then
+        skill_name=$(basename "$skill_dir")
+        echo "  - Copying skill: $skill_name"
+        skill_count=$((skill_count + 1))
+        # Copy to Cursor, Claude, and Codex skill directories
+        if cp -r "$skill_dir" "$PROJECT_DIR/.cursor/skills/"; then
+          echo "    ✓ Copied to .cursor/skills/"
+        else
+          echo "    ✗ Failed to copy to .cursor/skills/"
+        fi
+        if cp -r "$skill_dir" "$PROJECT_DIR/.claude/skills/"; then
+          echo "    ✓ Copied to .claude/skills/"
+        else
+          echo "    ✗ Failed to copy to .claude/skills/"
+        fi
+        if cp -r "$skill_dir" "$PROJECT_DIR/.codex/skills/"; then
+          echo "    ✓ Copied to .codex/skills/"
+        else
+          echo "    ✗ Failed to copy to .codex/skills/"
+        fi
+      else
+        echo "  - Skipping (not a valid skill): $(basename "$skill_dir")"
+      fi
+    done
+    if [ $skill_count -eq 0 ]; then
+      echo "  Warning: No skills found in $DIR"
+      echo "  Contents of $DIR:"
+      ls -la "$DIR" || echo "    (directory listing failed)"
+    fi
+  else
+    echo "Warning: Skills directory not found: $DIR"
+    echo "DEBUG: SRC_DIR=$SRC_DIR"
+    echo "DEBUG: SHARED_SKILLS_DIR=$SHARED_SKILLS_DIR"
   fi
 }
 
@@ -73,6 +121,11 @@ append_to_claude_md() {
 copy_rules "$SHARED_DIR"
 append_to_claude_md "$SHARED_DIR"
 
+# Always include shared skills
+echo "DEBUG: SRC_DIR=$SRC_DIR"
+echo "DEBUG: SHARED_SKILLS_DIR=$SHARED_SKILLS_DIR"
+copy_skills "$SHARED_SKILLS_DIR"
+
 # Inheritance handling
 case "$ENV_TYPE" in
   frontend)
@@ -96,8 +149,18 @@ case "$ENV_TYPE" in
 esac
 
 # Generate CLAUDE.md
-mv "$CLAUDE_MD_TEMP" CLAUDE.md
+mv "$CLAUDE_MD_TEMP" "$PROJECT_DIR/CLAUDE.md"
 trap - EXIT
 echo "CLAUDE.md generated for Claude Code"
 
-echo "Setup complete for '$ENV_TYPE' (Cursor + Claude)"
+if [ -d "$PROJECT_DIR/.cursor/skills" ] && [ "$(ls -A "$PROJECT_DIR/.cursor/skills" 2>/dev/null)" ]; then
+  echo "Skills installed in:"
+  echo "  - $PROJECT_DIR/.cursor/skills/ (Cursor)"
+  echo "  - $PROJECT_DIR/.claude/skills/ (Claude Code)"
+  echo "  - $PROJECT_DIR/.codex/skills/ (Codex)"
+  echo ""
+  echo "Installed skills:"
+  ls -1 "$PROJECT_DIR/.cursor/skills/" | sed 's/^/    - /'
+fi
+
+echo "Setup complete for '$ENV_TYPE' (Cursor + Claude + Codex)"

package/package.json

@@ -1,12 +1,8 @@
 {
     "name": "@mallardbay/cursor-rules",
-    "version": "1.0.14",
+    "version": "1.0.16",
     "description": "Mallard Bay shared cursor rules",
     "main": "bin/setup-cursor.sh",
-    "scripts": {
-        "test": "bin/test-setup.sh",
-        "prepublishOnly": "bin/test-setup.sh"
-    },
     "repository": "git@github.com:mallardbay/cursor-rules.git",
     "author": "mfrr1118 <mfrr@me.com>",
     "license": "MIT",

package/bin/test-setup.sh

@@ -1,108 +0,0 @@
-#!/usr/bin/env bash
-# test-setup.sh — Validates setup-cursor.sh works correctly before publishing
-set -e
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-TEST_DIR=$(mktemp -d)
-trap 'rm -rf "$TEST_DIR"' EXIT
-
-echo "Testing cursor-rules setup script..."
-echo "Test directory: $TEST_DIR"
-echo ""
-
-# Track test results
-PASSED=0
-FAILED=0
-
-# Safe increment functions (avoid set -e issues with ((0)))
-pass() { PASSED=$((PASSED + 1)); }
-fail() { FAILED=$((FAILED + 1)); }
-
-run_test() {
-  local env_type="$1"
-  local expected_patterns=("${@:2}")
-
-  echo "Testing env-type: $env_type"
-
-  cd "$TEST_DIR"
-  rm -rf .cursor CLAUDE.md 2>/dev/null || true
-
-  # Run the setup script
-  if ! "$SCRIPT_DIR/setup-cursor.sh" "$env_type" > /dev/null 2>&1; then
-    echo "  ❌ FAILED: Script exited with error"
-    fail
-    return
-  fi
-
-  # Check CLAUDE.md exists and has content
-  if [ ! -f "CLAUDE.md" ]; then
-    echo "  ❌ FAILED: CLAUDE.md was not created"
-    fail
-    return
-  fi
-
-  local line_count=$(wc -l < CLAUDE.md | tr -d ' ')
-  if [ "$line_count" -lt 50 ]; then
-    echo "  ❌ FAILED: CLAUDE.md has only $line_count lines (expected 50+)"
-    fail
-    return
-  fi
-
-  # Check .cursor/rules directory was created
-  if [ ! -d ".cursor/rules" ]; then
-    echo "  ❌ FAILED: .cursor/rules directory was not created"
-    fail
-    return
-  fi
-
-  # Check for expected content patterns
-  for pattern in "${expected_patterns[@]}"; do
-    if ! grep -q "$pattern" CLAUDE.md; then
-      echo "  ❌ FAILED: Missing expected content: $pattern"
-      fail
-      return
-    fi
-  done
-
-  echo "  ✓ PASSED ($line_count lines in CLAUDE.md)"
-  pass
-}
-
-# Test each environment type with expected content patterns
-run_test "frontend" "TypeScript Development Standards" "UI Development Standards" "Mallard Bay"
-run_test "backend" "TypeScript Development Standards" "Backend Development Rules" "Mallard Bay"
-run_test "frontend-lib" "TypeScript Development Standards" "UI Development Standards" "Mallard Bay"
-
-# Test via symlink (simulates npx behavior)
-echo "Testing via symlink (simulates npx)..."
-SYMLINK_DIR=$(mktemp -d)
-ln -s "$SCRIPT_DIR/setup-cursor.sh" "$SYMLINK_DIR/cursor-rules"
-cd "$TEST_DIR"
-rm -rf .cursor CLAUDE.md 2>/dev/null || true
-
-if ! "$SYMLINK_DIR/cursor-rules" frontend > /dev/null 2>&1; then
-  echo "  ❌ FAILED: Symlink execution failed"
-  fail
-else
-  symlink_lines=$(wc -l < CLAUDE.md | tr -d ' ')
-  if [ "$symlink_lines" -lt 50 ]; then
-    echo "  ❌ FAILED: Symlink test - CLAUDE.md has only $symlink_lines lines"
-    fail
-  else
-    echo "  ✓ PASSED: Symlink test ($symlink_lines lines)"
-    pass
-  fi
-fi
-rm -rf "$SYMLINK_DIR"
-
-echo ""
-echo "========================================"
-echo "Results: $PASSED passed, $FAILED failed"
-echo "========================================"
-
-if [ $FAILED -gt 0 ]; then
-  echo "❌ Tests failed!"
-  exit 1
-fi
-
-echo "✓ All tests passed!"