codingbuddy-rules 4.4.0 → 5.0.0

package/.ai-rules/skills/mcp-builder/examples/tool-example.ts

@@ -0,0 +1,203 @@
+/**
+ * MCP Tool Implementation Example
+ *
+ * Demonstrates a complete Tool handler following the MCP specification.
+ * Tools are functions the AI can call that may have side effects.
+ *
+ * Key patterns:
+ * - Schema-first design with JSON Schema validation
+ * - Structured error responses with isError flag
+ * - Input validation before processing
+ * - NestJS injectable service pattern
+ */
+
+import { Injectable } from '@nestjs/common';
+
+// --- 1. Define the Tool Schema (JSON Schema) ---
+
+export const fileAnalyzerToolSchema = {
+  name: 'analyze_file',
+  description:
+    'Analyze a source file for code quality metrics including complexity, ' +
+    'line count, and dependency analysis. Use when reviewing code quality ' +
+    'or planning refactoring.',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      filePath: {
+        type: 'string',
+        description: 'Relative path to the file from project root (e.g., "src/utils/parser.ts")',
+        minLength: 1,
+        maxLength: 500,
+      },
+      metrics: {
+        type: 'array',
+        description: 'Specific metrics to analyze (default: all)',
+        items: {
+          type: 'string',
+          enum: ['complexity', 'lines', 'dependencies', 'exports'],
+        },
+        default: ['complexity', 'lines', 'dependencies', 'exports'],
+      },
+      includeSource: {
+        type: 'boolean',
+        description: 'Whether to include the source code in the response (default: false)',
+        default: false,
+      },
+    },
+    required: ['filePath'],
+  },
+};
+
+// --- 2. Define Result Types ---
+
+interface ToolResult {
+  content: Array<{ type: 'text'; text: string }>;
+  isError?: boolean;
+}
+
+interface FileAnalysis {
+  filePath: string;
+  lineCount: number;
+  complexity: number;
+  dependencies: string[];
+  exports: string[];
+}
+
+// --- 3. Implement the Tool Handler ---
+
+@Injectable()
+export class FileAnalyzerHandler {
+  constructor(private readonly fileService: FileService) {}
+
+  async handle(params: {
+    filePath: string;
+    metrics?: string[];
+    includeSource?: boolean;
+  }): Promise<ToolResult> {
+    // Step 1: Validate input
+    if (!params.filePath?.trim()) {
+      return this.errorResult('filePath is required and cannot be empty');
+    }
+
+    if (params.filePath.includes('..')) {
+      return this.errorResult('filePath cannot contain path traversal (..)');
+    }
+
+    // Step 2: Check file exists
+    const exists = await this.fileService.exists(params.filePath);
+    if (!exists) {
+      return this.errorResult(`File not found: ${params.filePath}`);
+    }
+
+    // Step 3: Perform analysis
+    try {
+      const analysis = await this.analyze(params.filePath, params.metrics);
+      const output = this.formatAnalysis(analysis, params.includeSource);
+
+      return {
+        content: [{ type: 'text', text: output }],
+      };
+    } catch (error) {
+      return this.errorResult(
+        `Analysis failed for ${params.filePath}: ${(error as Error).message}`,
+      );
+    }
+  }
+
+  private async analyze(
+    filePath: string,
+    metrics?: string[],
+  ): Promise<FileAnalysis> {
+    const content = await this.fileService.read(filePath);
+    const lines = content.split('\n');
+    const selected = new Set(metrics ?? ['complexity', 'lines', 'dependencies', 'exports']);
+
+    return {
+      filePath,
+      lineCount: selected.has('lines') ? lines.length : -1,
+      complexity: selected.has('complexity') ? this.calculateComplexity(lines) : -1,
+      dependencies: selected.has('dependencies') ? this.extractDependencies(lines) : [],
+      exports: selected.has('exports') ? this.extractExports(lines) : [],
+    };
+  }
+
+  private calculateComplexity(lines: string[]): number {
+    const complexityKeywords = /\b(if|else|for|while|switch|case|catch|&&|\|\||\?)\b/g;
+    return lines.reduce((sum, line) => {
+      const matches = line.match(complexityKeywords);
+      return sum + (matches?.length ?? 0);
+    }, 1); // Base complexity of 1
+  }
+
+  private extractDependencies(lines: string[]): string[] {
+    const importPattern = /^import\s+.*from\s+['"]([^'"]+)['"]/;
+    return lines
+      .map((line) => line.match(importPattern)?.[1])
+      .filter((dep): dep is string => dep !== undefined);
+  }
+
+  private extractExports(lines: string[]): string[] {
+    const exportPattern = /^export\s+(?:default\s+)?(?:class|function|const|interface|type|enum)\s+(\w+)/;
+    return lines
+      .map((line) => line.match(exportPattern)?.[1])
+      .filter((name): name is string => name !== undefined);
+  }
+
+  private formatAnalysis(analysis: FileAnalysis, includeSource?: boolean): string {
+    const sections: string[] = [
+      `## File Analysis: ${analysis.filePath}`,
+      '',
+    ];
+
+    if (analysis.lineCount >= 0) {
+      sections.push(`**Lines:** ${analysis.lineCount}`);
+    }
+    if (analysis.complexity >= 0) {
+      sections.push(`**Cyclomatic Complexity:** ${analysis.complexity}`);
+    }
+    if (analysis.dependencies.length > 0) {
+      sections.push('', '**Dependencies:**');
+      analysis.dependencies.forEach((dep) => sections.push(`- \`${dep}\``));
+    }
+    if (analysis.exports.length > 0) {
+      sections.push('', '**Exports:**');
+      analysis.exports.forEach((exp) => sections.push(`- \`${exp}\``));
+    }
+
+    return sections.join('\n');
+  }
+
+  private errorResult(message: string): ToolResult {
+    return {
+      content: [{ type: 'text', text: `Error: ${message}` }],
+      isError: true,
+    };
+  }
+}
+
+// --- 4. Register in MCP Service ---
+
+/*
+// In mcp.service.ts:
+import { fileAnalyzerToolSchema, FileAnalyzerHandler } from './tools/file-analyzer';
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [fileAnalyzerToolSchema],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  switch (request.params.name) {
+    case 'analyze_file':
+      return this.fileAnalyzerHandler.handle(request.params.arguments);
+    default:
+      throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);
+  }
+});
+*/
+
+// Placeholder for dependency injection
+interface FileService {
+  exists(path: string): Promise<boolean>;
+  read(path: string): Promise<string>;
+}

package/.ai-rules/skills/mcp-builder/references/protocol-spec.md

@@ -0,0 +1,215 @@
+# MCP Protocol Quick Reference
+
+## Protocol Overview
+
+The Model Context Protocol (MCP) uses JSON-RPC 2.0 over stdio or HTTP+SSE transport. Servers expose three capability types: **Tools**, **Resources**, and **Prompts**.
+
+## JSON-RPC 2.0 Message Format
+
+### Request
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/call",
+  "params": {
+    "name": "search_rules",
+    "arguments": { "query": "TDD" }
+  }
+}
+```
+
+### Response (Success)
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "content": [{ "type": "text", "text": "..." }]
+  }
+}
+```
+
+### Response (Error)
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "error": {
+    "code": -32601,
+    "message": "Method not found"
+  }
+}
+```
+
+## Capability Methods
+
+### Tools
+
+| Method | Direction | Description |
+|--------|-----------|-------------|
+| `tools/list` | Client → Server | List available tools with schemas |
+| `tools/call` | Client → Server | Execute a tool by name with arguments |
+
+**Tool Result Shape:**
+
+```typescript
+interface ToolResult {
+  content: ContentBlock[];  // text, image, or resource content
+  isError?: boolean;        // true if the tool encountered an error
+}
+
+type ContentBlock =
+  | { type: 'text'; text: string }
+  | { type: 'image'; data: string; mimeType: string }
+  | { type: 'resource'; resource: ResourceContent };
+```
+
+### Resources
+
+| Method | Direction | Description |
+|--------|-----------|-------------|
+| `resources/list` | Client → Server | List available resources |
+| `resources/templates/list` | Client → Server | List URI templates for dynamic resources |
+| `resources/read` | Client → Server | Read a resource by URI |
+| `notifications/resources/list_changed` | Server → Client | Notify resource list changed |
+
+**Resource Shape:**
+
+```typescript
+interface Resource {
+  uri: string;          // e.g., "rules://core"
+  name: string;         // Human-readable name
+  description?: string; // What this resource contains
+  mimeType?: string;    // e.g., "text/markdown", "application/json"
+}
+
+interface ResourceContent {
+  uri: string;
+  mimeType?: string;
+  text?: string;   // For text content
+  blob?: string;   // For binary content (base64)
+}
+```
+
+### Prompts
+
+| Method | Direction | Description |
+|--------|-----------|-------------|
+| `prompts/list` | Client → Server | List available prompt templates |
+| `prompts/get` | Client → Server | Get a prompt with arguments filled in |
+
+**Prompt Shape:**
+
+```typescript
+interface Prompt {
+  name: string;
+  description?: string;
+  arguments?: PromptArgument[];
+}
+
+interface PromptArgument {
+  name: string;
+  description?: string;
+  required?: boolean;
+}
+
+interface GetPromptResult {
+  messages: Array<{
+    role: 'user' | 'assistant';
+    content: TextContent | ImageContent | EmbeddedResource;
+  }>;
+}
+```
+
+## Initialization Handshake
+
+```
+Client                          Server
+  |                                |
+  |-- initialize ----------------->|   (capabilities, clientInfo)
+  |<-- initialize result ----------|   (capabilities, serverInfo)
+  |-- notifications/initialized -->|   (confirm ready)
+  |                                |
+  |-- tools/list ----------------->|   (discover tools)
+  |-- resources/list ------------->|   (discover resources)
+  |-- prompts/list --------------->|   (discover prompts)
+```
+
+### Server Capabilities Declaration
+
+```typescript
+const serverCapabilities = {
+  tools: {},                    // Server provides tools
+  resources: {
+    subscribe: true,            // Supports resource subscriptions
+    listChanged: true,          // Sends list_changed notifications
+  },
+  prompts: {
+    listChanged: true,          // Sends list_changed notifications
+  },
+};
+```
+
+## Transport Modes
+
+### Stdio
+
+- Server reads JSON-RPC from stdin, writes to stdout
+- Logs MUST go to stderr (never stdout)
+- One message per line (newline-delimited JSON)
+- No HTTP overhead, fastest for local use
+
+### HTTP + SSE
+
+- Client opens SSE connection at `GET /sse`
+- Server sends `endpoint` event with message URL
+- Client sends JSON-RPC via `POST /messages`
+- Server streams responses via SSE
+
+```
+Client                              Server
+  |                                    |
+  |-- GET /sse ----------------------->|   (open SSE stream)
+  |<-- event: endpoint ---------------|   (data: /messages?sessionId=abc)
+  |                                    |
+  |-- POST /messages?sessionId=abc --->|   (JSON-RPC request)
+  |<-- event: message ----------------|   (JSON-RPC response via SSE)
+```
+
+## Error Codes
+
+| Code | Name | Description |
+|------|------|-------------|
+| `-32700` | Parse error | Invalid JSON |
+| `-32600` | Invalid request | Missing required fields |
+| `-32601` | Method not found | Unknown method |
+| `-32602` | Invalid params | Wrong parameter types |
+| `-32603` | Internal error | Server-side error |
+
+## Input Schema Best Practices
+
+- Always set `type: 'object'` at the top level
+- Mark required parameters in the `required` array
+- Add `description` to every property (LLMs use these to decide how to call)
+- Use `minLength`, `maximum`, `enum` constraints where applicable
+- Set sensible `default` values for optional parameters
+
+## URI Scheme Conventions
+
+```
+scheme://authority/path
+
+rules://core                   → Core rules
+rules://augmented-coding       → Augmented coding rules
+agents://solution-architect    → Agent definition
+config://project               → Project config
+skills://mcp-builder           → Skill content
+```
+
+- Use lowercase, hyphen-separated paths
+- Scheme should indicate the resource domain
+- Path should be human-readable and predictable

package/.ai-rules/skills/performance-optimization/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: performance-optimization
 description: Use when optimizing code performance, addressing slowness complaints, or measuring application speed improvements
+context: fork
+agent: general-purpose
+allowed-tools: Read, Grep, Glob, Bash
 ---
 
 # Performance Optimization

package/.ai-rules/skills/plan-and-review/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: plan-and-review
+description: Use when creating implementation plans that need quality review before execution — 4-phase workflow combining plan creation with automated plan-reviewer validation
+---
+
+# Plan and Review
+
+## Overview
+
+Create implementation plans and validate them through automated review before execution. This skill combines the writing-plans methodology with plan-reviewer agent dispatch to catch quality issues (missing file paths, vague acceptance criteria, scope gaps, TDD omissions) before any code is written.
+
+**Announce at start:** "I'm using the plan-and-review skill to create and validate the implementation plan."
+
+**Core principle:** No plan reaches execution without passing review. Critical/High findings must be resolved first.
+
+## The 4 Phases
+
+```
+Phase 1: Create Plan → Phase 2: Review → Phase 3: Revise (if needed) → Phase 4: Approved
+```
+
+### Phase 1: Create Plan
+
+Use the writing-plans methodology to create the implementation plan.
+
+1. **Invoke the writing-plans skill** (superpowers:writing-plans or equivalent)
+2. Follow all writing-plans requirements:
+   - Bite-sized tasks (2-5 minutes each)
+   - Exact file paths for all changes
+   - TDD structure (Red-Green-Refactor) for core logic
+   - Complete code in plan (no placeholders)
+   - Alternatives exploration for non-trivial decisions
+3. Save plan to `docs/plans/YYYY-MM-DD-<feature-name>.md`
+
+### Phase 2: Dispatch Plan Reviewer
+
+Dispatch the plan-reviewer agent as a subAgent to review the plan.
+
+1. **Dispatch plan-reviewer** using the Agent tool:
+   ```
+   subagent_type: "general-purpose"
+   prompt: |
+     You are the Plan Reviewer agent. Review the implementation plan at
+     docs/plans/<plan-file>.md against the original spec/issue.
+
+     Review checklist:
+     - File paths: All paths valid (Modify files exist, Create paths have valid parents)
+     - Acceptance criteria: Specific, measurable, verifiable (no vague terms)
+     - Scope alignment: Plan matches spec — no scope creep, no missing items
+     - TDD compliance: Red-Green-Refactor for core logic tasks
+     - Backward compatibility: Breaking changes documented with migration steps
+
+     Output a severity-rated findings table:
+     | Finding | Location | Severity | Recommendation |
+
+     End with Review Summary showing counts per severity and verdict:
+     APPROVED (Critical=0 AND High=0) or REVISE REQUIRED.
+   ```
+2. Collect the review results
+
+### Phase 3: Revise Plan (if Critical/High findings)
+
+If the review verdict is **REVISE REQUIRED**:
+
+1. Read each Critical and High finding
+2. Revise the plan to address each finding:
+   - Fix invalid file paths
+   - Make acceptance criteria specific and testable
+   - Add missing spec requirements as tasks
+   - Add TDD structure where missing
+   - Document breaking changes with migration steps
+3. Save the revised plan (overwrite the same file)
+4. **Re-dispatch plan-reviewer** (return to Phase 2)
+5. Repeat until verdict is **APPROVED**
+
+**Maximum iterations:** 3 revision cycles. If still not approved after 3 cycles, present remaining findings to user for manual resolution.
+
+### Phase 4: Plan Approved
+
+When the review verdict is **APPROVED**:
+
+1. Announce: "Plan approved by plan-reviewer — ready for execution."
+2. Present remaining Medium/Low findings as optional improvements
+3. Offer execution choice:
+   - **Subagent-Driven (this session):** Use superpowers:subagent-driven-development
+   - **Parallel Session (separate):** Use superpowers:executing-plans
+
+## When to Use This Skill
+
+- Creating implementation plans for non-trivial features
+- Plans that will be executed by other agents or in separate sessions
+- When plan quality is critical (e.g., parallel execution with multiple workers)
+- When the spec is complex and scope alignment matters
+
+## When NOT to Use This Skill
+
+- Single-file changes or trivial fixes
+- Plans you will execute yourself immediately in the same session
+- Exploratory prototyping where the plan will evolve rapidly
+
+## Integration with Parallel Orchestrator
+
+When used within parallel execution workflows:
+
+- The conductor generates worker directives that include plan creation
+- Each worker can use this skill to self-validate their plan before ACT mode
+- The plan-reviewer findings feed into the conductor's quality gates
+
+## Key Principles
+
+- **No plan without review** — every plan gets at least one review pass
+- **Severity drives action** — Critical/High must be fixed, Medium/Low are optional
+- **Evidence-based findings** — every finding references a specific plan section
+- **Bounded iteration** — maximum 3 revision cycles to prevent infinite loops
+- **Clear verdict** — APPROVED or REVISE REQUIRED, no ambiguity

package/.ai-rules/skills/pr-all-in-one/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: pr-all-in-one
 description: Unified commit and PR workflow. Auto-commits changes, creates/updates PRs with smart issue linking and multi-language support.
+disable-model-invocation: true
+argument-hint: [target-branch] [issue-id]
 ---
 
 # PR All-in-One
@@ -92,7 +94,7 @@ Step 7: Update existing PR (if exists)
 │   └── "bilingual" → Bilingual Template
 ├── Generate title:
 │   ├── "en"/"bilingual" → English title
-│   └── "ko" → 한국어 title
+│   └── "ko" → Korean title
 ├── Generate body with selected template
 ├── Merge with .github/pull_request_template.md (if exists)
 ├── NO AI signature
@@ -107,7 +109,7 @@ Step 8: Create new PR (if not exists)
 │   └── "bilingual" → Bilingual Template
 ├── Generate title:
 │   ├── "en"/"bilingual" → English (e.g., "feat: add auth")
-│   └── "ko" → 한국어 (e.g., "feat: 인증 추가")
+│   └── "ko" → Korean (e.g., "feat: add authentication")
 ├── Generate body with selected template + commit analysis
 ├── Merge with project template if exists
 ├── NO AI signature
@@ -246,22 +248,22 @@ N/A (no UI changes)
 
 #### When `prLanguage: "ko"`
 
-**Title**: `feat: 사용자 인증 추가`
+**Title**: `feat: add user authentication`
 
 **Body**:
 ```markdown
-## 컨텍스트
+## Context
 
-**관련 링크:**
-- 이슈: [AUTH-123](https://jira.example.com/browse/AUTH-123)
+**Related Links:**
+- Issue: [AUTH-123](https://jira.example.com/browse/AUTH-123)
 
-**상세 설명:**
+**Description Details:**
 
-JWT 기반 인증과 리프레시 토큰 지원을 추가했습니다.
+Added JWT-based authentication with refresh token support.
 
-## 스크린샷 또는 비디오
+## Screenshots or Videos
 
-N/A (UI 변경 없음)
+N/A (no UI changes)
 ```
 
 #### When `prLanguage: "bilingual"`
@@ -281,13 +283,13 @@ Added JWT-based authentication with refresh token support.
 
 ---
 
-**상세 설명:**
+**Description Details (Korean):**
 
-JWT 기반 인증과 리프레시 토큰 지원을 추가했습니다.
+Added JWT-based authentication with refresh token support. (Korean translation here)
 
 ## Screenshots or Videos
 
-N/A (no UI changes / UI 변경 없음)
+N/A (no UI changes)
 ```
 
 ### Template Definitions

package/.ai-rules/skills/pr-all-in-one/configuration-guide.md

@@ -42,7 +42,7 @@ The skill uses an interactive 4-step configuration flow:
   [3/4] PR Language
   ┌──────────────────────────┐
   │ PR description language  │
-  │ [English] [한국어]        │
+  │ [English] [Korean]        │
   │ [Bilingual] (EN + KO)    │
   └──────────────────────────┘
        ⬇
@@ -78,7 +78,7 @@ Selects which issue tracking system is used:
 
 Determines the language for PR descriptions:
 - **English**: PRs written in English only
-- **한국어**: PRs written in Korean only
+- **Korean**: PRs written in Korean only
 - **Bilingual**: PRs include both English and Korean
 
 ##### Detailed Language Behavior
@@ -86,7 +86,7 @@ Determines the language for PR descriptions:
 | Value | PR Title | PR Body | Use Case |
 |-------|----------|---------|----------|
 | `en` | English | English only | International teams, open source projects |
-| `ko` | 한국어 | 한국어만 | Korean-only teams, internal projects |
+| `ko` | Korean | Korean only | Korean-only teams, internal projects |
 | `bilingual` | English | English + Korean | Mixed teams, global + local collaboration |
 
 ##### Language Examples
@@ -97,14 +97,14 @@ Determines the language for PR descriptions:
 - Best for: Open source, international collaboration
 
 **`ko` (Korean)**:
-- Title: `feat: 사용자 인증 추가`
-- Body: 한국어만 사용한 설명
-- Best for: 한국어 기반 팀, 내부 프로젝트
+- Title: `feat: add user authentication`
+- Body: Korean-only description
+- Best for: Korean-speaking teams, internal projects
 
 **`bilingual` (Both)**:
 - Title: `feat: add user authentication` (English)
 - Body: English description followed by Korean translation
-- Best for: 글로벌 팀과 한국 팀이 함께 협업하는 프로젝트
+- Best for: Projects where global and Korean teams collaborate together
 
 #### Step 4: Issue URL Template
 Optional template for auto-generating issue links in PR bodies. Use `{id}` placeholder for the issue ID.