opencode-athena 0.0.1

package/commands/athena-dev.md

@@ -0,0 +1,322 @@
+---
+description: Implement the current BMAD story using Sisyphus and specialized subagents
+---
+
+# Athena Dev - Story Implementation
+
+You are implementing a BMAD story using OpenCode Athena's full capabilities.
+
+**You are Sisyphus, the orchestrator.** You will coordinate subagents and tools to implement this story efficiently and correctly.
+
+## Step 1: Load Story Context
+
+Call **athena_get_story** to load the current story context:
+
+```
+athena_get_story()
+```
+
+If you need a specific story, pass the story ID:
+
+```
+athena_get_story({ storyId: "2.3" })
+```
+
+This returns:
+- **Story**: Requirements and acceptance criteria
+- **Architecture**: Relevant technical patterns and decisions
+- **PRD**: Relevant functional requirements
+- **Sprint progress**: Where this story fits in the overall sprint
+
+## Step 2: Plan Your Approach
+
+Before diving into code, plan your implementation strategy:
+
+### 2.1 Understand Existing Patterns
+
+**If this feature is similar to existing code in the codebase**, use **@explore** to find examples:
+
+```
+@explore Find existing implementations similar to <feature>.
+
+I need to implement: {brief description}
+
+Please search the codebase for:
+1. Similar features or components
+2. Patterns that match this use case
+3. Existing code I can reference or extend
+
+Return file paths and brief descriptions of what you found.
+```
+
+**When to use Explore:**
+- ✅ When implementing something similar to existing functionality
+- ✅ When you need to understand project-specific patterns
+- ✅ When you want to ensure consistency with existing code
+- ❌ When implementing something completely new to the codebase
+
+### 2.2 Research Unfamiliar Technologies
+
+**If the story involves libraries, frameworks, or patterns you're not deeply familiar with**, use **@librarian** to research:
+
+```
+@librarian I need to implement {feature} using {library/framework}.
+
+Context from architecture:
+{paste relevant architecture sections}
+
+Please research:
+1. Best practices for {specific technology}
+2. Official documentation for {specific APIs}
+3. Examples from similar projects (GitHub search)
+4. Any gotchas or common mistakes to avoid
+
+Return concrete examples and recommendations.
+```
+
+**When to use Librarian:**
+- ✅ When using unfamiliar npm packages, APIs, or frameworks
+- ✅ When you need official documentation or API references
+- ✅ When you want to see how others solved similar problems
+- ❌ When you're already familiar with the technology
+
+### 2.3 Architectural Decisions
+
+**If the story requires architectural decisions** (how to structure code, which pattern to use, trade-offs between approaches), **consult @oracle BEFORE implementing**:
+
+```
+@oracle I need to make an architectural decision for Story {storyId}.
+
+**Story Context:**
+{paste story requirements}
+
+**Architecture Constraints:**
+{paste relevant architecture sections}
+
+**Decision Required:**
+{describe the decision - e.g., "Should I use a microservice or monolith?", "Which state management pattern?", "How to structure this module?"}
+
+**Options I'm Considering:**
+1. {Option A} - {pros/cons}
+2. {Option B} - {pros/cons}
+
+Please provide:
+- Architectural recommendation with rationale
+- How this fits with project architecture
+- Long-term implications of each option
+- Any risks to be aware of
+```
+
+**When to consult Oracle for architecture:**
+- ✅ Before implementing complex features
+- ✅ When multiple architectural approaches exist
+- ✅ When the decision has long-term implications
+- ✅ When deviating from existing patterns
+- ❌ For straightforward implementations following clear patterns
+
+## Step 3: Implement the Story
+
+With your research and planning complete, implement the story:
+
+### 3.1 Follow Architecture Patterns
+
+- **Reference the architecture sections** loaded in Step 1
+- **Follow naming conventions** from similar code (found via Explore)
+- **Use established patterns** (don't reinvent the wheel)
+
+### 3.2 Use Appropriate Tools
+
+**For refactoring:**
+- `lsp_rename` - Rename symbols safely across workspace
+- `lsp_find_references` - Find all usages before changing
+- `lsp_code_actions` - Apply IDE quick fixes
+
+**For structural changes:**
+- `ast_grep_search` - Find code patterns to modify
+- `ast_grep_replace` - Replace code patterns safely
+
+**For parallel work:**
+- Launch background agents for independent tasks
+- Example: "Frontend implementation" while you work on backend
+
+### 3.3 Frontend Work
+
+**If the story involves UI/UX changes** (styling, layout, visual design), **delegate to @frontend-ui-ux-engineer**:
+
+```
+@frontend-ui-ux-engineer Implement the UI for Story {storyId}.
+
+**Requirements:**
+{paste UI-related acceptance criteria}
+
+**Design Constraints:**
+{any design system, component library, or styling guidelines from architecture}
+
+**Components Needed:**
+{list components to create or modify}
+
+Please implement the visual/UX aspects. I will handle the business logic and data flow.
+```
+
+**When to delegate to Frontend UI/UX Engineer:**
+- ✅ Styling, colors, spacing, typography
+- ✅ Layout, responsive design, animations
+- ✅ Visual component structure
+- ❌ Business logic, data fetching, state management (you handle these)
+
+## Step 4: Verify Implementation
+
+Before marking the story complete, verify your work:
+
+### 4.1 Self-Check Acceptance Criteria
+
+For EACH acceptance criterion in the story:
+- [ ] Have you implemented it?
+- [ ] Does it work as specified?
+- [ ] Have you tested it?
+
+### 4.2 Run Automated Checks
+
+**Run LSP diagnostics on files you modified:**
+
+```
+lsp_diagnostics(filePath: "<file you changed>", severity: "all")
+```
+
+**Address ALL errors.** Warnings should be addressed if reasonable.
+
+**If the project has a build command:**
+
+```bash
+npm run build
+# OR
+pnpm run build
+# OR
+yarn build
+```
+
+**Build MUST pass** before completing the story.
+
+**If the project has tests:**
+
+```bash
+npm test
+# OR
+pnpm test  
+# OR
+yarn test
+```
+
+**Tests MUST pass** before completing the story.
+
+### 4.3 Code Quality Self-Review
+
+Ask yourself:
+- Is the code self-documenting? (minimal comments needed)
+- Are variable and function names clear?
+- Is error handling appropriate?
+- Are there any `any` types, `@ts-ignore`, or other type safety compromises?
+- Does this follow the architecture patterns?
+
+**If you're unsure about code quality**, consider running `/athena-review` for a comprehensive quality gate.
+
+## Step 5: Complete the Story
+
+When implementation is verified and ready, update the status:
+
+```
+athena_update_status({
+  storyId: "<story ID>",
+  status: "completed",
+  completionSummary: "Implemented {feature}. {What was built}. {Tests status}. {Any notes}."
+})
+```
+
+### Completion Checklist
+
+Before marking complete, ensure:
+- [ ] ALL acceptance criteria met
+- [ ] LSP diagnostics clean (no errors)
+- [ ] Build passes (if applicable)
+- [ ] Tests pass (if applicable)
+- [ ] Code follows architecture patterns
+- [ ] No type safety compromises
+- [ ] Code is self-documenting
+
+### If Not Ready
+
+If the story isn't complete but you need to save progress:
+
+```
+athena_update_status({
+  storyId: "<story ID>",
+  status: "in_progress",
+  notes: "Progress: {what's done}. Remaining: {what's left}."
+})
+```
+
+## If You Get Blocked
+
+If you encounter a blocker:
+
+```
+athena_update_status({
+  storyId: "<story ID>",
+  status: "blocked",
+  notes: "Blocked because {specific reason}. Need {what's needed} to proceed."
+})
+```
+
+Then explain the blocker in detail so the user can help resolve it.
+
+**If blocked on a technical issue**, consider using `/athena-debug` to invoke Oracle for debugging help.
+
+## Orchestration Summary
+
+Your workflow as Sisyphus:
+
+```
+1. Load story (athena_get_story)
+2. Plan approach:
+   - @explore → Find similar code in codebase
+   - @librarian → Research unfamiliar tech
+   - @oracle → Get architectural guidance
+3. Implement:
+   - Follow architecture patterns
+   - Use LSP/AST tools for refactoring
+   - @frontend-ui-ux-engineer → Delegate UI work
+4. Verify:
+   - Check acceptance criteria
+   - Run diagnostics, build, tests
+   - Self-review code quality
+5. Complete (athena_update_status)
+```
+
+## Quality Standards
+
+1. **Meet ALL acceptance criteria** - Non-negotiable
+2. **Follow architecture patterns exactly** - Consistency is critical
+3. **Minimize comments** - Code should be self-documenting
+4. **LSP diagnostics clean** - No errors allowed
+5. **Tests pass** - If tests exist, they must pass
+6. **Build succeeds** - If build exists, it must succeed
+7. **No type safety compromises** - No `any`, no ignores
+8. **No regressions** - Existing functionality must still work
+
+## When to Use Each Subagent
+
+| Subagent | When to Use | Don't Use When |
+|----------|-------------|----------------|
+| **@explore** | Finding existing patterns in codebase | Implementing something brand new |
+| **@librarian** | Researching libraries, APIs, external docs | You already know the tech well |
+| **@oracle** | Architectural decisions, complex debugging | Straightforward implementations |
+| **@frontend-ui-ux-engineer** | UI/visual/styling work | Business logic or data flow |
+
+## Tips for Effective Implementation
+
+- **Start with exploration** - Understand what exists before building new
+- **Research before coding** - Know the best practices before implementing
+- **Consult Oracle early** - Don't paint yourself into an architectural corner
+- **Delegate UI work** - Let specialists handle what they do best
+- **Verify continuously** - Don't wait until the end to check quality
+- **Document decisions** - If you made a trade-off, note it in the completion summary

package/commands/athena-info.md

@@ -0,0 +1,325 @@
+---
+description: Display OpenCode Athena configuration and toolkit information
+---
+
+# Athena Info - Toolkit Information
+
+Display current OpenCode Athena configuration, available capabilities, and troubleshooting information.
+
+## View Current Configuration
+
+Call **athena_config** to see the current setup:
+
+```
+athena_config()
+```
+
+This displays:
+- Athena version
+- Configured LLM providers
+- Agent model assignments
+- BMAD settings
+- Enabled features
+- MCP servers
+
+## Configuration Sections
+
+### View Specific Section
+
+To view only a specific section:
+
+```
+athena_config({ section: "subscriptions" })
+athena_config({ section: "models" })
+athena_config({ section: "bmad" })
+athena_config({ section: "features" })
+athena_config({ section: "mcps" })
+```
+
+### Section Details
+
+**Subscriptions:**
+- Which LLM providers are configured (Claude, OpenAI, Google)
+- Authentication status
+
+**Models:**
+- Agent model assignments
+- Sisyphus model (main orchestrator)
+- Oracle model (deep reasoning)
+- Librarian model (research)
+- Frontend Engineer model
+- Document Writer model
+- Multimodal Looker model
+
+**BMAD:**
+- Methodology track
+- Auto status update setting
+- Parallel story limit
+- BMAD directory location
+
+**Features:**
+- Bridge commands enabled
+- Auto sprint status updates
+- Parallel execution
+- Notifications
+- Context monitoring
+- Comment checker
+- LSP tools
+
+**MCPs:**
+- context7 (documentation lookup)
+- websearch_exa (web search)
+- grep_app (GitHub code search)
+
+## Configuration Files
+
+Configuration is stored in these locations:
+
+### Global Configuration (all projects)
+
+```
+~/.config/opencode/
+├── athena.json          # Athena-specific settings
+├── oh-my-opencode.json  # Agent model configuration
+├── opencode.json        # Plugin registration
+└── package.json         # Installed plugin packages
+```
+
+### Project Configuration (overrides global)
+
+```
+[project]/.opencode/
+├── athena.json          # Project-specific Athena settings
+└── oh-my-opencode.json  # Project-specific agent models
+```
+
+## Toolkit Capabilities
+
+### Bridge Commands
+
+| Command | Description | Invokes |
+|---------|-------------|---------|
+| `/athena-dev` | Implement a BMAD story | Sisyphus + subagents |
+| `/athena-review` | Quality gate review | Oracle (code + adversarial) |
+| `/athena-debug` | Debug complex issues | Oracle |
+| `/athena-research` | Research patterns/docs | Librarian |
+| `/athena-status` | Sprint status management | Athena tools |
+| `/athena-info` | This command | athena_config |
+| `/athena-parallel` | Parallel story execution | (Planned) |
+
+### Available Subagents
+
+| Agent | Model | Specialty |
+|-------|-------|-----------|
+| **Sisyphus** | (configured) | Orchestration, implementation |
+| **Oracle** | (configured) | Deep reasoning, debugging, code review |
+| **Librarian** | (configured) | Research, documentation, examples |
+| **Explore** | (configured) | Fast codebase search |
+| **Frontend UI/UX Engineer** | (configured) | Visual design, UI implementation |
+| **Document Writer** | (configured) | Documentation |
+| **Multimodal Looker** | (configured) | Image/PDF analysis |
+
+### Available Tools
+
+**Athena Tools:**
+- `athena_get_story` - Load BMAD story context
+- `athena_update_status` - Update sprint status
+- `athena_get_context` - Get cached story context
+- `athena_config` - View configuration
+- `athena_parallel` - Parallel story execution (planned)
+
+**oh-my-opencode Tools:**
+- LSP tools (hover, goto definition, find references, rename, etc.)
+- AST-grep tools (search, replace)
+- Background agent tools
+- Interactive bash (tmux)
+
+**MCP Tools:**
+- context7 (documentation lookup)
+- websearch_exa (web search)
+- grep_app (GitHub search)
+
+## Modifying Configuration
+
+### Option 1: Reinstall with Different Options
+
+```bash
+npx opencode-athena install
+```
+
+Interactive installer will prompt for new configuration.
+
+### Option 2: Use a Preset
+
+```bash
+npx opencode-athena install --preset minimal
+npx opencode-athena install --preset standard
+npx opencode-athena install --preset enterprise
+npx opencode-athena install --preset solo-quick
+```
+
+### Option 3: Edit Config Files Directly
+
+**Edit Athena settings:**
+```bash
+# Global
+nano ~/.config/opencode/athena.json
+
+# Project-specific
+nano .opencode/athena.json
+```
+
+**Edit agent models:**
+```bash
+# Global
+nano ~/.config/opencode/oh-my-opencode.json
+
+# Project-specific
+nano .opencode/oh-my-opencode.json
+```
+
+### Option 4: Update Specific Settings
+
+After editing config files, restart OpenCode to apply changes.
+
+## Troubleshooting
+
+### Check Installation Health
+
+Run the doctor command in terminal:
+
+```bash
+npx opencode-athena doctor
+```
+
+This checks:
+- Node.js version
+- OpenCode version
+- Plugin installation
+- Configuration validity
+- Authentication status
+
+### Auto-Fix Common Issues
+
+```bash
+npx opencode-athena doctor --fix
+```
+
+This will attempt to:
+- Reinstall missing plugins
+- Fix broken symlinks
+- Repair config files
+- Re-copy bridge commands
+
+### 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 project |
+| Commands not available | Verify commands in `~/.config/opencode/command/` |
+| Agent model errors | Check `oh-my-opencode.json` configuration |
+
+### Verify Plugin Installation
+
+Check installed plugins:
+
+```bash
+ls ~/.config/opencode/node_modules/ | grep -E '(opencode-athena|oh-my-opencode)'
+```
+
+Check OpenCode config:
+
+```bash
+cat ~/.config/opencode/opencode.json | grep plugin
+```
+
+Should include:
+- `opencode-athena/plugin`
+- `oh-my-opencode`
+
+### Check Authentication
+
+For each provider you've configured:
+
+```bash
+opencode auth login
+# Select provider and authenticate
+```
+
+## Version Information
+
+### Check Versions
+
+```bash
+# Athena CLI version
+npx opencode-athena --version
+
+# Installed package versions
+cd ~/.config/opencode
+npm list opencode-athena oh-my-opencode
+```
+
+### Update to Latest
+
+```bash
+npx opencode-athena update
+```
+
+This updates:
+- opencode-athena CLI
+- oh-my-opencode plugin
+- Auth plugins
+- Bridge commands
+
+## Getting Help
+
+### Documentation
+
+- [OpenCode Athena GitHub](https://github.com/ZebulonRouseFrantzich/opencode-athena)
+- [oh-my-opencode GitHub](https://github.com/code-yeongyu/oh-my-opencode)
+- [BMAD METHOD GitHub](https://github.com/bmad-method/bmad-method)
+
+### Report Issues
+
+If you encounter bugs:
+
+1. Run `npx opencode-athena doctor` and save output
+2. Note what you were doing when the issue occurred
+3. Open an issue on the appropriate GitHub repo
+
+### Quick Reference Card
+
+```
+┌────────────────────────────────────────────────────────────┐
+│                    ATHENA QUICK REFERENCE                   │
+├────────────────────────────────────────────────────────────┤
+│                                                             │
+│  COMMANDS:                                                  │
+│    /athena-dev      → Implement a story                    │
+│    /athena-review   → Quality gate review                  │
+│    /athena-debug    → Debug with Oracle                    │
+│    /athena-research → Research with Librarian              │
+│    /athena-status   → Sprint status                        │
+│    /athena-info     → This help                            │
+│                                                             │
+│  AGENTS:                                                    │
+│    @oracle          → Deep reasoning, code review          │
+│    @librarian       → Research, docs, examples             │
+│    @explore         → Fast codebase search                 │
+│    @frontend-ui-ux-engineer → UI/UX work                   │
+│                                                             │
+│  TOOLS:                                                     │
+│    athena_get_story      → Load story context              │
+│    athena_update_status  → Update story status             │
+│    athena_config         → View configuration              │
+│                                                             │
+│  CLI:                                                       │
+│    npx opencode-athena install   → Install/configure       │
+│    npx opencode-athena update    → Update plugins          │
+│    npx opencode-athena doctor    → Diagnose issues         │
+│    npx opencode-athena info      → Show config             │
+│                                                             │
+└────────────────────────────────────────────────────────────┘
+```