aiwg/agentic/code/frameworks/sdlc-complete/schemas/flows/execution-mode.yaml

Deployment tool and support utility for AI context. Copies agents, skills, commands, rules, and behaviors into the paths each AI platform reads (Claude Code, Codex, Copilot, Cursor, Warp, OpenClaw, and 6 more) so one source of truth works across 10 platfo

# Execution Mode Schema
# Based on REF-058 R-LAM (Reproducible LLM Agent Workflows)
# Issue: #114

$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://aiwg.io/schemas/execution-mode/v1"
title: "Execution Mode Configuration Schema"
description: |
  Execution mode system with strict, seeded, logged, and default modes
  to control reproducibility vs creativity tradeoff. Based on R-LAM findings
  that 47% of agent workflows produce different outputs on re-run.

type: object
required:
  - mode

properties:
  mode:
    type: string
    enum:
      - strict    # Full determinism: temperature=0, fixed seed
      - seeded    # Fixed seed with normal temperature
      - logged    # Captures all randomness sources
      - default   # Standard non-deterministic execution
    description: "Execution mode controlling reproducibility"

  strict:
    type: object
    description: "Configuration for strict mode"
    properties:
      temperature:
        type: number
        const: 0
        description: "Zero temperature for determinism"
      seed:
        type: integer
        description: "Fixed random seed"
      sampling:
        type: string
        const: "greedy"
        description: "Greedy decoding only"
      max_tokens:
        type: integer
        description: "Fixed max tokens"

  seeded:
    type: object
    description: "Configuration for seeded mode"
    properties:
      seed:
        type: integer
        description: "Fixed random seed"
      temperature:
        type: number
        default: 0.7
        description: "Normal temperature"
      log_seed:
        type: boolean
        default: true
        description: "Log seed in provenance"

  logged:
    type: object
    description: "Configuration for logged mode"
    properties:
      capture_sources:
        type: array
        items:
          type: string
          enum:
            - model_response
            - tool_outputs
            - external_calls
            - timestamps
            - file_contents
        default:
          - model_response
          - tool_outputs
        description: "What randomness sources to capture"
      log_location:
        type: string
        default: ".aiwg/provenance/"
        description: "Where to store logs"

  default:
    type: object
    description: "Configuration for default mode"
    properties:
      temperature:
        type: number
        default: 0.7
      allow_creativity:
        type: boolean
        default: true

# Mode selection guidance
mode_selection:
  strict:
    use_when:
      - "Testing and validation workflows"
      - "Compliance-critical operations"
      - "Debugging and bisection"
      - "CI/CD pipelines"
    tradeoff: "Maximum reproducibility, minimum creativity"
    overhead: "Minimal"

  seeded:
    use_when:
      - "Need some reproducibility but allow variation"
      - "A/B testing with controlled randomness"
      - "Development iteration"
    tradeoff: "Balanced reproducibility and creativity"
    overhead: "Minimal"

  logged:
    use_when:
      - "Need audit trail without restricting creativity"
      - "Post-hoc analysis requirements"
      - "Regulatory compliance"
    tradeoff: "Full creativity with complete logging"
    overhead: "Moderate (storage)"

  default:
    use_when:
      - "Normal interactive use"
      - "Creative tasks"
      - "Exploratory work"
    tradeoff: "Maximum creativity, no reproducibility guarantee"
    overhead: "None"

# Agent configuration
agent_mode_config:
  description: "How to configure modes per agent"

  in_agent_definition: |
    # In agent .md frontmatter
    ---
    execution:
      default_mode: strict
      allowed_modes: [strict, seeded]
    ---

  in_manifest: |
    # In manifest.json
    {
      "agents": {
        "test-engineer": {
          "execution_mode": "strict"
        }
      }
    }

  cli_override: |
    # CLI flag overrides agent default
    aiwg flow run --mode strict
    aiwg ralph "task" --mode seeded

# Provenance integration
provenance_fields:
  description: "Fields added to provenance records"
  fields:
    - name: execution_mode
      type: string
      required: true
    - name: temperature
      type: number
      required: true
    - name: seed
      type: integer
      required_if: "mode in [strict, seeded]"
    - name: randomness_log
      type: string
      required_if: "mode == logged"

# Validation rules
validation:
  strict_mode:
    - require: "temperature == 0"
      message: "Strict mode requires temperature=0"
    - require: "seed is set"
      message: "Strict mode requires fixed seed"

  seeded_mode:
    - require: "seed is set"
      message: "Seeded mode requires fixed seed"

# Examples
examples:
  - name: "Test workflow with strict mode"
    mode: strict
    strict:
      temperature: 0
      seed: 42
      sampling: greedy
      max_tokens: 4096

  - name: "Development with seeded mode"
    mode: seeded
    seeded:
      seed: 12345
      temperature: 0.7
      log_seed: true

  - name: "Compliance workflow with logging"
    mode: logged
    logged:
      capture_sources:
        - model_response
        - tool_outputs
        - external_calls
      log_location: ".aiwg/provenance/"

# References
references:
  research:
    - "@.aiwg/research/findings/REF-058-r-lam.md"
  implementation:
    - "#114"
  related:
    - "@agentic/code/addons/ralph/schemas/checkpoint.yaml"
    - "@agentic/code/frameworks/sdlc-complete/schemas/provenance/prov-record.yaml"