spec to hopefully unfuck opencode

2026-05-16 02:14:43 -04:00
parent e0d219d0dc
commit e6d9374e69
1 changed files with 150 additions and 0 deletions
@@ -0,0 +1,150 @@
+# OpenCode Agent Definition Fix - Design Spec
+
+## Overview
+
+Fix OpenCode agent definitions so subagents spawned via `@mention` (when using superpowers) properly enforce the conductor workflow. Currently subagents fail to follow 1-space indentation, TDD protocols, and delegation rules even when explicitly instructed.
+
+## Current State Audit
+
+### Files Involved
+- `.opencode/agents/tier3-worker.md` - Tier 3 Worker agent definition
+- `.opencode/agents/tier4-qa.md` - Tier 4 QA agent definition
+- `.opencode/agents/tier2-tech-lead.md` - Tier 2 Tech Lead agent definition
+- `.opencode/agents/tier1-orchestrator.md` - Tier 1 Orchestrator agent definition
+
+### Problems Identified
+
+1. **Wrong MCP Tool Naming**
+   - Current: `discovered_tool_py_get_code_outline`, `discovered_tool_run_powershell`
+   - Correct: `manual-slop_py_get_code_outline`, `manual-slop_run_powershell`
+   - Result: Subagents cannot find/locate MCP tools
+
+2. **Insufficient Code Style Enforcement**
+   - "1-space indentation" mentioned but not CRITICAL
+   - No explicit warning about native edit tool destroying indentation
+   - Subagents default to 4-space on unknown files
+
+3. **Missing Conductor Workflow Structure**
+   - No pre-delegation checkpoint protocol (`git add .`)
+   - No atomic commit per-task rules
+   - No TDD Red→Green→Refactor phase enforcement
+   - No mandatory task state tracking in plan.md
+
+4. **Context Amnesia Not Addressed**
+   - Subagents lose all workflow context between tasks
+   - No reminder about stateless operation
+   - No checkpoint/commit reminder system
+
+5. **Tier 3 Worker Mode Incorrect**
+   - `mode: subagent` may cause OpenCode to strip context
+   - May need `mode: primary` for full workflow access
+
+## Goals
+
+1. Subagents spawned via `@mention` follow conductor workflow without deviation
+2. 1-space indentation enforced as CRITICAL for all Python code
+3. TDD phases (Red→Green→Refactor) enforced mandatorily
+4. MCP tool names correct and functional
+5. Pre-delegation checkpoints prevent work loss
+6. Atomic commits per task maintained
+
+## Functional Requirements
+
+### 1. Agent Definition Rewrite
+
+All tier agent files (`.opencode/agents/*.md`) must include:
+
+- **CRITICAL Indentation Block** at top:
+  ```
+  ## CRITICAL: 1-Space Indentation for Python
+  
+  ALL Python code MUST use exactly 1 (ONE) space for indentation.
+  VIOLATION: Using 4 spaces or tabs will corrupt the codebase.
+  ```
+
+- **MCP Tool Mapping Table** (correct names):
+  ```
+  | Native Tool | MCP Tool |
+  |-------------|----------|
+  | read | manual-slop_read_file |
+  | edit | manual-slop_edit_file |
+  | bash | manual-slop_run_powershell |
+  | glob | manual-slop_search_files |
+  ```
+
+- **Pre-Delegation Checkpoint Protocol**:
+  ```
+  ## Pre-Delegation Checkpoint (MANDATORY)
+  
+  Before delegating ANY change:
+  1. Run: git add .
+  2. Reason: Prevents work loss if subagent fails
+  ```
+
+- **TDD Phase Enforcement**:
+  ```
+  ## TDD Protocol
+  
+  1. RED: Write failing test, confirm failure
+  2. GREEN: Implement to pass, confirm pass
+  3. REFACTOR: Optional, with passing tests
+  NEVER skip phases.
+  ```
+
+- **Atomic Commit Rules**:
+  ```
+  ## Commit Protocol
+  
+  After each task: git add . && git commit
+  Do NOT batch commits.
+  ```
+
+### 2. Tier 3 Worker Specific Fixes
+
+- Verify `mode: subagent` is correct for OpenCode's @mention system
+- Add WHERE/WHAT/HOW/SAFETY task structure reminder
+- Add BLOCKED protocol for unresolvable tasks
+- Include Context Amnesia reminder (fresh context each task)
+
+### 3. Tier 4 QA Specific Fixes
+
+- Add DO NOT FIX warning - analysis only
+- Include root cause tracing instructions
+- Add data flow tracing from docs/guide_architecture.md
+
+### 4. Tier 2 Tech Lead Specific Fixes
+
+- Add persistent memory reminder
+- Add surgical prompt structure (WHERE/WHAT/HOW/SAFETY)
+- Add delegation via Task tool instructions
+- Add phase completion verification protocol
+
+### 5. Tier 1 Orchestrator Specific Fixes
+
+- Verify mode: primary for main agent sessions
+- Add track initialization workflow
+- Add product alignment check
+
+## Architecture Reference
+
+Based on:
+- `conductor/workflow.md` - TDD protocol, commit rules
+- `conductor/product-guidelines.md` - Code style (1-space indentation)
+- `opencode.json` - MCP tool definitions (manual-slop_*)
+- superpowers docs - @mention subagent spawning
+
+## Out of Scope
+
+- Changes to superpowers plugin itself
+- Changes to OpenCode core behavior
+- Changes to mma_exec.py (not used in OpenCode flow)
+- Changes to Gemini CLI workflow (separate system)
+
+## Success Criteria
+
+1. All Python files in project use 1-space indentation
+2. Subagents follow TDD protocol without skipping phases
+3. Pre-delegation checkpoints executed before risky operations
+4. MCP tools findable by subagents
+5. Atomic commits maintained per task
+6. Conductor workflow followed without deviation even after corrections