# OpenCode Agent Definition Fix Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Fix OpenCode agent definition files so subagents spawned via @mention follow conductor workflow (1-space indentation, TDD, checkpoints, atomic commits)

**Architecture:** Rewrite `.opencode/agents/tier3-worker.md` and `.opencode/agents/tier4-qa.md` to add CRITICAL enforcement blocks, TDD phase structure, and pre-delegation checkpoint protocols. Tier 2 and Tier 1 agents are secondary targets.

**Tech Stack:** OpenCode agent definitions (Markdown with YAML frontmatter), Manual Slop MCP tools

---

## File Structure

- **Modify:** `.opencode/agents/tier3-worker.md` - Add enforcement blocks, TDD structure
- **Modify:** `.opencode/agents/tier4-qa.md` - Add architecture reference, strengthen analysis format
- **Modify:** `.opencode/agents/tier2-tech-lead.md` - Add delegation enforcement, phase completion protocol
- **Modify:** `.opencode/agents/tier1-orchestrator.md` - Add track initialization workflow

---

## Phase 1: Fix Tier 3 Worker Agent Definition

### Task 1.1: Add CRITICAL Indentation Block

**Files:**
- Modify: `.opencode/agents/tier3-worker.md`

- [ ] **Step 1: Read current tier3-worker.md header section**

Read `.opencode/agents/tier3-worker.md` lines 1-50 to identify insertion point after frontmatter.

- [ ] **Step 2: Add CRITICAL indentation block after "STRICT SYSTEM DIRECTIVE"**

Insert this block immediately after the STRICT SYSTEM DIRECTIVE line:

```markdown
## CRITICAL: 1-Space Indentation for Python

**ALL Python code MUST use exactly 1 (ONE) space for indentation.**

VIOLATIONS:
- Using 4 spaces or tabs will corrupt the codebase
- Native edit tools destroy 1-space indentation - use MCP tools ONLY

MCP Edit Tools (SAFE):
- `manual-slop_edit_file` - find/replace, preserves indentation
- `manual-slop_py_update_definition` - replace function/class
- `manual-slop_set_file_slice` - replace line range

DO NOT use native `edit` or `write` tools on Python files.
```

- [ ] **Step 3: Commit**

```bash
git add .opencode/agents/tier3-worker.md
git commit -m "fix(agents): Add CRITICAL 1-space indentation block to tier3-worker"
```

### Task 1.2: Add Pre-Delegation Checkpoint Protocol

**Files:**
- Modify: `.opencode/agents/tier3-worker.md` (same file, different section)

- [ ] **Step 1: Read tier3-worker.md around "Task Start Checklist"**

Read lines 45-80 to find the Task Start Checklist section.

- [ ] **Step 2: Add Pre-Delegation Checkpoint Protocol before Task Start Checklist**

Insert this section:

```markdown
## Pre-Delegation Checkpoint Protocol (MANDATORY)

Before implementing ANY code change:

1. **Stage your work:** `manual-slop_run_powershell` with `git add .`
2. **Why:** Prevents work loss if the implementation fails or needs rollback
3. **When:** Always - before touching any file that matters

This is NOT optional. It is the difference between recoverable and catastrophic failure.
```

- [ ] **Step 3: Commit**

```bash
git add .opencode/agents/tier3-worker.md
git commit -m "fix(agents): Add pre-delegation checkpoint protocol to tier3-worker"
```

### Task 1.3: Add TDD Phase Enforcement

**Files:**
- Modify: `.opencode/agents/tier3-worker.md` (same file, different section)

- [ ] **Step 1: Read tier3-worker.md around "Task Execution Protocol"**

Read lines 60-120 to find the Task Execution Protocol section.

- [ ] **Step 2: Enhance Task Execution Protocol with TDD Phase Structure**

Replace the existing "Task Execution Protocol" section with:

```markdown
## Task Execution Protocol (MANDATORY TDD)

### Phase 1: RED - Write Failing Test
- Write a test that defines the expected behavior
- Run: `manual-slop_run_powershell` with `uv run pytest tests/path/test.py -v`
- Confirm: Test MUST fail before proceeding
- DO NOT skip this phase

### Phase 2: GREEN - Implement to Pass
- Implement the minimal code to make the test pass
- Run tests again
- Confirm: Test MUST pass
- DO NOT skip this phase

### Phase 3: REFACTOR - Optional
- With passing tests, improve code quality
- DO NOT change behavior
- Re-run tests to confirm still passing

### Commit Protocol (ATOMIC PER TASK)
After each task completion:
1. `manual-slop_run_powershell` with `git add .`
2. `git commit -m "feat(scope): description"`
3. DO NOT batch commits across tasks
```

- [ ] **Step 3: Commit**

```bash
git add .opencode/agents/tier3-worker.md
git commit -m "fix(agents): Add TDD phase enforcement to tier3-worker"
```

### Task 1.4: Add BLOCKED Protocol

**Files:**
- Modify: `.opencode/agents/tier3-worker.md` (same file, different section)

- [ ] **Step 1: Read tier3-worker.md end of file**

Read lines 120-150 to find where to insert BLOCKED protocol.

- [ ] **Step 2: Add BLOCKED Protocol section at end of file**

Append before the Limitations section:

```markdown
## BLOCKED Protocol

If you cannot complete the task:

1. Start your response with: `BLOCKED:`
2. Explain exactly why you cannot proceed
3. List what information or changes would unblock you
4. DO NOT attempt partial implementations that break the build

Examples of BLOCKED conditions:
- Missing required context about the codebase
- Task requires architectural decisions not in the spec
- Target file/line range does not exist as described
- Cyclic dependency discovered that wasn't documented
```

- [ ] **Step 3: Commit**

```bash
git add .opencode/agents/tier3-worker.md
git commit -m "fix(agents): Add BLOCKED protocol to tier3-worker"
```

---

## Phase 2: Fix Tier 4 QA Agent Definition

### Task 2.1: Add Architecture Reference to Tier 4 QA

**Files:**
- Modify: `.opencode/agents/tier4-qa.md`

- [ ] **Step 1: Read current tier4-qa.md**

Read `.opencode/agents/tier4-qa.md` lines 1-80 to understand current structure.

- [ ] **Step 2: Add Architecture Reference section after "Context Amnesia"**

Insert after Context Amnesia section:

```markdown
## Architecture Reference

When analyzing errors, trace data flow through thread domains documented in:
- `docs/guide_architecture.md`: Thread domains, event system, AI client, HITL mechanism
- `docs/guide_mma.md`: 4-tier orchestration, DAG engine, worker lifecycle

Key threading model:
- GUI main thread: UI rendering only
- asyncio worker thread: AI communication
- HookServer thread: API hook handling
- NEVER write GUI state from background threads
```

- [ ] **Step 3: Commit**

```bash
git add .opencode/agents/tier4-qa.md
git commit -m "fix(agents): Add architecture reference to tier4-qa"
```

### Task 2.2: Strengthen Tier 4 QA Analysis Format

**Files:**
- Modify: `.opencode/agents/tier4-qa.md`

- [ ] **Step 1: Read tier4-qa.md around "Root Cause Analysis"**

Read lines 60-100 to find the Root Cause Analysis section.

- [ ] **Step 2: Enhance Root Cause Analysis with data flow tracing instructions**

Replace the existing Analysis Protocol section with enhanced version:

```markdown
## Analysis Protocol

### 1. Understand the Error
- Read the provided error output, test failure, or log carefully
- Identify affected files from traceback
- Do NOT assume - base analysis on evidence only

### 2. Investigate
Use MCP tools to understand the context:
- `manual-slop_read_file` - Read relevant source files
- `manual-slop_py_find_usages` - Search for related patterns
- `manual-slop_search_files` - Find related files
- `manual-slop_get_git_diff` - Check recent changes

### 3. Root Cause Analysis (MANDATORY FORMAT)

Provide a structured analysis in this exact format:

```
## Error Analysis

### Summary
[One-sentence description of the error]

### Root Cause
[Detailed explanation of WHY the error occurred - not just what went wrong]

### Evidence
[File:line references supporting the analysis]

### Data Flow Trace
[How data moved through the system to cause this error]
[Reference specific thread domains if applicable: GUI main, asyncio worker, HookServer]

### Impact
[What functionality is affected]

### Recommendations
[Suggested fixes - but DO NOT implement them]
```

### 4. DO NOT FIX
- Your job is ANALYSIS ONLY
- Do NOT modify any files
- Do NOT write code
- Return the analysis and let the controller decide
```

- [ ] **Step 3: Commit**

```bash
git add .opencode/agents/tier4-qa.md
git commit -m "fix(agents): Strengthen tier4-qa analysis format"
```

---

## Phase 3: Fix Tier 2 Tech Lead Agent Definition

### Task 3.1: Add Delegation Enforcement to Tier 2

**Files:**
- Modify: `.opencode/agents/tier2-tech-lead.md`

- [ ] **Step 1: Read current tier2-tech-lead.md**

Read `.opencode/agents/tier2-tech-lead.md` lines 1-100.

- [ ] **Step 2: Add CRITICAL Delegation Rules after STRICT SYSTEM DIRECTIVE**

Insert after STRICT SYSTEM DIRECTIVE:

```markdown
## CRITICAL: Delegate Implementation - Do NOT Implement Directly

You are Tier 2 Tech Lead. Your role is ARCHITECTURE and DELEGATION.

**NEVER** implement code directly. ALWAYS delegate to Tier 3 via Task tool.

**Delegation Pattern:**
1. Research with skeleton tools
2. Draft surgical prompt with WHERE/WHAT/HOW/SAFETY
3. Delegate to Tier 3 via Task tool
4. Verify result

**Pre-Delegation Checkpoint:**
Before delegating ANY non-trivial change:
1. Run: `manual-slop_run_powershell` with `git add .`
2. Reason: Prevents work loss if subagent fails
```

- [ ] **Step 3: Commit**

```bash
git add .opencode/agents/tier2-tech-lead.md
git commit -m "fix(agents): Add delegation enforcement to tier2-tech-lead"
```

### Task 3.2: Add Phase Completion Protocol to Tier 2

**Files:**
- Modify: `.opencode/agents/tier2-tech-lead.md`

- [ ] **Step 1: Read tier2-tech-lead.md around "TDD Protocol" section**

Read lines 100-150 to find the TDD Protocol section.

- [ ] **Step 2: Add Phase Completion Verification Protocol**

After TDD Protocol section, add:

```markdown
## Phase Completion Protocol

When all tasks in a phase are complete:

1. **Run verification:** `/conductor-verify`
2. **Present results:** Show user the results
3. **Await confirmation:** Wait for user yes/no
4. **Create checkpoint:** `git add . && git commit -m "conductor(checkpoint): Phase N complete"`
5. **Attach note:** `git notes add -m "<verification report>" <commit_hash>`
6. **Update plan:** Mark phase `[x]` with checkpoint SHA in plan.md
```

- [ ] **Step 3: Commit**

```bash
git add .opencode/agents/tier2-tech-lead.md
git commit -m "fix(agents): Add phase completion protocol to tier2-tech-lead"
```

---

## Phase 4: Fix Tier 1 Orchestrator Agent Definition

### Task 4.1: Add Track Initialization Workflow

**Files:**
- Modify: `.opencode/agents/tier1-orchestrator.md`

- [ ] **Step 1: Read current tier1-orchestrator.md**

Read `.opencode/agents/tier1-orchestrator.md` lines 1-100.

- [ ] **Step 2: Add Track Initialization Protocol after Session Start Checklist**

Find the Session Start Checklist section and add after it:

```markdown
## Track Initialization Protocol

When starting a new track:

1. **Read track context:**
   - `conductor/tracks.md` - active tracks
   - `conductor/tech-stack.md` - technology constraints
   - `conductor/product.md` - product vision

2. **Audit existing state:**
   - Use `manual-slop_py_get_code_outline` to map files
   - Use `manual-slop_get_git_diff` to check recent changes
   - Document "Current State Audit" in spec

3. **Create track spec:**
   - Follow spec template with: Overview, Current State Audit, Goals, Requirements
   - Include Architecture Reference section

4. **Initialize track directory:**
   - Create `conductor/tracks/{name}_{YYYYMMDD}/`
   - Write spec.md, plan.md, metadata.json
```

- [ ] **Step 3: Commit**

```bash
git add .opencode/agents/tier1-orchestrator.md
git commit -m "fix(agents): Add track initialization workflow to tier1-orchestrator"
```

---

## Verification

After all phases complete:

- [ ] **Step 1: Verify indentation block in tier3-worker.md**

Run: `grep -n "1-space" .opencode/agents/tier3-worker.md`
Expected: Multiple matches including "CRITICAL"

- [ ] **Step 2: Verify TDD phase structure**

Run: `grep -n "RED\|GREEN\|REFACTOR" .opencode/agents/tier3-worker.md`
Expected: All three phases present

- [ ] **Step 3: Verify checkpoint protocol**

Run: `grep -n "git add \." .opencode/agents/tier3-worker.md`
Expected: Pre-delegation checkpoint present

- [ ] **Step 4: Verify tier4-qa architecture reference**

Run: `grep -n "guide_architecture" .opencode/agents/tier4-qa.md`
Expected: Reference present

---

**Plan complete and saved to `docs/superpowers/plans/2026-05-16-opencode-agent-fix-plan.md`. Two execution options:**

**1. Subagent-Driven (recommended)** - Dispatch a fresh subagent per task, review between tasks, fast iteration

**2. Inline Execution** - Execute tasks in this session using executing-plans, batch execution with checkpoints

**Which approach?**