@mallardbay/cursor-rules 1.0.18 → 1.0.20

package/.cursor/shared/rules/general-best-practices.mdc

@@ -69,6 +69,12 @@ These principles apply to all code changes and should guide every implementation
 ### Testing and Linting
 - **Lint and test files related to your changes** before completing work
 - Run linters on modified files and fix issues
+  - Use `yarn lint:quiet` for quick iterations
+  - Use `yarn lint:quiet:slow` for deeper checks but slower when wrapping up
+- **Never disable eslint rules** to make lint errors go away—fix the underlying issues instead
+  - Do not add `eslint-disable` comments unless there's a legitimate, documented reason
+  - Do not modify eslint config files to disable rules that are flagging real problems
+  - If a rule seems incorrect, investigate why it exists and fix the code properly
 - Run tests for affected modules, not the entire test suite unnecessarily
 - For large changes: **use test sharding**—split tests across multiple runs
 - **Do not run all tests in parallel** when dealing with many changes
@@ -113,6 +119,8 @@ These principles apply to all code changes and should guide every implementation
 1. Make **small, incremental changes**
 2. **Test as you go**—verify each change works before moving on
 3. **Lint frequently**—don't accumulate lint errors
+   - Use `yarn lint:quiet` for quick iterations
+   - Use `yarn lint:quiet:slow` for deeper checks when wrapping up
 4. **Follow existing patterns**—don't reinvent the wheel
 5. **Use semantic names**—code should be self-documenting
 6. **Keep functions focused**—one responsibility per function
@@ -122,6 +130,8 @@ These principles apply to all code changes and should guide every implementation
 1. **Clean up failed attempts**—remove experimental code
 2. **Remove unused code**—imports, variables, functions
 3. **Run linters** on modified files
+   - Use `yarn lint:quiet` for quick iterations
+   - Use `yarn lint:quiet:slow` for deeper checks when wrapping up
 4. **Run relevant tests**—not the entire suite unless necessary
 5. **Verify the change works** end-to-end
 6. **Check for side effects**—ensure changes don't break unrelated code
@@ -143,6 +153,7 @@ These principles apply to all code changes and should guide every implementation
 - ❌ Functions that do multiple unrelated things
 - ❌ Leaving commented-out code or debugging statements
 - ❌ Skipping tests or linting "to save time"
+- ❌ Disabling eslint rules instead of fixing the underlying issues
 - ❌ Running entire test suite for small changes
 - ❌ Leaving experimental code after failed attempts
 - ❌ Premature optimization without profiling

package/.cursor/shared/rules/testing.mdc

@@ -41,7 +41,10 @@ Avoid e2e tests for UI. Favor unit tests.
 -   Write clear, descriptive test names
 -   Test one concept per test case
 -   Avoid test interdependence
--   Use meaningful assertions
+-   **Every test must have assertions**—tests without assertions are pointless and provide no value
+  - Use meaningful assertions that verify expected behavior
+  - Assertions validate that the code works correctly—without them, tests don't catch bugs
+  - If a test doesn't need assertions, it probably doesn't need to exist
 -   Avoid tests that will make the overall run slower
 
 ### Component Testing

package/README.md

@@ -8,7 +8,7 @@ This project provides a structured way to manage AI agent rules and skills for d
 
 - **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
+- **Codex**: A combined `AGENTS.md` file and `.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:
@@ -108,10 +108,11 @@ your-project/
 │       │   └── SKILL.md
 │       └── address-pr-feedback/
 │           └── SKILL.md
-└── CLAUDE.md           # Claude Code configuration (combined rules)
+├── CLAUDE.md           # Claude Code configuration (combined rules)
+└── AGENTS.md           # Codex IDE configuration (combined rules)
 ```
 
-The `CLAUDE.md` file combines all applicable rules into a single file, with YAML frontmatter stripped for compatibility with Claude Code.
+Both `CLAUDE.md` and `AGENTS.md` combine all applicable rules into single files, with YAML frontmatter stripped for compatibility. Each file includes header comments explaining its purpose and which tool uses it.
 
 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.
 

package/bin/setup-cursor.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # setup-cursor.sh — frontend & frontend-lib layering with shared base
-# Also generates CLAUDE.md for Claude Code
+# Also generates CLAUDE.md for Claude Code and AGENTS.md for Codex
 
 set -e
 
@@ -43,25 +43,18 @@ SRC_DIR="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 # When run via npx, if .cursor doesn't exist at SRC_DIR, find the actual package location
 if [ ! -d "$SRC_DIR/.cursor/shared/skills" ]; then
-  # Try multiple possible locations for the package
+  # Try multiple possible locations for the package (using individual checks instead of array for sh compatibility)
   # When SRC_DIR is node_modules, package is at SRC_DIR/@mallardbay/cursor-rules
-  # When SRC_DIR is _npx cache, package might be at SRC_DIR/node_modules/@mallardbay/cursor-rules
-  POSSIBLE_LOCATIONS=(
-    "$SRC_DIR/@mallardbay/cursor-rules"
-    "$SRC_DIR/node_modules/@mallardbay/cursor-rules"
-    "$(dirname "$SRC_DIR")/@mallardbay/cursor-rules"
-    "$(dirname "$(dirname "$SRC_DIR"))/@mallardbay/cursor-rules"
-  )
-  
-  for location in "${POSSIBLE_LOCATIONS[@]}"; do
-    if [ -d "$location/.cursor/shared/skills" ]; then
-      SRC_DIR="$location"
-      break
-    fi
-  done
-  
-  # If still not found, search for package.json with our name
-  if [ ! -d "$SRC_DIR/.cursor/shared/skills" ]; then
+  if [ -d "$SRC_DIR/@mallardbay/cursor-rules/.cursor/shared/skills" ]; then
+    SRC_DIR="$SRC_DIR/@mallardbay/cursor-rules"
+  elif [ -d "$SRC_DIR/node_modules/@mallardbay/cursor-rules/.cursor/shared/skills" ]; then
+    SRC_DIR="$SRC_DIR/node_modules/@mallardbay/cursor-rules"
+  elif [ -d "$(dirname "$SRC_DIR")/@mallardbay/cursor-rules/.cursor/shared/skills" ]; then
+    SRC_DIR="$(dirname "$SRC_DIR")/@mallardbay/cursor-rules"
+  elif [ -d "$(dirname "$(dirname "$SRC_DIR")")/@mallardbay/cursor-rules/.cursor/shared/skills" ]; then
+    SRC_DIR="$(dirname "$(dirname "$SRC_DIR")")/@mallardbay/cursor-rules"
+  else
+    # If still not found, search for package.json with our name
     PACKAGE_ROOT=$(find "$(dirname "$SRC_DIR")" -maxdepth 5 -type f -name "package.json" -exec grep -l '"name":\s*"@mallardbay/cursor-rules"' {} \; 2>/dev/null | head -1 | xargs dirname 2>/dev/null)
     if [ -n "$PACKAGE_ROOT" ] && [ -d "$PACKAGE_ROOT/.cursor/shared/skills" ]; then
       SRC_DIR="$PACKAGE_ROOT"
@@ -69,9 +62,6 @@ if [ ! -d "$SRC_DIR/.cursor/shared/skills" ]; then
   fi
 fi
 
-echo "DEBUG: Final SRC_DIR=$SRC_DIR"
-echo "DEBUG: Checking if .cursor/shared/skills exists: $([ -d "$SRC_DIR/.cursor/shared/skills" ] && echo "YES" || echo "NO")"
-
 SHARED_DIR="$SRC_DIR/.cursor/shared/rules"
 FRONTEND_DIR="$SRC_DIR/.cursor/frontend/rules"
 FRONTEND_LIB_DIR="$SRC_DIR/.cursor/frontend-lib/rules"
@@ -84,9 +74,33 @@ 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
+# Temporary files to collect content for both CLAUDE.md and AGENTS.md
 CLAUDE_MD_TEMP=$(mktemp)
-trap 'rm -f "$CLAUDE_MD_TEMP"' EXIT
+AGENTS_MD_TEMP=$(mktemp)
+trap 'rm -f "$CLAUDE_MD_TEMP" "$AGENTS_MD_TEMP"' EXIT
+
+# Add header comments explaining what each file is
+add_file_header() {
+  local file="$1"
+  local tool_name="$2"
+  local description="$3"
+  
+  cat > "$file" <<EOF
+<!--
+This file provides custom instructions and project context for $tool_name.
+
+$description
+
+This file is automatically generated by @mallardbay/cursor-rules. It combines
+all applicable rules from .cursor/rules/ into a single configuration file.
+
+For more information:
+- $tool_name: See official documentation
+- This package: https://github.com/mallardbay/cursor-rules
+-->
+
+EOF
+}
 
 copy_rules() {
   local DIR="$1"
@@ -98,7 +112,6 @@ copy_rules() {
 
 copy_skills() {
   local DIR="$1"
-  echo "DEBUG: Checking skills directory: $DIR"
   if [ -d "$DIR" ]; then
     echo "Copying skills from: $DIR"
     # Ensure target directories exist
@@ -137,13 +150,11 @@ copy_skills() {
     fi
   else
     echo "Warning: Skills directory not found: $DIR"
-    echo "DEBUG: SRC_DIR=$SRC_DIR"
-    echo "DEBUG: SHARED_SKILLS_DIR=$SHARED_SKILLS_DIR"
   fi
 }
 
-# Append rules to CLAUDE.md (strips YAML frontmatter)
-append_to_claude_md() {
+# Append rules to both CLAUDE.md and AGENTS.md (strips YAML frontmatter)
+append_to_md_files() {
   local DIR="$1"
   if [ -d "$DIR" ]; then
     for file in "$DIR"/*.mdc; do
@@ -152,7 +163,10 @@ append_to_claude_md() {
       echo "" >> "$CLAUDE_MD_TEMP"
       echo "---" >> "$CLAUDE_MD_TEMP"
       echo "" >> "$CLAUDE_MD_TEMP"
-      # Strip YAML frontmatter (content between --- markers) and append
+      echo "" >> "$AGENTS_MD_TEMP"
+      echo "---" >> "$AGENTS_MD_TEMP"
+      echo "" >> "$AGENTS_MD_TEMP"
+      # Strip YAML frontmatter (content between --- markers) and append to both
       awk '
         BEGIN { in_frontmatter=0; found_end=0 }
         /^---$/ && !found_end {
@@ -161,34 +175,45 @@ append_to_claude_md() {
         }
         !in_frontmatter || found_end { print }
       ' "$file" >> "$CLAUDE_MD_TEMP"
+      # Also append to AGENTS.md (same content)
+      awk '
+        BEGIN { in_frontmatter=0; found_end=0 }
+        /^---$/ && !found_end {
+          if (in_frontmatter) { found_end=1; next }
+          else { in_frontmatter=1; next }
+        }
+        !in_frontmatter || found_end { print }
+      ' "$file" >> "$AGENTS_MD_TEMP"
     done
   fi
 }
 
+# Initialize both files with headers
+add_file_header "$CLAUDE_MD_TEMP" "Claude Code" "Claude Code automatically reads CLAUDE.md files from your project root to understand project conventions, coding standards, and development workflows."
+add_file_header "$AGENTS_MD_TEMP" "Codex IDE" "Codex IDE reads AGENTS.md files to provide project-specific context and instructions. Codex discovers AGENTS.md files starting from the project root and walking down to your current directory."
+
 # Always include shared rules
 copy_rules "$SHARED_DIR"
-append_to_claude_md "$SHARED_DIR"
+append_to_md_files "$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)
     copy_rules "$FRONTEND_DIR"
-    append_to_claude_md "$FRONTEND_DIR"
+    append_to_md_files "$FRONTEND_DIR"
     ;;
   backend)
     copy_rules "$BACKEND_DIR"
-    append_to_claude_md "$BACKEND_DIR"
+    append_to_md_files "$BACKEND_DIR"
     ;;
   frontend-lib)
     copy_rules "$FRONTEND_DIR"
     copy_rules "$FRONTEND_LIB_DIR"
-    append_to_claude_md "$FRONTEND_DIR"
-    append_to_claude_md "$FRONTEND_LIB_DIR"
+    append_to_md_files "$FRONTEND_DIR"
+    append_to_md_files "$FRONTEND_LIB_DIR"
     ;;
   *)
     echo "Unknown environment type: $ENV_TYPE"
@@ -196,10 +221,12 @@ case "$ENV_TYPE" in
     ;;
 esac
 
-# Generate CLAUDE.md
+# Generate both CLAUDE.md and AGENTS.md
 mv "$CLAUDE_MD_TEMP" "$PROJECT_DIR/CLAUDE.md"
+mv "$AGENTS_MD_TEMP" "$PROJECT_DIR/AGENTS.md"
 trap - EXIT
 echo "CLAUDE.md generated for Claude Code"
+echo "AGENTS.md generated for Codex IDE"
 
 if [ -d "$PROJECT_DIR/.cursor/skills" ] && [ "$(ls -A "$PROJECT_DIR/.cursor/skills" 2>/dev/null)" ]; then
   echo "Skills installed in:"

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mallardbay/cursor-rules",
-    "version": "1.0.18",
+    "version": "1.0.20",
     "description": "Mallard Bay shared cursor rules",
     "main": "bin/setup-cursor.sh",
     "repository": "git@github.com:mallardbay/cursor-rules.git",