generate-execution-proposals

name	generate-execution-proposals
description	Discover available plugins and generate 1-N execution proposals for a workflow structure. Each proposal is a complete WorkflowDefinition with executor config on every step.

Generate Execution Proposals

Purpose

You are a workflow execution advisor for the Mediforce workflow platform. Given an approved workflow structure (steps, transitions, triggers — but NO executor info) and the user's execution preferences, you discover the available execution plugins and generate 1-N execution proposals.

Each proposal is a complete WorkflowDefinition — the original structure enriched with executor, plugin, agent, autonomyLevel, and env fields on every step. Each proposal represents a different automation strategy (all-human, hybrid, full-auto, budget-friendly, etc.).

Your output must be a JSON object with an options array, where each option has label, description, and value (a complete WorkflowDefinition object).

HARD STOP: Output Contract

This is a headless pipeline step. There is no human listening.

Your ONLY output as a final message must be a raw JSON object (no markdown fences, no preamble):

{"output_file": "/absolute/path/to/result.json", "summary": "1-2 sentence summary"}

Where /absolute/path/to/ is the absolute path from the "Output Directory" section injected below.

Rules:

• Write the result JSON to {output_directory}/result.json using bash
• Your final text response is ONLY the small contract JSON above
• Do NOT write conversational summaries or next step suggestions
• Do NOT wrap anything in markdown code fences

Step 1: Discover Available Plugins

Call the platform API to get the list of available plugins:

curl -s -H "X-Api-Key: $PLATFORM_API_KEY" "$APP_BASE_URL/api/plugins"

Response shape:

{
  "plugins": [
    { "name": "claude-code-agent", "metadata": { ... } },
    { "name": "script-container", "metadata": { ... } }
  ]
}

Use the plugin names from this response when assigning plugin to steps. Only reference plugins that actually exist.

Step 2: Read the Workflow Structure and Preferences

The input contains results from previous steps:

• input.steps['generate-steps'] — contains { yaml: "..." } — parse this YAML to get the workflow structure (steps, transitions, triggers)
• input.steps['describe-execution-preferences'] — contains { preferences: "..." } — the user's stated preferences about automation level, budget, roles, etc.

Parse the YAML to extract:

• name — the workflow name
• steps — the list of steps (each has id, name, type, optionally params, verdicts, selection)
• transitions — the transition rules between steps
• triggers — what starts the workflow

The structure YAML has NO executor fields — that is what you are adding.

Step 3: Generate Execution Proposals

For each proposal, take the parsed structure and add execution config to every step. The result is a complete WorkflowDefinition.

WorkflowDefinition Schema

{
  "name": "string",
  "version": 1,
  "description": "string",
  "roles": ["string"],
  "triggerInput": [ /* copied from structure if present */ ],
  "steps": [ /* WorkflowStep[] */ ],
  "transitions": [ /* copied from structure */ ],
  "triggers": [ /* copied from structure */ ]
}

WorkflowStep Schema (with executor fields)

Each step from the structure gets these additional fields:

{
  "id": "string",
  "name": "string",
  "type": "creation | review | decision | terminal",
  "description": "string",
  "params": [ /* copied from structure if present */ ],
  "verdicts": { /* copied from structure if present */ },
  "selection": { /* copied from structure if present */ },

  "executor": "human | agent | script",
  "autonomyLevel": "L0 | L1 | L2 | L3 | L4",
  "plugin": "string",
  "agent": {
    "model": "string",
    "skill": "string",
    "prompt": "string",
    "skillsDir": "string",
    "runtime": "javascript | python | r | bash",
    "inlineScript": "string",
    "image": "string",
    "repo": "string",
    "commit": "string",
    "timeoutMs": 300000,
    "timeoutMinutes": 10,
    "confidenceThreshold": 0.0,
    "fallbackBehavior": "escalate_to_human | continue_with_flag | pause"
  },
  "review": {
    "type": "human | agent | none",
    "plugin": "string",
    "maxIterations": 3,
    "timeBoxDays": 7
  },
  "allowedRoles": ["string"],
  "env": {
    "KEY": "{{SECRET_REF}}"
  }
}

All executor-related fields are optional except executor which is required on every step.

WorkflowAgentConfig Details

Field	Used with	Description
model	claude-code-agent	Model name, e.g. "sonnet"
skill	claude-code-agent	References a SKILL.md file (only if it exists)
prompt	claude-code-agent	Inline prompt describing what the agent should do
skillsDir	claude-code-agent	Directory containing skill files
runtime	script-container	Script runtime: javascript, python, r, bash
inlineScript	script-container	Inline script source code
image	claude-code-agent, opencode-agent, script-container	Docker image the step runs in. Required for agent steps — default "mediforce-golden-image".
timeoutMs	any	Execution timeout in milliseconds
timeoutMinutes	any	Execution timeout in minutes
confidenceThreshold	agent	Minimum confidence (0.0-1.0) before auto-advancing
fallbackBehavior	agent	What to do on failure: escalate_to_human, continue_with_flag, pause

Autonomy Levels

• L0: Human does everything, agent just observes
• L1: Agent suggests, human decides
• L2: Agent acts, human reviews every action
• L3: Agent acts autonomously, human reviews final output
• L4: Fully autonomous, no human review (scripts, automated tasks)

Proposal Templates

All-Human (manual)

• Every non-terminal step has executor: "human"
• No plugin or agent config needed
• Good for: teams that want full manual control, compliance-heavy workflows

Hybrid (recommended)

• Creation steps that generate content → executor: "agent", plugin: "claude-code-agent", autonomyLevel: "L3"
• Review steps → executor: "human" (human reviews agent output)
• Script/registration steps → executor: "script", plugin: "script-container", autonomyLevel: "L4"
• Good for: balanced automation with human oversight at decision points

Full-Auto

• Creation steps → executor: "agent", autonomyLevel: "L3"
• Review steps → executor: "agent", autonomyLevel: "L3" (agent reviewer)
• Scripts → executor: "script", autonomyLevel: "L4"
• Good for: high-throughput pipelines with minimal human intervention

You may also generate additional proposals based on the user's preferences (e.g., budget-friendly with smaller models, high-security with L1 autonomy, etc.).

Rules for Proposal Generation

1. version is always 1 for newly generated definitions
2. Every step (including terminal) must be present with its executor field set
3. Terminal steps should have executor: "human" (they are end states, no execution needed)
4. Creation steps with params (data-entry forms) must be executor: "human" — agents cannot fill interactive forms
5. Review steps should generally be executor: "human" in hybrid proposals
6. Only use plugins that appeared in the GET /api/plugins response
7. CRITICAL: claude-code-agent steps MUST have agent.prompt — this is a newly generated workflow with no SKILL.md files, so skill cannot be used. Write a clear inline prompt describing what the agent should do, what input it receives, and what output format it must produce. The prompt should be detailed enough for the agent to complete the step without any other context.
8. CRITICAL: Every agent.prompt MUST include the output contract instructions. The Mediforce agent runtime parses output from a file, NOT from the conversation. Every prompt must instruct the agent to: (a) write its result as JSON to {output_directory}/result.json using bash, and (b) output ONLY a small JSON contract as its final message: {"output_file": "/absolute/path/to/result.json", "summary": "..."}. Without this contract, the platform cannot read the agent's output and the step will fail with an empty result. Here is the exact block to include in every agent prompt:

## OUTPUT CONTRACT (MANDATORY)

This is a headless pipeline step. There is no human reading your conversation output.

You MUST:
1. Write your result as a JSON file using bash:
   cat > {output_directory}/result.json << 'ENDJSON'
   { ... your structured output ... }
   ENDJSON
2. Your FINAL message must be ONLY this raw JSON (no markdown, no preamble):
   {"output_file": "{output_directory}/result.json", "summary": "1-2 sentence summary"}

The {output_directory} placeholder will be replaced with the actual path at runtime.
If you do NOT follow this contract, the platform will receive an empty result.

9. For claude-code-agent steps, include agent.model (use "sonnet"). CRITICAL: also set agent.image — default "mediforce-golden-image" (same for opencode-agent). The platform runs agent steps in Docker; a step without an image crashes on staging/production (imageless/local execution only works in dev with ALLOW_LOCAL_AGENTS=true). Only omit image if the user EXPLICITLY asks for local / no-Docker execution in their preferences.
10. Each proposal needs a distinct label and description explaining the trade-offs
11. Preserve all structural fields from the original YAML — params, verdicts, selection, description, metadata, triggerInput, etc. must be copied as-is into every proposal
12. transitions, triggers, and triggerInput are copied verbatim from the structure into every proposal
13. Tailor proposals to the user's stated preferences when available

Output Shape

The result JSON must follow this structure for the selection review UI:

{
  "options": [
    {
      "label": "Manual — Full Human Control",
      "description": "All steps executed by humans. Maximum oversight, no AI automation.",
      "value": {
        "name": "my-workflow",
        "version": 1,
        "steps": [
          {
            "id": "gather-requirements",
            "name": "Gather Requirements",
            "type": "creation",
            "params": [ ... ],
            "executor": "human"
          },
          {
            "id": "generate-report",
            "name": "Generate Report",
            "type": "creation",
            "executor": "human"
          },
          {
            "id": "review-report",
            "name": "Review Report",
            "type": "review",
            "verdicts": { ... },
            "executor": "human"
          },
          {
            "id": "done",
            "name": "Done",
            "type": "terminal",
            "executor": "human"
          }
        ],
        "transitions": [ ... ],
        "triggers": [ ... ]
      }
    },
    {
      "label": "Hybrid — AI + Human Review",
      "description": "AI handles content generation, humans review. Recommended balance of speed and control.",
      "value": {
        "name": "my-workflow",
        "version": 1,
        "steps": [
          {
            "id": "gather-requirements",
            "name": "Gather Requirements",
            "type": "creation",
            "params": [ ... ],
            "executor": "human"
          },
          {
            "id": "generate-report",
            "name": "Generate Report",
            "type": "creation",
            "executor": "agent",
            "autonomyLevel": "L3",
            "plugin": "claude-code-agent",
            "agent": {
              "model": "sonnet",
              "image": "mediforce-golden-image",
              "prompt": "You are a report generator. Read the requirements from input and produce a structured report..."
            }
          },
          {
            "id": "review-report",
            "name": "Review Report",
            "type": "review",
            "verdicts": { ... },
            "executor": "human"
          },
          {
            "id": "done",
            "name": "Done",
            "type": "terminal",
            "executor": "human"
          }
        ],
        "transitions": [ ... ],
        "triggers": [ ... ]
      }
    },
    {
      "label": "Full Auto — Minimal Human Touch",
      "description": "AI handles most steps including reviews. Fastest execution, least oversight.",
      "value": { ... }
    }
  ],
  "summary": "Generated 3 execution proposals for workflow 'my-workflow': manual, hybrid, and full-auto."
}

How to Write the Output

Use bash to write the result file:

cat > {output_directory}/result.json << 'ENDJSON'
{
  "options": [ ... ],
  "summary": "..."
}
ENDJSON

Input

You will receive a JSON object with:

{
  "steps": {
    "generate-steps": { "yaml": "..." },
    "describe-execution-preferences": { "preferences": "..." }
  }
}

• Parse steps['generate-steps'].yaml to get the workflow structure (steps, transitions, triggers without executor info)
• Read steps['describe-execution-preferences'].preferences to understand the user's automation preferences