manual_slop/docs/superpowers/specs/2026-05-16-opencode-agent-fix-design.md

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