Centralized AI Development Rules

Progressive disclosure framework for AI coding tools. Loads only relevant development rules based on project context and task type.

Features

• MECE Framework - Mutually Exclusive, Collectively Exhaustive rule organization
• Progressive Disclosure - Load only relevant rules (project + task level)
• Multi-tool Support - Claude Code, Cursor, GitHub Copilot, Gemini
• 74.4% Token Savings - Validated in production testing
• Four-Dimensional Structure - Base, Language, Framework, Cloud rules

Quick Start

Installation (one command, idempotent):

curl -fsSL https://raw.githubusercontent.com/paulduvall/centralized-rules/main/install-hooks.sh -o install-hooks.sh && bash install-hooks.sh

This installs globally (all projects). Safe to run multiple times - it updates in place. The installer verifies SHA256 checksums on downloaded release tarballs.

Security note: The script is downloaded to disk before execution — not piped directly to bash. You can inspect install-hooks.sh before running it.

For project-specific installation:

curl -fsSL https://raw.githubusercontent.com/paulduvall/centralized-rules/main/install-hooks.sh -o install-hooks.sh && bash install-hooks.sh --local

Idempotent behavior:

• Already installed? → Updates it in place
• Not installed? → Installs fresh
• Running it again? → Safely updates to latest version

No prompts, no conflicts, just works.

Advanced options:

# Install specific version
curl -fsSL https://raw.githubusercontent.com/paulduvall/centralized-rules/main/install-hooks.sh -o install-hooks.sh && bash install-hooks.sh --version v0.1.0

# Pin to specific commit SHA
curl -fsSL https://raw.githubusercontent.com/paulduvall/centralized-rules/main/install-hooks.sh -o install-hooks.sh && bash install-hooks.sh --commit abc1234

# Install from main branch (developers/testing)
curl -fsSL https://raw.githubusercontent.com/paulduvall/centralized-rules/main/install-hooks.sh -o install-hooks.sh && bash install-hooks.sh --edge

What You'll See

Hook displays concise banner showing detected rules:

═══════════════════════════════════════════════════════
🎯 Centralized Rules Active | Source: paulduvall/centralized-rules@16c0aa5
🔍 Rules: base/code-quality
💡 Follow standards • Write tests • Ensure security • Refactor
═══════════════════════════════════════════════════════

For git operations, pre-commit quality gates trigger:

═══════════════════════════════════════════════════════
🎯 Centralized Rules Active | Source: paulduvall/centralized-rules@16c0aa5
⚠️ PRE-COMMIT: Tests → Security → Quality → Refactor
🔍 Rules: base/git-tagging, base/git-workflow
💡 Small commits, clear messages - your future self will thank you
═══════════════════════════════════════════════════════

Verify Installation

Check hook is registered:

/hooks

Should show:

UserPromptSubmit
  2. $CLAUDE_PROJECT_DIR/.claude/hooks/activate-rules.sh

Test with code request - banner appears, Claude follows standards.

How It Works

Hook script runs on every prompt:

1. Detect context - Scans project for language markers (package.json, pyproject.toml, go.mod)
2. Match keywords - Analyzes prompt for task-specific terms (test, security, refactor)
3. Display banner - Shows which rules apply
4. Claude applies - Follows detected coding standards

Architecture

centralized-rules/
├── base/          # 23 universal rules (all projects)
├── languages/     # 6+ languages (Python, TypeScript, Go, Java, C#, Rust)
├── frameworks/    # 12+ frameworks (React, Django, FastAPI, Spring Boot, etc.)
└── cloud/         # Cloud providers (AWS, Vercel)

Auto-Detection

Languages: Detected via pyproject.toml, package.json, go.mod, pom.xml, Cargo.toml

Frameworks: Parsed from dependency files

Keywords:

• Testing: test, pytest, jest, tdd
• Security: auth, encrypt, validate
• Git: commit, push, pull request
• Refactoring: refactor, optimize

Real-World Results

Python + FastAPI project measurements:

Troubleshooting

Duplicate banner appearing (hook runs twice):

You've installed both globally AND locally. Remove one installation:

# Option 1: Remove global hook (keep local)
jq 'del(.hooks.UserPromptSubmit[] | select(.hooks[]?.command | contains("activate-rules.sh")))' \
   ~/.claude/settings.json > ~/.claude/settings.json.tmp && \
   mv ~/.claude/settings.json.tmp ~/.claude/settings.json

# Option 2: Remove local hook (keep global)
jq 'del(.hooks.UserPromptSubmit[] | select(.hooks[]?.command | contains("activate-rules.sh")))' \
   .claude/settings.json > .claude/settings.json.tmp && \
   mv .claude/settings.json.tmp .claude/settings.json

Without jq:

# Manually edit the settings file and remove the UserPromptSubmit hook
vim ~/.claude/settings.json  # For global
# OR
vim .claude/settings.json    # For local

Hook not appearing:

/hooks  # Check registered hooks
chmod +x .claude/hooks/activate-rules.sh  # Fix permissions

Wrong language detected:
Create appropriate marker file (package.json, pyproject.toml, go.mod)

No banner displayed:
Include keywords in prompt: "Write a Python function with tests"

Customization

Local Rule Overrides

Customize rules for your project without forking:

# Create override directory
mkdir -p .claude/rules-local/base

# Add project-specific security requirements
cat > .claude/rules-local/base/security.md << 'EOF'
# Additional Security Requirements
- All API endpoints require authentication
- Rate limiting on public routes
EOF

# Sync with overrides applied
./sync-ai-rules.sh --tool claude

Configure merge behavior in .claude/rules-config.local.json:

{
    "merge_strategy": "extend",
    "overrides": {
        "base/security.md": "replace"
    },
    "exclude": ["base/chaos-engineering.md"]
}

Merge strategies:

• extend (default): Append local after central
• replace: Local completely replaces central
• prepend: Local appears before central

Preview changes without applying: ./sync-ai-rules.sh --dry-run

See Local Override Documentation for full reference.

Keyword Detection

Edit .claude/skills/skill-rules.json to add keywords:

{
  "keywordMappings": {
    "languages": {
      "python": {
        "keywords": ["python", ".py", "your-keyword"],
        "rules": ["languages/python"]
      }
    }
  }
}

Changes take effect immediately.

Organization Deployment

Fork repository:

export RULES_REPO="https://raw.githubusercontent.com/your-org/centralized-rules/main"
curl -fsSL $RULES_REPO/install-hooks.sh -o install-hooks.sh && bash install-hooks.sh --global

Commit to projects:

cp -r .claude/ your-project-template/
git add .claude/

Documentation

• Installation Guide - Setup instructions
• Hook System - Automatic rule loading and quality gates
• Local Overrides - Project-level rule customization
• Classification System - Prompt classification
• Bash Code Quality - Engineering analysis

Supported Technologies

Languages: Python, TypeScript, JavaScript, Go, Java, C#, Rust

Frameworks: React, Next.js, Django, FastAPI, Flask, Express, Spring Boot, NestJS, Vue

Cloud: AWS, Vercel

AI Tools: Claude Code, Cursor, GitHub Copilot, Gemini

Contributing

Open issues or pull requests at github.com/paulduvall/centralized-rules.

License

MIT License - See LICENSE for details.