docs(superpowers): Add agent fix design and implementation plan
This commit is contained in:
@@ -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 "<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?**
|
||||
Reference in New Issue
Block a user