| name | plugin-testing |
| description | Verify plugin spec requirements with actionable test cases. Use when testing reflection or TTS plugins, validating code changes, or running the test suite before deployment. |
| metadata | {"author":"opencode-reflection-plugin","version":"1.0"} |
Plugin Testing Checklist
Verify plugin spec requirements with actionable test cases for the reflection and TTS plugins.
Plugin Specifications
Reflection Plugin (reflection-3.ts)
Purpose
Evaluates task completion when the agent goes idle. If the task is incomplete, sends feedback to continue work.
Spec Requirements
| ID | Requirement | Description |
|---|
| R1 | Uses RECENT human input | Extract the most recent human message as the task (not the first) |
| R2 | Returns feedback only if INCOMPLETE | Only call promptAsync() when verdict.complete === false |
| R3 | No feedback if COMPLETE | Complete tasks show toast only, no prompt (prevents infinite loop) |
| R4 | No console.log | No logging to avoid breaking CLI output |
| R5 | Stores in .reflection/ | Save reflection data (task, result, tools, prompt, verdict, timestamp) to .reflection/ directory |
| R6 | Skip judge sessions | Never reflect on judge sessions (contain "TASK VERIFICATION") |
| R7 | Skip aborted sessions | Never reflect on sessions cancelled by user (Esc key) |
| R8 | Attempt limiting | Max 3 reflection attempts per session before giving up |
| R9 | Reset on new input | Reset attempt counter when user provides new input |
| R10 | Concurrent protection | Prevent multiple simultaneous reflections on same session |
Data Storage Format (.reflection/)
{
"task": "string - the most recent human message",
"result": "string - the assistant's response (truncated to 2000 chars)",
"tools": "string - last 10 tool calls",
"prompt": "string - the full judge prompt sent",
"verdict": {
"complete": "boolean",
"feedback": "string"
},
"timestamp": "ISO 8601 timestamp"
}
TTS Plugin (tts.ts)
Purpose
Reads the agent's final response aloud when a session completes.
Spec Requirements
| ID | Requirement | Description |
|---|
| T1 | Default engine is Coqui | loadConfig() defaults to engine: "coqui" |
| T2 | Stores in .tts/ | Save TTS data (originalText, cleanedText, spokenText, engine, timestamp) to .tts/ directory |
| T3 | Skip judge sessions | Never speak judge session responses |
| T4 | Skip incomplete sessions | Only speak when session is complete |
| T5 | Speech lock | Prevent multiple agents from speaking simultaneously |
| T6 | Text cleaning | Remove code blocks, markdown, URLs before speaking |
| T7 | Text truncation | Truncate to 1000 chars max |
| T8 | Engine fallback | Fall back to OS TTS if configured engine fails |
| T9 | Multiple engines | Support coqui, chatterbox, and os engines |
| T10 | Server mode | Keep TTS model loaded for fast subsequent requests |
Data Storage Format (.tts/)
{
"originalText": "string - raw assistant response",
"cleanedText": "string - after removing code/markdown",
"spokenText": "string - final text sent to TTS (may be truncated)",
"engine": "string - coqui|chatterbox|os",
"timestamp": "ISO 8601 timestamp"
}
Testing Checklist
Pre-requisites
Reflection Plugin Tests
R1: Uses RECENT human input
R2: Returns feedback only if INCOMPLETE
R3: No feedback if COMPLETE
R4: No console.log
R5: Stores in .reflection/
R6: Skip judge sessions
R7: Skip aborted sessions
R8: Attempt limiting
R9: Reset on new input
R10: Concurrent protection
TTS Plugin Tests
T1: Default engine is Coqui
T2: Stores in .tts/
T3: Skip judge sessions
T4: Skip incomplete sessions
T5: Speech lock
T6: Text cleaning
T7: Text truncation
T8: Engine fallback
T9: Multiple engines
T10: Server mode
Running Tests
Unit Tests
cd /Users/engineer/workspace/opencode-reflection-plugin
npm test
E2E Tests (CRITICAL - must always run)
cd /Users/engineer/workspace/opencode-reflection-plugin
OPENCODE_E2E=1 npm run test:e2e
Manual TTS Test
npm run test:tts:manual
Verify Deployment
ls -la ~/.config/opencode/plugin/
diff reflection-3.ts ~/.config/opencode/plugin/reflection.ts
diff tts.ts ~/.config/opencode/plugin/tts.ts
cat ~/.config/opencode/tts.json
Verify Data Storage (after running a task)
ls -la .reflection/
cat .reflection/*.json | head -50
ls -la .tts/
cat .tts/*.json | head -50
Known Issues
-
Reflection may not trigger in test environments - If tasks complete very quickly before session.idle fires, reflection may not run. This is expected behavior, not a bug.
-
TTS Coqui server startup time - First TTS request with Coqui may take 30-60 seconds while model downloads and loads. Subsequent requests are fast due to server mode.
