OpenCode Athena

> Strategic wisdom meets practical execution

Unified oh-my-opencode + BMAD METHOD v6 toolkit for OpenCode.


What is Athena?

OpenCode Athena bridges the gap between BMAD METHOD's rigorous planning and oh-my-opencode's superior execution:

- Planning (BMAD): PRD → Architecture → Epics → Stories
- Execution (oh-my-opencode): Sisyphus + Oracle + Librarian + LSP tools + parallel agents
- Bridge (Athena): Automatic handoff, status tracking, context injection

| Without Athena | With Athena |
|----------------|-------------|
| Manual oh-my-opencode setup | One-command installation |
| Manual BMAD ↔ Sisyphus handoff | Automated bridge commands |
| Manual sprint-status.yaml updates | Auto-tracking |
| Separate context management | Unified context injection |
| Manual auth configuration | Guided setup wizard |

Quick Start

``bash
npx opencode-athena install
`

The interactive installer will:
1. Ask about your LLM subscriptions (Claude, OpenAI, Google)
2. Configure oh-my-opencode with optimal agent models
3. Set up authentication plugins
4. Install bridge commands

Requirements

- OpenCode 1.0.132+
- Node.js 20+
- One or more LLM subscriptions:
- Claude Pro/Max (recommended)
- ChatGPT Plus/Pro
- Google/Gemini
- GitHub Copilot (Free/Pro/Pro+/Business/Enterprise)

Commands

After installation, these commands are available in OpenCode:

| Command | Description |
|---------|-------------|
| /athena-dev | Implement current BMAD story with Sisyphus |
| /athena-review | Combined quality gate (BMAD + oh-my-opencode) |
| /athena-debug | Debug with Oracle (GPT-5.1 reasoning) |
| /athena-research | Research with Librarian + MCPs |
| /athena-parallel | Execute multiple stories in parallel |
| /athena-status | View/update sprint status |
| /athena-info | Show toolkit configuration |
| /athena-review-story | Party review stories for security/logic/performance gaps (pre-dev) |

Workflow

$3

Use BMAD agents for planning:

`
Load PM agent → *prd
Load Architect agent → *create-architecture
Load SM agent → sprint-planning → create-story
`

$3

Use Athena bridge commands in an iterative loop:

`
/athena-dev # Load story, implement with Sisyphus
/athena-review # Quality gate with collaborative discussion
`

If review passes:
`
/athena-status # Mark complete, get next story
`

If review finds issues:
1. Sisyphus auto-updates story status to in_progress
2. You discuss findings together and decide which to address
3. Sisyphus updates story file with implementation notes
4. Sisyphus recommends: Stay in session or Restart /athena-dev
5. You decide and proceed:
- Stay in session: Continue fixing in current session
- Restart: Exit and run /athena-dev again (loads implementation notes)
6. After fixes, run /athena-review again (respects previous decisions)

Iterative Quality Loop:
`
Implement → Review → Discuss → Fix → Review → ... → PASS
`

Key Features:
- Review discussions are preserved in story file
- Subsequent reviews don't re-block on deferred/rejected items
- Checkboxed implementation notes track progress
- Flexible: stay in session for simple fixes, restart for complex rework

$3

Continue until sprint is complete, then run retrospective with BMAD SM.

Pre-Development Story Review

The /athena-review-story command runs a comprehensive "party review" of stories before development begins, catching issues when they're cheap to fix (in markdown, not code).

$3

`bash
/athena-review-story epic-2 # Review all stories in Epic 2
/athena-review-story 2.3 # Deep dive on Story 2.3
/athena-review-story --thorough # Force advanced model
`

$3

`
┌─────────────────────────────────────────┐
│ PHASE 1: Automated Analysis │
│ • Oracle finds security/logic gaps │
│ • Recommends BMAD agents by findings │
│ • Saves review to docs/reviews/ │
└─────────────────────────────────────────┘
│
▼
User: [Q]uick review or [D]iscuss?
│
[D]
▼
┌─────────────────────────────────────────┐
│ PHASE 2: Parallel Agent Analysis │
│ • Architect, DEV, TEA, PM in parallel │
│ • Each analyzes ALL stories │
│ • Cross-story pattern detection │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ PHASE 3: Informed Discussion │
│ • Athena party discussion orchestration│
│ • Interactive agent debate │
│ • Decisions captured to story files │
└─────────────────────────────────────────┘
`

$3

| Category | Icon | Examples |
|----------|------|----------|
| Security | 🔒 | Missing auth, input validation, data exposure |
| Logic | 🧠 | Edge cases, error handling, race conditions |
| Best Practices | ✨ | Anti-patterns, testing gaps, accessibility |
| Performance | ⚡ | N+1 queries, caching, large data handling |

$3

Agents are recommended based on finding types:

| Finding Type | Agents Recommended |
|--------------|-------------------|
| Security issues | Architect (Winston), DEV (Amelia), TEA (Murat) |
| Logic gaps | DEV, TEA, Analyst (Mary) |
| Performance concerns | Architect, DEV |
| Best practice issues | DEV, Tech Writer (Paige) |
| High severity (any) | PM (John) - always required |

$3

- Quick Review [Q]: Accept Phase 1 findings, skip discussion. Best for low-severity issues.
- Full Discussion [D]: Run Phases 2-3 with parallel agents and informed discussion. Best for complex or high-severity findings.

BMAD ↔ Todo Sync

Athena automatically synchronizes BMAD story checkboxes with oh-my-opencode's todo tool:

- Automatic population: Story tasks appear in your todo list when loading a story
- Two-way sync: Marking todos complete updates BMAD file checkboxes
- Athena-themed format: [2.3ΔAC1] Task description
- Compaction-safe: Works seamlessly after session compaction
- Story context: Prefix tells you where to look for full details

$3

`
┌─────────────────────────────────────────────────────────────────────────┐
│ WRITE-THROUGH CACHE MODEL │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ BMAD Files (Source of Truth) Todo Cache (Session View) │
│ ┌─────────────────────────┐ ┌─────────────────────────┐ │
│ │ story-2-3.md │ │ [2.3ΔAC1] Login ○ │ │
│ │ - [ ] AC1: Login │◄────────│ [2.3ΔAC2] Logout ✓ │ │
│ │ - [x] AC2: Logout │ Write │ [2.3ΔTask1] Tests ○ │ │
│ │ - [ ] Task: Add tests │ back │ │ │
│ └─────────────────────────┘ └─────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
`

When you call athena_get_story, todos are extracted from the story file's checkboxes and returned in a format ready for todowrite. Marking a todo complete automatically updates the corresponding checkbox in the BMAD file.

$3

| BMAD Section | Todo Prefix | Example |
|--------------|-------------|---------|
| Acceptance Criteria | AC{n} | [2.3ΔAC1] Users can login |
| Tasks/Subtasks | Task{n} | [2.3ΔTask3] Write tests |
| Implementation Notes | Fix{n} | [2.3ΔFix2] Hardcoded secret |

$3

Todo sync is enabled by default. To disable:

`json
{
"features": {
"todoSync": false
}
}
`

Story Complexity Analysis

Athena automatically checks story complexity before implementation and suggests decomposition when stories are too large. This prevents context compaction issues during implementation.

$3

When you run /athena-dev, Athena:

1. Analyzes the story - Counts tasks, estimates effort points per task
2. Compares against thresholds - Research-backed limits (8 tasks / 8 points warning, 12 tasks / 13 points critical)
3. Recommends action - proceed, suggest-decomposition, or require-decomposition
4. Offers decomposition - Automatically groups tasks and creates sub-stories

$3

Each task is scored based on:

| Signal | Points Added |
|--------|--------------|
| Many subtasks (>5) | +3 |
| High-effort keywords (implement, create, refactor) | +2 |
| Medium-effort keywords (add, update, modify) | +1 |
| Testing/verification required | +1 |
| External system integration (API, database) | +1 |
| Vague description | +2 |

Points are mapped to Fibonacci scale: 1, 2, 3, 5, 8.

$3

When decomposition is recommended, Athena:

1. Groups tasks by concern - UI, core logic, integration, testing
2. Balances groups - Target ~8 points per sub-story
3. Handles dependencies - Testing tasks depend on implementation tasks
4. Preserves dev notes - Applicable sections copied to each sub-story

Filename format:
- Original: 3-2-reset-list-screen.md
- Sub-stories: 3-2a-reset-list-screen.md, 3-2b-reset-list-screen.md

$3

| Tool | Description |
|------|-------------|
| athena_analyze_story | Analyze story complexity and get recommendations |
| athena_decompose_story | Split story into sub-stories |

$3

`
📊 COMPLEXITY ANALYSIS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Tasks: 10 / 8 recommended ⚠️
Points: 15 / 8 threshold 🔴
File size: 12KB / 30KB ✅
Estimated compactions: 1

🔀 SUGGESTED DECOMPOSITION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Story 3.2a: Core Implementation
├─ Tasks: 1, 2, 3, 4
├─ Points: ~8
└─ Dependencies: None

Story 3.2b: Testing & Verification
├─ Tasks: 5, 6, 7
├─ Points: ~7
└─ Dependencies: 3.2a
`

Configuration

Configuration files are stored in ~/.config/opencode/:

- athena.json - Athena-specific settings
- oh-my-opencode.json - Agent model configuration
- opencode.json - Plugin registration

$3

Use --preset during installation:

`bash
npx opencode-athena install --preset minimal # Bare essentials
npx opencode-athena install --preset standard # Recommended (default)
npx opencode-athena install --preset enterprise # Full features
npx opencode-athena install --preset solo-quick # Solo dev quick flow
npx opencode-athena install --preset copilot-only # GitHub Copilot users
`

$3

Create .opencode/athena.json in your project root to override global settings.

$3

Athena provides fine-grained control over model behavior through temperature and thinkingLevel settings. These can be configured per agent role in athena.json:

`json
{
"models": {
"settings": {
"sisyphus": {
"temperature": 0.3,
"thinkingLevel": "medium"
},
"oracle": {
"thinkingLevel": "high"
},
"librarian": {
"temperature": 0.2
}
}
}
}
`

Temperature controls response randomness. Valid range is provider-specific:
- Anthropic: 0.0-1.0
- OpenAI: 0.0-2.0
- Google: 0.0-2.0
- GitHub Copilot: Not supported

Lower values = more focused, higher = more creative. Defaults are model-family-aware and clamped to valid ranges.

ThinkingLevel controls reasoning depth for supported models:
- "low" - Quick responses, minimal reasoning
- "medium" - Balanced (default)
- "high" - Deep reasoning, slower

ThinkingLevel maps to provider-specific parameters:
| Provider | Parameter | Values |
|----------|-----------|--------|
| Anthropic | thinking.budget_tokens | 4096 / 16384 / 32768 |
| OpenAI | reasoning_effort | "low" / "medium" / "high" |
| Google | thinking_level | "low" / "medium" / "high" |

Note: Temperature and thinkingLevel are not supported for GitHub Copilot-routed models.

$3

Add custom models to use models not in the built-in list. Custom models can override built-in models or add entirely new ones:

`json
{
"models": {
"sisyphus": "custom/my-finetuned-model",
"custom": [
{
"id": "custom/my-finetuned-model",
"name": "My Fine-tuned Model",
"provider": "openai",
"description": "Custom fine-tuned GPT for our codebase",
"capabilities": {
"thinking": false,
"contextWindow": 128000,
"supportsTemperature": true
}
},
{
"id": "anthropic/claude-4-opus",
"name": "Claude 4 Opus (Override)",
"provider": "anthropic",
"description": "Override built-in model with custom settings"
}
]
}
}
`

Custom model fields:
- id (required): Unique identifier, format: provider/model-name
- name (required): Display name
- provider (required): "anthropic", "openai", "google", or "github-copilot"
- description: Optional description
- capabilities: Optional capability hints
- thinking: Whether the model supports extended thinking
- contextWindow: Context window size in tokens
- supportsTemperature: Whether temperature can be adjusted

$3

By default, Athena prevents agents from automatically performing git operations (commits, pushes, branch creation). This ensures developers maintain full control over version control.

Default behavior (autoGitOperations: false):
- ✅ Agents can read git state (git status, git diff, git log)
- ❌ Agents cannot automatically commit, push, or create branches
- ⚠️ If an agent attempts a git write operation, a warning is injected
- 📝 Agents must ask for explicit user permission before git operations

Enable automatic git operations:

Set features.autoGitOperations: true in athena.json:

`json
{
"features": {
"autoGitOperations": true
}
}
`

Or during installation, check the "Auto Git Operations" feature.

Covered operations:
- Git commits & pushes: git commit, git push
- Branch operations: git checkout -b, git branch, git switch -c, git switch --create
- Merging & rebasing: git merge, git rebase, git cherry-pick
- Stashing & tags: git stash, git tag
- Reset operations: git reset (all variants: --soft, --mixed, --hard)
- GitHub PR operations: gh pr create, gh pr edit, gh pr merge, gh pr close, gh pr review
- GitHub issue operations: gh issue create, gh issue edit, gh issue close
- GitHub release operations: gh release create, gh release edit, gh release delete

Why this is the default:

Version control is critical. Automatic commits can:
- Create unclear commit messages
- Commit unintended changes
- Disrupt branch strategies
- Bypass code review processes

With autoGitOperations: false, agents track progress via athena_update_status() instead, which updates sprint-status.yaml without git operations.

$3

By default, Athena auto-detects BMAD file locations using BMAD METHOD v6 conventions. However, you can override any file path if your project uses non-standard locations or naming conventions.

Automatic detection features:
- ✅ Case-insensitive search (finds prd.md, PRD.md, Prd.md)
- ✅ Multiple search paths (planning-artifacts, docs, sprint-artifacts)
- ✅ Nested vs flat story structures

Override paths when needed:

`json
{
"bmad": {
"paths": {
"stories": "custom/stories",
"sprintStatus": "custom/sprint.yaml",
"prd": "planning/requirements.md",
"architecture": "design/system-arch.md",
"epics": "backlog/epic-list.md"
}
}
}
`

Available path overrides:

| Field | Default Detection | Example Override |
|-------|-------------------|------------------|
| stories | docs/implementation-artifacts/stories/ or docs/sprint-artifacts/ (flat structure) | "dev/user-stories" |
| sprintStatus | sprint-status.yaml in implementation or sprint artifacts | "status/current-sprint.yaml" |
| prd | PRD.md (case-insensitive) in planning artifacts or docs | "planning/product-requirements.md" |
| architecture | architecture.md (case-insensitive) in planning artifacts or docs | "docs/system-design.md" |
| epics | epics.md (case-insensitive) in planning artifacts or docs | "backlog/epic-definitions.md" |

Path format:
- All paths are relative to project root
- Use forward slashes (/) even on Windows
- Set to null to use automatic detection (default)

Use case example:

If your project has a non-standard structure:
`
my-project/
├── planning/
│ ├── requirements.md # Instead of PRD.md
│ └── system-design.md # Instead of architecture.md
└── dev/
├── sprint-status.yaml
└── stories/
├── story-1-1.md
└── story-1-2.md
`

Configure overrides:
`json
{
"bmad": {
"paths": {
"stories": "dev/stories",
"sprintStatus": "dev/sprint-status.yaml",
"prd": "planning/requirements.md",
"architecture": "planning/system-design.md"
}
}
}
`

GitHub Copilot Support

Athena supports GitHub Copilot as a model provider, allowing you to use Claude, GPT, and Gemini models through your Copilot subscription. This is especially useful for enterprise users who only have access to LLMs through Copilot.

$3

1. Run the installer and select "GitHub Copilot" when asked about subscriptions
2. Select your Copilot plan level (determines available models)
3. After installation, authenticate:
`bash
opencode auth login github-copilot
`

Or use the copilot-only preset:
`bash
npx opencode-athena install --preset copilot-only
`

$3

Model availability depends on your GitHub Copilot plan:

| Plan | Claude Models | GPT Models | Gemini Models |
|------|---------------|------------|---------------|
| Free | Haiku 4.5 | GPT-4.1, GPT-5-mini | - |
| Pro | Haiku 4.5, Sonnet 4, Sonnet 4.5 | GPT-4.1, GPT-5, GPT-5-mini, GPT-5.1, GPT-5.1-codex, GPT-5.2 | Gemini 2.5 Pro, Gemini 3 Flash, Gemini 3 Pro |
| Pro+ | All Pro models + Opus 4.1, Opus 4.5 | All Pro models | All Pro models |
| Business | Haiku 4.5, Sonnet 4, Sonnet 4.5 | GPT-4.1, GPT-5, GPT-5-mini, GPT-5.1, GPT-5.1-codex, GPT-5.2 | Gemini 2.5 Pro, Gemini 3 Flash, Gemini 3 Pro |
| Enterprise | All Pro models + Opus 4.1, Opus 4.5 | All Pro models | All Pro models |

$3

GitHub Copilot acts as a proxy to multiple LLM providers. When you configure a Copilot-routed model (e.g., github-copilot/claude-sonnet-4), requests are sent through GitHub's API.

Naming convention: Copilot-routed models use the format github-copilot/{model} (e.g., github-copilot/gpt-4o).

Priority behavior: If you have both direct provider access and Copilot access (e.g., Claude Pro + Copilot), Athena prefers direct provider models for better feature support.

$3

Models accessed through GitHub Copilot have some limitations compared to direct provider access:

- No temperature control: Copilot strips temperature parameters
- No thinking/reasoning modes: Extended thinking (Claude), reasoning effort (OpenAI), and thinking level (Google) are not supported
- Rate limits: Subject to Copilot's rate limits rather than provider limits
- Feature lag: New model features may not be immediately available

For full model capabilities, use direct provider subscriptions when possible.

Architecture

`
┌─────────────────────────────────────────────────────────────────────────────┐
│ OPENCODE ATHENA │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ CLI Installer │ │
│ │ npx opencode-athena install npx opencode-athena doctor │ │
│ │ npx opencode-athena upgrade npx opencode-athena uninstall │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ OpenCode Plugin │ │
│ │ Custom Tools: Event Hooks: │ │
│ │ • athena_get_story • session.idle │ │
│ │ • athena_update_status • session.created │ │
│ │ • athena_get_context • tool.execute.before │ │
│ │ • athena_parallel • tool.execute.after │ │
│ │ • athena_config • session.compacting │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Bridge Commands │ │
│ │ /athena-dev /athena-review /athena-debug │ │
│ │ /athena-research /athena-parallel /athena-status │ │
│ │ /athena-review-story │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────┐ ┌──────────────────────┐ ┌────────────────┐ │
│ │ oh-my-opencode │ │ BMAD METHOD v6 │ │ Auth Plugins │ │
│ │ (managed) │ │ (per-project) │ │ (managed) │ │
│ └──────────────────────┘ └──────────────────────┘ └────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────┐
│ OpenCode │
│ (Base) │
└─────────────┘
`

Troubleshooting

`bash
npx opencode-athena doctor # Diagnose issues
npx opencode-athena doctor --fix # Auto-fix common problems
`

Common issues:

| Issue | Solution |
|-------|----------|
| Plugin not loading | Run doctor --fix to reinstall |
| Auth errors | Run opencode auth login for each provider |
| BMAD not found | Run npx bmad-method@alpha install in your project |
| Commands not available | Verify commands are in ~/.config/opencode/command/ |

Publishing Releases

This package uses Trusted Publishing (OIDC) for secure, credential-free releases via GitHub Actions.

$3

1. Update version:
`bash
npm version patch # 0.0.3 -> 0.0.4
npm version minor # 0.1.0 -> 0.2.0
npm version major # 1.0.0 -> 2.0.0
`

2. Commit and push:
`bash
git add package.json
git commit -m "Bump version to X.Y.Z"
git push origin main
`

3. Create and push tag:
`bash
git tag vX.Y.Z
git push origin vX.Y.Z
`

4. Monitor: GitHub Actions publishes automatically
- Watch: Actions
- Verify: npm package
- Check: GitHub Releases

$3

Trusted Publishing (OIDC):
- ✅ Zero stored credentials (no npm tokens in GitHub)
- ✅ Short-lived authentication (hours, not years)
- ✅ Cannot be leaked (runtime-only tokens)
- ✅ Automatic provenance attestations
- ✅ OpenSSF industry standard

Provenance Attestations:

Every release includes cryptographically signed provenance via Sigstore, providing:
- Verifiable link between npm package and GitHub source code
- Proof of which GitHub Actions workflow built the package
- Immutable transparency log entry
- Supply chain security guarantees

Verify any published version:
`bash
npm install opencode-athena
npm audit signatures
`

$3

The release workflow uses:
- Trusted Publishing - OIDC authentication (no long-lived tokens)
- npm CLI 11+ - Required for Trusted Publishing support
- GitHub-hosted runners - Secure, isolated build environment
- Automatic provenance - Generated without --provenance flag

Trusted Publisher configuration:
- Provider: GitHub Actions
- Repository: ZebulonRouseFrantzich/opencode-athena
- Workflow: release.yml
- Permissions: id-token: write, contents: write

$3

| Issue | Solution |
|-------|----------|
| "Unable to authenticate" | Verify Trusted Publisher config on npmjs.com matches exactly (case-sensitive) |
| Workflow filename mismatch | Must be release.yml (not Release.yml or full path) |
| npm version error | Ensure npm 11.5.1+ (workflow upgrades automatically) |
| No provenance generated | Automatic with Trusted Publishing - check npmjs.com package page |
| Self-hosted runner error | Use GitHub-hosted runners only (required for OIDC) |

For detailed setup: .github/workflows/release.yml`

$3

We use Trusted Publishing instead of traditional npm tokens because:
- Security: Eliminates risks from npm credential breaches
- Compliance: Implements OpenSSF Trusted Publishers standard
- Simplicity: No manual token management or rotation
- Transparency: Automatic provenance provides supply chain visibility

Learn more: npm Trusted Publishing Documentation

Credits

Built on top of:

- OpenCode by SST
- oh-my-opencode by code-yeongyu
- BMAD METHOD by bmad-code-org

License

MIT-0 (MIT No Attribution) - See LICENSE for details.