@saulwade/swl-ses 1.0.0

package/schemas/agent-contract.json

@@ -0,0 +1,176 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://swl-ses/schemas/agent-contract.json",
+  "title": "Contrato de agente SWL",
+  "description": "Define el contrato de input/output de un agente SWL para el orquestador. Permite al orquestador validar dependencias, resolver variables {{...}} y construir prompts tipados. Inspirado en el patrón ToolConfig<Params, Response> de Sim Studio (simstudioai/sim).",
+  "type": "object",
+  "required": ["agente", "descripcion", "inputEsperado", "outputEsperado"],
+  "additionalProperties": false,
+  "properties": {
+    "agente": {
+      "type": "string",
+      "description": "Nombre del agente en kebab-case (debe coincidir con el archivo en agentes/)",
+      "pattern": "^[a-z][a-z0-9-]*-swl$",
+      "examples": ["implementador-swl", "planificador-swl", "revisor-codigo-swl"]
+    },
+    "descripcion": {
+      "type": "string",
+      "description": "Qué hace el agente — una oración concisa",
+      "minLength": 10,
+      "maxLength": 200
+    },
+    "inputEsperado": {
+      "type": "object",
+      "description": "Estructura de input que el agente necesita para funcionar correctamente",
+      "additionalProperties": false,
+      "properties": {
+        "requerido": {
+          "type": "array",
+          "description": "Campos o contexto requeridos en el prompt — sin ellos el agente no puede ejecutar",
+          "items": { "type": "string" },
+          "default": [],
+          "examples": [["PLAN.md", "arquitectura del proyecto", "stack tecnológico"]]
+        },
+        "opcional": {
+          "type": "array",
+          "description": "Campos opcionales que mejoran la calidad del output",
+          "items": { "type": "string" },
+          "default": [],
+          "examples": [["historial de commits", "APRENDIZAJES.md"]]
+        },
+        "referencias": {
+          "type": "array",
+          "description": "Referencias {{...}} al execution-state.json que este agente puede consumir",
+          "items": {
+            "type": "string",
+            "pattern": "^[\\w.-]+$"
+          },
+          "default": [],
+          "examples": [["planificador-swl.output.archivos", "contexto.decisiones"]]
+        }
+      }
+    },
+    "outputEsperado": {
+      "type": "object",
+      "description": "Estructura del output que el agente produce al completar su tarea",
+      "additionalProperties": false,
+      "properties": {
+        "campos": {
+          "type": "object",
+          "description": "Mapa campo → descripción del output. Estos campos pueden referenciarse como {{agente.output.campo}}",
+          "additionalProperties": { "type": "string" },
+          "default": {},
+          "examples": [
+            {
+              "archivosCreados": "Lista de archivos nuevos creados",
+              "archivosModificados": "Lista de archivos modificados",
+              "resumen": "Descripción en prosa de lo implementado"
+            }
+          ]
+        },
+        "efectosSecundarios": {
+          "type": "array",
+          "description": "Archivos o recursos que el agente modifica como efecto secundario (para auditoría)",
+          "items": { "type": "string" },
+          "default": [],
+          "examples": [["src/", ".planning/ESTADO.md", "CHANGELOG.md"]]
+        }
+      }
+    },
+    "dependencias": {
+      "type": "array",
+      "description": "Agentes que DEBEN haber completado su ejecución antes que este. El orquestador valida esto contra execution-state.json.",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9-]*-swl$"
+      },
+      "default": [],
+      "examples": [["planificador-swl"], ["arquitecto-swl", "planificador-swl"]]
+    },
+    "ejecucionParalela": {
+      "type": "boolean",
+      "description": "Si true, puede ejecutarse en paralelo con otros agentes del mismo slice (sin dependencias de datos entre ellos). Los revisores generalmente son true; los implementadores generalmente son false.",
+      "default": false
+    },
+    "skillsRequeridos": {
+      "type": "array",
+      "description": "Skills que el agente DEBE cargar con Skill() antes de iniciar su tarea. El orquestador puede validar que el skill existe.",
+      "items": { "type": "string" },
+      "default": [],
+      "examples": [["typescript-avanzado", "checklist-calidad"]]
+    },
+    "tipoEjecucion": {
+      "type": "string",
+      "description": "Tipo de ejecución del agente — afecta cómo el orquestador maneja el output",
+      "enum": ["implementacion", "revision", "planificacion", "investigacion", "infraestructura"],
+      "default": "implementacion"
+    },
+    "ejemploUso": {
+      "type": "object",
+      "description": "Ejemplo concreto de cómo invocar este agente desde el orquestador",
+      "additionalProperties": false,
+      "properties": {
+        "prompt": {
+          "type": "string",
+          "description": "Ejemplo de prompt con referencias {{...}} resueltas"
+        },
+        "outputEjemplo": {
+          "type": "object",
+          "description": "Ejemplo del outputResumen que se escribiría en execution-state.json"
+        }
+      }
+    }
+  },
+  "examples": [
+    {
+      "agente": "implementador-swl",
+      "descripcion": "Implementa slices verticales de funcionalidad según PLAN.md, produciendo código limpio con tests.",
+      "inputEsperado": {
+        "requerido": ["PLAN.md aprobado", "stack tecnológico", "slice a implementar"],
+        "opcional": ["historial de commits recientes", "APRENDIZAJES.md"],
+        "referencias": [
+          "planificador-swl.output.archivosACrear",
+          "arquitecto-swl.output.decisiones",
+          "contexto.decisiones"
+        ]
+      },
+      "outputEsperado": {
+        "campos": {
+          "archivosCreados": "Archivos nuevos creados en el slice",
+          "archivosModificados": "Archivos existentes modificados",
+          "testsCreados": "Tests escritos para la funcionalidad",
+          "resumen": "Descripción de lo implementado en 2-3 oraciones"
+        },
+        "efectosSecundarios": ["src/", "tests/"]
+      },
+      "dependencias": ["planificador-swl"],
+      "ejecucionParalela": false,
+      "skillsRequeridos": ["checklist-calidad"],
+      "tipoEjecucion": "implementacion"
+    },
+    {
+      "agente": "revisor-codigo-swl",
+      "descripcion": "Revisa calidad del código implementado con criterios de senior: SOLID, DRY, complejidad ciclomática.",
+      "inputEsperado": {
+        "requerido": ["archivos a revisar", "criterios de calidad"],
+        "opcional": ["historia de cambios del PR"],
+        "referencias": [
+          "implementador-swl.output.archivosCreados",
+          "implementador-swl.output.archivosModificados"
+        ]
+      },
+      "outputEsperado": {
+        "campos": {
+          "score": "Score numérico global N/10",
+          "hallazgos": "Lista de hallazgos clasificados por severidad",
+          "veredicto": "APROBADO | APROBADO_CON_CORRECCIONES | RECHAZADO"
+        },
+        "efectosSecundarios": []
+      },
+      "dependencias": ["implementador-swl"],
+      "ejecucionParalela": true,
+      "skillsRequeridos": [],
+      "tipoEjecucion": "revision"
+    }
+  ]
+}

package/schemas/agent-frontmatter.schema.json

@@ -0,0 +1,149 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://swl-ses.dev/schemas/agent-frontmatter.json",
+  "title": "SWL Agent Frontmatter",
+  "description": "Schema de validacion para el frontmatter YAML de agentes del sistema SWL",
+  "type": "object",
+  "required": ["name", "description", "tools", "model", "version", "nivelRiesgo"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]+-swl$",
+      "maxLength": 64,
+      "description": "Nombre en kebab-case terminado en -swl"
+    },
+    "description": {
+      "type": "string",
+      "minLength": 20,
+      "maxLength": 1024,
+      "description": "Descripcion que incluye QUE hace y CUANDO invocarlo"
+    },
+    "tools": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": ["Read", "Write", "Edit", "Bash", "Grep", "Glob", "Agent", "Skill", "WebSearch", "WebFetch"]
+      },
+      "minItems": 1,
+      "description": "Herramientas permitidas para este agente"
+    },
+    "model": {
+      "type": "string",
+      "oneOf": [
+        { "enum": ["opus", "sonnet", "haiku", "inherit"] },
+        { "pattern": "^claude-(opus|sonnet|haiku)-[0-9]+-[0-9]+(-[0-9]+)?$" }
+      ],
+      "description": "Modelo principal del agente. Acepta alias cortos (opus/sonnet/haiku), 'inherit' para sub-agentes, o nombre completo tipo 'claude-opus-4-7', 'claude-sonnet-4-6', 'claude-haiku-4-5-20251001'."
+    },
+    "modeloAlterno": {
+      "type": "string",
+      "oneOf": [
+        { "enum": ["opus", "sonnet", "haiku", "inherit"] },
+        { "pattern": "^claude-(opus|sonnet|haiku)-[0-9]+-[0-9]+(-[0-9]+)?$" }
+      ],
+      "description": "Modelo alternativo cuando el principal no esta disponible. Mismos formatos aceptados que 'model'."
+    },
+    "ventanaContexto": {
+      "type": "string",
+      "description": "Ventana de contexto recomendada"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Version semantica del agente"
+    },
+    "nivelRiesgo": {
+      "type": "string",
+      "enum": ["BAJO", "MEDIO", "ALTO"],
+      "description": "Nivel de riesgo de las operaciones del agente"
+    },
+    "skillsInvocables": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Skills que este agente puede invocar"
+    },
+    "skillsRestringidos": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Skills que este agente NO debe invocar"
+    },
+    "permisosRed": {
+      "type": "boolean",
+      "description": "Si el agente puede hacer llamadas de red"
+    },
+    "permisosEscritura": {
+      "type": "boolean",
+      "description": "Si el agente puede escribir archivos"
+    },
+    "permisosComandos": {
+      "type": "boolean",
+      "description": "Si el agente puede ejecutar comandos bash"
+    },
+    "presupuestoMaxUsd": {
+      "type": "number",
+      "minimum": 0.01,
+      "maximum": 50.0,
+      "description": "Presupuesto maximo en USD por invocacion del agente. Inspirado en maxBudgetUsd del Anthropic Agent SDK. El hook tracking-costos emite alerta al 80% y sugiere detener al 100%"
+    },
+    "maxTurnos": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 100,
+      "description": "Maximo de turnos (iteraciones de herramienta) por invocacion. Previene loops infinitos. Inspirado en maxTurns del Anthropic Agent SDK"
+    },
+    "toolBudget": {
+      "type": "object",
+      "properties": {
+        "simple": { "type": "integer", "description": "Tool calls para tareas simples" },
+        "standard": { "type": "integer", "description": "Tool calls para tareas estandar" },
+        "complex": { "type": "integer", "description": "Tool calls para tareas complejas" }
+      },
+      "description": "Presupuesto de tool calls por nivel de complejidad"
+    },
+    "evolvable": {
+      "type": "boolean",
+      "description": "Marca AGP learnability. Si false, el loop de auto-evolucion NO debe proponer cambios a este agente. Default implicito (ausencia del campo): true para BAJO, false para MEDIO/ALTO."
+    },
+    "evolvable_scope": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": ["description", "examples", "instructions", "skillsInvocables", "skillsRestringidos", "tools", "model", "nivelRiesgo", "permisosRed", "permisosEscritura", "permisosComandos"]
+      },
+      "description": "Si evolvable=true, limita las secciones/campos que el loop puede modificar. Ausente implica 'description' y 'examples' unicamente — campos de seguridad NUNCA evolucionan sin aprobacion humana."
+    },
+    "invariantes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["campo", "operador", "valor"],
+        "properties": {
+          "campo": {
+            "type": "string",
+            "description": "Nombre de la propiedad del frontmatter a validar tras una evolucion (ej: 'permisosRed')."
+          },
+          "operador": {
+            "type": "string",
+            "enum": ["eq", "neq", "lte", "gte", "in", "not_in"],
+            "description": "Operador de comparacion. eq/neq: igualdad; lte/gte: orden numerico; in/not_in: pertenencia a lista."
+          },
+          "valor": {
+            "description": "Valor esperado. Para in/not_in debe ser array."
+          },
+          "razon": {
+            "type": "string",
+            "description": "Justificacion humana del invariante. Opcional pero recomendado."
+          }
+        },
+        "additionalProperties": false
+      },
+      "description": "Safety invariants que el commit gate (run-skill-evals.js) debe verificar tras cada evolucion."
+    },
+    "exclusiones": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Situaciones donde este agente NO debe invocarse aunque parezca relevante superficialmente. Campo propio de swl-ses; previene activacion tangencial (agent hijacking) por similitud de terminos en description. Equivalente estructural de la seccion 'Cuando NO invocarme' en el cuerpo, legible por herramientas de analisis sin parsear markdown. Aditivo, no breaking, aplicable a agentes con evolvable:false (metadata defensiva, no evolucion AGP — ver ADR-0004)."
+    }
+  },
+  "additionalProperties": true
+}

package/schemas/agent-message.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://swl-ses.dev/schemas/agent-message.json",
+  "title": "SWL Agent Message",
+  "description": "Schema de validacion para mensajes entre agentes SWL",
+  "type": "object",
+  "required": ["id", "type", "from", "to", "timestamp", "status"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^msg-[a-z0-9]+-[a-z0-9]+$",
+      "description": "Identificador unico del mensaje generado por generarMessageId()"
+    },
+    "type": {
+      "type": "string",
+      "enum": ["task_handoff", "query", "response", "completed", "conflict"],
+      "description": "Tipo de mensaje segun el protocolo SWL inter-agent"
+    },
+    "from": {
+      "type": "string",
+      "description": "Nombre del agente emisor"
+    },
+    "to": {
+      "type": "string",
+      "description": "Nombre del agente destinatario o 'broadcast' para todos"
+    },
+    "payload": {
+      "type": "object",
+      "description": "Datos del mensaje, estructura libre segun type"
+    },
+    "contextFiles": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Rutas de archivos relevantes al mensaje, usadas para deteccion de conflictos"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Fecha y hora de creacion del mensaje en formato ISO 8601"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["pending", "processed", "expired"],
+      "description": "Estado actual del mensaje en el ciclo de vida del protocolo"
+    },
+    "processedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Fecha y hora en que el mensaje fue marcado como procesado"
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/agent-output-implementacion.schema.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "AgentOutputImplementacion",
+  "description": "Schema para output estructurado del agente implementador. Garantiza formato parseable para el orquestador.",
+  "type": "object",
+  "required": ["estado", "slicesCompletados", "slicesTotal", "commits"],
+  "properties": {
+    "estado": {
+      "type": "string",
+      "enum": ["COMPLETADO", "PARCIAL", "BLOQUEADO"],
+      "description": "Estado final de la implementacion"
+    },
+    "slicesCompletados": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Cantidad de slices completados exitosamente"
+    },
+    "slicesTotal": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Cantidad total de slices en el plan"
+    },
+    "commits": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["hash", "slice", "mensaje"],
+        "properties": {
+          "hash": {
+            "type": "string",
+            "description": "Hash corto del commit (7 chars)"
+          },
+          "slice": {
+            "type": "string",
+            "description": "ID del slice (ej: T-01)"
+          },
+          "mensaje": {
+            "type": "string",
+            "description": "Mensaje del commit"
+          }
+        }
+      }
+    },
+    "desviaciones": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["slice", "regla", "descripcion"],
+        "properties": {
+          "slice": {
+            "type": "string",
+            "description": "ID del slice donde ocurrio la desviacion"
+          },
+          "regla": {
+            "type": "string",
+            "enum": ["AUTO-FIX", "AUTO-ADD", "AUTO-FIX-TEST", "STOP"],
+            "description": "Regla de desviacion aplicada (1-4)"
+          },
+          "descripcion": {
+            "type": "string",
+            "description": "Que se desvio y por que"
+          }
+        }
+      },
+      "default": []
+    },
+    "pendiente": {
+      "type": "string",
+      "description": "Descripcion del bloqueo (solo si estado = BLOQUEADO o PARCIAL)"
+    },
+    "tokenUsage": {
+      "type": "object",
+      "properties": {
+        "input": { "type": "integer", "minimum": 0 },
+        "output": { "type": "integer", "minimum": 0 }
+      },
+      "description": "Tokens consumidos en la implementacion"
+    },
+    "toolCalls": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Total de tool calls ejecutados"
+    }
+  }
+}

package/schemas/agent-output-planificacion.schema.json

@@ -0,0 +1,113 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "AgentOutputPlanificacion",
+  "description": "Schema para output estructurado del agente planificador. Formato parseable para ejecutar-fase.",
+  "type": "object",
+  "required": ["tareas", "oleadas", "duracionEstimada"],
+  "properties": {
+    "tareas": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "titulo", "tipo", "descripcion", "entregable", "verificacion", "tiempoEstimado"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^T-\\d{2,3}$",
+            "description": "ID de la tarea (ej: T-01, T-02)"
+          },
+          "titulo": {
+            "type": "string",
+            "description": "Nombre descriptivo de la tarea"
+          },
+          "tipo": {
+            "type": "string",
+            "enum": ["AFK", "HITL"],
+            "description": "AFK = autonoma, HITL = requiere decision humana"
+          },
+          "descripcion": {
+            "type": "string",
+            "minLength": 20,
+            "description": "Que hacer, sin ambiguedad"
+          },
+          "entregable": {
+            "type": "string",
+            "description": "Que existe cuando la tarea esta completa"
+          },
+          "verificacion": {
+            "type": "string",
+            "description": "Comando o condicion observable para verificar"
+          },
+          "dependencias": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^T-\\d{2,3}$"
+            },
+            "default": [],
+            "description": "IDs de tareas que deben completarse antes"
+          },
+          "tiempoEstimado": {
+            "type": "string",
+            "description": "Estimacion (ej: 30 min, 1h)"
+          },
+          "oleada": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Numero de oleada a la que pertenece"
+          }
+        }
+      }
+    },
+    "oleadas": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["numero", "nombre", "tareas"],
+        "properties": {
+          "numero": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "nombre": {
+            "type": "string",
+            "description": "Nombre conceptual de la oleada"
+          },
+          "tareas": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^T-\\d{2,3}$"
+            },
+            "description": "IDs de tareas en esta oleada"
+          }
+        }
+      }
+    },
+    "riesgos": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["tarea", "riesgo", "mitigacion"],
+        "properties": {
+          "tarea": { "type": "string" },
+          "riesgo": { "type": "string" },
+          "probabilidad": { "type": "string", "enum": ["baja", "media", "alta"] },
+          "mitigacion": { "type": "string" }
+        }
+      },
+      "default": []
+    },
+    "duracionEstimada": {
+      "type": "string",
+      "description": "Duracion total estimada (ej: 4h, 2 dias)"
+    },
+    "tareasHITL": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Cantidad de tareas que requieren intervencion humana"
+    }
+  }
+}

package/schemas/agent-output-review.schema.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "AgentOutputReview",
+  "description": "Schema para output estructurado de agentes revisores (codigo, seguridad, lenguaje). Garantiza formato parseable entre agentes.",
+  "type": "object",
+  "required": ["veredicto", "criticos", "mayores", "menores", "hallazgos"],
+  "properties": {
+    "veredicto": {
+      "type": "string",
+      "enum": ["APROBADO", "APROBADO_CON_OBSERVACIONES", "REQUIERE_CORRECCIONES", "RECHAZADO"],
+      "description": "Resultado global de la revision"
+    },
+    "criticos": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Cantidad de hallazgos criticos (bloquean merge)"
+    },
+    "mayores": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Cantidad de hallazgos mayores (requieren atencion)"
+    },
+    "menores": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Cantidad de hallazgos menores (sugerencias)"
+    },
+    "hallazgos": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["severidad", "archivo", "descripcion"],
+        "properties": {
+          "severidad": {
+            "type": "string",
+            "enum": ["CRITICO", "MAYOR", "MENOR"],
+            "description": "Nivel de severidad del hallazgo"
+          },
+          "archivo": {
+            "type": "string",
+            "description": "Ruta del archivo afectado"
+          },
+          "linea": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Numero de linea (opcional)"
+          },
+          "descripcion": {
+            "type": "string",
+            "description": "Que se encontro"
+          },
+          "fix": {
+            "type": "string",
+            "description": "Como corregirlo"
+          },
+          "cvss": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 10,
+            "description": "Score CVSSv3 (solo para revisor-seguridad)"
+          }
+        }
+      }
+    },
+    "cobertura": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 100,
+      "description": "Porcentaje de cobertura de tests (si aplica)"
+    },
+    "score": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 10,
+      "description": "Score global de calidad 0-10"
+    }
+  }
+}