@saulwade/swl-ses 2.2.4 → 2.3.1
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.
- package/CLAUDE.md +48 -7
- package/README.md +3 -3
- package/agentes/accesibilidad-wcag-swl.md +690 -690
- package/agentes/arquitecto-swl.md +267 -267
- package/agentes/auto-evolucion-swl.md +908 -908
- package/agentes/backend-api-swl.md +472 -472
- package/agentes/backend-csharp-swl.md +420 -420
- package/agentes/backend-go-swl.md +390 -390
- package/agentes/backend-java-swl.md +281 -281
- package/agentes/backend-node-swl.md +479 -479
- package/agentes/backend-python-swl.md +605 -605
- package/agentes/backend-rust-swl.md +364 -364
- package/agentes/backend-workers-swl.md +482 -482
- package/agentes/cloud-infra-swl.md +509 -509
- package/agentes/consolidador-swl.md +541 -541
- package/agentes/datos-swl.md +605 -605
- package/agentes/depurador-swl.md +352 -352
- package/agentes/devops-ci-swl.md +400 -400
- package/agentes/disenador-ui-swl.md +569 -569
- package/agentes/documentador-swl.md +345 -345
- package/agentes/frontend-angular-swl.md +621 -621
- package/agentes/frontend-css-swl.md +716 -716
- package/agentes/frontend-react-swl.md +692 -692
- package/agentes/frontend-swl.md +496 -496
- package/agentes/frontend-tailwind-swl.md +826 -826
- package/agentes/gh-fix-ci-swl.md +2 -2
- package/agentes/implementador-swl.md +328 -328
- package/agentes/investigador-swl.md +432 -432
- package/agentes/investigador-ux-swl.md +505 -505
- package/agentes/llm-apps-swl.md +278 -278
- package/agentes/migrador-swl.md +442 -442
- package/agentes/mobile-android-swl.md +511 -511
- package/agentes/mobile-cross-swl.md +541 -541
- package/agentes/mobile-ios-swl.md +502 -502
- package/agentes/mobile-testing-swl.md +302 -302
- package/agentes/nemesis-auditor-swl.md +285 -285
- package/agentes/notificador-swl.md +918 -918
- package/agentes/observabilidad-swl.md +438 -438
- package/agentes/orquestador-swl.md +1026 -1026
- package/agentes/pagos-swl.md +310 -310
- package/agentes/perfilador-usuario-swl.md +321 -321
- package/agentes/planificador-swl.md +399 -399
- package/agentes/producto-prd-swl.md +589 -589
- package/agentes/red-team-swl.md +1 -1
- package/agentes/release-manager-swl.md +590 -590
- package/agentes/rendimiento-swl.md +713 -713
- package/agentes/resolutor-build-swl.md +245 -245
- package/agentes/revisor-angular-swl.md +278 -278
- package/agentes/revisor-codigo-swl.md +505 -505
- package/agentes/revisor-csharp-swl.md +264 -264
- package/agentes/revisor-go-swl.md +259 -259
- package/agentes/revisor-java-swl.md +257 -257
- package/agentes/revisor-kotlin-swl.md +273 -273
- package/agentes/revisor-nextjs-swl.md +281 -281
- package/agentes/revisor-php-swl.md +271 -271
- package/agentes/revisor-react-swl.md +278 -278
- package/agentes/revisor-rust-swl.md +346 -346
- package/agentes/revisor-seguridad-swl.md +399 -399
- package/agentes/revisor-swift-swl.md +268 -268
- package/agentes/revisor-typescript-swl.md +346 -346
- package/agentes/sre-swl.md +291 -291
- package/agentes/tdd-qa-swl.md +393 -393
- package/comandos/swl/aprobar-plan.md +146 -141
- package/comandos/swl/briefing.md +119 -119
- package/comandos/swl/contribuir.md +233 -233
- package/comandos/swl/predecir.md +139 -139
- package/comandos/swl/release.md +30 -8
- package/comandos/swl/sesiones.md +1 -1
- package/comandos/swl/status.md +343 -333
- package/gateway/agent-executor.js +1 -1
- package/gateway/lib/event-channel.js +191 -191
- package/habilidades/agent-deep-links/SKILL.md +148 -148
- package/habilidades/agentes-como-servicio/SKILL.md +2 -2
- package/habilidades/angular-moderno/SKILL.md +20 -1
- package/habilidades/auto-evolucion-protocolo/SKILL.md +276 -276
- package/habilidades/backend-async-postgres-testing/SKILL.md +215 -215
- package/habilidades/backend-error-design/SKILL.md +221 -221
- package/habilidades/backend-production-resilience/SKILL.md +288 -288
- package/habilidades/benchmark-memoria/SKILL.md +186 -186
- package/habilidades/calidad-anti-patrones-universales/SKILL.md +368 -368
- package/habilidades/calidad-contract-testing/SKILL.md +165 -165
- package/habilidades/calidad-mutation-testing/SKILL.md +170 -170
- package/habilidades/changelog-generator/scripts/parse-commits.js +367 -367
- package/habilidades/checklist-seguridad/recursos/stride-cobertura.md +60 -60
- package/habilidades/contenedores-docker/SKILL.md +3 -1
- package/habilidades/diagrama-arquitectura/assets/template.html +276 -276
- package/habilidades/doubt-driven-review/recursos/EXAMPLES.md +130 -130
- package/habilidades/drift-detection/SKILL.md +179 -179
- package/habilidades/ejecutar-fase/SKILL.md +564 -541
- package/habilidades/ejecutar-task-iterativo/SKILL.md +278 -278
- package/habilidades/estructura-proyecto-claude/recursos/frontmatter-y-hooks-referencia.md +1 -1
- package/habilidades/estructura-proyecto-claude/recursos/mcp-json-template.json +57 -57
- package/habilidades/eval-framework/SKILL.md +212 -212
- package/habilidades/extractor-de-aprendizajes/SKILL.md +3 -3
- package/habilidades/feynman-auditor-swl/recursos/preguntas-language-agnostic.md +108 -108
- package/habilidades/harness-claude-code/recursos/disciplina-harness-regla.md +252 -252
- package/habilidades/legacy-code-rescue/SKILL.md +267 -267
- package/habilidades/meta-skills-estandar/recursos/convencion-examples.md +93 -93
- package/habilidades/patrones-python/recursos/patrones-avanzados.md +469 -469
- package/habilidades/perfil-usuario/SKILL.md +200 -200
- package/habilidades/planear-fase/SKILL.md +15 -1
- package/habilidades/prevencion-sobreingenieria/recursos/EXAMPLES.md +580 -580
- package/habilidades/proceso-ddia-fundamentos/SKILL.md +255 -255
- package/habilidades/proceso-ddia-streaming/SKILL.md +231 -231
- package/habilidades/proceso-debate-adversarial/SKILL.md +191 -164
- package/habilidades/proceso-debate-adversarial/recursos/personas.md +105 -105
- package/habilidades/proceso-discovery-machote/SKILL.md +157 -157
- package/habilidades/proceso-dynamic-workflows/SKILL.md +138 -138
- package/habilidades/proceso-dynamic-workflows/recursos/template-adversarial-verify.js +65 -65
- package/habilidades/proceso-dynamic-workflows/recursos/template-triage.js +65 -65
- package/habilidades/proceso-intent-engineering/SKILL.md +269 -269
- package/habilidades/proceso-modular-split/SKILL.md +256 -256
- package/habilidades/prompt-engineering/recursos/patrones-avanzados.md +2 -2
- package/habilidades/state-inconsistency-auditor-swl/recursos/coupled-state-patterns.md +147 -147
- package/habilidades/structured-outputs/SKILL.md +2 -2
- package/habilidades/swl-claudemd/recursos/contrato-aprender.md +83 -83
- package/habilidades/swl-claudemd/recursos/duplicacion-reglas-globales.md +85 -85
- package/habilidades/swl-claudemd/recursos/plantillas-init.md +94 -94
- package/habilidades/swl-dashboard/SKILL.md +2 -2
- package/habilidades/tdd-workflow/SKILL.md +33 -1
- package/habilidades/tdd-workflow/recursos/gherkin-bdd.md +111 -111
- package/habilidades/validacion-ci-sistema/recursos/validadores-completos.md +1 -1
- package/habilidades/validacion-ci-sistema/scripts/validar-sistema.sh +1 -1
- package/hooks/captura-acciones-post.js +151 -0
- package/hooks/captura-acciones-session.js +155 -0
- package/hooks/ciclo-evolucion-subagente.js +26 -26
- package/hooks/ciclo-evolucion.js +26 -26
- package/hooks/claudemd-bloat-detector.js +161 -161
- package/hooks/claudemd-duplicacion-detector.js +170 -170
- package/hooks/contexto-iteracion.js +144 -144
- package/hooks/guardrail-modelo.js +1 -1
- package/hooks/lib/agent-routing.js +107 -107
- package/hooks/lib/auto-consolidator.js +335 -335
- package/hooks/lib/autonomia.js +208 -208
- package/hooks/lib/briefing.js +512 -474
- package/hooks/lib/captura-acciones.js +392 -0
- package/hooks/lib/ciclo-evolucion.js +47 -47
- package/hooks/lib/deep-links.js +185 -185
- package/hooks/lib/error-classifier.js +308 -308
- package/hooks/lib/etapa-auto-evolucion.js +701 -701
- package/hooks/lib/etapa-metricas.js +388 -388
- package/hooks/lib/etapa-perfil-usuario.js +376 -376
- package/hooks/lib/loop-telemetry.js +321 -321
- package/hooks/lib/merkle-audit.js +96 -96
- package/hooks/lib/model-router.js +2 -2
- package/hooks/lib/propose-step.js +358 -358
- package/hooks/lib/provenance-tracker.js +191 -191
- package/hooks/lib/rate-limit-tracker.js +253 -253
- package/hooks/lib/resource-quota.js +122 -122
- package/hooks/lib/retry-jitter.js +165 -165
- package/hooks/lib/security-net.js +201 -201
- package/hooks/lib/skill-auditor.js +588 -588
- package/hooks/lib/sync-status.js +228 -228
- package/hooks/lib/taint-tracker.js +107 -107
- package/hooks/lib/text-similarity.js +241 -241
- package/hooks/lib/token-estimator.js +1 -0
- package/hooks/lib/toon-compressor.js +245 -245
- package/hooks/lib/usage-model.js +1 -1
- package/hooks/linea-estado.js +2 -0
- package/hooks/registro-turnos.js +209 -209
- package/hooks/session-briefing.js +98 -98
- package/hooks/spec-gate.js +211 -211
- package/hooks/sugerir-regenerar-inventario.js +170 -170
- package/hooks/tdd-gate.js +241 -241
- package/hooks/telemetria-skill-routing.js +100 -100
- package/hooks/validar-formato-post-subagente.js +140 -140
- package/hooks/validar-intent-spec.js +242 -242
- package/hooks/validar-memoria-hook.js +218 -218
- package/hooks/validar-planning-paths.js +134 -134
- package/instintos/autonomia.yaml +27 -27
- package/instintos/prompt-appendices.yaml +57 -57
- package/llms.txt +2 -2
- package/manifiestos/agent-output-schemas.json +57 -57
- package/manifiestos/canonical-hashes.json +2291 -1637
- package/manifiestos/hooks-config.json +18 -0
- package/manifiestos/modulos.json +4 -0
- package/manifiestos/planning-paths.json +44 -44
- package/manifiestos/skills-lock.json +1282 -1282
- package/package.json +2 -2
- package/plantillas/auditor-veto-template.md +105 -105
- package/plantillas/github-workflows/README.md +47 -47
- package/plantillas/github-workflows/release-please.yml +44 -44
- package/plantillas/github-workflows/swl-ci.yml +107 -107
- package/plantillas/github-workflows/swl-security.yml +51 -51
- package/plugin.json +2 -2
- package/reglas/accesibilidad.md +10 -10
- package/reglas/analisis-previo-tareas-grandes.md +172 -172
- package/reglas/api-diseno.md +9 -9
- package/reglas/arreglar-al-detectar.md +240 -240
- package/reglas/auditorias-documentales-estructurales.md +7 -7
- package/reglas/cloud-infra.md +8 -8
- package/reglas/consultar-vault-primero.md +195 -195
- package/reglas/debatir-antes-de-aceptar.md +158 -158
- package/reglas/fragmentos-compartidos.md +183 -183
- package/reglas/hooks.md +6 -6
- package/reglas/intent-engineering.md +218 -218
- package/reglas/markitdown.md +8 -8
- package/reglas/memoria-consolidada.md +41 -0
- package/reglas/monitor-ci.md +309 -309
- package/reglas/patrones.md +6 -6
- package/reglas/seguridad-agentes.md +66 -0
- package/reglas/sesiones-paralelas.md +180 -180
- package/reglas/sin-duplicacion-reglas-globales.md +182 -182
- package/reglas/skills-estandar.md +6 -6
- package/reglas/testing.md +7 -7
- package/reglas/tests-cleanup.md +224 -224
- package/reglas/usar-code-review-graph.md +155 -155
- package/reglas/usar-context7.md +226 -226
- package/reglas/verificar-citas-normativas.md +548 -548
- package/schemas/agent-frontmatter.schema.json +3 -3
- package/schemas/agent-message.schema.json +73 -73
- package/schemas/agent-output-implementacion.schema.json +114 -114
- package/schemas/agent-output-planificacion.schema.json +150 -150
- package/schemas/agent-output-review.schema.json +98 -98
- package/schemas/diary-entry.schema.json +112 -112
- package/schemas/hook-profiles.schema.json +54 -54
- package/schemas/hooks-config.schema.json +89 -89
- package/schemas/instinct.schema.json +161 -152
- package/schemas/modulos.schema.json +38 -38
- package/schemas/perfiles.schema.json +36 -36
- package/schemas/plugin.schema.json +77 -77
- package/schemas/skill-evals.schema.json +119 -119
- package/schemas/skill-frontmatter.schema.json +245 -245
- package/scripts/audit-tools/audit-history.js +330 -330
- package/scripts/audit-tools/bundle-tracker.js +290 -290
- package/scripts/audit-tools/canary-monitor.js +352 -352
- package/scripts/audit-tools/code-profiler.js +605 -605
- package/scripts/audit-tools/dep-doctor.js +320 -320
- package/scripts/audit-tools/env-validator.js +206 -206
- package/scripts/audit-tools/lib/fs-walk.js +48 -48
- package/scripts/audit-tools/lib/output.js +23 -23
- package/scripts/audit-tools/migration-checker.js +392 -392
- package/scripts/audit-tools/pentest-scanner.js +1436 -1436
- package/scripts/benchmark-memoria.js +167 -167
- package/scripts/bootstrap-instintos.js +25 -7
- package/scripts/cli/aprobar-plan.js +73 -73
- package/scripts/cli/briefing.js +23 -23
- package/scripts/cli/ciclo-evolucion.js +26 -26
- package/scripts/cli/configurar-ci.js +40 -40
- package/scripts/cli/derivar-feature-list.js +25 -25
- package/scripts/cli/detectar-host.js +27 -27
- package/scripts/cli/diary-entry.js +69 -69
- package/scripts/cli/execution-state.js +18 -18
- package/scripts/cli/gateway-notify.js +41 -41
- package/scripts/cli/liberar-fase.js +42 -42
- package/scripts/cli/loop-telemetry.js +125 -125
- package/scripts/cli/mark-evolved.js +56 -56
- package/scripts/cli/metricas-dora.js +26 -26
- package/scripts/cli/near-duplicate.js +55 -55
- package/scripts/cli/notificaciones.js +123 -123
- package/scripts/cli/propose-step.js +29 -29
- package/scripts/cli/schedule-parse.js +19 -19
- package/scripts/cli/sugerir-modelo.js +20 -20
- package/scripts/cli/verificar-plan.js +36 -36
- package/scripts/cli/verificar-trazabilidad.js +35 -35
- package/scripts/configurar-branch-protection.js +418 -418
- package/scripts/detectar-aprendizajes-duplicados.js +151 -151
- package/scripts/field-report.js +199 -199
- package/scripts/generar-checklists-consolidados.js +273 -273
- package/scripts/generar-matriz-lenguajes.js +271 -271
- package/scripts/lib/artefactos-python.js +43 -43
- package/scripts/lib/auditar-invocaciones-comandos.js +104 -104
- package/scripts/lib/benchmark-metrics.js +160 -160
- package/scripts/lib/budget-enforcer.js +252 -252
- package/scripts/lib/ci-reader.js +193 -193
- package/scripts/lib/claude-sessions.js +1 -0
- package/scripts/lib/configurar-ci.js +380 -380
- package/scripts/lib/contadores-inventario.js +217 -217
- package/scripts/lib/detectar-host-swl.js +175 -175
- package/scripts/lib/detectar-stack-detallado.js +307 -307
- package/scripts/lib/detector-autoduplicacion-intra-archivo.js +234 -234
- package/scripts/lib/detector-reglas-duplicadas.js +220 -220
- package/scripts/lib/diary-entry.js +234 -234
- package/scripts/lib/eval-metrics-store.js +218 -218
- package/scripts/lib/eval-quality.js +171 -171
- package/scripts/lib/eval-schemas.js +144 -144
- package/scripts/lib/eval-self-correct.js +106 -106
- package/scripts/lib/eval-validator.js +185 -185
- package/scripts/lib/evidencia-release.js +322 -322
- package/scripts/lib/expandir-targets.js +71 -71
- package/scripts/lib/gate-hooks-requires.js +249 -249
- package/scripts/lib/gate-licencias.js +212 -212
- package/scripts/lib/git-metricas.js +257 -257
- package/scripts/lib/gitignore-manifest.js +44 -11
- package/scripts/lib/jaccard-similarity.js +98 -98
- package/scripts/lib/longmemeval-runner.js +125 -125
- package/scripts/lib/metricas-dora.js +204 -204
- package/scripts/lib/npm-version.js +261 -261
- package/scripts/lib/paquetes-conocidos.js +50 -50
- package/scripts/lib/plan-lock.js +275 -275
- package/scripts/lib/pr-analyzer.js +399 -399
- package/scripts/lib/prompt-builder.js +264 -264
- package/scripts/lib/reglas-globales-conocidas.json +180 -180
- package/scripts/lib/resolver-plan-fase.js +37 -37
- package/scripts/lib/rrf-fusion.js +175 -175
- package/scripts/lib/schema-version.js +164 -164
- package/scripts/lib/scoring-instintos.js +277 -277
- package/scripts/lib/semantic-search.js +252 -252
- package/scripts/lib/skill-metrics.js +41 -1
- package/scripts/lib/toml-merge.js +204 -204
- package/scripts/lib/tool-cost-analyzer.js +1 -0
- package/scripts/limpiar-artefactos-python.js +131 -131
- package/scripts/mcp-server/auth.js +105 -105
- package/scripts/mcp-server/cache.js +106 -106
- package/scripts/migrar-csv-a-array.js +168 -168
- package/scripts/migrar-fase-dominio.js +200 -200
- package/scripts/publicar.js +497 -497
- package/scripts/run-eval.js +141 -141
- package/scripts/tui/componentes/selector-multi.js +189 -189
- package/scripts/tui/componentes/selector-unico.js +158 -158
- package/scripts/tui/ejecutores.js +375 -375
- package/scripts/tui/index.js +162 -162
- package/scripts/tui/lib/colores.js +129 -129
- package/scripts/tui/lib/render.js +264 -264
- package/scripts/tui/lib/teclas.js +113 -113
- package/scripts/tui/pantallas/inspect.js +173 -173
- package/scripts/tui/pantallas/install-wizard.js +334 -334
- package/scripts/tui/pantallas/menu-principal.js +52 -52
- package/scripts/tui/pantallas/progreso.js +274 -274
- package/scripts/tui/pantallas/resumen.js +132 -132
- package/scripts/tui/pantallas/uninstall-wizard.js +208 -208
- package/scripts/tui/pantallas/update-wizard.js +232 -232
- package/scripts/tui/pantallas/welcome.js +187 -187
- package/scripts/validar-userland-vacio.js +110 -110
- package/scripts/verificar-trazabilidad.js +329 -298
|
@@ -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.
|