@saulwade/swl-ses 1.3.2 → 1.3.4

package/comandos/swl/claudemd.md

@@ -1,136 +1,141 @@
----
-name: swl:claudemd
-description: Audita, refactoriza, valida o inicializa archivos CLAUDE.md según best practices Anthropic (ADR-0016). Subcomandos audit (analiza calidad), refactor (sugiere extracciones), check (verifica secciones canónicas), init-user (crea ~/.claude/CLAUDE.md template), init-project (genera CLAUDE.md raíz del proyecto).
-allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
----
-
-# /swl:claudemd — Tratamiento profesional de CLAUDE.md
-
-Comando para auditar, refactorizar y mantener `CLAUDE.md` siguiendo las
-cinco recomendaciones del video oficial Anthropic *"The CLAUDE.md file"*:
-
-1. **Compacto** — empieza sin uno, agrega solo lo que tengas que corregir
-2. **Stack arriba** — lenguaje, framework, ORM, BD
-3. **Commands** — cómo correr dev, tests, lint, build
-4. **Code style** — convenciones de indentación, exports, nombrado
-5. **Conventions** — dónde van las cosas, qué patrones preferir
-
-**Carga**: `Skill("swl-claudemd")` — contiene la lógica de auditoría, las
-secciones canónicas, los umbrales de inflación y los templates de
-generación. Delega análisis y criterios al skill.
-
-## Subcomandos
-
-| Subcomando | Propósito |
-|---|---|
-| `/swl:claudemd audit` | Audita el CLAUDE.md actual (líneas, bullets gigantes, secciones canónicas, @references, placeholders) |
-| `/swl:claudemd check` | Como audit pero exit 1 si hay WARN — útil en pre-commit/CI |
-| `/swl:claudemd refactor` | Sugiere extracciones a archivos `@`-referenciados (no modifica, solo propone diff) |
-| `/swl:claudemd init-user` | Crea `~/.claude/CLAUDE.md` con template de preferencias personales si no existe |
-| `/swl:claudemd init-project` | Genera CLAUDE.md raíz del proyecto detectando el stack actual |
-
-Sin subcomando: equivale a `audit`.
-
-## Cuándo usar
-
-- Después de modificar manualmente CLAUDE.md (verifica calidad)
-- Al inicio de un proyecto que no tenía CLAUDE.md (init-project)
-- Al cambiar de máquina y querer transportar preferencias (init-user)
-- En pre-commit hook si el proyecto trackea CLAUDE.md (check)
-- Cuando el hook `claudemd-bloat-detector` emite nudge
-
-## Ejecución de cada subcomando
-
-### audit / check
-
-```bash
-node scripts/auditar-claudemd.js                # output legible
-node scripts/auditar-claudemd.js --json         # output JSON estructurado
-node scripts/auditar-claudemd.js --strict       # exit 1 si WARN (modo check)
-```
-
-El veredicto puede ser:
-
-- **OK** — cumple best practices, sin hallazgos
-- **WARN** — tiene oportunidades de mejora (líneas excesivas, bullets
-  gigantes, secciones ausentes, sin @references)
-- **ERROR** — no existe, tiene placeholders sin reemplazar, faltan
-  secciones críticas
-
-### refactor
-
-Lee el CLAUDE.md actual, identifica candidatos a extracción (bullets
-monolíticos, secciones largas, contenido duplicable a `@references`) y
-imprime el diff propuesto. **NO modifica el archivo** — el usuario
-revisa y aplica manualmente o con `git apply`.
-
-Patrones de extracción típicos:
-
-| Si el bullet/sección contiene… | Mover a… |
-|---|---|
-| Variables de entorno opt-in | `docs/variables-entorno.md` |
-| Reglas de gobernanza extensas | `docs/gobernanza.md` |
-| Catálogo de comandos completo | `COMANDOS.md` (referenciar) |
-| Mapa de propagación detallado | `docs/mapa-propagacion.md` |
-| Convenciones de cada capa | `docs/convenciones-{capa}.md` |
-
-### init-user
-
-Verifica si existe `~/.claude/CLAUDE.md` (en Windows:
-`%USERPROFILE%\.claude\CLAUDE.md`). Si no existe, genera template
-mínimo:
-
-```markdown
-# CLAUDE.md (preferencias personales transversales)
-
-> Este archivo aplica a TODOS mis proyectos. Las reglas específicas de
-> proyecto van en el CLAUDE.md de la raíz del proyecto, no aquí.
-
-## Mi rol y stack preferido
-
-- Rol: [ej. ingeniero senior backend]
-- Stack preferido: [ej. Python + FastAPI, TypeScript + Next.js]
-- Herramientas habituales: [ej. Neovim, ripgrep, fd, gh CLI]
-
-## Estilo de comunicación
-
-- Idioma: español
-- Formato preferido para respuestas: [breve / detallado / con tablas]
-- Cuándo prefiero ver alternativas vs. una sola recomendación
-
-## Patrones que aplico siempre
-
-- [ej. "Antes de implementar, mostrar el plan"]
-- [ej. "Tests para todo código nuevo, sin excepción"]
-- [ej. "Commits atómicos en español, formato conventional"]
-```
-
-Si ya existe, NO lo sobreescribe — sugiere añadir secciones faltantes.
-
-### init-project
-
-Detecta el stack del proyecto actual con `scripts/lib/detectar-stack-detallado.js`
-y genera `./CLAUDE.md` mínimo con:
-
-- Sección **Stack** poblada (lenguaje, framework, ORM, package manager)
-- Sección **Comandos** poblada (npm scripts detectados o comandos típicos)
-- Sección **Code style** vacía con placeholders
-- Sección **Conventions** vacía con placeholders
-- Sección **@references** apuntando a `.planning/PROYECTO.md`,
-  `README.md`, etc. si existen
-
-Si CLAUDE.md ya existe, **NO lo sobreescribe**. Sugiere correr
-`/swl:claudemd refactor` para mejorar el actual.
-
-## Variables de entorno
-
-Ver `@docs/variables-entorno.md` sección "Calidad de CLAUDE.md":
-
-- `SWL_CLAUDEMD_BLOAT` (on/off) — activa hook `claudemd-bloat-detector`
-- `SWL_CLAUDEMD_MAX_LINES` (default 200) — umbral de líneas totales
-- `SWL_CLAUDEMD_MAX_BULLET_CHARS` (default 1000) — umbral de bullet/párrafo
-
-## Exit codes
-
-- `0` — OK o WARN (consultivo)
-- `1` — ERROR o `--strict` + WARN
+---
+name: swl:claudemd
+description: Audita, refactoriza, valida o inicializa archivos CLAUDE.md según best practices Anthropic (ADR-0016). Subcomandos audit (analiza calidad), refactor (sugiere extracciones), check (verifica secciones canónicas), init-user (crea ~/.claude/CLAUDE.md template), init-project (genera CLAUDE.md raíz del proyecto).
+allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
+---
+
+# /swl:claudemd — Tratamiento profesional de CLAUDE.md
+
+Comando para auditar, refactorizar y mantener `CLAUDE.md` siguiendo las
+cinco recomendaciones del video oficial Anthropic *"The CLAUDE.md file"*:
+
+1. **Compacto** — empieza sin uno, agrega solo lo que tengas que corregir
+2. **Stack arriba** — lenguaje, framework, ORM, BD
+3. **Commands** — cómo correr dev, tests, lint, build
+4. **Code style** — convenciones de indentación, exports, nombrado
+5. **Conventions** — dónde van las cosas, qué patrones preferir
+
+**Carga**: `Skill("swl-claudemd")` — contiene la lógica de auditoría, las
+secciones canónicas, los umbrales de inflación y los templates de
+generación. Delega análisis y criterios al skill.
+
+## Subcomandos
+
+| Subcomando | Propósito |
+|---|---|
+| `/swl:claudemd audit` | Audita el CLAUDE.md actual (líneas, bullets gigantes, secciones canónicas, @references, placeholders) |
+| `/swl:claudemd check` | Como audit pero exit 1 si hay WARN — útil en pre-commit/CI |
+| `/swl:claudemd refactor` | Sugiere extracciones a archivos `@`-referenciados (no modifica, solo propone diff) |
+| `/swl:claudemd init-user` | Crea `~/.claude/CLAUDE.md` con template de preferencias personales si no existe |
+| `/swl:claudemd init-project` | Genera CLAUDE.md raíz del proyecto detectando el stack actual |
+
+Sin subcomando: equivale a `audit`.
+
+## Cuándo usar
+
+- Después de modificar manualmente CLAUDE.md (verifica calidad)
+- Al inicio de un proyecto que no tenía CLAUDE.md (init-project)
+- Al cambiar de máquina y querer transportar preferencias (init-user)
+- En pre-commit hook si el proyecto trackea CLAUDE.md (check)
+- Cuando el hook `claudemd-bloat-detector` emite nudge
+
+## Ejecución de cada subcomando
+
+### audit / check
+
+```bash
+npx -y @saulwade/swl-ses@latest audit-claudemd            # output legible
+npx -y @saulwade/swl-ses@latest audit-claudemd --json     # output JSON estructurado
+npx -y @saulwade/swl-ses@latest audit-claudemd --strict   # exit 1 si WARN (modo check)
+```
+
+El subcomando `audit-claudemd` del CLI funciona con cualquier modo de instalación
+(global vía `npm i -g`, npx puntual o local dev) porque resuelve el script via
+el paquete npm, no via path relativo al CWD. Es independiente del proyecto desde
+donde se invoque.
+
+El veredicto puede ser:
+
+- **OK** — cumple best practices, sin hallazgos
+- **WARN** — tiene oportunidades de mejora (líneas excesivas, bullets
+  gigantes, secciones ausentes, sin @references)
+- **ERROR** — no existe, tiene placeholders sin reemplazar, faltan
+  secciones críticas
+
+### refactor
+
+Lee el CLAUDE.md actual, identifica candidatos a extracción (bullets
+monolíticos, secciones largas, contenido duplicable a `@references`) y
+imprime el diff propuesto. **NO modifica el archivo** — el usuario
+revisa y aplica manualmente o con `git apply`.
+
+Patrones de extracción típicos:
+
+| Si el bullet/sección contiene… | Mover a… |
+|---|---|
+| Variables de entorno opt-in | `docs/variables-entorno.md` |
+| Reglas de gobernanza extensas | `docs/gobernanza.md` |
+| Catálogo de comandos completo | `COMANDOS.md` (referenciar) |
+| Mapa de propagación detallado | `docs/mapa-propagacion.md` |
+| Convenciones de cada capa | `docs/convenciones-{capa}.md` |
+
+### init-user
+
+Verifica si existe `~/.claude/CLAUDE.md` (en Windows:
+`%USERPROFILE%\.claude\CLAUDE.md`). Si no existe, genera template
+mínimo:
+
+```markdown
+# CLAUDE.md (preferencias personales transversales)
+
+> Este archivo aplica a TODOS mis proyectos. Las reglas específicas de
+> proyecto van en el CLAUDE.md de la raíz del proyecto, no aquí.
+
+## Mi rol y stack preferido
+
+- Rol: [ej. ingeniero senior backend]
+- Stack preferido: [ej. Python + FastAPI, TypeScript + Next.js]
+- Herramientas habituales: [ej. Neovim, ripgrep, fd, gh CLI]
+
+## Estilo de comunicación
+
+- Idioma: español
+- Formato preferido para respuestas: [breve / detallado / con tablas]
+- Cuándo prefiero ver alternativas vs. una sola recomendación
+
+## Patrones que aplico siempre
+
+- [ej. "Antes de implementar, mostrar el plan"]
+- [ej. "Tests para todo código nuevo, sin excepción"]
+- [ej. "Commits atómicos en español, formato conventional"]
+```
+
+Si ya existe, NO lo sobreescribe — sugiere añadir secciones faltantes.
+
+### init-project
+
+Detecta el stack del proyecto actual con `scripts/lib/detectar-stack-detallado.js`
+y genera `./CLAUDE.md` mínimo con:
+
+- Sección **Stack** poblada (lenguaje, framework, ORM, package manager)
+- Sección **Comandos** poblada (npm scripts detectados o comandos típicos)
+- Sección **Code style** vacía con placeholders
+- Sección **Conventions** vacía con placeholders
+- Sección **@references** apuntando a `.planning/PROYECTO.md`,
+  `README.md`, etc. si existen
+
+Si CLAUDE.md ya existe, **NO lo sobreescribe**. Sugiere correr
+`/swl:claudemd refactor` para mejorar el actual.
+
+## Variables de entorno
+
+Ver `@docs/variables-entorno.md` sección "Calidad de CLAUDE.md":
+
+- `SWL_CLAUDEMD_BLOAT` (on/off) — activa hook `claudemd-bloat-detector`
+- `SWL_CLAUDEMD_MAX_LINES` (default 200) — umbral de líneas totales
+- `SWL_CLAUDEMD_MAX_BULLET_CHARS` (default 1000) — umbral de bullet/párrafo
+
+## Exit codes
+
+- `0` — OK o WARN (consultivo)
+- `1` — ERROR o `--strict` + WARN