diff --git a/docs/superpowers/plans/2026-05-16-opencode-agent-fix-plan.md b/docs/superpowers/plans/2026-05-16-opencode-agent-fix-plan.md new file mode 100644 index 00000000..24a2df50 --- /dev/null +++ b/docs/superpowers/plans/2026-05-16-opencode-agent-fix-plan.md @@ -0,0 +1,442 @@ +# 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 "" ` +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?** \ No newline at end of file