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`:

```bash
#!/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

```bash
#!/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`:

```markdown
# 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

```bash
# 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.