{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "handoff-context",
  "title": "SWL Handoff Context Schemas",
  "description": "Schemas para contexto de transferencia entre agentes SWL. Portados del patrón HandoffContext/PipelineContext de rowboat con adaptación al sistema de agentes Claude Code.",

  "definitions": {

    "HandoffContext": {
      "type": "object",
      "description": "Contexto mínimo de transferencia entre dos agentes. Incluye trazabilidad de la cadena y limite de profundidad.",
      "required": ["reason", "parentAgent", "transferCount"],
      "additionalProperties": false,
      "properties": {
        "reason": {
          "type": "string",
          "enum": ["direct_handoff", "pipeline_execution", "task_delegation", "escalation", "review_request"],
          "description": "Motivo de la transferencia. 'escalation' para problemas que superan capacidad del agente origen. 'review_request' para validación de calidad."
        },
        "parentAgent": {
          "type": "string",
          "description": "Nombre del agente que origina la transferencia (ej: 'orquestador-swl', 'planificador-swl')."
        },
        "transferCount": {
          "type": "integer",
          "minimum": 0,
          "maximum": 10,
          "description": "Número de transferencias desde el agente raíz. Si supera 10, el agente debe rechazar y reportar loop al usuario."
        },
        "sessionId": {
          "type": "string",
          "description": "ID de la sesión de Claude Code para correlación con run-log.js."
        },
        "metadata": {
          "type": "object",
          "description": "Datos adicionales específicos del dominio (libre). No incluir datos sensibles ni contexto de conversación completo.",
          "additionalProperties": true
        }
      }
    },

    "PipelineContext": {
      "type": "object",
      "description": "Contexto enriquecido para ejecución de pipelines multi-agente (ej: fases del PLAN.md). Extiende HandoffContext con estado del pipeline.",
      "required": ["reason", "parentAgent", "transferCount", "pipelineName", "currentStep", "totalSteps"],
      "additionalProperties": false,
      "properties": {
        "reason": {
          "type": "string",
          "enum": ["pipeline_execution"],
          "description": "Siempre 'pipeline_execution' para este schema."
        },
        "parentAgent": {
          "type": "string"
        },
        "transferCount": {
          "type": "integer",
          "minimum": 0,
          "maximum": 10
        },
        "sessionId": {
          "type": "string"
        },
        "pipelineName": {
          "type": "string",
          "description": "Nombre del pipeline o fase (ej: 'fase-2-backend', 'ejecutar-plan-v3')."
        },
        "currentStep": {
          "type": "integer",
          "minimum": 1,
          "description": "Número del paso actual (base 1)."
        },
        "totalSteps": {
          "type": "integer",
          "minimum": 1,
          "description": "Total de pasos del pipeline."
        },
        "isLastStep": {
          "type": "boolean",
          "description": "true si currentStep === totalSteps."
        },
        "stepResults": {
          "type": "array",
          "description": "Resultados acumulados de pasos anteriores. Cada agente SOLO recibe los resultados relevantes para su paso, no el array completo.",
          "items": {
            "type": "object",
            "required": ["step", "agentName"],
            "properties": {
              "step": {
                "type": "integer",
                "description": "Número del paso que produjo este resultado."
              },
              "agentName": {
                "type": "string",
                "description": "Agente que produjo este resultado."
              },
              "output": {
                "type": "object",
                "description": "Output estructurado del paso (artefactos: paths, resúmenes, decisiones).",
                "additionalProperties": true
              },
              "status": {
                "type": "string",
                "enum": ["completed", "skipped", "failed"],
                "default": "completed"
              }
            }
          }
        },
        "pipelineData": {
          "type": "object",
          "description": "Datos compartidos mutables del pipeline (estado acumulado accesible por todos los pasos).",
          "additionalProperties": true
        },
        "metadata": {
          "type": "object",
          "additionalProperties": true
        }
      }
    },

    "TaskDelegationContext": {
      "type": "object",
      "description": "Contexto para delegación de una tarea específica del PLAN.md a un agente especializado.",
      "required": ["reason", "parentAgent", "transferCount", "taskId", "taskDescription"],
      "additionalProperties": false,
      "properties": {
        "reason": {
          "type": "string",
          "enum": ["task_delegation"]
        },
        "parentAgent": {
          "type": "string"
        },
        "transferCount": {
          "type": "integer",
          "minimum": 0,
          "maximum": 10
        },
        "sessionId": {
          "type": "string"
        },
        "taskId": {
          "type": "string",
          "description": "ID de la tarea del PLAN.md (ej: 'T-03')."
        },
        "taskDescription": {
          "type": "string",
          "maxLength": 500,
          "description": "Descripción completa de la tarea del plan (self-contained, sin referencias a otros docs)."
        },
        "verificationCriteria": {
          "type": "string",
          "description": "Criterio de verificación de la tarea (copiado del PLAN.md)."
        },
        "relevantFiles": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Lista de archivos relevantes para la tarea (file:line cuando aplica)."
        },
        "previousTaskOutputs": {
          "type": "array",
          "description": "Outputs de tareas previas que esta tarea depende.",
          "items": {
            "type": "object",
            "properties": {
              "taskId":    { "type": "string" },
              "output":    { "type": "object", "additionalProperties": true }
            }
          }
        },
        "metadata": {
          "type": "object",
          "additionalProperties": true
        }
      }
    }

  },

  "oneOf": [
    { "$ref": "#/definitions/HandoffContext" },
    { "$ref": "#/definitions/PipelineContext" },
    { "$ref": "#/definitions/TaskDelegationContext" }
  ],

  "examples": [
    {
      "comment": "HandoffContext — orquestador delega al planificador",
      "reason": "direct_handoff",
      "parentAgent": "orquestador-swl",
      "transferCount": 1,
      "sessionId": "abc123",
      "metadata": { "requestType": "feature", "priority": "high" }
    },
    {
      "comment": "PipelineContext — ejecutar-fase pasa resultados del paso 2 al paso 3",
      "reason": "pipeline_execution",
      "parentAgent": "implementador-swl",
      "transferCount": 3,
      "sessionId": "abc123",
      "pipelineName": "fase-2-backend",
      "currentStep": 3,
      "totalSteps": 7,
      "isLastStep": false,
      "stepResults": [
        { "step": 1, "agentName": "implementador-swl", "output": { "schemaPath": "src/models/user.ts" }, "status": "completed" },
        { "step": 2, "agentName": "backend-python-swl", "output": { "migrationPath": "db/migrations/001.sql" }, "status": "completed" }
      ]
    },
    {
      "comment": "TaskDelegationContext — orquestador delega T-03 al backend-python-swl",
      "reason": "task_delegation",
      "parentAgent": "orquestador-swl",
      "transferCount": 1,
      "sessionId": "abc123",
      "taskId": "T-03",
      "taskDescription": "Implementar endpoint POST /users con validación Pydantic v2 y persistencia SQLAlchemy async.",
      "verificationCriteria": "curl -X POST /users devuelve 201 con { id, email, created_at }",
      "relevantFiles": ["src/routers/users.py:1", "src/models/user.py:45", "src/schemas/user.py"]
    }
  ]
}