{
  "markdown": "<p align=\"center\">\n  <img src=\"athena-logo.png\" alt=\"Athena\" width=\"420\">\n</p>\n\n<p align=\"center\"><strong>Workflow orchestrator for AI coding agents.</strong><br>\nActive multi-agent coordination with enforced discipline — not passive prompts.</p>\n\n<p align=\"center\">\n  Supported harnesses: <strong>Claude Code · Cursor · Codex · Gemini CLI · OpenCode · Copilot CLI</strong>\n</p>\n\n---\n\n## What's Different\n\nMost workflow plugins inject text that *suggests* what to do. Athena *enforces* it:\n\n- **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.\n- **Per-task two-stage review** — every task runs `implementer → spec-reviewer → code-quality-reviewer`. Catches gaps while the diff is small.\n- **Status-code protocol** — workers report exactly one of `DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED`. The coordinator branches on it; no silent failures.\n- **Model-tier dispatch** — cheap for mechanical implementers, standard for integration, most-capable for design/debug. Cost-aware by default.\n- **Continuous execution** — no \"should I continue?\" check-ins between tasks. Stops only on unresolvable BLOCKED, 3 failed wave fixes, genuine ambiguity, or all done.\n- **Wave verification gates** — full test suite per wave, max 3 fix attempts, then \"wave stuck\" playbook.\n- **Pipeline state tracking** — `.athena-state.json` survives context compression; atomic write-to-temp-then-rename; corruption auto-backed-up and reset.\n- **Scientific debugging** — hypotheses tracked, evidence required, no guess-and-check.\n- **Enforced TDD** — test must fail before implementing, pass before refactoring.\n- **Recovery playbooks** — actionable next steps when gates fail.\n- **Pause/resume/reset** — disable Athena temporarily, re-enable without losing state.\n\n## Install\n\n### Claude Code\n\n```bash\nclaude plugin marketplace add bencrooks-dev/athena\nclaude plugin install athena\n```\n\nThen install the auto-trigger hooks (recommended):\n\n```bash\nnode hooks/install.cjs\n```\n\nThis wires three hooks into `~/.claude/settings.json`:\n- **SessionStart** — injects `athena-init` as additionalContext at session boot (the strongest enforcement vector)\n- **PostToolUse** — nudges toward the right skill after tests pass, review feedback, merge conflicts, new source files, plan reads, and edit bursts\n- **PreToolUse** — backs up `athena-init`'s \"check before acting\" rule on action tools (Edit/Write/Bash)\n\nAll three hooks respect `/athena-pause` — they exit early when Athena is paused.\n\nDeclarative alternative: Claude Code also reads `hooks/hooks.json` from the plugin root, which wires the same three hooks via `${CLAUDE_PLUGIN_ROOT}`.\n\n### Cursor\n\n```bash\ngit clone https://github.com/bencrooks-dev/athena.git ~/.cursor/athena\nmkdir -p ~/.cursor/skills\nln -s ~/.cursor/athena/skills ~/.cursor/skills/athena\n```\n\nRestart 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`](docs/platforms/cursor.md).\n\n### Codex (CLI and App)\n\n```bash\ngit clone https://github.com/bencrooks-dev/athena.git ~/.codex/athena\nmkdir -p ~/.agents/skills\nln -s ~/.codex/athena/skills ~/.agents/skills/athena\n```\n\nEnable multi-agent support in `~/.codex/config.toml` so Athena's build flow can dispatch subagents:\n\n```toml\n[features]\nmulti_agent = true\n```\n\nFull reference: [`docs/platforms/codex.md`](docs/platforms/codex.md). Tool-name mapping: `skills/athena-init/references/codex-tools.md`.\n\n### Gemini CLI\n\nGemini 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.\n\nSee `skills/athena-init/references/gemini-tools.md` for the tool-name mapping (`@generalist` for subagent dispatch).\n\n### OpenCode\n\nAdd Athena to the `plugin` array in your `opencode.json`:\n\n```json\n{\n  \"plugin\": [\"athena@git+https://github.com/bencrooks-dev/athena.git\"]\n}\n```\n\nRestart 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.\n\n### GitHub Copilot CLI\n\nCopilot 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).\n\n## Commands\n\n### `/athena` — Smart Router\n\nDetects what you need from natural language and routes to the right workflow. Just describe what you're doing:\n\n- \"I want to build a...\" → routes to `/athena-brainstorm`\n- \"plan out the auth system\" → routes to `/athena-plan`\n- \"build it\" → routes to `/athena-build`\n- \"this is broken\" → routes to `/athena-debug`\n- \"review the code\" → routes to `/athena-review`\n- \"add tests\" → routes to `/athena-tdd`\n- \"I think it's done\" → routes to `/athena-verify`\n- \"the reviewer said...\" → routes to `/athena-receive-review`\n- \"let's ship\" → routes to `/athena-ship`\n- \"merge it\" / \"create a PR\" → routes to `/athena-finish`\n- \"I need an isolated branch\" → routes to `/athena-worktree`\n- \"create a new skill\" → routes to `/athena-forge`\n- \"pause athena\" → routes to `/athena-pause`\n- \"resume athena\" → routes to `/athena-resume`\n\n**State-aware:** If `.athena-state.json` exists, the router uses pipeline phase to inform routing (e.g., routes to `/athena-build` when a plan exists, or to `/athena-ship` when build is complete).\n\n### `/athena-brainstorm` — Designer\n\nScale-aware idea exploration. Turns ideas into validated designs through focused conversation:\n\n- **Tiny tasks** (config change) → 1 question, verbal approval, done in 2 minutes\n- **Small tasks** (new function) → 2-3 questions, verbal design\n- **Medium tasks** (new module) → 3-5 questions, written spec saved to file\n- **Large tasks** (new system) → full exploration, decomposition, sectioned spec\n\nHard gate: no code until design is approved. But the design scales to the task — no 500-word spec for a config change.\n\n### `/athena-plan` — Architect\n\nExplores requirements, proposes approaches, and generates structured plans with:\n\n- **Wave-based task structure** — which tasks are parallel vs sequential\n- **Dependency graphs** — which tasks block which\n- **Complete code in every step** — no placeholders\n- **Plan IDs and commit tracing** — every commit links back to its plan and task (`[plan:feature-name] [wave:1/task:2]`)\n- **Version management** — replanning archives old versions with `-vN` suffixes\n- **Built to feed `/athena-build`** — the plan format is designed for automated execution\n\n### `/athena-build` — Executor\n\nExecutes plans using the coordinator pattern:\n\n```\nWave 1 ──→ [Agent A] ──→ Synthesize ──→ Verify ──→ Wave 2\n           [Agent B] ──↗                   ↓\n           [Agent C] ──↗              Tests pass?\n                                      No → Fix → Re-verify\n                                      Yes → Next wave\n```\n\n- Parallel agents for independent tasks within each wave\n- Synthesis step reviews all results for integration issues\n- Verification gate: tests must pass before next wave\n- Maximum 3 fix attempts per wave, then escalates to you\n- **Agent timeout handling** — if an agent doesn't respond in 5 minutes, retries with simplified scope, then splits the task\n- **Pipeline state tracking** — updates `.athena-state.json` after each wave (survives context compression)\n- **Recovery playbooks** — actionable next steps for stuck waves, blocked agents, agent timeouts, state corruption, and context compression\n\n### `/athena-debug` — Investigator\n\nScientific method debugging:\n\n```\nObserve → Hypothesize → Predict → Test → Conclude → Fix → Verify\n```\n\n- 2-3 ranked hypotheses with evidence\n- Predictions tested experimentally before acting\n- Checkpoints before fixes (rollback if fix fails)\n- Anti-patterns blocked: no shotgun debugging, no cargo cult fixes\n- **Recovery playbooks** — guidance for all-hypotheses-rejected, fix-causes-regression, and flaky-bug scenarios\n- **State update** — records debug outcome in `.athena-state.json` (clears `build-stuck` on success)\n\n### `/athena-review` — Auditor\n\nTwo-pass review (order matters):\n\n**Pass 1 — Spec Compliance:** Did we build what was asked?\n```\n[DONE]    User authentication\n[DONE]    Password hashing\n[MISSING] Rate limiting — not found in codebase\n```\nFix all MISSING items before Pass 2.\n\n**Pass 2 — Code Quality:** Is it built well?\n```\n[CRITICAL] src/auth.js:42 — SQL injection in query\n[IMPORTANT] src/auth.js:78 — Missing test for error path\n```\n\n### `/athena-tdd` — Test Driver\n\nEnforced red-green-refactor with gates:\n\n| Phase | Gate |\n|-------|------|\n| RED | Write test → must FAIL |\n| GREEN | Write code → test must PASS |\n| REFACTOR | Clean up → all tests must still PASS |\n\nCannot proceed to GREEN without a failing test. Cannot refactor without passing tests. No shortcuts.\n\n### `/athena-verify` — Gatekeeper\n\nStandalone mid-work verification — fires before you claim anything is done, not just at ship time:\n\n```\nVerification\n════════════\n[PASS] Tests: 24/24 passing — full suite output shown\n[PASS] Bug fixed — reproduction case no longer fails\n[FAIL] Feature works — edge case returns wrong result\n\nVerdict: NOT VERIFIED ✗\n```\n\nIncludes regression verification protocol: fix → pass → revert → fail → restore → pass. Records results in `.athena-state.json` so other skills know verification ran.\n\n### `/athena-receive-review` — Responder\n\nHandles incoming code review feedback with technical rigor — not performative agreement:\n\n```\nFeedback Response\n═════════════════\n1. [ACCEPT] src/auth.js:42 — Valid: SQL injection, implementing fix\n2. [REJECT] src/auth.js:78 — Incorrect: reviewer missed the null check on line 76\n3. [DISCUSS] src/utils.js:15 — Subjective: codebase uses pattern Y, not X\n4. [CLARIFY] src/api.js:90 — \"Doesn't look right\" — what specifically?\n```\n\nVerifies each suggestion before implementing. Pushes back on incorrect feedback with evidence. Detects performative agreement patterns in its own responses.\n\n### `/athena-ship` — Launcher\n\nPre-ship verification gate:\n\n```\nShip Checklist\n══════════════\n[PASS] Tests: 24/24 passing\n[PASS] Clean working directory\n[PASS] Branch up to date\n[WARN] 1 console.log in src/utils.js:42\n[PASS] Plan: 5/5 tasks complete\n\nResult: READY TO SHIP\n```\n\nChecks pipeline state before running — warns if build was stuck or Athena is paused. Then choose: create PR, merge locally, push only, or abort.\n\n### `/athena-finish` — Closer\n\nCompletes development branches after ship verification passes:\n\n```\nBranch ready. What would you like to do?\n\n1. Merge to main locally\n2. Push and create a Pull Request\n3. Keep branch as-is (handle later)\n4. Discard this work\n```\n\nPipeline-aware — trusts `/athena-ship`'s verification gates, won't re-run checks. Handles worktree cleanup automatically.\n\n### `/athena-worktree` — Isolator\n\nCreates isolated git worktrees for parallel development:\n\n- **Smart defaults** — uses `.worktrees/` by default, no questions needed\n- **Safety checks** — verifies gitignore (including `.athena-state.json`), runs baseline tests\n- **Auto-setup** — detects project type, installs dependencies\n- **Cross-platform** — works on Windows and Unix\n- **Pipeline integration** — `/athena-finish` cleans up worktrees automatically\n\n### `/athena-forge` — Skill Smith\n\nCreates and refines Claude Code skills using TDD:\n\n```\nRED    — Run pressure scenarios without skill, document failures\nGREEN  — Write minimal skill addressing those specific failures\nREFACTOR — Close loopholes, add rationalization table, re-test\n```\n\nIncludes the exact Athena SKILL.md template, frontmatter rules, style guide, and quality checklist. One skill at a time — deploy and test before writing the next.\n\n### `/athena-canvas` — Visualizer\n\nZero-dependency visual brainstorming. Creates self-contained HTML files during `/athena-brainstorm` for mockups, wireframes, and layout comparisons:\n\n- **No server required** — just HTML files the user opens in their browser\n- **Dark theme, interactive** — click-to-select options, responsive layout\n- **Per-question decision** — only used when visuals help, not every question\n- **Fully offline** — no CDN, no network, works anywhere\n\n### `/athena-pause` — Circuit Breaker\n\nTemporarily disables all Athena workflow enforcement:\n\n- Hooks stop firing, routing stops, gates stop blocking\n- Pipeline state is preserved — nothing is lost\n- Resume with `/athena-resume` when ready\n- Use for quick ad-hoc work that doesn't need ceremony\n\n### `/athena-resume` — Restore\n\nRe-enables Athena after a pause:\n\n- Reports how long Athena was paused\n- Shows current pipeline state (so you know where you left off)\n- Suggests next action based on phase (e.g., \"build completed — run `/athena-ship`\")\n- All routing, gates, and hooks reactivate immediately\n\n### `/athena-init` — Guardian\n\nAuto-activation bootstrapper that ensures Athena skills are considered before every action:\n\n- Routes through `/athena` on every user message\n- Rationalization table blocks common excuses for skipping skill checks\n- Backed by PreToolUse hook for enforcement that survives context compression\n- State-aware — respects paused state, reads pipeline phase\n\n## Pipeline State\n\nAthena tracks pipeline state in `.athena-state.json` at the project root. This file:\n\n- **Survives context compression** — skills read it to reconstruct where they are mid-session\n- **Enables state-aware routing** — the router knows whether you're mid-build, post-verify, or stuck\n- **Prevents redundant work** — `/athena-ship` knows when `/athena-verify` already ran\n- **Supports pause/resume** — state is preserved across pauses\n\n```json\n{\n  \"phase\": \"build-complete\",\n  \"plan\": \"docs/plans/2025-01-15-user-auth-flow.md\",\n  \"planId\": \"plan:user-auth-flow\",\n  \"wave\": { \"current\": 3, \"total\": 3 },\n  \"tasks\": { \"completed\": 8, \"total\": 8 },\n  \"lastVerification\": { \"timestamp\": \"2025-01-15T10:30:00Z\", \"result\": \"PASS\", \"tests\": 24 },\n  \"paused\": false\n}\n```\n\nAdd `.athena-state.json`, `.athena-edit-burst.json`, and `.athena-state.*.json` to your `.gitignore` — these are internal state files.\n\n### State Recovery\n\nIf `.athena-state.json` becomes corrupt (e.g., partial write due to crash):\n- The state helper auto-detects corruption, backs up to `.athena-state.corrupt.json`, and returns `{}`\n- All writes use atomic temp-file-then-rename to prevent corruption\n- To manually reset: run `/athena-pause` and request a state reset — backs up current state and starts fresh\n- To restore from backup: copy `.athena-state.pre-reset.json` back to `.athena-state.json`\n\n### Configurable Settings\n\nYou can tune Athena behavior via fields in `.athena-state.json`:\n\n| Field | Default | Description |\n|-------|---------|-------------|\n| `editBurstThreshold` | 15 | Number of edits without a commit before nudge fires |\n\n## Multi-Platform Support\n\nAthena works on all major AI coding tools:\n\n| Platform | Install Guide |\n|----------|---------------|\n| **Claude Code** | `claude plugin marketplace add bencrooks-dev/athena` |\n| **Cursor** | [docs/platforms/cursor.md](docs/platforms/cursor.md) |\n| **Codex** | [docs/platforms/codex.md](docs/platforms/codex.md) |\n| **Gemini CLI** | [docs/platforms/gemini.md](docs/platforms/gemini.md) |\n| **OpenCode** | [docs/platforms/opencode.md](docs/platforms/opencode.md) |\n\nAll guides include Windows + macOS/Linux instructions and tool mapping tables.\n\n## Agent Fleet\n\nAthena ships dedicated agent definitions for parallel execution — not just \"use the Agent tool\", but purpose-built agents with specific roles, tools, and output formats:\n\n| Agent | Role | Dispatched By |\n|-------|------|---------------|\n| `athena-worker` | Writes code (plan tasks or freeform), tests, commits | `/athena-build`, direct dispatch |\n| `athena-code-reviewer` | Four-pass review (spec, correctness, security, quality) | `/athena-build` (between waves), `/athena-review`, `/athena-ship` |\n| `athena-debugger` | Investigates and fixes bugs using scientific method | `/athena-debug`, `/athena-build` (fix attempts) |\n| `athena-verifier` | Runs test suite, reports with evidence | `/athena-build`, `/athena-ship` |\n| `athena-researcher` | Explores codebase, maps architecture | `/athena-plan`, `/athena-brainstorm` |\n| `athena-scout` | Fast parallel search, finds files/patterns | Any skill needing broad search |\n\nBuild execution dispatches workers in parallel per wave, with reviewer and verifier gates between waves:\n\n```\nWave N\n  ├── athena-workers (parallel, one per task)\n  ├── athena-code-reviewer (four-pass audit)\n  ├── athena-verifier (runs full test suite)\n  └── All green? → Wave N+1\n```\n\n## Architecture\n\nAthena is a skills plugin with auto-trigger hooks and persistent pipeline state. Skills are SKILL.md files, agents are markdown definitions in `agents/`. Install is instant, runs everywhere.\n\n### Auto-Trigger Hooks\n\nAthena includes two hook types that automatically enforce workflows:\n\n**PostToolUse** (6 triggers):\n- After tests pass → reminds to run `/athena-verify` before claiming done\n- When PR review feedback detected → nudges toward `/athena-receive-review`\n- When merge conflicts detected → nudges toward `/athena-debug`\n- When new source file created → nudges toward `/athena-tdd`\n- When plan file read → nudges toward `/athena-build`\n- After 15+ edits without a commit → nudges verification (configurable via `editBurstThreshold`)\n\n**PreToolUse** (init enforcement):\n- Before action tools (Edit/Write/Bash) → checks that an Athena skill was considered\n- Rate-limited to once per 60 seconds to avoid noise\n- Skips exploration commands (git status, ls, etc.)\n\nBoth hooks respect `/athena-pause` — they exit early when Athena is paused.\n\nInstall hooks: `node hooks/install.cjs`\n\nThe installer backs up your existing `settings.json` before modifying it and preserves any non-Athena hooks already configured.\n\n## Engram Integration\n\nIf [Engram](https://github.com/bencrooks-dev/engram) (memory optimization plugin) is installed, Athena uses it to create a feedback loop: workflows produce learnings, learnings improve future workflows.\n\n### Session Logging (workflows → memory)\n\nThree Athena skills log structured topics to Engram after completion:\n\n| Skill | What Gets Logged |\n|-------|-----------------|\n| `/athena-debug` | Bug category, root cause pattern, affected component |\n| `/athena-build` | Feature area, technology patterns, architectural decisions |\n| `/athena-receive-review` | Review feedback themes, recurring corrections |\n\nThis feeds Engram's `engram_session_coverage` analysis — over time it surfaces patterns like \"you've debugged auth 4 times but have no memory about common auth failures.\" Non-obvious root causes and recurring corrections also nudge toward `/engram-suggest` for memory capture.\n\n### Memory-Aware Planning (memory → workflows)\n\n`/athena-plan` calls `engram_simulate_relevance` during Phase 1 (context gathering) to check what memories exist for the task:\n\n- **`feedback` memories are critical** — past corrections override default planning instincts. If a feedback memory says \"don't mock the database\", the planner won't propose mocked DB tests.\n- **`user` memories** inform how to pitch proposals (simple vs complex preferences)\n- **`project`/`reference` memories** provide context about ongoing work and external resources\n\nLow-confidence matches are silently ignored. High-confidence matches are factored into proposals without announcement.\n\nBoth integrations are conditional — they only fire if Engram is installed.\n\n## License\n\nMIT\n",
  "bytes": 19755,
  "sha": "271a0507ff11a6eb689cd2957d82ad9c6e19f27c23a688ab4e9d1bd19d8309bf",
  "repo_slug": "bencrooks-dev/athena",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_bencrooks_dev_athena_1ab1c6a4/readme"
}