Execution

Runtime state tracking for an executing plan, including node progress and agent assignments.

Overview

Executions track the runtime state of a plan being executed. They record which nodes are in progress, completed, or blocked, and can track which agents are assigned to each node. Executions are typically created when a plan is started, and updated as execution progresses.

Schema

yaml

apiVersion: planspec.io/v1alpha1
kind: Execution
metadata:
  name: string          # Required, unique identifier
  namespace: string     # Required, resource namespace
  labels: object        # Optional, key-value pairs
  annotations: object   # Optional, metadata
spec:
  planRef:              # Required, reference to the plan being executed
    name: string        # Name of the plan
  goalRef:              # Optional, reference to the goal
    name: string        # Name of the goal
  bindingRef:           # Optional, reference to binding rules
    name: string        # Name of the binding
  nodeBindings:         # Optional, per-node binding overrides
    <nodeId>: object    # Node-specific binding configuration
  runtimeRef:           # Optional, reference to runtime environment
    name: string        # Name of the runtime
  parameters: object    # Optional, execution parameters
  context: object[]     # Optional, contextual attachments
status:
  phase: string         # Execution phase
  runId: string         # Unique run identifier
  reason: string        # Reason for current phase
  message: string       # Human-readable status message
  queuedTime: string    # When execution was queued
  startTime: string     # When execution started
  completionTime: string  # When execution completed
  lastPhaseTransitionTime: string  # Last phase change
  specHash: string      # Hash of the spec for tracking changes
  nodeStatuses:         # Per-node execution states (keyed by node ID)
    <nodeId>:
      phase: string     # Node execution phase
      startTime: string # When node started
      completionTime: string  # When node completed
      attempt: number   # Current attempt number
      outputs: object   # Node outputs
      message: string   # Status message
      extensions: object  # Extension data
  artifacts: object[]   # Execution artifacts
  conditions: object[]  # Status conditions
  extensions: object    # Extension data

Fields

Spec Fields

Field	Type	Required	Description
`planRef`	object	Yes	Reference to the plan being executed
`planRef.name`	string	Yes	Name of the plan
`goalRef`	object	No	Reference to the goal this execution achieves
`goalRef.name`	string	Yes*	Name of the goal (*if goalRef provided)
`bindingRef`	object	No	Reference to binding rules for capability resolution
`bindingRef.name`	string	Yes*	Name of the binding (*if bindingRef provided)
`nodeBindings`	object	No	Per-node binding overrides (keyed by node ID)
`runtimeRef`	object	No	Reference to the runtime environment
`runtimeRef.name`	string	Yes*	Name of the runtime (*if runtimeRef provided)
`parameters`	object	No	Execution parameters passed to nodes
`context`	object[]	No	Contextual attachments for execution

Status Fields

Field	Type	Description
`phase`	string	Overall execution phase
`runId`	string	Unique identifier for this run
`reason`	string	Machine-readable reason for current phase
`message`	string	Human-readable status message
`queuedTime`	string	When execution was queued (ISO 8601)
`startTime`	string	When execution started (ISO 8601)
`completionTime`	string	When execution completed (ISO 8601)
`lastPhaseTransitionTime`	string	Last phase transition timestamp
`specHash`	string	Hash of the execution spec
`nodeStatuses`	object	Per-node states, keyed by node ID
`artifacts`	object[]	Artifacts produced during execution
`conditions`	object[]	Status conditions with details
`extensions`	object	Extension data

Execution Phases

Phase	Description
`Pending`	Execution created but not started
`Running`	Execution in progress
`Blocked`	Execution blocked (e.g., waiting for gate approval)
`Succeeded`	All nodes completed successfully
`Failed`	Execution failed
`Cancelled`	Execution was cancelled

Node Status Fields

Field	Type	Description
`phase`	string	Node execution phase
`startTime`	string	When node execution started
`completionTime`	string	When node execution completed
`attempt`	number	Current attempt number (for retries)
`outputs`	object	Outputs produced by the node
`message`	string	Status message for the node
`extensions`	object	Node-specific extension data

Node Phases

Phase	Description
`Pending`	Node not yet started
`Running`	Node currently executing
`Blocked`	Node blocked by dependencies or gate
`Succeeded`	Node completed successfully
`Failed`	Node execution failed
`Skipped`	Node was skipped (conditional execution)
`Cancelled`	Node was cancelled

Example

yaml

apiVersion: planspec.io/v1alpha1
kind: Execution
metadata:
  name: user-auth-execution-001
  namespace: default
  labels:
    plan: user-auth-implementation
    environment: development
spec:
  planRef:
    name: user-auth-implementation
  goalRef:
    name: user-authentication
  bindingRef:
    name: development-bindings
  parameters:
    environment: development
    debug: true
status:
  phase: Running
  runId: "run-abc123"
  startTime: "2024-01-15T10:00:00Z"
  nodeStatuses:
    setup-database:
      phase: Succeeded
      startTime: "2024-01-15T10:00:00Z"
      completionTime: "2024-01-15T10:15:00Z"
      attempt: 1
      outputs:
        tableCreated: true
    implement-signup:
      phase: Running
      startTime: "2024-01-15T10:15:00Z"
      attempt: 1
    implement-login:
      phase: Running
      startTime: "2024-01-15T10:15:00Z"
      attempt: 1
    security-review:
      phase: Blocked
      message: "Waiting for dependent nodes to complete"
    implement-refresh:
      phase: Pending

JSON Schema

The full JSON Schema is available at: Execution Schema

Next Steps

Plan - Define the plan to execute
Gate - Add approval checkpoints to executions
Binding - Configure capability resolution