150 lines
4.7 KiB
Markdown
150 lines
4.7 KiB
Markdown
# 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 |