# ============================================================================
# CleverAgents Action Configuration Schema
# ============================================================================
#
# Formal YAML schema definition for action configuration files.
# Actions are reusable plan templates created via:
#   agents action create --config <file>
#
# This schema is based on the formal JSON Schema defined in
# docs/specification.md (Section "Action Configuration Files → JSON Schema",
# lines 15651-15788).
#
# Schema Version: 1
# ============================================================================

schema_version: "1"

# ----------------------------------------------------------------------------
# Top-Level Fields
# ----------------------------------------------------------------------------

fields:
  # ─── Identity ─────────────────────────────────────────────────
  name:
    type: string
    required: true
    pattern: "^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$"
    description: >
      Fully qualified action name in <namespace>/<name> format.
      Examples: local/code-coverage, myorg/security-audit

  description:
    type: string
    required: true
    description: >
      Short (one-line) description of the action.

  long_description:
    type: string
    required: false
    description: >
      Detailed multi-line description explaining purpose, usage,
      and expected outcomes.

  # ─── Lifecycle Actors ─────────────────────────────────────────
  strategy_actor:
    type: string
    required: true
    pattern: "^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$"
    description: >
      Actor to use during the Strategize phase.
      Must reference a registered actor by namespaced name.

  execution_actor:
    type: string
    required: true
    pattern: "^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$"
    description: >
      Actor to use during the Execute phase.
      Must reference a registered actor by namespaced name.

  estimation_actor:
    type: string
    required: false
    pattern: "^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$"
    description: >
      Actor for effort and cost estimation before execution.

  review_actor:
    type: string
    required: false
    pattern: "^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$"
    description: >
      Actor for reviewing execution results.

  apply_actor:
    type: string
    required: false
    pattern: "^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$"
    description: >
      Actor to use during the Apply phase.

  invariant_actor:
    type: string
    required: false
    pattern: "^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$"
    description: >
      Actor for reconciling conflicting invariants across scopes.

  # ─── Completion Criteria ──────────────────────────────────────
  definition_of_done:
    type: string
    required: true
    description: >
      Clear, measurable criteria that define when the action's
      work is complete.

  # ─── Action Properties ────────────────────────────────────────
  reusable:
    type: boolean
    required: false
    default: true
    description: >
      Whether the action persists after being used.
      If false, the action is archived after first use.

  read_only:
    type: boolean
    required: false
    default: false
    description: >
      Whether the action is restricted to read-only operations.
      Read-only actions must only use tools with read_only: true.

  state:
    type: string
    required: false
    enum: [available, archived]
    default: available
    description: >
      State of the action. Only 'available' and 'archived' are valid.

  # ─── Arguments ────────────────────────────────────────────────
  arguments:
    type: array
    required: false
    description: >
      Typed parameters that users supply when using the action
      via 'agents plan use --arg name=value'.
    items:
      type: object
      required_fields: [name, type]
      additional_properties: false
      fields:
        name:
          type: string
          required: true
          description: "Argument name. Used as key in --arg name=value."
        type:
          type: string
          required: true
          enum: [string, integer, float, boolean, list]
          description: "Data type of the argument."
        required:
          type: boolean
          required: false
          default: false
          description: "Whether the argument must be provided."
        description:
          type: string
          required: false
          description: "Human-readable description shown in help text."
        default:
          type: any
          required: false
          description: >
            Default value when the argument is not provided.
            Type must match the 'type' field.
        validation_pattern:
          type: string
          required: false
          description: "Regex pattern for validating string arguments."
        min_value:
          type: number
          required: false
          description: "Minimum acceptable value for integer/float arguments."
        max_value:
          type: number
          required: false
          description: "Maximum acceptable value for integer/float arguments."

  # ─── Automation ───────────────────────────────────────────────
  automation_profile:
    type: string
    required: false
    description: >
      Default automation profile for plans created from this action.
      References a named automation profile (e.g., local/cautious, trusted).

  # ─── Invariants ───────────────────────────────────────────────
  invariants:
    type: array
    required: false
    items:
      type: string
    description: >
      Constraints carried forward as plan-level invariants when
      the action is used. Invariants are trimmed, de-duplicated,
      and blanks are dropped during validation.

  # ─── Inputs Schema (Advanced) ─────────────────────────────────
  inputs_schema:
    type: object
    required: false
    description: >
      Optional JSON Schema dict for advanced input validation
      beyond basic argument types. Allows complex nested validation
      rules for action inputs.

# ----------------------------------------------------------------------------
# Constraints
# ----------------------------------------------------------------------------

required: [name, description, strategy_actor, execution_actor, definition_of_done]
additional_properties: false

# ----------------------------------------------------------------------------
# Key Normalization
# ----------------------------------------------------------------------------
# The schema loader accepts camelCase keys and normalizes them to snake_case:
#   strategyActor  -> strategy_actor
#   executionActor -> execution_actor
#   definitionOfDone -> definition_of_done
#   longDescription -> long_description
#   estimationActor -> estimation_actor
#   reviewActor -> review_actor
#   applyActor -> apply_actor
#   invariantActor -> invariant_actor
#   readOnly -> read_only
#   automationProfile -> automation_profile
#   inputsSchema -> inputs_schema
#   validationPattern -> validation_pattern
#   minValue -> min_value
#   maxValue -> max_value
#   schemaVersion -> schema_version
# Legacy camelCase keys emit a warning but are accepted.