codingbuddy-rules 4.2.0 → 4.4.0

package/.ai-rules/skills/mcp-builder/SKILL.md

@@ -0,0 +1,356 @@
+---
+name: mcp-builder
+description: Use when building or extending MCP (Model Context Protocol) servers. Covers NestJS-based server design, Tools/Resources/Prompts capability design, transport implementation (stdio/SSE), and testing strategies.
+---
+
+# MCP Builder
+
+## Overview
+
+The Model Context Protocol (MCP) is the standard for connecting AI assistants to external tools, data, and prompts. Building a quality MCP server requires understanding the protocol's three capability types and implementing them with proper error handling and transport support.
+
+**Core principle:** MCP servers are AI interfaces, not REST APIs. Design for machine consumption and LLM context efficiency.
+
+**Iron Law:**
+```
+SCHEMA FIRST. Every Tool, Resource, and Prompt must have complete JSON Schema before implementation.
+```
+
+## When to Use
+
+- Creating a new MCP server from scratch
+- Adding new Tools, Resources, or Prompts to an existing server
+- Implementing new transport modes (stdio ↔ SSE)
+- Testing MCP server capabilities
+- Debugging MCP communication issues
+
+## MCP Architecture Overview
+
+```
+MCP Client (Claude, Cursor, etc.)
+        ↕  stdio / SSE
+MCP Server
+  ├── Tools      → Functions the AI can call (side effects allowed)
+  ├── Resources  → Data the AI can read (read-only, URI-addressed)
+  └── Prompts    → Reusable prompt templates
+```
+
+## NestJS MCP Server Structure
+
+```
+apps/mcp-server/src/
+├── main.ts              # Transport setup (stdio vs SSE)
+├── app.module.ts        # Root module
+├── mcp/
+│   ├── mcp.module.ts    # MCP module
+│   ├── mcp.service.ts   # MCP server registration
+│   ├── tools/           # Tool handlers
+│   ├── resources/       # Resource handlers
+│   └── prompts/         # Prompt handlers
+└── rules/
+    ├── rules.module.ts
+    └── rules.service.ts # Business logic (pure)
+```
+
+## Designing MCP Capabilities
+
+### Tools (AI can call these)
+
+Tools perform actions and return results. They CAN have side effects.
+
+```typescript
+// Tool Schema (define first)
+const searchRulesTool = {
+  name: 'search_rules',
+  description: 'Search AI coding rules by keyword or topic. Returns matching rules with their content.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: {
+        type: 'string',
+        description: 'Search term to find relevant rules',
+        minLength: 1,
+        maxLength: 200,
+      },
+      limit: {
+        type: 'number',
+        description: 'Maximum results to return (default: 10)',
+        minimum: 1,
+        maximum: 50,
+        default: 10,
+      },
+    },
+    required: ['query'],
+  },
+};
+```
+
+```typescript
+// Tool Handler
+@Injectable()
+export class SearchRulesHandler {
+  constructor(private readonly rulesService: RulesService) {}
+
+  async handle(params: { query: string; limit?: number }): Promise<ToolResult> {
+    // Validate input
+    if (!params.query?.trim()) {
+      return {
+        content: [{ type: 'text', text: 'Error: query is required' }],
+        isError: true,
+      };
+    }
+
+    try {
+      const results = await this.rulesService.search(params.query, {
+        limit: params.limit ?? 10,
+      });
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: results.length === 0
+              ? 'No rules found for: ' + params.query
+              : results.map(r => `## ${r.name}\n${r.content}`).join('\n\n'),
+          },
+        ],
+      };
+    } catch (error) {
+      return {
+        content: [{ type: 'text', text: `Error: ${error.message}` }],
+        isError: true,
+      };
+    }
+  }
+}
+```
+
+### Resources (AI can read these)
+
+Resources are read-only data exposed via URI. Use for static/cacheable content.
+
+```typescript
+// Resource definition
+const ruleResource = {
+  uri: 'rules://core',
+  name: 'Core Rules',
+  description: 'Core workflow rules (PLAN/ACT/EVAL modes)',
+  mimeType: 'text/markdown',
+};
+
+// Resource handler
+async readResource(uri: string): Promise<ResourceContent> {
+  const ruleName = uri.replace('rules://', '');
+  const content = await this.rulesService.getRule(ruleName);
+
+  if (!content) {
+    throw new Error(`Resource not found: ${uri}`);
+  }
+
+  return {
+    uri,
+    mimeType: 'text/markdown',
+    text: content,
+  };
+}
+```
+
+**Resource URI design:**
+```
+rules://core           → Core rules file
+rules://agents/list    → List of agents
+agents://planner       → Specific agent definition
+checklists://security  → Security checklist
+```
+
+### Prompts (Reusable templates)
+
+```typescript
+const activateAgentPrompt = {
+  name: 'activate_agent',
+  description: 'Generate activation prompt for a specialist agent',
+  arguments: [
+    {
+      name: 'agentName',
+      description: 'Name of the agent to activate (e.g., "solution-architect")',
+      required: true,
+    },
+    {
+      name: 'task',
+      description: 'Task description for the agent',
+      required: false,
+    },
+  ],
+};
+
+async getPrompt(name: string, args: Record<string, string>): Promise<PromptResult> {
+  if (name === 'activate_agent') {
+    const agent = await this.agentsService.getAgent(args.agentName);
+    return {
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `Activate the ${agent.displayName} specialist.\n\n${agent.systemPrompt}\n\n${args.task ?? ''}`,
+          },
+        },
+      ],
+    };
+  }
+  throw new Error(`Unknown prompt: ${name}`);
+}
+```
+
+## Transport Implementation
+
+### Stdio Transport (Default)
+
+```typescript
+// main.ts
+async function bootstrap() {
+  const transport = process.env.MCP_TRANSPORT ?? 'stdio';
+
+  if (transport === 'stdio') {
+    const app = await NestFactory.createApplicationContext(AppModule);
+    const mcpService = app.get(McpService);
+    await mcpService.startStdio();
+  } else {
+    const app = await NestFactory.create(AppModule);
+    await app.listen(process.env.PORT ?? 3000);
+  }
+}
+```
+
+### SSE Transport (HTTP)
+
+```typescript
+// SSE endpoint with optional auth
+@Get('/sse')
+@UseGuards(SseAuthGuard)
+async sse(@Req() req: Request, @Res() res: Response) {
+  const transport = new SSEServerTransport('/messages', res);
+  await this.mcpService.connect(transport);
+}
+
+@Post('/messages')
+@UseGuards(SseAuthGuard)
+async messages(@Req() req: Request, @Res() res: Response) {
+  await this.mcpService.handleMessage(req, res);
+}
+```
+
+```typescript
+// Auth guard
+@Injectable()
+export class SseAuthGuard implements CanActivate {
+  canActivate(context: ExecutionContext): boolean {
+    const token = process.env.MCP_SSE_TOKEN;
+    if (!token) return true; // Auth disabled if token not set
+
+    const request = context.switchToHttp().getRequest();
+    const provided = request.headers.authorization?.replace('Bearer ', '');
+    return provided === token;
+  }
+}
+```
+
+## Testing Strategy
+
+### Unit Tests (Tools/Resources)
+
+```typescript
+describe('SearchRulesHandler', () => {
+  let handler: SearchRulesHandler;
+  let rulesService: RulesService;
+
+  beforeEach(() => {
+    rulesService = new RulesService('./test-fixtures/.ai-rules');
+    handler = new SearchRulesHandler(rulesService);
+  });
+
+  it('returns results for valid query', async () => {
+    const result = await handler.handle({ query: 'TDD' });
+    expect(result.isError).toBeUndefined();
+    expect(result.content[0].text).toContain('TDD');
+  });
+
+  it('returns error for empty query', async () => {
+    const result = await handler.handle({ query: '' });
+    expect(result.isError).toBe(true);
+  });
+});
+```
+
+### Integration Tests (Protocol Level)
+
+```typescript
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+
+describe('MCP Server Integration', () => {
+  let client: Client;
+
+  beforeAll(async () => {
+    const transport = new StdioClientTransport({
+      command: 'node',
+      args: ['dist/main.js'],
+    });
+    client = new Client({ name: 'test', version: '1.0.0' }, {});
+    await client.connect(transport);
+  });
+
+  it('lists available tools', async () => {
+    const { tools } = await client.listTools();
+    expect(tools.map(t => t.name)).toContain('search_rules');
+  });
+
+  it('calls search_rules tool', async () => {
+    const result = await client.callTool({
+      name: 'search_rules',
+      arguments: { query: 'TDD' },
+    });
+    expect(result.isError).toBeFalsy();
+  });
+});
+```
+
+## Design Checklist
+
+```
+Tool Design:
+- [ ] Name is a verb or verb_noun (search_rules, get_agent)
+- [ ] Description explains WHAT and WHEN (for LLM to understand)
+- [ ] All parameters have descriptions and types
+- [ ] Required vs optional params clearly marked
+- [ ] Error responses use isError: true with descriptive messages
+- [ ] Input validated before processing
+
+Resource Design:
+- [ ] URI follows scheme://path pattern
+- [ ] mimeType set correctly (text/markdown, application/json)
+- [ ] Read-only (no side effects)
+- [ ] Returns 404-equivalent for missing resources
+
+Prompt Design:
+- [ ] Arguments have clear descriptions
+- [ ] Output is ready-to-use for the LLM
+- [ ] Does not duplicate Tool functionality
+
+Server:
+- [ ] Stdio and SSE transports both tested
+- [ ] Auth guard works when MCP_SSE_TOKEN is set
+- [ ] Auth disabled when MCP_SSE_TOKEN is unset
+- [ ] Error handling prevents server crashes
+```
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Tool does too many things | One Tool = one action |
+| Resource has side effects | Move to Tool if it changes state |
+| Schema has no descriptions | LLM uses descriptions to decide when/how to call |
+| No error handling in tools | Always catch and return isError: true |
+| Breaking stdio with console.log | Use stderr for logs: `process.stderr.write(...)` |
+| Hardcoded paths | Use env vars or config injection |

package/.ai-rules/skills/prompt-engineering/SKILL.md

@@ -0,0 +1,318 @@
+---
+name: prompt-engineering
+description: Use when writing prompts for AI tools, optimizing agent system prompts, or designing AI-readable instructions. Covers prompt structure, meta-prompting, chain-of-thought, and tool-specific optimization.
+---
+
+# Prompt Engineering
+
+## Overview
+
+A prompt is an API contract with an AI system. Precision matters. Ambiguous prompts produce inconsistent results; clear prompts produce consistent, predictable behavior.
+
+**Core principle:** Prompts are executable specifications. Write them like you write tests: with clear inputs, expected behavior, and success criteria.
+
+**Iron Law:**
+```
+TEST YOUR PROMPT WITH AT LEAST 3 DIFFERENT INPUTS BEFORE USING IN PRODUCTION
+One input is anecdote. Three is pattern. Ten is confidence.
+```
+
+## When to Use
+
+- Writing system prompts for codingbuddy agents
+- Creating CLAUDE.md / .cursorrules instructions
+- Designing tool descriptions for MCP servers
+- Optimizing prompts that produce inconsistent results
+- Building prompt chains for multi-step workflows
+
+## Prompt Anatomy
+
+Every effective prompt has these components:
+
+```
+┌─────────────────────────────────────────┐
+│ ROLE        Who/what is the AI?         │
+│ CONTEXT     What situation are we in?   │
+│ TASK        What specifically to do?    │
+│ CONSTRAINTS What rules must be obeyed?  │
+│ FORMAT      How to structure output?    │
+│ EXAMPLES    Show, don't just tell       │
+└─────────────────────────────────────────┘
+```
+
+Not every prompt needs all components, but most production prompts need most of them.
+
+## Prompt Patterns
+
+### Pattern 1: Role + Task (Basic)
+
+```
+You are a [specific role].
+
+Your task: [specific action] for [specific context].
+```
+
+**Example:**
+```
+You are a TypeScript code reviewer specializing in security.
+
+Your task: Review the authentication module below for OWASP Top 10 vulnerabilities.
+Output a list of findings ordered by severity (Critical → High → Medium → Low).
+```
+
+### Pattern 2: Chain-of-Thought (Complex Reasoning)
+
+Force step-by-step reasoning before conclusions:
+
+```
+Before answering, think through:
+1. [First consideration]
+2. [Second consideration]
+3. [Third consideration]
+
+Then provide your conclusion.
+```
+
+**Example:**
+```
+Before suggesting a fix, think through:
+1. What is the root cause of this bug?
+2. What are the possible fix approaches?
+3. What are the trade-offs of each approach?
+4. Which approach has the least risk?
+
+Then provide your recommendation with rationale.
+```
+
+### Pattern 3: Few-Shot (Examples)
+
+Show the AI what good output looks like:
+
+```
+[Task description]
+
+Examples:
+
+Input: [example input 1]
+Output: [example output 1]
+
+Input: [example input 2]
+Output: [example output 2]
+
+Now complete:
+Input: [actual input]
+Output:
+```
+
+**Example (agent expertise):**
+```
+Format agent expertise as specific, actionable skills.
+
+Examples:
+
+Input: security
+Output: "OWASP Top 10 Vulnerability Assessment", "JWT Authentication Design", "SQL Injection Prevention"
+
+Input: databases
+Output: "PostgreSQL Query Optimization", "Zero-Downtime Schema Migrations", "Connection Pool Tuning"
+
+Now complete:
+Input: frontend
+Output:
+```
+
+### Pattern 4: Constraint-First
+
+Lead with what NOT to do (especially useful for restrictive behaviors):
+
+```
+NEVER [prohibited action].
+ALWAYS [required action].
+If [edge case], then [specific handling].
+
+Your task: [task description]
+```
+
+**Example:**
+```
+NEVER include markdown formatting in your output — plain text only.
+ALWAYS include the file path in references (e.g., src/app.ts:42).
+If you are uncertain, say "I'm not sure" rather than guessing.
+
+Your task: Analyze the build error below and identify the root cause.
+```
+
+### Pattern 5: Meta-Prompting
+
+Prompt the AI to generate or improve prompts:
+
+```
+I need a prompt for [purpose].
+
+The prompt should:
+- [Requirement 1]
+- [Requirement 2]
+- [Requirement 3]
+
+Generate 3 prompt variations ranked from most to least structured.
+```
+
+## System Prompt Design (codingbuddy Agents)
+
+Agent system prompts follow a specific structure:
+
+```markdown
+# [Agent Display Name]
+
+You are a [role] specialist focused on [narrow domain].
+
+## Your Expertise
+
+You excel at:
+- [Specific skill 1 — concrete, not vague]
+- [Specific skill 2]
+- [Specific skill 3]
+
+## Your Approach
+
+When activated:
+1. [First action — what you always do first]
+2. [Analysis approach]
+3. [Output structure]
+
+## What You Do NOT Handle
+
+Redirect to appropriate specialists for:
+- [Out-of-scope 1] → use [other-agent-name]
+- [Out-of-scope 2] → use [other-agent-name]
+
+## Output Format
+
+Structure all responses as:
+### Findings
+[Severity: Critical/High/Medium/Low] — [Description]
+
+### Recommendations
+[Prioritized list]
+```
+
+## MCP Tool Description Design
+
+Tool descriptions are prompts read by AI to decide when and how to use a tool:
+
+```typescript
+{
+  name: 'search_rules',
+  // ❌ Bad: vague
+  description: 'Search rules',
+
+  // ✅ Good: specific use case + when to use
+  description: 'Search AI coding rules by keyword or topic. Use this when looking for specific guidelines about coding practices, TDD, security, or workflow modes. Returns matching rules with their content.',
+
+  inputSchema: {
+    properties: {
+      query: {
+        type: 'string',
+        // ❌ Bad: no guidance
+        description: 'Query string',
+
+        // ✅ Good: what makes a good query
+        description: 'Search term such as "TDD", "security", "TypeScript strict", or a question like "how to handle migrations"',
+      }
+    }
+  }
+}
+```
+
+## Prompt Testing
+
+### Test Matrix
+
+For each prompt, test these dimensions:
+
+| Dimension | Test Cases |
+|-----------|-----------|
+| Happy path | Ideal input, expected output |
+| Edge cases | Empty input, very long input, unusual characters |
+| Adversarial | Input designed to break the constraint |
+| Ambiguous | Input that could be interpreted multiple ways |
+
+### Evaluation Criteria
+
+```markdown
+## Prompt Evaluation Rubric
+
+**Accuracy:** Does output match expected behavior? (1-5)
+**Consistency:** Same input → same output across runs? (1-5)
+**Format compliance:** Does output match requested format? (1-5)
+**Boundary respect:** Does it honor constraints? (1-5)
+**Efficiency:** Is it unnecessarily verbose? (1-5)
+
+Total: 20 points. Target: ≥ 16 for production use.
+```
+
+## Tool-Specific Optimization
+
+### Claude Code (CLAUDE.md)
+
+```markdown
+## Best practices for Claude Code instructions:
+
+- Use ## headers to organize sections
+- Bold critical rules: **NEVER do X**
+- Use code blocks for exact command examples
+- Include trigger conditions: "When user types PLAN..."
+- Reference other files: "See .claude/rules/tool-priority.md"
+```
+
+### Cursor (.cursorrules)
+
+```markdown
+## Best practices for Cursor rules:
+
+- One rule per line for reliable parsing
+- Start each rule with the trigger: "When writing TypeScript..."
+- Avoid multi-paragraph rules (Cursor truncates)
+- Use concrete examples, not abstract principles
+```
+
+### GitHub Copilot (.github/copilot-instructions.md)
+
+```markdown
+## Best practices for Copilot instructions:
+
+- Lead with task-oriented rules
+- Examples are more effective than descriptions
+- Copilot follows "do X" more reliably than "don't do Y"
+- Keep total instructions under 8000 characters
+```
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Vague task ("be helpful") | Specific task ("list 3 alternatives with trade-offs") |
+| No format specification | Add explicit format: "Respond as JSON: {field: value}" |
+| Contradictory constraints | Test for conflicts before deploying |
+| No examples for complex tasks | Add 2-3 few-shot examples |
+| Testing with one input | Test with at least 3 diverse inputs |
+| Long monolithic prompt | Break into focused sections with headers |
+
+## Quick Reference
+
+```
+Prompt Length Guidelines:
+──────────────────────────
+Simple instruction    → 50-100 tokens
+Structured prompt     → 100-500 tokens
+Agent system prompt   → 500-2000 tokens
+Complex workflow      → 2000-4000 tokens
+(>4000 = consider splitting into sub-prompts)
+
+Reliability Ranking (most to least reliable):
+──────────────────────────────────────────────
+1. Explicit format + examples (highest)
+2. Explicit format, no examples
+3. Implicit format with examples
+4. Implicit format, no examples (lowest)
+```