Marketplace Resolution

Workflows and plugins are distributed through marketplace repositories — GitHub repos with a defined directory structure and catalog files. The primary marketplace is lespaceman/athena-workflow-marketplace.

Local Workflow Registry

Workflows must be installed into Athena's local registry before use. The registry lives at:

~/.config/athena/workflows/
  e2e-test-builder/
    workflow.json
  pr-review/
    workflow.json

When you run --workflow=e2e-test-builder, Athena looks up ~/.config/athena/workflows/e2e-test-builder/workflow.json.

Installing a Workflow

athena workflow install e2e-test-builder@lespaceman/athena-workflow-marketplace --name e2e-test-builder

This causes Athena to:

1. Clone lespaceman/athena-workflow-marketplace into ~/.config/athena/marketplaces/lespaceman/athena-workflow-marketplace/ (first use only; cached thereafter)
2. Read .athena-workflow/marketplace.json to find e2e-test-builder
3. Copy the workflow definition to ~/.config/athena/workflows/e2e-test-builder/workflow.json

You can then reference it as:

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

Marketplace Repository Structure

athena-workflow-marketplace/
  .claude-plugin/
    marketplace.json          # Plugin catalog
  .athena-workflow/
    marketplace.json          # Workflow catalog
  .workflows/
    e2e-test-builder/
      workflow.json
      system-prompt.md
  plugins/
    e2e-test-builder/
      .claude-plugin/
        plugin.json
      skills/
        add-e2e-tests/
          SKILL.md
    site-knowledge/
      .claude-plugin/
        plugin.json
      skills/
        ...

The Two Catalogs

A marketplace repo contains two separate catalog files serving different resolution paths:

Plugin Catalog: .claude-plugin/marketplace.json

Consumed by Athena's plugin loader when resolving name@owner/repo plugin refs.

{
  "name": "athena-workflow-marketplace",
  "owner": {"name": "lespaceman"},
  "metadata": {
    "pluginRoot": "./plugins"
  },
  "plugins": [
    {
      "name": "e2e-test-builder",
      "source": "e2e-test-builder",
      "description": "Playwright E2E test workflow runner"
    },
    {
      "name": "site-knowledge",
      "source": "site-knowledge",
      "description": "Site-specific automation patterns"
    }
  ]
}

With pluginRoot: "./plugins", the source value is a subdirectory name under ./plugins/. Without pluginRoot, it's a relative path from the repo root.

Workflow Catalog: .athena-workflow/marketplace.json

Consumed by the workflow installer when resolving workflow refs.

{
  "workflows": [
    {
      "name": "e2e-test-builder",
      "source": "./.workflows/e2e-test-builder/workflow.json",
      "description": "Iterative E2E test generation workflow"
    }
  ]
}

Marketplace Caching

Marketplace repos are cloned to ~/.config/athena/marketplaces/<owner>/<repo>/. Athena pulls the latest on subsequent uses. If the network is unavailable, the cached version is used (graceful degradation).

Plugin Resolution from Config

Plugins are resolved at runtime (not pre-installed). When your config references e2e-test-builder@lespaceman/athena-workflow-marketplace, Athena:

1. Checks ~/.config/athena/marketplaces/lespaceman/athena-workflow-marketplace/ (cloning if needed)
2. Reads .claude-plugin/marketplace.json
3. Finds the e2e-test-builder entry and resolves source relative to pluginRoot
4. Loads the plugin from the resolved directory

Adding a New Workflow to the Marketplace

1. Create .workflows/<name>/workflow.json in the marketplace repo
2. Register it in .athena-workflow/marketplace.json
3. If the workflow needs a plugin, add the plugin under plugins/ and register it in .claude-plugin/marketplace.json

{
  "workflows": [
    {
      "name": "my-workflow",
      "source": "./.workflows/my-workflow/workflow.json",
      "description": "My reusable workflow"
    }
  ]
}