{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "AI Consultant Response Schema v2.0",
  "description": "Unified output schema for all AI consultants in ai-consultants skill",
  "type": "object",
  "required": ["consultant", "response", "confidence", "metadata"],
  "properties": {
    "consultant": {
      "type": "string",
      "description": "Name of the consultant (Gemini, Codex, Mistral, Kimi, Claude, Qwen3, GLM, Grok, DeepSeek, MiniMax)",
      "enum": ["Gemini", "Codex", "Mistral", "Kimi", "Claude", "Qwen3", "GLM", "Grok", "DeepSeek", "MiniMax"]
    },
    "model": {
      "type": "string",
      "description": "Specific model version used"
    },
    "persona": {
      "type": "string",
      "description": "Assigned persona role",
      "enum": ["The Architect", "The Pragmatist", "The Devil's Advocate", "The Innovator", "The Integrator", "The Pair Programmer", "The Systems Thinker", "The Eastern Sage", "The Synthesizer", "The Analyst", "The Methodologist", "The Provocateur", "The Code Specialist", "The Pragmatic Optimizer", "The Local Expert"]
    },
    "response": {
      "type": "object",
      "required": ["summary", "detailed", "approach"],
      "properties": {
        "summary": {
          "type": "string",
          "description": "TL;DR in 2-3 sentences (max 500 chars)",
          "maxLength": 500
        },
        "detailed": {
          "type": "string",
          "description": "Full detailed response"
        },
        "approach": {
          "type": "string",
          "description": "High-level approach name/category"
        },
        "code_snippets": {
          "type": "array",
          "description": "Code examples if applicable",
          "items": {
            "type": "object",
            "properties": {
              "language": { "type": "string" },
              "code": { "type": "string" },
              "description": { "type": "string" }
            }
          }
        },
        "pros": {
          "type": "array",
          "description": "Advantages of the proposed solution",
          "items": { "type": "string" }
        },
        "cons": {
          "type": "array",
          "description": "Disadvantages or trade-offs",
          "items": { "type": "string" }
        },
        "alternatives": {
          "type": "array",
          "description": "Alternative approaches considered",
          "items": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "reason_not_chosen": { "type": "string" }
            }
          }
        },
        "caveats": {
          "type": "array",
          "description": "Important assumptions or limitations",
          "items": { "type": "string" }
        },
        "references": {
          "type": "array",
          "description": "Links or references if applicable",
          "items": { "type": "string" }
        },
        "findings": {
          "type": "array",
          "description": "Locally normalized, atomically attributable findings generated during synthesis. Provider-supplied IDs are never trusted.",
          "items": { "$ref": "#/definitions/normalized_finding" }
        }
      }
    },
    "confidence": {
      "type": "object",
      "required": ["score", "reasoning"],
      "properties": {
        "score": {
          "type": "integer",
          "description": "Confidence score from 1-10",
          "minimum": 1,
          "maximum": 10
        },
        "reasoning": {
          "type": "string",
          "description": "Why this confidence level was assigned"
        },
        "uncertainty_factors": {
          "type": "array",
          "description": "Factors that reduce confidence",
          "items": { "type": "string" }
        }
      }
    },
    "metadata": {
      "type": "object",
      "properties": {
        "cost_source": {
          "type": "string",
          "enum": ["unavailable", "estimated-standard-rates", "estimated-long-context-standard-rates"],
          "description": "Codex estimate provenance; not a provider invoice."
        },
        "cost_note": {"type": "string", "description": "Limitations of the local cost estimate."},
        "tokens_cached_input": {"type": "integer", "minimum": 0, "description": "Cached subset of CLI total input tokens; not added again."},

        "billing_models": {
          "type": "array",
          "items": {"type": "string"},
          "description": "Billing participants; not content-model attestation."
        },
        "tokens_used": {
          "type": "integer",
          "description": "Tokens consumed. CLI/API usage can be measured, estimated or unknown; read tokens_source before treating it as exact."
        },
        "tokens_input": {
          "type": "integer",
          "description": "Prompt tokens from CLI/API usage or local estimation; interpret together with tokens_source. Prefer a recorded split over re-splitting tokens_used."
        },
        "tokens_output": {
          "type": "integer",
          "description": "Completion tokens from CLI/API usage or local estimation; interpret together with tokens_source."
        },
        "tokens_source": {
          "type": "string",
          "enum": ["measured", "estimated", "unknown"],
          "description": "Where tokens_used came from: measured = CLI/API usage, estimated = local prompt/reply approximation, unknown = not recorded. Key presence alone does not identify transport or measurement."
        },
        "latency_ms": {
          "type": "integer",
          "description": "Response time in milliseconds"
        },
        "model_version": {
          "type": "string",
          "description": "Best effective model identifier available from the provider, a capability probe, or the request"
        },
        "requested_model": {
          "type": "string",
          "description": "Model identifier requested by ai-consultants before provider resolution"
        },
        "model_identity_source": {
          "type": "string",
          "enum": ["provider-reported", "capability-probed", "requested-only"],
          "description": "Strength of the evidence behind model/model_version"
        },
        "response_quality": {
          "type": "string",
          "enum": ["structured", "fallback", "error", "unknown"],
          "description": "Whether the provider satisfied the JSON contract, returned usable prose, failed, or predates quality tagging."
        },
        "cli_version": {
          "type": "string",
          "description": "Observed consultant CLI version for provenance only; compatibility is not decided from this string."
        },
        "cli_compatibility": {
          "type": "string",
          "enum": ["capability-probed", "incompatible"],
          "description": "Result of checking the CLI's required command, model, and structured-output capabilities before dispatch."
        },
        "timestamp": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp of response"
        }
      }
    }
  },
  "definitions": {
    "normalized_finding": {
      "type": "object",
      "required": ["id", "kind", "field", "text"],
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^[a-z0-9_]+:[1-9][0-9]*$",
          "description": "Stable local ID: normalized lowercase consultant slug (alphanumeric/underscore) plus one-based deterministic index."
        },
        "kind": { "type": "string", "enum": ["summary", "recommendation", "trade_off", "alternative", "edge_case", "evidence"] },
        "field": { "type": "string", "enum": ["summary", "pros", "cons", "alternatives", "caveats", "references"] },
        "text": { "type": "string", "minLength": 1 }
      }
    },
    "synthesis_coverage_item": {
      "type": "object",
      "required": ["point", "source_ids"],
      "properties": {
        "point": { "type": "string" },
        "raised_by": { "type": "array", "items": { "type": "string" } },
        "source_ids": {
          "type": "array",
          "minItems": 1,
          "items": { "type": "string", "pattern": "^[a-z0-9_]+:[1-9][0-9]*$" },
          "description": "Required local normalized source IDs. Local integrity checking rejects IDs outside the expected response findings."
        },
        "kind": { "type": "string" }
      }
    }
  }
}