codingbuddy-rules 4.3.0 → 4.4.0

package/.ai-rules/skills/legacy-modernization/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: legacy-modernization
+description: Use when modernizing legacy code or migrating outdated patterns to current best practices. Covers assessment, strangler fig pattern, incremental migration, and risk management.
+---
+
+# Legacy Modernization
+
+## Overview
+
+Legacy code isn't bad code — it's code that solved a real problem when it was written. Modernization is the process of adapting it to current requirements without breaking what works.
+
+**Core principle:** Never rewrite from scratch. Strangle it incrementally. Each step must leave the system in a working state.
+
+**Iron Law:**
+```
+THE SYSTEM MUST WORK AFTER EVERY CHANGE
+There is no "temporarily broken while we modernize"
+```
+
+## When to Use
+
+- Migrating from CommonJS to ESM
+- Upgrading major framework versions (NestJS 9 → 10)
+- Replacing callback patterns with async/await
+- Moving from JavaScript to TypeScript
+- Replacing deprecated APIs
+- Architectural migration (monolith → modules)
+
+## Assessment Phase
+
+### Inventory
+
+Before any changes, understand what you have:
+
+```bash
+# Size and complexity
+find src/ -name "*.ts" -o -name "*.js" | \
+  xargs wc -l | sort -rn | head -20
+
+# Dependency graph
+npx madge --circular src/
+
+# Test coverage (what's protected)
+npx jest --coverage --coverageReporters text-summary
+
+# Outdated packages
+npm outdated
+
+# Known patterns to modernize
+grep -rn "require\(" src/ --include="*.ts" | wc -l  # CommonJS in TypeScript
+grep -rn "callback\|\.then\|\.catch" src/ --include="*.ts" | wc -l  # Promises vs async
+grep -rn ": any" src/ --include="*.ts" | wc -l  # Untyped code
+```
+
+### Risk Assessment
+
+Rate each area for modernization risk:
+
+```markdown
+## Modernization Risk Register
+
+| Module | Lines | Test Coverage | External Deps | Criticality | Risk |
+|--------|-------|---------------|---------------|-------------|------|
+| rules.service.ts | 120 | 85% | None | High | LOW |
+| mcp.service.ts | 450 | 45% | MCP SDK | High | HIGH |
+| main.ts | 60 | 0% | NestJS | Medium | MEDIUM |
+
+Risk = (Criticality × (100 - Coverage%)) / 100
+```
+
+### Modernization Backlog
+
+```markdown
+## Modernization Items
+
+| ID | Pattern | Count | Files | Effort |
+|----|---------|-------|-------|--------|
+| M-001 | `any` type → explicit types | 23 | 8 files | 2h |
+| M-002 | Callbacks → async/await | 12 | 4 files | 4h |
+| M-003 | CommonJS → ESM imports | 45 | 15 files | 1h |
+| M-004 | NestJS 9 → NestJS 10 | 1 | package.json | 8h |
+```
+
+## Migration Strategies
+
+### Strategy 1: Strangler Fig (Recommended)
+
+Build new behavior alongside old behavior, gradually replacing old with new.
+
+```typescript
+// Phase 1: New implementation behind feature flag
+async getRules(): Promise<Rule[]> {
+  if (process.env.USE_NEW_RULES_ENGINE === 'true') {
+    return this.newRulesEngine.getRules(); // New implementation
+  }
+  return this.legacyGetRules(); // Old implementation still works
+}
+
+// Phase 2: Enable in staging, verify
+// Phase 3: Enable in production (10% → 50% → 100%)
+// Phase 4: Remove old implementation
+async getRules(): Promise<Rule[]> {
+  return this.newRulesEngine.getRules(); // Old code removed
+}
+```
+
+### Strategy 2: Branch by Abstraction
+
+1. Create abstraction over legacy code
+2. Implement new code behind abstraction
+3. Switch abstraction to new code
+4. Remove old code
+
+```typescript
+// Step 1: Introduce interface
+interface RulesEngine {
+  getRules(): Promise<Rule[]>;
+  searchRules(query: string): Promise<Rule[]>;
+}
+
+// Step 2: Wrap legacy code
+class LegacyRulesEngine implements RulesEngine {
+  // Existing code, now behind interface
+}
+
+// Step 3: New implementation
+class NewRulesEngine implements RulesEngine {
+  // Modern implementation
+}
+
+// Step 4: Switch (one line change)
+const rulesEngine: RulesEngine = new NewRulesEngine();
+// Was: new LegacyRulesEngine()
+```
+
+## Common Modernization Patterns
+
+### JavaScript → TypeScript
+
+```javascript
+// Before (JavaScript)
+function getUser(id) {
+  return fetch('/api/users/' + id)
+    .then(function(response) {
+      return response.json();
+    })
+    .then(function(data) {
+      return data.user;
+    });
+}
+```
+
+```typescript
+// After (TypeScript + async/await)
+async function getUser(id: string): Promise<User> {
+  const response = await fetch(`/api/users/${id}`);
+  const data: { user: User } = await response.json();
+  return data.user;
+}
+```
+
+### Callbacks → Async/Await
+
+```javascript
+// Before (callbacks)
+function readRule(path, callback) {
+  fs.readFile(path, 'utf8', function(err, content) {
+    if (err) return callback(err);
+    callback(null, parseRule(content));
+  });
+}
+```
+
+```typescript
+// After (async/await)
+async function readRule(path: string): Promise<Rule> {
+  const content = await fs.promises.readFile(path, 'utf-8');
+  return parseRule(content);
+}
+```
+
+### Removing `any` Types
+
+```typescript
+// Before
+function processRule(rule: any): any {
+  return { name: rule.name, content: rule.content };
+}
+
+// After (step 1: define interface)
+interface RuleInput {
+  name: string;
+  content: string;
+  [key: string]: unknown; // allow extra properties
+}
+
+interface ProcessedRule {
+  name: string;
+  content: string;
+}
+
+// After (step 2: type the function)
+function processRule(rule: RuleInput): ProcessedRule {
+  return { name: rule.name, content: rule.content };
+}
+```
+
+## Safe Migration Process
+
+```
+For EACH modernization item:
+
+1. WRITE TESTS (if coverage < 80%)
+   - Tests must cover current behavior
+   - These tests protect against regression
+
+2. MODERNIZE one file at a time
+   - Apply pattern change
+   - Keep behavior identical
+
+3. RUN ALL TESTS
+   - All existing tests must still pass
+   - No "we'll fix the tests later"
+
+4. COMMIT
+   - One commit per file or per pattern type
+   - Message: "refactor: migrate X to Y in Z"
+
+5. VERIFY in staging before next item
+```
+
+## Version Upgrade Process (Major Versions)
+
+```markdown
+## NestJS 9 → 10 Migration Plan
+
+### Preparation
+- [ ] Read migration guide: https://docs.nestjs.com/migration-guide
+- [ ] Test suite at 80%+ coverage
+- [ ] Feature branch created
+
+### Steps
+1. [ ] Update peer dependencies first
+2. [ ] Update NestJS packages
+3. [ ] Fix breaking API changes (see migration guide)
+4. [ ] Run test suite
+5. [ ] Fix type errors
+6. [ ] Test in staging
+7. [ ] Deploy to production
+
+### Rollback
+- git revert to previous package.json
+- npm install
+- Deploy previous version
+```
+
+## Risk Mitigation
+
+| Risk | Mitigation |
+|------|-----------|
+| Breaking working functionality | Write tests before modernizing |
+| Long migration blocks features | Use strangler fig pattern |
+| Merge conflicts | Small, frequent commits |
+| Regression in edge cases | Test coverage for edge cases first |
+| Team unfamiliar with new patterns | Document new patterns + pair programming |
+
+## Red Flags — STOP
+
+| Thought | Reality |
+|---------|---------|
+| "Let's rewrite it from scratch" | Rewrites take 3× longer and miss edge cases |
+| "We'll fix tests later" | Tests are the safety net — fix them now |
+| "One big refactoring PR" | Small PRs are safer and reviewable |
+| "The new code is obviously correct" | Verify with tests, not confidence |
+| "We can modernize while adding features" | Keep modernization commits separate |
+
+## Quick Reference
+
+```
+Migration Patterns:
+──────────────────────────────
+Strangler Fig  → New code wraps old, gradual replacement
+Branch by Abstraction → Interface first, then implementations
+Parallel Run   → Old and new run simultaneously, compare results
+Expand-Contract → Database: add new → migrate → remove old
+
+Priority Order:
+──────────────────────────────
+1. Highest risk (low coverage, high criticality) → test first
+2. Quick wins (high impact, low effort)
+3. Architectural changes (last, requires stability)
+```

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 |