@mallardbay/cursor-rules 1.0.30 → 1.0.31

package/.cursor/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
@@ -108,11 +114,18 @@ These principles apply to all code changes and should guide every implementation
 4. **Check git history** to understand why code exists as it does
 5. **Identify related files** that might be affected
 6. **Ask clarifying questions** if requirements are unclear
+7. **Use MCP servers when available**—leverage Model Context Protocol servers for enhanced capabilities
+   - **Context7 MCP**: Use the context7 MCP server when available to retrieve up-to-date documentation and code examples for libraries
+   - If context7 MCP is not available, suggest adding it to improve access to library documentation
+   - **Suggest useful MCP servers**: When appropriate, suggest popular and useful MCP servers that could enhance development workflow based on the task at hand
+   - Consider MCP servers for documentation, testing, debugging, and other development tasks
 
 ### During 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 +135,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 +158,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/general-best-practices.mdc

@@ -7,6 +7,14 @@ alwaysApply: true
 
 These principles apply to all code changes and should guide every implementation decision.
 
+## Project Setup
+
+- Install dependencies with `yarn`
+- Run the project locally with `yarn start`
+- Run tests with `yarn test`
+- For large test suites, use sharding: `JEST_SHARD=1/n yarn test` where `n` is the total number of shards (never more than 10)
+  - Example: `JEST_SHARD=1/3 yarn test`, `JEST_SHARD=2/3 yarn test`, `JEST_SHARD=3/3 yarn test`
+
 ## Core Principles
 
 ### DRY (Don't Repeat Yourself)
@@ -75,8 +83,8 @@ These principles apply to all code changes and should guide every implementation
   - 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
+- Run tests with `yarn test` for affected modules, not the entire test suite unnecessarily
+- For large changes: **use test sharding** via `JEST_SHARD=1/n yarn test`—split tests across multiple shards (never more than 10)
 - **Do not run all tests in parallel** when dealing with many changes
 - Tests should be **clear, fast, and minimize setup duplication**
 - Use shared test utilities and fixtures to reduce boilerplate
@@ -143,7 +151,7 @@ These principles apply to all code changes and should guide every implementation
 
 ### When Changes Are Large
 1. **Consider splitting** into multiple smaller PRs
-2. **Use test sharding**—run tests in batches, not all at once
+2. **Use test sharding** (`JEST_SHARD=1/n yarn test`)—run tests in batches, not all at once (max 10 shards)
 3. **Review incrementally**—make sure each part works before moving on
 4. **Document the approach**—explain why changes are structured this way
 5. **Check impact** on related systems and files

package/README.md

@@ -112,10 +112,28 @@ your-project/
 └── AGENTS.md           # Codex IDE configuration (combined rules)
 ```
 
-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.
+Both `CLAUDE.md` and `AGENTS.md` combine all applicable rules into single files, with YAML frontmatter stripped for compatibility. Each file opens with a header comment that states the file is **auto-generated** (do not edit by hand) and that **project-specific rules** belong in `AGENTS_LOCAL.md`, plus which tool consumes the file.
 
 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.
 
+### Project-Local Rules (`AGENTS_LOCAL.md`)
+
+If your project needs additional rules beyond what the shared configuration provides, create an `AGENTS_LOCAL.md` file in your project root. Its content will be automatically appended to both `CLAUDE.md` and `AGENTS.md` when the setup script runs.
+
+This is useful for:
+- Project-specific conventions or architectural decisions
+- Team-level overrides or additions
+- Context that only applies to a single repository
+
+```
+your-project/
+├── AGENTS_LOCAL.md    # Your project-specific rules (checked into version control)
+├── CLAUDE.md          # Generated (includes AGENTS_LOCAL.md content)
+└── AGENTS.md          # Generated (includes AGENTS_LOCAL.md content)
+```
+
+`AGENTS_LOCAL.md` is meant to be checked into version control, while `CLAUDE.md` and `AGENTS.md` are generated and should be gitignored.
+
 ## Development
 
 ### Adding New Rules

package/bin/setup-cursor.sh

@@ -92,8 +92,16 @@ 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.
+AUTO-GENERATED — DO NOT EDIT THIS FILE BY HAND. It is produced by
+@mallardbay/cursor-rules when you run the setup script (e.g. npx @mallardbay/cursor-rules <env-type>).
+Any manual changes will be overwritten on the next run.
+
+Content sources: shared and environment-specific rules copied into .cursor/rules/ as *.mdc files,
+combined here with YAML frontmatter stripped.
+
+PROJECT-SPECIFIC RULES: Add or edit AGENTS_LOCAL.md in the project root (commit that file).
+On the next setup run, its contents are appended to both CLAUDE.md and AGENTS.md. Do not put
+long-lived project-only guidance only in this file — use AGENTS_LOCAL.md instead.
 
 For more information:
 - $tool_name: See official documentation
@@ -226,6 +234,19 @@ case "$ENV_TYPE" in
     ;;
 esac
 
+# Append project-local AGENTS_LOCAL.md if it exists
+if [ -f "$PROJECT_DIR/AGENTS_LOCAL.md" ]; then
+  echo "Found AGENTS_LOCAL.md — appending project-local rules"
+  echo "" >> "$CLAUDE_MD_TEMP"
+  echo "---" >> "$CLAUDE_MD_TEMP"
+  echo "" >> "$CLAUDE_MD_TEMP"
+  cat "$PROJECT_DIR/AGENTS_LOCAL.md" >> "$CLAUDE_MD_TEMP"
+  echo "" >> "$AGENTS_MD_TEMP"
+  echo "---" >> "$AGENTS_MD_TEMP"
+  echo "" >> "$AGENTS_MD_TEMP"
+  cat "$PROJECT_DIR/AGENTS_LOCAL.md" >> "$AGENTS_MD_TEMP"
+fi
+
 # Generate both CLAUDE.md and AGENTS.md
 mv "$CLAUDE_MD_TEMP" "$PROJECT_DIR/CLAUDE.md"
 mv "$AGENTS_MD_TEMP" "$PROJECT_DIR/AGENTS.md"

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mallardbay/cursor-rules",
-    "version": "1.0.30",
+    "version": "1.0.31",
     "description": "Mallard Bay shared cursor rules",
     "main": "bin/setup-cursor.sh",
     "repository": "git@github.com:mallardbay/cursor-rules.git",
@@ -18,6 +18,15 @@
     "publishConfig": {
         "access": "public"
     },
+    "scripts": {
+        "test": "echo 'No tests yet'",
+        "test:ci": "echo 'No tests yet'",
+        "lint:quiet": "echo 'No linting configured yet'",
+        "release": "semantic-release"
+    },
+    "devDependencies": {
+        "semantic-release": "^24.0.0"
+    },
     "bin": {
         "cursor-rules": "bin/setup-cursor.sh"
     }