cmp-standards 2.0.1 → 2.6.0

package/standards/skills/workflow-design.md

@@ -0,0 +1,323 @@
+# Diseño de Workflows con Skills
+
+## Concepto
+
+Un **workflow** es una secuencia de pasos que Claude ejecuta. Las skills definen workflows reutilizables.
+
+## Tipos de Workflows
+
+### 1. Linear Workflow
+
+Pasos en secuencia:
+
+```markdown
+---
+name: deploy
+description: Deploy to production
+---
+
+# Deploy Workflow
+
+## Steps (execute in order)
+
+1. **Verify** - Run tests and typecheck
+2. **Build** - Create production build
+3. **Deploy** - Push to production
+4. **Verify** - Check deployment health
+```
+
+### 2. Branching Workflow
+
+Decisiones basadas en condiciones:
+
+```markdown
+---
+name: fix-issue
+description: Fix a reported issue
+arguments:
+  - name: issueType
+    enum: [bug, performance, security]
+---
+
+# Fix Issue
+
+## Analyze
+
+First, identify the type of issue.
+
+## If bug
+1. Reproduce the issue
+2. Write failing test
+3. Fix the code
+4. Verify test passes
+
+## If performance
+1. Profile the code
+2. Identify bottleneck
+3. Optimize
+4. Benchmark improvement
+
+## If security
+1. Assess severity
+2. Create fix
+3. Run security scan
+4. Document in changelog
+```
+
+### 3. Iterative Workflow
+
+Repetir hasta condición:
+
+```markdown
+---
+name: refactor
+description: Iterative refactoring
+---
+
+# Refactor Workflow
+
+## Loop until complete
+
+1. **Identify** next refactoring opportunity
+2. **Apply** refactoring
+3. **Verify** tests still pass
+4. **Check** if more refactoring needed
+   - If yes: continue to step 1
+   - If no: complete workflow
+```
+
+### 4. Parallel Workflow
+
+Tareas independientes en paralelo:
+
+```markdown
+---
+name: full-check
+description: Run all checks
+---
+
+# Full Check Workflow
+
+## Run in parallel
+
+Execute these independently:
+- `npm run typecheck`
+- `npm run lint`
+- `npm run test`
+- `npm run build`
+
+## Collect results
+
+Report status of all checks.
+```
+
+## Integración con Expertos
+
+Para decisiones críticas, consultar `/experts`:
+
+```markdown
+---
+name: implement-feature
+description: Implement a new feature with expert review
+---
+
+# Implement Feature
+
+## 1. Plan
+
+Create implementation plan using TodoWrite.
+
+## 2. Implement
+
+Execute the plan step by step.
+
+## 3. Expert Review
+
+If touching critical paths (finance, auth, schema):
+
+```
+/experts [modified files]
+```
+
+Wait for approval before proceeding.
+
+## 4. Finalize
+
+If approved:
+- Run final verification
+- Create commit
+
+If rejected:
+- Address feedback
+- Return to step 2
+```
+
+## Workflows Estándar Recomendados
+
+### Feature Development
+
+```markdown
+1. Understand requirements
+2. Create plan (TodoWrite)
+3. Implement incrementally
+4. Write tests for critical paths
+5. Run verification (typecheck, lint)
+6. Expert review if critical
+7. Commit changes
+```
+
+### Bug Fix
+
+```markdown
+1. Reproduce issue
+2. Identify root cause
+3. Write failing test
+4. Implement fix
+5. Verify test passes
+6. Check for regressions
+7. Commit with issue reference
+```
+
+### Refactoring
+
+```markdown
+1. Identify scope
+2. Ensure test coverage
+3. Small, incremental changes
+4. Run tests after each change
+5. No behavior changes
+6. Commit atomically
+```
+
+## Estado y Tracking
+
+Usar TodoWrite para tracking:
+
+```markdown
+## Tracking
+
+Use TodoWrite to:
+- Create tasks at workflow start
+- Update status as you progress
+- Mark completed when done
+- Add discovered tasks as needed
+```
+
+## Memory Integration
+
+Registrar aprendizajes:
+
+```markdown
+## Learning Capture
+
+During workflow:
+- Capture new patterns discovered
+- Note gotchas for future reference
+- Record decisions made and why
+
+Use memory tools to persist learnings.
+```
+
+## Error Handling
+
+```markdown
+## If errors occur
+
+1. **Log** the error context
+2. **Analyze** root cause
+3. **Decide** next action:
+   - Retry if transient
+   - Ask user if unclear
+   - Abort if unrecoverable
+4. **Document** the issue if new pattern
+```
+
+## Composing Workflows
+
+Skills pueden llamar otras skills:
+
+```markdown
+---
+name: release
+description: Full release workflow
+---
+
+# Release
+
+## Steps
+
+1. Run `/full-check` - all validations
+2. Run `/changelog` - update changelog
+3. Run `/version-bump` - increment version
+4. Run `/deploy` - push to production
+5. Run `/notify` - send notifications
+```
+
+## Ejemplo Completo
+
+```markdown
+---
+name: add-api-endpoint
+description: Add new TRPC endpoint with full workflow
+arguments:
+  - name: routerName
+    required: true
+  - name: procedureName
+    required: true
+---
+
+# Add API Endpoint: {{routerName}}.{{procedureName}}
+
+## 1. Setup Tasks
+
+Create TodoWrite entries:
+- [ ] Create procedure in router
+- [ ] Add Zod schema
+- [ ] Write tests
+- [ ] Update client types
+
+## 2. Implementation
+
+### 2.1 Locate Router
+
+Find `src/server/api/routers/{{routerName}}.ts`
+
+### 2.2 Add Procedure
+
+```typescript
+{{procedureName}}: protectedProcedure
+  .input({{procedureName}}Schema)
+  .mutation(async ({ ctx, input }) => {
+    // Implementation
+  })
+```
+
+### 2.3 Add Schema
+
+```typescript
+const {{procedureName}}Schema = z.object({
+  // Define input schema
+})
+```
+
+## 3. Testing
+
+Create test at `src/server/api/routers/__tests__/{{routerName}}.test.ts`
+
+## 4. Verification
+
+Run:
+- `npm run typecheck`
+- `npm run test -- {{routerName}}`
+
+## 5. Expert Review
+
+If {{routerName}} is in critical path:
+```
+/experts src/server/api/routers/{{routerName}}.ts
+```
+
+## 6. Complete
+
+Mark all todos as completed.
+```

package/standards/tools/tool-design.md

@@ -0,0 +1,297 @@
+# Diseño de Tools Internas
+
+## Qué es una Tool
+
+Una **Tool** es una utilidad reutilizable que automatiza tareas comunes. Diferente de MCP tools, estas son funciones/scripts internos del proyecto.
+
+## Categorías
+
+### 1. CLI Tools
+
+Scripts ejecutables desde terminal:
+
+```
+scripts/
+├── checks/           # Validaciones
+│   ├── typecheck.mjs
+│   └── lint.mjs
+├── migration/        # Migraciones
+│   └── run-migration.mjs
+└── ai/               # AI-related
+    └── generate.mjs
+```
+
+### 2. Build Tools
+
+Parte del proceso de build:
+
+```typescript
+// tools/build/
+├── compile.ts
+├── bundle.ts
+└── optimize.ts
+```
+
+### 3. Dev Tools
+
+Para desarrollo local:
+
+```typescript
+// tools/dev/
+├── mock-server.ts
+├── seed-db.ts
+└── test-utils.ts
+```
+
+## Estructura de una CLI Tool
+
+```typescript
+#!/usr/bin/env node
+// scripts/my-tool.mjs
+
+import { parseArgs } from 'node:util'
+
+// 1. Parse arguments
+const { values, positionals } = parseArgs({
+  options: {
+    verbose: { type: 'boolean', short: 'v', default: false },
+    output: { type: 'string', short: 'o' }
+  },
+  allowPositionals: true
+})
+
+// 2. Validate input
+if (positionals.length === 0) {
+  console.error('Usage: my-tool <input> [--verbose] [--output path]')
+  process.exit(1)
+}
+
+// 3. Execute
+async function main() {
+  try {
+    const result = await doWork(positionals[0], values)
+    console.log('Done:', result)
+    process.exit(0)
+  } catch (error) {
+    console.error('Error:', error.message)
+    process.exit(1)
+  }
+}
+
+main()
+```
+
+## Patrones Recomendados
+
+### Patrón: Reporter
+
+Para tools que analizan y reportan:
+
+```typescript
+interface ReportResult {
+  passed: boolean
+  items: ReportItem[]
+  summary: string
+}
+
+async function analyze(path: string): Promise<ReportResult> {
+  const items = await scanFiles(path)
+  const issues = items.filter(i => !i.valid)
+
+  return {
+    passed: issues.length === 0,
+    items: issues,
+    summary: `Found ${issues.length} issues in ${items.length} files`
+  }
+}
+```
+
+### Patrón: Transformer
+
+Para tools que transforman archivos:
+
+```typescript
+interface TransformOptions {
+  input: string
+  output: string
+  dryRun?: boolean
+}
+
+async function transform(options: TransformOptions): Promise<void> {
+  const content = await readFile(options.input, 'utf-8')
+  const transformed = applyTransformations(content)
+
+  if (options.dryRun) {
+    console.log('Would write to:', options.output)
+    console.log(transformed)
+    return
+  }
+
+  await writeFile(options.output, transformed)
+}
+```
+
+### Patrón: Batch Processor
+
+Para operaciones sobre múltiples archivos:
+
+```typescript
+async function processBatch(
+  files: string[],
+  processor: (file: string) => Promise<void>
+): Promise<BatchResult> {
+  const results = await Promise.allSettled(
+    files.map(processor)
+  )
+
+  return {
+    total: files.length,
+    succeeded: results.filter(r => r.status === 'fulfilled').length,
+    failed: results.filter(r => r.status === 'rejected').length
+  }
+}
+```
+
+## Configuración
+
+### En package.json
+
+```json
+{
+  "scripts": {
+    "tool:analyze": "node scripts/analyze.mjs",
+    "tool:migrate": "node scripts/migrate.mjs",
+    "tool:generate": "node scripts/generate.mjs"
+  }
+}
+```
+
+### Con argumentos
+
+```json
+{
+  "scripts": {
+    "lint:all": "npm run lint -- --fix",
+    "check:verbose": "npm run check -- --verbose"
+  }
+}
+```
+
+## Logging
+
+```typescript
+// Usar chalk para colores
+import chalk from 'chalk'
+
+function log(level: 'info' | 'warn' | 'error', msg: string) {
+  const prefix = {
+    info: chalk.blue('ℹ'),
+    warn: chalk.yellow('⚠'),
+    error: chalk.red('✖')
+  }
+  console.error(`${prefix[level]} ${msg}`)
+}
+
+// Usar stderr para logs, stdout para output
+console.error('[INFO] Processing...')  // logs
+console.log(JSON.stringify(result))    // output (puede ser piped)
+```
+
+## Testing Tools
+
+```typescript
+import { describe, it, expect } from 'vitest'
+import { execSync } from 'child_process'
+
+describe('my-tool', () => {
+  it('should process valid input', () => {
+    const result = execSync('node scripts/my-tool.mjs input.txt')
+    expect(result.toString()).toContain('Done')
+  })
+
+  it('should fail on invalid input', () => {
+    expect(() => {
+      execSync('node scripts/my-tool.mjs')
+    }).toThrow()
+  })
+})
+```
+
+## Anti-Patterns
+
+### NO: Hardcoded paths
+
+```typescript
+// MAL
+const config = await readFile('/Users/carlos/project/config.json')
+
+// BIEN
+const config = await readFile(path.join(process.cwd(), 'config.json'))
+```
+
+### NO: Silent failures
+
+```typescript
+// MAL
+try {
+  await doWork()
+} catch {
+  // silencio
+}
+
+// BIEN
+try {
+  await doWork()
+} catch (error) {
+  console.error('Failed:', error.message)
+  process.exit(1)
+}
+```
+
+### NO: Sin validación de input
+
+```typescript
+// MAL
+async function main() {
+  await processFile(process.argv[2])
+}
+
+// BIEN
+async function main() {
+  const file = process.argv[2]
+  if (!file) {
+    console.error('Usage: tool <file>')
+    process.exit(1)
+  }
+  if (!existsSync(file)) {
+    console.error(`File not found: ${file}`)
+    process.exit(1)
+  }
+  await processFile(file)
+}
+```
+
+## Documentación
+
+Cada tool debe tener:
+
+1. **JSDoc header** con descripción y ejemplos
+2. **--help** flag que explica uso
+3. **README** si es compleja
+
+```typescript
+/**
+ * @file Analyze TypeScript files for common issues
+ * @example
+ * ```bash
+ * # Analyze single file
+ * npm run tool:analyze src/index.ts
+ *
+ * # Analyze directory
+ * npm run tool:analyze src/ --recursive
+ *
+ * # Output JSON
+ * npm run tool:analyze src/ --format json > report.json
+ * ```
+ */
+```