@saulwade/swl-ses 2.6.1 → 2.8.0

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 (268) hide show
  1. package/CLAUDE.md +14 -2
  2. package/README.md +65 -18
  3. package/agentes/_intent-spec.md +73 -73
  4. package/agentes/_propose-step.md +90 -90
  5. package/bin/swl-ses.js +10 -0
  6. package/comandos/swl/brainstorm.md +1 -0
  7. package/comandos/swl/briefing.md +119 -119
  8. package/comandos/swl/contribuir.md +233 -233
  9. package/comandos/swl/deuda-codigo.md +97 -97
  10. package/comandos/swl/mcp-status.md +1 -0
  11. package/gateway/lib/event-channel.js +191 -191
  12. package/habilidades/agent-deep-links/SKILL.md +148 -148
  13. package/habilidades/backend-async-postgres-testing/SKILL.md +216 -216
  14. package/habilidades/backend-error-design/SKILL.md +221 -221
  15. package/habilidades/backend-production-resilience/SKILL.md +288 -288
  16. package/habilidades/calidad-anti-patrones-universales/SKILL.md +105 -1
  17. package/habilidades/calidad-contract-testing/SKILL.md +165 -165
  18. package/habilidades/calidad-mutation-testing/SKILL.md +25 -1
  19. package/habilidades/checklist-seguridad/recursos/stride-cobertura.md +60 -60
  20. package/habilidades/ci-cd-pipelines/SKILL.md +5 -1
  21. package/habilidades/css-moderno/SKILL.md +7 -1
  22. package/habilidades/diagrama-arquitectura/assets/template.html +276 -276
  23. package/habilidades/doubt-driven-review/recursos/EXAMPLES.md +130 -130
  24. package/habilidades/estructura-proyecto-claude/recursos/mcp-json-template.json +57 -57
  25. package/habilidades/extractor-de-aprendizajes/SKILL.md +5 -1
  26. package/habilidades/feynman-auditor-swl/recursos/preguntas-language-agnostic.md +108 -108
  27. package/habilidades/harness-claude-code/SKILL.md +3 -2
  28. package/habilidades/meta-skills-estandar/recursos/convencion-examples.md +93 -93
  29. package/habilidades/patrones-python/recursos/patrones-avanzados.md +469 -469
  30. package/habilidades/perfil-usuario/SKILL.md +200 -200
  31. package/habilidades/prevencion-sobreingenieria/recursos/EXAMPLES.md +580 -580
  32. package/habilidades/prevencion-sobreingenieria/recursos/soluciones-nativas.md +166 -166
  33. package/habilidades/prevencion-sobreingenieria/recursos/variables-residuales-post-refactor.md +85 -85
  34. package/habilidades/proceso-ddia-streaming/SKILL.md +231 -231
  35. package/habilidades/proceso-discovery-machote/SKILL.md +157 -157
  36. package/habilidades/proceso-dynamic-workflows/SKILL.md +60 -0
  37. package/habilidades/proceso-dynamic-workflows/recursos/template-adversarial-verify.js +65 -65
  38. package/habilidades/proceso-dynamic-workflows/recursos/template-triage.js +65 -65
  39. package/habilidades/proceso-intent-engineering/SKILL.md +269 -269
  40. package/habilidades/proceso-modular-split/SKILL.md +256 -256
  41. package/habilidades/state-inconsistency-auditor-swl/recursos/coupled-state-patterns.md +147 -147
  42. package/habilidades/swl-claudemd/recursos/contrato-aprender.md +83 -83
  43. package/habilidades/swl-claudemd/recursos/duplicacion-reglas-globales.md +85 -85
  44. package/habilidades/swl-claudemd/recursos/plantillas-init.md +94 -94
  45. package/habilidades/tdd-workflow/recursos/gherkin-bdd.md +111 -111
  46. package/hooks/calidad-pre-commit.js +159 -10
  47. package/hooks/ciclo-evolucion-subagente.js +26 -26
  48. package/hooks/ciclo-evolucion.js +26 -26
  49. package/hooks/contexto-subagente.js +68 -68
  50. package/hooks/lib/auto-consolidator.js +335 -335
  51. package/hooks/lib/ciclo-evolucion.js +47 -47
  52. package/hooks/lib/deep-links.js +185 -185
  53. package/hooks/lib/error-classifier.js +308 -308
  54. package/hooks/lib/notificacion-formato.js +45 -11
  55. package/hooks/lib/provenance-tracker.js +191 -191
  56. package/hooks/lib/raiz-proyecto.js +35 -4
  57. package/hooks/lib/resource-quota.js +122 -122
  58. package/hooks/lib/retry-jitter.js +165 -165
  59. package/hooks/lib/security-net.js +201 -201
  60. package/hooks/lib/skill-auditor.js +588 -588
  61. package/hooks/lib/sync-status.js +228 -228
  62. package/hooks/lib/taint-tracker.js +107 -107
  63. package/hooks/lib/text-similarity.js +241 -241
  64. package/hooks/lib/toon-compressor.js +245 -245
  65. package/hooks/notificacion-telegram.js +5 -11
  66. package/hooks/session-briefing.js +12 -4
  67. package/instintos/autonomia.yaml +27 -27
  68. package/instintos/prompt-appendices.yaml +57 -57
  69. package/llms.txt +1 -1
  70. package/manifiestos/agent-output-schemas.json +57 -57
  71. package/manifiestos/canonical-hashes.json +662 -0
  72. package/manifiestos/harness-ir.json +47536 -0
  73. package/manifiestos/hooks-config.json +469 -469
  74. package/manifiestos/invariantes-criticos.json +30 -30
  75. package/manifiestos/policy-bundle.json +2065 -0
  76. package/manifiestos/policy-corpus-w2.json +3926 -0
  77. package/manifiestos/runtime-adapters-core3.json +208 -0
  78. package/manifiestos/runtime-conformance.json +139 -0
  79. package/manifiestos/skills-lock.json +43 -43
  80. package/package.json +2 -2
  81. package/plantillas/auditor-veto-template.md +105 -105
  82. package/plantillas/github-workflows/release-please.yml +44 -44
  83. package/plantillas/github-workflows/swl-ci.yml +107 -107
  84. package/plantillas/github-workflows/swl-security.yml +51 -51
  85. package/plugin.json +2 -2
  86. package/reglas/accesibilidad.md +10 -10
  87. package/reglas/auditorias-documentales-estructurales.md +7 -7
  88. package/reglas/cloud-infra.md +8 -8
  89. package/reglas/consultar-vault-primero.md +195 -195
  90. package/reglas/git-workflow.md +1 -0
  91. package/reglas/hooks.md +6 -6
  92. package/reglas/intent-engineering.md +218 -218
  93. package/reglas/markitdown.md +8 -8
  94. package/reglas/monitor-ci.md +12 -0
  95. package/reglas/patrones.md +6 -6
  96. package/reglas/testing.md +7 -7
  97. package/reglas/tests-cleanup.md +224 -224
  98. package/schemas/agent-message.schema.json +73 -73
  99. package/schemas/agent-output-implementacion.schema.json +114 -114
  100. package/schemas/agent-output-planificacion.schema.json +150 -150
  101. package/schemas/agent-output-review.schema.json +98 -98
  102. package/schemas/diary-entry.schema.json +112 -112
  103. package/schemas/gate-state.schema.json +76 -0
  104. package/schemas/harness-ir.schema.json +369 -0
  105. package/schemas/hook-profiles.schema.json +54 -54
  106. package/schemas/hooks-config.schema.json +89 -89
  107. package/schemas/legacy-gates.schema.json +45 -0
  108. package/schemas/modulos.schema.json +38 -38
  109. package/schemas/perfiles.schema.json +36 -36
  110. package/schemas/plugin.schema.json +77 -77
  111. package/schemas/policy-bundle.schema.json +140 -0
  112. package/schemas/policy-enforcement.schema.json +117 -0
  113. package/schemas/policy-operation.schema.json +261 -0
  114. package/schemas/runtime-adapter.schema.json +176 -0
  115. package/schemas/runtime-build-attestation.schema.json +100 -0
  116. package/schemas/runtime-conformance.schema.json +239 -0
  117. package/schemas/runtime-diagnostic.schema.json +395 -0
  118. package/schemas/skill-evals.schema.json +119 -119
  119. package/schemas/skill-frontmatter.schema.json +245 -245
  120. package/schemas/w4-certification-request.schema.json +72 -0
  121. package/schemas/w4-certification-verdict.schema.json +224 -0
  122. package/schemas/w4-corpus.schema.json +172 -0
  123. package/schemas/w4-mutation-report.schema.json +116 -0
  124. package/schemas/w4-replay-result.schema.json +164 -0
  125. package/schemas/w4-scoring-report.schema.json +89 -0
  126. package/scripts/audit-tools/audit-history.js +330 -330
  127. package/scripts/audit-tools/bundle-tracker.js +290 -290
  128. package/scripts/audit-tools/canary-monitor.js +352 -352
  129. package/scripts/audit-tools/code-profiler.js +605 -605
  130. package/scripts/audit-tools/dep-doctor.js +320 -320
  131. package/scripts/audit-tools/env-validator.js +206 -206
  132. package/scripts/audit-tools/lib/fs-walk.js +48 -48
  133. package/scripts/audit-tools/lib/output.js +23 -23
  134. package/scripts/audit-tools/migration-checker.js +392 -392
  135. package/scripts/audit-tools/pentest-scanner.js +1436 -1436
  136. package/scripts/bootstrap-instintos.js +3 -0
  137. package/scripts/cli/aprobar-plan.js +73 -73
  138. package/scripts/cli/briefing.js +23 -23
  139. package/scripts/cli/ciclo-evolucion.js +26 -26
  140. package/scripts/cli/derivar-feature-list.js +25 -25
  141. package/scripts/cli/detectar-host.js +27 -27
  142. package/scripts/cli/diary-entry.js +69 -69
  143. package/scripts/cli/execution-state.js +18 -18
  144. package/scripts/cli/gateway-notify.js +41 -41
  145. package/scripts/cli/liberar-fase.js +42 -42
  146. package/scripts/cli/mark-evolved.js +56 -56
  147. package/scripts/cli/metricas-dora.js +26 -26
  148. package/scripts/cli/near-duplicate.js +55 -55
  149. package/scripts/cli/notificaciones.js +123 -123
  150. package/scripts/cli/propose-step.js +29 -29
  151. package/scripts/cli/schedule-parse.js +19 -19
  152. package/scripts/cli/sugerir-modelo.js +20 -20
  153. package/scripts/cli/verificar-plan.js +36 -36
  154. package/scripts/cli/verificar-trazabilidad.js +35 -35
  155. package/scripts/comandos/install-asistido.js +8 -7
  156. package/scripts/configurar-branch-protection.js +418 -418
  157. package/scripts/detectar-aprendizajes-duplicados.js +151 -151
  158. package/scripts/doctor.js +61 -36
  159. package/scripts/generar-checklists-consolidados.js +273 -273
  160. package/scripts/generar-claims-runtime.js +1342 -0
  161. package/scripts/generar-harness-ir.js +257 -0
  162. package/scripts/generar-inventario.js +52 -54
  163. package/scripts/generar-policy-bundle.js +202 -0
  164. package/scripts/instalador.js +26 -7
  165. package/scripts/lib/approval-receipts.js +190 -0
  166. package/scripts/lib/artefactos-python.js +43 -43
  167. package/scripts/lib/benchmark-metrics.js +160 -160
  168. package/scripts/lib/budget-enforcer.js +252 -252
  169. package/scripts/lib/certificacion-loop-state.js +421 -0
  170. package/scripts/lib/ci-reader.js +193 -193
  171. package/scripts/lib/ciclo-autonomo/yaml-instintos.js +56 -0
  172. package/scripts/lib/clasificar-directorio.js +92 -0
  173. package/scripts/lib/contadores-inventario.js +217 -217
  174. package/scripts/lib/detectar-host-swl.js +175 -175
  175. package/scripts/lib/detectar-runtime.js +29 -20
  176. package/scripts/lib/detectar-stack-detallado.js +307 -307
  177. package/scripts/lib/detector-autoduplicacion-intra-archivo.js +234 -234
  178. package/scripts/lib/detector-reglas-duplicadas.js +220 -220
  179. package/scripts/lib/eval-metrics-store.js +218 -218
  180. package/scripts/lib/eval-quality.js +171 -171
  181. package/scripts/lib/eval-schemas.js +144 -144
  182. package/scripts/lib/eval-self-correct.js +106 -106
  183. package/scripts/lib/eval-validator.js +185 -185
  184. package/scripts/lib/evidence-verifier.js +192 -0
  185. package/scripts/lib/evidencia-release.js +322 -322
  186. package/scripts/lib/frontmatter-canonico.js +509 -0
  187. package/scripts/lib/gate-engine.js +871 -0
  188. package/scripts/lib/gate-hooks-requires.js +249 -249
  189. package/scripts/lib/gate-licencias.js +212 -212
  190. package/scripts/lib/git-config-preflight.js +48 -0
  191. package/scripts/lib/git-metricas.js +257 -257
  192. package/scripts/lib/harness-ir.js +778 -0
  193. package/scripts/lib/harness-source-snapshot.js +309 -0
  194. package/scripts/lib/integrity-ledger.js +1147 -0
  195. package/scripts/lib/jaccard-similarity.js +98 -98
  196. package/scripts/lib/legacy-gate-migration.js +324 -0
  197. package/scripts/lib/limpiar-basura-global.js +45 -2
  198. package/scripts/lib/longmemeval-runner.js +125 -125
  199. package/scripts/lib/metricas-dora.js +204 -204
  200. package/scripts/lib/notificaciones-telegram.js +1 -0
  201. package/scripts/lib/npm-version.js +1 -0
  202. package/scripts/lib/paquetes-conocidos.js +50 -50
  203. package/scripts/lib/plan-lock.js +61 -13
  204. package/scripts/lib/policy-broker.js +338 -0
  205. package/scripts/lib/policy-bundle.js +342 -0
  206. package/scripts/lib/policy-context-provider.js +310 -0
  207. package/scripts/lib/policy-contract.js +479 -0
  208. package/scripts/lib/policy-verifier-utils.js +65 -0
  209. package/scripts/lib/pr-analyzer.js +399 -399
  210. package/scripts/lib/principal-verifier.js +178 -0
  211. package/scripts/lib/prompt-builder.js +264 -264
  212. package/scripts/lib/resolver-plan-fase.js +37 -37
  213. package/scripts/lib/rrf-fusion.js +175 -175
  214. package/scripts/lib/runtime-adapter-contract.js +267 -0
  215. package/scripts/lib/runtime-artifact-verifier.js +426 -0
  216. package/scripts/lib/runtime-build-attestation.js +127 -0
  217. package/scripts/lib/runtime-bundle-installer.js +586 -0
  218. package/scripts/lib/runtime-compiler.js +327 -0
  219. package/scripts/lib/runtime-conformance.js +202 -0
  220. package/scripts/lib/runtime-doctor-core3.js +567 -0
  221. package/scripts/lib/runtime-doctor-input.js +59 -0
  222. package/scripts/lib/runtime-operation-adapter.js +267 -0
  223. package/scripts/lib/schema-version.js +164 -164
  224. package/scripts/lib/semantic-search.js +252 -252
  225. package/scripts/lib/signed-envelope.js +545 -0
  226. package/scripts/lib/single-use-store.js +359 -0
  227. package/scripts/lib/skills-externas.js +31 -0
  228. package/scripts/lib/transformadores/codex.js +15 -8
  229. package/scripts/lib/transformadores/gemini.js +79 -5
  230. package/scripts/lib/w4-attestation-adapter.js +158 -0
  231. package/scripts/lib/w4-canario.js +337 -0
  232. package/scripts/lib/w4-claims.js +182 -0
  233. package/scripts/lib/w4-corpus-generador.js +542 -0
  234. package/scripts/lib/w4-gate-c5.js +115 -0
  235. package/scripts/lib/w4-harness-bajo-prueba.js +155 -0
  236. package/scripts/lib/w4-matriz-combos.js +55 -0
  237. package/scripts/lib/w4-motor-mutacion.js +1348 -0
  238. package/scripts/lib/w4-motor-replay.js +735 -0
  239. package/scripts/lib/w4-pin-origen.js +54 -0
  240. package/scripts/lib/w4-publicar-request.js +132 -0
  241. package/scripts/lib/w4-revocacion.js +62 -0
  242. package/scripts/lib/w4-runtimes-core3.js +38 -0
  243. package/scripts/lib/w4-scorer-certificacion.js +692 -0
  244. package/scripts/lib/w4-superficie-candidato.js +49 -0
  245. package/scripts/lib/w4-veredicto.js +452 -0
  246. package/scripts/lib/w4-verificar-veredicto.js +302 -0
  247. package/scripts/limpiar-artefactos-python.js +131 -131
  248. package/scripts/migrar-csv-a-array.js +168 -168
  249. package/scripts/migrar-fase-dominio.js +200 -200
  250. package/scripts/migrar-gates-legacy.js +108 -0
  251. package/scripts/publicar-certification-request.js +115 -0
  252. package/scripts/runtime-doctor.js +107 -0
  253. package/scripts/tui/componentes/selector-multi.js +189 -189
  254. package/scripts/tui/componentes/selector-unico.js +158 -158
  255. package/scripts/tui/ejecutores.js +375 -375
  256. package/scripts/tui/lib/colores.js +129 -129
  257. package/scripts/tui/lib/render.js +264 -264
  258. package/scripts/tui/lib/teclas.js +113 -113
  259. package/scripts/tui/pantallas/install-wizard.js +12 -7
  260. package/scripts/tui/pantallas/menu-principal.js +52 -52
  261. package/scripts/tui/pantallas/progreso.js +274 -274
  262. package/scripts/tui/pantallas/resumen.js +132 -132
  263. package/scripts/validar-userland-vacio.js +110 -110
  264. package/scripts/verificar-aislamiento-swl-eval.js +87 -0
  265. package/scripts/verificar-empaquetado-downstream.js +375 -0
  266. package/scripts/verificar-loop-constructor.js +215 -0
  267. package/scripts/verificar-trazabilidad.js +13 -6
  268. package/scripts/verificar-veredicto-real.js +84 -0
@@ -1,269 +1,269 @@
1
- ---
2
- name: proceso-intent-engineering
3
- description: >
4
- Framework "Intent Engineering" de 8 partes (Pawel Huryn, 2024-2026) para
5
- especificar agentes IA: Strategy, Objective, Desired Outcomes, Health Metrics,
6
- Org Context, Constraints (steering+hardGuardrails), Autonomy Boundaries, Stop
7
- Rules. Cargar cuando se cree un agente nuevo nivelRiesgo:ALTO, se audite uno
8
- existente, o se diagnostique un agente que falla por intent incompleto.
9
- when_to_use: >
10
- Usar cuando el usuario menciona crear agente nuevo, refactor de agente ALTO,
11
- promover MEDIO a ALTO, agente que "se desvia del objetivo", agente que ignora
12
- restricciones blandas, intent spec, /goal, agentes que fallan por instrucciones
13
- ambiguas, health metrics, steering vs guardrails.
14
- ---
15
-
16
- # Intent Engineering — el framework de 8 partes para agentes
17
-
18
- ## Cuándo cargar
19
-
20
- - Diseñar un agente nuevo `nivelRiesgo: ALTO` (uso obligatorio según
21
- `reglas/intent-engineering.md`).
22
- - Refactorizar un agente existente que falla por intent ambiguo.
23
- - Auditar un agente con `/swl:revisar` y se detecta "deriva de scope".
24
- - Decidir cómo materializar restricciones blandas (steering) vs duras
25
- (hardGuardrails) en un agente.
26
- - Promover un agente de `MEDIO` a `ALTO` — la regla exige las 8 partes.
27
-
28
- ## Cuándo NO cargar
29
-
30
- - Agente `BAJO` o `MEDIO` riesgo — declarar las 8 partes es overkill.
31
- - Fix puntual de typo o ajuste de descripción de un agente existente.
32
- - Crear skill (no agente) — el framework aplica a agentes, no a skills.
33
- - Investigación de tooling externo (carga `investigador-swl`).
34
-
35
- ## Fuente y verificación
36
-
37
- Adaptado de Pawel Huryn, *"Lead Agents Like Humans"* (Product Compass,
38
- 2026-05). La cita clave que justifica las 8 partes:
39
-
40
- > "Lead agents the way good orgs lead empowered teams. OKRs (2016) →
41
- > empowered teams (2020) → intent engineering (2024). /goal is two of
42
- > eight parts." (Huryn, línea 5)
43
-
44
- `/goal` (slash command de Codex y Claude Code) cubre las partes 2 y 3.
45
- Las otras seis son responsabilidad del autor del agente.
46
-
47
- ## Las 8 partes — qué declarar y dónde vive en SWL
48
-
49
- ### Parte 1 — Strategy
50
-
51
- Visión, mercado, propuesta de valor, tradeoffs. Huryn lo describe así:
52
-
53
- > "You wouldn't onboard a senior PM with 'handle customer support.' You'd
54
- > ground them in the strategy first: vision, market, value proposition,
55
- > trade-offs." (línea 43)
56
-
57
- **Dónde vive en SWL**: frontmatter `strategy: "..."` (máx 500 chars).
58
- Cuando un agente operativo (`backend-python-swl`, `frontend-react-swl`)
59
- necesita strategy específica al proyecto, hereda del `CLAUDE.md`. Cuando
60
- el rol del agente impone trade-offs propios (`producto-prd-swl`,
61
- `arquitecto-swl`), se declara explícito.
62
-
63
- Ejemplo (`arquitecto-swl`):
64
- ```yaml
65
- strategy: >
66
- Diseñar para evolvabilidad sobre completitud inicial. Módulos profundos
67
- (Ousterhout) sobre micro-servicios prematuros. ADRs sobre wikis. Reversible
68
- sobre óptimo cuando el costo de equivocarse es bajo.
69
- ```
70
-
71
- ### Parte 2 — Objective
72
-
73
- El problema y por qué importa. Guía el juicio cuando las instrucciones se
74
- agotan.
75
-
76
- **Dónde vive en SWL**: campo `description:` del agente. Ya obligatorio
77
- por schema. Para captura la regla "qué hace + cuándo invocarlo".
78
-
79
- ### Parte 3 — Desired Outcomes
80
-
81
- Estados observables (no actividades) que prueban el objetivo cumplido.
82
- Huryn enumera 4 reglas:
83
-
84
- - Observable states, not agent activities.
85
- - From the user's perspective, not the agent's.
86
- - Measurable or verifiable without relying on agent self-report.
87
- - Leading, not lagging.
88
-
89
- **Dónde vive en SWL**: criterios de aceptación en `PLAN.md` por feature.
90
- El `/swl:verificar` con goal-backward valida outcomes en 4 niveles.
91
-
92
- ### Parte 4 — Health Metrics
93
-
94
- Lo que NO debe degradar mientras se persiguen outcomes. Cita textual:
95
-
96
- > "Goodhart's Law: when a measure becomes a target, it stops being a good
97
- > measure. [...] Health metrics steer; guardrails enforce." (líneas 134, 150)
98
-
99
- **Dónde vive en SWL**: frontmatter `healthMetrics: [...]`. Diferencia
100
- clave con outcomes: outcomes son lo que persigues; health metrics son lo
101
- que proteges mientras persigues.
102
-
103
- Ejemplo (`migrador-swl`):
104
- ```yaml
105
- healthMetrics:
106
- - Integridad referencial de datos durante toda la ventana de migración
107
- - Tiempo de downtime <= 0 (expand-contract obligatorio)
108
- - Tests preexistentes verde antes y después
109
- - Sin warnings nuevos de ORM (N+1, lazy loading)
110
- ```
111
-
112
- Si el agente detecta que una health metric está cayendo, **debe ser más
113
- conservador, no más agresivo** — esa es la diferencia operacional con un
114
- outcome.
115
-
116
- ### Parte 5 — Org Context
117
-
118
- Sistema (otros agentes, hooks, tooling) + organización (proyecto, usuario,
119
- dominio). No todo va en el prompt:
120
-
121
- > "Core context (always needed) goes in the system prompt. Reference
122
- > context goes in retrieval. Dynamic context (per-request) goes in the
123
- > orchestration layer." (línea 159, parafraseada)
124
-
125
- **Dónde vive en SWL**: `CLAUDE.md` del proyecto (org), `contextos/`
126
- (dev/review/research), `INVENTARIO.md` (system context). El agente no
127
- necesita declararlo — lo recibe vía carga inicial.
128
-
129
- ### Parte 6 — Constraints (los dos tipos)
130
-
131
- Huryn separa muy claramente:
132
-
133
- **Steering prompts (prompt-level)** — texto que el agente lee y debería
134
- seguir, pero puede ignorar bajo presión:
135
- - Behavioral guidance
136
- - Risk preferences
137
- - Tone and caution
138
-
139
- **Hard guardrails (orchestration-level)** — restricciones aplicadas en
140
- arquitectura, no en lenguaje:
141
- - Tool restrictions
142
- - Output validation
143
- - Action gating
144
- - Approval gates (HITL)
145
-
146
- > "If a constraint matters, it must be enforced in architecture, not
147
- > language. [...] The reasoning layer proposes. The orchestration layer
148
- > enforces. If a constraint lives only in the prompt, it's a suggestion."
149
- > (líneas 196, 197 paraf., 198)
150
-
151
- **Dónde vive en SWL**:
152
- - `steering: [...]` en frontmatter del agente (texto que el modelo lee)
153
- - `hardGuardrails: [...]` declara qué hook/regla/schema enforza qué
154
- restricción. Sintaxis: `@reglas/X.md`, `@hooks/Y.js`, o texto inline
155
- si es específico al agente.
156
-
157
- Anti-patrón: declarar como `steering` algo que necesita enforcement real
158
- ("no eliminar archivos" sin hook que lo prevenga). Si la restricción
159
- importa, va en `hardGuardrails` con apoyo de hook/permiso/schema.
160
-
161
- ### Parte 7 — Autonomy Boundaries
162
-
163
- Huryn define 4 niveles:
164
-
165
- 1. **Full Autonomy** — acciones reversibles, impacto limitado, modos de
166
- falla conocidos.
167
- 2. **Guarded Autonomy** — cambios visibles al usuario, riesgo medio.
168
- Requiere logging y rollback.
169
- 3. **Proposal-First** — decisiones estratégicas. El agente propone, el
170
- humano aprueba, el agente ejecuta.
171
- 4. **No Autonomy (Human-Required)** — compromisos legales, cambios
172
- irreversibles, acciones financieras.
173
-
174
- **Mapeo a SWL** (3 niveles, no 4 — decisión consciente, ver ADR-0025):
175
-
176
- | Huryn 4-tier | SWL `nivelRiesgo` | HITL? |
177
- |---|---|---|
178
- | Full Autonomy | BAJO | No |
179
- | Guarded Autonomy | MEDIO | Solo en ramas críticas |
180
- | Proposal-First | ALTO | Sí, antes de mutaciones irreversibles |
181
- | Human-Required | ALTO + `permisos*: false` | Sí, siempre |
182
-
183
- El nivel 4 de Huryn se modela en SWL como ALTO + permisos restrictivos en
184
- frontmatter. NO se introduce un cuarto tier en el enum `nivelRiesgo`.
185
-
186
- ### Parte 8 — Stop Rules
187
-
188
- Tres tipos de stop, todos load-bearing:
189
-
190
- - **Halt** — restricciones en conflicto, confianza cae 2x consecutivas,
191
- `maxTurnos` alcanzado.
192
- - **Escalate** — fuera de scope, tema legal/compliance detectado,
193
- frustración persistente.
194
- - **Complete** — outcomes alcanzados, usuario confirma.
195
-
196
- > "Halt and escalate are the load-bearing branches, and /goal ships
197
- > neither." (línea 271)
198
-
199
- **Dónde vive en SWL**:
200
- - `maxTurnos:` en frontmatter — tope de iteraciones.
201
- - Recovery Catalog en `reglas/seguridad-agentes.md § Recovery Catalog` —
202
- reprompt → reduce-autonomy → escalate → terminate.
203
- - `notificador-swl` para escalado a humano vía Telegram/desktop.
204
-
205
- ## Cómo aplicar el framework a un agente nuevo
206
-
207
- 1. Cargar este skill antes de escribir el primer carácter del agente.
208
- 2. Importar `agentes/_intent-spec.md` con `fragmentos: [_intent-spec]`.
209
- 3. Declarar los 4 campos opcionales del schema:
210
- - `strategy:` (Parte 1)
211
- - `healthMetrics:` (Parte 4)
212
- - `steering:` (Parte 6 — soft)
213
- - `hardGuardrails:` (Parte 6 — hard)
214
- 4. Verificar que `description` cubre Parte 2 (Objective).
215
- 5. Verificar que `nivelRiesgo` mapea a Parte 7 (Autonomy Boundaries).
216
- 6. Verificar que `maxTurnos` está declarado si hay loop interno (Parte 8).
217
- 7. Org Context (Parte 5) vive en CLAUDE.md — no se duplica en el agente.
218
- 8. Desired Outcomes (Parte 3) vive en PLAN.md de cada invocación — no se
219
- hardcodea en el agente.
220
-
221
- ## Anti-patrones específicos a evitar
222
-
223
- - **`steering` que debería ser `hardGuardrails`**: "no eliminar tablas"
224
- sin hook `proteccion-rutas.js` o equivalente. Si importa, va en
225
- arquitectura.
226
- - **Health metrics como outcomes negados**: "no degradar latencia" es
227
- health metric; "latencia < 200ms p95" es outcome. La diferencia: outcome
228
- se persigue, health metric se protege mientras se persigue.
229
- - **Strategy demasiado genérica**: "código limpio y mantenible" no es
230
- strategy de un agente — es default. Strategy debe nombrar el tradeoff
231
- específico que ese agente prioriza.
232
- - **Autonomy Boundaries por ego, no por riesgo**: `nivelRiesgo: ALTO` no
233
- es prestigio; es declaración de que el agente toca cosas
234
- irreversibles. Si BAJO o MEDIO basta, no inflar.
235
- - **Stop Rules ausentes**: agente sin `maxTurnos` ni recovery declarado
236
- puede entrar en loop infinito. Default seguro: 10-15 turnos.
237
-
238
- ## Gotchas no obvios
239
-
240
- - **Health metrics no se enforce por sí solas**: el agente las lee y se
241
- comporta más conservador, pero NO hay hook que las verifique
242
- automáticamente. Diseñar telemetría que las capture si el agente es
243
- crítico.
244
- - **`steering` y `hardGuardrails` aceptan `@reglas/X.md`**: cuando una
245
- restricción es global, no copiar el texto — referenciar la regla
246
- evita drift.
247
- - **El framework no resuelve ambigüedad de objetivos en conflicto**:
248
- si dos health metrics chocan entre sí, la prioridad debe declararse
249
- como tradeoff en `strategy`.
250
-
251
- ## Referencia rápida — campos por nivelRiesgo
252
-
253
- | Campo | BAJO | MEDIO | ALTO |
254
- |---|---|---|---|
255
- | `description` (Parte 2) | Obligatorio | Obligatorio | Obligatorio |
256
- | `nivelRiesgo` (Parte 7) | Obligatorio | Obligatorio | Obligatorio |
257
- | `maxTurnos` (Parte 8) | Recomendado | Recomendado | Obligatorio |
258
- | `strategy` (Parte 1) | Opcional | Opcional | Obligatorio |
259
- | `healthMetrics` (Parte 4) | Opcional | Opcional | Obligatorio |
260
- | `steering` (Parte 6) | Opcional | Recomendado | Recomendado |
261
- | `hardGuardrails` (Parte 6) | Opcional | Recomendado | Obligatorio |
262
- | `fragmentos: [_intent-spec]` | Opcional | Opcional | Obligatorio |
263
-
264
- ## Origen
265
-
266
- Skill creado el 2026-05-18 como parte de Opción B de integración
267
- `temp/Lead-agents-like-humans.md` + `temp/DDIA*.md`. Ver ADR-0025 para la
268
- decisión de scope. Fragment compartido `_intent-spec` es la
269
- versión system-prompt-embebida; este skill es la versión invocable on-demand.
1
+ ---
2
+ name: proceso-intent-engineering
3
+ description: >
4
+ Framework "Intent Engineering" de 8 partes (Pawel Huryn, 2024-2026) para
5
+ especificar agentes IA: Strategy, Objective, Desired Outcomes, Health Metrics,
6
+ Org Context, Constraints (steering+hardGuardrails), Autonomy Boundaries, Stop
7
+ Rules. Cargar cuando se cree un agente nuevo nivelRiesgo:ALTO, se audite uno
8
+ existente, o se diagnostique un agente que falla por intent incompleto.
9
+ when_to_use: >
10
+ Usar cuando el usuario menciona crear agente nuevo, refactor de agente ALTO,
11
+ promover MEDIO a ALTO, agente que "se desvia del objetivo", agente que ignora
12
+ restricciones blandas, intent spec, /goal, agentes que fallan por instrucciones
13
+ ambiguas, health metrics, steering vs guardrails.
14
+ ---
15
+
16
+ # Intent Engineering — el framework de 8 partes para agentes
17
+
18
+ ## Cuándo cargar
19
+
20
+ - Diseñar un agente nuevo `nivelRiesgo: ALTO` (uso obligatorio según
21
+ `reglas/intent-engineering.md`).
22
+ - Refactorizar un agente existente que falla por intent ambiguo.
23
+ - Auditar un agente con `/swl:revisar` y se detecta "deriva de scope".
24
+ - Decidir cómo materializar restricciones blandas (steering) vs duras
25
+ (hardGuardrails) en un agente.
26
+ - Promover un agente de `MEDIO` a `ALTO` — la regla exige las 8 partes.
27
+
28
+ ## Cuándo NO cargar
29
+
30
+ - Agente `BAJO` o `MEDIO` riesgo — declarar las 8 partes es overkill.
31
+ - Fix puntual de typo o ajuste de descripción de un agente existente.
32
+ - Crear skill (no agente) — el framework aplica a agentes, no a skills.
33
+ - Investigación de tooling externo (carga `investigador-swl`).
34
+
35
+ ## Fuente y verificación
36
+
37
+ Adaptado de Pawel Huryn, *"Lead Agents Like Humans"* (Product Compass,
38
+ 2026-05). La cita clave que justifica las 8 partes:
39
+
40
+ > "Lead agents the way good orgs lead empowered teams. OKRs (2016) →
41
+ > empowered teams (2020) → intent engineering (2024). /goal is two of
42
+ > eight parts." (Huryn, línea 5)
43
+
44
+ `/goal` (slash command de Codex y Claude Code) cubre las partes 2 y 3.
45
+ Las otras seis son responsabilidad del autor del agente.
46
+
47
+ ## Las 8 partes — qué declarar y dónde vive en SWL
48
+
49
+ ### Parte 1 — Strategy
50
+
51
+ Visión, mercado, propuesta de valor, tradeoffs. Huryn lo describe así:
52
+
53
+ > "You wouldn't onboard a senior PM with 'handle customer support.' You'd
54
+ > ground them in the strategy first: vision, market, value proposition,
55
+ > trade-offs." (línea 43)
56
+
57
+ **Dónde vive en SWL**: frontmatter `strategy: "..."` (máx 500 chars).
58
+ Cuando un agente operativo (`backend-python-swl`, `frontend-react-swl`)
59
+ necesita strategy específica al proyecto, hereda del `CLAUDE.md`. Cuando
60
+ el rol del agente impone trade-offs propios (`producto-prd-swl`,
61
+ `arquitecto-swl`), se declara explícito.
62
+
63
+ Ejemplo (`arquitecto-swl`):
64
+ ```yaml
65
+ strategy: >
66
+ Diseñar para evolvabilidad sobre completitud inicial. Módulos profundos
67
+ (Ousterhout) sobre micro-servicios prematuros. ADRs sobre wikis. Reversible
68
+ sobre óptimo cuando el costo de equivocarse es bajo.
69
+ ```
70
+
71
+ ### Parte 2 — Objective
72
+
73
+ El problema y por qué importa. Guía el juicio cuando las instrucciones se
74
+ agotan.
75
+
76
+ **Dónde vive en SWL**: campo `description:` del agente. Ya obligatorio
77
+ por schema. Para captura la regla "qué hace + cuándo invocarlo".
78
+
79
+ ### Parte 3 — Desired Outcomes
80
+
81
+ Estados observables (no actividades) que prueban el objetivo cumplido.
82
+ Huryn enumera 4 reglas:
83
+
84
+ - Observable states, not agent activities.
85
+ - From the user's perspective, not the agent's.
86
+ - Measurable or verifiable without relying on agent self-report.
87
+ - Leading, not lagging.
88
+
89
+ **Dónde vive en SWL**: criterios de aceptación en `PLAN.md` por feature.
90
+ El `/swl:verificar` con goal-backward valida outcomes en 4 niveles.
91
+
92
+ ### Parte 4 — Health Metrics
93
+
94
+ Lo que NO debe degradar mientras se persiguen outcomes. Cita textual:
95
+
96
+ > "Goodhart's Law: when a measure becomes a target, it stops being a good
97
+ > measure. [...] Health metrics steer; guardrails enforce." (líneas 134, 150)
98
+
99
+ **Dónde vive en SWL**: frontmatter `healthMetrics: [...]`. Diferencia
100
+ clave con outcomes: outcomes son lo que persigues; health metrics son lo
101
+ que proteges mientras persigues.
102
+
103
+ Ejemplo (`migrador-swl`):
104
+ ```yaml
105
+ healthMetrics:
106
+ - Integridad referencial de datos durante toda la ventana de migración
107
+ - Tiempo de downtime <= 0 (expand-contract obligatorio)
108
+ - Tests preexistentes verde antes y después
109
+ - Sin warnings nuevos de ORM (N+1, lazy loading)
110
+ ```
111
+
112
+ Si el agente detecta que una health metric está cayendo, **debe ser más
113
+ conservador, no más agresivo** — esa es la diferencia operacional con un
114
+ outcome.
115
+
116
+ ### Parte 5 — Org Context
117
+
118
+ Sistema (otros agentes, hooks, tooling) + organización (proyecto, usuario,
119
+ dominio). No todo va en el prompt:
120
+
121
+ > "Core context (always needed) goes in the system prompt. Reference
122
+ > context goes in retrieval. Dynamic context (per-request) goes in the
123
+ > orchestration layer." (línea 159, parafraseada)
124
+
125
+ **Dónde vive en SWL**: `CLAUDE.md` del proyecto (org), `contextos/`
126
+ (dev/review/research), `INVENTARIO.md` (system context). El agente no
127
+ necesita declararlo — lo recibe vía carga inicial.
128
+
129
+ ### Parte 6 — Constraints (los dos tipos)
130
+
131
+ Huryn separa muy claramente:
132
+
133
+ **Steering prompts (prompt-level)** — texto que el agente lee y debería
134
+ seguir, pero puede ignorar bajo presión:
135
+ - Behavioral guidance
136
+ - Risk preferences
137
+ - Tone and caution
138
+
139
+ **Hard guardrails (orchestration-level)** — restricciones aplicadas en
140
+ arquitectura, no en lenguaje:
141
+ - Tool restrictions
142
+ - Output validation
143
+ - Action gating
144
+ - Approval gates (HITL)
145
+
146
+ > "If a constraint matters, it must be enforced in architecture, not
147
+ > language. [...] The reasoning layer proposes. The orchestration layer
148
+ > enforces. If a constraint lives only in the prompt, it's a suggestion."
149
+ > (líneas 196, 197 paraf., 198)
150
+
151
+ **Dónde vive en SWL**:
152
+ - `steering: [...]` en frontmatter del agente (texto que el modelo lee)
153
+ - `hardGuardrails: [...]` declara qué hook/regla/schema enforza qué
154
+ restricción. Sintaxis: `@reglas/X.md`, `@hooks/Y.js`, o texto inline
155
+ si es específico al agente.
156
+
157
+ Anti-patrón: declarar como `steering` algo que necesita enforcement real
158
+ ("no eliminar archivos" sin hook que lo prevenga). Si la restricción
159
+ importa, va en `hardGuardrails` con apoyo de hook/permiso/schema.
160
+
161
+ ### Parte 7 — Autonomy Boundaries
162
+
163
+ Huryn define 4 niveles:
164
+
165
+ 1. **Full Autonomy** — acciones reversibles, impacto limitado, modos de
166
+ falla conocidos.
167
+ 2. **Guarded Autonomy** — cambios visibles al usuario, riesgo medio.
168
+ Requiere logging y rollback.
169
+ 3. **Proposal-First** — decisiones estratégicas. El agente propone, el
170
+ humano aprueba, el agente ejecuta.
171
+ 4. **No Autonomy (Human-Required)** — compromisos legales, cambios
172
+ irreversibles, acciones financieras.
173
+
174
+ **Mapeo a SWL** (3 niveles, no 4 — decisión consciente, ver ADR-0025):
175
+
176
+ | Huryn 4-tier | SWL `nivelRiesgo` | HITL? |
177
+ |---|---|---|
178
+ | Full Autonomy | BAJO | No |
179
+ | Guarded Autonomy | MEDIO | Solo en ramas críticas |
180
+ | Proposal-First | ALTO | Sí, antes de mutaciones irreversibles |
181
+ | Human-Required | ALTO + `permisos*: false` | Sí, siempre |
182
+
183
+ El nivel 4 de Huryn se modela en SWL como ALTO + permisos restrictivos en
184
+ frontmatter. NO se introduce un cuarto tier en el enum `nivelRiesgo`.
185
+
186
+ ### Parte 8 — Stop Rules
187
+
188
+ Tres tipos de stop, todos load-bearing:
189
+
190
+ - **Halt** — restricciones en conflicto, confianza cae 2x consecutivas,
191
+ `maxTurnos` alcanzado.
192
+ - **Escalate** — fuera de scope, tema legal/compliance detectado,
193
+ frustración persistente.
194
+ - **Complete** — outcomes alcanzados, usuario confirma.
195
+
196
+ > "Halt and escalate are the load-bearing branches, and /goal ships
197
+ > neither." (línea 271)
198
+
199
+ **Dónde vive en SWL**:
200
+ - `maxTurnos:` en frontmatter — tope de iteraciones.
201
+ - Recovery Catalog en `reglas/seguridad-agentes.md § Recovery Catalog` —
202
+ reprompt → reduce-autonomy → escalate → terminate.
203
+ - `notificador-swl` para escalado a humano vía Telegram/desktop.
204
+
205
+ ## Cómo aplicar el framework a un agente nuevo
206
+
207
+ 1. Cargar este skill antes de escribir el primer carácter del agente.
208
+ 2. Importar `agentes/_intent-spec.md` con `fragmentos: [_intent-spec]`.
209
+ 3. Declarar los 4 campos opcionales del schema:
210
+ - `strategy:` (Parte 1)
211
+ - `healthMetrics:` (Parte 4)
212
+ - `steering:` (Parte 6 — soft)
213
+ - `hardGuardrails:` (Parte 6 — hard)
214
+ 4. Verificar que `description` cubre Parte 2 (Objective).
215
+ 5. Verificar que `nivelRiesgo` mapea a Parte 7 (Autonomy Boundaries).
216
+ 6. Verificar que `maxTurnos` está declarado si hay loop interno (Parte 8).
217
+ 7. Org Context (Parte 5) vive en CLAUDE.md — no se duplica en el agente.
218
+ 8. Desired Outcomes (Parte 3) vive en PLAN.md de cada invocación — no se
219
+ hardcodea en el agente.
220
+
221
+ ## Anti-patrones específicos a evitar
222
+
223
+ - **`steering` que debería ser `hardGuardrails`**: "no eliminar tablas"
224
+ sin hook `proteccion-rutas.js` o equivalente. Si importa, va en
225
+ arquitectura.
226
+ - **Health metrics como outcomes negados**: "no degradar latencia" es
227
+ health metric; "latencia < 200ms p95" es outcome. La diferencia: outcome
228
+ se persigue, health metric se protege mientras se persigue.
229
+ - **Strategy demasiado genérica**: "código limpio y mantenible" no es
230
+ strategy de un agente — es default. Strategy debe nombrar el tradeoff
231
+ específico que ese agente prioriza.
232
+ - **Autonomy Boundaries por ego, no por riesgo**: `nivelRiesgo: ALTO` no
233
+ es prestigio; es declaración de que el agente toca cosas
234
+ irreversibles. Si BAJO o MEDIO basta, no inflar.
235
+ - **Stop Rules ausentes**: agente sin `maxTurnos` ni recovery declarado
236
+ puede entrar en loop infinito. Default seguro: 10-15 turnos.
237
+
238
+ ## Gotchas no obvios
239
+
240
+ - **Health metrics no se enforce por sí solas**: el agente las lee y se
241
+ comporta más conservador, pero NO hay hook que las verifique
242
+ automáticamente. Diseñar telemetría que las capture si el agente es
243
+ crítico.
244
+ - **`steering` y `hardGuardrails` aceptan `@reglas/X.md`**: cuando una
245
+ restricción es global, no copiar el texto — referenciar la regla
246
+ evita drift.
247
+ - **El framework no resuelve ambigüedad de objetivos en conflicto**:
248
+ si dos health metrics chocan entre sí, la prioridad debe declararse
249
+ como tradeoff en `strategy`.
250
+
251
+ ## Referencia rápida — campos por nivelRiesgo
252
+
253
+ | Campo | BAJO | MEDIO | ALTO |
254
+ |---|---|---|---|
255
+ | `description` (Parte 2) | Obligatorio | Obligatorio | Obligatorio |
256
+ | `nivelRiesgo` (Parte 7) | Obligatorio | Obligatorio | Obligatorio |
257
+ | `maxTurnos` (Parte 8) | Recomendado | Recomendado | Obligatorio |
258
+ | `strategy` (Parte 1) | Opcional | Opcional | Obligatorio |
259
+ | `healthMetrics` (Parte 4) | Opcional | Opcional | Obligatorio |
260
+ | `steering` (Parte 6) | Opcional | Recomendado | Recomendado |
261
+ | `hardGuardrails` (Parte 6) | Opcional | Recomendado | Obligatorio |
262
+ | `fragmentos: [_intent-spec]` | Opcional | Opcional | Obligatorio |
263
+
264
+ ## Origen
265
+
266
+ Skill creado el 2026-05-18 como parte de Opción B de integración
267
+ `temp/Lead-agents-like-humans.md` + `temp/DDIA*.md`. Ver ADR-0025 para la
268
+ decisión de scope. Fragment compartido `_intent-spec` es la
269
+ versión system-prompt-embebida; este skill es la versión invocable on-demand.