# 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