Skill: ailois/opencode-acp (version 1.0.0)

--- name: opencode-acp description: Collaborate with OpenCode via ACP protocol for code modifications, refactoring, and feature implementation. metadata: { "openclaw": { "emoji": "🔧", "requires": { "anyBins": ["opencode"] } }, } --- # OpenCode ACP Collaboration Use OpenCode via ACP (Agent Client Protocol) for code modifications, refactoring, and feature implementation. ## Quick Start ### Automated Workflow (Recommended) Use the provided Python script for automated OpenCode collaboration: > On first run, the skill auto-creates a local `.venv` (Python 3.9+) in this skill directory and re-runs inside that environment. > If the current interpreter is below 3.9, it auto-discovers a local Python 3.9+ executable (`python3.12`/`python3.11`/`python3.10`/`python3.9`/`python3`/`python`; on Windows also `py -3.x`). ```bash # Run from this repository root # Simple task python opencode_acp_client.py \ --project /path/to/project \ --task "Add --version flag to CLI" # With verbose logging python opencode_acp_client.py \ --project /path/to/project \ --task "Refactor authentication module" \ --verbose # With custom timeout (default: 600 seconds) python opencode_acp_client.py \ --project /path/to/project \ --task "Build REST API for todos" \ --timeout 1200 ``` **What it does:** 1. Starts OpenCode ACP server 2. Initializes ACP connection 3. Creates session 4. Sends task 5. Monitors progress and displays output 6. Stops OpenCode when done **Output:** - Real-time progress updates - Tool calls and status - Agent messages - Completion status ### Manual Workflow (Advanced) For fine-grained control, use manual JSON-RPC messages: ```bash # Start OpenCode ACP server in background exec pty:true workdir:/path/to/project background:true command:"opencode acp" # Returns sessionId (e.g., "neat-zephyr") # Initialize connection process action:write sessionId:neat-zephyr data:'{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{"fs":{"readTextFile":true,"writeTextFile":true},"terminal":true},"clientInfo":{"name":"Claw","title":"Claw AI Assistant","version":"1.0.0"}}}\n' # Wait for response process action:log sessionId:neat-zephyr # Create session process action:write sessionId:neat-zephyr data:'{"jsonrpc":"2.0","id":1,"method":"session/new","params":{"cwd":"/path/to/project","mcpServers":[]}}\n' # Wait for session ID process action:log sessionId:neat-zephyr # Send task process action:write sessionId:neat-zephyr data:'{"jsonrpc":"2.0","id":2,"method":"session/prompt","params":{"sessionId":"ses_xxx","prompt":[{"type":"text","text":"Your task here"}]}}\n' # Monitor progress process action:log sessionId:neat-zephyr # Kill when done process action:kill sessionId:neat-zephyr ``` ## The Pattern: Plan → Execute → Verify ### Step 1: Analyze Requirements **Your job (as planner):** - Understand user needs - Identify technical constraints - Assess impact and risks **Output:** - Clear, specific requirements - Technical constraints - Risk assessment ### Step 2: Create Plan **Your job (as planner):** - Break down into executable steps - Define acceptance criteria - Provide implementation guidance **Format:** ```markdown # Task: [Task Name] ## Objective [Goal description] ## Requirements 1. [Requirement 1] 2. [Requirement 2] ... ## Acceptance Criteria - ✅ [Criterion 1] - ✅ [Criterion 2] ... ## Implementation Guidance 1. [Step 1] 2. [Step 2] ... ## Verification [How to verify] ``` ### Step 3: Execute with OpenCode **Start OpenCode ACP server:** ```bash exec pty:true workdir:/path/to/project background:true command:"opencode acp" ``` **Initialize connection:** ```json {"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{"fs":{"readTextFile":true,"writeTextFile":true},"terminal":true},"clientInfo":{"name":"Claw","title":"Claw AI Assistant","version":"1.0.0"}}} ``` **Create session:** ```json {"jsonrpc":"2.0","id":1,"method":"session/new","params":{"cwd":"/path/to/project","mcpServers":[]}} ``` **Send task:** ```json {"jsonrpc":"2.0","id":2,"method":"session/prompt","params":{"sessionId":"ses_xxx","prompt":[{"type":"text","text":"[Your plan from Step 2]"}]}} ``` ### Step 4: Monitor Progress **Poll for updates:** ```bash process action:log sessionId:neat-zephyr ``` **Key update types:** - `agent_thought_chunk` - OpenCode's thinking process - `tool_call` - Tool invocations (search, analyze, edit) - `plan` - Task plan updates - `stopReason` - Task completion signal **Stop conditions:** - `stopReason: "end_turn"` - Normal completion - `stopReason: "cancelled"` - Task cancelled - Timeout (suggest: 5-10 minutes) ### Step 5: Verify Results **Verification checklist:** - ✅ Code changes match requirements - ✅ Acceptance criteria met - ✅ Code style consistent - ✅ Tests pass - ✅ No regressions **Verification methods:** 1. Review OpenCode's change summary 2. Run relevant tests 3. Manual verification of key features 4. Code quality check ### Step 6: Cleanup **Stop OpenCode:** ```bash process action:kill sessionId:neat-zephyr ``` **Record results:** - Update memory/YYYY-MM-DD.md - Record success/failure reasons - Document lessons learned ## ⚠️ First-Time Project Setup If this is OpenCode's first time working on a project, initialize the knowledge base first: 1. **Start OpenCode TUI** (not acp mode): ```bash cd /path/to/project opencode ``` 2. **Run initialization**: ``` /init-deep ``` 3. **Wait for completion**: - OpenCode creates hierarchical AGENTS.md knowledge base - Analyzes project structure and code - Builds project context 4. **Exit and restart in acp mode**: - After initialization, exit TUI - Restart with `opencode acp` for collaboration **Why init-deep?** - Helps OpenCode understand project structure - Builds code knowledge graph - Improves execution efficiency and accuracy - Reduces unnecessary exploration and trial-and-error ## OpenCode Configuration **Location:** `/root/.opencode/opencode.json` **Recommended mode:** `sisyphus` (AI orchestrator) ## ACP Protocol Details **Protocol version:** 1 **Transport format:** JSON-RPC 2.0 **Message delimiter:** Newline (\n) **Communication:** stdin/stdout ## Available OpenCode Modes - **sisyphus** (recommended): Powerful AI orchestrator, excels at planning and delegation - **hephaestus**: Autonomous deep worker, end-to-end task completion - **prometheus**: Planning agent - **atlas**: Task orchestrator ## Best Practices ### 1. Clear Requirements **Good:** ```markdown # Task: Add Version Command ## Objective Add --version flag to display project version from package.json ## Requirements 1. Support both --version and -v 2. Display format: "QMD Memory v1.0.0\nOpenClaw memory plugin" 3. Exit after displaying version ## Acceptance Criteria - ✅ `bun src/qmd.ts --version` works - ✅ Version matches package.json - ✅ No impact on existing commands ``` **Bad:** ```markdown Add version command ``` ### 2. Acceptance Criteria **Good criteria:** - Specific, measurable, verifiable - Include positive and negative tests - Consider edge cases **Example:** - ✅ Run `command --version` displays correct version - ✅ Run `command -v` displays same result - ✅ Version matches package.json - ✅ Exit code is 0 - ✅ No impact on other commands ### 3. Progress Monitoring **Key metrics:** - Task breakdown count (typically 3-7 subtasks) - Background agents count (typically 2-4) - Tool call count (search, analyze, edit) - Execution time (typically 2-10 minutes) **Warning signs:** - Long silence (> 2 minutes) - Repeated error messages - Tool call failures - Timeout ### 4. Error Handling **Common errors:** 1. **GLIBC version issues**: Some tools (like ast_grep) may be incompatible - Solution: OpenCode auto-switches to other tools 2. **Agent not found**: e.g., "librarian" agent unavailable - Solution: OpenCode uses other agents 3. **Timeout**: Task execution too long - Solution: Break into smaller tasks or increase timeout ## Collaboration Principles ### Planner's Responsibilities 1. **Clear requirements**: - Specific, measurable, verifiable - Include context and constraints - Provide examples and references 2. **Reasonable plan**: - Break into small steps - Consider technical feasibility - Estimate workload 3. **Effective verification**: - Clear acceptance criteria - Executable verification methods - Timely feedback ### Executor's Characteristics (OpenCode) 1. **Automatic planning**: - Break requirements into subtasks - Auto-select tools and methods - Parallel execution of multiple tasks 2. **Intelligent execution**: - Use sisyphus mode (AI orchestrator) - Launch background explore agents - Auto-search and analyze code 3. **Continuous feedback**: - Real-time progress reports - Show thinking process - Provide execution summary ## Real-World Example ### Case: Add Version Command to QMD **Requirement:** Add `--version` command-line option **Planner's work:** 1. Analyze requirement: Need to read package.json version, display project info 2. Create plan: - Locate CLI argument parsing logic - Add version flag handling - Implement version info output - Add tests 3. Set acceptance criteria: - `bun src/qmd.ts --version` displays correct version - `-v` alias works - Version matches package.json - No impact on existing features **OpenCode's work:** 1. Auto-break into 5 subtasks 2. Launch 3 explore agents in parallel 3. Search code structure (parseCLI, version info, tests) 4. Implement code changes 5. Run tests for verification **Result:** - ✅ Collaboration mode verified successfully - ✅ OpenCode auto-plans and executes - ✅ Parallel processing improves efficiency - ✅ Real-time progress feedback ## Common Questions ### Q1: What to do for first-time project? **A:** First-time project must initialize knowledge base: 1. Start OpenCode TUI: ```bash cd /path/to/project opencode ``` 2. Run initialization: ``` /init-deep ``` 3. Exit after completion, then use acp mode for collaboration **Purpose:** - Create hierarchical AGENTS.md knowledge base - Analyze project structure and dependencies - Build code context, improve execution efficiency ### Q2: How to choose OpenCode mode? **A:** - **sisyphus** (default): Suitable for most tasks, auto-planning and parallel execution - **hephaestus**: Suitable for complex tasks requiring deep analysis - **prometheus**: Suitable for planning-only scenarios, no execution needed ### Q3: How to handle OpenCode execution failure? **A:** 1. Check error messages and logs 2. Analyze failure reason (unclear requirements? technical limitations?) 3. Adjust plan or requirements 4. Restart OpenCode 5. If multiple failures, consider manual implementation ### Q4: How to optimize collaboration efficiency? **A:** 1. **Clear requirements**: Reduce OpenCode's guessing and trial-and-error 2. **Reasonable breakdown**: Break large tasks into small tasks 3. **Parallel execution**: OpenCode auto-parallelizes 4. **Timely feedback**: Monitor progress, adjust promptly ### Q5: How can other Agents use this workflow? **A:** - **Butler Agent**: When making long-term plans, can delegate code modification tasks to OpenCode - **Challenger Agent**: When finding optimization opportunities, can use OpenCode for quick implementation - **Main Agent**: When receiving user requirements, can coordinate OpenCode execution All Agents follow the same workflow: analyze requirements → create plan → start OpenCode → monitor progress → verify results. ## Rules 1. **Always use pty:true** - OpenCode needs a terminal 2. **Initialize first-time projects** - Run `/init-deep` before first use 3. **Clear requirements** - Specific, measurable, verifiable 4. **Monitor progress** - Check logs regularly, don't just wait 5. **Verify results** - Always check acceptance criteria 6. **Record lessons** - Update memory with successes and failures 7. **Be patient** - Don't kill sessions prematurely 8. **Use process:log** - Check progress without interfering ## Progress Updates When spawning OpenCode in background, keep user informed: - Send 1 short message when starting (what's running + where) - Update only when something changes: - Milestone completes (build finished, tests passed) - OpenCode asks a question / needs input - Error occurs or user action needed - OpenCode finishes (include what changed + where) - If killing session, immediately say why This prevents "Agent failed before reply" confusion. ## Auto-Notify on Completion For long-running tasks, append wake trigger to prompt: ``` ... your task here. When completely finished, run this command to notify me: openclaw system event --text "Done: [brief summary]" --mode now ``` **Example:** ```bash exec pty:true workdir:~/project background:true command:"opencode acp" # ... initialize, create session ... # Send prompt with wake trigger: {"jsonrpc":"2.0","id":2,"method":"session/prompt","params":{"sessionId":"ses_xxx","prompt":[{"type":"text","text":"Build a REST API for todos.\n\nWhen completely finished, run: openclaw system event --text \"Done: Built todos REST API with CRUD endpoints\" --mode now"}]}} ``` This triggers immediate wake event — you get notified in seconds, not minutes. ## Version History - **v1.0** (2026-02-16): Initial version - OpenCode 1.2.1 - ACP protocol version 1 - sisyphus mode - Test project: openclaw-qmd --- **Last updated:** 2026-02-16 **Maintainer:** Claw 🐾 **Status:** ✅ Verified


Security scan verdicts — ClawScan: clean | static analysis:  | VirusTotal: suspicious | SkillSpector: suspicious (MEDIUM)