{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://raw.githubusercontent.com/fractary/faber/main/plugins/faber/config/schemas/plan.schema.json",
  "title": "FABER Plan Schema",
  "description": "JSON Schema for FABER workflow plans generated by CLI or workflow-planner agent",
  "type": "object",
  "required": ["id", "created_by", "created", "workflow", "items"],
  "additionalProperties": true,
  "properties": {
    "$schema": {
      "type": "string",
      "format": "uri",
      "description": "JSON Schema reference for IDE validation"
    },
    "id": {
      "type": "string",
      "description": "Unique plan identifier (format: {org}-{project}-{work-id}-{YYYYMMDD}-{HHMMSS})",
      "examples": ["corthosai-etl-corthion-ai-258-20260106-143022", "fractary-faber-258-20260106-143022"]
    },
    "created_by": {
      "type": "string",
      "enum": ["cli", "workflow-planner", "api"],
      "description": "Tool that created the plan"
    },
    "cli_version": {
      "type": "string",
      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
      "description": "Version of CLI that created the plan (if created_by: cli)",
      "examples": ["3.4.0"]
    },
    "created": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp when plan was created"
    },
    "metadata": {
      "type": "object",
      "description": "Structured metadata for analytics and partitioning",
      "properties": {
        "org": {
          "type": "string",
          "description": "GitHub organization"
        },
        "project": {
          "type": "string",
          "description": "Project/repository name"
        },
        "subproject": {
          "type": "string",
          "description": "Subproject identifier (e.g., issue-258, ipeds-admissions)"
        },
        "year": { "type": "string" },
        "month": { "type": "string" },
        "day": { "type": "string" },
        "hour": { "type": "string" },
        "minute": { "type": "string" },
        "second": { "type": "string" }
      }
    },
    "source": {
      "type": "object",
      "description": "How the plan was sourced",
      "properties": {
        "input": {
          "type": "string",
          "description": "Original user input"
        },
        "work_id": {
          "type": ["string", "null"],
          "description": "Work item ID (if work_id planning mode)"
        },
        "planning_mode": {
          "type": "string",
          "enum": ["work_id", "target"],
          "description": "How the plan was initiated"
        },
        "target_match": {
          "type": ["object", "null"],
          "description": "Target pattern match info (if target planning mode)"
        },
        "expanded_from": {
          "type": ["string", "null"],
          "description": "Parent plan if this was expanded from a multi-target plan"
        }
      }
    },
    "workflow": {
      "type": "object",
      "required": ["id", "inheritance_chain", "phases"],
      "description": "Full resolved workflow with all steps and prompts",
      "properties": {
        "id": {
          "type": "string",
          "description": "Workflow identifier (e.g., fractary-faber-default, dataset-create)"
        },
        "resolved_at": {
          "type": "string",
          "format": "date-time",
          "description": "When the workflow was resolved"
        },
        "inheritance_chain": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Workflow inheritance chain from child to root ancestor"
        },
        "phases": {
          "type": "object",
          "description": "Resolved phases with merged steps from inheritance chain",
          "properties": {
            "frame": { "$ref": "#/definitions/resolved_phase" },
            "architect": { "$ref": "#/definitions/resolved_phase" },
            "build": { "$ref": "#/definitions/resolved_phase" },
            "evaluate": { "$ref": "#/definitions/resolved_phase" },
            "release": { "$ref": "#/definitions/resolved_phase" }
          }
        }
      }
    },
    "autonomy": {
      "type": "string",
      "enum": ["supervised", "assisted", "autonomous", "guarded"],
      "description": "Autonomy level for workflow execution"
    },
    "phases_to_run": {
      "type": ["array", "null"],
      "items": { "type": "string" },
      "description": "Phase filter (null = run all enabled phases)"
    },
    "step_to_run": {
      "type": ["string", "null"],
      "description": "Step filter (null = run all steps)"
    },
    "additional_instructions": {
      "type": ["string", "null"],
      "description": "Additional instructions for the executor"
    },
    "items": {
      "type": "array",
      "description": "Plan items (one per target/work-id)",
      "items": {
        "$ref": "#/definitions/plan_item"
      }
    },
    "execution": {
      "type": "object",
      "description": "Execution metadata",
      "properties": {
        "mode": {
          "type": "string",
          "enum": ["sequential", "parallel"],
          "description": "Execution mode for multiple items"
        },
        "max_concurrent": {
          "type": "integer",
          "minimum": 1,
          "description": "Max concurrent executions (if parallel mode)"
        },
        "status": {
          "type": "string",
          "enum": ["pending", "in_progress", "completed", "failed"],
          "description": "Execution status"
        },
        "started_at": {
          "type": ["string", "null"],
          "format": "date-time"
        },
        "completed_at": {
          "type": ["string", "null"],
          "format": "date-time"
        },
        "results": {
          "type": "array",
          "description": "Per-item execution results"
        }
      }
    }
  },
  "definitions": {
    "resolved_phase": {
      "type": "object",
      "description": "A resolved workflow phase with merged steps",
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Whether this phase is enabled"
        },
        "description": {
          "type": "string",
          "description": "Phase description"
        },
        "steps": {
          "type": "array",
          "description": "Resolved steps for this phase",
          "items": {
            "$ref": "#/definitions/workflow_step"
          }
        },
        "pre_steps": {
          "type": "array",
          "items": { "$ref": "#/definitions/workflow_step" }
        },
        "post_steps": {
          "type": "array",
          "items": { "$ref": "#/definitions/workflow_step" }
        },
        "require_approval": {
          "type": "boolean"
        },
        "max_retries": {
          "type": "integer",
          "minimum": 0
        },
        "result_handling": {
          "$ref": "#/definitions/result_handling"
        }
      }
    },
    "workflow_step": {
      "type": "object",
      "required": ["id", "prompt"],
      "description": "A resolved workflow step with executable prompt",
      "properties": {
        "id": {
          "type": "string",
          "description": "Step identifier (e.g., build-engineer, evaluate-deploy-apply-test)"
        },
        "name": {
          "type": "string",
          "description": "Human-readable step name"
        },
        "description": {
          "type": "string",
          "description": "Step description"
        },
        "prompt": {
          "type": "string",
          "description": "Executable slash command for this step (e.g., /fractary-faber-code:engineer --work-id {work_id})"
        },
        "source": {
          "type": "string",
          "description": "Source workflow that defines this step (set during merge resolution)"
        },
        "guards": {
          "type": "object",
          "description": "Guard conditions for step execution",
          "properties": {
            "skip_if": { "type": "string" },
            "require_if": { "type": "string" }
          }
        },
        "result_handling": {
          "$ref": "#/definitions/result_handling"
        },
        "position": {
          "type": "string",
          "enum": ["pre_step", "step", "post_step"],
          "description": "Position type within the phase"
        }
      }
    },
    "result_handling": {
      "type": "object",
      "description": "Result handling configuration",
      "properties": {
        "on_success": { "type": "string" },
        "on_warning": { "type": "string" },
        "on_failure": { "type": "string" },
        "on_pending_input": { "type": "string" }
      }
    },
    "plan_item": {
      "type": "object",
      "description": "A single plan item (one per target or work-id)",
      "properties": {
        "target": {
          "type": "string",
          "description": "Target identifier"
        },
        "work_id": {
          "type": ["string", "null"],
          "description": "Work item ID (null if target mode)"
        },
        "planning_mode": {
          "type": "string",
          "enum": ["work_id", "target"]
        },
        "issue": {
          "type": ["object", "null"],
          "description": "Issue metadata (null if target mode)",
          "properties": {
            "number": { "type": "integer" },
            "title": { "type": "string" },
            "url": { "type": "string", "format": "uri" }
          }
        },
        "target_context": {
          "type": ["object", "null"],
          "description": "Target-specific context (null if work_id mode)"
        },
        "branch": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "status": {
              "type": "string",
              "enum": ["new", "ready", "resume"]
            },
            "resume_from": {
              "type": "object",
              "properties": {
                "phase": { "type": "string" },
                "step": { "type": "string" }
              }
            }
          }
        },
        "worktree": {
          "type": ["string", "null"]
        }
      }
    }
  }
}