@saulwade/swl-ses 2.2.0 → 2.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (81) hide show
  1. package/CLAUDE.md +199 -196
  2. package/README.md +597 -579
  3. package/agentes/arquitecto-swl.md +0 -5
  4. package/agentes/backend-python-swl.md +0 -5
  5. package/agentes/implementador-swl.md +0 -5
  6. package/agentes/nemesis-auditor-swl.md +0 -5
  7. package/agentes/orquestador-swl.md +0 -5
  8. package/agentes/planificador-swl.md +0 -5
  9. package/agentes/revisor-codigo-swl.md +0 -5
  10. package/bin/swl-mcp-server.js +1 -1
  11. package/comandos/swl/adoptar-proyecto.md +253 -258
  12. package/comandos/swl/aprender.md +823 -828
  13. package/comandos/swl/claudemd.md +234 -239
  14. package/comandos/swl/ejecutar-fase.md +0 -5
  15. package/comandos/swl/nuevo-proyecto.md +200 -205
  16. package/comandos/swl/release.md +19 -5
  17. package/comandos/swl/revisar-impacto.md +0 -5
  18. package/habilidades/agent-browser/SKILL.md +0 -5
  19. package/habilidades/angular-moderno/SKILL.md +0 -5
  20. package/habilidades/api-rest-diseno/SKILL.md +0 -5
  21. package/habilidades/aprendizaje-continuo/SKILL.md +0 -5
  22. package/habilidades/auth-patrones/SKILL.md +0 -5
  23. package/habilidades/build-errors-nextjs/SKILL.md +0 -5
  24. package/habilidades/changelog-generator/SKILL.md +174 -179
  25. package/habilidades/checklist-seguridad/SKILL.md +0 -5
  26. package/habilidades/contenedores-docker/SKILL.md +0 -5
  27. package/habilidades/datos-etl/SKILL.md +0 -5
  28. package/habilidades/doc-sync/SKILL.md +0 -5
  29. package/habilidades/extractor-de-aprendizajes/SKILL.md +0 -5
  30. package/habilidades/fastapi-experto/SKILL.md +0 -5
  31. package/habilidades/frontend-avanzado/SKILL.md +0 -5
  32. package/habilidades/iam-secretos/SKILL.md +0 -5
  33. package/habilidades/manejo-errores/SKILL.md +0 -5
  34. package/habilidades/mapear-codebase/SKILL.md +0 -5
  35. package/habilidades/meta-skills-estandar/SKILL.md +0 -5
  36. package/habilidades/monitoring-alertas/SKILL.md +0 -5
  37. package/habilidades/nextjs-experto/SKILL.md +0 -5
  38. package/habilidades/nextjs-testing/SKILL.md +0 -5
  39. package/habilidades/node-experto/SKILL.md +0 -5
  40. package/habilidades/orquestacion-async/SKILL.md +0 -5
  41. package/habilidades/patrones-python/SKILL.md +227 -232
  42. package/habilidades/planear-fase/SKILL.md +336 -341
  43. package/habilidades/postgresql-experto/SKILL.md +0 -5
  44. package/habilidades/prevencion-sobreingenieria/SKILL.md +0 -5
  45. package/habilidades/protocolo-revision-swl/SKILL.md +0 -5
  46. package/habilidades/react-experto/SKILL.md +0 -5
  47. package/habilidades/release-semver/SKILL.md +0 -5
  48. package/habilidades/swl-claudemd/SKILL.md +0 -5
  49. package/habilidades/tdd-workflow/SKILL.md +710 -715
  50. package/habilidades/testing-python/SKILL.md +335 -340
  51. package/habilidades/verificar-trabajo/SKILL.md +0 -5
  52. package/hooks/lib/etapa-perfil-usuario.js +1 -1
  53. package/hooks/lib/evolution-tracker.js +191 -35
  54. package/hooks/resumen-sesion.js +4 -4
  55. package/llms.txt +1 -1
  56. package/manifiestos/canonical-hashes.json +1310 -0
  57. package/manifiestos/modulos.json +3 -0
  58. package/manifiestos/skills-lock.json +70 -70
  59. package/package.json +1 -1
  60. package/plugin.json +1 -1
  61. package/scripts/doctor.js +13 -0
  62. package/scripts/generar-canonical-hashes.js +147 -0
  63. package/scripts/instalador.js +140 -54
  64. package/scripts/lib/audit-evolved.js +76 -0
  65. package/scripts/lib/canonical-hash.js +94 -0
  66. package/scripts/lib/evolved-fuente.js +138 -0
  67. package/scripts/lib/manifiestos.js +1 -1
  68. package/scripts/publicar.js +42 -5
  69. package/scripts/remediar-evolved-instaladas.js +242 -0
  70. package/scripts/validar.js +14 -0
  71. package/scripts/vendor/claude-usage/__pycache__/scanner.cpython-314.pyc +0 -0
  72. package/scripts/verificar-evolucion.js +36 -0
  73. package/scripts/verificar-release.js +33 -0
  74. package/agentes/.evolved.json +0 -9
  75. package/comandos/swl/.evolved.json +0 -23
  76. package/habilidades/auth-patrones/.evolved.json +0 -9
  77. package/habilidades/extractor-de-aprendizajes/.evolved.json +0 -9
  78. package/habilidades/instalar-sistema/.evolved.json +0 -9
  79. package/habilidades/manejo-errores/.evolved.json +0 -9
  80. package/habilidades/node-experto/.evolved.json +0 -9
  81. package/habilidades/release-semver/.evolved.json +0 -9
@@ -1,239 +1,234 @@
1
- ---
2
- name: swl:claudemd
3
- 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).
4
- allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
5
- evolved: true
6
- evolved-from: "1.6.9"
7
- evolved-at: "2026-05-22"
8
- evolved-by: "aprender"
9
- evolved-note: "Audit dimensión 7 duplicación de reglas globales (cataloga 6 reglas de ~/.claude/rules/ que NO deben duplicarse inline). Refactor propone reemplazo canónico. Aplica regla nueva sin-duplicacion-reglas-globales.md."
10
- ---
11
-
12
- # /swl:claudemdTratamiento profesional de CLAUDE.md
13
-
14
- Comando para auditar, refactorizar y mantener `CLAUDE.md` siguiendo las
15
- cinco recomendaciones del video oficial Anthropic *"The CLAUDE.md file"*:
16
-
17
- 1. **Compacto** — empieza sin uno, agrega solo lo que tengas que corregir
18
- 2. **Stack arriba**lenguaje, framework, ORM, BD
19
- 3. **Commands** cómo correr dev, tests, lint, build
20
- 4. **Code style** convenciones de indentación, exports, nombrado
21
- 5. **Conventions** — dónde van las cosas, qué patrones preferir
22
-
23
- **Carga**: `Skill("swl-claudemd")` — contiene la lógica de auditoría, las
24
- secciones canónicas, los umbrales de inflación y los templates de
25
- generación. Delega análisis y criterios al skill.
26
-
27
- ## Subcomandos
28
-
29
- | Subcomando | Propósito |
30
- |---|---|
31
- | `/swl:claudemd audit` | Audita el CLAUDE.md actual (líneas, bullets gigantes, secciones canónicas, @references, placeholders) |
32
- | `/swl:claudemd check` | Como audit pero exit 1 si hay WARN — útil en pre-commit/CI |
33
- | `/swl:claudemd refactor` | Sugiere extracciones a archivos `@`-referenciados (no modifica, solo propone diff) |
34
- | `/swl:claudemd init-user` | Crea `~/.claude/CLAUDE.md` con template de preferencias personales si no existe |
35
- | `/swl:claudemd init-project` | Genera CLAUDE.md raíz del proyecto detectando el stack actual |
36
-
37
- Sin subcomando: equivale a `audit`.
38
-
39
- ## Cuándo usar
40
-
41
- - Después de modificar manualmente CLAUDE.md (verifica calidad)
42
- - Al inicio de un proyecto que no tenía CLAUDE.md (init-project)
43
- - Al cambiar de máquina y querer transportar preferencias (init-user)
44
- - En pre-commit hook si el proyecto trackea CLAUDE.md (check)
45
- - Cuando el hook `claudemd-bloat-detector` emite nudge
46
-
47
- ## Ejecución de cada subcomando
48
-
49
- ### audit / check
50
-
51
- ```bash
52
- npx -y @saulwade/swl-ses@latest audit-claudemd # output legible
53
- npx -y @saulwade/swl-ses@latest audit-claudemd --json # output JSON estructurado
54
- npx -y @saulwade/swl-ses@latest audit-claudemd --strict # exit 1 si WARN (modo check)
55
- ```
56
-
57
- El subcomando `audit-claudemd` del CLI funciona con cualquier modo de instalación
58
- (global vía `npm i -g`, npx puntual o local dev) porque resuelve el script via
59
- el paquete npm, no via path relativo al CWD. Es independiente del proyecto desde
60
- donde se invoque.
61
-
62
- El veredicto puede ser:
63
-
64
- - **OK** — cumple best practices, sin hallazgos
65
- - **WARN** — tiene oportunidades de mejora (líneas excesivas, bullets
66
- gigantes, secciones ausentes, sin @references)
67
- - **ERROR** no existe, tiene placeholders sin reemplazar, faltan
68
- secciones críticas
69
-
70
- ### refactor
71
-
72
- Lee el CLAUDE.md actual, identifica candidatos a extracción (bullets
73
- monolíticos, secciones largas, contenido duplicable a `@references`) y
74
- imprime el diff propuesto. **NO modifica el archivo** — el usuario
75
- revisa y aplica manualmente o con `git apply`.
76
-
77
- Patrones de extracción típicos:
78
-
79
- | Si el bullet/sección contiene… | Mover a… |
80
- |---|---|
81
- | Variables de entorno opt-in | `docs/variables-entorno.md` |
82
- | Reglas de gobernanza extensas | `docs/gobernanza.md` |
83
- | Catálogo de comandos completo | `COMANDOS.md` (referenciar) |
84
- | Mapa de propagación detallado | `docs/mapa-propagacion.md` |
85
- | Convenciones de cada capa | `docs/convenciones-{capa}.md` |
86
-
87
- ### init-user
88
-
89
- Verifica si existe `~/.claude/CLAUDE.md` (en Windows:
90
- `%USERPROFILE%\.claude\CLAUDE.md`). Si no existe, genera template
91
- mínimo:
92
-
93
- ```markdown
94
- # CLAUDE.md (preferencias personales transversales)
95
-
96
- > Este archivo aplica a TODOS mis proyectos. Las reglas específicas de
97
- > proyecto van en el CLAUDE.md de la raíz del proyecto, no aquí.
98
-
99
- ## Mi rol y stack preferido
100
-
101
- - Rol: [ej. ingeniero senior backend]
102
- - Stack preferido: [ej. Python + FastAPI, TypeScript + Next.js]
103
- - Herramientas habituales: [ej. Neovim, ripgrep, fd, gh CLI]
104
-
105
- ## Estilo de comunicación
106
-
107
- - Idioma: español
108
- - Formato preferido para respuestas: [breve / detallado / con tablas]
109
- - Cuándo prefiero ver alternativas vs. una sola recomendación
110
-
111
- ## Patrones que aplico siempre
112
-
113
- - [ej. "Antes de implementar, mostrar el plan"]
114
- - [ej. "Tests para todo código nuevo, sin excepción"]
115
- - [ej. "Commits atómicos en español, formato conventional"]
116
- ```
117
-
118
- Si ya existe, NO lo sobreescribe — sugiere añadir secciones faltantes.
119
-
120
- ### init-project
121
-
122
- Detecta el stack del proyecto actual con `scripts/lib/detectar-stack-detallado.js`
123
- y genera `./CLAUDE.md` mínimo con:
124
-
125
- - Sección **Reglas obligatorias** que **DEBE** incluir como primera línea
126
- bajo el encabezado:
127
- ```markdown
128
- ## Reglas obligatorias
129
-
130
- Aplica la regla global `usar-sistema-swl.md` (matriz operacional del sistema
131
- SWL), auto-cargada desde `.claude/rules/`. NO duplicar su contenido aquí.
132
- ```
133
- Esta mención es obligatoria recuerda la matriz operacional de uso del
134
- sistema SWL. NO usar `@reglas/usar-sistema-swl.md`: la regla se auto-carga
135
- desde `.claude/rules/` y un `@reglas/...` se rompe en proyectos downstream
136
- (ahí no existe `reglas/`). Las demás reglas globales (`seguridad.md`,
137
- `arquitectura.md`, etc.) también se auto-cargan desde `.claude/rules/` — NO
138
- referenciarlas con `@reglas/...`; mencionarlas por nombre si hace falta.
139
- - Sección **Reglas de máxima prioridad** con sub-sección obligatoria
140
- **Cuatro principios de implementación (Karpathy)**:
141
- ```markdown
142
- ### Cuatro principios de implementación (Karpathy)
143
- Antes de implementar, refactorizar o corregir bugs: (1) **pensar antes de codificar** (no asumir en silencio), (2) **simplicidad primero** (sin abstracciones especulativas), (3) **cambios quirúrgicos** (leer archivo completo antes de editar, no refactor de oportunidad), (4) **ejecución orientada a metas** (criterios verificables, test que reproduce bugs antes del fix). Detalle + 9 ejemplos MAL→BIEN: `Skill("prevencion-sobreingenieria")` + `recursos/EXAMPLES.md`.
144
- ```
145
- Esta sub-sección es estándar SWL y cubre los gaps cognitivos más
146
- frecuentes del agente sin agregar reglas específicas del proyecto.
147
- - Sección **Stack** poblada (lenguaje, framework, ORM, package manager)
148
- - Sección **Comandos** poblada (npm scripts detectados o comandos típicos)
149
- - Sección **Code style** vacía con placeholders
150
- - Sección **Conventions** vacía con placeholders
151
- - Sección **@references** apuntando a `.planning/PROYECTO.md`,
152
- `README.md`, etc. si existen
153
-
154
- Si CLAUDE.md ya existe, **NO lo sobreescribe**. Sugiere correr
155
- `/swl:claudemd refactor` para mejorar el actual. Si detecta que el CLAUDE.md
156
- existente NO menciona la regla global `usar-sistema-swl` o NO menciona los cuatro
157
- principios Karpathy (o `prevencion-sobreingenieria`), emitir hallazgo WARN
158
- recomendando agregarlo manualmente.
159
-
160
- ### Validación síncrona post-generación
161
-
162
- Tras `init-project` generar el archivo nuevo, ejecutar inmediatamente
163
- `audit` sobre el resultado:
164
-
165
- ```bash
166
- swl-ses audit-claudemd --json
167
- # Fallback si el script no está en el proyecto destino (instalación global vía npm):
168
- npx -y @saulwade/swl-ses@latest audit-claudemd --json
169
- ```
170
-
171
- Veredicto esperado: `OK` (el template debe respetar el contrato por
172
- construcción). Cualquier WARN/ERROR es bug del template — reportar al
173
- usuario y abrir issue para corrección. Este check es parte del contrato
174
- cruzado con `/swl:aprender` documentado en `@docs/contrato-aprender-claudemd.md`.
175
-
176
- ### audit checks específicos sobre Karpathy
177
-
178
- El subcomando `audit` verifica además de las dimensiones estándar:
179
-
180
- - ¿El CLAUDE.md menciona los cuatro principios Karpathy (texto literal
181
- "Karpathy" o nombres de los 4 principios) o referencia
182
- `prevencion-sobreingenieria` con `Skill(...)` o `@reglas/`?
183
-
184
- Si NO los menciona y el archivo tiene >50 líneas: emitir hallazgo WARN
185
- recomendando agregar la sub-sección compacta (4 líneas) como guía de
186
- implementación. NO emite WARN para CLAUDE.md mínimos (<50 LOC) ni para
187
- archivos `~/.claude/CLAUDE.md` user-level (esos siguen otro contrato).
188
-
189
- ### audit checks específicos sobre duplicación de reglas globales
190
-
191
- El subcomando `audit` también detecta (dimensión 7) si CLAUDE.md duplica
192
- reglas que ya viven en `~/.claude/rules/` y se cargan globalmente.
193
- Consume el catálogo declarativo
194
- `scripts/lib/reglas-globales-conocidas.json` que cataloga 6 reglas
195
- conocidas:
196
-
197
- - `brevedad-output.md` § Idioma obligatorio: español de México
198
- - `brevedad-output.md` § Brevedad y eficiencia de output
199
- - `git-coauthor.md` § Sin co-autores en commits
200
- - `arreglar-al-detectar.md` § Detectar Informar Arreglar
201
- - `debatir-antes-de-aceptar.md`
202
- - `usar-context7.md`
203
-
204
- Si detecta duplicación: emite hallazgo `duplicacion-reglas-globales`
205
- severidad WARN con línea aproximada y remediación específica. NO bloquea
206
- el comando — sirve como nudge para limpiar el CLAUDE.md.
207
-
208
- NO aplica a `~/.claude/CLAUDE.md` user-level (ahí pueden declararse
209
- preferencias personales que parafrasean reglas globales).
210
-
211
- Aplica regla `reglas/sin-duplicacion-reglas-globales.md`.
212
-
213
- ### refactor — propuestas para duplicaciones de reglas globales
214
-
215
- Cuando `audit` detecta duplicaciones, el subcomando `refactor` propone
216
- el reemplazo concreto usando `construirSugerenciaRefactor()` del
217
- detector. Cada propuesta incluye:
218
-
219
- - **Bloque a eliminar** (línea aproximada en CLAUDE.md)
220
- - **Regla global afectada** (archivo + sección canónica)
221
- - **Reemplazo sugerido** (3 opciones):
222
- 1. Eliminar el bloque — la regla global YA aplica automáticamente
223
- 2. Reescribir como matiz local en ≤3 líneas referenciando la regla
224
- 3. Documentar override explícito con justificación
225
-
226
- El refactor SOLO imprime el diff propuesto. El usuario decide aplicar.
227
-
228
- ## Variables de entorno
229
-
230
- Ver `@docs/variables-entorno.md` sección "Calidad de CLAUDE.md":
231
-
232
- - `SWL_CLAUDEMD_BLOAT` (on/off) — activa hook `claudemd-bloat-detector`
233
- - `SWL_CLAUDEMD_MAX_LINES` (default 200) umbral de líneas totales
234
- - `SWL_CLAUDEMD_MAX_BULLET_CHARS` (default 1000) umbral de bullet/párrafo
235
-
236
- ## Exit codes
237
-
238
- - `0` — OK o WARN (consultivo)
239
- - `1` — ERROR o `--strict` + WARN
1
+ ---
2
+ name: swl:claudemd
3
+ 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).
4
+ allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
5
+ ---
6
+
7
+ # /swl:claudemd — Tratamiento profesional de CLAUDE.md
8
+
9
+ Comando para auditar, refactorizar y mantener `CLAUDE.md` siguiendo las
10
+ cinco recomendaciones del video oficial Anthropic *"The CLAUDE.md file"*:
11
+
12
+ 1. **Compacto**empieza sin uno, agrega solo lo que tengas que corregir
13
+ 2. **Stack arriba** — lenguaje, framework, ORM, BD
14
+ 3. **Commands** cómo correr dev, tests, lint, build
15
+ 4. **Code style** convenciones de indentación, exports, nombrado
16
+ 5. **Conventions** — dónde van las cosas, qué patrones preferir
17
+
18
+ **Carga**: `Skill("swl-claudemd")`contiene la lógica de auditoría, las
19
+ secciones canónicas, los umbrales de inflación y los templates de
20
+ generación. Delega análisis y criterios al skill.
21
+
22
+ ## Subcomandos
23
+
24
+ | Subcomando | Propósito |
25
+ |---|---|
26
+ | `/swl:claudemd audit` | Audita el CLAUDE.md actual (líneas, bullets gigantes, secciones canónicas, @references, placeholders) |
27
+ | `/swl:claudemd check` | Como audit pero exit 1 si hay WARN — útil en pre-commit/CI |
28
+ | `/swl:claudemd refactor` | Sugiere extracciones a archivos `@`-referenciados (no modifica, solo propone diff) |
29
+ | `/swl:claudemd init-user` | Crea `~/.claude/CLAUDE.md` con template de preferencias personales si no existe |
30
+ | `/swl:claudemd init-project` | Genera CLAUDE.md raíz del proyecto detectando el stack actual |
31
+
32
+ Sin subcomando: equivale a `audit`.
33
+
34
+ ## Cuándo usar
35
+
36
+ - Después de modificar manualmente CLAUDE.md (verifica calidad)
37
+ - Al inicio de un proyecto que no tenía CLAUDE.md (init-project)
38
+ - Al cambiar de máquina y querer transportar preferencias (init-user)
39
+ - En pre-commit hook si el proyecto trackea CLAUDE.md (check)
40
+ - Cuando el hook `claudemd-bloat-detector` emite nudge
41
+
42
+ ## Ejecución de cada subcomando
43
+
44
+ ### audit / check
45
+
46
+ ```bash
47
+ npx -y @saulwade/swl-ses@latest audit-claudemd # output legible
48
+ npx -y @saulwade/swl-ses@latest audit-claudemd --json # output JSON estructurado
49
+ npx -y @saulwade/swl-ses@latest audit-claudemd --strict # exit 1 si WARN (modo check)
50
+ ```
51
+
52
+ El subcomando `audit-claudemd` del CLI funciona con cualquier modo de instalación
53
+ (global vía `npm i -g`, npx puntual o local dev) porque resuelve el script via
54
+ el paquete npm, no via path relativo al CWD. Es independiente del proyecto desde
55
+ donde se invoque.
56
+
57
+ El veredicto puede ser:
58
+
59
+ - **OK** cumple best practices, sin hallazgos
60
+ - **WARN** — tiene oportunidades de mejora (líneas excesivas, bullets
61
+ gigantes, secciones ausentes, sin @references)
62
+ - **ERROR** no existe, tiene placeholders sin reemplazar, faltan
63
+ secciones críticas
64
+
65
+ ### refactor
66
+
67
+ Lee el CLAUDE.md actual, identifica candidatos a extracción (bullets
68
+ monolíticos, secciones largas, contenido duplicable a `@references`) y
69
+ imprime el diff propuesto. **NO modifica el archivo** — el usuario
70
+ revisa y aplica manualmente o con `git apply`.
71
+
72
+ Patrones de extracción típicos:
73
+
74
+ | Si el bullet/sección contiene… | Mover a… |
75
+ |---|---|
76
+ | Variables de entorno opt-in | `docs/variables-entorno.md` |
77
+ | Reglas de gobernanza extensas | `docs/gobernanza.md` |
78
+ | Catálogo de comandos completo | `COMANDOS.md` (referenciar) |
79
+ | Mapa de propagación detallado | `docs/mapa-propagacion.md` |
80
+ | Convenciones de cada capa | `docs/convenciones-{capa}.md` |
81
+
82
+ ### init-user
83
+
84
+ Verifica si existe `~/.claude/CLAUDE.md` (en Windows:
85
+ `%USERPROFILE%\.claude\CLAUDE.md`). Si no existe, genera template
86
+ mínimo:
87
+
88
+ ```markdown
89
+ # CLAUDE.md (preferencias personales transversales)
90
+
91
+ > Este archivo aplica a TODOS mis proyectos. Las reglas específicas de
92
+ > proyecto van en el CLAUDE.md de la raíz del proyecto, no aquí.
93
+
94
+ ## Mi rol y stack preferido
95
+
96
+ - Rol: [ej. ingeniero senior backend]
97
+ - Stack preferido: [ej. Python + FastAPI, TypeScript + Next.js]
98
+ - Herramientas habituales: [ej. Neovim, ripgrep, fd, gh CLI]
99
+
100
+ ## Estilo de comunicación
101
+
102
+ - Idioma: español
103
+ - Formato preferido para respuestas: [breve / detallado / con tablas]
104
+ - Cuándo prefiero ver alternativas vs. una sola recomendación
105
+
106
+ ## Patrones que aplico siempre
107
+
108
+ - [ej. "Antes de implementar, mostrar el plan"]
109
+ - [ej. "Tests para todo código nuevo, sin excepción"]
110
+ - [ej. "Commits atómicos en español, formato conventional"]
111
+ ```
112
+
113
+ Si ya existe, NO lo sobreescribe sugiere añadir secciones faltantes.
114
+
115
+ ### init-project
116
+
117
+ Detecta el stack del proyecto actual con `scripts/lib/detectar-stack-detallado.js`
118
+ y genera `./CLAUDE.md` mínimo con:
119
+
120
+ - Sección **Reglas obligatorias** que **DEBE** incluir como primera línea
121
+ bajo el encabezado:
122
+ ```markdown
123
+ ## Reglas obligatorias
124
+
125
+ Aplica la regla global `usar-sistema-swl.md` (matriz operacional del sistema
126
+ SWL), auto-cargada desde `.claude/rules/`. NO duplicar su contenido aquí.
127
+ ```
128
+ Esta mención es obligatoria — recuerda la matriz operacional de uso del
129
+ sistema SWL. NO usar `@reglas/usar-sistema-swl.md`: la regla se auto-carga
130
+ desde `.claude/rules/` y un `@reglas/...` se rompe en proyectos downstream
131
+ (ahí no existe `reglas/`). Las demás reglas globales (`seguridad.md`,
132
+ `arquitectura.md`, etc.) también se auto-cargan desde `.claude/rules/` — NO
133
+ referenciarlas con `@reglas/...`; mencionarlas por nombre si hace falta.
134
+ - Sección **Reglas de máxima prioridad** con sub-sección obligatoria
135
+ **Cuatro principios de implementación (Karpathy)**:
136
+ ```markdown
137
+ ### Cuatro principios de implementación (Karpathy)
138
+ Antes de implementar, refactorizar o corregir bugs: (1) **pensar antes de codificar** (no asumir en silencio), (2) **simplicidad primero** (sin abstracciones especulativas), (3) **cambios quirúrgicos** (leer archivo completo antes de editar, no refactor de oportunidad), (4) **ejecución orientada a metas** (criterios verificables, test que reproduce bugs antes del fix). Detalle + 9 ejemplos MAL→BIEN: `Skill("prevencion-sobreingenieria")` + `recursos/EXAMPLES.md`.
139
+ ```
140
+ Esta sub-sección es estándar SWL y cubre los gaps cognitivos más
141
+ frecuentes del agente sin agregar reglas específicas del proyecto.
142
+ - Sección **Stack** poblada (lenguaje, framework, ORM, package manager)
143
+ - Sección **Comandos** poblada (npm scripts detectados o comandos típicos)
144
+ - Sección **Code style** vacía con placeholders
145
+ - Sección **Conventions** vacía con placeholders
146
+ - Sección **@references** apuntando a `.planning/PROYECTO.md`,
147
+ `README.md`, etc. si existen
148
+
149
+ Si CLAUDE.md ya existe, **NO lo sobreescribe**. Sugiere correr
150
+ `/swl:claudemd refactor` para mejorar el actual. Si detecta que el CLAUDE.md
151
+ existente NO menciona la regla global `usar-sistema-swl` o NO menciona los cuatro
152
+ principios Karpathy (o `prevencion-sobreingenieria`), emitir hallazgo WARN
153
+ recomendando agregarlo manualmente.
154
+
155
+ ### Validación síncrona post-generación
156
+
157
+ Tras `init-project` generar el archivo nuevo, ejecutar inmediatamente
158
+ `audit` sobre el resultado:
159
+
160
+ ```bash
161
+ swl-ses audit-claudemd --json
162
+ # Fallback si el script no está en el proyecto destino (instalación global vía npm):
163
+ npx -y @saulwade/swl-ses@latest audit-claudemd --json
164
+ ```
165
+
166
+ Veredicto esperado: `OK` (el template debe respetar el contrato por
167
+ construcción). Cualquier WARN/ERROR es bug del template reportar al
168
+ usuario y abrir issue para corrección. Este check es parte del contrato
169
+ cruzado con `/swl:aprender` documentado en `@docs/contrato-aprender-claudemd.md`.
170
+
171
+ ### audit checks específicos sobre Karpathy
172
+
173
+ El subcomando `audit` verifica además de las dimensiones estándar:
174
+
175
+ - ¿El CLAUDE.md menciona los cuatro principios Karpathy (texto literal
176
+ "Karpathy" o nombres de los 4 principios) o referencia
177
+ `prevencion-sobreingenieria` con `Skill(...)` o `@reglas/`?
178
+
179
+ Si NO los menciona y el archivo tiene >50 líneas: emitir hallazgo WARN
180
+ recomendando agregar la sub-sección compacta (4 líneas) como guía de
181
+ implementación. NO emite WARN para CLAUDE.md mínimos (<50 LOC) ni para
182
+ archivos `~/.claude/CLAUDE.md` user-level (esos siguen otro contrato).
183
+
184
+ ### audit checks específicos sobre duplicación de reglas globales
185
+
186
+ El subcomando `audit` también detecta (dimensión 7) si CLAUDE.md duplica
187
+ reglas que ya viven en `~/.claude/rules/` y se cargan globalmente.
188
+ Consume el catálogo declarativo
189
+ `scripts/lib/reglas-globales-conocidas.json` que cataloga 6 reglas
190
+ conocidas:
191
+
192
+ - `brevedad-output.md` § Idioma obligatorio: español de México
193
+ - `brevedad-output.md` § Brevedad y eficiencia de output
194
+ - `git-coauthor.md` § Sin co-autores en commits
195
+ - `arreglar-al-detectar.md` § Detectar → Informar → Arreglar
196
+ - `debatir-antes-de-aceptar.md`
197
+ - `usar-context7.md`
198
+
199
+ Si detecta duplicación: emite hallazgo `duplicacion-reglas-globales`
200
+ severidad WARN con línea aproximada y remediación específica. NO bloquea
201
+ el comando — sirve como nudge para limpiar el CLAUDE.md.
202
+
203
+ NO aplica a `~/.claude/CLAUDE.md` user-level (ahí sí pueden declararse
204
+ preferencias personales que parafrasean reglas globales).
205
+
206
+ Aplica regla `reglas/sin-duplicacion-reglas-globales.md`.
207
+
208
+ ### refactor propuestas para duplicaciones de reglas globales
209
+
210
+ Cuando `audit` detecta duplicaciones, el subcomando `refactor` propone
211
+ el reemplazo concreto usando `construirSugerenciaRefactor()` del
212
+ detector. Cada propuesta incluye:
213
+
214
+ - **Bloque a eliminar** (línea aproximada en CLAUDE.md)
215
+ - **Regla global afectada** (archivo + sección canónica)
216
+ - **Reemplazo sugerido** (3 opciones):
217
+ 1. Eliminar el bloque — la regla global YA aplica automáticamente
218
+ 2. Reescribir como matiz local en ≤3 líneas referenciando la regla
219
+ 3. Documentar override explícito con justificación
220
+
221
+ El refactor SOLO imprime el diff propuesto. El usuario decide aplicar.
222
+
223
+ ## Variables de entorno
224
+
225
+ Ver `@docs/variables-entorno.md` sección "Calidad de CLAUDE.md":
226
+
227
+ - `SWL_CLAUDEMD_BLOAT` (on/off) — activa hook `claudemd-bloat-detector`
228
+ - `SWL_CLAUDEMD_MAX_LINES` (default 200) — umbral de líneas totales
229
+ - `SWL_CLAUDEMD_MAX_BULLET_CHARS` (default 1000) — umbral de bullet/párrafo
230
+
231
+ ## Exit codes
232
+
233
+ - `0` — OK o WARN (consultivo)
234
+ - `1` ERROR o `--strict` + WARN
@@ -2,11 +2,6 @@
2
2
  name: swl:ejecutar-fase
3
3
  description: Recibe el número de una fase y la implementa siguiendo el PLAN.md. Delega al agente implementador-swl, hace commits atómicos por slice, produce RESUMEN.md y actualiza ESTADO.md y HOJA-RUTA.md al terminar.
4
4
  allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
5
- evolved: true
6
- evolved-from: "1.6.8"
7
- evolved-at: "2026-05-22"
8
- evolved-by: "aprender"
9
- evolved-note: "Paso 4.2 — cota dura 30k tokens al prompt del sub-agente para prevenir autocompact thrashing (origen SIGAF 2026-05-22)"
10
5
  ---
11
6
 
12
7
  # /swl:ejecutar-fase <n> [--iterative] — Ejecutar implementación de una fase