From e6d9374e6995e58f765837ea42615c0b2e8523ad Mon Sep 17 00:00:00 2001 From: Ed_ Date: Sat, 16 May 2026 02:14:43 -0400 Subject: [PATCH] spec to hopefully unfuck opencode --- .../2026-05-16-opencode-agent-fix-design.md | 150 ++++++++++++++++++ 1 file changed, 150 insertions(+) create mode 100644 docs/superpowers/specs/2026-05-16-opencode-agent-fix-design.md diff --git a/docs/superpowers/specs/2026-05-16-opencode-agent-fix-design.md b/docs/superpowers/specs/2026-05-16-opencode-agent-fix-design.md new file mode 100644 index 00000000..8d9f15a9 --- /dev/null +++ b/docs/superpowers/specs/2026-05-16-opencode-agent-fix-design.md @@ -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 \ No newline at end of file