Custom Workflow from Scratch

Build a workflow definition, test it locally, and optionally publish it.

1. Create the Workflow File

// workflow.json
{
  "name": "dependency-audit",
  "version": "1.0.0",
  "description": "Audit project dependencies for issues.",
  "promptTemplate": "Audit all dependencies in this project. Check for outdated packages, known vulnerabilities, and unused dependencies. Output a structured report.",
  "plugins": [],
  "isolation": "strict",
  "model": "sonnet"
}

2. Add a Loop (Optional)

For iterative tasks, add loop configuration:

{
  "name": "dependency-audit",
  "version": "1.0.0",
  "description": "Audit project dependencies for issues.",
  "promptTemplate": "Audit all dependencies in this project.",
  "loop": {
    "enabled": true,
    "completionMarker": "ATHENA_COMPLETE",
    "maxIterations": 5,
    "blockedMarker": "ATHENA_BLOCKED",
    "trackerPath": ".audit-tracker.json",
    "continuePrompt": "Continue the audit. Tracker: {trackerPath}"
  },
  "isolation": "strict"
}

3. Bundle Plugins

Reference marketplace or local plugins:

{
  "plugins": [
    "my-plugin@my-org/my-marketplace",
    "./local-helpers"
  ]
}

These auto-load when the workflow activates. MCP configs from all plugins are merged.

4. Add a System Prompt (Optional)

{
  "systemPromptFile": "./system-prompt.md"
}

Create the file relative to the workflow directory.

5. Install Locally

Copy to the local registry:

mkdir -p ~/.config/athena/workflows/dependency-audit
cp workflow.json ~/.config/athena/workflows/dependency-audit/

6. Test

athena-flow --workflow=dependency-audit

Or in exec mode:

athena-flow exec "audit dependencies" --workflow=dependency-audit

7. Publish to a Marketplace

Add the workflow to a marketplace repo:

your-marketplace/
  .athena-workflow/
    marketplace.json
  .workflows/
    dependency-audit/
      workflow.json
      system-prompt.md  # if used

{
  "workflows": [
    {
      "name": "dependency-audit",
      "source": "./.workflows/dependency-audit/workflow.json",
      "description": "Audit project dependencies for issues"
    }
  ]
}

Others install with:

athena workflow install dependency-audit@your-org/your-marketplace --name dependency-audit

Environment Variables

Inject env vars into the agent process:

{
  "env": {
    "NODE_ENV": "test",
    "AUDIT_STRICT": "true"
  }
}