ed/manual_slop
Private
Public Access
0
0
Fork 0
Code Activity
Files
bd20feeaae133165e6d7f63b96a8b962b2fef2cd
manual_slop/docs/superpowers/plans/2026-05-16-opencode-agent-fix-plan.md
T

13 KiB
Raw Blame History

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:

## 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
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:

## 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
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:

## 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
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:

## 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
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:

## 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
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:

## 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
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:

## 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
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:

## 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
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:

## 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
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?

View Git Blame Copy Permalink