codingbuddy-rules 5.0.0 → 5.1.1

package/.ai-rules/adapters/aider.md

@@ -0,0 +1,374 @@
+# Aider Integration Guide
+
+Guide for using codingbuddy with Aider (CLI AI pair programming tool).
+
+## Overview
+
+codingbuddy integrates with Aider through:
+
+1. **AGENTS.md** - Industry standard format compatible with all AI tools
+2. **CONVENTIONS.md** - Aider's native convention file format
+3. **`.aider.conf.yml`** - Aider configuration file
+
+## Two Usage Contexts
+
+### End Users (Your Project)
+
+End users provide codingbuddy rules to Aider via read-only convention files:
+
+```bash
+# Load codingbuddy rules as read-only context
+aider --read CONVENTIONS.md
+```
+
+Or configure in `.aider.conf.yml`:
+
+```yaml
+read:
+  - CONVENTIONS.md
+```
+
+### Monorepo Contributors
+
+Contributors to the codingbuddy repository can reference `.ai-rules/` files directly:
+
+```bash
+# Load multiple rule files as read-only context
+aider --read packages/rules/.ai-rules/rules/core.md \
+      --read packages/rules/.ai-rules/rules/augmented-coding.md \
+      --read packages/rules/.ai-rules/rules/project.md \
+      --read AGENTS.md
+```
+
+Or in `.aider.conf.yml`:
+
+```yaml
+read:
+  - packages/rules/.ai-rules/rules/core.md
+  - packages/rules/.ai-rules/rules/augmented-coding.md
+  - packages/rules/.ai-rules/rules/project.md
+  - AGENTS.md
+```
+
+## DRY Principle
+
+**Single Source of Truth**: `packages/rules/.ai-rules/`
+
+- All Agent definitions, rules, skills managed only in `.ai-rules/`
+- `CONVENTIONS.md` acts as a **pointer or summary** referencing `.ai-rules/`
+- No duplication; reference source files via `--read`
+
+## Aider Configuration System
+
+### `.aider.conf.yml`
+
+Aider's primary configuration file using YAML format. Loaded from these locations (in order, later files take priority):
+
+1. **Home directory** (`~/.aider.conf.yml`) - Global personal settings
+2. **Git root** (`.aider.conf.yml`) - Project-level settings
+3. **Current directory** (`.aider.conf.yml`) - Directory-specific settings
+
+### Configuration Example
+
+```yaml
+# .aider.conf.yml - codingbuddy integration
+
+# Load codingbuddy rules as read-only context
+read:
+  - CONVENTIONS.md
+  - AGENTS.md
+
+# Recommended settings for codingbuddy workflow
+auto-commits: true
+suggest-shell-commands: true
+```
+
+### List Format Options
+
+Lists can be specified as bullet lists or inline arrays:
+
+```yaml
+# Bullet list
+read:
+  - CONVENTIONS.md
+  - AGENTS.md
+
+# Inline array
+read: [CONVENTIONS.md, AGENTS.md]
+```
+
+### CONVENTIONS.md
+
+Aider's native mechanism for specifying coding guidelines. Create a `CONVENTIONS.md` in your project root:
+
+```markdown
+# Project Conventions
+
+## Workflow
+Follow PLAN/ACT/EVAL workflow modes.
+- Start in PLAN mode for analysis and planning
+- Move to ACT mode for implementation (TDD: Red -> Green -> Refactor)
+- Use EVAL mode for code quality evaluation
+
+## Code Quality
+- TypeScript strict mode (no `any`)
+- 90%+ test coverage goal
+- SOLID principles
+- No mocking - test real behavior
+
+## TDD Cycle
+1. Write a failing test (Red)
+2. Implement minimum code to pass (Green)
+3. Refactor for clarity (Refactor)
+
+## Project Structure
+See `packages/rules/.ai-rules/rules/project.md` for layered architecture details.
+
+## Specialist Agents
+See `packages/rules/.ai-rules/agents/README.md` for available specialists.
+```
+
+Load it with:
+
+```bash
+aider --read CONVENTIONS.md
+```
+
+> **Tip:** Use `--read` (read-only) instead of `--file` (editable) for convention files. This prevents accidental modifications and enables prompt caching.
+
+### `.aiderignore`
+
+Aider supports `.aiderignore` for excluding files from its context, using `.gitignore`-style patterns:
+
+```gitignore
+# .aiderignore
+node_modules/
+dist/
+*.min.js
+*.lock
+```
+
+Place in the git root directory. For custom ignore files, use `--aiderignore <filename>`.
+
+## Integration Methods
+
+### Method 1: CONVENTIONS.md (Recommended for End Users)
+
+Create a `CONVENTIONS.md` summarizing your project's coding standards, then load it as read-only context:
+
+```bash
+aider --read CONVENTIONS.md
+```
+
+### Method 2: Direct `.ai-rules/` References (Recommended for Contributors)
+
+Load specific rule files directly for comprehensive coverage:
+
+```yaml
+# .aider.conf.yml
+read:
+  - packages/rules/.ai-rules/rules/core.md
+  - packages/rules/.ai-rules/rules/augmented-coding.md
+  - packages/rules/.ai-rules/rules/project.md
+  - AGENTS.md
+```
+
+### Method 3: Combined Approach
+
+Use `CONVENTIONS.md` for quick reference and load detailed rules separately:
+
+```yaml
+# .aider.conf.yml
+read:
+  - CONVENTIONS.md
+  - packages/rules/.ai-rules/rules/core.md
+```
+
+## Directory Structure
+
+```
+project/
+├── .aider.conf.yml              # Aider configuration
+├── .aiderignore                 # File exclusion patterns
+├── CONVENTIONS.md               # Coding conventions (for Aider)
+├── AGENTS.md                    # Cross-platform agent definitions
+├── packages/rules/.ai-rules/
+│   ├── rules/
+│   │   ├── core.md
+│   │   ├── project.md
+│   │   └── augmented-coding.md
+│   ├── agents/
+│   │   └── *.json
+│   └── adapters/
+│       └── aider.md             # This guide
+└── ~/.aider.conf.yml            # Global user settings
+```
+
+## Usage
+
+### Basic Workflow
+
+```bash
+# Start Aider with codingbuddy conventions
+aider --read CONVENTIONS.md
+
+# In the Aider chat, reference workflow modes
+> Please follow PLAN mode to design this feature first
+
+# Add specific files for editing
+> /add src/auth/login.ts
+
+# Add read-only context
+> /read packages/rules/.ai-rules/agents/security-specialist.json
+```
+
+### In-Chat Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/add <file>` | Add file for editing |
+| `/read <file>` | Add file as read-only context |
+| `/drop <file>` | Remove file from context |
+| `/ask <question>` | Ask without making changes |
+| `/architect <request>` | Use architect mode for planning |
+
+### Architect Mode
+
+Aider's `/architect` command maps naturally to codingbuddy's PLAN mode:
+
+```bash
+# PLAN mode equivalent
+> /architect Design a user authentication system with JWT
+
+# ACT mode equivalent (regular chat)
+> Implement the authentication system following TDD
+```
+
+### Using Specialist Context
+
+Load specialist agent definitions as read-only context for focused reviews:
+
+```bash
+# Security review
+> /read packages/rules/.ai-rules/agents/security-specialist.json
+> Review the auth implementation from a security perspective
+
+# Performance review
+> /read packages/rules/.ai-rules/agents/performance-specialist.json
+> Analyze performance bottlenecks in this module
+```
+
+## Community Conventions
+
+Aider maintains a community conventions repository at [github.com/Aider-AI/conventions](https://github.com/Aider-AI/conventions) with pre-built convention files for various tech stacks. These can complement codingbuddy rules.
+
+## MCP Support
+
+> **Note:** As of early 2026, Aider does not natively support MCP servers. Rules integration relies on the `--read` flag and `CONVENTIONS.md` approach described above. If MCP support is added in the future, the same codingbuddy MCP server configuration used by other tools can be applied.
+
+### Workaround: Using Aider with MCP-Provided Rules
+
+Export rules from the MCP server to files, then load them in Aider:
+
+```bash
+# Export rules content to a file (manual step)
+# Then load in Aider
+aider --read exported-rules.md
+```
+
+## Skills
+
+Without MCP support, Aider accesses codingbuddy skills through file references:
+
+### Using Skills
+
+```bash
+# Load a skill as read-only context
+> /read packages/rules/.ai-rules/skills/systematic-debugging/SKILL.md
+> Debug this authentication failure using the systematic debugging approach
+
+> /read packages/rules/.ai-rules/skills/test-driven-development/SKILL.md
+> Implement this feature following TDD workflow
+```
+
+### Available Skills
+
+| Skill | File |
+|-------|------|
+| Systematic Debugging | `skills/systematic-debugging/SKILL.md` |
+| Test-Driven Development | `skills/test-driven-development/SKILL.md` |
+| Brainstorming | `skills/brainstorming/SKILL.md` |
+| Writing Plans | `skills/writing-plans/SKILL.md` |
+| Executing Plans | `skills/executing-plans/SKILL.md` |
+| Frontend Design | `skills/frontend-design/SKILL.md` |
+
+## Known Limitations
+
+Aider is a CLI tool with a different architecture than IDE-based AI assistants:
+
+| Feature | Status | Workaround |
+|---------|--------|------------|
+| **MCP Server support** | ❌ Not available | Use `--read` flag with convention/rule files |
+| **Mode keywords (PLAN/ACT/EVAL/AUTO)** | ❌ Not native | Manually instruct Aider to follow mode workflows |
+| **Specialist agent dispatch** | ❌ Not available | Load specialist JSON as read-only context with `/read` |
+| **Background subagents** | ❌ Not available | Sequential analysis only |
+| **Session hooks** | ❌ Not available | Rely on `.aider.conf.yml` for always-on settings |
+| **Context document persistence** | ❌ Not available | Manually manage context between sessions |
+| **Skills auto-detection** | ❌ Not available | Manually load skills via `/read` |
+| **Autonomous loop (AUTO mode)** | ❌ Not available | Use Aider's interactive chat loop manually |
+
+### Aider Strengths
+
+Despite these limitations, Aider offers unique advantages:
+
+- **CLI-native**: Works in any terminal, SSH sessions, CI/CD pipelines
+- **Git-aware**: Automatic commits, diff-based editing
+- **Repo-map**: Automatic codebase understanding via tree-sitter
+- **Multi-model**: Supports OpenAI, Anthropic, local models, and more
+- **Prompt caching**: Read-only files are cached for efficient token usage
+- **Architect mode**: Built-in plan-then-implement workflow
+
+## AGENTS.md
+
+Industry standard format compatible with all AI tools (Aider, Cursor, Claude Code, Codex, etc.):
+
+```markdown
+# AGENTS.md
+
+This project uses codingbuddy MCP server to manage AI Agents.
+
+## Quick Start
+...
+```
+
+See `AGENTS.md` in project root for details. Aider can read this file:
+
+```bash
+aider --read AGENTS.md
+```
+
+## Verification Status
+
+> Documentation based on Aider public documentation and community resources. Runtime verification has been performed for core features.
+
+| Pattern | Status | Notes |
+|---------|--------|-------|
+| `CONVENTIONS.md` loading via `--read` | ✅ Verified | Documented in official Aider docs |
+| `.aider.conf.yml` configuration | ✅ Verified | YAML format with multi-location loading |
+| `.aiderignore` file support | ✅ Verified | `.gitignore`-style patterns |
+| Read-only file context (`/read`) | ✅ Verified | Files cached with prompt caching enabled |
+| Architect mode for planning | ✅ Verified | Maps to PLAN mode workflow |
+| MCP server integration | ❌ Not supported | No native MCP support as of early 2026 |
+| AGENTS.md compatibility | ✅ Verified | Standard markdown, loadable via `--read` |
+| Community conventions repo | ✅ Verified | Available at github.com/Aider-AI/conventions |
+
+## Reference
+
+- [Aider Documentation](https://aider.chat/docs/)
+- [Aider Conventions Guide](https://aider.chat/docs/usage/conventions.html)
+- [Aider Configuration](https://aider.chat/docs/config/aider_conf.html)
+- [Aider Options Reference](https://aider.chat/docs/config/options.html)
+- [Aider In-Chat Commands](https://aider.chat/docs/usage/commands.html)
+- [Community Conventions Repository](https://github.com/Aider-AI/conventions)
+- [AGENTS.md Official Spec](https://agents.md)
+- [codingbuddy Documentation](../../docs/)