myworkspace/docs/workflow-integration-guide.md

OpenCode Integration Guide for Cline

This guide explains how Cline can automatically hand off tasks to OpenCode when a task is well-defined, eliminating manual terminal interaction.

Overview

Goal: Cline should orchestrate and supervise OpenCode, automatically handing off well-defined tasks for autonomous iteration.

Current State:

• OpenCode CLI runs in terminal (TUI)
• Cline operates in IDE
• Both need a bridge for automation

Automation Options

Option 1: Command-Line Script (Simplest)

Create docs/task-handoff-script.sh:

#!/bin/bash
# Hand off task to OpenCode

PROJECT_PATH="${1:-.}"
TASK_DESC="${2:-}"

cd "$PROJECT_PATH"
opencode run "$TASK_DESC"

Cline usage:

1. Cline writes task-brief.md
2. Cline invokes: `bash docs/task-handoff-script.sh "Linkding Browser Extension/LinkdingSync" "Implement Playwright E2E tests"`
3. OpenCode runs autonomously
4. Cline monitors via git checkpoints

Option 2: Batch Task Queue

#!/bin/bash
# task-queue.sh

TASKS=(
  "Linkding Browser Extension/LinkdingSync: Implement Playwright tests for bookmark creation"
  "Linkding Browser Extension/LinkdingSync: Implement Playwright tests for API sync"
  "Linkding Browser Extension/LinkdingSync: Implement Playwright tests for conflict resolution"
)

for task in "${TASKS[@]}"; do
  IFS=':' read -r PROJECT TASK <<< "$task"
  cd "$PROJECT"
  opencode run "$TASK" &
done

wait  # Wait for all tasks

Option 3: MCP Server (Advanced)

Create MCP server spec: docs/opencode-mcp-server.json

Features:

• opencode-launch-task - Launch with task
• opencode-check-status - Check progress
• opencode-rethink - Request re-think
• opencode-complete-task - Approve changes

Option 4: Cline Workflow Markdown

Create @LinkdingSync/task-delegate-to-opencode.md:

# task-delegate-to-opencode.md

## Step 1
Read task-brief.md and AGENTS.md

## Step 2
Validate task is well-defined:
- [ ] Acceptance criteria clear
- [ ] Constraints documented
- [ ] Time estimate reasonable

## Step 3
Launch OpenCode:
```bash
opencode run "Read AGENTS.md and task-brief.md. [GOALS FROM BRIEF]"

Step 4

Monitor progress (git commits, terminal output)

Step 5

At 50%/90% checkpoint:

• Check if on track
• If stuck >2x time: re-evaluate

Step 6

Approve/reject changes

Step 7

Mark complete in tasks.md

## Workflow Diagram

┌─────────────────────────────────────────────────┐ │ 1. CLINE (IDE) - Task Definition │ │ • Write task-brief.md │ │ • Document acceptance criteria │ │ • Estimate time │ └─────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────┐ │ 2. CLINE - Task Validation │ │ • Validate: clear criteria, constraints │ │ • If invalid: revise task-brief.md │ │ • If valid: proceed to handoff │ └─────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────┐ │ 3. AUTOMATED HANDOFF │ │ • Cline invokes: task-handoff-script.sh │ │ • Or: opencode run "..." │ │ • OpenCode starts autonomously │ └─────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────┐ │ 4. OPENCODE (Terminal) - Autonomous Execution │ │ • Reads AGENTS.md │ │ • Reads task-brief.md │ │ • Creates test files │ │ • Runs tests repeatedly │ │ • Reports progress/blockers │ └─────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────┐ │ 5. CLINE - Checkpoint Monitoring │ │ • Git status: git log --oneline -10 │ │ • At 50%: Check progress │ │ • At 90%: Should be near completion │ │ • At 2x: Re-evaluate approach │ │ • At 3x: Strong re-think needed │ └─────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────┐ │ 6. CLINE - Integration & Approval │ │ • Review changes made │ │ • Approve/reject changes │ │ • Add refinements if needed │ │ • Commit and push │ └─────────────────────────────────────────────────┘

## Task Brief Template

```markdown
# task-brief.md

## Context
[Brief background on what led to this task]

## Goal
[What needs to be achieved]

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

## Constraints
- [ ] Constraint 1 (e.g., "Don't modify auth module")
- [ ] Constraint 2 (e.g., "Must use existing API pattern")

## Related Files
- File 1
- File 2

## Time Estimate
[e.g., 45 minutes]

## Checkpoints
- 50%: [what to review]
- 90%: [what to review]

## Chatlog Reference
- Session log: @projectname\chatlog.md

Handoff Trigger Checklist

Cline should hand off to OpenCode when:

• Task brief exists in project root
• AGENTS.md exists with project context
• Acceptance criteria are clear and measurable
• Time estimate is realistic (not vague like "do this")
• Constraints are documented
• No product-level decisions needed during iteration

When NOT to Hand Off

Keep with Cline when:

• Architecture-level decisions needed
• User-facing feature refinement
• Final change approval required
• Cross-project coordination needed
• Task requires multiple human approvals

Monitoring Commands

# Check OpenCode progress
git log --oneline -10
git status

# Check recent commits
git diff HEAD~5..HEAD

# View OpenCode output (if logging enabled)
tail -f @projectname\chatlog.md

# Check for stuck loops (no commits in X minutes)

Re-think Workflow

When OpenCode is stuck:

1. Check time elapsed vs estimate
2. Review recent commits - any meaningful changes?
3. Check error patterns - same error repeating?
4. Review AGENTS.md - missing context?
5. Update task brief - clarify constraints?
6. Request re-think or change tool (Aider vs OpenCode)

Error Handling

No Progress After 2x Time

1. Review task-brief.md for clarity
2. Check AGENTS.md for missing context
3. Consider breaking into smaller tasks
4. Adjust approach based on blockers

Same Error Pattern > 3 Times

1. Document in task-brief.md
2. Add to AGENTS.md as known issue
3. Consider different tool (Aider for simple edits)

Test Harness Issues

1. Review playwright.config.ts
2. Check API authentication
3. Ensure browsers are installed
4. Verify test expectations

Documentation Files

File	Purpose
.clinerules	Global agent guidance
docs/task-handoff-script.sh	Automation script
docs/opencode-mcp-server.json	MCP server spec
docs/workflow-integration-guide.md	This guide
docs/agent-evaluation-framework.md	Evaluation criteria
docs/agent-tools-installation.md	Installation guide
@projectname/AGENTS.md	Project context
@projectname/task-brief.md	Current task

Summary

1. Cline defines well-defined tasks in task-brief.md
2. Cline validates task is ready for autonomous iteration
3. Automation hands off to OpenCode via script or command
4. OpenCode runs autonomously reading AGENTS.md and task brief
5. Cline monitors via git checkpoints and terminal output
6. Cline approves changes after integration

This eliminates manual terminal interaction while maintaining human oversight.