Workflow Schema Reference

Workflow Schema Reference

Workflows are defined as workflow.json files. They live in the local registry at ~/.config/athena/workflows/<n>/workflow.json after installation.

Full Schema

{
  "name": "e2e-test-builder",
  "version": "1.0.0",
  "description": "Automatically discover and generate end-to-end tests.",
  "plugins": [
    "e2e-test-builder@lespaceman/athena-workflow-marketplace",
    "site-knowledge@lespaceman/athena-workflow-marketplace"
  ],
  "promptTemplate": "Add comprehensive Playwright E2E tests for this codebase. Begin by analyzing existing test conventions, then identify untested user flows, implement tests for each, and run them to confirm they pass.",
  "systemPromptFile": "./system-prompt.md",
  "loop": {
    "enabled": true,
    "completionMarker": "ATHENA_COMPLETE",
    "maxIterations": 10,
    "blockedMarker": "ATHENA_BLOCKED",
    "trackerPath": ".athena-tracker.json",
    "continuePrompt": "Continue from where you left off. Tracker: {trackerPath}"
  },
  "isolation": "minimal",
  "model": "claude-opus-4-5",
  "env": {
    "PLAYWRIGHT_BROWSERS_PATH": "0"
  }
}

Field Reference

name

Type: string — Required

The workflow's unique identifier. Used in --workflow flags and config files.

version

Type: string — Recommended

Semver version string. Shown in the header and marketplace listings.

description

Type: string — Optional

Human-readable description shown in marketplace listings.

plugins

Type: string[] — Optional

Plugin references to load when the workflow activates. Each entry is a local directory path or a marketplace ref (name@owner/repo). These are merged with plugins from config files and --plugin flags.

{
  "plugins": [
    "e2e-test-builder@lespaceman/athena-workflow-marketplace",
    "./local-helpers"
  ]
}

promptTemplate

Type: string — Required (unless systemPromptFile covers the task)

The initial prompt injected into the session when the workflow starts. This is a single string — the full prompt, not a template with variables. Sent as the user message to kick off the task.

systemPromptFile

Type: string — Optional

A relative path (from the workflow directory) to a markdown file used as the system prompt for the session.

loop

Type: object — Optional

Configures iterative execution. If omitted, the workflow runs once.

FieldTypeRequiredDescription
enabledbooleanYesWhether looping is active
completionMarkerstringYesString Claude must output to signal task completion
maxIterationsnumberYesMaximum number of loop iterations before stopping
blockedMarkerstringNoString Claude outputs to signal it is blocked and cannot proceed
trackerPathstringNoRelative path (from project root) to a tracker file
continuePromptstringNoPrompt for iterations 2+. Supports {trackerPath} interpolation

The loop runs until Claude outputs completionMarker, outputs blockedMarker, or maxIterations is reached.

isolation

Type: "strict" | "minimal" | "permissive" — Optional

The isolation preset for sessions using this workflow. If the workflow requires a more permissive level than the user's current preset, Athena upgrades it with a warning.

model

Type: string — Optional

Override the model for this workflow. Accepts short aliases or full model IDs.

env

Type: object — Optional

Environment variables injected into the spawned Claude Code process.

{
  "env": {
    "NODE_ENV": "test",
    "PLAYWRIGHT_BROWSERS_PATH": "0"
  }
}