# Workflow State Schema
# Defines the structure for workflow execution state files
# State files are stored at: .aiox/{instance-id}-state.yaml
#
# Version: 1.0.0
# Created: 2026-01-31
# Purpose: Track workflow execution progress across sessions

schema:
  version: "1.0.0"

fields:
  # ---- Identity ----
  workflow_id:
    type: string
    required: true
    description: "ID from the workflow YAML (e.g., greenfield-service)"

  workflow_name:
    type: string
    required: true
    description: "Human-readable workflow name"

  instance_id:
    type: string
    required: true
    description: "Unique execution instance ID (format: {workflow_id}-YYYYMMDD-{random})"

  # ---- Context ----
  target_context:
    type: string
    required: true
    enum: [core, squad, hybrid]
    default: core
    description: "Whether workflow is from AIOX core, a squad, or hybrid (uses agents from both)"

  squad_name:
    type: string
    required: false
    description: "Squad name when target_context=squad or hybrid"

  # ---- Lifecycle ----
  started_at:
    type: string
    format: iso-8601
    required: true
    description: "When the workflow execution started"

  updated_at:
    type: string
    format: iso-8601
    required: true
    description: "Last state update timestamp"

  status:
    type: string
    required: true
    enum: [active, paused, completed, aborted]
    default: active
    description: "Current workflow execution status"

  current_phase:
    type: string
    required: false
    description: "Name/description of current phase"

  current_step_index:
    type: number
    required: true
    default: 0
    description: "Zero-based index of the current step in the sequence"

  # ---- Steps ----
  steps:
    type: array
    required: true
    description: "Mirrors workflow sequence with execution state"
    items:
      step_index:
        type: number
        description: "Zero-based index in the sequence"
      phase:
        type: string
        description: "Phase name or agent name for this step"
      agent:
        type: string
        description: "Agent responsible for this step"
      action:
        type: string
        description: "What this step does (creates/updates/validates/action)"
      status:
        type: string
        enum: [pending, in_progress, completed, skipped]
        default: pending
      optional:
        type: boolean
        default: false
        description: "Whether this step can be skipped"
      started_at:
        type: string
        format: iso-8601
        description: "When this step was started"
      completed_at:
        type: string
        format: iso-8601
        description: "When this step was completed"
      artifacts_created:
        type: array
        items:
          type: string
        description: "Artifacts produced during this step"
      notes:
        type: string
        description: "Notes or observations from execution"
      session_id:
        type: string
        description: "Claude Code session ID where this step was executed"

  # ---- Artifacts ----
  artifacts:
    type: array
    required: false
    description: "Global artifact registry tracking all created outputs"
    items:
      name:
        type: string
        description: "Artifact identifier (e.g., project-brief.md)"
      created_by_step:
        type: number
        description: "Step index that created this artifact"
      path:
        type: string
        description: "File path where artifact is stored"
      status:
        type: string
        enum: [created, pending]
        description: "Whether artifact has been created"

  # ---- Decisions ----
  decisions:
    type: array
    required: false
    description: "Decision log for audit and continuity"
    items:
      step_index:
        type: number
        description: "Step where decision was made"
      decision:
        type: string
        description: "What was decided"
      rationale:
        type: string
        description: "Why this decision was made"
      timestamp:
        type: string
        format: iso-8601

# Example state file:
#
# workflow_id: greenfield-service
# workflow_name: Greenfield Service/API Development
# instance_id: greenfield-service-20260131-a1b2c3
# target_context: core
# started_at: "2026-01-31T10:00:00Z"
# updated_at: "2026-01-31T14:30:00Z"
# status: active
# current_phase: "PM: Create PRD"
# current_step_index: 1
#
# steps:
#   - step_index: 0
#     phase: "Analyst: Project Brief"
#     agent: analyst
#     action: "creates: project-brief.md"
#     status: completed
#     started_at: "2026-01-31T10:00:00Z"
#     completed_at: "2026-01-31T11:00:00Z"
#     artifacts_created: [project-brief.md]
#     session_id: "session-abc123"
#
#   - step_index: 1
#     phase: "PM: Create PRD"
#     agent: pm
#     action: "creates: prd.md"
#     status: in_progress
#     started_at: "2026-01-31T14:00:00Z"
#
# artifacts:
#   - name: project-brief.md
#     created_by_step: 0
#     path: docs/project-brief.md
#     status: created
#   - name: prd.md
#     created_by_step: 1
#     path: docs/prd.md
#     status: pending
#
# decisions:
#   - step_index: 0
#     decision: "Skipped brainstorming, went directly to project brief"
#     rationale: "Clear requirements already provided by stakeholder"
#     timestamp: "2026-01-31T10:05:00Z"