{
  "$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"
    }
  ]
}