Overview

A workflow defines the shape of an agent session — what the agent should do, with which prompt, using which plugins, under which isolation level, and whether to loop.

What a Workflow Bundles

ComponentPurpose
promptTemplateInitial prompt injected into the session
systemPromptFileMarkdown file used as the system prompt
plugins[]Plugin references auto-loaded on activation
loopIterative execution config (completion markers, max iterations)
isolationPermission preset for the session
modelModel override
envEnvironment variables for the agent process

Activating a Workflow

Install first (see Marketplace), then activate:

athena-flow --workflow=e2e-test-builder

Or set it in your project config:

{
  "workflow": "e2e-test-builder"
}

When a workflow activates, it:

  1. Auto-loads its declared plugins[]
  2. Applies its isolation preset (upgrading from yours if needed, with a warning)
  3. Injects promptTemplate and systemPromptFile
  4. Runs loop logic if loop.enabled

Plugin Bundles

Workflows declare plugin dependencies in plugins[]:

{
  "plugins": [
    "e2e-test-builder@lespaceman/athena-workflow-marketplace",
    "site-knowledge@lespaceman/athena-workflow-marketplace"
  ]
}

These are resolved exactly like --plugin flags. Duplicates with config/CLI plugins are deduplicated.

Plugin Load Order

  1. Workflow plugins[]
  2. Global config plugins[]
  3. Project config plugins[]
  4. --plugin CLI flags

Later entries win on name conflicts.

Workflow Discovery

If a loaded plugin directory contains a workflow.json at its root, Athena auto-discovers it. If exactly one workflow is discovered and no --workflow flag is set, it activates automatically. Multiple discovered workflows require an explicit --workflow selection.