What is a Workflow

What is a Workflow

A workflow is a reusable definition for how Athena orchestrates a Claude Code session around a specific task. Where a plugin adds capabilities (skills, MCP tools), a workflow defines the shape of a session — what the agent should do, with what prompt template, using which plugins, under which isolation level, and whether to loop.

What Workflows Define

A workflow.json can specify:

  • Prompt template — A single string injected as the initial prompt, priming Claude for the task
  • System prompt file — A path to a markdown file used as the system prompt
  • Plugin references — Which plugins to load when the workflow activates, so you don't need --plugin flags manually
  • Isolation preset — The default isolation level for sessions running this workflow (upgraded from the user's setting if the workflow requires more permissive access)
  • Loop configuration — Whether the agent runs once or loops until a completion marker is detected
  • Model override — A specific model to use for this workflow
  • Environment variables — Env vars injected into the spawned Claude process

Example Use Cases

End-to-end test generation — A workflow that primes Claude to discover testable surfaces, generate Playwright tests, run them, and iterate until they pass. The workflow bundles the e2e-test-builder plugin and configures a loop with a completion marker.

Pull request review — A workflow with a focused prompt template and no loop. Single-shot execution.

Dependency audit — A workflow that processes each dependency file and generates a report. Loop-based, terminates when the completion marker appears in Claude's output.

Activating a Workflow

Workflows must be installed into the local registry before they can be activated. See Marketplace Resolution for installation.

CLI flag (by name):

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

Project config:

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

When a workflow is active, it:

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

Workflow Discovery from Plugins

If a loaded plugin directory contains a workflow.json at its root, Athena auto-discovers it. If exactly one workflow is discovered across all loaded plugins and no --workflow flag is set, it activates automatically. If multiple are discovered, Athena warns and requires an explicit --workflow selection.