cmp-standards 2.0.1 → 2.4.0

package/standards/mcp/tool-patterns.md

@@ -0,0 +1,354 @@
+# Patrones de Diseño para MCP Tools
+
+## Patrón: CRUD Básico
+
+Para entidades que necesitan operaciones estándar:
+
+```typescript
+// tools/entity.ts
+export const entityTools = [
+  {
+    name: 'entity_create',
+    description: 'Create a new entity',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        title: { type: 'string' },
+        data: { type: 'object' }
+      },
+      required: ['title']
+    }
+  },
+  {
+    name: 'entity_get',
+    description: 'Get entity by ID',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string' }
+      },
+      required: ['id']
+    }
+  },
+  {
+    name: 'entity_list',
+    description: 'List entities with optional filters',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        limit: { type: 'number', default: 10 },
+        filter: { type: 'object' }
+      }
+    }
+  },
+  {
+    name: 'entity_update',
+    description: 'Update entity by ID',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string' },
+        updates: { type: 'object' }
+      },
+      required: ['id', 'updates']
+    }
+  },
+  {
+    name: 'entity_delete',
+    description: 'Delete entity by ID',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string' }
+      },
+      required: ['id']
+    }
+  }
+]
+```
+
+## Patrón: Search Tool
+
+Para búsquedas con múltiples criterios:
+
+```typescript
+{
+  name: 'memory_search',
+  description: 'Search memories by content, domain, tags, or date range',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: {
+        type: 'string',
+        description: 'Text to search in title and body'
+      },
+      domain: {
+        type: 'string',
+        description: 'Filter by domain (e.g., "architecture", "performance")'
+      },
+      tags: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Filter by tags (AND logic)'
+      },
+      dateFrom: {
+        type: 'string',
+        description: 'ISO date string for start range'
+      },
+      dateTo: {
+        type: 'string',
+        description: 'ISO date string for end range'
+      },
+      limit: {
+        type: 'number',
+        default: 10,
+        description: 'Max results to return'
+      }
+    }
+  }
+}
+```
+
+**Handler Pattern:**
+
+```typescript
+async function handleSearch(args: SearchArgs) {
+  const conditions: SQL[] = []
+
+  if (args.query) {
+    conditions.push(
+      or(
+        like(memories.title, `%${args.query}%`),
+        like(memories.body, `%${args.query}%`)
+      )
+    )
+  }
+
+  if (args.domain) {
+    conditions.push(eq(memories.domain, args.domain))
+  }
+
+  // Build query with all conditions
+  const results = await db.query.memories.findMany({
+    where: and(...conditions),
+    limit: args.limit ?? 10,
+    orderBy: desc(memories.createdAt)
+  })
+
+  return results
+}
+```
+
+## Patrón: Batch Operations
+
+Para operaciones sobre múltiples items:
+
+```typescript
+{
+  name: 'tasks_batch_update',
+  description: 'Update status of multiple tasks at once',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      ids: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Task IDs to update'
+      },
+      status: {
+        type: 'string',
+        enum: ['pending', 'in_progress', 'completed']
+      }
+    },
+    required: ['ids', 'status']
+  }
+}
+```
+
+**Handler con Promise.all:**
+
+```typescript
+async function handleBatchUpdate(args: BatchUpdateArgs) {
+  const results = await Promise.allSettled(
+    args.ids.map(id =>
+      db.update(tasks)
+        .set({ status: args.status, updatedAt: new Date() })
+        .where(eq(tasks.id, id))
+    )
+  )
+
+  const succeeded = results.filter(r => r.status === 'fulfilled').length
+  const failed = results.filter(r => r.status === 'rejected').length
+
+  return {
+    total: args.ids.length,
+    succeeded,
+    failed
+  }
+}
+```
+
+## Patrón: Aggregation Tool
+
+Para datos agregados/estadísticas:
+
+```typescript
+{
+  name: 'analytics_summary',
+  description: 'Get aggregated analytics for a time period',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      period: {
+        type: 'string',
+        enum: ['day', 'week', 'month'],
+        default: 'week'
+      },
+      metrics: {
+        type: 'array',
+        items: {
+          type: 'string',
+          enum: ['memories_created', 'patterns_detected', 'tasks_completed']
+        }
+      }
+    }
+  }
+}
+```
+
+## Patrón: Composite Tool
+
+Cuando una operación necesita múltiples pasos:
+
+```typescript
+{
+  name: 'session_init',
+  description: 'Initialize a new work session with context loading',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      projectPath: { type: 'string' },
+      loadMemories: { type: 'boolean', default: true },
+      checkPatterns: { type: 'boolean', default: true }
+    },
+    required: ['projectPath']
+  }
+}
+```
+
+**Handler:**
+
+```typescript
+async function handleSessionInit(args: SessionInitArgs) {
+  const results: Record<string, unknown> = {}
+
+  // Step 1: Load project config
+  results.config = await loadProjectConfig(args.projectPath)
+
+  // Step 2: Parallel operations
+  const [memories, patterns] = await Promise.all([
+    args.loadMemories ? loadRecentMemories() : [],
+    args.checkPatterns ? detectPatterns() : []
+  ])
+
+  results.memories = memories
+  results.patterns = patterns
+
+  // Step 3: Generate context summary
+  results.summary = generateContextSummary(results)
+
+  return results
+}
+```
+
+## Patrón: Validation Tool
+
+Para validar datos antes de operaciones costosas:
+
+```typescript
+{
+  name: 'schema_validate',
+  description: 'Validate data against a schema before processing',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      schemaName: { type: 'string' },
+      data: { type: 'object' }
+    },
+    required: ['schemaName', 'data']
+  }
+}
+```
+
+## Anti-Patterns
+
+### NO: Tools Demasiado Genéricas
+
+```typescript
+// MAL - demasiado genérica
+{
+  name: 'do_database_operation',
+  inputSchema: {
+    properties: {
+      operation: { type: 'string' },  // "insert", "update", "delete"
+      table: { type: 'string' },
+      data: { type: 'object' }
+    }
+  }
+}
+
+// BIEN - específica y clara
+{
+  name: 'memory_create',
+  // ...
+}
+```
+
+### NO: Tools con Demasiados Parámetros
+
+```typescript
+// MAL - 15 parámetros
+{
+  name: 'complex_search',
+  inputSchema: {
+    properties: {
+      // ... 15 propiedades
+    }
+  }
+}
+
+// BIEN - dividir en tools más simples
+{
+  name: 'search_by_content',
+  // 2-3 parámetros
+}
+{
+  name: 'search_by_metadata',
+  // 2-3 parámetros
+}
+```
+
+### NO: Efectos Secundarios Ocultos
+
+```typescript
+// MAL - hace más de lo que dice
+async function handleGetMemory(id: string) {
+  const memory = await getMemory(id)
+  await updateAccessCount(id)  // Efecto secundario oculto
+  await logAccess(id)          // Otro efecto secundario
+  return memory
+}
+
+// BIEN - solo hace lo que dice
+async function handleGetMemory(id: string) {
+  return await getMemory(id)
+}
+```
+
+## Tips de Rendimiento
+
+1. **Paginación obligatoria** para list operations
+2. **Índices** en campos de búsqueda
+3. **Caché** para datos que no cambian frecuentemente
+4. **Parallel queries** con Promise.all cuando son independientes
+5. **Streaming** para respuestas grandes (futuro de MCP)

package/standards/skills/skill-structure.md

@@ -0,0 +1,286 @@
+# Estructura de Skills
+
+## Qué es una Skill
+
+Una **Skill** es un conjunto de instrucciones que Claude Code puede ejecutar. Se invocan con `/skill-name` y expanden a un prompt completo.
+
+## Ubicaciones
+
+```
+.claude/
+├── skills/                    # Project skills
+│   ├── commit.md
+│   ├── review-pr.md
+│   └── create-component.md
+└── settings.json              # Skill registration
+
+~/.claude/
+└── skills/                    # Global skills
+    └── my-global-skill.md
+```
+
+## Anatomía de una Skill
+
+```markdown
+---
+name: create-component
+description: Create a new React component with tests
+arguments:
+  - name: componentName
+    description: Name of the component
+    required: true
+  - name: type
+    description: Component type
+    enum: [page, feature, ui]
+    default: feature
+---
+
+# Create Component: {{componentName}}
+
+## Instructions
+
+1. Create the component file at `src/components/{{type}}/{{componentName}}.tsx`
+2. Create the test file at `src/components/{{type}}/{{componentName}}.test.tsx`
+3. Export from barrel file
+
+## Component Template
+
+```tsx
+export function {{componentName}}() {
+  return <div>{{componentName}}</div>
+}
+```
+
+## Test Template
+
+```tsx
+import { render, screen } from '@testing-library/react'
+import { {{componentName}} } from './{{componentName}}'
+
+describe('{{componentName}}', () => {
+  it('renders', () => {
+    render(<{{componentName}} />)
+    expect(screen.getByText('{{componentName}}')).toBeInTheDocument()
+  })
+})
+```
+```
+
+## Frontmatter
+
+```yaml
+---
+name: skill-name           # Required: kebab-case
+description: Brief desc    # Required: <100 chars
+arguments:                 # Optional: arguments
+  - name: argName
+    description: What it is
+    required: true/false
+    default: value
+    enum: [opt1, opt2]
+---
+```
+
+## Variables
+
+Usar `{{variable}}` para interpolación:
+
+```markdown
+# Task: {{taskName}}
+
+Working on component {{componentName}} in {{directory}}.
+```
+
+## Categorías de Skills
+
+### 1. Workflow Skills
+
+Automatizan flujos de trabajo comunes:
+
+```markdown
+---
+name: commit
+description: Create a git commit with conventional format
+---
+
+# Commit Changes
+
+1. Run `git status` to see changes
+2. Run `git diff` to review changes
+3. Create commit message following conventional commits
+4. Execute `git commit -m "message"`
+```
+
+### 2. Generator Skills
+
+Crean código/archivos:
+
+```markdown
+---
+name: create-router
+description: Create a new TRPC router
+arguments:
+  - name: routerName
+    required: true
+---
+
+# Create Router: {{routerName}}
+
+Create file at `src/server/api/routers/{{routerName}}.ts`
+```
+
+### 3. Analysis Skills
+
+Analizan código/proyecto:
+
+```markdown
+---
+name: review-pr
+description: Review pull request changes
+arguments:
+  - name: prNumber
+    required: true
+---
+
+# Review PR #{{prNumber}}
+
+1. Fetch PR changes
+2. Analyze for security issues
+3. Check code quality
+4. Provide feedback
+```
+
+### 4. Documentation Skills
+
+Generan documentación:
+
+```markdown
+---
+name: document-api
+description: Generate API documentation
+---
+
+# Document API
+
+1. Scan all TRPC routers
+2. Extract procedure signatures
+3. Generate markdown docs
+```
+
+## Registrar Skills
+
+En `.claude/settings.json`:
+
+```json
+{
+  "skills": [
+    {
+      "name": "create-component",
+      "file": ".claude/skills/create-component.md"
+    },
+    {
+      "name": "commit",
+      "file": ".claude/skills/commit.md"
+    }
+  ]
+}
+```
+
+## Best Practices
+
+### 1. Instrucciones Claras
+
+```markdown
+# BIEN
+1. First, read the existing component at `src/components/Button.tsx`
+2. Create new variant following the same pattern
+3. Add to exports in `src/components/index.ts`
+
+# MAL
+Create a component somehow and put it somewhere.
+```
+
+### 2. Contexto Necesario
+
+```markdown
+# BIEN
+## Context
+This project uses:
+- React 19 with Server Components
+- Tailwind CSS for styling
+- Shadcn UI components
+
+## Task
+Create component following these conventions.
+
+# MAL
+Create a component.
+```
+
+### 3. Ejemplos Concretos
+
+```markdown
+## Example
+
+Input: `/create-component UserProfile page`
+
+Creates:
+- `src/components/page/UserProfile.tsx`
+- `src/components/page/UserProfile.test.tsx`
+- Updates `src/components/page/index.ts`
+```
+
+### 4. Manejo de Errores
+
+```markdown
+## If errors occur
+
+1. If component already exists: ask user to confirm overwrite
+2. If directory missing: create it
+3. If imports fail: check barrel exports exist
+```
+
+## Anti-Patterns
+
+### NO: Skills demasiado genéricas
+
+```markdown
+# MAL
+---
+name: do-stuff
+description: Does things
+---
+
+Do whatever the user wants.
+```
+
+### NO: Sin estructura clara
+
+```markdown
+# MAL
+Create component and test and export and also maybe some types.
+```
+
+### NO: Hardcoded values
+
+```markdown
+# MAL
+Create file at `/Users/carlos/project/src/Component.tsx`
+
+# BIEN
+Create file at `src/components/{{componentName}}.tsx`
+```
+
+## Testing Skills
+
+Antes de registrar una skill:
+
+1. Probar con diferentes argumentos
+2. Verificar que maneja edge cases
+3. Confirmar que sigue los estándares del proyecto
+
+```bash
+# Test skill manually
+/create-component TestComponent feature
+# Verify output matches expectations
+```