Initial commit: LinkSyncServer and LinkSyncExtension projects with complete documentation, models, API endpoints, tests, and extension implementation
This commit is contained in:
DavidSaylor
285
docs/workflow-integration-guide.md
Normal file
285
docs/workflow-integration-guide.md
Normal file
@@ -0,0 +1,285 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user