diffray 0.1.0

package/README.md

@@ -0,0 +1,395 @@
+# ⚡ diffray
+
+**Code Review Pipeline** - Git diffs → Agents → Results
+
+## What is an Agent?
+
+**Agent is an abstraction** - it can be either:
+
+- **LLM Agent** - API call to Claude, GPT, or other LLMs
+- **CLI Agent** - Execution of CLI tools like `claude`, `auggie`, etc.
+
+This allows you to combine different review approaches in one pipeline!
+
+
+## Architecture
+
+```
+Git Changes → Pipeline → LLM Agent (Claude API)  → Result 1
+                      → CLI Agent (claude code) → Result 2
+                      → CLI Agent (auggie)      → Result 3
+                      → LLM Agent (GPT-4)       → Result 4
+```
+
+## Key Features
+
+- **Pipeline-based** - Process diffs through multiple stages
+- **Stage System** - Organized execution: Load Rules → Match → Execute → Aggregate
+- **Rule Matching** - Run different agents on different file types using glob patterns
+- **Flexible Agents** - Mix LLM APIs and CLI tools in one pipeline
+- **Markdown Agents** - Define agents using simple Markdown files
+- **Parallel Execution** - All agents run simultaneously within their stage
+- **Live Spinners** - Visual feedback for each agent (no external dependencies)
+- **Configurable** - Enable/disable agents, rules, and stages
+- **Global** - Works in any git repository
+- **Lightweight** - Minimal dependencies
+
+## Installation
+
+### From source
+
+```bash
+# Clone and install
+git clone <your-repo>
+cd diffray
+bun install
+
+# Link globally
+bun link
+```
+
+Now you can use `diffray` anywhere!
+
+## Usage
+
+### Run Pipeline
+
+```bash
+# Run code review pipeline
+diffray
+
+# Output:
+# ⚡ diffray - AI Code Review
+#
+# ■ Analyzing changes...
+# ◇ 8 files: 7 modified, 1 added
+#    624 changes: +612 -12
+# ◉ Loading agents...
+# ✓ Loaded 2 agent(s)
+#
+# ↻ Running 2 agent(s) in parallel...
+# ✓ Custom Code Review (101ms)
+# ✓ Security Scanner (101ms)
+#
+# ✓ Pipeline completed successfully in 102ms
+# ■ 2/2 agents succeeded
+
+# Verbose mode (shows file details and prompts)
+diffray --verbose
+
+# JSON output (machine-readable)
+diffray --json
+
+# Filter by severity (show only critical)
+diffray --severity=critical
+
+# Filter by multiple severities (critical and high)
+diffray --severity=critical,high
+
+# Combine options
+diffray --json --severity=critical
+
+# Output includes:
+#    ~ README.md: +141 -5
+#    ~ src/cli.ts: +107 -3
+#    + src/config.test.ts: +52 -0
+#    ...
+```
+
+### Manage Agents
+
+```bash
+# List all agents
+diffray agents list
+
+# Show agent details
+diffray agents show bug-hunter
+
+# Sync agents from MD files to cache
+diffray agents sync
+```
+
+**Creating Custom Agents:**
+
+Agents are defined using Markdown files! See [Agent Configuration Guide](./docs/AGENTS.md) for details.
+
+To create a custom agent, create a new `.md` file in `src/defaults/agents/` with the following structure:
+- Frontmatter with ID, Order, Enabled, and Executor fields
+- Description section
+- System Prompt section
+
+After creating or modifying agents, run `diffray agents sync` to reload them.
+
+### Manage Executors
+
+```bash
+# List all executors
+diffray executors list
+
+# Show executor details
+diffray executors show claude-cli
+
+# Enable/disable executors
+diffray executors enable cerebras-api
+diffray executors disable claude-cli
+```
+
+### Manage Rules
+
+Rules allow you to run different agents on different file types using glob patterns. Rules are defined in Markdown files in `src/defaults/rules/`.
+
+```bash
+# List all rules
+diffray rules list
+
+# Show rule details
+diffray rules show code-bugs
+
+# Test rule matching against specific files
+diffray rules test code-bugs src/cli.ts src/agents.ts README.md
+# Output:
+# ✓ Matched 2 file(s):
+#   ● src/cli.ts
+#   ● src/agents.ts
+# Not matched 1 file(s):
+#   ○ README.md
+
+# Sync rules from MD files to cache
+diffray rules sync
+```
+
+**Creating Custom Rules:**
+
+Create a new `.md` file in `src/defaults/rules/` with frontmatter:
+
+```markdown
+---
+id: "my-rule"
+name: "My Custom Rule"
+description: "Description of what this rule does"
+patterns: ["**/*.ts", "**/*.tsx"]
+agent: "bug-hunter"
+---
+
+Additional instructions for the agent when this rule matches.
+```
+
+**Default Rules:**
+- `code-bugs`: Run bug-hunter on code files `**/*.{ts,tsx,js,jsx,py,go,rs,java,rb,php}`
+- `code-security`: Run security-scan on code files `**/*.{ts,tsx,js,jsx,py,go,rs,java,rb,php}`
+- `config-security`: Run security-scan on config files `**/*.{json,yaml,yml,toml}`
+
+### Configuration
+
+diffray stores configuration in `~/.diffray/config.json`. This file caches agents, executors, rules, and settings.
+
+```bash
+# Initialize configuration file
+diffray config init
+
+# Show current configuration
+diffray config show
+
+# Edit configuration in your $EDITOR
+diffray config edit
+
+# Reset to defaults
+diffray config reset
+```
+
+#### Configuration Structure
+
+The configuration file has the following structure:
+
+```json
+{
+  "excludePatterns": ["*.lock", "*.min.js", "dist/*", "node_modules/**"],
+  "output": {
+    "colorize": true,
+    "verbose": false,
+    "format": "terminal"
+  },
+  "executors": [...],
+  "agents": [...],
+  "rules": [...],
+  "stages": [...]
+}
+```
+
+**Key Sections:**
+
+- `excludePatterns`: File patterns to exclude from review (array of glob patterns)
+- `output.colorize`: Enable colored output (boolean, default: `true`)
+- `output.verbose`: Show verbose output (boolean, default: `false`)
+- `output.format`: Output format - `terminal`, `markdown`, or `json` (default: `terminal`)
+- `executors`: Cached executor configurations (managed via `diffray executors` commands)
+- `agents`: Cached agent configurations (synced from Markdown files via `diffray agents sync`)
+- `rules`: Cached rule configurations (synced from MD files via `diffray rules sync`)
+- `stages`: Pipeline stage configurations with enabled/disabled status
+
+### Executors Configuration
+
+Executors define **how** to run Agents. diffray supports multiple executor types:
+
+- **CLI Executors** - Run CLI tools like `claude`, `auggie`, etc.
+- **LLM API Executors** - Call LLM APIs directly (Claude, GPT, etc.)
+
+Executors are configured in `~/.diffray/config.json`.
+
+#### Executor Configuration
+
+Executors can be configured in `~/.diffray/config.json`:
+
+```json
+{
+  "executors": [
+    {
+      "name": "claude-cli",
+      "enabled": true,
+      "model": "opus",
+      "timeout": 180
+    },
+    {
+      "name": "cerebras-api",
+      "enabled": true,
+      "model": "llama-3.1-8b",
+      "temperature": 0.5,
+      "maxTokens": 4096
+    }
+  ]
+}
+```
+
+#### Executor Options
+
+**CLI Executors (claude-cli):**
+- `enabled` - Enable/disable executor
+- `model` - Model to use (default: `sonnet`)
+- `timeout` - Timeout in seconds (default: 120)
+
+**API Executors (cerebras-api):**
+- `enabled` - Enable/disable executor
+- `model` - Model to use (default: `llama-3.3-70b`)
+- `temperature` - Temperature (default: 0.7)
+- `maxTokens` - Max tokens (default: 8192)
+
+#### Linking Agents to Executors
+
+Agents reference executors via the `executor` field in their Markdown configuration:
+
+```markdown
+---
+ID: bug-hunter
+Executor: claude-cli
+---
+```
+
+## Agent Configuration
+
+Agents are configured using **Markdown files** in `src/defaults/agents/`. See the [Agent Configuration Guide](./docs/AGENTS.md) for complete documentation.
+
+### Agent Markdown Format
+
+Each agent is defined in a `.md` file with frontmatter metadata:
+
+```markdown
+# Agent: Bug Hunter
+
+---
+ID: bug-hunter
+Order: 1
+Enabled: true
+Executor: claude-cli
+---
+
+## Description
+
+Detects bugs, logic errors and runtime issues in code.
+
+## System Prompt
+
+You are a code reviewer analyzing changes for:
+
+### Logic Errors
+- Identify bugs and edge cases
+- Check error handling
+
+### Code Quality
+- Assess readability
+- Check naming conventions
+
+Reference ../output-format.md for JSON output structure.
+```
+
+The system will automatically load all `.md` files from `src/defaults/agents/` and cache them in the config. Run `diffray agents sync` to reload after changes.
+
+## Example Output
+
+```
+⚡ diffray - AI Code Review
+
+■ Analyzing changes...
+
+Summary: 2 modified, 1 added
+
+================================================================================
+
+src/index.ts (modified)
+
++ export function greet(name: string): string {
++   return `Hello, ${name}!`;
++ }
+
+--------------------------------------------------------------------------------
+
+✓ Reviewed 3 file(s)
+```
+
+## Development
+
+```bash
+# Run in development mode
+bun run dev
+
+# Build standalone binary
+bun run build
+
+# Run tests
+bun test
+```
+
+## Project Structure
+
+```
+diffray/
+├── bin/
+│   └── diffray.ts           # CLI entry point
+├── src/
+│   ├── cli.ts               # Main CLI logic
+│   ├── pipeline.ts          # Pipeline execution
+│   ├── stages/              # Pipeline stages
+│   ├── agents/              # Agent registry and loaders
+│   ├── executors/           # Executor implementations
+│   ├── commands/            # CLI commands
+│   ├── defaults/            # Default agents and rules (Markdown)
+│   ├── git.ts               # Git operations
+│   └── issue-formatter.ts   # Issue formatting
+└── package.json
+```
+
+## Roadmap
+
+- [ ] Interactive mode with file selection
+- [ ] Export reports to markdown/HTML
+- [ ] Integration with GitHub/GitLab
+- [ ] Token batching for large diffs
+- [ ] Caching for repeated reviews
+
+## Built With
+
+- [Bun](https://bun.sh) - Fast JavaScript runtime
+- TypeScript - Type safety
+
+## License
+
+MIT

package/bin/diffray-wrapper.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+import { spawn } from 'child_process';
+import { existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const isWindows = process.platform === 'win32';
+const binaryName = isWindows ? 'diffray.exe' : 'diffray';
+const binaryPath = join(__dirname, '..', '.bin', binaryName);
+
+if (!existsSync(binaryPath)) {
+  console.error(`Error: diffray binary not found at ${binaryPath}`);
+  console.error('Try reinstalling: npm install -g diffray');
+  process.exit(1);
+}
+
+const child = spawn(binaryPath, process.argv.slice(2), {
+  stdio: 'inherit',
+  windowsHide: true,
+});
+
+child.on('error', (err) => {
+  console.error('Failed to start diffray:', err.message);
+  process.exit(1);
+});
+
+child.on('close', (code) => {
+  process.exit(code ?? 0);
+});

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "diffray",
+  "version": "0.1.0",
+  "description": "AI-powered code review CLI for git changes",
+  "author": "Ilya Strelov <strelov1@gmail.com>",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "diffray": "./bin/diffray-wrapper.js"
+  },
+  "files": [
+    "bin/diffray-wrapper.js",
+    "scripts/postinstall.js",
+    "src/defaults"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "dev": "bun run ./bin/diffray.ts",
+    "build": "bun build ./bin/diffray.ts --compile --target=bun --minify --outfile dist/diffray",
+    "build:all": "bash scripts/build-all.sh",
+    "link": "bun link",
+    "unlink": "bun unlink",
+    "ts-check": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepublishOnly": "echo 'Run build:all and create GitHub release first!'"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/diffray/diffray.git"
+  },
+  "homepage": "https://github.com/diffray/diffray#readme",
+  "bugs": {
+    "url": "https://github.com/diffray/diffray/issues"
+  },
+  "keywords": [
+    "code-review",
+    "ai",
+    "cli",
+    "git",
+    "diff",
+    "llm",
+    "claude",
+    "cerebras",
+    "pull-request"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@types/bun": "latest",
+    "@typescript-eslint/eslint-plugin": "^8.52.0",
+    "@typescript-eslint/parser": "^8.52.0",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "prettier": "^3.7.4"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "citty": "^0.1.6",
+    "diff": "^8.0.2",
+    "glob": "^13.0.0",
+    "zod": "^3.22.4"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import process from 'process';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+async function main() {
+  try {
+    if (process.env.DIFFRAY_SKIP_DOWNLOAD === '1') {
+      console.log('Skipping diffray binary download (DIFFRAY_SKIP_DOWNLOAD=1)');
+      process.exit(0);
+    }
+
+    const packageJsonPath = path.join(__dirname, '..', 'package.json');
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+    const version = packageJson.version;
+
+    const platform = process.platform;
+    const arch = process.arch;
+
+    const platformArchMap = {
+      'darwin-arm64': 'diffray-darwin-arm64',
+      'darwin-x64': 'diffray-darwin-x64',
+      'linux-arm64': 'diffray-linux-arm64',
+      'linux-x64': 'diffray-linux-x64',
+      'win32-x64': 'diffray-win-x64.exe'
+    };
+
+    const platformArch = `${platform}-${arch}`;
+    const binaryName = platformArchMap[platformArch];
+
+    if (!binaryName) {
+      console.error(`Unsupported platform: ${platformArch}`);
+      process.exit(1);
+    }
+
+    console.log(`Downloading diffray v${version} for ${platformArch}...`);
+
+    const url = `https://github.com/diffray/diffray/releases/download/v${version}/${binaryName}`;
+    const response = await fetch(url);
+
+    if (!response.ok) {
+      console.error(`Failed to download binary: ${response.status} ${response.statusText}`);
+      process.exit(1);
+    }
+
+    const binDir = path.join(__dirname, '..', '.bin');
+    if (!fs.existsSync(binDir)) {
+      fs.mkdirSync(binDir, { recursive: true });
+    }
+
+    const outputPath = platform === 'win32' 
+      ? path.join(binDir, 'diffray.exe')
+      : path.join(binDir, 'diffray');
+
+    const buffer = await response.arrayBuffer();
+    fs.writeFileSync(outputPath, new Uint8Array(buffer));
+
+    if (platform !== 'win32') {
+      fs.chmodSync(outputPath, 0o755);
+    }
+
+    console.log('Successfully installed diffray binary');
+    process.exit(0);
+  } catch (error) {
+    console.error('Error installing diffray binary:', error.message);
+    process.exit(1);
+  }
+}
+
+main();

package/src/defaults/agents/EXAMPLE.md.template

@@ -0,0 +1,27 @@
+<!-- This is a template for creating custom agents. Copy and modify. -->
+
+# Agent: Custom Agent Template
+
+---
+ID: custom-agent
+Order: 10
+Enabled: false
+Executor: test-cli
+---
+
+## Description
+
+This is a template agent. Replace this text with your agent's description.
+Explain what this agent does and when it should be used.
+
+## System Prompt
+
+You are a custom agent. Replace this with your agent's instructions.
+
+### Focus Areas
+- Add your focus areas here
+- Use bullet points for clarity
+
+### Guidelines
+- Explain what to look for
+- Be specific about the analysis approach

package/src/defaults/agents/bug-hunter.md

@@ -0,0 +1,24 @@
+---
+name: bug-hunter
+description: Detects bugs, logic errors and runtime issues
+enabled: true
+executor: claude-cli
+---
+
+You are a bug detection specialist focused on identifying logic errors and runtime issues that will cause code to fail or behave incorrectly.
+
+**Your Mission**: Find bugs before they reach production. Focus ONLY on correctness - will the code work as intended?
+
+**Focus Areas**:
+- **Null/Undefined Safety**: Missing null checks, potential NPE, undefined access
+- **Logic Errors**: Incorrect conditionals, wrong operators, off-by-one errors, algorithm bugs
+- **Edge Cases**: Empty arrays/objects, boundary conditions, unexpected input
+- **Type Safety**: Type coercion bugs, incorrect type usage (not style)
+- **Async/Concurrency**: Race conditions, unhandled promise rejections, callback errors
+- **Resource Cleanup**: Unclosed files/connections/streams that will cause crashes
+
+**Instructions**:
+- ONLY report issues likely to cause runtime errors or incorrect behavior
+- Focus on "will this crash or produce wrong results?"
+- Provide evidence: what input will break it?
+- Be concise and actionable

package/src/defaults/agents/performance-check.md

@@ -0,0 +1,25 @@
+---
+name: performance-check
+description: Checks for performance issues
+enabled: true
+executor: claude-cli
+---
+
+You are a performance optimization expert specializing in identifying bottlenecks, scalability issues, and optimization opportunities.
+
+**Your Mission**: Identify performance bottlenecks that affect real-world usage and scalability. Think at scale - what works for 10 users might break for 10,000.
+
+**Focus Areas**:
+- **Algorithm Complexity**: O(n²) or worse algorithms, nested loops, inefficient searching/sorting
+- **Database Performance**: N+1 queries, missing indexes, no pagination, inefficient joins
+- **Memory Management**: Memory leaks, excessive allocations, no streaming for large data
+- **Network & I/O**: Excessive API calls, missing caching, sequential requests, large payloads
+- **Concurrency**: Blocking operations, missing parallelization opportunities
+- **Resource Usage**: Unclosed file handles/connections, CPU-intensive operations
+
+**Instructions**:
+- Focus on measurable impact, not micro-optimizations
+- Consider scale and usage patterns
+- Provide Big O analysis where applicable
+- Note any trade-offs (e.g., memory vs speed)
+- Only report actual performance issues

package/src/defaults/agents/security-scan.md

@@ -0,0 +1,27 @@
+---
+name: security-scan
+description: Scans for security vulnerabilities
+enabled: true
+executor: claude-cli
+---
+
+You are a senior security engineer performing focused security audits of code changes.
+
+**Your Mission**: Identify HIGH-CONFIDENCE security vulnerabilities with real exploitation potential before they reach production.
+
+**Focus Areas**:
+- **Injection Attacks**: SQL, XSS, command injection, code injection, template injection
+- **Authentication & Authorization**: bypass, privilege escalation, broken access control
+- **Secrets & Crypto**: hardcoded credentials, weak algorithms, key exposure
+- **Data Protection**: sensitive data exposure, insecure storage, PII leakage
+- **Deserialization**: pickle, YAML, JSON vulnerabilities
+
+**Quality Standards**:
+- Only flag issues with high confidence of actual exploitability
+- Every finding must have a concrete attack path with evidence
+- Prioritize: CRITICAL (RCE, data breach) > HIGH (auth bypass) > MEDIUM (defense-in-depth)
+- Skip theoretical issues, focus on real security impact
+
+**Instructions**:
+- Be concise and actionable
+- Only report actual security vulnerabilities

package/src/defaults/prompts/output-format.md

@@ -0,0 +1,57 @@
+# Output Format
+
+Return your findings as a **JSON array** with the following structure:
+
+```json
+[
+  {
+    "file": "path/to/file.ts",
+    "lineStart": 10,
+    "lineEnd": 15,
+    "severity": "critical|high|medium|low",
+    "category": "security|performance|bug|quality|style|docs",
+    "shortDescription": "Brief one-line description",
+    "fullDescription": "Detailed description of the issue",
+    "suggestion": "How to fix this issue (optional)"
+  }
+]
+```
+
+## Field Descriptions:
+
+- **file**: Relative path to the file containing the issue
+- **lineStart**: Starting line number of the issue
+- **lineEnd**: Ending line number of the issue (can be same as lineStart)
+- **severity**: One of: `critical`, `high`, `medium`, `low`
+- **category**: One of: `security`, `performance`, `bug`, `quality`, `style`, `docs`
+- **shortDescription**: Brief one-line summary of the issue
+- **fullDescription**: Detailed explanation of what's wrong
+- **suggestion**: (Optional) Recommendation on how to fix the issue
+
+## Important Rules:
+
+1. **Return empty array if no issues found**: `[]`
+2. **Use valid JSON format** - ensure proper escaping of quotes and special characters
+3. **Be precise with line numbers** - they must correspond to actual lines in the diff
+4. **Only report actual issues** - do NOT report:
+   - Code that is already correct
+   - Positive observations or compliments
+   - "No action needed" type comments
+   - Documentation improvements that are already good
+
+## Example:
+
+```json
+[
+  {
+    "file": "src/utils/validator.ts",
+    "lineStart": 42,
+    "lineEnd": 45,
+    "severity": "high",
+    "category": "bug",
+    "shortDescription": "Potential null pointer dereference",
+    "fullDescription": "The 'user' object may be null at this point, but is accessed without a null check. This will cause a runtime error if user is null.",
+    "suggestion": "Add a null check before accessing user properties: if (user) { ... }"
+  }
+]
+```

package/src/defaults/prompts/validation.md

@@ -0,0 +1,80 @@
+# Validation Agent
+
+You are a strict code review validation agent. Your task is to validate issues found by other agents and ONLY KEEP issues that are CLEARLY VALID with HIGH CONFIDENCE.
+
+You will receive a JSON array of issues. Each issue has:
+- file: the file path
+- lineStart, lineEnd: the line range
+- severity: critical, high, medium, or low
+- category: security, performance, bug, quality, style, or docs
+- shortDescription: brief description
+- fullDescription: detailed description
+- suggestion: optional suggestion for fixing
+- agent: which agent found this issue
+
+## KEEP only issues that meet ALL criteria:
+- The issue is REAL and VERIFIABLE in the code
+- Line numbers are correct (within ~5 lines)
+- The claim can be proven with concrete evidence
+- The issue has clear practical impact
+- NOT a duplicate of another issue
+
+## FILTER OUT (remove) these issues:
+- Speculative or theoretical issues without proof
+- Issues where line numbers don't match actual code
+- Subjective style preferences
+- Issues that cannot be verified
+- Duplicate issues (keep only one)
+- Issues about code not in the diff
+- Low-confidence or "might be" issues
+
+IMPORTANT: When in doubt, FILTER OUT the issue. Only keep issues you are 90%+ confident are real problems.
+
+Your job is to:
+1. Analyze each issue carefully
+2. Only filter out CLEAR false positives as defined above
+3. Return the valid issues in JSON format
+
+You may include your analysis and reasoning, but MUST include a JSON array of valid issues somewhere in your response. The JSON array can be wrapped in markdown code blocks.
+
+## Example input:
+
+```json
+[
+  {
+    "file": "src/example.ts",
+    "lineStart": 10,
+    "lineEnd": 15,
+    "severity": "medium",
+    "category": "quality",
+    "shortDescription": "Duplicate logic",
+    "fullDescription": "The same calculation is performed twice",
+    "suggestion": "Extract to a helper function",
+    "agent": "bug-hunter"
+  }
+]
+```
+
+## Example output (KEEP - this is a valid code quality issue):
+
+```json
+[
+  {
+    "file": "src/example.ts",
+    "lineStart": 10,
+    "lineEnd": 15,
+    "severity": "medium",
+    "category": "quality",
+    "shortDescription": "Duplicate logic",
+    "fullDescription": "The same calculation is performed twice",
+    "suggestion": "Extract to a helper function",
+    "agent": "bug-hunter"
+  }
+]
+```
+
+## Example of what to FILTER OUT:
+
+- "Variable 'foo' is unused" but the variable IS used later in the code
+- "Missing null check" but there's already a null check
+- Issue about line 50 but the file only has 30 lines

package/src/defaults/rules/EXAMPLE.md.template

@@ -0,0 +1,31 @@
+<!-- This is a template for creating custom rules. Copy this file and modify it to create your own rule. -->
+
+---
+name: "custom-rule"
+description: "Template for creating custom rules"
+patterns: ["**/*.js", "**/*.ts"]
+agent: "code-quality"
+---
+
+Please review the provided code and check for issues according to the following criteria:
+
+1. Analyze the code structure and organization
+2. Check for potential performance issues or optimizations
+3. Verify error handling and edge cases
+4. Review naming conventions and code readability
+5. Ensure proper documentation and comments where needed
+
+Focus Areas:
+1. Code quality and maintainability
+2. Security vulnerabilities
+3. Performance bottlenecks
+4. Best practices adherence
+5. Error handling completeness
+
+Note: Only report actual issues found in the code. Do not report potential issues that don't exist in the current implementation.
+
+When reporting issues, be specific and actionable:
+- Clearly identify the file and line number
+- Explain why it's an issue
+- Provide concrete suggestions for improvement
+- Include code examples when helpful

package/src/defaults/rules/code-bugs.md

@@ -0,0 +1,31 @@
+---
+name: code-bugs
+description: Bug detection for code files
+patterns:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+  - "**/*.py"
+  - "**/*.go"
+  - "**/*.rs"
+  - "**/*.java"
+  - "**/*.rb"
+  - "**/*.php"
+agent: bug-hunter
+---
+
+Review code changes for:
+1. Potential bugs or logic errors
+2. Edge cases and error handling
+3. Resource leaks or memory issues
+4. Race conditions or concurrency bugs
+5. Null/undefined access
+
+Be concise and actionable.
+
+IMPORTANT: Only report actual issues that need fixing. Do NOT report:
+- Documentation improvements that are already good
+- Code that is already correct
+- Positive observations or compliments
+- "No action needed" type comments

package/src/defaults/rules/code-performance.md

@@ -0,0 +1,30 @@
+---
+name: code-performance
+description: Performance analysis for code files
+patterns:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+  - "**/*.py"
+  - "**/*.go"
+  - "**/*.rs"
+  - "**/*.java"
+  - "**/*.rb"
+  - "**/*.php"
+agent: performance-check
+---
+
+Review code changes for:
+1. Algorithm complexity (O(n^2) or worse)
+2. N+1 queries and database inefficiencies
+3. Memory leaks and excessive allocations
+4. Missing caching opportunities
+5. Blocking operations and missing parallelization
+
+Be concise and actionable.
+
+IMPORTANT: Only report actual performance issues. Do NOT report:
+- Micro-optimizations with negligible impact
+- Theoretical issues without real-world consequences
+- Code that is already performant

package/src/defaults/rules/code-security.md

@@ -0,0 +1,25 @@
+---
+name: code-security
+description: Security scan for code files
+patterns:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+  - "**/*.py"
+  - "**/*.go"
+  - "**/*.rs"
+  - "**/*.java"
+  - "**/*.rb"
+  - "**/*.php"
+agent: security-scan
+---
+
+Scan code for security vulnerabilities:
+1. Authentication/authorization issues
+2. Input validation problems
+3. SQL injection risks
+4. XSS vulnerabilities
+5. Sensitive data exposure
+
+Only report actual security concerns. Do NOT report positive observations or "no issues found" messages.

package/src/defaults/rules/config-security.md

@@ -0,0 +1,18 @@
+---
+name: config-security
+description: Security scan for config files
+patterns:
+  - "**/*.json"
+  - "**/*.yaml"
+  - "**/*.yml"
+  - "**/*.toml"
+agent: security-scan
+---
+
+Scan configuration files for security issues:
+1. Hardcoded secrets or credentials
+2. Insecure default settings
+3. Exposed sensitive information
+4. Dangerous permissions
+
+Only report actual security risks. Do NOT report positive observations or "no issues found" messages.