@clipboard-health/ai-rules

Pre-built AI agent rules for consistent coding standards. Uses a retrieval-based approach: generates a compressed index in AGENTS.md pointing to copied .rules/ files that agents read on demand.

Table of contents

• Install
• Usage
  • Quick Start
  • Include/Exclude Rules
  • Updating Rules
• Available Rules
• Contributing Rules
• Migration from v1
• Local development commands

Install

npm install --save-dev @clipboard-health/ai-rules

Usage

Quick Start

1. If you have an existing AGENTS.md and/or CLAUDE.md file in your repository, rename it to OVERLAY.md. The sync script appends this file's contents to generated AGENTS.md so it's loaded into LLM agent contexts.

2. Choose the profile that matches your project type:

   Profile	Includes	Use For
   common	common	TypeScript libraries, generic projects
   frontend	common + frontend	React apps, web apps
   backend	common + backend	NestJS services, APIs
   fullstack	common + frontend + backend	Monorepos, fullstack apps
   datamodeling	datamodeling	DBT data modeling

3. Add it to your package.json:

   {
     "scripts": {
       "sync-ai-rules": "node ./node_modules/@clipboard-health/ai-rules/scripts/sync.js [PROFILE_NAME]",
       "postinstall": "node --run sync-ai-rules"
     }
   }
   

4. Run:

   npm install  # Runs postinstall automatically
   

5. Commit the generated files:

   git add .rules/ AGENTS.md CLAUDE.md
   git commit -m "feat: add AI coding rules"
   

Include/Exclude Rules

Fine-tune which rules are synced using --include and --exclude:

# Backend profile without MongoDB rules
node sync.js backend --exclude backend/mongodb

# Common profile plus one backend rule
node sync.js common --include backend/architecture

# Multiple overrides
node sync.js backend --exclude backend/mongodb backend/postgres --include frontend/testing

Unknown rule ids are skipped with a warning so a stale --include/--exclude never breaks installs.

Update your package.json script accordingly:

{
  "scripts": {
    "sync-ai-rules": "node ./node_modules/@clipboard-health/ai-rules/scripts/sync.js backend --exclude backend/mongodb"
  }
}

Updating Rules

When we release new rules or improvements:

# Update the package
npm update @clipboard-health/ai-rules

# The postinstall script automatically syncs the latest files
npm install

# Review the changes
git diff .rules/ AGENTS.md

# Commit the updates
git add .rules/ AGENTS.md CLAUDE.md
git commit -m "chore: update AI coding rules"

Rules are occasionally split so each one carries a narrower retrieval trigger. If you pin individual rule ids with --include rather than taking a whole category, check the diff for new ids after upgrading: a stale --include keeps resolving, so you lose the split-out rules without a warning.

Available Rules

Each rule's "When to Read" text comes from the description field in the rule file's YAML frontmatter — the single source of truth used for the generated AGENTS.md index and the tables below.

backend

common

datamodeling

frontend

Contributing Rules

A rule earns its place only if a frontier model would do the wrong thing without it: Clipboard-specific decisions, library choices, naming, and hard-won gotchas. Do not add tutorials, generic best practices, or anything a linter already enforces.

To add or change a rule:

1. Edit or create the rule file under rules/<category>/ with a frontmatter description (the "When to Read" text).
2. Run npx tsx scripts/populateReadme.ts to regenerate the tables above (a test fails if they drift).
3. New categories are directories under rules/; no registration needed.

Migration from v1

v2 replaces the monolithic AGENTS.md with a retrieval-based approach. Rule files are now committed to your repo under .rules/.

1. Update the package:

   npm install --save-dev @clipboard-health/ai-rules@latest
   

2. Run install to trigger sync:

   npm install
   

3. Add .rules/ to git and commit:

   git add .rules/ AGENTS.md CLAUDE.md
   git commit -m "feat!: update ai-rules to v2 retrieval-based approach"
   

Local development commands

See package.json scripts for a list of commands.