@ingeniomaps/cauce 0.2.0 → 0.3.0

package/teams/README.md

@@ -0,0 +1,60 @@
+# Equipos
+
+Un equipo compone varios cargos de `agents/` en un recorrido con etapas, dueños de decisión y gates de
+salida. Es lo que convierte una intención en una épica candidata —o en la razón por la que todavía no
+lo es— sin que un solo agente decida por todos.
+
+## Los que trae Cauce
+
+| Equipo | Descubrimiento | Deja | Para qué |
+|---|---|---|---|
+| `system/feasibility-review` | 3 etapas | épica | ¿vale el esfuerzo? Con la evidencia que ya existe. |
+| `system/product-development` | 5 etapas | épica | ¿qué construimos y cómo? Produce evidencia nueva. |
+| `system/incident-review` | 4 etapas | informe | ¿qué pasó y qué aprendemos? Después de contener. |
+
+Son tres **formas**, no tres dominios. Un equipo de seguridad o uno de crecimiento tienen la misma forma
+con otros cargos: eso lo escribe cada empresa, porque cómo decide es suyo.
+
+## Escribir uno propio
+
+Copiar la estructura de [000-template.md](000-template.md) a `teams/<slug>/`, con su `team.json` y su
+`WORKFLOW.md`, y validar:
+
+```bash
+node tools/ops.js team list
+node tools/ops.js team check <slug>
+node tools/ops.js team show <slug>
+```
+
+Un equipo propio con el mismo slug que uno de `system/` lo reemplaza; con otro slug, convive. **Nunca
+editar dentro de `system/`**: se reemplaza completo en cada actualización.
+
+## Invocar un equipo
+
+Tres formas, de la más simple a la más explícita:
+
+```text
+/team quiero cobrar con tarjeta guardada
+/team incident-review: se cayó el checkout el martes a las 14:00
+/team {"team": "acme-soporte", "intent": "qué se quiere evaluar"}
+```
+
+Sin prefijo corre `product-development`. El prefijo se confirma contra los equipos que existen: si no
+es uno, el texto completo se toma como intención, así que escribir `nota: revisar esto` no dispara un
+equipo llamado `nota`. Con el equipo pasado explícitamente, un slug inexistente falla en vez de caer al
+por defecto en silencio.
+
+## Corto o largo
+
+Un recorrido largo cuesta más y aporta más certeza. La elección es la misma que con los lanes de una
+tarea: usar el corto cuando la evidencia ya existe y la pregunta es de esfuerzo, y el largo cuando hay
+que averiguar algo antes de comprometerse.
+
+Un recorrido corto que termina en "hay que investigar" no falló: acotó el problema por el costo de tres
+etapas en lugar de cinco.
+
+## Lo que un equipo nunca hace
+
+Ningún recorrido promueve trabajo al BACKLOG. Escribe la épica candidata en `planning/roadmap/` y para;
+la promoción es la firma humana que autoriza ejecución. Un gate que no se cumple se convierte en una
+acción concreta en `planning/HUMAN_ACTIONS.md`, no en un gate más blando.

package/teams/system/feasibility-review/WORKFLOW.md

@@ -0,0 +1,60 @@
+# Feasibility Review
+
+## Cómo activarlo
+
+Usar este equipo cuando hay una intención concreta y la pregunta es **si vale el esfuerzo**, no cómo
+resolverla. Tres etapas y tres dueños de decisión: encuadre, factibilidad y recomendación.
+
+```text
+Usa el team feasibility-review para evaluar esta intención:
+<qué se quiere lograr, para quién, y qué evidencia ya tenemos>
+```
+
+Si la respuesta requiere hablar con usuarios, medir algo que hoy no se mide o explorar el diseño, este
+equipo no es el indicado: lo correcto es que recomiende investigar y que después corra
+`product-development`, que sí tiene research y shape.
+
+## Cuándo usar este y cuándo el largo
+
+| | `feasibility-review` | `product-development` |
+|---|---|---|
+| Etapas de descubrimiento | 3 | 5 |
+| Pregunta que responde | ¿vale el esfuerzo? | ¿qué construimos y cómo? |
+| Evidencia | usa la que ya existe | produce evidencia nueva |
+| Salida típica | hacer, no hacer o investigar | épica con criterios y diseño |
+
+Un recorrido corto que termina en "hay que investigar" no falló: acotó el problema por el costo de tres
+etapas en lugar de cinco.
+
+## Protocolo de handoff
+
+Cada handoff incluye:
+
+```markdown
+Etapa y agente:
+Pregunta que resuelve:
+Evidencia usada y su origen:
+Supuestos e incertidumbre:
+Lo que falta averiguar:
+Exit gate: cumplido / no cumplido
+Autorizaciones pendientes:
+```
+
+No avanzar si el exit gate no se cumple. La etapa siguiente puede devolver el handoff cuando falte
+evidencia, autoridad o un criterio verificable.
+
+## Selección de agentes condicionales
+
+`user-researcher` entra cuando el encuadre depende de una necesidad que nadie verificó.
+`security-engineer` y `privacy-compliance-specialist`, cuando la opción toca autenticación, permisos o
+datos personales. `finops-engineer`, cuando el costo de operar es parte de la decisión —típico si suma
+inferencia de modelos—. `legal-counsel`, cuando hay compromiso contractual o afirmación pública.
+
+Se incorporan por riesgo, no por rutina: sumar un cargo que no aporta diluye la revisión.
+
+## Límites
+
+El recorrido produce una recomendación, no una aprobación. Escribe la épica candidata en `roadmap/`
+cuando la respuesta es hacer, y **nunca promueve al BACKLOG**: esa firma es humana. Cuando la respuesta
+es investigar, la acción concreta queda en `planning/HUMAN_ACTIONS.md`; cuando es no hacer, el motivo y
+qué lo cambiaría quedan en la sección Lecciones de `planning/INBOX.md`.

package/teams/system/feasibility-review/team.json

@@ -0,0 +1,73 @@
+{
+  "schemaVersion": 1,
+  "slug": "feasibility-review",
+  "name": "Feasibility Review",
+  "purpose": "Decidir si una intención vale el esfuerzo, con la evidencia que ya existe, antes de abrir un descubrimiento completo.",
+  "outcome": "epic",
+  "entryAgent": "product-manager",
+  "facilitator": "project-manager",
+  "decisionOwners": {
+    "value_and_priority": "product-manager",
+    "technical_design": "software-architect",
+    "capacity_and_assignment": "engineering-manager"
+  },
+  "conditionalAgents": [
+    "user-researcher",
+    "security-engineer",
+    "privacy-compliance-specialist",
+    "finops-engineer",
+    "legal-counsel"
+  ],
+  "stages": [
+    {
+      "id": "frame",
+      "phase": "discovery",
+      "agent": "product-manager",
+      "dependsOn": [],
+      "produces": [
+        "problem-and-outcome",
+        "evidence-already-available"
+      ],
+      "exitGate": "Problema, usuario, outcome y qué evidencia ya existe están explícitos; lo que falta averiguar queda listado, no supuesto."
+    },
+    {
+      "id": "assess",
+      "phase": "discovery",
+      "agent": "software-architect",
+      "dependsOn": [
+        "frame"
+      ],
+      "produces": [
+        "feasibility-and-options",
+        "risks-and-unknowns"
+      ],
+      "exitGate": "Hay al menos una opción viable con su costo grueso y sus riesgos, o la razón técnica concreta por la que no la hay."
+    },
+    {
+      "id": "decide",
+      "phase": "discovery",
+      "agent": "engineering-manager",
+      "dependsOn": [
+        "assess"
+      ],
+      "produces": [
+        "recommendation",
+        "what-would-change-the-answer"
+      ],
+      "exitGate": "La recomendación es hacer, no hacer o investigar, con el esfuerzo estimado y qué evidencia cambiaría la respuesta."
+    }
+  ],
+  "guardrails": [
+    "Cada agente conserva los límites y autorizaciones de su SKILL.md.",
+    "Este recorrido usa la evidencia que ya existe; no la produce ni la reemplaza por supuestos.",
+    "Recomendar investigar es un resultado legítimo, no una falla del recorrido.",
+    "Los agentes condicionales se incorporan por riesgo, plataforma y alcance, no por rutina.",
+    "Ningún handoff convierte una recomendación en aprobación ni en ejecución."
+  ],
+  "completion": [
+    "La recomendación distingue lo que se sabe de lo que se supone.",
+    "El esfuerzo estimado tiene rango y supuestos visibles, no un número solo.",
+    "Queda escrito qué evidencia cambiaría la decisión.",
+    "Si el resultado es investigar, la acción concreta queda registrada para una persona."
+  ]
+}

package/teams/system/incident-review/WORKFLOW.md

@@ -0,0 +1,65 @@
+# Incident Review
+
+## Qué es y qué no es
+
+Este equipo hace la **revisión posterior** de un incidente ya contenido. No responde incidentes en vivo:
+un recorrido de agentes no es un incident commander, no tiene acceso a producción, no está de guardia y
+no puede decidir bajo presión con información parcial. Confundir una cosa con la otra sería peligroso.
+
+Mientras el incidente está activo, mandan las personas de guardia. Este recorrido empieza después,
+cuando el servicio ya está estable y lo que hace falta es entender qué pasó.
+
+```text
+Usa el team incident-review para analizar este incidente:
+<qué falló, cuándo, cómo se detectó y qué evidencia hay: logs, alertas, métricas, tickets>
+```
+
+## Salida
+
+Produce un **informe**, no una épica: `planning/reports/<fecha>-<slug>.md`. Los seguimientos quedan en la
+sección Lecciones de `planning/INBOX.md` **sin promover**, y las acciones que requieren una persona
+—comunicar a clientes, notificar a un regulador, cambiar un contrato— en `planning/HUMAN_ACTIONS.md`.
+
+Convertir un seguimiento en trabajo sigue siendo una decisión humana, igual que en cualquier otro
+recorrido.
+
+## Etapas
+
+```
+scope     → sre                    línea de tiempo e impacto real
+diagnose  → software-architect     factores que contribuyeron, y por qué no se detectó antes
+exposure  → security-engineer      si hubo acceso, pérdida o exposición de datos
+learn     → engineering-manager    seguimientos con dueño propuesto
+```
+
+`diagnose` y `exposure` dependen ambas de `scope` y responden preguntas distintas: una busca por qué
+falló, la otra qué quedó expuesto. Separarlas evita que la urgencia técnica tape la evaluación de datos.
+
+## Protocolo de handoff
+
+```markdown
+Etapa y agente:
+Pregunta que resuelve:
+Evidencia usada y su origen (log, alerta, métrica, ticket):
+Hechos / hipótesis / lo indeterminado:
+Exit gate: cumplido / no cumplido
+Autorizaciones u obligaciones pendientes:
+```
+
+Una causa sin evidencia se declara **hipótesis**, aunque cerrar el informe con una causa firme sea más
+cómodo. Un informe que inventa una causa para poder cerrarse hace daño: se toman decisiones sobre él.
+
+## Selección de agentes condicionales
+
+`database-administrator` y `devops-engineer` cuando el factor está en datos o en infraestructura.
+`privacy-compliance-specialist` y `legal-counsel` en cuanto la etapa `exposure` no puede descartar
+acceso a datos personales — ahí puede haber plazos regulatorios, y esa es una acción humana urgente.
+`qa-engineer` cuando la pregunta es por qué las pruebas no lo detectaron. `finops-engineer` cuando el
+incidente fue de costo, no de disponibilidad.
+
+## Límites
+
+Nadie en este recorrido opera producción, aplica una remediación, comunica a un cliente ni notifica a
+un regulador. Todo eso se propone y lo decide una persona. Tampoco se atribuye responsabilidad a
+personas: se analizan las condiciones que hicieron posible el fallo, porque un informe que busca
+culpables consigue que la próxima vez nadie reporte nada.

package/teams/system/incident-review/team.json

@@ -0,0 +1,72 @@
+{
+  "schemaVersion": 1,
+  "slug": "incident-review",
+  "name": "Incident Review",
+  "purpose": "Entender un incidente ya contenido y convertirlo en aprendizaje verificable, sin buscar culpables ni cerrar con una causa cómoda.",
+  "outcome": "report",
+  "entryAgent": "site-reliability-engineer",
+  "facilitator": "engineering-manager",
+  "decisionOwners": {
+    "impact_and_scope": "site-reliability-engineer",
+    "technical_cause": "software-architect",
+    "customer_communication": "customer-support-specialist",
+    "security_assessment": "security-engineer"
+  },
+  "conditionalAgents": [
+    "database-administrator",
+    "devops-engineer",
+    "privacy-compliance-specialist",
+    "legal-counsel",
+    "qa-engineer",
+    "finops-engineer"
+  ],
+  "stages": [
+    {
+      "id": "scope",
+      "phase": "discovery",
+      "agent": "site-reliability-engineer",
+      "dependsOn": [],
+      "produces": ["timeline", "impact-and-blast-radius"],
+      "exitGate": "Qué falló, desde cuándo hasta cuándo, a quiénes afectó y cómo se detectó están establecidos con evidencia, no con recuerdos."
+    },
+    {
+      "id": "diagnose",
+      "phase": "discovery",
+      "agent": "software-architect",
+      "dependsOn": ["scope"],
+      "produces": ["contributing-factors", "why-it-was-not-caught"],
+      "exitGate": "Los factores que contribuyeron están sostenidos por evidencia y se distingue causa de síntoma; si la causa no se determinó, se dice y se explica qué haría falta."
+    },
+    {
+      "id": "exposure",
+      "phase": "discovery",
+      "agent": "security-engineer",
+      "dependsOn": ["scope"],
+      "produces": ["data-and-security-exposure"],
+      "exitGate": "Está determinado si hubo acceso, pérdida o exposición de datos, o queda explícito que no se pudo determinar y qué evidencia falta."
+    },
+    {
+      "id": "learn",
+      "phase": "discovery",
+      "agent": "engineering-manager",
+      "dependsOn": ["diagnose", "exposure"],
+      "produces": ["follow-ups", "detection-and-prevention-gaps"],
+      "exitGate": "Cada seguimiento es una acción concreta con dueño propuesto, y se distingue lo que evita la repetición de lo que sólo la detecta antes."
+    }
+  ],
+  "guardrails": [
+    "Cada agente conserva los límites y autorizaciones de su SKILL.md.",
+    "El incidente ya está contenido: este recorrido no opera producción ni ejecuta remediaciones.",
+    "No se atribuye responsabilidad a personas; se analizan condiciones, no culpables.",
+    "Una causa sin evidencia se declara como hipótesis, aunque cerrar el informe sea más cómodo.",
+    "Ninguna comunicación a clientes ni notificación regulatoria sale de este recorrido: se propone y la decide una persona.",
+    "Los seguimientos quedan en el INBOX sin promover; convertirlos en trabajo es una decisión humana."
+  ],
+  "completion": [
+    "La línea de tiempo está sostenida por registros, no por reconstrucción de memoria.",
+    "Se distingue lo que se sabe de lo que se supone, y las hipótesis están marcadas como tales.",
+    "La exposición de datos está determinada o declarada como indeterminada con su motivo.",
+    "Cada seguimiento indica si previene la repetición o sólo acelera la detección.",
+    "Las obligaciones de comunicación o notificación quedan registradas como acción humana."
+  ]
+}

package/teams/system/product-development/team.json

@@ -3,6 +3,7 @@
   "slug": "product-development",
   "name": "Product Development Team",
   "purpose": "Convertir un problema validado de usuario en una entrega segura, usable, operable y medible.",
+  "outcome": "epic",
   "entryAgent": "product-manager",
   "facilitator": "project-manager",
   "decisionOwners": {
@@ -28,65 +29,118 @@
   "stages": [
     {
       "id": "frame",
+      "phase": "discovery",
       "agent": "product-manager",
       "dependsOn": [],
-      "produces": ["opportunity-brief", "outcome-and-guardrails"],
+      "produces": [
+        "opportunity-brief",
+        "outcome-and-guardrails"
+      ],
       "exitGate": "Problema, usuario, outcome, baseline, límites y decisión requerida están explícitos."
     },
     {
       "id": "research",
+      "phase": "discovery",
       "agent": "user-researcher",
-      "dependsOn": ["frame"],
-      "produces": ["research-evidence", "needs-and-risks"],
+      "dependsOn": [
+        "frame"
+      ],
+      "produces": [
+        "research-evidence",
+        "needs-and-risks"
+      ],
       "exitGate": "La evidencia diferencia hallazgos, hipótesis y preguntas abiertas sin inventar consenso."
     },
     {
       "id": "shape",
+      "phase": "discovery",
       "agent": "ux-designer",
-      "dependsOn": ["research"],
-      "produces": ["journey-and-flows", "usability-risks"],
+      "dependsOn": [
+        "research"
+      ],
+      "produces": [
+        "journey-and-flows",
+        "usability-risks"
+      ],
       "exitGate": "El flujo cubre estados críticos, errores, accesibilidad, control y recuperación del usuario."
     },
     {
       "id": "architect",
+      "phase": "discovery",
       "agent": "software-architect",
-      "dependsOn": ["frame", "shape"],
-      "produces": ["architecture-decision", "interfaces-and-quality-attributes"],
+      "dependsOn": [
+        "frame",
+        "shape"
+      ],
+      "produces": [
+        "architecture-decision",
+        "interfaces-and-quality-attributes"
+      ],
       "exitGate": "Opciones y tradeoffs están documentados; interfaces, riesgos y reversibilidad son verificables."
     },
     {
       "id": "plan",
+      "phase": "discovery",
       "agent": "engineering-manager",
-      "dependsOn": ["architect"],
-      "produces": ["delivery-plan", "ownership-and-capacity"],
+      "dependsOn": [
+        "architect"
+      ],
+      "produces": [
+        "delivery-plan",
+        "ownership-and-capacity"
+      ],
       "exitGate": "Los equipos dueños validaron estimaciones, capacidad, dependencias y criterios de integración."
     },
     {
       "id": "build",
+      "phase": "delivery",
       "agent": "backend-engineer",
-      "dependsOn": ["plan"],
-      "produces": ["working-increment", "implementation-evidence"],
+      "dependsOn": [
+        "plan"
+      ],
+      "produces": [
+        "working-increment",
+        "implementation-evidence"
+      ],
       "exitGate": "El incremento mínimo funciona en entorno autorizado y conserva contratos, controles y pruebas."
     },
     {
       "id": "verify",
+      "phase": "delivery",
       "agent": "qa-engineer",
-      "dependsOn": ["build"],
-      "produces": ["quality-evidence", "residual-risk"],
+      "dependsOn": [
+        "build"
+      ],
+      "produces": [
+        "quality-evidence",
+        "residual-risk"
+      ],
       "exitGate": "Criterios, regresiones, riesgos y evidencia adversa están visibles; no quedan bloqueos ocultos."
     },
     {
       "id": "release",
+      "phase": "delivery",
       "agent": "release-manager",
-      "dependsOn": ["verify"],
-      "produces": ["release-readiness", "rollout-and-rollback"],
+      "dependsOn": [
+        "verify"
+      ],
+      "produces": [
+        "release-readiness",
+        "rollout-and-rollback"
+      ],
       "exitGate": "Owners autorizados aceptaron readiness, observabilidad, soporte, rollout, abort y rollback."
     },
     {
       "id": "learn",
+      "phase": "delivery",
       "agent": "data-analyst",
-      "dependsOn": ["release"],
-      "produces": ["outcome-review", "follow-up-recommendation"],
+      "dependsOn": [
+        "release"
+      ],
+      "produces": [
+        "outcome-review",
+        "follow-up-recommendation"
+      ],
       "exitGate": "Outcome y guardrails se comparan con baseline; se decide mantener, iterar, escalar o retirar."
     }
   ],

package/template/AGENTS.md

@@ -58,6 +58,17 @@ Aplica a `planning/business-rules/`, `planning/adr/`, `planning/rules/`, `teams/
 `planning/` —roadmap, backlog, WIP, done, inbox y acciones humanas— es del proyecto y no se toca al
 actualizar.
 
+`automatization/hooks/` y `automatization/runners/` son runtime del toolkit y se reemplazan enteros. No
+tienen `system/` porque no hace falta: lo que un proyecto necesita ya funciona sin editarlos.
+
+- **Agregar un guard propio**: creá `automatization/hooks/guard-<nombre>.sh` y registralo en la
+  configuración de tu runner. Sobrevive a cada actualización, porque el toolkit no lo conoce.
+- **Desactivar un guard**: quitalo de esa configuración, que es del proyecto. El archivo sigue ahí.
+- **Cambiar un comportamiento**: agregá el tuyo, no edites el del toolkit.
+
+Un guard existente **no se edita**: `upgrade` detecta el cambio y se detiene antes de pisarlo, y con
+`--force` deja registrado qué descartó.
+
 ## Cómo leer el estado
 
 Antes de abrir un archivo de `planning/`, preguntarle al CLI: es determinista, no gasta contexto y no

package/template/README.md

@@ -12,7 +12,7 @@ node tools/ops.js team check product-development
 
 - `organization/`: contexto estable de producto y negocio.
 - `agents/roles/`: cargos de IA reutilizables; cada agente lee el contexto de `organization/`.
-- `agents/workflows/`, `agents/coordinators/` y `agents/specialists/`: categorías extensibles para otros tipos de agentes.
+- Cualquier otro directorio bajo `agents/` es un tipo válido: se reconoce al tener contenido.
 - `teams/`: composiciones de varios agentes y sus handoffs.
 - `planning/`: roadmap, cola aprobada, trabajo en vuelo, evidencia e historial.
 - `AGENTS.md`: límites de autonomía y acciones que requieren una persona.

package/template/planning/reports/README.md

@@ -0,0 +1,11 @@
+# Informes
+
+Salida de los recorridos de equipo cuyo `outcome` es `report`: revisiones de incidente, análisis
+posteriores y cualquier recorrido que registre lo aprendido en vez de proponer trabajo.
+
+Un archivo por informe, nombrado `<AAAA-MM-DD>-<slug>.md`. Son evidencia: se commitean y no se
+reescriben. Si una conclusión cambia, se agrega un informe nuevo que lo diga.
+
+Los seguimientos que salen de un informe van a la sección Lecciones de `../INBOX.md` sin promover, y
+las acciones que requieren una persona a `../HUMAN_ACTIONS.md`. Convertir un seguimiento en trabajo es
+una decisión humana.

package/agents/coordinators/.gitkeep

@@ -1 +0,0 @@
-

package/agents/specialists/.gitkeep

@@ -1 +0,0 @@
-

package/agents/workflows/.gitkeep

@@ -1 +0,0 @@
-