@saulwade/swl-ses 1.0.0

package/habilidades/estructura-proyecto-claude/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: estructura-proyecto-claude
+description: >
+  Genera y valida estructuras de proyecto Claude-ready según las guías oficiales
+  "Claude Code Project Structure" y "Claude Code Workflow Cheatsheet".
+  Cargar al inicializar proyecto nuevo, migrar proyecto existente al sistema SWL,
+  auditar estructura Claude-ready, agregar extensiones (commands, skills, agents,
+  hooks, plugins), o configurar MCP. Cubre arquitectura de 4 capas, jerarquía
+  de memoria, 6 tipos de extensión, 27 hook events, frontmatter de skills/agents/commands
+  y settings avanzados.
+version: "1.0.0"
+herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep]
+exclusiones:
+  - "No cargar para iniciar un proyecto desde cero — ese flujo usa `/swl:nuevo-proyecto` que incluye entrevista de contexto antes de generar la estructura; este skill genera estructura pero no recoge requisitos de negocio."
+  - "No cargar para agregar o actualizar un agente o skill específico dentro de un proyecto ya estructurado — eso es trabajo directo sobre el frontmatter del componente; cargar este skill solo cuando se auditea o crea la estructura completa del proyecto."
+  - "No cargar para configurar permisos de tools individuales en un agente — `seguridad-agentes` cubre la decisión de permisos; este skill cubre la estructura del proyecto, no la política de permisos de cada agente."
+  - "No cargar solo para leer la documentación de un tipo de extensión Claude Code — la guía oficial vía Context7 MCP es más actualizada para detalles de API específicos de extensiones."
+evolvable: true  # default para skill estandar
+---
+# Estructura de Proyecto Claude-ready
+
+Fuentes oficiales:
+- `referencias/Claude Code Project Structure.jpg`
+- `referencias/Claude Code WorkFlow Cheatsheet.jpg`
+- https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
+
+## Cuándo cargar esta skill
+
+- Se inicializa un proyecto nuevo (`/swl:nuevo-proyecto`)
+- Se migra un proyecto existente al sistema SWL
+- Se audita si un proyecto tiene estructura Claude-ready correcta
+- Se agregan extensiones (commands, skills, agents, hooks, plugins)
+- Se configura MCP para un proyecto
+
+---
+
+## Estructura base oficial
+
+```
+mi_proyecto/
++-- CLAUDE.md                              # Fuente de verdad del proyecto (L1)
++-- .claude/
+|   +-- settings.json                      # Permisos, hooks y context rules
+|   +-- settings.local.json                # Config local (NUNCA commitear)
+|   +-- commands/                          # Slash commands del proyecto
+|   +-- skills/                            # Módulos de capacidad (L2)
+|   |   +-- nombre-skill/
+|   |       +-- SKILL.md
+|   |       +-- scripts/, references/, assets/
+|   +-- agents/                            # Subagentes del proyecto (L4)
+|   +-- hooks/                             # Automatizaciones event-driven (L3)
+|   +-- rules/                             # Reglas con scope por paths
+|   +-- plugins/                           # Plugins distribuibles
++-- .planning/                             # Estado de planificación SWL
+|   +-- PROYECTO.md, REQUISITOS.md, HOJA-RUTA.md, ESTADO.md
+|   +-- research/
++-- .mcp.json                              # Configuracion de servidores MCP
+```
+
+---
+
+## Arquitectura de 4 capas
+
+| Capa | Componente | Propósito |
+|------|-----------|-----------|
+| **L1** | **CLAUDE.md** | Contexto persistente — cargado SIEMPRE al inicio |
+| **L2** | **Skills** | Conocimiento versionado — cargados por coincidencia |
+| **L3** | **Hooks** | Seguridad y automatización — event-driven |
+| **L4** | **Agents** | Subagentes con contexto propio — ejecución aislada |
+
+---
+
+## Jerarquía de memoria CLAUDE.md
+
+| Scope | Path | Aplica a |
+|-------|------|----------|
+| **Managed Policy** | Sistema | Todos los usuarios org |
+| **User** | `~/.claude/CLAUDE.md` | Todos tus proyectos |
+| **Project** | `./CLAUDE.md` | Proyecto (repo) |
+| **Subdirectory** | `packages/frontend/CLAUDE.md` | Paquete del monorepo |
+
+### Comportamiento de carga
+
+- **Ancestor (ARRIBA)**: al inicio, carga TODOS los CLAUDE.md desde cwd hasta la raíz del sistema de archivos — siempre se cargan
+- **Descendant (ABAJO)**: lazy — solo carga cuando Claude navega a un subdirectorio
+- **Siblings**: NUNCA se cargan entre sí
+- Solo las **primeras 200 líneas** de cada CLAUDE.md se inyectan al prompt del sistema
+
+**Reglas clave**: Menos de 200 líneas por CLAUDE.md. Subdirectorios agregan, NUNCA sobreescriben.
+
+---
+
+## 6 tipos de extensión
+
+| Tipo | Activación | Ubicación |
+|------|-----------|-----------|
+| **Skills** | Auto-activación | `.claude/skills/` |
+| **Commands** | Manual (`/comando`) | `.claude/commands/` |
+| **Subagents** | Spawn por orquestador | `.claude/agents/` |
+| **Hooks** | Event-driven | `settings.json` hooks |
+| **MCP Servers** | Siempre disponibles | `.mcp.json` |
+| **Plugins** | Instalación | `.claude/plugins/` |
+
+---
+
+## Anatomía de una skill — Tres niveles de carga
+
+| Nivel | Qué carga | Cuándo | Costo |
+|-------|-----------|--------|-------|
+| **Level 1** | Frontmatter (name + description) | Siempre | ~100 tokens |
+| **Level 2** | Cuerpo de SKILL.md | Al activarse | <5k tokens |
+| **Level 3** | scripts/, references/, assets/ | Bajo demanda | Sin límite |
+
+### Frontmatter completo de SKILL.md
+
+```yaml
+---
+name: nombre-skill              # kebab-case, max 64 chars
+description: >                  # max 1024 chars — QUÉ + CUÁNDO
+  Describe qué hace y cuándo Claude debe auto-activarla.
+allowed-tools: ["Read", "Grep", "Glob"]
+paths:
+  - "src/api/**/*.ts"
+context: fork                   # fork = subagente aislado
+---
+```
+
+Ver referencia completa en [recursos/frontmatter-y-hooks-referencia.md](recursos/frontmatter-y-hooks-referencia.md).
+
+---
+
+## Hook Events (14 críticos de 27 oficiales)
+
+| Evento | Cuándo se dispara | Uso típico |
+|--------|-------------------|-----------|
+| **PreToolUse** | Antes de ejecutar herramienta | Bloquear ops inseguras |
+| **PostToolUse** | Después de ejecutar herramienta | Auto-lint, format |
+| **SessionStart** | Al iniciar sesión | Cargar contexto |
+| **Stop** | Al completar respuesta | Verificar tarea |
+| **PreCompact** | Antes de compactar | Salvar estado crítico |
+| **PostCompact** | Después de compactar | Re-inyectar contexto |
+| **Notification** | Claude espera input | Alertas desktop |
+
+Los 20 eventos restantes, frontmatter de agents (16 campos) y commands (13 campos),
+opciones avanzadas de hooks y orden de resolución en
+[recursos/frontmatter-y-hooks-referencia.md](recursos/frontmatter-y-hooks-referencia.md).
+
+---
+
+## 7 secciones obligatorias de CLAUDE.md
+
+| # | Sección | Contenido |
+|---|---------|-----------|
+| 1 | **Tech Stack** | Lenguaje, framework, BD, herramientas con versiones |
+| 2 | **Conventions** | Estilo, tipo hints, formato, imports |
+| 3 | **Architecture** | Directorios clave y qué contiene cada uno |
+| 4 | **Security** | No secretos, validación, queries parametrizadas |
+| 5 | **Testing** | Framework de tests, cómo correr, cobertura mínima |
+| 6 | **Git Workflow** | Branch strategy, commit format, PR rules |
+| 7 | **Common Workflows** | Comandos de build, test, deploy, dev server |
+
+Ver template completo en [recursos/claude-md-template.md](recursos/claude-md-template.md).
+
+---
+
+## Gestión de contexto
+
+| Rango | Accion |
+|-------|--------|
+| **0-40%** | Trabajar normalmente |
+| **40-70%** | Monitorear uso de contexto |
+| **70-90%** | Ejecutar `/compact` |
+| **90-100%** | Detener, compactar, o nueva sesion |
+
+---
+
+## Reglas de generación
+
+1. **No sobrescribir sin confirmación** — verificar existencia antes de crear.
+2. **Ajustar al stack detectado** — `pyproject.toml` -> Python, `package.json` -> Node.
+3. **Registrar decisiones en ESTADO.md**.
+4. **`.gitignore`** debe incluir `.claude/settings.local.json` y `.env`.
+5. **Skills usan `references/`** dentro de `.claude/skills/`, y `recursos/` en `habilidades/`.
+6. **CLAUDE.md < 200 líneas** — dividir en `.claude/rules/*.md` con `paths:` si excede.
+
+---
+
+## Variantes por stack
+
+Ver [recursos/variantes-por-stack.md](recursos/variantes-por-stack.md).
+
+| Stack | Archivo raiz | ORM / DB | Framework de test |
+|-------|-------------|----------|-------------------|
+| Python/FastAPI | `pyproject.toml` | SQLAlchemy + Alembic | pytest + httpx |
+| Node.js | `package.json` | Prisma / Drizzle | Vitest / Jest |
+| Angular | `angular.json` | N/A | Karma / Jest |
+| React/Next.js | `next.config.js` | N/A | Vitest + RTL |
+
+---
+
+Para configuración completa de settings.json, .mcp.json, plugins y checklist detallado, ver [recursos/configuracion-y-extensiones.md](recursos/configuracion-y-extensiones.md).
+
+## Cuándo NO cargar
+
+- Se inicia un proyecto completamente nuevo — usar `/swl:nuevo-proyecto`, que conduce la entrevista de contexto antes de elegir estructura; este skill genera la estructura pero no recoge los requisitos del proyecto.
+- Se modifica o crea un componente específico (un agente, un skill, un hook) dentro de un proyecto ya estructurado — el overhead de cargar toda la arquitectura de 4 capas no compensa para una edición puntual de frontmatter.
+- Se configuran permisos de herramientas o nivel de riesgo de un agente — esa decisión requiere `seguridad-agentes`; este skill describe dónde vive la configuración, no qué valores son seguros.
+- Se busca la sintaxis actual de una API de extensión específica de Claude Code — Context7 MCP tiene la documentación oficial más actualizada para APIs de comandos, hooks y settings avanzados.
+
+## Gotchas / Errores comunes no obvios
+
+- **CLAUDE.md supera 200 líneas sin subdirectorios y Claude Code deja de respetarlo**: el agente empieza a saltarse reglas de proyecto porque el archivo es demasiado largo para ser incluido completo en el contexto. Causa: reglas que deberían estar en `.claude/rules/*.md` con `paths:` quedan todas en el CLAUDE.md raíz. Solución: dividir en archivos en `.claude/rules/` con `paths:` filtrado por extensión o directorio — la regla 6 de este skill dice CLAUDE.md < 200 líneas.
+- **`settings.local.json` committeado con permisos de desarrollo**: el archivo contiene `allowedTools` con `Bash` habilitado globalmente y queda en el repositorio. Causa: `.gitignore` no incluye `.claude/settings.local.json`. Solución: verificar que `.gitignore` tiene la entrada antes de cualquier commit que toque `.claude/` — este archivo es por definición local y nunca debe versionarse.
+- **Hook declarado en `hooks/` pero sin registrar en `manifiestos/hooks-config.json`**: el hook no se ejecuta y nadie entiende por qué el evento PreToolUse no dispara. Causa: crear el archivo del hook sin actualizar el manifiesto. Solución: toda adición de hook requiere actualización de `manifiestos/hooks-config.json` y `.claude/settings.json` según la tabla de propagación en CLAUDE.md — el hook no se activa si Claude Code no sabe que existe.
+- **`herramientasPermitidas` en skill declarada con tools que el agente invocador no tiene**: el skill requiere `Write` pero el agente que lo carga solo tiene `Read`. Causa: el frontmatter del skill declara herramientas sin verificar qué agentes lo invocarán. Solución: al crear un skill, verificar que los agentes que están en `skillsInvocables` del skill tienen al menos las mismas tools en su propio frontmatter — la cadena de permisos no escala hacia arriba.

package/habilidades/estructura-proyecto-claude/recursos/claude-md-template.md

@@ -0,0 +1,261 @@
+# CLAUDE.md — [Nombre del Proyecto]
+
+> Fuente de verdad del proyecto para Claude Code.
+> Claude lee este archivo al inicio de cada sesión.
+> Actualizar cuando cambien convenciones, stack o arquitectura.
+> Mantener bajo 200 líneas — usar .claude/rules/ para instrucciones extensas.
+> Última actualización: [YYYY-MM-DD]
+
+---
+
+## Qué es este proyecto
+
+[2-3 oraciones describiendo el propósito del proyecto, el problema que resuelve
+y a quién va dirigido. Ser específico — evitar frases genéricas como "sistema
+de gestión empresarial".]
+
+**Ejemplo**:
+> API REST para el sistema de facturación electrónica de PyMEs en México.
+> Genera CFDIs 4.0 certificados por el SAT e integra con los PACs Finkok y Diverza.
+> Expone una interfaz REST consumida por el frontend Angular y la app móvil React Native.
+
+---
+
+## 1. Stack tecnológico
+
+| Capa | Tecnologia | Version |
+|------|-----------|---------|
+| Lenguaje backend | Python | 3.12 |
+| Framework backend | FastAPI | 0.115+ |
+| ORM | SQLAlchemy | 2.0 (async) |
+| Base de datos | PostgreSQL | 16 |
+| Migraciones | Alembic | 1.13+ |
+| Gestor de paquetes | uv | 0.5+ |
+| Lenguaje frontend | TypeScript | 5.4+ |
+| Framework frontend | Angular | 20+ |
+| Estilos | Tailwind CSS | 4.0 |
+| Tests backend | pytest + httpx | - |
+| Tests frontend | Jasmine + Karma | - |
+| CI/CD | GitHub Actions | - |
+| Contenedores | Docker + Compose | - |
+
+> Ajustar esta tabla al stack real del proyecto. Eliminar filas que no aplican.
+
+---
+
+## 2. Convenciones de código
+
+### Python / Backend
+
+- **Estilo**: PEP 8 + Ruff para lint y formato. Máximo 88 caracteres por línea.
+- **Type hints**: Obligatorios en toda función pública. Sin `Any` sin justificación.
+- **Docstrings**: Solo en funciones públicas de módulos, clases y endpoints complejos.
+  Formato Google Style.
+- **Imports**: Agrupados — stdlib, terceros, locales. Separados por línea en blanco.
+- **Nombres**: `snake_case` para variables y funciones, `PascalCase` para clases.
+
+### TypeScript / Frontend
+
+- **Framework**: Angular 20+ con signals. Sin NgModules para componentes nuevos.
+- **Directivas de control**: `@if`, `@for`, `@switch`. NUNCA `*ngIf`, `*ngFor`.
+- **Estado**: `signal()` y `computed()` para estado reactivo.
+- **Estilos**: Tailwind CSS. Angular Material SOLO para componentes funcionales.
+- **HTTP**: Siempre tipado. Sin `any` en responses de API.
+
+### Naming conventions
+
+- Archivos: `kebab-case` para todos los archivos
+- Componentes Angular: `nombre.component.ts`, `nombre.component.html`
+- Services: `nombre.service.ts`
+- Models: `nombre.model.ts`
+- Tests: `nombre.spec.ts` (frontend), `test_nombre.py` (backend)
+
+---
+
+## 3. Arquitectura
+
+```
+src/
++-- [capa-1]/          # [Descripción: ej. "Componentes React compartidos"]
++-- [capa-2]/          # [Descripción: ej. "Handlers / lógica de negocio"]
++-- [capa-3]/          # [Descripción: ej. "Utilidades compartidas"]
++-- [capa-4]/          # [Descripción: ej. "Modelos de datos y schemas"]
+```
+
+### Reglas de arquitectura
+- Services no importan directamente modelos de otros dominios
+- Endpoints no tienen lógica de negocio — delegan a services
+- Componentes no hacen llamadas HTTP directamente — usan services
+
+---
+
+## 4. Seguridad
+
+- No secretos en código ni logs — usar variables de entorno
+- Validar todos los inputs del usuario en el boundary del sistema
+- Usar queries parametrizadas — NUNCA concatenación de strings SQL
+- RBAC en todos los endpoints que modifican datos
+- CORS configurado explícitamente — no wildcard `*` en producción
+- Rate limiting en endpoints públicos
+- Headers de seguridad: HSTS, X-Content-Type-Options, X-Frame-Options
+
+---
+
+## 5. Testing
+
+### Estrategia de tests
+
+| Tipo | Framework | Cobertura mínima |
+|------|-----------|-----------------|
+| Unit tests backend | pytest | 80% líneas |
+| Integration tests | pytest + httpx | Todos los endpoints |
+| Unit tests frontend | Jasmine + Karma | 70% líneas |
+| E2E tests | Playwright / Cypress | Flujos críticos |
+
+### Como correr tests
+
+```bash
+# Backend — tests completos con cobertura
+pytest tests/ --cov=app --cov-report=html -v
+
+# Backend — solo un modulo
+pytest tests/test_facturacion.py -v
+
+# Frontend — tests unitarios
+ng test
+
+# Frontend — E2E
+ng e2e
+
+# Lint y tipo-checking
+ruff check app/ tests/
+mypy app/
+```
+
+### Reglas de testing
+- Todo PR debe incluir tests para código nuevo/modificado
+- Tests deben tener assertions reales (no solo verificar que no lanza excepción)
+- Fixtures compartidas en `conftest.py` / `test-utils.ts`
+- Mock solo para dependencias externas (APIs, email). NUNCA mockear la BD en integration tests.
+
+---
+
+## 6. Git Workflow
+
+### Ramas
+- `main` — produccion, protegida
+- `develop` — integracion (si aplica)
+- `feature/descripcion-corta` — features nuevas
+- `fix/descripcion-corta` — bug fixes
+- `chore/descripcion` — mantenimiento
+
+### Commits
+Formato Conventional Commits en inglés:
+```
+feat: add CFDI billing endpoint
+fix: correct RFC validation in schema
+chore: update security dependencies
+refactor: extract billing logic to service
+test: add integration tests for auth flow
+```
+
+### Pull Requests
+- Al menos 1 revisor
+- Tests pasando en CI
+- Sin TODO sin ticket asociado
+- Squash merge a main
+
+---
+
+## 7. Comandos comunes (Workflows)
+
+```bash
+# --- Setup inicial ---
+uv sync                                    # Instalar dependencias Python
+npm install                                # Instalar dependencias frontend
+
+# --- Desarrollo ---
+uvicorn app.main:app --reload --port 8000  # Backend dev server
+ng serve --open                            # Frontend dev server
+
+# --- Base de datos ---
+alembic revision --autogenerate -m "desc"  # Crear migracion
+alembic upgrade head                       # Aplicar migraciones
+alembic downgrade -1                       # Revertir ultima
+
+# --- Testing ---
+pytest tests/ -v                           # Tests backend
+ng test                                    # Tests frontend
+
+# --- Calidad ---
+ruff check app/ tests/                     # Lint Python
+ruff format app/ tests/                    # Format Python
+mypy app/                                  # Type checking
+
+# --- Docker ---
+docker compose up -d postgres redis        # Solo infra
+docker compose up --build                  # Todo
+docker compose down                        # Detener
+```
+
+---
+
+## Reglas anti-error del proyecto
+
+> Estas reglas documentan errores que ya ocurrieron en este proyecto.
+> Son la segunda defensa después de los tests.
+
+### Backend
+
+- **selectinload OBLIGATORIO**: Toda relación accedida en serialización Pydantic
+  DEBE tener `selectinload()` en el query. Sin esto -> `MissingGreenlet` en runtime.
+- **Services NO hacen commit**: Solo `db.add()`, `db.flush()`, `db.refresh()`.
+  El commit SIEMPRE en el endpoint.
+- **Literal[] en schemas**: Campos con dominio cerrado (`estatus`, `tipo`) DEBEN
+  usar `Literal["valor1", "valor2"]`. NUNCA `str` sin restricción.
+- **RBAC en escritura**: Todos los endpoints POST/PUT/DELETE deben tener
+  `_=Depends(require_role([...]))`.
+
+### Frontend
+
+- **PaginatedResponse**: Todo endpoint paginado parsear con `.pipe(map(r => r.items))`.
+- **track obligatorio en @for**: `@for (item of items; track item.id)`.
+- **takeUntilDestroyed()**: En toda suscripcion larga o polling.
+
+---
+
+## Estructura de archivos
+
+```
+[Pegar aqui la estructura de arbol del proyecto, generada con:
+  tree -I "node_modules|__pycache__|.git|*.pyc|dist|build" --max-depth=3
+]
+```
+
+---
+
+## Variables de entorno requeridas
+
+Copiar `.env.example` a `.env` y completar antes de ejecutar:
+
+```bash
+cp .env.example .env
+```
+
+Descripción de cada variable en `.env.example`. Las variables marcadas con `*`
+son obligatorias para correr en desarrollo.
+
+---
+
+## Agentes y skills activos en este proyecto
+
+| Tipo | Nombre | Propósito |
+|------|--------|-----------|
+| Skill | [nombre] | [qué cubre] |
+| Agente | [nombre] | [cuándo se usa] |
+| Comando | `/proyecto:nombre` | [qué hace] |
+
+---
+
+*Template generado con `Skill("estructura-proyecto-claude")` el [YYYY-MM-DD].*
+*Mantener actualizado al cierre de cada fase con `consolidador-swl`.*

package/habilidades/estructura-proyecto-claude/recursos/configuracion-y-extensiones.md

@@ -0,0 +1,176 @@
+# Estructura de Proyecto Claude-ready — Configuracion y Extensiones
+
+Referencia extendida de la skill `estructura-proyecto-claude`. Contiene ejemplos
+completos de settings.json, .mcp.json, plugins y checklists detallados.
+
+---
+
+## Estructura de settings.json
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Bash(git:*)",
+      "Bash(npm:*)",
+      "Bash(python:*)",
+      "Read(**/src/**)",
+      "Write(**/src/**)"
+    ],
+    "deny": [
+      "Bash(rm -rf:*)",
+      "Bash(curl * | bash:*)",
+      "Bash(sudo:*)",
+      "Read(**/env:*)"
+    ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "type": "command",
+        "command": "node .claude/hooks/lint-check.js"
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write",
+        "type": "command",
+        "command": "node .claude/hooks/format-on-save.js"
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "startup",
+        "type": "command",
+        "command": "node .claude/hooks/load-context.js"
+      }
+    ]
+  },
+  "context": {
+    "rules": [
+      "CLAUDE.md"
+    ]
+  }
+}
+```
+
+### Jerarquía de settings (mayor a menor prioridad)
+
+1. **Managed** (MDM plist / Registry / Server-managed / `managed-settings.d/`)
+2. **CLI arguments** (solo sesión actual)
+3. **`.claude/settings.local.json`** (personal, git-ignored)
+4. **`.claude/settings.json`** (equipo, commiteado)
+5. **`~/.claude/settings.json`** (global personal)
+
+---
+
+## Settings avanzados y variables de entorno
+
+Settings poco documentados pero de alto impacto:
+
+| Setting | Tipo | Efecto |
+|---------|------|--------|
+| `plansDirectory` | string | Redirige archivos de plan a directorio custom (ej: `"./.planning"`) |
+| `outputStyle` | string | Estilo de respuesta: `"Explanatory"`, `"Concise"`, etc. |
+| `spinnerVerbs` | array | Verbos custom para el spinner de actividad |
+| `spinnerTipsOverride` | object | `{ "tips": [...], "excludeDefault": true }` para tips personalizados |
+| `enableAllProjectMcpServers` | boolean | Habilitar todos los MCP sin pedir permiso |
+
+### Variables de entorno de control (en `"env"` de settings.json)
+
+| Variable | Valor | Efecto |
+|----------|-------|--------|
+| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | `"80"` | Compactar al 80% de contexto (default: ~95%) — reduce riesgo de overflow |
+| `CLAUDE_CODE_TASK_LIST_ID` | string | ID de lista de tareas compartida (Agent Teams) |
+| `CLAUDE_PLUGIN_DATA` | path | Directorio de datos persistentes por skill entre sesiones |
+| `ENABLE_TOOL_SEARCH` | `"true"` | Habilitar Tool Search para lazy loading de herramientas |
+
+### Flags CLI de alto impacto
+
+| Flag | Efecto |
+|------|--------|
+| `--bare` | Arranque hasta 10x más rápido — omite carga de CLAUDE.md y skills. Útil para scripts |
+| `--add-dir <path>` | Agregar directorio adicional a la sesión — sesiones multi-repo sin copiar archivos |
+| `-w` / `--worktree` | Git worktree aislado — cada sesión en su propia rama |
+| `--agent=<nombre>` | Usar agente custom como agente principal de la sesión |
+| `--effort high` | Nivel de esfuerzo alto para todas las respuestas |
+| `/sandbox` | Reduce 84% los diálogos de permisos — sandbox seguro para exploración |
+```
+
+---
+
+## Estructura de .mcp.json
+
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"]
+    },
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "" }
+    },
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@anthropic/mcp-playwright"]
+    }
+  }
+}
+```
+
+Ver catalogo completo en [mcp-json-template.json](mcp-json-template.json).
+
+---
+
+## Plugins distribuibles
+
+Los plugins empaquetan skills + agents + hooks para distribucion:
+
+```
+mi-plugin/
++-- plugin.json              # Manifest (nombre, version, dependencias)
++-- skills/
+|   +-- mi-skill/SKILL.md
++-- agents/
+|   +-- mi-agent.md
++-- hooks/
+|   +-- hooks.json
++-- mcp-servers/
+|   +-- server.json
++-- README.md
+```
+
+Distribucion via Git, GitHub, npm o paths locales. Namespace: `plugin-name:skill-name`.
+
+---
+
+## Checklist completo de proyecto Claude-ready
+
+### Estructura base
+- [ ] `CLAUDE.md` existe con las 7 secciones (Stack, Conventions, Architecture, Security, Testing, Git, Workflows)
+- [ ] `CLAUDE.md` tiene menos de 200 lineas
+- [ ] `.claude/settings.json` existe con permisos (allow/deny) y hooks
+- [ ] `.claude/settings.local.json` esta en `.gitignore`
+
+### Extensiones
+- [ ] `.claude/commands/` tiene al menos 1 comando del proyecto
+- [ ] `.claude/skills/` tiene skills con SKILL.md + references/
+- [ ] `.claude/agents/` tiene agentes especializados del proyecto
+- [ ] `.claude/hooks/` tiene hooks configurados (al menos PreToolUse)
+- [ ] `.claude/rules/` tiene reglas path-scoped si CLAUDE.md > 200 lineas
+
+### Integraciones
+- [ ] `.mcp.json` existe con al menos context7 y github
+- [ ] Archivos de stack (package.json o pyproject.toml) son consistentes con CLAUDE.md
+
+### Estado SWL
+- [ ] `.planning/ESTADO.md` existe y esta actualizado
+- [ ] `.planning/PROYECTO.md` define el proyecto
+
+### Jerarquia de memoria
+- [ ] CLAUDE.md de subdirectorios (si monorepo) NO sobreescriben padre
+- [ ] Cada CLAUDE.md < 200 lineas