processor

const (
	DefaultMaxIterations      = 10
	DefaultTimeoutSeconds     = 0 // 0 = no timeout (rely on max_iterations)
	DefaultContextWindow      = 5
	DefaultCheckpointInterval = 5 // Save state every N iterations
)

const (
	OutputSTDOUT = "STDOUT"
	InputSTDIN   = "STDIN"
	InputNA      = "NA"
)

const (
	// MaxMemorySizeBytes is the maximum size for memory file content (500KB)
	// This ensures memory can fit in model context windows along with prompts
	// Typical context windows: GPT-4: ~128K tokens (~512KB), Claude: ~200K tokens (~800KB)
	// We use 500KB to leave room for prompts and other content
	MaxMemorySizeBytes = 500 * 1024

	// MaxMemorySizeWarningBytes is the size at which we warn users (400KB)
	MaxMemorySizeWarningBytes = 400 * 1024
)

const EmbeddedLLMGuide = `# Comanda YAML DSL Guide (for LLM Consumption)

This guide specifies the YAML-based Domain Specific Language (DSL) for Comanda workflows, enabling LLMs to generate valid workflow files.

## ⚠️ CRITICAL RULES - READ BEFORE GENERATING ⚠️

**RULE 1 - execute_loops IGNORES top-level steps:**
When a workflow has ` + "`execute_loops:`" + `, ONLY the loops in the ` + "`loops:`" + ` block run. Any steps defined outside ` + "`loops:`" + ` are COMPLETELY IGNORED.

**RULE 2 - codebase-index with multi-loop workflows:**
If you need codebase-index AND multiple loops, the codebase-index MUST be inside a loop:
` + "```yaml" + `
loops:
  indexer:
    max_iterations: 1
    allowed_paths: [~/myproject, .]
    steps:
      index:
        step_type: codebase-index
        codebase_index:
          root: ~/myproject
          output:
            path: .comanda/INDEX.md
            store: repo

  analyzer:
    depends_on: [indexer]
    steps:
      analyze:
        input: .comanda/INDEX.md
        model: claude-code
        action: "Analyze the codebase"
        output: STDOUT

execute_loops:
  - indexer
  - analyzer
` + "```" + `

**RULE 3 - Output to files, not STDOUT, in multi-step/multi-loop workflows:**
When a workflow has multiple steps or loops that build on each other, use file outputs (e.g., ` + "`output: ./results.md`" + `) instead of ` + "`output: STDOUT`" + `. STDOUT is only useful when the next step uses ` + "`input: STDIN`" + `. For agentic loops that create documentation or artifacts, always write to files so later loops can read them.

**RULE 4 - Never put codebase-index as a top-level step with execute_loops:**
` + "```yaml" + `
# ❌ WRONG - index_step is IGNORED, $PROJECT_INDEX is never set!
index_step:
  step_type: codebase-index
  codebase_index:
    root: ~/myproject

loops:
  analyze:
    steps:
      step1:
        input: $PROJECT_INDEX  # ❌ This variable doesn't exist!
        ...

execute_loops:
  - analyze
` + "```" + `

## Overview

Comanda workflows consist of one or more named steps. Each step performs an operation. There are seven main types of steps:
1.  **Standard Processing Step:** Involves LLMs, file processing, data operations.
2.  **Generate Step:** Uses an LLM to dynamically create a new Comanda workflow YAML file.
3.  **Process Step:** Executes another Comanda workflow file (static or dynamically generated).
4.  **Agentic Loop Step:** Iteratively processes until an exit condition is met (for refinement, planning, autonomous tasks).
5.  **Multi-Loop Orchestration:** Coordinates multiple interdependent agentic loops with variable passing and creator/checker patterns.
6.  **Codebase Index Step:** Scans a repository and generates a compact Markdown index for LLM consumption.
7.  **qmd Search Step:** Searches local knowledge bases using qmd (BM25, vector, or hybrid search).

## Core Workflow Structure

A Comanda workflow is a YAML map where each key is a ` + "`step_name`" + ` (string, user-defined), mapping to a dictionary defining the step.

` + "```yaml" + `
# Example of a workflow structure
workflow_step_1:
  # ... step definition ...
another_step_name:
  # ... step definition ...
` + "```" + `

## 1. Standard Processing Step Definition

This is the most common step type.

**Basic Structure:**
` + "```yaml" + `
step_name:
  input: [input source]
  model: [model name]
  action: [action to perform / prompt provided]
  output: [output destination]
  type: [optional, e.g., "openai-responses"] # Specifies specialized handling
  batch_mode: [individual|combined] # Optional, for multi-file inputs
  skip_errors: [true|false] # Optional, for multi-file inputs
  # ... other type-specific fields for "openai-responses" like 'instructions', 'tools', etc.
` + "```" + `

**Key Elements:**
- ` + "`input`" + `: (Required for most, can be ` + "`NA`" + `) Source of data. See "Input Types".
- ` + "`model`" + `: (Required, can be ` + "`NA`" + `) LLM model to use. See "Models".
- ` + "`action`" + `: (Required for most) Instructions or operations. See "Actions".
- ` + "`output`" + `: (Required) Destination for results. See "Outputs".
- ` + "`type`" + `: (Optional) Specifies a specialized handler for the step, e.g., ` + "`openai-responses`" + `. If omitted, it's a general-purpose LLM or NA step.
- ` + "`batch_mode`" + `: (Optional, default: ` + "`combined`" + `) For steps with multiple file inputs, defines if files are processed ` + "`combined`" + ` into one LLM call or ` + "`individual`" + `ly.
- ` + "`skip_errors`" + `: (Optional, default: ` + "`false`" + `) If ` + "`batch_mode: individual`" + `, determines if processing continues if one file fails.

**OpenAI Responses API Specific Fields (used when ` + "`type: openai-responses`" + `):**
- ` + "`instructions`" + `: (string) System message for the LLM.
- ` + "`tools`" + `: (list of maps) Configuration for tools/functions the LLM can call.
- ` + "`previous_response_id`" + `: (string) ID of a previous response for maintaining conversation state.
- ` + "`max_output_tokens`" + `: (int) Token limit for the LLM response.
- ` + "`temperature`" + `: (float) Sampling temperature.
- ` + "`top_p`" + `: (float) Nucleus sampling (top-p).
- ` + "`stream`" + `: (bool) Whether to stream the response.
- ` + "`response_format`" + `: (map) Specifies response format, e.g., ` + "`{ type: \"json_object\" }`" + `.


## 2. Generate Step Definition (` + "`generate`" + `)

This step uses an LLM to dynamically create a new Comanda workflow YAML file.

**Structure:**
` + "```yaml" + `
step_name_for_generation:
  input: [optional_input_source_for_context, or NA] # e.g., STDIN, a file with requirements
  generate:
    model: [llm_model_for_generation, optional] # e.g., gpt-4o-mini. Uses default if omitted.
    action: [prompt_for_workflow_generation] # Natural language instruction for the LLM.
    output: [filename_for_generated_yaml] # e.g., new_workflow.yaml
    context_files: [list_of_files_for_additional_context, optional] # e.g., [schema.txt, examples.yaml]
` + "```" + `
**` + "`generate`" + ` Block Attributes:**
- ` + "`model`" + `: (string, optional) Specifies the LLM to use for generation. If omitted, uses the ` + "`default_generation_model`" + ` configured in Comanda. You can set or update this default model by running ` + "`comanda configure`" + ` and following the prompts for setting a default generation model.
- ` + "`action`" + `: (string, required) The natural language instruction given to the LLM to guide the workflow generation.
- ` + "`output`" + `: (string, required) The filename where the generated Comanda workflow YAML file will be saved.
- ` + "`context_files`" + `: (list of strings, optional) A list of file paths to provide as additional context to the LLM, beyond the standard Comanda DSL guide (which is implicitly included).
- **Note:** The ` + "`input`" + ` field for a ` + "`generate`" + ` step is optional. If provided (e.g., ` + "`STDIN`" + ` or a file path), its content will be added to the context for the LLM generating the workflow. If not needed, use ` + "`input: NA`" + `.

## 3. Process Step Definition (` + "`process`" + `)

This step executes another Comanda workflow file.

**Structure:**
` + "```yaml" + `
step_name_for_processing:
  input: [optional_input_source_for_sub_workflow, or NA] # e.g., STDIN to pass data to the sub-workflow
  process:
    workflow_file: [path_to_comanda_yaml_to_execute] # e.g., generated_workflow.yaml or existing_flow.yaml
    inputs: {key1: value1, key2: value2, optional} # Map of inputs to pass to the sub-workflow.
    # capture_outputs: [list_of_outputs_to_capture, optional] # Future: Define how to capture specific outputs.
` + "```" + `
**` + "`process`" + ` Block Attributes:**
- ` + "`workflow_file`" + `: (string, required) The path to the Comanda workflow YAML file to be executed. This can be a statically defined path or the output of a ` + "`generate`" + ` step.
- ` + "`inputs`" + `: (map, optional) A map of key-value pairs to pass as initial variables to the sub-workflow. These can be accessed within the sub-workflow (e.g., as ` + "`$parent.key1`" + `).
- **Note:** The ` + "`input`" + ` field for a ` + "`process`" + ` step is optional. If ` + "`input: STDIN`" + ` is used, the output of the previous step in the parent workflow will be available as the initial ` + "`STDIN`" + ` for the *first* step of the sub-workflow if that first step expects ` + "`STDIN`" + `.

## 4. Agentic Loop Step Definition (` + "`agentic_loop`" + ` / ` + "`agentic-loop`" + `)

Agentic loops enable iterative LLM processing until an exit condition is met. This is powerful for tasks that require refinement, multi-step reasoning, or autonomous decision-making.

**When to use agentic loops:**
- Iterative code improvement (analyze → fix → verify cycles)
- Multi-step planning and execution
- Tasks where the LLM decides when work is complete
- Refinement workflows (draft → improve → finalize)

### Inline Syntax (Single-Step Loop)

For simple iterative tasks with a single step:

` + "```yaml" + `
step_name:
  agentic_loop:
    max_iterations: 5           # Safety limit (default: 10)
    exit_condition: pattern_match  # or "llm_decides"
    exit_pattern: "COMPLETE"    # Regex pattern for pattern_match
  input: STDIN
  model: claude-code
  action: |
    Iteration {{ loop.iteration }}.
    Previous work: {{ loop.previous_output }}

    Continue improving. Say COMPLETE when done.
  output: STDOUT
` + "```" + `

### Block Syntax (Multi-Step Loop)

For complex loops with multiple sub-steps per iteration:

` + "```yaml" + `
agentic-loop:
  config:
    max_iterations: 5           # Safety limit (default: 10)
    timeout_seconds: 300        # Total timeout (default: 300)
    exit_condition: llm_decides # or "pattern_match"
    exit_pattern: "DONE"        # For pattern_match
    context_window: 3           # Past iterations to include (default: 5)

  steps:
    plan:
      input: STDIN
      model: claude-code
      action: |
        Iteration {{ loop.iteration }}.
        Previous: {{ loop.previous_output }}

        Plan next steps. Say DONE if complete.
      output: $PLAN

    execute:
      input: $PLAN
      model: claude-code
      action: "Execute the plan"
      output: STDOUT
` + "```" + `

**` + "`agentic_loop`" + ` Configuration:**

**Core Settings:**
- ` + "`max_iterations`" + `: (int, default: 10) Maximum iterations before stopping.
- ` + "`timeout_seconds`" + `: (int, default: 0) Total time limit in seconds. **0 = no timeout** (loop runs until max_iterations or exit condition).
- ` + "`exit_condition`" + `: (string) How to detect completion:
  - ` + "`llm_decides`" + `: Exits when output ends with "DONE", "COMPLETE", or "FINISHED" (case-insensitive). Works when these words appear at the very end of the output, at the end of any line, or as the entire output.
  - ` + "`pattern_match`" + `: Exits when output matches ` + "`exit_pattern`" + ` regex
- ` + "`exit_pattern`" + `: (string) Regex pattern for ` + "`pattern_match`" + ` condition.
- ` + "`context_window`" + `: (int, default: 5) Number of past iterations to include in context.

**File Access (REQUIRED for Claude Code):**
- ` + "`allowed_paths`" + `: (list, **REQUIRED for file operations**) Directories where Claude Code can use tools (Read, Write, Edit, Bash, etc.). **Without this, Claude Code runs in print-only mode and CANNOT read/write files.** When generating workflows, infer paths from: the ` + "`codebase_index.root`" + ` if present, file paths mentioned in the action, or use ` + "`[.]`" + ` (current directory) as fallback.
- ` + "`tools`" + `: (list, optional) Restrict available tools (e.g., ` + "`[Read, Glob, Grep]`" + ` for read-only access). If omitted, all tools are available.

**State Persistence (for Long-Running Loops):**
- ` + "`name`" + `: (string, **REQUIRED for stateful loops**) Unique identifier for the loop. Enables state persistence and resume capability.
- ` + "`stateful`" + `: (bool, default: false) Enable state persistence to ` + "`~/.comanda/loop-states/{name}.json`" + `. Allows resuming after interruption.
- ` + "`checkpoint_interval`" + `: (int, default: 5) Save state every N iterations. Lower values = more frequent saves = safer resume.

**Quality Gates (Automated Validation):**
- ` + "`quality_gates`" + `: (list, optional) Automated checks to run after each iteration. Each gate validates loop output and can trigger retry/abort/skip actions.

**Quality Gate Configuration:**
` + "```yaml" + `
quality_gates:
  - name: typecheck           # Gate name
    command: "npm run typecheck"  # Shell command to execute
    on_fail: retry            # Action: retry, abort, or skip
    timeout: 60               # Timeout in seconds
    retry:                    # Retry configuration (optional)
      max_attempts: 3         # Maximum retry attempts
      backoff_type: exponential  # linear or exponential
      initial_delay: 5        # Initial delay in seconds

  - name: security
    type: security            # Built-in gate type (syntax, security, test)
    on_fail: abort

  - name: tests
    command: "npm test"
    on_fail: skip             # Continue even if this fails
` + "```" + `

**Built-in Quality Gate Types:**
- ` + "`syntax`" + `: Checks for syntax errors (Python, JS, Go, etc.)
- ` + "`security`" + `: Scans for hardcoded secrets, security issues
- ` + "`test`" + `: Runs test commands with coverage reporting

**Quality Gate Actions (` + "`on_fail`" + `):**
- ` + "`retry`" + `: Retry the gate with backoff (exponential or linear)
- ` + "`abort`" + `: Stop loop immediately and save state as "failed"
- ` + "`skip`" + `: Log warning and continue to next iteration

**Template Variables in Actions:**
- ` + "`{{ loop.iteration }}`" + `: Current iteration number (1-based)
- ` + "`{{ loop.previous_output }}`" + `: Output from previous iteration
- ` + "`{{ loop.total_iterations }}`" + `: Maximum allowed iterations
- ` + "`{{ loop.elapsed_seconds }}`" + `: Seconds since loop started

**Example: Agentic Code Exploration**
` + "```yaml" + `
explore_codebase:
  agentic_loop:
    max_iterations: 3
    exit_condition: llm_decides
    allowed_paths: [./src, ./tests]
    tools: [Read, Glob, Grep]  # Read-only access
  input: STDIN
  model: claude-code
  action: |
    Explore the codebase and answer: {{ loop.previous_output }}
    Say DONE when you have the answer.
  output: STDOUT
` + "```" + `

**Example: Iterative Code Implementation**
` + "```yaml" + `
implement:
  agentic_loop:
    max_iterations: 3
    exit_condition: pattern_match
    exit_pattern: "SATISFIED"
    allowed_paths: [.]  # Required for file operations
  input: STDIN
  model: claude-code
  action: |
    Iteration {{ loop.iteration }}. Implement and improve the code.
    Previous: {{ loop.previous_output }}

    Add error handling, edge cases, tests.
    Say SATISFIED when production-ready.
  output: STDOUT
` + "```" + `

**Example: Plan and Build Loop**
` + "```yaml" + `
agentic-loop:
  config:
    max_iterations: 5
    exit_condition: llm_decides
    allowed_paths: [.]  # Required for file operations

  steps:
    plan:
      input: STDIN
      model: claude-code
      action: |
        Iteration {{ loop.iteration }}.
        Create/refine the implementation plan.
        Say DONE when ready to implement.
      output: $PLAN

    build:
      input: $PLAN
      model: claude-code
      action: "Generate code based on the plan"
      output: STDOUT
` + "```" + `

**Example: Long-Running Loop with State Persistence**
` + "```yaml" + `
agentic-loop:
  config:
    name: code-refactor-loop      # Required for stateful loops
    stateful: true                 # Enable state persistence
    max_iterations: 50
    timeout_seconds: 0             # No timeout - run until complete
    checkpoint_interval: 5         # Save every 5 iterations
    exit_condition: llm_decides
    allowed_paths: [./src]

    quality_gates:
    name: syntax-check
        type: syntax
        on_fail: retry
        retry:
          max_attempts: 3
          backoff_type: exponential
          initial_delay: 2

    name: tests
        command: "npm test"
        on_fail: abort              # Stop if tests fail
        timeout: 300

  steps:
    analyze:
      input: STDIN
      model: claude-code
      action: |
        Iteration {{ loop.iteration }} of {{ loop.total_iterations }}.
        Analyze code and refactor one module.
        Say DONE when all modules are refactored.
      output: STDOUT
` + "```" + `

**Example: Quality Gates with Retry**
` + "```yaml" + `
code_improvement:
  agentic_loop:
    name: improve-code
    stateful: true
    max_iterations: 10
    allowed_paths: [.]

    quality_gates:
    name: typecheck
        command: "npm run typecheck"
        on_fail: retry
        timeout: 60
        retry:
          max_attempts: 3
          backoff_type: exponential
          initial_delay: 5

    name: lint
        command: "npm run lint"
        on_fail: skip               # Non-critical, continue

  input: STDIN
  model: claude-code
  action: "Improve code quality. Say COMPLETE when done."
  output: STDOUT
` + "```" + `

**CRITICAL: When generating agentic_loop workflows with Claude Code:**
- **ALWAYS include ` + "`allowed_paths`" + `** - Claude Code CANNOT read/write files without it
- If the workflow uses ` + "`codebase_index`" + `, use the same ` + "`root`" + ` directory in ` + "`allowed_paths`" + `
- If the action mentions specific file paths or directories, include those directories
- When in doubt, use ` + "`allowed_paths: [.]`" + ` for current directory access
- Forgetting ` + "`allowed_paths`" + ` is a common error that causes "permission denied" failures
- For long-running tasks (hours/days), use ` + "`stateful: true`" + ` and ` + "`timeout_seconds: 0`" + `
- **Default to ` + "`claude-code`" + ` model for agentic workflows** - it provides the best tool use and autonomous capabilities

## 5. Multi-Loop Orchestration

Multi-loop orchestration enables complex autonomous workflows with multiple interdependent agentic loops. This is essential for creator/checker patterns, sequential processing pipelines, and complex task decomposition.

**When to use multi-loop orchestration:**
- Creator/checker validation workflows (loop A creates, loop B validates, rerun A if validation fails)
- Sequential data processing (collect → analyze → report)
- Complex task decomposition (break large task into specialized sub-loops)
- Workflows requiring variable passing between autonomous agents

### Named Loops Syntax

Define multiple named loops with dependencies and variable passing:

` + "```yaml" + `
loops:
  data-collector:
    name: data-collector
    stateful: true
    max_iterations: 10
    timeout_seconds: 0
    exit_condition: llm_decides
    allowed_paths: [.]
    output_state: $RAW_DATA         # Export result to variable

    steps:
    collect:
          input: STDIN
          model: claude-code
          action: "Collect data and say DONE when complete"
          output: STDOUT

  data-analyzer:
    name: data-analyzer
    depends_on: [data-collector]    # Wait for collector to complete
    input_state: $RAW_DATA           # Read collector's output
    stateful: true
    max_iterations: 5
    exit_condition: llm_decides
    allowed_paths: [.]
    output_state: $ANALYSIS          # Export analysis result

    steps:
    analyze:
          input: STDIN
          model: claude-code
          action: |
            Analyze this data: {{ loop.previous_output }}
            Say DONE when analysis is complete.
          output: STDOUT

  report-generator:
    name: report-generator
    depends_on: [data-analyzer]     # Wait for analyzer
    input_state: $ANALYSIS           # Read analyzer's output
    max_iterations: 1
    allowed_paths: [.]

    steps:
    generate:
          input: STDIN
          model: claude-code
          action: "Create final report based on analysis"
          output: STDOUT

# Execute loops in dependency order (topological sort)
execute_loops:
  - data-collector
  - data-analyzer
  - report-generator
` + "```" + `

**Key Configuration Fields:**
- ` + "`loops`" + `: (map) Named loop definitions
- ` + "`depends_on`" + `: (list) Loops that must complete before this one starts
- ` + "`input_state`" + `: (string) Variable to read as input (e.g., ` + "`$RAW_DATA`" + `)
- ` + "`output_state`" + `: (string) Variable to export result to (e.g., ` + "`$ANALYSIS`" + `)
- ` + "`execute_loops`" + `: (list) Simple execution order (dependencies override this)

### Creator/Checker Pattern

Advanced workflow pattern where a creator loop implements features and a checker loop validates them, with automatic rerun on failure:

` + "```yaml" + `
loops:
  # Creator loop: implements features
  feature-creator:
    name: feature-creator
    stateful: true
    max_iterations: 3
    timeout_seconds: 0
    exit_condition: llm_decides
    allowed_paths: [.]
    output_state: $CODE

    quality_gates:
    name: syntax
        type: syntax
        on_fail: abort

    steps:
    implement:
          input: STDIN
          model: claude-code
          action: |
            Iteration {{ loop.iteration }}.
            Implement the requested feature.
            Say DONE when implementation is complete.
          output: STDOUT

  # Checker loop: validates implementation
  code-checker:
    name: code-checker
    depends_on: [feature-creator]   # Wait for creator
    input_state: $CODE               # Read creator's output
    max_iterations: 1
    exit_condition: pattern_match
    exit_pattern: "^PASS"            # Exit when output starts with PASS

    steps:
    review:
          input: STDIN
          model: claude-code
          action: |
            Review this implementation: {{ loop.previous_output }}

            Check for:
            - Correctness
            - Edge cases
            - Code quality
            - Test coverage

            Output: PASS if acceptable, or FAIL with specific issues.
          output: STDOUT

# Advanced workflow with creator/checker relationship
workflow:
  creator:
    type: loop
    loop: feature-creator
    role: creator

  checker:
    type: loop
    loop: code-checker
    role: checker
    validates: creator               # This loop validates the creator
    on_fail: rerun_creator          # Auto-rerun creator if validation fails
` + "```" + `

**Workflow Node Configuration:**
- ` + "`type`" + `: Always ` + "`loop`" + ` for loop nodes
- ` + "`loop`" + `: Name of the loop to execute
- ` + "`role`" + `: Node role (` + "`creator`" + `, ` + "`checker`" + `, ` + "`finalizer`" + `)
- ` + "`validates`" + `: Name of the node this checker validates
- ` + "`on_fail`" + `: Action on validation failure:
  - ` + "`rerun_creator`" + `: Automatically rerun the creator loop (max 3 attempts)
  - ` + "`abort`" + `: Stop workflow immediately
  - ` + "`manual`" + `: Return for manual review

**Validation Logic:**
- Checker loop output is scanned for "PASS" or "FAIL"
- If "PASS" found → workflow continues
- If "FAIL" found and ` + "`on_fail: rerun_creator`" + ` → creator reruns with checker feedback
- Maximum 3 rerun attempts (prevents infinite loops)

### Dependency Graph Execution

Comanda automatically executes loops in correct order using topological sort:

1. **Build dependency graph** from ` + "`depends_on`" + ` relationships
2. **Detect cycles** - fail fast if circular dependencies exist
3. **Topological sort** using Kahn's algorithm
4. **Execute in order** - each loop waits for its dependencies

**Cycle Detection Example:**
` + "```yaml" + `
loops:
  loop-a:
    depends_on: [loop-b]

  loop-b:
    depends_on: [loop-a]

execute_loops:
  - loop-a
  - loop-b

# Error: dependency cycle detected: loop-a -> loop-b -> loop-a
` + "```" + `

### Variable Passing

Variables flow between loops via ` + "`input_state`" + ` and ` + "`output_state`" + `:

` + "```yaml" + `
loops:
  producer:
    output_state: $MY_DATA          # Write to variable

  consumer:
    depends_on: [producer]
    input_state: $MY_DATA            # Read from variable
` + "```" + `

**Variable Rules:**
- Variables are stored in memory during workflow execution
- ` + "`output_state`" + ` exports loop's final output to a variable
- ` + "`input_state`" + ` reads variable as loop input
- Variables persist across loop boundaries
- Missing variable causes error (check dependencies)

### Complete Example: Codebase Analysis Pipeline

` + "```yaml" + `
# Multi-loop workflow: analyze codebase → identify issues → generate report
loops:
  codebase-analyzer:
    name: codebase-analyzer
    stateful: true
    max_iterations: 20
    timeout_seconds: 0
    exit_condition: llm_decides
    allowed_paths: [/tmp/code]
    output_state: $ANALYSIS

    steps:
    analyze:
          input: NA
          model: claude-code
          action: |
            Analyze the codebase at /tmp/code.
            Find patterns, architecture issues, dependencies.
            Say DONE when analysis is complete.
          output: STDOUT

  tech-debt-finder:
    name: tech-debt-finder
    depends_on: [codebase-analyzer]
    input_state: $ANALYSIS
    stateful: true
    max_iterations: 10
    timeout_seconds: 0
    exit_condition: llm_decides
    allowed_paths: [/tmp/code]
    output_state: $TECH_DEBT

    steps:
    identify:
          input: STDIN
          model: claude-code
          action: |
            Based on this analysis: {{ loop.previous_output }}

            Identify tech debt and anti-patterns:
            - Code smells
            - Security issues
            - Performance bottlenecks
            - Maintainability problems

            Say DONE when complete.
          output: STDOUT

  report-writer:
    name: report-writer
    depends_on: [tech-debt-finder]
    input_state: $TECH_DEBT
    max_iterations: 1
    allowed_paths: [.]

    steps:
    write:
          input: STDIN
          model: claude-code
          action: |
            Create a comprehensive markdown report:
            {{ loop.previous_output }}

            Save to ./tech-debt-report.md
          output: STDOUT

execute_loops:
  - codebase-analyzer
  - tech-debt-finder
  - report-writer
` + "```" + `

**CRITICAL: When generating multi-loop workflows:**
- **Use ` + "`claude-code`" + ` as default model** for agentic capabilities
- **Always include ` + "`allowed_paths`" + `** for each loop that needs file access
- **Use ` + "`stateful: true`" + `** for long-running loops
- **Set ` + "`timeout_seconds: 0`" + `** for unlimited runtime
- **Use meaningful variable names** (` + "`$RAW_DATA`" + `, not ` + "`$OUTPUT`" + `)
- **Infer ` + "`allowed_paths`" + ` from user prompt** (e.g., "/tmp/code" → ` + "`allowed_paths: [/tmp/code]`" + `)
- **Default ` + "`checkpoint_interval: 5`" + `** for safety

### Using Codebase Index with Multi-Loop Workflows

**⚠️ CRITICAL:** When using ` + "`execute_loops:`" + `, **ONLY the loops are executed**. Top-level steps (outside the ` + "`loops:`" + ` block) are IGNORED.

❌ **WRONG** - Top-level codebase-index step will NOT run:
` + "```yaml" + `
# This step is IGNORED when using execute_loops!
index_core:
  step_type: codebase-index
  codebase_index:
    root: ~/my-project

loops:
  analyze:
    steps:
      step1:
        input: $MY_PROJECT_INDEX  # ❌ Variable never set!
        model: claude-code
        action: "Analyze the codebase"
        output: STDOUT

execute_loops:
  - analyze
` + "```" + `

✅ **CORRECT** - Reference the output file path directly:
` + "```yaml" + `
loops:
  analyze:
    allowed_paths: [~/my-project, .]
    steps:
      # First step: Generate the index
      index:
        step_type: codebase-index
        codebase_index:
          root: ~/my-project
          output:
            path: .comanda/MY_PROJECT_INDEX.md
            store: repo

      # Subsequent steps: Read the index file directly
      analyze:
        input: .comanda/MY_PROJECT_INDEX.md
        model: claude-code
        action: "Analyze this codebase index"
        output: STDOUT

execute_loops:
  - analyze
` + "```" + `

✅ **ALSO CORRECT** - Use input_state to pass index between loops:
` + "```yaml" + `
loops:
  indexer:
    max_iterations: 1
    allowed_paths: [~/my-project]
    output_state: $CODEBASE_INDEX
    steps:
      index:
        step_type: codebase-index
        codebase_index:
          root: ~/my-project
        output: STDOUT

  analyzer:
    depends_on: [indexer]
    input_state: $CODEBASE_INDEX
    allowed_paths: [~/my-project, .]
    steps:
      analyze:
        input: STDIN
        model: claude-code
        action: |
          Codebase index:
          {{ loop.previous_output }}

          Analyze the architecture.
        output: STDOUT

execute_loops:
  - indexer
  - analyzer
` + "```" + `


## 6. Codebase Index Step Definition (` + "`codebase_index`" + `)

This step scans a repository and generates a compact Markdown index optimized for LLM consumption. It supports multiple programming languages and exposes workflow variables for downstream steps.

**When to use codebase-index:**
- When you need to give an LLM context about a codebase structure
- Before code analysis, refactoring, or documentation tasks
- When building workflows that operate on unfamiliar repositories

**Structure:**
` + "```yaml" + `
step_name:
  step_type: codebase-index  # Alternative: use codebase_index block
  codebase_index:
    root: .                   # Repository path (default: current directory)
    output:
      path: .comanda/INDEX.md # Custom output path (optional)
      format: structured      # Output format: summary, structured, full
      store: repo             # Where to store: repo, config, or both
      encrypt: false          # Enable AES-256 encryption
    expose:
      workflow_variable: true # Export as workflow variables
      memory:
        enabled: true         # Register as memory source
        key: repo.index       # Memory key name
    adapters:                 # Per-language configuration (optional)
      go:
        ignore_dirs: [vendor, testdata]
        priority_files: ["cmd/**/*.go"]
    max_output_kb: 100        # Maximum output size in KB
    qmd:                      # qmd integration (optional)
      collection: myproject   # Register index as qmd collection
      context: "Project source code"  # Description for search relevance
      embed: false            # Run qmd embed after (slow, enables semantic search)
` + "```" + `

**` + "`codebase_index`" + ` Block Attributes:**
- ` + "`root`" + `: (string, default: ` + "`.`" + `) Repository path to scan.
- ` + "`output.path`" + `: (string, optional) Custom output file path. Default: ` + "`.comanda/<repo>_INDEX.md`" + `
- ` + "`output.format`" + `: (string, default: ` + "`structured`" + `) Output format: ` + "`summary`" + ` (compact 1-2KB for system prompts), ` + "`structured`" + ` (balanced with sections), or ` + "`full`" + ` (detailed with all symbols).
- ` + "`output.store`" + `: (string, default: ` + "`repo`" + `) Where to save: ` + "`repo`" + ` (in repository), ` + "`config`" + ` (~/.comanda/), or ` + "`both`" + `.
- ` + "`output.encrypt`" + `: (bool, default: false) Encrypt output with AES-256 GCM. Saves as ` + "`.enc`" + ` file. Requires ` + "`COMANDA_INDEX_KEY`" + ` environment variable.
- ` + "`expose.workflow_variable`" + `: (bool, default: true) Export index as workflow variables.
- ` + "`expose.memory.enabled`" + `: (bool, default: false) Register as a named memory source.
- ` + "`expose.memory.key`" + `: (string) Key name for memory access.
- ` + "`adapters`" + `: (map, optional) Per-language configuration overrides.
- ` + "`max_output_kb`" + `: (int, default: 100) Maximum size of generated index.
- ` + "`qmd.collection`" + `: (string, optional) Register index as a qmd collection with this name.
- ` + "`qmd.context`" + `: (string, optional) Description for the collection (improves search relevance).
- ` + "`qmd.embed`" + `: (bool, default: false) Run ` + "`qmd embed`" + ` after indexing (enables semantic search, slow).

**Workflow Variables Exported:**

After the step runs, these variables are available (where ` + "`<REPO>`" + ` is the uppercase repository name, e.g., ` + "`src`" + ` becomes ` + "`SRC`" + `):
- ` + "`$<REPO>_INDEX`" + `: Full Markdown content of the index
- ` + "`$<REPO>_INDEX_PATH`" + `: Absolute path to the saved index file
- ` + "`$<REPO>_INDEX_SHA`" + `: Hash of the index content
- ` + "`$<REPO>_INDEX_UPDATED`" + `: ` + "`true`" + ` if index was regenerated

**⚠️ CRITICAL: Referencing the Index in Subsequent Steps**

When a later step needs the codebase index content, you MUST use the exported variable — NOT the file path.

✅ **CORRECT** - Use the exported variable:
` + "```yaml" + `
index_codebase:
  step_type: codebase-index
  codebase_index:
    root: ./src

analyze_codebase:
  input: $SRC_INDEX          # ✅ Use the variable!
  model: claude-code
  action: "Analyze this codebase structure"
  output: STDOUT
` + "```" + `

❌ **WRONG** - Do NOT use the file path directly:
` + "```yaml" + `
index_codebase:
  step_type: codebase-index
  codebase_index:
    root: ./src
    output:
      path: .comanda/INDEX.md

analyze_codebase:
  input: .comanda/INDEX.md    # ❌ WRONG! Path may not resolve correctly
  model: claude-code
  action: "Analyze this codebase structure"
  output: STDOUT
` + "```" + `

**Why?** The ` + "`output.path`" + ` is relative to the repository root (when ` + "`store: repo`" + `), not the current working directory. The exported variable always contains the correct content regardless of where you run the workflow.

**Supported Languages:**
- **Go**: Uses AST parsing. Detection: ` + "`go.mod`" + `, ` + "`go.sum`" + `
- **Python**: Uses regex. Detection: ` + "`pyproject.toml`" + `, ` + "`requirements.txt`" + `, ` + "`setup.py`" + `
- **TypeScript/JavaScript**: Uses regex. Detection: ` + "`tsconfig.json`" + `, ` + "`package.json`" + `
- **Flutter/Dart**: Uses regex. Detection: ` + "`pubspec.yaml`" + `

**Example: Index and Analyze a Codebase**
` + "```yaml" + `
# Step 1: Generate codebase index
index_repo:
  step_type: codebase-index
  codebase_index:
    root: ./my-project
    expose:
      workflow_variable: true

# Step 2: Use the index for analysis
analyze_architecture:
  input: STDIN
  model: claude-code
  action: |
    Here is the codebase index:
    $MY_PROJECT_INDEX

    Analyze the architecture and suggest improvements.
  output: STDOUT
` + "```" + `

**Example: Minimal Usage**
` + "```yaml" + `
index_repo:
  step_type: codebase-index
  codebase_index:
    root: .
` + "```" + `

### Using the Index Registry

Indexes can be pre-captured using ` + "`comanda index capture`" + `, then loaded without regenerating:

**Loading from Registry:**
` + "```yaml" + `
load_index:
  codebase_index:
    use: myproject              # Load from registry
    max_age: 24h                # Warn if stale

load_multiple:
  codebase_index:
    use: [project1, project2]   # Load multiple indexes
    aggregate: true             # Create $AGGREGATED_INDEX
` + "```" + `

**Inline Index References (` + "`${INDEX:name}`" + `):**
` + "```yaml" + `
analyze:
  input: |
    Context: ${INDEX:myproject}
    Review the architecture.
  model: claude
  output: STDOUT
` + "```" + `


## 7. qmd Search Step Definition (` + "`qmd_search`" + `)

This step searches local knowledge bases using qmd, providing BM25, vector, or hybrid search capabilities.

**When to use qmd-search:**
- Retrieval-Augmented Generation (RAG) workflows
- Searching indexed codebases or documentation
- Finding relevant context before LLM processing

**Prerequisites:**
- Install qmd: ` + "`bun install -g @tobilu/qmd`" + `
- Create a collection: ` + "`qmd collection add ./docs --name docs`" + `

**Structure:**
` + "```yaml" + `
step_name:
  type: qmd-search
  qmd_search:
    query: "${QUESTION}"      # Search query (supports variable substitution)
    collection: docs          # Optional: restrict to specific collection
    mode: search              # search (BM25), vsearch (vector), query (hybrid)
    limit: 5                  # Number of results (default: 5)
    min_score: 0.3            # Minimum relevance score (0.0-1.0)
    format: text              # Output format: text (default), json, files
  output: CONTEXT             # Store results in variable
` + "```" + `

**` + "`qmd_search`" + ` Block Attributes:**
- ` + "`query`" + `: (string, required) Search query. Supports variable substitution (e.g., ` + "`${QUESTION}`" + `).
- ` + "`collection`" + `: (string, optional) Restrict search to a specific qmd collection.
- ` + "`mode`" + `: (string, default: ` + "`search`" + `) Search mode:
  - ` + "`search`" + `: BM25 keyword search (fastest, recommended default)
  - ` + "`vsearch`" + `: Vector/semantic search (slower, requires embeddings)
  - ` + "`query`" + `: Hybrid search with LLM reranking (slowest, best quality)
- ` + "`limit`" + `: (int, default: 5) Maximum number of results to return.
- ` + "`min_score`" + `: (float, optional) Minimum relevance score threshold (0.0-1.0).
- ` + "`format`" + `: (string, default: ` + "`text`" + `) Output format:
  - ` + "`text`" + `: Human-readable text output
  - ` + "`json`" + `: Structured JSON output
  - ` + "`files`" + `: List of matching file paths only
- ` + "`full`" + `: (bool, default: false) Return full document content instead of snippets.

**Example: RAG Workflow**
` + "```yaml" + `
# Search for relevant context
retrieve_context:
  type: qmd-search
  qmd_search:
    query: "${USER_QUESTION}"
    collection: docs
    mode: search
    limit: 5
  output: CONTEXT

# Generate answer with context
generate_answer:
  input: |
    Context:
    ${CONTEXT}
    
    Question: ${USER_QUESTION}
  model: claude-sonnet
  action: "Answer the question using only the provided context."
  output: STDOUT
` + "```" + `

**Example: Code Search with codebase-index**
` + "```yaml" + `
# Index codebase with qmd registration
index_code:
  type: codebase-index
  codebase_index:
    root: ./src
    qmd:
      collection: mycode
      context: "Application source code"

# Search the indexed code
find_relevant_code:
  type: qmd-search
  qmd_search:
    query: "authentication middleware"
    collection: mycode
    limit: 10
  output: RELEVANT_CODE

# Analyze with LLM
analyze_code:
  input: ${RELEVANT_CODE}
  model: claude-code
  action: "Analyze these code snippets and suggest improvements."
  output: STDOUT
` + "```" + `

## Common Elements (for Standard Steps)

### Input Types
- File path: ` + "`input: path/to/file.txt`" + `
- Previous step output: ` + "`input: STDIN`" + `
- Multiple file paths: ` + "`input: [file1.txt, file2.txt]`" + `
- Web scraping: ` + "`input: { url: \"https://example.com\" }`" + ` (Further scrape config under ` + "`scrape_config`" + ` map if needed)
- Database query: ` + "`input: { database: { type: \"postgres\", query: \"SELECT * FROM users\" } }`" + `
- No input: ` + "`input: NA`" + `
- Input with alias for variable: ` + "`input: path/to/file.txt as $my_var`" + `
- List with aliases: ` + "`input: [file1.txt as $file1_content, file2.txt as $file2_content]`" + `

### Chunking
For processing large files, you can use the ` + "`chunk`" + ` configuration to split the input into manageable pieces:

**Basic Structure:**
` + "```yaml" + `
step_name:
  input: "large_file.txt"
  chunk:
    by: lines  # or "tokens"
    size: 1000  # number of lines or tokens per chunk
    overlap: 50  # optional: number of lines or tokens to overlap between chunks
    max_chunks: 10  # optional: limit the total number of chunks processed
  batch_mode: individual  # required for chunking to process each chunk separately
  model: gpt-4o-mini
  action: "Process this chunk of text: {{ current_chunk }}"
  output: "chunk_{{ chunk_index }}_result.txt"  # can use chunk_index in output path
` + "```" + `

**Key Elements:**
- ` + "`chunk`" + `: (Optional) Configuration block for chunking a large input file.
  - ` + "`by`" + `: (Required) Chunking method - either ` + "`lines`" + ` or ` + "`tokens`" + `.
  - ` + "`size`" + `: (Required) Number of lines or tokens per chunk.
  - ` + "`overlap`" + `: (Optional) Number of lines or tokens to include from the previous chunk, providing context continuity.
  - ` + "`max_chunks`" + `: (Optional) Maximum number of chunks to process, useful for testing or limiting processing.
- ` + "`batch_mode: individual`" + `: Required when using chunking to process each chunk as a separate LLM call.
- ` + "`{{ current_chunk }}`" + `: Template variable that gets replaced with the current chunk content in the action.
- ` + "`{{ chunk_index }}`" + `: Template variable for the current chunk number (0-based), useful in output paths.

**Consolidation Pattern:**
A common pattern is to process chunks individually and then consolidate the results:

` + "```yaml" + `
# Step 1: Process chunks
process_chunks:
  input: "large_document.txt"
  chunk:
    by: lines
    size: 1000
  batch_mode: individual
  model: gpt-4o-mini
  action: "Extract key points from: {{ current_chunk }}"
  output: "chunk_{{ chunk_index }}_summary.txt"

# Step 2: Consolidate results
consolidate_results:
  input: "chunk_*.txt"  # Use wildcard to collect all chunk outputs
  model: gpt-4o-mini
  action: "Combine these summaries into one coherent document."
  output: "final_summary.txt"
` + "```" + `

### Models
- Single model: ` + "`model: gpt-4o-mini`" + `
- No model (for non-LLM operations): ` + "`model: NA`" + `
- Multiple models (for comparison): ` + "`model: [gpt-4o-mini, claude-3-opus-20240229]`" + `

### Actions
- Single instruction: ` + "`action: \"Summarize this text.\"`" + `
- Multiple sequential instructions: ` + "`action: [\"Action 1\", \"Action 2\"]`" + `
- Reference variable: ` + "`action: \"Compare with $previous_data.\"`" + `
- Reference markdown file: ` + "`action: path/to/prompt.md`" + `

### Outputs
- Console: ` + "`output: STDOUT`" + `
- File: ` + "`output: results.txt`" + ` or ` + "`output: ./path/to/output.md`" + `
- Database: ` + "`output: { database: { type: \"postgres\", table: \"results_table\" } }`" + `
- Output with alias (if supported for variable creation from output): ` + "`output: STDOUT as $step_output_var`" + `

**⚠️ IMPORTANT: Writing to files**
When the result should be saved to a file, use the ` + "`output:`" + ` field directly. Do NOT instruct the LLM to "write to a file" in the action.

✅ **CORRECT** - Use ` + "`output:`" + ` for file writing:
` + "```yaml" + `
summarize_document:
  input: report.txt
  model: claude-code
  action: "Summarize this document"
  output: ./summary.md
` + "```" + `

❌ **WRONG** - Do NOT tell the LLM to write the file:
` + "```yaml" + `
summarize_document:
  input: report.txt
  model: claude-code
  action: "Summarize this document and write it to ./summary.md"
  output: STDOUT
` + "```" + `

## Variables
- Definition: ` + "`input: data.txt as $initial_data`" + `
- Reference: ` + "`action: \"Compare this analysis with $initial_data\"`" + `
- Scope: Variables are typically scoped to the workflow. For ` + "`process`" + ` steps, parent variables are not directly accessible by default; use the ` + "`process.inputs`" + ` map to pass data.

## Validation Rules Summary (for LLM)

1.  A step definition must clearly be one of: Standard, Generate, or Process.
    *   A step cannot mix top-level keys from different types (e.g., a ` + "`generate`" + ` step should not have a top-level ` + "`model`" + ` or ` + "`output`" + ` key; these belong inside the ` + "`generate`" + ` block).
2.  **Standard Step:**
    *   Must contain ` + "`input`" + `, ` + "`model`" + `, ` + "`action`" + `, ` + "`output`" + ` (unless ` + "`type: openai-responses`" + `, where ` + "`action`" + ` might be replaced by ` + "`instructions`" + `).
    *   ` + "`input`" + ` can be ` + "`NA`" + `. ` + "`model`" + ` can be ` + "`NA`" + `.
3.  **Generate Step:**
    *   Must contain a ` + "`generate`" + ` block.
    *   ` + "`generate`" + ` block must contain ` + "`action`" + ` (string prompt) and ` + "`output`" + ` (string filename).
    *   ` + "`generate.model`" + ` is optional (uses default if omitted).
    *   Top-level ` + "`input`" + ` for the step is optional (can be ` + "`NA`" + ` or provide context).
4.  **Process Step:**
    *   Must contain a ` + "`process`" + ` block.
    *   ` + "`process`" + ` block must contain ` + "`workflow_file`" + ` (string path).
    *   ` + "`process.inputs`" + ` is optional.
    *   Top-level ` + "`input`" + ` for the step is optional (can be ` + "`NA`" + ` or ` + "`STDIN`" + ` to pipe to sub-workflow).
5.  **Agentic Loop Step (Inline):**
    *   Must contain an ` + "`agentic_loop`" + ` block with loop configuration.
    *   Must also contain ` + "`input`" + `, ` + "`model`" + `, ` + "`action`" + `, ` + "`output`" + ` at the step level.
    *   ` + "`agentic_loop.max_iterations`" + ` defaults to 10 if not specified.
    *   ` + "`agentic_loop.exit_condition`" + ` can be ` + "`llm_decides`" + ` or ` + "`pattern_match`" + `.
6.  **Agentic Loop Block (Top-level):**
    *   Uses ` + "`agentic-loop:`" + ` as a top-level key (like ` + "`parallel-process:`" + `).
    *   Must contain ` + "`config`" + ` block with loop settings.
    *   Must contain ` + "`steps`" + ` block with one or more sub-steps.
    *   Each sub-step follows standard step structure (` + "`input`" + `, ` + "`model`" + `, ` + "`action`" + `, ` + "`output`" + `).
7.  **Codebase Index Step:**
    *   Must have ` + "`step_type: codebase-index`" + ` OR contain a ` + "`codebase_index`" + ` block.
    *   ` + "`codebase_index.root`" + ` defaults to ` + "`.`" + ` (current directory).
    *   Exports workflow variables: ` + "`<REPO>_INDEX`" + `, ` + "`<REPO>_INDEX_PATH`" + `, ` + "`<REPO>_INDEX_SHA`" + `, ` + "`<REPO>_INDEX_UPDATED`" + `.
    *   Does not require ` + "`input`" + `, ` + "`model`" + `, ` + "`action`" + `, or ` + "`output`" + ` fields.

8.  **qmd Search Step:**
    *   Must have ` + "`type: qmd-search`" + ` OR contain a ` + "`qmd_search`" + ` block.
    *   ` + "`qmd_search.query`" + ` is required.
    *   ` + "`qmd_search.mode`" + ` defaults to ` + "`search`" + ` (BM25).
    *   Does not require ` + "`input`" + `, ` + "`model`" + `, or ` + "`action`" + ` fields.
## Chaining and Examples

Steps can be "chained together" by either passing STDOUT from one step to STDIN of the next step or by writing to a file and then having subsequent steps take this file as input.

**Meta-Processing Example:**
` + "```yaml" + `
gather_requirements:
  input: requirements_document.txt
  model: claude-3-opus-20240229
  action: "Based on the input document, define the core tasks for a data processing workflow. Output as a concise list."
  output: STDOUT

generate_data_workflow:
  input: STDIN # Using output from previous step as context
  generate:
    model: gpt-4o-mini # LLM to generate the workflow
    action: "Generate a Comanda workflow YAML to perform the tasks described in the input. The workflow should read 'raw_data.csv', perform transformations, and save to 'processed_data.csv'."
    output: dynamic_data_processor.yaml # Filename for the generated workflow

execute_data_workflow:
  input: NA # Or potentially STDIN if dynamic_data_processor.yaml's first step expects it
  process:
    workflow_file: dynamic_data_processor.yaml # Execute the generated workflow
    # inputs: { source_file: "override_data.csv" } # Optional: override inputs for the sub-workflow
  output: STDOUT # Log output of the process step itself (e.g., success/failure)
` + "```" + `

### Advanced Chaining: Enabling Independent Analysis with Files

The standard ` + "`STDIN`" + `/` + "`STDOUT`" + ` chain is designed for sequential processing, where each step receives the output of the one immediately before it. However, many workflows require a downstream step to **independently analyze outputs from multiple, potentially non-sequential, upstream steps.**

To enable this, you must use files to store intermediate results. This pattern ensures that each output is preserved and can be accessed directly by any subsequent step, rather than being lost in a pipeline.

**The recommended pattern is:**
1.  Each upstream step saves its result to a distinct file (e.g., ` + "`step1_output.txt`" + `, ` + "`step2_output.txt`" + `).
2.  The downstream step that needs to perform the independent analysis lists these files as its ` + "`input`" + `.

**Example: A 3-Step Workflow with a Final Review**

In this scenario, the third step needs to review the outputs of both the first and second steps independently.

` + "```yaml" + `
# Step 1: Initial analysis
analyze_introductions:
  input: introductions.md
  model: gpt-4o-mini
  action: "Perform a detailed analysis of the introductions document. Focus on key themes, writing style, and effectiveness."
  output: step1_analysis.txt

# Step 2: Quality assessment of the original document
quality_assessment:
  input: introductions.md
  model: gpt-4o-mini
  action: "Perform a quality assessment on the original document. Identify strengths and potential gaps."
  output: step2_qa.txt

# Step 3: Final summary based on both outputs
final_summary:
  input: [step1_analysis.txt, step2_qa.txt]
  model: gpt-4o-mini
  action: "Review the results from the analysis (step1_analysis.txt) and the QA (step2_qa.txt). Provide a comprehensive summary that synthesizes the findings from both."
  output: final_summary.md
` + "```" + `

This file-based approach is the correct way to handle any workflow where a step's logic depends on having discrete access to multiple prior outputs.

## CRITICAL: Workflow Simplicity Guidelines

**ALWAYS prefer the simplest possible workflow.** Over-engineered workflows are harder to debug, maintain, and understand.

**Key principles:**
1. **Minimize steps**: If a task can be done in 1 step, don't use 3. Most tasks need 1-2 steps.
2. **Avoid unnecessary chaining**: Don't chain steps unless the output of one is genuinely needed by the next.
3. **Use direct file I/O**: If you need to read a file and process it, that's ONE step, not three.
4. **Prefer STDIN/STDOUT**: Use simple STDIN/STDOUT chaining over complex file intermediates when sequential processing suffices.
5. **One model per workflow when possible**: Don't use multiple models unless comparing outputs or the task genuinely requires different capabilities.

**Examples of OVER-ENGINEERED workflows (AVOID):**
` + "```yaml" + `
# BAD: Too many steps for a simple task
read_file:
  input: document.txt
  model: NA
  action: NA
  output: temp_content.txt

analyze_content:
  input: temp_content.txt
  model: gpt-4o-mini
  action: "Analyze this"
  output: temp_analysis.txt

format_output:
  input: temp_analysis.txt
  model: gpt-4o-mini
  action: "Format nicely"
  output: STDOUT
` + "```" + `

**GOOD: Simple and direct:**
` + "```yaml" + `
# GOOD: One step does the job
analyze_document:
  input: document.txt
  model: gpt-4o-mini
  action: "Analyze this document and format the output nicely"
  output: STDOUT
` + "```" + `

**When multiple steps ARE appropriate:**
- Processing different source files independently, then combining results
- Using tool commands to pre-process data before LLM analysis
- Generating a workflow dynamically, then executing it
- Tasks that genuinely require different models for different capabilities
- **Agentic loops** for iterative refinement, planning, or autonomous decision-making

**When to use Agentic Loops:**
- Code improvement cycles (analyze → fix → verify)
- Planning and execution workflows
- Tasks where quality depends on iteration
- When the LLM should decide when work is complete

This guide covers the core concepts and syntax of Comanda's YAML DSL, including meta-processing capabilities. LLMs should use this structure to generate valid workflow files.`

const PromptPrefix = "" /* 234-byte string literal not displayed */