{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://agentguides.io/schemas/0.1/guide.schema.json",
  "title": "GUIDE.md frontmatter",
  "description": "JSON Schema for the YAML frontmatter of a Guide's GUIDE.md file. Generated from agentguides.spec.guide — edit the model, not this file.",
  "$defs": {
    "EndState": {
      "additionalProperties": false,
      "properties": {
        "id": {
          "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "score": {
          "maximum": 1.0,
          "minimum": 0.0,
          "type": "number"
        }
      },
      "required": [
        "id"
      ],
      "type": "object"
    },
    "ExternalResource": {
      "additionalProperties": false,
      "oneOf": [
        {
          "required": [
            "url"
          ]
        },
        {
          "required": [
            "path"
          ]
        }
      ],
      "properties": {
        "title": {
          "minLength": 1,
          "type": "string"
        },
        "url": {
          "format": "uri",
          "type": "string"
        },
        "path": {
          "type": "string"
        }
      },
      "required": [
        "title"
      ],
      "type": "object"
    },
    "Feature": {
      "enum": [
        "agent-judgment-reasoning",
        "branching",
        "linear-steps",
        "prereqs",
        "recover",
        "retry",
        "sub-walks"
      ],
      "type": "string"
    },
    "GuideBlock": {
      "additionalProperties": false,
      "properties": {
        "id": {
          "description": "Unique kebab-case id within the book/sibling scope.",
          "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
          "type": "string"
        },
        "version": {
          "description": "Semver version.",
          "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$",
          "type": "string"
        },
        "summary": {
          "description": "1-3 sentences. 'Am I in the right place?' hook.",
          "minLength": 1,
          "type": "string"
        },
        "goal_state": {
          "description": "What success looks like when the Guide completes.",
          "minLength": 1,
          "type": "string"
        },
        "prerequisites": {
          "items": {
            "$ref": "#/$defs/Prerequisite"
          },
          "type": "array"
        },
        "external_resources": {
          "items": {
            "$ref": "#/$defs/ExternalResource"
          },
          "type": "array"
        },
        "rollback_strategy": {
          "default": "best-effort",
          "enum": [
            "full",
            "best-effort",
            "none"
          ],
          "type": "string"
        },
        "rollback_entry": {
          "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
          "type": "string"
        },
        "estimated_duration_minutes": {
          "minimum": 0,
          "type": "integer"
        },
        "tags": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "requires": {
          "$ref": "#/$defs/GuideDependencies"
        },
        "end_states": {
          "description": "Declared successful exits. Ordering = preference.",
          "items": {
            "$ref": "#/$defs/EndState"
          },
          "minItems": 1,
          "type": "array"
        },
        "runtime": {
          "$ref": "#/$defs/GuideRuntime"
        }
      },
      "required": [
        "id",
        "version",
        "summary",
        "goal_state"
      ],
      "type": "object"
    },
    "GuideDependencies": {
      "additionalProperties": false,
      "properties": {
        "skills": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "guides": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "tools": {
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "type": "object"
    },
    "GuideRequires": {
      "additionalProperties": false,
      "properties": {
        "features": {
          "description": "Walk-runtime feature capabilities the Guide depends on. Each must name a feature in the canonical taxonomy (agentguides.resources.CAPABILITY_FEATURES).",
          "items": {
            "$ref": "#/$defs/Feature"
          },
          "type": "array"
        },
        "version": {
          "description": "Declared compatible runtime version range as a PEP 440 specifier (e.g. '>=0.5.10,<0.6.0'). Checked against the installed agentguides version at validate + walk start (warn on mismatch).",
          "type": "string"
        }
      },
      "type": "object"
    },
    "GuideRuntime": {
      "additionalProperties": false,
      "properties": {
        "requires": {
          "$ref": "#/$defs/GuideRequires"
        }
      },
      "type": "object"
    },
    "Prerequisite": {
      "additionalProperties": false,
      "properties": {
        "id": {
          "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
          "type": "string"
        },
        "check": {
          "description": "Relative path to a verification script.",
          "type": "string"
        },
        "performer": {
          "enum": [
            "agent",
            "human"
          ],
          "type": "string"
        },
        "description": {
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "id",
        "description"
      ],
      "type": "object"
    }
  },
  "properties": {
    "guide": {
      "$ref": "#/$defs/GuideBlock"
    }
  },
  "required": [
    "guide"
  ],
  "type": "object"
}