opencode-sdlc-plugin 0.2.1 → 0.3.2

package/commands/sdlc-info.md

@@ -0,0 +1,325 @@
+---
+description: Display OpenCode SDLC configuration and toolkit information
+---
+
+# SDLC Info - Toolkit Information
+
+Display current OpenCode SDLC configuration, available capabilities, and troubleshooting information.
+
+## View Current Configuration
+
+Call **sdlc_config** to see the current setup:
+
+```
+sdlc_config()
+```
+
+This displays:
+- SDLC version
+- Configured LLM providers
+- Agent model assignments
+- BMAD settings
+- Enabled features
+- MCP servers
+
+## Configuration Sections
+
+### View Specific Section
+
+To view only a specific section:
+
+```
+sdlc_config({ section: "subscriptions" })
+sdlc_config({ section: "models" })
+sdlc_config({ section: "bmad" })
+sdlc_config({ section: "features" })
+sdlc_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/
+├── sdlc.json          # SDLC-specific settings
+├── oh-my-opencode.json  # Agent model configuration
+├── opencode.json        # Plugin registration
+└── package.json         # Installed plugin packages
+```
+
+### Project Configuration (overrides global)
+
+```
+[project]/.opencode/
+├── sdlc.json          # Project-specific SDLC settings
+└── oh-my-opencode.json  # Project-specific agent models
+```
+
+## Toolkit Capabilities
+
+### Bridge Commands
+
+| Command | Description | Invokes |
+|---------|-------------|---------|
+| `/sdlc-dev` | Implement a BMAD story | Sisyphus + subagents |
+| `/sdlc-review` | Quality gate review | Oracle (code + adversarial) |
+| `/sdlc-debug` | Debug complex issues | Oracle |
+| `/sdlc-research` | Research patterns/docs | Librarian |
+| `/sdlc-status` | Sprint status management | SDLC tools |
+| `/sdlc-info` | This command | sdlc_config |
+| `/sdlc-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
+
+**SDLC Tools:**
+- `sdlc_get_story` - Load BMAD story context
+- `sdlc_update_status` - Update sprint status
+- `sdlc_get_context` - Get cached story context
+- `sdlc_config` - View configuration
+- `sdlc_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-sdlc install
+```
+
+Interactive installer will prompt for new configuration.
+
+### Option 2: Use a Preset
+
+```bash
+npx opencode-sdlc install --preset minimal
+npx opencode-sdlc install --preset standard
+npx opencode-sdlc install --preset enterprise
+npx opencode-sdlc install --preset solo-quick
+```
+
+### Option 3: Edit Config Files Directly
+
+**Edit SDLC settings:**
+```bash
+# Global
+nano ~/.config/opencode/sdlc.json
+
+# Project-specific
+nano .opencode/sdlc.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-sdlc doctor
+```
+
+This checks:
+- Node.js version
+- OpenCode version
+- Plugin installation
+- Configuration validity
+- Authentication status
+
+### Auto-Fix Common Issues
+
+```bash
+npx opencode-sdlc 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-sdlc|oh-my-opencode)'
+```
+
+Check OpenCode config:
+
+```bash
+cat ~/.config/opencode/opencode.json | grep plugin
+```
+
+Should include:
+- `opencode-sdlc/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
+# SDLC CLI version
+npx opencode-sdlc --version
+
+# Installed package versions
+cd ~/.config/opencode
+npm list opencode-sdlc oh-my-opencode
+```
+
+### Update to Latest
+
+```bash
+npx opencode-sdlc update
+```
+
+This updates:
+- opencode-sdlc CLI
+- oh-my-opencode plugin
+- Auth plugins
+- Bridge commands
+
+## Getting Help
+
+### Documentation
+
+- [OpenCode SDLC GitHub](https://github.com/ZebulonRouseFrantzich/opencode-sdlc)
+- [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-sdlc 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:                                                  │
+│    /sdlc-dev      → Implement a story                    │
+│    /sdlc-review   → Quality gate review                  │
+│    /sdlc-debug    → Debug with Oracle                    │
+│    /sdlc-research → Research with Librarian              │
+│    /sdlc-status   → Sprint status                        │
+│    /sdlc-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:                                                     │
+│    sdlc_get_story      → Load story context              │
+│    sdlc_update_status  → Update story status             │
+│    sdlc_config         → View configuration              │
+│                                                             │
+│  CLI:                                                       │
+│    npx opencode-sdlc install   → Install/configure       │
+│    npx opencode-sdlc update    → Update plugins          │
+│    npx opencode-sdlc doctor    → Diagnose issues         │
+│    npx opencode-sdlc info      → Show config             │
+│                                                             │
+└────────────────────────────────────────────────────────────┘
+```

package/commands/sdlc-parallel.md

@@ -0,0 +1,283 @@
+---
+description: Work on multiple stories in parallel using background agents
+---
+
+# SDLC Parallel - Multi-Story Execution
+
+> **⚠️ NOT YET IMPLEMENTED**
+> 
+> This command describes **planned functionality** that is not yet available. The `sdlc_parallel` tool is a placeholder. This document describes the intended behavior for future implementation.
+
+## Git Operations Policy
+
+**⚠️ AUTOMATIC GIT OPERATIONS ARE PROHIBITED**
+
+You must NOT perform any git operations automatically:
+- ❌ Do NOT run `git commit` to save changes
+- ❌ Do NOT run `git push` to push to remote
+- ❌ Do NOT run `git checkout -b` or `git branch` to create branches
+- ❌ Do NOT run `git merge`, `git rebase`, or `git cherry-pick`
+- ❌ Do NOT run `gh pr create` or other GitHub CLI operations
+
+**Git operations are ONLY permitted if the user explicitly requests them.**
+
+When working on multiple stories in parallel, git operations become especially important to coordinate manually. Always ask the user before performing any git operations.
+
+---
+
+Execute multiple BMAD stories simultaneously using background agents for maximum throughput.
+
+## Planned Behavior
+
+### When to Use This Command
+
+- Multiple independent stories in the sprint backlog
+- Stories work on different parts of the codebase (no file conflicts)
+- You want to maximize development throughput
+- Stories have no dependencies on each other
+
+### Prerequisites
+
+- Multiple pending stories in `sprint-status.yaml`
+- Stories must be independent (no blocking dependencies)
+- Stories should not modify the same files
+- Sufficient context window capacity for coordination
+
+## Planned Workflow
+
+### Step 1: Check Sprint Status
+
+First, view available stories:
+
+```
+sdlc_get_story()
+```
+
+Identify stories that can safely run in parallel:
+- ✅ Different modules or directories
+- ✅ No shared file modifications
+- ✅ No data dependencies
+- ❌ Avoid stories that modify the same files
+
+### Step 2: Analyze for Conflicts (Planned)
+
+The `sdlc_parallel` tool will analyze stories for potential conflicts:
+
+```
+sdlc_parallel({
+  storyIds: ["2.1", "2.2", "2.3"],
+  dryRun: true  // Just check for conflicts, don't execute
+})
+```
+
+**Planned conflict detection:**
+- Parse story requirements for file paths mentioned
+- Check architecture.md for overlapping components
+- Identify shared dependencies
+- Report potential conflicts before execution
+
+### Step 3: Execute in Parallel (Planned)
+
+```
+sdlc_parallel({
+  storyIds: ["2.1", "2.2", "2.3"],
+  waitForCompletion: false  // Return immediately, run in background
+})
+```
+
+**Planned execution flow:**
+1. Validate no conflicts between selected stories
+2. Mark all stories as `in_progress` in `sprint-status.yaml`
+3. Spawn background agent for each story
+4. Each agent runs `/sdlc-dev` workflow independently
+5. Coordinate to prevent concurrent file modifications
+6. Report completion as each story finishes
+
+### Step 4: Monitor Progress (Planned)
+
+**Planned monitoring capabilities:**
+
+```
+sdlc_parallel({
+  action: "status"
+})
+```
+
+Returns:
+- Which stories are running
+- Progress of each background agent
+- Any conflicts or blockers encountered
+- Estimated completion time
+
+### Step 5: Handle Completion (Planned)
+
+When stories complete:
+- `sprint-status.yaml` updated automatically
+- Notification sent for each completion
+- Combined test run suggested
+- Integration check recommended
+
+## Planned Features
+
+### Conflict Prevention
+
+| Conflict Type | Detection | Resolution |
+|---------------|-----------|------------|
+| Same file edits | Pre-execution analysis | Reject parallel execution |
+| Shared dependencies | Architecture analysis | Sequential for conflict area |
+| Data dependencies | Story requirement parsing | Enforce story order |
+
+### Coordination Strategies (Planned)
+
+**File-level locking:**
+- First agent to touch a file gets exclusive access
+- Other agents wait if they need the same file
+
+**Module-level partitioning:**
+- Assign stories to non-overlapping code areas
+- Detect boundary violations
+
+**Merge coordination:**
+- If conflicts occur, pause and notify
+- User resolves manually or chooses which version wins
+
+### Configuration (Planned)
+
+```json
+// sdlc.json
+{
+  "parallel": {
+    "maxConcurrentStories": 3,
+    "conflictStrategy": "prevent", // or "coordinate" or "manual"
+    "notifyOnComplete": true,
+    "autoRunTests": true
+  }
+}
+```
+
+## Current Workaround
+
+Until `sdlc_parallel` is implemented, you can achieve similar results manually:
+
+### Manual Parallel Workflow
+
+**1. Open multiple terminal sessions:**
+
+```bash
+# Terminal 1 - Primary story (your focus)
+opencode
+# Run /sdlc-dev for story 2.1
+
+# Terminal 2 - Background story
+opencode  
+# Run /sdlc-dev for story 2.2
+```
+
+**2. Or use background agents within single session:**
+
+```
+# Start story 2.1 in background
+background_task({
+  agent: "Sisyphus",
+  prompt: "Implement BMAD story 2.1. Load context with sdlc_get_story({storyId: '2.1'}), implement following /sdlc-dev workflow, update status when complete.",
+  description: "Story 2.1 implementation"
+})
+
+# Work on story 2.2 yourself
+/sdlc-dev 2.2
+```
+
+**3. Coordinate manually:**
+
+- Keep track of which files each story modifies
+- Avoid parallel work on same files
+- Run combined tests after both complete
+- Check for integration issues
+
+## Design Considerations for Implementation
+
+### Background Agent Integration
+
+The planned implementation will use oh-my-opencode's background agent system:
+
+```typescript
+// Conceptual implementation
+async function executeParallel(storyIds: string[]) {
+  // 1. Validate no conflicts
+  const conflicts = await detectConflicts(storyIds);
+  if (conflicts.length > 0) {
+    return { error: "Conflicts detected", conflicts };
+  }
+  
+  // 2. Mark all as in_progress
+  for (const id of storyIds) {
+    await updateSprintStatus(id, "in_progress");
+  }
+  
+  // 3. Spawn background agents
+  const tasks = storyIds.map(id => ({
+    agent: "Sisyphus",
+    prompt: generateStoryPrompt(id),
+  }));
+  
+  // 4. Launch and track
+  const results = await backgroundManager.launchMany(tasks);
+  
+  return { launched: results.length, taskIds: results.map(r => r.id) };
+}
+```
+
+### Conflict Detection Strategy
+
+```typescript
+// Conceptual conflict detection
+async function detectConflicts(storyIds: string[]) {
+  const storyFiles: Map<string, string[]> = new Map();
+  
+  for (const id of storyIds) {
+    const story = await loadStory(id);
+    const files = extractMentionedFiles(story);
+    const architectureFiles = extractArchitectureFiles(story);
+    storyFiles.set(id, [...files, ...architectureFiles]);
+  }
+  
+  // Find overlapping files
+  const conflicts = [];
+  for (const [id1, files1] of storyFiles) {
+    for (const [id2, files2] of storyFiles) {
+      if (id1 >= id2) continue;
+      const overlap = files1.filter(f => files2.includes(f));
+      if (overlap.length > 0) {
+        conflicts.push({ stories: [id1, id2], files: overlap });
+      }
+    }
+  }
+  
+  return conflicts;
+}
+```
+
+## Limitations
+
+Even when implemented:
+
+- **Context limits**: Each background agent uses context window
+- **Coordination overhead**: Managing multiple agents has overhead
+- **Conflict resolution**: Some conflicts require human judgment
+- **Testing complexity**: Parallel changes complicate testing
+
+## Tips for Future Use
+
+- **Start small**: Test with 2 stories before scaling up
+- **Choose wisely**: Pick stories in truly independent areas
+- **Monitor actively**: Check progress regularly
+- **Test together**: Run full test suite after parallel completion
+- **Review carefully**: Parallel work may have subtle integration issues
+
+## Related Commands
+
+| Command | Use When |
+|---------|----------|
+| `/sdlc-dev` | Single story implementation |
+| `/sdlc-status` | Check sprint status and pending stories |
+| `/sdlc-review` | Quality gate after parallel completion |