@saulwade/swl-ses 1.0.0

package/habilidades/workflow-claude-code/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: workflow-claude-code
+description: >
+  Patrones de flujo de trabajo diario con Claude Code: gestión de sesiones,
+  atajos de teclado, Plan Mode, feature-per-session, gestión de contexto,
+  jerarquía de memoria, handoff multi-sesión, niveles de esfuerzo de Opus 4.7
+  (high/xhigh/max) y el patrón de delegación. Cargar cuando el usuario pregunte
+  cómo usar Claude Code eficientemente, cuando necesite optimizar su flujo de
+  trabajo, o cuando inicie un proyecto nuevo. NO cargar para estructura de
+  proyecto (usar estructura-proyecto-claude).
+version: "1.1.0"
+herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep]
+exclusiones:
+  - "No cargar para configurar la estructura de directorios de un proyecto Claude-ready; usar `estructura-proyecto-claude`."
+  - "No cargar para resolver problemas de degradación de contexto en mitad de una sesión larga; en ese caso ejecutar `/swl:compactar` directamente."
+  - "No cargar para consultar documentación de librerías o frameworks externos; usar Context7 MCP."
+  - "No cargar para ajustar permisos de herramientas en settings.json; usar `Skill('update-config')`."
+evolvable: true  # default para skill estandar
+---
+# Workflow con Claude Code
+
+Fuente: `referencias/Claude Code WorkFlow Cheatsheet.jpg` (2026 Edition)
+
+Esta skill cubre CÓMO trabajar con Claude Code de forma efectiva.
+Para ESTRUCTURA de proyecto, usar `estructura-proyecto-claude`.
+
+## Cuándo cargar esta skill
+
+- El usuario pregunta cómo usar Claude Code eficientemente
+- Se necesita optimizar el flujo de trabajo diario
+- Se inicia un proyecto nuevo y se necesita onboarding
+- Hay problemas de contexto o productividad
+- Se requiere handoff entre sesiones
+
+## Cuándo NO cargar
+
+- Se necesita estructura de archivos para un proyecto Claude-ready (CLAUDE.md, .claude/agents/, etc.); usar `estructura-proyecto-claude`.
+- El contexto ya está al 70%+ y el usuario quiere compactar ahora mismo; ejecutar `/swl:compactar` sin cargar skills adicionales.
+- El usuario pregunta por una librería específica (ej: "¿cómo uso FastAPI?"); la respuesta está en Context7 MCP, no en este skill de workflow.
+- Se busca configurar hooks, permisos o settings.json; usar `Skill("update-config")`.
+
+---
+
+## Patrón de flujo diario
+
+```
+1. cd proyecto && claude            # Iniciar sesion
+2. Shift+Tab+Tab -> Plan Mode       # Entrar a Plan Mode
+3. Describir intent de la feature    # Claude planea primero
+4. Shift+Tab -> Auto Accept          # Cambiar a ejecucion
+5. /compact cuando sea necesario     # Liberar contexto
+6. Esc Esc + rewind si algo falla    # Retroceder
+7. Commit frecuentemente             # Puntos de recuperacion
+8. Nueva sesion por feature          # Contexto fresco
+```
+
+**Regla de oro**: Una sesión = una feature. Sesiones largas degradan la calidad.
+
+---
+
+## Modos de operación
+
+### Plan Mode (Shift+Tab+Tab)
+
+- Claude analiza y planifica ANTES de escribir código
+- NO ejecuta herramientas — solo razona
+- Usar para: features complejas, decisiones de arquitectura, debugging, cambios >5 archivos
+
+### Auto Accept Mode (Shift+Tab)
+
+- Claude ejecuta herramientas sin pedir confirmación
+- Usar para: tareas bien definidas, generación de boilerplate, tests, después de aprobar plan
+
+### Default Mode
+
+- Claude pide confirmación antes de cada tool use
+- Usar para: operaciones destructivas, deploy, cambios en producción
+
+---
+
+## Atajos de teclado esenciales
+
+| Atajo | Acción |
+|-------|--------|
+| `Shift+Tab` | Toggle extended thinking / Auto Accept |
+| `Shift+Tab+Tab` | Plan Mode |
+| `Esc Esc` | Menú de rewind (deshacer último paso) |
+| `Tab` | Toggle extended thinking |
+| `/compact` | Compactar contexto |
+| `/init` | Generar CLAUDE.md inicial |
+| `/clear` | Limpiar sesión (nueva conversación) |
+| `Ctrl+C` | Interrumpir operación actual |
+
+---
+
+## Gestión de contexto
+
+### Rangos de uso
+
+| Rango | Acción | Señal |
+|-------|--------|-------|
+| **0-40%** | Trabajar normalmente | Verde |
+| **40-70%** | Monitorear — considerar compactar pronto | Amarillo |
+| **70-90%** | Ejecutar `/compact` inmediatamente | Naranja |
+| **90-100%** | `/clear` o nueva sesión obligatoria | Rojo |
+
+### Señales de degradación de contexto (context rot)
+
+- Claude repite preguntas que ya respondió
+- Olvida decisiones tomadas anteriormente
+- Genera código inconsistente con lo que acaba de escribir
+- Más de 40 turnos en la conversación
+
+### Estrategias anti context rot
+
+1. **Una feature por sesión** — El patrón más importante
+2. **Commits frecuentes** — Punto de recuperación ante compactación
+3. **CLAUDE.md < 200 líneas** — Reduce carga base de contexto
+4. **Subagentes** — Delegan trabajo a contextos frescos
+5. **`.claude/rules/` con paths** — Carga lazy, solo lo necesario
+6. **/compact proactivo** — No esperar a que se degrade
+
+---
+
+## Jerarquía de memoria
+
+### CLAUDE.md en cascada
+
+```
+~/.claude/CLAUDE.md              # User — aplica a TODOS tus proyectos
+   |
+   +-- /CLAUDE.md                # Project — compartido via git
+       |
+       +-- /frontend/CLAUDE.md   # Subdirectory — scoped context
+       +-- /backend/CLAUDE.md    # Subdirectory — scoped context
+```
+
+**Reglas**:
+- Cada nivel **agrega** al anterior, NUNCA sobreescribe
+- Mantener cada archivo bajo **200 líneas**
+- Subdirectorios se cargan **lazy** (solo al trabajar con archivos en esa ruta)
+
+### Qué poner en cada nivel
+
+| Nivel | Contenido | Ejemplo |
+|-------|-----------|---------|
+| **User** (`~/.claude/CLAUDE.md`) | Preferencias globales | "Usar conventional commits" |
+| **Project** (`./CLAUDE.md`) | Stack, arquitectura, convenciones | "Python 3.12 + FastAPI" |
+| **Subdirectory** | Convenciones de un módulo | "Angular 20 con signals" |
+| **Auto Memory** | Aprendizajes de sesiones previas | "El usuario prefiere pnpm" |
+
+---
+
+## Handoff entre sesiones
+
+### Cuándo cerrar sesión
+
+- Feature completada y commiteada
+- Contexto >70% usado
+- Más de 40 turnos
+- Cambio de tarea/dominio significativo
+
+### Protocolo de handoff
+
+1. **Commit** todo el trabajo en progreso
+2. **Documentar** estado actual (qué está listo, qué falta, decisiones pendientes)
+3. **Compactar o nueva sesión**
+4. En proyectos SWL, usar `/swl:checkpoint` para guardar estado
+
+---
+
+## Mejores prácticas
+
+### Lo que SÍ hacer
+
+1. Correr `/init` primero — Genera un CLAUDE.md inicial
+2. Ser específico en instrucciones — "Agrega endpoint POST /invoices" > "agrega facturación"
+3. Referenciar archivos con `@` — Carga el archivo en contexto
+4. Commitear para compartir aprendizaje — CLAUDE.md en git = equipo alineado
+5. Usar subagentes para tareas independientes
+
+### Lo que NO hacer
+
+1. Sesiones largas (más de 40 turnos = degradación)
+2. CLAUDE.md gigante (más de 200 líneas)
+3. Ignorar /compact en 70%+
+4. Todo en una sesión
+5. Secretos en CLAUDE.md
+
+---
+
+## Patrón de delegación con Opus 4.7 (desde abril 2026)
+
+Opus 4.7 introduce un shift operativo importante: **rinde mejor tratado como un
+ingeniero al que delegas, no como un pair programmer al que guías línea por línea**.
+Fuente: https://claude.com/blog/best-practices-for-using-claude-opus-4-7-with-claude-code
+
+### Tres cambios en el workflow
+
+1. **Especificar tareas completas desde el inicio**
+   - Dar intent + constraints + acceptance criteria + file locations en el
+     primer prompt, no fragmentado en varios turnos.
+   - Un prompt completo al inicio es más eficiente que 5 turnos de refinamiento.
+   - Ejemplo: en lugar de "agrega autenticación" → "agrega JWT auth en
+     `src/auth/jwt.ts` usando `jose` v5, con refresh tokens de 15min,
+     tests en `tests/auth.test.ts`, sin tocar la capa de BD".
+
+2. **Reducir interacciones turn-by-turn**
+   - Cada turno suma overhead de razonamiento.
+   - Agrupar preguntas: "A, B y C" en un solo turno > tres turnos separados.
+   - No interrumpir a mitad de una tarea larga salvo que sea bloqueante.
+
+3. **Usar auto mode cuando sea apropiado**
+   - Disponible para usuarios Max de Claude Code.
+   - Ideal para tareas de larga duración donde confías en la ejecución autónoma.
+   - El modelo notifica cuando la tarea se completa.
+
+### Niveles de esfuerzo (xhigh es el nuevo default)
+
+| Nivel | Cuándo usar | Comportamiento |
+|-------|-------------|----------------|
+| `high` | Tareas mecánicas, refactors simples | Balance inteligencia/costo/velocidad |
+| `xhigh` (default) | **La mayoría** de tareas de coding agentic | Razonamiento extendido sin overthinking |
+| `max` | Problemas genuinamente difíciles | Más pensamiento pero diminishing returns — no abusar |
+
+Toggle con `Shift+Tab`. No existe más el `extended thinking con budget fijo` —
+el modelo decide dinámicamente cuánto razonar según la tarea.
+
+### Sub-agentes: paralelismo explícito
+
+Opus 4.7 usa menos sub-agentes por defecto que 4.6. Si una tarea se beneficia
+de ejecución paralela, declararlo en el prompt:
+
+- "Ejecuta estos 3 análisis en paralelo" > confiar en que lo decidirá solo.
+- Especificar qué tool uses van en paralelo en una sola respuesta.
+
+### Instrucciones literales
+
+Opus 4.7 interpreta instrucciones de forma más literal. Los prompts ambiguos
+que 4.6 resolvía por inferencia ahora se ejecutan al pie de la letra. Invertir
+tiempo en eliminar ambigüedad al inicio ahorra iteraciones.
+
+### Tokenizer actualizado (impacto en presupuesto)
+
+El mismo contenido produce 1.0–1.35× más tokens en 4.7 que en 4.6. Las reglas
+de context management del sistema SWL se recalibraron:
+- Umbral de compactación: 60% → 50% del contexto
+- `context-builder` budget default: 2000 → 2500 tokens
+
+Consultar skill `compactacion-contexto` para protocolo completo.
+
+Para skills bundled de Claude Code, patrones de productividad por tarea
+y quick reference completa, ver [recursos/referencia-completa.md](recursos/referencia-completa.md).
+
+## Gotchas / Errores comunes no obvios
+
+- **Sesión de >40 turnos sin compactar**: el agente no monitorea el conteo de turnos y continúa trabajando hasta que Claude empieza a "olvidar" decisiones tomadas temprano en la sesión. Causa: no se aplica la señal de context rot (40 turnos). Solución: al llegar a 40 turnos, ejecutar `/swl:compactar` antes de la siguiente tarea grande — no esperar a que la degradación sea visible en la calidad del output.
+- **CLAUDE.md superando 200 líneas sin subdirectorios**: el proyecto crece y todo el contexto se acumula en el CLAUDE.md raíz, incrementando la carga base de contexto de cada conversación. Causa: no se crean CLAUDE.md de subdirectorio para módulos como `backend/` o `frontend/`. Solución: extraer convenciones específicas de módulo a su propio `<directorio>/CLAUDE.md`; el CLAUDE.md raíz mantiene solo lo global.
+- **Auto Accept Mode activado en operaciones destructivas**: el usuario activa `Shift+Tab` para acelerar trabajo y olvida cambiarlo antes de un deploy o borrado de archivos. Causa: el modo no tiene contexto de operación. Solución: volver a Default Mode explícitamente antes de operaciones irreversibles (`Shift+Tab` de vuelta) — Auto Accept es para generación de código, no para operaciones con blast radius alto.
+- **Tokenizer 4.7 subestimado en presupuesto de contexto**: el mismo CLAUDE.md que ocupaba el 30% del contexto en Opus 4.6 ocupa hasta 40% en 4.7 debido al tokenizer más granular. Causa: el umbral de compactación no se recalibró al migrar de modelo. Solución: con Opus 4.7, bajar el umbral de compactación de 70% a 50% tal como indica el skill `compactacion-contexto`.

package/habilidades/workflow-claude-code/recursos/referencia-completa.md

@@ -0,0 +1,109 @@
+# Referencia Completa — Workflow con Claude Code
+
+## Skills Bundled de Claude Code
+
+Claude Code incluye 17 skills predefinidos que NO requieren instalación.
+Se invocan con `/nombre-skill` directamente en cualquier sesión:
+
+### Documentos y datos
+| Skill | Qué hace |
+|-------|---------|
+| `/pdf` | Leer, crear, combinar, dividir PDFs |
+| `/pptx` | Crear presentaciones PowerPoint |
+| `/docx` | Crear documentos Word |
+| `/xlsx` | Analizar hojas de cálculo Excel |
+
+### Frontend y diseño
+| Skill | Qué hace |
+|-------|---------|
+| `/frontend-design` | Interfaces frontend de alta calidad visual |
+| `/web-artifacts-builder` | Componentes web complejos (React + shadcn/ui) |
+| `/brand-guidelines` | Aplicar guías de marca Anthropic |
+| `/canvas-design` | Diseño en canvas HTML |
+| `/theme-factory` | Crear temas y design systems |
+| `/algorithmic-art` | Arte algorítmico y generativo |
+
+### Desarrollo y testing
+| Skill | Qué hace |
+|-------|---------|
+| `/claude-api` | Desarrollar con la API de Claude / Anthropic SDK |
+| `/mcp-builder` | Construir servidores MCP |
+| `/webapp-testing` | Testing de aplicaciones web |
+| `/skill-creator` | Crear nuevos skills para Claude Code |
+
+### Comunicación
+| Skill | Qué hace |
+|-------|---------|
+| `/internal-comms` | Comunicaciones internas (status reports, FAQs) |
+| `/doc-coauthoring` | Co-escribir documentos |
+| `/slack-gif-creator` | Crear GIFs para Slack |
+
+### Combinando con flujo SWL
+
+Estos skills se combinan naturalmente con el flujo SWL:
+
+- `/swl:ejecutar-fase` + `/frontend-design` — Implementar UI con alta calidad visual
+- `/swl:verificar` + `/webapp-testing` — Verificar con tests de aplicación web
+- `documentador-swl` + `/pdf` + `/pptx` — Generar entregables en múltiples formatos
+- `producto-prd-swl` + `/docx` — Exportar PRD como documento Word
+- `datos-swl` + `/xlsx` — Analizar datos de Excel para ETL
+- `auto-evolucion-swl` + `/skill-creator` — Crear nuevos skills del sistema
+
+---
+
+## Patrones de Productividad
+
+### Para features nuevas
+
+```
+Plan Mode -> describir feature -> aprobar plan -> Auto Accept -> implementar -> commit
+```
+
+### Para debugging
+
+```
+Plan Mode -> describir bug + evidence -> Claude investiga -> diagnóstico
+-> Auto Accept -> fix -> test -> commit
+```
+
+### Para refactoring
+
+```
+Plan Mode -> describir que refactorizar y por que -> Claude analiza impacto
+-> aprobar plan -> Auto Accept -> refactorizar en pasos atomicos
+-> test despues de cada paso -> commit
+```
+
+### Para code review
+
+```
+Default Mode -> "review PR #123" -> Claude analiza cambios
+-> sugiere mejoras -> discutir -> aplicar fixes
+```
+
+### Para onboarding en proyecto existente
+
+```
+claude
+> "Analiza este codebase y explicame la arquitectura"
+> "Que tecnologias usa y como estan organizadas?"
+> "Cuales son los flujos principales?"
+-> Claude lee el codebase -> genera resumen -> usuario refina CLAUDE.md
+```
+
+---
+
+## Quick Reference
+
+| Comando | Función |
+|---------|---------|
+| `/init` | Generar CLAUDE.md inicial |
+| `/compact` | Comprimir contexto |
+| `/clear` | Nueva conversación |
+| `/memory` | Toggle auto memory |
+| `/help` | Ayuda de Claude Code |
+| `Shift+Tab` | Toggle extended thinking |
+| `Shift+Tab+Tab` | Plan Mode |
+| `Esc Esc` | Rewind menu |
+| `!comando` | Ejecutar shell command |
+| `@archivo` | Cargar archivo en contexto |

package/hooks/_run-hook.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# _run-hook.sh — Wrapper resiliente para ejecutar hooks SWL.
+#
+# Resuelve la ruta a `node` en entornos donde el PATH no lo incluye
+# (típico: git-bash/MinGW en Windows cuando Claude Code lo lanza). Esto
+# evita el error "/usr/bin/bash: line 1: node: command not found" que
+# aparecía cuando settings.json tenía `node -e "..."` sin prefix.
+#
+# Uso desde .claude/settings.json:
+#   "command": "bash ./hooks/_run-hook.sh <nombre-del-hook>.js"
+#
+# También se puede pasar la ruta absoluta (modo global):
+#   "command": "bash /ruta/absoluta/hooks/_run-hook.sh /ruta/abs/hook.js"
+#
+# Nunca falla el hook por error de resolución: si no encuentra node, sale
+# con código 0 silencioso (hooks SWL son non-blocking por diseño).
+
+set +e
+
+HOOK_SPEC="${1:-}"
+[ -z "$HOOK_SPEC" ] && exit 0
+
+# 1. node en PATH (caso ideal: Linux, macOS, Windows con PATH ok)
+NODE_BIN="$(command -v node 2>/dev/null)"
+
+# 2. Fallback a ubicaciones típicas en Windows
+if [ -z "$NODE_BIN" ]; then
+  for candidate in \
+    "/c/Program Files/nodejs/node.exe" \
+    "/c/Program Files (x86)/nodejs/node.exe" \
+    "$HOME/AppData/Roaming/npm/node.exe" \
+    "/usr/local/bin/node" \
+    "/opt/homebrew/bin/node"; do
+    if [ -x "$candidate" ]; then
+      NODE_BIN="$candidate"
+      break
+    fi
+  done
+fi
+
+# 3. Sin node → salir silenciosamente (hooks son non-blocking)
+[ -z "$NODE_BIN" ] && exit 0
+
+# Detectar si HOOK_SPEC es ruta absoluta o nombre relativo
+if [ -f "$HOOK_SPEC" ]; then
+  # Ruta absoluta o relativa válida
+  HOOK_PATH="$HOOK_SPEC"
+else
+  # Asumir nombre relativo desde ./hooks/
+  HOOK_PATH="./hooks/$HOOK_SPEC"
+fi
+
+# Ejecutar el hook con wrapper resiliente MODULE_NOT_FOUND
+"$NODE_BIN" -e "try{require('$HOOK_PATH')}catch(e){if(e.code!=='MODULE_NOT_FOUND')throw e}"
+
+# Siempre exit 0 (non-blocking)
+exit 0