opencode-athena 0.0.1

package/LICENSE

@@ -0,0 +1,18 @@
+MIT No Attribution
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,178 @@
+# OpenCode Athena
+
+> **Strategic wisdom meets practical execution**
+
+Unified [oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode) + [BMAD METHOD v6](https://github.com/bmad-method/bmad-method) toolkit for [OpenCode](https://opencode.ai).
+
+[![npm version](https://img.shields.io/npm/v/opencode-athena)](https://www.npmjs.com/package/opencode-athena)
+[![License: MIT-0](https://img.shields.io/badge/License-MIT--0-yellow.svg)](https://opensource.org/licenses/MIT-0)
+
+## 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](https://opencode.ai/docs) 1.0.132+
+- Node.js 20+
+- One or more LLM subscriptions:
+  - Claude Pro/Max (recommended)
+  - ChatGPT Plus/Pro
+  - Google/Gemini
+
+## 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 |
+
+## Workflow
+
+### 1. Plan with BMAD (Phases 1-3)
+
+Use BMAD agents for planning:
+
+```
+Load PM agent → *prd
+Load Architect agent → *create-architecture
+Load SM agent → *sprint-planning → *create-story
+```
+
+### 2. Implement with Athena (Phase 4)
+
+Use Athena bridge commands:
+
+```
+/athena-dev        # Load story, implement with Sisyphus
+/athena-review     # Quality gate
+/athena-status     # Mark complete, get next story
+```
+
+### 3. Repeat
+
+Continue until sprint is complete, then run retrospective with BMAD SM.
+
+## Configuration
+
+Configuration files are stored in `~/.config/opencode/`:
+
+- `athena.json` - Athena-specific settings
+- `oh-my-opencode.json` - Agent model configuration
+- `opencode.json` - Plugin registration
+
+### Presets
+
+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
+```
+
+### Project Overrides
+
+Create `.opencode/athena.json` in your project root to override global settings.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           OPENCODE ATHENA                                    │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                              │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │                         CLI Installer                                │   │
+│  │   npx opencode-athena install    npx opencode-athena doctor         │   │
+│  │   npx opencode-athena update     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              │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│                                                                              │
+│  ┌──────────────────────┐  ┌──────────────────────┐  ┌────────────────┐   │
+│  │    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/` |
+
+## Credits
+
+Built on top of:
+
+- [OpenCode](https://opencode.ai) by SST
+- [oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode) by code-yeongyu
+- [BMAD METHOD](https://github.com/bmad-method/bmad-method) by bmad-method
+
+## License
+
+MIT-0 (MIT No Attribution) - See [LICENSE](LICENSE) for details.

package/commands/athena-debug.md

@@ -0,0 +1,338 @@
+---
+description: Debug an issue using Oracle's deep reasoning capabilities
+---
+
+# Athena Debug - Oracle-Powered Debugging
+
+Use Oracle, the debugging specialist, to analyze and fix complex issues with systematic hypothesis-driven debugging.
+
+**You are Sisyphus, the orchestrator.** You will coordinate Oracle's deep reasoning with automated tools to efficiently diagnose and fix issues.
+
+## When to Use This Command
+
+- Complex bugs that span multiple files
+- Performance issues requiring deep analysis
+- Architectural problems needing strategic solutions
+- Issues where the root cause is unclear
+- Bugs you've tried to fix 2+ times without success
+
+## Step 1: Gather Context
+
+### 1.1 Check Story Context (if applicable)
+
+If debugging during story implementation, load the story context first:
+
+```
+athena_get_story()
+```
+
+This provides:
+- Acceptance criteria (to understand expected behavior)
+- Architecture patterns (to understand design intent)
+- Related code context
+
+### 1.2 Collect Error Evidence
+
+Before invoking Oracle, gather all available evidence:
+
+**Error messages and stack traces:**
+- Copy the exact error message
+- Include the full stack trace if available
+- Note which file/line the error points to
+
+**Reproduction information:**
+- Steps to reproduce the issue
+- Input values that trigger the error
+- Environment details (dev/prod, browser, etc.)
+
+**What you've already tried:**
+- Previous fix attempts
+- Why they didn't work
+- Any patterns you've noticed
+
+### 1.3 Use Explore for Initial Context (Optional but Recommended)
+
+Before invoking expensive Oracle, use **@explore** to gather codebase context:
+
+```
+@explore I'm debugging an issue in {area of code}.
+
+The error is: {error message}
+The problematic behavior is: {description}
+
+Please find:
+1. The code paths related to this functionality
+2. Similar error handling in the codebase
+3. Any related tests that might indicate expected behavior
+4. Recent changes to these files (if visible)
+
+Return file paths and relevant code sections.
+```
+
+**When to skip Explore:**
+- You already know exactly where the bug is
+- You've already traced the code path
+- The issue is architectural, not code-specific
+
+## Step 2: Invoke Oracle for Diagnosis
+
+Ask **@oracle** to perform systematic debugging:
+
+```
+@oracle I need help debugging a complex issue.
+
+## Problem Description
+
+**Expected Behavior:**
+{what should happen}
+
+**Actual Behavior:**
+{what happens instead}
+
+**Error Message/Stack Trace:**
+```
+{paste exact error}
+```
+
+**Reproduction Steps:**
+1. {step 1}
+2. {step 2}
+3. {step 3}
+
+## Context
+
+**Affected Files:**
+{list files involved - from Explore or your knowledge}
+
+**Architecture Context:**
+{relevant architecture patterns if from story context}
+
+**What I've Already Tried:**
+- {attempt 1 and why it failed}
+- {attempt 2 and why it failed}
+
+## Debugging Request
+
+Please analyze this issue using your systematic debugging approach:
+
+1. **Evidence Analysis**: Review the error, stack trace, and context
+2. **Hypothesis Generation**: List 3-5 possible root causes ranked by likelihood
+3. **Hypothesis Testing**: For each hypothesis, describe how to test/verify it
+4. **Root Cause Identification**: Based on testing, identify the most likely root cause
+5. **Solution Design**: Propose a fix that addresses the root cause
+6. **Risk Assessment**: Identify any side effects or risks of the proposed fix
+
+Do NOT implement the fix yet. First, present your analysis and get confirmation.
+```
+
+## Step 3: Review Oracle's Analysis
+
+Oracle will provide:
+
+1. **Hypotheses** - Ranked list of possible root causes
+2. **Evidence Mapping** - How each hypothesis explains the observed behavior
+3. **Testing Plan** - How to verify/eliminate each hypothesis
+4. **Recommended Root Cause** - The most likely cause based on analysis
+5. **Proposed Fix** - Solution design
+
+### 3.1 Validate the Analysis
+
+Before proceeding with the fix:
+
+- Does the root cause explain ALL the symptoms?
+- Does the proposed fix address the root cause (not just symptoms)?
+- Are there any risks or side effects?
+
+### 3.2 Request Implementation
+
+If you agree with Oracle's analysis:
+
+```
+@oracle Your analysis looks correct. Please implement the fix you proposed.
+
+Specifically:
+- {any additional constraints}
+- {any files to avoid modifying}
+- {any patterns to follow}
+
+After implementing, show me what changed and explain how it fixes the root cause.
+```
+
+If you disagree or need more investigation:
+
+```
+@oracle I have concerns about hypothesis #{N}.
+
+{explain your concern}
+
+Please investigate further:
+- {specific thing to check}
+- {alternative hypothesis to consider}
+```
+
+## Step 4: Verify the Fix
+
+### 4.1 Run Automated Checks
+
+After Oracle implements the fix:
+
+**Run LSP diagnostics on modified files:**
+
+```
+lsp_diagnostics(filePath: "<modified file>", severity: "all")
+```
+
+**Run the build (if applicable):**
+
+```bash
+npm run build
+```
+
+**Run tests (if applicable):**
+
+```bash
+npm test
+```
+
+### 4.2 Reproduce the Original Issue
+
+Try to reproduce the original bug:
+
+- Follow the same reproduction steps
+- Use the same input values
+- Verify the error no longer occurs
+
+### 4.3 Check for Regressions
+
+- Does existing functionality still work?
+- Do related tests still pass?
+- Are there any new errors or warnings?
+
+## Step 5: Document and Update Status
+
+### 5.1 Document the Fix
+
+Record what was learned:
+
+```markdown
+## Debug Summary
+
+**Issue:** {brief description}
+**Root Cause:** {what Oracle identified}
+**Fix Applied:** {what was changed}
+**Files Modified:** {list of files}
+**Verification:** {how it was verified}
+```
+
+### 5.2 Update Story Status (if applicable)
+
+If debugging was part of a story:
+
+**If fix is complete and story can continue:**
+```
+athena_update_status({
+  storyId: "<story ID>",
+  status: "in_progress",
+  notes: "Debug complete. Root cause: {cause}. Fixed by: {fix}. Continuing implementation."
+})
+```
+
+**If issue was blocking and is now resolved:**
+```
+athena_update_status({
+  storyId: "<story ID>",
+  status: "in_progress",
+  notes: "Blocker resolved. Issue was {root cause}. Fixed by {solution}."
+})
+```
+
+**If issue requires external help:**
+```
+athena_update_status({
+  storyId: "<story ID>",
+  status: "blocked",
+  notes: "Debug identified issue but fix requires {external dependency/decision}. Root cause: {cause}."
+})
+```
+
+## Oracle's Debugging Methodology
+
+Oracle uses a systematic approach:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                   GATHER EVIDENCE                        │
+│  Collect error messages, stack traces, reproduction     │
+│  steps, and context from affected code                  │
+└─────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────┐
+│                 FORM HYPOTHESES                          │
+│  Generate 3-5 possible root causes, ranked by           │
+│  likelihood based on evidence                           │
+└─────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────┐
+│                 TEST HYPOTHESES                          │
+│  For each hypothesis, identify how to verify or         │
+│  eliminate it using tools and code analysis             │
+└─────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────┐
+│              IDENTIFY ROOT CAUSE                         │
+│  Based on testing, determine the most likely            │
+│  root cause that explains all symptoms                  │
+└─────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────┐
+│                 IMPLEMENT FIX                            │
+│  Design and implement a solution that addresses         │
+│  the root cause (not just symptoms)                     │
+└─────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────┐
+│                    VERIFY                                │
+│  Confirm fix resolves the issue without                 │
+│  introducing regressions                                │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Tips for Effective Debugging
+
+### Provide Complete Context
+
+- **Include full error messages** - Don't paraphrase, copy exactly
+- **Include stack traces** - The call stack reveals the code path
+- **Show the problematic code** - Oracle needs to see what's happening
+- **Describe reproduction steps** - How to trigger the bug
+
+### Don't Jump to Solutions
+
+- Let Oracle analyze before implementing
+- Review Oracle's hypotheses critically
+- Confirm root cause before fixing
+
+### Verify Thoroughly
+
+- The bug should be gone after the fix
+- Nothing else should break
+- Tests should pass
+
+### Cost Awareness
+
+- **Oracle is expensive** (GPT-5.2 deep reasoning)
+- Use Explore first for context gathering (cheaper)
+- Only invoke Oracle for genuinely complex bugs
+- Simple bugs (typos, obvious errors) don't need Oracle
+
+## When NOT to Use This Command
+
+- **Simple syntax errors** - LSP diagnostics will catch these
+- **Obvious bugs** - If you can see the issue, just fix it
+- **Configuration issues** - Check docs first
+- **First attempt at fixing** - Try yourself first, use Oracle after 2+ failures