codingbuddy-rules 4.3.0 → 4.4.0

package/.ai-rules/skills/agent-design/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: agent-design
+description: Use when creating new specialist agent definitions for codingbuddy. Covers JSON schema design, expertise definition, system prompt authoring, and differentiation from existing agents.
+---
+
+# Agent Design
+
+## Overview
+
+Agents are specialist personas that AI assistants embody to provide focused, domain-specific guidance. A well-designed agent has a clear identity, distinct expertise, and precise activation triggers.
+
+**Core principle:** Each agent does ONE thing exceptionally well. Overlap is a design flaw.
+
+**Iron Law:**
+```
+DEFINE THE AGENT'S "NO" BEFORE DEFINING ITS "YES"
+What this agent explicitly does NOT handle is as important as what it does.
+```
+
+## When to Use
+
+- Adding a new specialist domain to codingbuddy
+- Improving an existing agent's focus and expertise
+- Designing agent activation trigger patterns
+- Reviewing agent differentiation before adding to the registry
+
+## Agent Schema Reference
+
+Agents are defined in `packages/rules/.ai-rules/agents/<name>.json` (filename is kebab-case):
+
+```json
+{
+  "name": "My Specialist",
+  "description": "One-sentence description of what this agent specializes in",
+  "role": {
+    "title": "Specialist Role Title",
+    "type": "specialist",
+    "expertise": [
+      "Domain Expertise Area 1",
+      "Domain Expertise Area 2",
+      "Domain Expertise Area 3"
+    ],
+    "responsibilities": [
+      "Key responsibility 1",
+      "Key responsibility 2"
+    ]
+  },
+  "context_files": [
+    ".ai-rules/rules/core.md",
+    ".ai-rules/rules/project.md"
+  ],
+  "modes": {
+    "planning": {
+      "activation": { "trigger": "When planning..." }
+    },
+    "evaluation": {
+      "activation": { "trigger": "When evaluating..." }
+    }
+  }
+}
+```
+
+### Required Fields
+
+| Field | Type | Rules |
+|-------|------|-------|
+| `name` | string | Display name, Title Case (e.g., "Migration Specialist") |
+| `description` | string | 10+ chars, one sentence |
+| `role` | object | Must include `title` at minimum |
+| `role.title` | string | Official role title |
+| `role.expertise` | string[] | 3-7 items, specific domains |
+| `context_files` | string[] | Paths starting with `.ai-rules/` |
+
+> **Note:** The JSON filename uses kebab-case (e.g., `migration-specialist.json`), while `name` is Title Case.
+
+### Optional Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `role.type` | string | `primary` (main agent in a mode) / `specialist` (domain reviews) |
+| `role.responsibilities` | string[] | Key responsibilities |
+| `modes.planning` | object | Planning mode activation config |
+| `modes.implementation` | object | Implementation mode activation config |
+| `modes.evaluation` | object | Evaluation mode activation config |
+| `activation` | object | Activation triggers, workflow integration |
+| `model` | object | Preferred AI model config (`preferred`, `reason`) |
+
+## Design Process
+
+### Phase 1: Define the Domain
+
+Answer these questions before writing any JSON:
+
+```
+1. What SPECIFIC problem domain does this agent own?
+   Example: "Database schema migrations with zero downtime"
+   NOT: "Databases" (too broad)
+
+2. What does this agent explicitly NOT handle?
+   Example: "Does not handle query optimization (→ performance-specialist)"
+
+3. What 3 things is this agent the BEST at?
+   (These become expertise items)
+
+4. Who calls this agent? (Which modes, which tasks)
+
+5. Name 3 existing agents. Is there overlap? If yes, redesign.
+```
+
+### Phase 2: Differentiation Check
+
+Before finalizing, compare against all existing agents:
+
+```bash
+# List all existing agents
+ls packages/rules/.ai-rules/agents/*.json | \
+  xargs -I{} jq -r '.name + ": " + .description' {}
+```
+
+**Overlap detection:**
+- If two agents share > 2 expertise items → merge or split differently
+- If trigger keywords match another agent → tighten the triggers
+- If the description could apply to another agent → rewrite
+
+### Phase 3: Write the System Prompt
+
+The system prompt is the agent's constitution. It must:
+
+```markdown
+# [DisplayName]
+
+You are a [Role] specialist agent focused on [narrow domain].
+
+## Your Expertise
+
+You excel at:
+- [Specific skill 1]
+- [Specific skill 2]
+- [Specific skill 3]
+
+## Your Approach
+
+When activated, you:
+1. [First thing you always do]
+2. [Second thing you always do]
+3. [How you structure your output]
+
+## What You DO NOT Handle
+
+Redirect to appropriate specialists for:
+- [Out-of-scope concern 1] → [other-agent]
+- [Out-of-scope concern 2] → [other-agent]
+
+## Output Format
+
+Always structure your responses as:
+- [Output element 1]
+- [Output element 2]
+```
+
+### Phase 4: Write the JSON
+
+Save as `packages/rules/.ai-rules/agents/migration-specialist.json`:
+
+```json
+{
+  "name": "Migration Specialist",
+  "description": "Zero-downtime database schema migration planning and execution specialist",
+  "role": {
+    "title": "Database Migration Engineer",
+    "type": "specialist",
+    "expertise": [
+      "Zero-Downtime Schema Changes",
+      "Expand-Contract Migration Pattern",
+      "Rollback Strategy Design",
+      "Large Data Migration Batching",
+      "Migration Validation Procedures"
+    ],
+    "responsibilities": [
+      "Plan and verify zero-downtime schema migrations",
+      "Design rollback strategies for all migration scenarios",
+      "Validate data integrity pre and post migration"
+    ]
+  },
+  "context_files": [
+    ".ai-rules/rules/core.md",
+    ".ai-rules/rules/project.md"
+  ],
+  "modes": {
+    "planning": {
+      "activation": {
+        "trigger": "When planning database schema migrations",
+        "auto_activate_conditions": ["Schema change planning", "Migration strategy design"]
+      }
+    },
+    "evaluation": {
+      "activation": {
+        "trigger": "When evaluating migration safety and rollback readiness"
+      }
+    }
+  }
+}
+```
+
+### Phase 5: Validate
+
+```bash
+# Validate JSON syntax
+cat packages/rules/.ai-rules/agents/my-agent.json | jq .
+
+# Check filename uniqueness (filenames are kebab-case)
+ls packages/rules/.ai-rules/agents/ | grep "my-agent"
+
+# Validate against schema (required: name, description, role, context_files)
+npx ajv validate \
+  -s packages/rules/.ai-rules/schemas/agent.schema.json \
+  -d packages/rules/.ai-rules/agents/my-agent.json
+```
+
+## Naming Conventions
+
+| Pattern | Example | Use for |
+|---------|---------|---------|
+| `<domain>-specialist` | `security-specialist` | Narrow domain expert |
+| `<role>-engineer` | `devops-engineer` | Engineering role |
+| `<role>-developer` | `frontend-developer` | Developer persona |
+| `<role>-architect` | `solution-architect` | Architecture role |
+| `<domain>-mode` | `plan-mode` | Workflow mode agent |
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Too broad ("backend developer") | Narrow to specific domain (e.g., "api-designer") |
+| Expertise overlaps with existing agent | Merge or redefine scope |
+| System prompt has no "you do NOT handle" | Every agent needs explicit boundaries |
+| Expertise items are vague ("databases") | Make specific ("PostgreSQL Query Optimization") |
+| No mode specified | Always define which PLAN/ACT/EVAL modes apply |
+| Filename uses camelCase | Use kebab-case for filenames (e.g., `my-agent.json`) |
+
+## Quick Reference
+
+```
+Agent Tier Definitions:
+─────────────────────────────
+primary     → Used as main agent in a mode (solution-architect, plan-mode)
+specialist  → Called in parallel for domain reviews (security-specialist)
+
+Mode Usage:
+─────────────────────────────
+PLAN   → Design, architecture, planning agents
+ACT    → Implementation, development agents
+EVAL   → Review, quality, security agents
+ALL    → Cross-cutting agents (code-reviewer)
+```
+
+## Checklist Before Adding Agent
+
+```
+- [ ] Domain is specific, not broad
+- [ ] No significant overlap with existing agents (< 2 shared expertise items)
+- [ ] System prompt includes "what this agent does NOT handle"
+- [ ] 3-7 expertise items, all specific
+- [ ] JSON validates against agent.schema.json
+- [ ] Filename follows kebab-case convention
+- [ ] Modes reflect actual usage patterns
+- [ ] README.md updated with new agent
+- [ ] Added to relevant adapter configurations
+```

package/.ai-rules/skills/code-explanation/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: code-explanation
+description: Use when explaining complex code to new team members, conducting code reviews, onboarding, or understanding unfamiliar codebases. Provides structured analysis from high-level overview to implementation details.
+---
+
+# Code Explanation
+
+## Overview
+
+Understanding code is a prerequisite to improving it. Rushed explanations create misunderstanding that compounds over time.
+
+**Core principle:** Explain at the right level of abstraction. Start high, drill down only when needed.
+
+**Iron Law:**
+```
+READ BEFORE EXPLAINING. UNDERSTAND BEFORE SIMPLIFYING.
+```
+
+Never explain code you haven't fully read. Never simplify what you haven't fully understood.
+
+## When to Use
+
+- Onboarding new team members to a codebase
+- Code review: explaining design decisions
+- Understanding legacy code before modifying it
+- Explaining an AI agent's recommendations
+- Documenting complex algorithms or patterns
+- Understanding error stack traces
+
+## The Five Levels of Explanation
+
+Choose the level based on your audience and purpose:
+
+| Level | Audience | Goal | Depth |
+|-------|----------|------|-------|
+| **L1: Bird's Eye** | Non-technical stakeholders | What does this system do? | Architecture diagram |
+| **L2: Module** | New developers | How is this organized? | Module/file structure |
+| **L3: Function** | Developers onboarding | What does this code do? | Function by function |
+| **L4: Line** | Debugging partners | Why is this written this way? | Line by line |
+| **L5: Algorithm** | Algorithm review | How does this work mathematically? | Proof-level |
+
+## The Explanation Process
+
+### Phase 1: Read First
+
+```
+1. Read the entire file/function before explaining anything
+2. Identify the core purpose (what problem does this solve?)
+3. Note dependencies (what does this require?)
+4. Note side effects (what does this change?)
+5. Note error handling (what can go wrong?)
+```
+
+### Phase 2: Bird's Eye View (Always Start Here)
+
+```markdown
+**What this is:** One sentence describing purpose
+**What problem it solves:** The business/technical need
+**How it fits:** Where it sits in the larger system
+**Key dependencies:** What it relies on
+**Key outputs:** What it produces or modifies
+```
+
+**Example:**
+```markdown
+**What this is:** RulesService — file system reader for AI coding rules
+**What problem it solves:** Provides a unified interface for reading and searching
+  .ai-rules files regardless of directory structure
+**How it fits:** Used by McpModule to serve rules via MCP protocol
+**Key dependencies:** Node.js fs/promises, glob patterns
+**Key outputs:** Array of Rule objects with name, content, and metadata
+```
+
+### Phase 3: Structure Walk-Through
+
+Walk through the code structure before implementation details:
+
+```typescript
+// Before explaining each function, show the structure:
+
+class RulesService {
+  // 1. Constructor — sets up file paths
+  constructor() { ... }
+
+  // 2. getRules() — entry point, returns all rules
+  async getRules(): Promise<Rule[]> { ... }
+
+  // 3. searchRules() — filters rules by query
+  async searchRules(query: string): Promise<Rule[]> { ... }
+
+  // 4. Private: readRuleFile() — reads individual file
+  private async readRuleFile(path: string): Promise<Rule> { ... }
+}
+```
+
+### Phase 4: Deep Dive (Only When Requested)
+
+Explain non-obvious implementation choices:
+
+```typescript
+// ❓ "Why is this using glob instead of fs.readdir?"
+// ✅ "glob allows pattern matching across nested directories
+//    (.ai-rules/**/*.md) without manual recursion. readdir
+//    only lists one directory level."
+
+const files = await glob('**/*.md', { cwd: this.rulesDir });
+```
+
+```typescript
+// ❓ "Why is this async even though it looks synchronous?"
+// ✅ "File I/O is always async in Node.js to avoid blocking
+//    the event loop. Even a small file read blocks for ~1-5ms
+//    which multiplies badly under load."
+
+const content = await fs.readFile(filePath, 'utf-8');
+```
+
+### Phase 5: Mental Model
+
+Finish with a mental model the reader can hold in their head:
+
+```
+RulesService mental model:
+─────────────────────────
+  .ai-rules/             ← Root directory
+  └── rules/core.md      ← Each .md file becomes a Rule
+  └── agents/planner.json ← Each .json becomes an Agent
+
+  getRules() = "read all files, return as array"
+  searchRules() = "filter that array by content match"
+  getAgent() = "read specific JSON file, parse it"
+```
+
+## Explanation Templates
+
+### For Functions
+
+```markdown
+### `functionName(params): returnType`
+
+**Purpose:** [One sentence — what does it do?]
+
+**Parameters:**
+- `param1` — [What it represents, valid range/values]
+- `param2` — [What it represents, valid range/values]
+
+**Returns:** [What is returned, in what shape]
+
+**Side effects:** [What does it change outside itself?]
+
+**Error cases:** [What errors can it throw and when?]
+
+**Example:**
+\`\`\`typescript
+const result = functionName('input', { option: true });
+// result === { expected: 'output' }
+\`\`\`
+```
+
+### For Classes
+
+```markdown
+### `ClassName`
+
+**Responsibility:** [Single responsibility in one sentence]
+
+**Lifecycle:**
+1. Construction — [What happens when created]
+2. Usage — [How it's used]
+3. Cleanup — [Any teardown needed]
+
+**Key methods:**
+- `method1()` — [Purpose]
+- `method2()` — [Purpose]
+
+**Dependencies injected:**
+- `Dependency1` — [Why it needs this]
+```
+
+### For Complex Algorithms
+
+```markdown
+### Algorithm: [Name]
+
+**Problem:** [What problem does this solve?]
+
+**Approach:** [High-level strategy]
+
+**Complexity:** O([time]) time, O([space]) space
+
+**Step-by-step walkthrough:**
+
+Given input `[example input]`:
+1. Step 1 → intermediate result
+2. Step 2 → intermediate result
+3. Final step → `[expected output]`
+
+**Edge cases handled:**
+- Empty input: [behavior]
+- Single element: [behavior]
+- Duplicate values: [behavior]
+```
+
+## Onboarding Guide Format
+
+When explaining a whole codebase to a new team member:
+
+```markdown
+# [Project Name] Codebase Guide
+
+## In 30 Seconds
+
+[What this system does, who uses it, why it exists]
+
+## Mental Model
+
+[ASCII diagram of key components and data flow]
+
+## Start Here
+
+1. Read `src/main.ts` — entry point
+2. Read `src/app.module.ts` — understand module structure
+3. Read `src/mcp/mcp.service.ts` — core business logic
+
+## Key Concepts
+
+**[Concept 1]:** [Explanation with code example]
+**[Concept 2]:** [Explanation with code example]
+
+## Common Tasks
+
+- "How do I add a new rule?" → See `packages/rules/.ai-rules/`
+- "How do I add a new agent?" → See `packages/rules/.ai-rules/agents/`
+- "How do I run tests?" → `yarn test`
+
+## What to Avoid
+
+- [Common mistake 1 and why]
+- [Common mistake 2 and why]
+```
+
+## Red Flags — STOP
+
+| Thought | Reality |
+|---------|---------|
+| "I'll explain as I read" | Read first, explain second |
+| "The code is self-explanatory" | It's never self-explanatory to someone new |
+| "Just look at the tests" | Tests explain behavior, not intent |
+| "I'll summarize without reading" | Summaries from unread code spread misinformation |
+
+## Quick Reference
+
+| Situation | Explanation Level |
+|-----------|------------------|
+| New to project | L1 → L2 → L3 on request |
+| Code review | L3 — function by function |
+| Debugging together | L4 — line by line |
+| Algorithm discussion | L5 — mathematical |
+| Stakeholder demo | L1 only |