athena

Workflow orchestrator for AI coding agents.
Active multi-agent coordination with enforced discipline — not passive prompts.

Supported harnesses: Claude Code · Cursor · Codex · Gemini CLI · OpenCode · Copilot CLI

---

What's Different

Most workflow plugins inject text that suggests what to do. Athena enforces it:

• SessionStart bootstrap — athena-init is injected as additional context at session boot (Claude Code, Cursor, OpenCode), or loaded as a context file (Gemini CLI, Codex). The framework is in the model's eyes from message 1.
• Per-task two-stage review — every task runs implementer → spec-reviewer → code-quality-reviewer. Catches gaps while the diff is small.
• Status-code protocol — workers report exactly one of DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED. The coordinator branches on it; no silent failures.
• Model-tier dispatch — cheap for mechanical implementers, standard for integration, most-capable for design/debug. Cost-aware by default.
• Continuous execution — no "should I continue?" check-ins between tasks. Stops only on unresolvable BLOCKED, 3 failed wave fixes, genuine ambiguity, or all done.
• Wave verification gates — full test suite per wave, max 3 fix attempts, then "wave stuck" playbook.
• Pipeline state tracking — .athena-state.json survives context compression; atomic write-to-temp-then-rename; corruption auto-backed-up and reset.
• Scientific debugging — hypotheses tracked, evidence required, no guess-and-check.
• Enforced TDD — test must fail before implementing, pass before refactoring.
• Recovery playbooks — actionable next steps when gates fail.
• Pause/resume/reset — disable Athena temporarily, re-enable without losing state.

Install

Claude Code

claude plugin marketplace add bencrooks-dev/athena
claude plugin install athena

Then install the auto-trigger hooks (recommended):

node hooks/install.cjs

This wires three hooks into ~/.claude/settings.json:

• SessionStart — injects athena-init as additionalContext at session boot (the strongest enforcement vector)
• PostToolUse — nudges toward the right skill after tests pass, review feedback, merge conflicts, new source files, plan reads, and edit bursts
• PreToolUse — backs up athena-init's "check before acting" rule on action tools (Edit/Write/Bash)

All three hooks respect /athena-pause — they exit early when Athena is paused.

Declarative alternative: Claude Code also reads hooks/hooks.json from the plugin root, which wires the same three hooks via ${CLAUDE_PLUGIN_ROOT}.

Cursor

git clone https://github.com/bencrooks-dev/athena.git ~/.cursor/athena
mkdir -p ~/.cursor/skills
ln -s ~/.cursor/athena/skills ~/.cursor/skills/athena

Restart Cursor. Skills are discovered via SKILL.md frontmatter; hooks/hooks-cursor.json wires SessionStart, PreToolUse, and PostToolUse. Full Windows/PowerShell instructions, update, and uninstall: see docs/platforms/cursor.md.

Codex (CLI and App)

git clone https://github.com/bencrooks-dev/athena.git ~/.codex/athena
mkdir -p ~/.agents/skills
ln -s ~/.codex/athena/skills ~/.agents/skills/athena

Enable multi-agent support in ~/.codex/config.toml so Athena's build flow can dispatch subagents:

[features]
multi_agent = true

Full reference: docs/platforms/codex.md. Tool-name mapping: skills/athena-init/references/codex-tools.md.

Gemini CLI

Gemini reads gemini-extension.json at the repo root, which points at GEMINI.md as the session-load context file. Activate athena-init first via activate_skill; subsequent skills load on demand.

See skills/athena-init/references/gemini-tools.md for the tool-name mapping (@generalist for subagent dispatch).

OpenCode

Add Athena to the plugin array in your opencode.json:

{
  "plugin": ["athena@git+https://github.com/bencrooks-dev/athena.git"]
}

Restart OpenCode. The plugin (.opencode/plugins/athena.js) auto-registers the skills directory and injects athena-init as the session bootstrap context. See .opencode/INSTALL.md for details.

GitHub Copilot CLI

Copilot CLI auto-loads AGENTS.md. See skills/athena-init/references/copilot-tools.md for the tool-name mapping (task for subagent dispatch, async shells for long-running test suites).

Commands

/athena — Smart Router

Detects what you need from natural language and routes to the right workflow. Just describe what you're doing: