Initial commit: LinkSyncServer and LinkSyncExtension projects with complete documentation, models, API endpoints, tests, and extension implementation
This commit is contained in:
DavidSaylor
429
docs/agent-evaluation-framework.md
Normal file
429
docs/agent-evaluation-framework.md
Normal file
@@ -0,0 +1,429 @@
|
||||
# Agent Evaluation Framework
|
||||
|
||||
This document defines how to evaluate agent performance and make re-thinking decisions across your MyWorkspace projects.
|
||||
|
||||
## Evaluation Criteria
|
||||
|
||||
### Primary Metrics
|
||||
|
||||
| Metric | Threshold | Action |
|
||||
|--------|-----------|--------|
|
||||
| **Progress Rate** | < 10% per 30 min | Re-evaluate approach |
|
||||
| **Same Error Pattern** | > 3 failures | Investigate root cause |
|
||||
| **Test Harness** | Time per iteration | Track convergence speed |
|
||||
| **File Changes** | No meaningful changes | Agent stuck or unclear task |
|
||||
| **Time Elapsed** | > 2x estimate | Re-think strongly advised |
|
||||
| **Time Elapsed** | > 3x estimate | Re-think required |
|
||||
|
||||
### Secondary Metrics
|
||||
|
||||
- **Context Usage**: Monitor token usage in chatlog
|
||||
- **Git Commits**: Track meaningful changes
|
||||
- **Test Pass Rate**: Monitor improvement over iterations
|
||||
- **API Call Success**: For browser automation tasks
|
||||
|
||||
## Re-think Decision Tree
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ Task Running with Agent │
|
||||
└─────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────┐
|
||||
│ Is time > 50% of estimate? │
|
||||
└─────────────────────────────┘
|
||||
│ │
|
||||
YES │ NO
|
||||
↓ │
|
||||
┌──────────────────┐
|
||||
│ Check progress │
|
||||
│ Still on track? │
|
||||
└──────────────────┘
|
||||
│
|
||||
YES │ NO
|
||||
↓ ↓
|
||||
Continue ┌──────────────┐
|
||||
checkpoint │ Review │
|
||||
│ blockers │
|
||||
└──────────────┘
|
||||
↓ │
|
||||
┌──────────────────┐
|
||||
│ Time > 90%? │
|
||||
└──────────────────┘
|
||||
│
|
||||
YES │ NO
|
||||
↓ │
|
||||
┌──────────────────┐
|
||||
│ Near completion │
|
||||
│ Keep going │
|
||||
└──────────────────┘
|
||||
↓ │
|
||||
Complete ┌──────────────┐
|
||||
│ Time > 2x? │
|
||||
└──────────────┘
|
||||
│
|
||||
YES │ NO
|
||||
↓ │
|
||||
┌──────────────┐
|
||||
│ Re-evaluate │
|
||||
│ - Check task │
|
||||
│ - Review AGENTS.md
|
||||
│ - Adjust approach
|
||||
└──────────────┘
|
||||
↓
|
||||
┌──────────────┐
|
||||
│ Time > 3x? │
|
||||
└──────────────┘
|
||||
│
|
||||
YES │ NO
|
||||
↓ │
|
||||
┌──────────────┐
|
||||
│ Strong │
|
||||
│ Re-think │
|
||||
│ - Clear task │
|
||||
│ - New brief │
|
||||
│ - New tool │
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
## Agent-Specific Evaluation
|
||||
|
||||
### OpenCode Evaluation
|
||||
|
||||
**Expected Behavior:**
|
||||
- Reads AGENTS.md for context
|
||||
- Writes files directly to project
|
||||
- Runs tests repeatedly
|
||||
- Reports blockers clearly
|
||||
|
||||
**Good Signs:**
|
||||
- Multiple git commits per session
|
||||
- Test failure patterns changing
|
||||
- Iteration time decreasing
|
||||
- Clear progress indicators
|
||||
|
||||
**Bad Signs:**
|
||||
- Repeating same error
|
||||
- Only small/pointless changes
|
||||
- Session time increasing
|
||||
- Agent "thinking" with no output
|
||||
|
||||
**Actions:**
|
||||
- **Minor stall**: Wait 5-10 min
|
||||
- **Repeated errors**: Update AGENTS.md, clarify task
|
||||
- **No progress**: Pause, re-evaluate task brief
|
||||
|
||||
### Aider Evaluation
|
||||
|
||||
**Expected Behavior:**
|
||||
- CLI-based, simple interactions
|
||||
- Works well for single-file changes
|
||||
- Requires model configuration
|
||||
|
||||
**Good Signs:**
|
||||
- Quick response times
|
||||
- Clean diff output
|
||||
- Minimal context needed
|
||||
|
||||
**Bad Signs:**
|
||||
- Repeated file overwrites
|
||||
- Model timeout errors
|
||||
- Large context required
|
||||
|
||||
### Playwright Evaluation
|
||||
|
||||
**Expected Behavior:**
|
||||
- Test files in `tests/` folder
|
||||
- HTML report output
|
||||
- Screenshot on failure
|
||||
|
||||
**Good Signs:**
|
||||
- Tests running successfully
|
||||
- Reports capturing issues
|
||||
- Network interception working
|
||||
|
||||
**Bad Signs:**
|
||||
- Browser not launching
|
||||
- API calls timing out
|
||||
- Element not found errors
|
||||
|
||||
## Task Progress Tracking
|
||||
|
||||
### For Each Task
|
||||
|
||||
Create/Update: `<project-root>/tasks.md`
|
||||
|
||||
```markdown
|
||||
# Task: Increase Test Coverage for LinkdingSync
|
||||
|
||||
## Start Time
|
||||
2026-05-09 08:00
|
||||
|
||||
## Estimated Duration
|
||||
45 minutes
|
||||
|
||||
## Current Progress
|
||||
25% - Test structure created
|
||||
|
||||
## Current Blockers
|
||||
None
|
||||
|
||||
## Next Steps
|
||||
1. Implement auth test
|
||||
2. Implement API call test
|
||||
3. Run full suite
|
||||
```
|
||||
|
||||
### Checkpoint Questions
|
||||
|
||||
**At 50% time:**
|
||||
1. Is the agent still making progress?
|
||||
2. Are tests converging or regressing?
|
||||
3. Have blockers been identified?
|
||||
|
||||
**At 90% time:**
|
||||
1. Should be near completion
|
||||
2. Review remaining work
|
||||
3. Decide: continue or adjust
|
||||
|
||||
**After 2x time:**
|
||||
1. Review AGENTS.md for missing context
|
||||
2. Check task brief clarity
|
||||
3. Consider tool change
|
||||
|
||||
**After 3x time:**
|
||||
1. Strong evidence of stuck loop
|
||||
2. Re-think required
|
||||
3. New approach or tool needed
|
||||
|
||||
## Tool Evaluation
|
||||
|
||||
### When to Switch Tools
|
||||
|
||||
| Current Tool | Switch If... | To... |
|
||||
|--------------|---------------|-------|
|
||||
| OpenCode | Simple one-off | Aider |
|
||||
| OpenCode | Very complex refactoring | Consider re-scoping |
|
||||
| Aider | Complex iterative task | OpenCode |
|
||||
| Playwright | Test runner errors | Fix config, continue |
|
||||
| Any | 3x time with no progress | Re-evaluate approach |
|
||||
|
||||
### Cross-Project Patterns
|
||||
|
||||
**Document in `docs/tools.md`:**
|
||||
- What worked well
|
||||
- What didn't work
|
||||
- Tool preferences by project type
|
||||
- Configuration lessons learned
|
||||
|
||||
## Documentation Requirements
|
||||
|
||||
### AGENTS.md (Per Project)
|
||||
|
||||
```markdown
|
||||
# AGENTS.md
|
||||
|
||||
## Project Overview
|
||||
[What this project does]
|
||||
|
||||
## Setup Commands
|
||||
```bash
|
||||
npm install
|
||||
npm run dev
|
||||
npm test
|
||||
```
|
||||
|
||||
## Architecture
|
||||
[Brief notes]
|
||||
|
||||
## Testing
|
||||
- Unit tests: `npm test`
|
||||
- E2E tests: `npx playwright test`
|
||||
- Coverage target: 80%
|
||||
|
||||
## Conventions
|
||||
- Use TypeScript strict mode
|
||||
- Error handling with try/catch
|
||||
- API calls must timeout
|
||||
|
||||
## Known Issues
|
||||
- [List if any]
|
||||
|
||||
## Project Tools
|
||||
- Playwright for browser tests
|
||||
- OpenCode for iteration
|
||||
- API: `https://api.linkding.com`
|
||||
```
|
||||
|
||||
### task-brief.md (Per Task)
|
||||
|
||||
```markdown
|
||||
# Task Brief
|
||||
|
||||
## Context
|
||||
[Why this task]
|
||||
|
||||
## Goal
|
||||
[What needs done]
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] Criterion 1
|
||||
- [ ] Criterion 2
|
||||
|
||||
## Constraints
|
||||
- [ ] Constraint 1
|
||||
|
||||
## Related Files
|
||||
- File 1
|
||||
- File 2
|
||||
```
|
||||
|
||||
## Example Evaluation Log
|
||||
|
||||
```markdown
|
||||
# Evaluation Log: LinkdingSync Test Harness
|
||||
|
||||
## Session 1 (2026-05-09)
|
||||
|
||||
### Agent: OpenCode
|
||||
### Task: Add Playwright tests
|
||||
|
||||
### Progress
|
||||
- [x] Test structure created
|
||||
- [x] First test implemented
|
||||
- [ ] Tests converging
|
||||
|
||||
### Time Elapsed
|
||||
30 min (of 60 estimated)
|
||||
|
||||
### Issues
|
||||
- API calls timing out intermittently
|
||||
|
||||
### Decision
|
||||
Continue - tests improving
|
||||
|
||||
---
|
||||
|
||||
## Session 2 (2026-05-09)
|
||||
|
||||
### Time Elapsed
|
||||
55 min
|
||||
|
||||
### Progress
|
||||
- [x] Tests converging
|
||||
- [ ] 2 of 3 scenarios passing
|
||||
|
||||
### Issues
|
||||
- Resolved API timeout with retry logic
|
||||
|
||||
### Decision
|
||||
Continue - approaching completion
|
||||
|
||||
---
|
||||
|
||||
## Final Summary
|
||||
|
||||
### Time Actual: 75 min
|
||||
### Time Estimated: 60 min
|
||||
### Deviation: +25%
|
||||
|
||||
### Outcome
|
||||
SUCCESS - All acceptance criteria met
|
||||
|
||||
### Lessons
|
||||
- API retry logic needed upfront
|
||||
- Playwright config requires specific timeout values
|
||||
```
|
||||
|
||||
## Integration with Chat Logs
|
||||
|
||||
### Automatic Logging
|
||||
|
||||
Chat logs are automatically written to:
|
||||
- `<project-root>/chatlog.md`
|
||||
|
||||
### Key Information to Capture
|
||||
|
||||
**At task start:**
|
||||
- Task brief summary
|
||||
- AGENTS.md reference
|
||||
- Estimated time
|
||||
|
||||
**At checkpoints:**
|
||||
- Current progress
|
||||
- Issues encountered
|
||||
- Decision made
|
||||
|
||||
**At completion:**
|
||||
- Time actual vs estimated
|
||||
- Lessons learned
|
||||
- Recommendations
|
||||
|
||||
## Re-think Workflow
|
||||
|
||||
When re-thinking is triggered:
|
||||
|
||||
1. **Stop agent** (if running in terminal)
|
||||
2. **Review chatlog.md** for session history
|
||||
3. **Check tasks.md** for progress notes
|
||||
4. **Review AGENTS.md** for missing context
|
||||
5. **Document in tasks.md**:
|
||||
- What went wrong
|
||||
- What's changed
|
||||
- New estimates
|
||||
6. **Clear task brief** or update
|
||||
7. **Resume or restart** agent
|
||||
|
||||
## Escalation Path
|
||||
|
||||
```
|
||||
Agent Struggling → Check AGENTS.md → Update context
|
||||
→ Continue → Still stuck → Re-evaluate approach
|
||||
→ Clear approach → Time > 2x → Re-think
|
||||
↓
|
||||
Time > 3x or No Progress
|
||||
↓
|
||||
Re-think Required:
|
||||
- New task brief
|
||||
- Different tool
|
||||
- New approach
|
||||
```
|
||||
|
||||
## Quick Reference Commands
|
||||
|
||||
### OpenCode
|
||||
```bash
|
||||
# Start new task
|
||||
opencode --task task-brief.md
|
||||
|
||||
# Stop (Ctrl+C in terminal)
|
||||
```
|
||||
|
||||
### Aider
|
||||
```bash
|
||||
# Start
|
||||
aider
|
||||
|
||||
# Stop
|
||||
Ctrl+C
|
||||
```
|
||||
|
||||
### Playwright
|
||||
```bash
|
||||
# Run tests
|
||||
npx playwright test
|
||||
|
||||
# With specific project
|
||||
npx playwright test --project=chromium
|
||||
```
|
||||
|
||||
### Git for Verification
|
||||
```bash
|
||||
# Check recent commits
|
||||
git log --oneline -10
|
||||
|
||||
# Check what changed
|
||||
git diff HEAD~5..HEAD
|
||||
|
||||
# Check for stuck state (no new commits)
|
||||
git status
|
||||
304
docs/agent-tools-installation.md
Normal file
304
docs/agent-tools-installation.md
Normal file
@@ -0,0 +1,304 @@
|
||||
# Agent Tools Installation Guide
|
||||
|
||||
This guide covers installation and configuration of the multi-agent tooling stack for your MyWorkspace projects.
|
||||
|
||||
## Overview
|
||||
|
||||
The tooling stack provides complementary agents for different workflow patterns:
|
||||
|
||||
| Agent | Primary Use Case | Best For |
|
||||
|-------|------|-----------|
|
||||
| **OpenCode** | Main autonomous agent | Test harness iteration, debugging loops, multi-file refactors |
|
||||
| **Aider** | Quick CLI assistant | Small tasks, one-off fixes, simple edits |
|
||||
| **Playwright** | Browser automation | E2E testing, API call simulation, UI testing |
|
||||
| **E2B** | Sandboxed execution | Running generated code safely |
|
||||
|
||||
## Installation
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Node.js 18+ (for Playwright, OpenCode)
|
||||
- Python 3.10+ (for Aider)
|
||||
- Git (for repository management)
|
||||
- Access to npm and pip
|
||||
|
||||
### 1. Install OpenCode (Recommended for Self-Hosted)
|
||||
|
||||
```bash
|
||||
# Download from GitHub (OpenCode is open-source, self-hosted)
|
||||
# Visit: https://github.com/anomalyco/opencode/releases
|
||||
# Run the installer for your platform
|
||||
|
||||
# OR use npm package (if available in registry)
|
||||
npm install -g opencode
|
||||
|
||||
# Verify installation
|
||||
opencode --version
|
||||
```
|
||||
|
||||
**Important:** OpenCode is the open-source tool. Do not confuse with Claude Code (Anthropic's service).
|
||||
|
||||
**Configuration:**
|
||||
- OpenCode reads `AGENTS.md` for project context
|
||||
- Create/Edit: `n:\Data\Users\David\MyWorkspace\@projectname\AGENTS.md`
|
||||
- Task briefs go in: `<project-root>/task-brief.md`
|
||||
|
||||
### 2. Install Aider
|
||||
|
||||
```bash
|
||||
# Install via pip
|
||||
pip install aider-chat
|
||||
|
||||
# Verify installation
|
||||
aider --version
|
||||
|
||||
# Basic usage
|
||||
aider project-folder --model ollama/<your-model>
|
||||
```
|
||||
|
||||
**Aider Configuration:**
|
||||
- Create/Edit: `.aider.conf.yml` in project root
|
||||
- Example:
|
||||
```yaml
|
||||
model: ollama/llama3.2
|
||||
max_messages: 50
|
||||
user_instructions: "Read AGENTS.md for project context"
|
||||
```
|
||||
|
||||
### 3. Install Playwright
|
||||
|
||||
```bash
|
||||
# Install as npm dev dependency (for browser automation in projects)
|
||||
npm install -D @playwright/test
|
||||
|
||||
# Install browsers
|
||||
npx playwright install
|
||||
|
||||
# Verify installation
|
||||
npx playwright --version
|
||||
|
||||
# Example usage in project:
|
||||
# playwright.config.ts
|
||||
# Tests run via: npx playwright test
|
||||
```
|
||||
|
||||
### 4. Install E2B (Optional)
|
||||
|
||||
```bash
|
||||
# For sandboxed code execution
|
||||
npm install @e2b/sdk
|
||||
|
||||
# Example usage in project:
|
||||
# const { Sandbox } = require('@e2b/sdk');
|
||||
# const sandbox = await Sandbox.create({...});
|
||||
```
|
||||
|
||||
## Usage Patterns
|
||||
|
||||
### Quick Reference
|
||||
|
||||
| Task | Tool | Command |
|
||||
|------|------|---------|
|
||||
| Simple file edit | Aider | `aider` |
|
||||
| Test harness debugging | OpenCode | `opencode --task task-brief.md` |
|
||||
| Browser E2E testing | Playwright | `npx playwright test` |
|
||||
| Code snippet validation | E2B | See sandbox examples |
|
||||
|
||||
### OpenCode Workflow
|
||||
|
||||
1. **Prepare project context:**
|
||||
- Ensure `AGENTS.md` exists in project root
|
||||
- Document build/test commands, architecture, conventions
|
||||
|
||||
2. **Create task brief:**
|
||||
```markdown
|
||||
# task-brief.md
|
||||
|
||||
## Context
|
||||
Need to add Playwright tests for API endpoints
|
||||
|
||||
## Goal
|
||||
Implement E2E tests for user authentication flow
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] Tests pass for happy path
|
||||
- [ ] Tests fail appropriately for invalid auth
|
||||
- [ ] Tests run under 5 minutes
|
||||
|
||||
## Constraints
|
||||
- Don't modify authentication service code
|
||||
- Use existing API patterns
|
||||
```
|
||||
|
||||
3. **Launch OpenCode:**
|
||||
```bash
|
||||
opencode --task task-brief.md
|
||||
```
|
||||
|
||||
4. **Review and integrate:**
|
||||
- OpenCode writes to project files
|
||||
- Review changes in IDE
|
||||
- Approve/reject as needed
|
||||
|
||||
### Aider Quick Tasks
|
||||
|
||||
```bash
|
||||
# Simple one-off task
|
||||
aider
|
||||
|
||||
# With specific model
|
||||
aider --model ollama/llama3.2
|
||||
|
||||
# With instructions
|
||||
aider -m "Refactor auth module to use new pattern"
|
||||
```
|
||||
|
||||
### Playwright Project Setup
|
||||
|
||||
For browser extension projects:
|
||||
|
||||
```bash
|
||||
# Initialize Playwright config
|
||||
npx playwright init
|
||||
|
||||
# Add a new test file
|
||||
npx playwright test tests/example.spec.ts
|
||||
|
||||
# Run with specific browsers
|
||||
npx playwright test --project=chromium
|
||||
npx playwright test --project=firefox
|
||||
```
|
||||
|
||||
### Playwright Configuration Example
|
||||
|
||||
```typescript
|
||||
// playwright.config.ts
|
||||
import { defineConfig, devices } from '@playwright/test';
|
||||
|
||||
export default defineConfig({
|
||||
testDir: './tests',
|
||||
fullyParallel: true,
|
||||
forbidOnly: !!process.env.CI,
|
||||
retries: process.env.CI ? 2 : 0,
|
||||
workers: process.env.CI ? 1 : undefined,
|
||||
reporter: 'html',
|
||||
use: {
|
||||
baseURL: 'http://localhost:3000',
|
||||
screenshot: 'only-on-failure',
|
||||
},
|
||||
projects: [
|
||||
{ name: 'chromium', use: { ...devices['Desktop Chrome'] } },
|
||||
{ name: 'firefox', use: { ...devices['Desktop Firefox'] } },
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
## Cross-Project Workflows
|
||||
|
||||
### Standard Setup Template
|
||||
|
||||
When starting a new project:
|
||||
|
||||
```bash
|
||||
# 1. Initialize git
|
||||
git init
|
||||
|
||||
# 2. Create AGENTS.md
|
||||
# - Project overview
|
||||
# - Build/test commands
|
||||
# - Architecture notes
|
||||
# - Conventions
|
||||
|
||||
# 3. Create task-brief.md (for current task)
|
||||
# - Context
|
||||
# - Goal
|
||||
# - Acceptance criteria
|
||||
# - Constraints
|
||||
|
||||
# 4. Install project dependencies
|
||||
npm install
|
||||
|
||||
# 5. Install Playwright for browser projects
|
||||
npm install -D @playwright/test
|
||||
|
||||
# 6. Configure .clinerules (if project-specific)
|
||||
```
|
||||
|
||||
### Project Memory Files
|
||||
|
||||
| File | Purpose | Written By | Read By |
|
||||
|------|---------|-------------|---------|
|
||||
| `AGENTS.md` | Project context | Cline | All agents |
|
||||
| `task-brief.md` | Current task spec | Cline | OpenCode/Aider |
|
||||
| `.clinerules` | Project-specific guidance | Cline | Cline only |
|
||||
| `TODOs.txt` | Task tracking | Any | All |
|
||||
|
||||
## Evaluation Framework
|
||||
|
||||
### Tool Selection Matrix
|
||||
|
||||
| Criteria | OpenCode | Aider | Playwright | E2B |
|
||||
|----------|-----------|-------|------------|-----|
|
||||
| Complex iteration | ✓ Best | Limited | N/A | N/A |
|
||||
| Simple edits | Good | ✓ Best | N/A | N/A |
|
||||
| Browser testing | Via Playwright | Via Playwright | ✓ Best | N/A |
|
||||
| Local models | ✓ Supported | ✓ Supported | N/A | N/A |
|
||||
| Self-hosted | ✓ Supported | ✓ Supported | N/A | N/A |
|
||||
|
||||
### Cost-Efficiency Considerations
|
||||
|
||||
Since you run self-hosted models:
|
||||
|
||||
1. **Small tasks** → Aider (fastest, lowest cost)
|
||||
2. **Iterative debugging** → OpenCode (can converge without your input)
|
||||
3. **Browser automation** → Playwright (via OpenCode or Aider orchestration)
|
||||
4. **Safe code execution** → E2B (when needed)
|
||||
|
||||
### Monitoring Agent Progress
|
||||
|
||||
**For OpenCode/Aider sessions:**
|
||||
|
||||
1. **Check logs:** Review terminal output for progress indicators
|
||||
2. **Review commits:** Git commits show file changes
|
||||
3. **Review TODOs:** Check `tasks.md` for completed items
|
||||
4. **Review chatlog:** See `@projectname/chatlog.md` for session notes
|
||||
|
||||
**Re-think Triggers:**
|
||||
|
||||
- **50% time elapsed:** Check if task is on track
|
||||
- **90% time elapsed:** Task should be near completion
|
||||
- **2x time estimate:** Re-evaluate approach
|
||||
- **3x time estimate:** Strong re-think needed
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### OpenCode Issues
|
||||
|
||||
- **Agent not responding:** Check model is running (`ollama list`)
|
||||
- **AGENTS.md not read:** Verify file exists in project root
|
||||
- **Permissions denied:** Ensure write permissions in project folder
|
||||
|
||||
### Aider Issues
|
||||
|
||||
- **Model not found:** `ollama pull <model-name>`
|
||||
- **Large context errors:** Increase `max_context_tokens` in config
|
||||
|
||||
### Playwright Issues
|
||||
|
||||
- **Browser download fails:** Run `npx playwright install --with-deps`
|
||||
- **Network errors:** Check proxy settings in config
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Install tools** (toggle to Act mode when ready)
|
||||
2. **Create AGENTS.md** for existing projects
|
||||
3. **Test workflow** with LinkdingSync test harness
|
||||
4. **Document lessons** in `docs/` folder
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [OpenCode Documentation](https://open-code.ai/en/docs)
|
||||
- [Cline Customization](https://docs.cline.bot/customization/overview)
|
||||
- [Aider Documentation](https://aider.github.io/)
|
||||
- [Playwright Documentation](https://playwright.dev/)
|
||||
- [E2B Documentation](https://e2b.dev/)
|
||||
262
docs/multi-agent-workflow-summary.md
Normal file
262
docs/multi-agent-workflow-summary.md
Normal file
@@ -0,0 +1,262 @@
|
||||
# Multi-Agent Workflow Integration Summary
|
||||
|
||||
This document provides a complete overview of integrating additional agents into your Cline workflow for more autonomous iteration.
|
||||
|
||||
## Executive Summary
|
||||
|
||||
You asked to improve your coding workflow by leveraging additional agents for autonomous iteration on well-defined problems. The goal is to reduce hand-holding of Cline while maintaining oversight and quality control.
|
||||
|
||||
### Key Outcomes
|
||||
|
||||
1. **Refined Cline guidance** - Updated `.clinerules` with agent orchestration patterns
|
||||
2. **Tool identification** - OpenCode (primary), Aider (quick tasks), Playwright (browser tests), E2B (optional sandboxing)
|
||||
3. **Progress monitoring** - Time estimates, checkpoint reviews, re-think triggers defined
|
||||
4. **Proof of Concept ready** - LinkdingSync test harness documentation prepared
|
||||
|
||||
## Tool Evaluation Summary
|
||||
|
||||
| Tool | Role | When to Use | Notes |
|
||||
|------|------|-------------|-------|
|
||||
| **OpenCode** | Primary autonomous agent | Test harness iteration, debugging loops, multi-file refactoring | Self-hosted, reads AGENTS.md |
|
||||
| **Aider** | Quick task assistant | Simple edits, one-off fixes | Fast, minimal overhead |
|
||||
| **Playwright** | Browser automation | E2E testing, API call simulation | Used by OpenCode/Aider |
|
||||
| **E2B** | Sandboxed execution | Optional, for safe code running | Consider if needed |
|
||||
|
||||
**Claude Code** was intentionally not recommended as it's Anthropic-specific and you prefer self-hosted models.
|
||||
|
||||
## Integration Mechanisms
|
||||
|
||||
### 1. `.clinerules` - Global Guidance
|
||||
|
||||
**Location:** `n:\Data\Users\David\MyWorkspace\.clinerules`
|
||||
|
||||
**Purpose:** Always-on guidance for all projects
|
||||
|
||||
**What's included:**
|
||||
- Agent overview and roles
|
||||
- Handoff protocol (when to delegate)
|
||||
- Progress monitoring thresholds
|
||||
- Time estimate guidelines (2x/3x re-think triggers)
|
||||
- Project file conventions
|
||||
|
||||
### 2. Workflows - Task Templates
|
||||
|
||||
**Location:** Project-specific markdown files
|
||||
|
||||
**Purpose:** Step-by-step task definitions for Cline to orchestrate
|
||||
|
||||
**Example:** `task-delegate-to-opencode.md`
|
||||
|
||||
```markdown
|
||||
# task-delegate-to-opencode.md
|
||||
|
||||
## Step 1
|
||||
Gather acceptance criteria from user or task brief
|
||||
|
||||
## Step 2
|
||||
Write or update AGENTS.md with project context
|
||||
|
||||
## Step 3
|
||||
Create task brief in `<root>/task-brief.md`
|
||||
|
||||
## Step 4
|
||||
Launch OpenCode with: `opencode --task task-brief.md`
|
||||
|
||||
## Step 5
|
||||
Review output and approve changes
|
||||
|
||||
## Step 6
|
||||
Mark task as complete in tasks.md
|
||||
```
|
||||
|
||||
### 3. Hooks - Pre/Post Action Enforcement
|
||||
|
||||
**Available in Cline:** Yes (via Ghost.io/cine-v3-36-hooks)
|
||||
|
||||
**Purpose:** Run at known workflow moments
|
||||
|
||||
**Example use cases:**
|
||||
- Detect when task has >3 test failures → Suggest OpenCode handoff
|
||||
- Inject AGENTS.md content before task launch
|
||||
- Validate operation before execution
|
||||
|
||||
**Note:** Hook implementation requires Cline extension configuration. Documented in `.clinerules` as conceptual guidance.
|
||||
|
||||
### 4. Skills - Contextual Expertise
|
||||
|
||||
**Available in Cline:** Yes
|
||||
|
||||
**Purpose:** On-demand knowledge injection
|
||||
|
||||
**Example use cases:**
|
||||
- Add Playwright expertise before browser test tasks
|
||||
- Inject API documentation before integration tasks
|
||||
- Load project architecture notes before major changes
|
||||
|
||||
**Note:** Skill implementation via system prompts or context injection. Documented conceptually in `.clinerules`.
|
||||
|
||||
## Project Memory Files
|
||||
|
||||
| File | Purpose | Who Writes | Who Reads |
|
||||
|------|---------|------------|-----------|
|
||||
| `AGENTS.md` | Project context (build, test, conventions) | Cline | All agents |
|
||||
| `task-brief.md` | Current task specification | Cline | OpenCode/Aider |
|
||||
| `.clinerules` | Project-specific guidance | Cline | Cline only |
|
||||
| `TODOs.txt` | Task tracking | Any | All |
|
||||
| `tasks.md` | Detailed task progress | Any | All |
|
||||
|
||||
## Workflow Diagram
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ TASK INITIATION (CLINE) │
|
||||
│ - Define task and acceptance criteria │
|
||||
│ - Create/update task-brief.md │
|
||||
│ - Create/update AGENTS.md │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ ORCHESTRATION (CLINE) │
|
||||
│ - Review .clinerules for guidance │
|
||||
│ - Decide: direct Cline OR delegate to agent │
|
||||
│ - Record time estimate and checkpoint plan │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ AUTONOMOUS ITERATION (OPENCODE/AIDER) │
|
||||
│ - Read AGENTS.md for project context │
|
||||
│ - Execute task per task-brief.md │
|
||||
│ - Run tests repeatedly until stable │
|
||||
│ - Report on progress or blockers │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ CHECKPOINT REVIEW (CLINE) │
|
||||
│ - Review progress at 50% and 90% of estimate │
|
||||
│ - Detect stuck loops or blockers │
|
||||
│ - Decide: continue, re-think, or escalate │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ INTEGRATION & APPROVAL (CLINE) │
|
||||
│ - Review diff from agent work │
|
||||
│ - Approve/reject changes │
|
||||
│ - Add final product-level refinements │
|
||||
│ - Commit and push to git │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Next Steps for Implementation
|
||||
|
||||
### Phase 1: Setup (Immediate)
|
||||
|
||||
1. **Install OpenCode:**
|
||||
```bash
|
||||
npm install -g @anthropic-ai/claude-code
|
||||
```
|
||||
|
||||
2. **Install Aider:**
|
||||
```bash
|
||||
pip install aider-chat
|
||||
```
|
||||
|
||||
3. **Install Playwright:**
|
||||
```bash
|
||||
npm install -D @playwright/test
|
||||
npx playwright install
|
||||
```
|
||||
|
||||
4. **Update existing projects:**
|
||||
- Create `AGENTS.md` in Linkding Browser Extension
|
||||
- Document build/test commands
|
||||
- Add architecture notes
|
||||
|
||||
### Phase 2: Test Workflow (Short Term)
|
||||
|
||||
1. **Create proof of concept task brief:**
|
||||
- Task: "Increase Playwright test coverage for LinkdingSync"
|
||||
- Document acceptance criteria
|
||||
- Set time estimate
|
||||
|
||||
2. **Run OpenCode session:**
|
||||
```bash
|
||||
opencode --task task-brief.md
|
||||
```
|
||||
|
||||
3. **Monitor checkpoints:**
|
||||
- Review at 50% of estimated time
|
||||
- Review at 90% of estimated time
|
||||
- Re-evaluate if time > 2x estimate
|
||||
|
||||
4. **Integrate results:**
|
||||
- Review changes in VSCodium
|
||||
- Approve/reject as needed
|
||||
- Document lessons in `docs/`
|
||||
|
||||
### Phase 3: Refine & Scale (Medium Term)
|
||||
|
||||
1. **Document what works/doesn't work**
|
||||
2. **Create reusable task templates**
|
||||
3. **Add hooks to `.clinerules` if needed**
|
||||
4. **Evaluate E2B for sandboxing use cases**
|
||||
|
||||
## Quick Reference Commands
|
||||
|
||||
### Launch OpenCode
|
||||
```bash
|
||||
opencode --task task-brief.md
|
||||
```
|
||||
|
||||
### Launch Aider
|
||||
```bash
|
||||
aider
|
||||
```
|
||||
|
||||
### Run Playwright Tests
|
||||
```bash
|
||||
npx playwright test
|
||||
```
|
||||
|
||||
### Check Git Status
|
||||
```bash
|
||||
git log --oneline -10
|
||||
git status
|
||||
```
|
||||
|
||||
## Documentation Created
|
||||
|
||||
| File | Location | Purpose |
|
||||
|------|----------|---------|
|
||||
| `.clinerules` | Workspace root | Global agent guidance |
|
||||
| `docs/agent-tools-installation.md` | docs/ | Tool installation guide |
|
||||
| `docs/agent-evaluation-framework.md` | docs/ | Evaluation & re-think criteria |
|
||||
| `docs/multi-agent-workflow-summary.md` | docs/ | This document |
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [OpenCode Documentation](https://open-code.ai/en/docs)
|
||||
- [Cline Customization](https://docs.cline.bot/customization/overview)
|
||||
- [Aider Documentation](https://aider.github.io/)
|
||||
- [Playwright Documentation](https://playwright.dev/)
|
||||
|
||||
## Key Takeaways
|
||||
|
||||
1. **Cline** = Orchestrator (IDE-native, human-in-the-loop)
|
||||
2. **OpenCode** = Primary autonomous agent (terminal-driven iteration)
|
||||
3. **Aider** = Quick task assistant (simple edits)
|
||||
4. **Playwright** = Browser automation (via OpenCode/Aider)
|
||||
5. **Shared memory** = AGENTS.md for project context
|
||||
6. **Progress monitoring** = Time estimates with 2x/3x re-think thresholds
|
||||
7. **Task briefs** = Clear acceptance criteria for agents
|
||||
|
||||
## Files to Review Before Acting
|
||||
|
||||
1. `.clinerules` - Updated with agent guidance
|
||||
2. `docs/agent-tools-installation.md` - Installation instructions
|
||||
3. `docs/agent-evaluation-framework.md` - Evaluation criteria
|
||||
4. `Linkding Browser Extension/LinkdingSync/AGENTS.md` - Create for project context
|
||||
5. `Linkding Browser Extension/LinkdingSync/task-brief.md` - Create for test harness task
|
||||
|
||||
---
|
||||
|
||||
**Ready to proceed?** Toggle to Act mode when you're ready to install tools and begin the proof of concept.
|
||||
122
docs/opencode-mcp-server.json
Normal file
122
docs/opencode-mcp-server.json
Normal file
@@ -0,0 +1,122 @@
|
||||
{
|
||||
"name": "opencode-handoff",
|
||||
"version": "1.0.0",
|
||||
"description": "OpenCode task handoff MCP server for Cline integration",
|
||||
"type": "stdio",
|
||||
"capabilities": {
|
||||
"tools": true
|
||||
},
|
||||
"tools": [
|
||||
{
|
||||
"name": "opencode-launch-task",
|
||||
"description": "Launch OpenCode session with task description. Cline should use this when task is well-defined with clear acceptance criteria.",
|
||||
"inputSchema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"projectPath": {
|
||||
"type": "string",
|
||||
"description": "Path to project directory (e.g., 'Linkding Browser Extension/LinkdingSync')"
|
||||
},
|
||||
"task": {
|
||||
"type": "string",
|
||||
"description": "Task description for OpenCode to execute"
|
||||
},
|
||||
"model": {
|
||||
"type": "string",
|
||||
"description": "Model to use (e.g., 'qwen3.5-9b', 'llama3.2')"
|
||||
},
|
||||
"checkpoints": {
|
||||
"type": "object",
|
||||
"description": "Checkpoint settings for progress monitoring",
|
||||
"properties": {
|
||||
"checkAt50Percent": {
|
||||
"type": "boolean",
|
||||
"default": true,
|
||||
"description": "Check progress at 50% of estimated time"
|
||||
},
|
||||
"checkAt90Percent": {
|
||||
"type": "boolean",
|
||||
"default": true,
|
||||
"description": "Check progress at 90% of estimated time"
|
||||
},
|
||||
"rethinkThreshold2x": {
|
||||
"type": "boolean",
|
||||
"default": true,
|
||||
"description": "Re-evaluate at 2x estimated time"
|
||||
},
|
||||
"rethinkThreshold3x": {
|
||||
"type": "boolean",
|
||||
"default": true,
|
||||
"description": "Strong re-think at 3x estimated time"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"required": ["projectPath", "task"]
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "opencode-check-status",
|
||||
"description": "Check OpenCode session status and progress",
|
||||
"inputSchema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"sessionId": {
|
||||
"type": "string",
|
||||
"description": "Session ID to check (optional - defaults to last session)"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "opencode-rethink",
|
||||
"description": "Request OpenCode re-think when stuck. Use when time > 2x estimate or no progress.",
|
||||
"inputSchema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"reason": {
|
||||
"type": "string",
|
||||
"description": "Reason for re-think (e.g., 'no progress after 2x time', 'same error pattern >3 times')"
|
||||
},
|
||||
"newApproach": {
|
||||
"type": "string",
|
||||
"description": "Suggested new approach if known"
|
||||
},
|
||||
"updateAGENTSmd": {
|
||||
"type": "string",
|
||||
"description": "Additional context to add to AGENTS.md"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "opencode-complete-task",
|
||||
"description": "Mark OpenCode task as complete. Cline reviews diff and approves here.",
|
||||
"inputSchema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"changes": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"file": {"type": "string"},
|
||||
"summary": {"type": "string"}
|
||||
}
|
||||
},
|
||||
"description": "Files changed by OpenCode"
|
||||
},
|
||||
"approved": {
|
||||
"type": "boolean",
|
||||
"description": "Whether Cline approves these changes"
|
||||
},
|
||||
"revisions": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Any revisions Cline recommends"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
54
docs/task-handoff-script.sh
Normal file
54
docs/task-handoff-script.sh
Normal file
@@ -0,0 +1,54 @@
|
||||
#!/bin/bash
|
||||
# Task Handoff Script - Automate OpenCode Launch
|
||||
# Cline can invoke this to automatically hand off tasks to OpenCode
|
||||
|
||||
# Usage: task-handoff.sh "PROJECT_PATH" "TASK_DESCRIPTION"
|
||||
|
||||
set -e
|
||||
|
||||
PROJECT_PATH="${1:-.}"
|
||||
TASK_DESC="${2:-}"
|
||||
|
||||
if [ -z "$TASK_DESC" ]; then
|
||||
echo "Usage: task-handoff.sh \"PROJECT_PATH\" \"TASK DESCRIPTION\""
|
||||
echo ""
|
||||
echo "Example:"
|
||||
echo " task-handoff.sh \"Linkding Browser Extension/LinkdingSync\" \"Implement Playwright tests for bookmark sync\""
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "=========================================="
|
||||
echo "OpenCode Task Handoff"
|
||||
echo "=========================================="
|
||||
echo "Project: $PROJECT_PATH"
|
||||
echo "Task: $TASK_DESC"
|
||||
echo "=========================================="
|
||||
|
||||
# Change to project directory
|
||||
cd "$PROJECT_PATH"
|
||||
|
||||
# Check if task brief exists
|
||||
if [ -f "task-brief.md" ]; then
|
||||
echo ""
|
||||
echo "Found task-brief.md"
|
||||
echo "--- Task Brief Contents ---"
|
||||
cat task-brief.md
|
||||
echo "--- End Task Brief ---"
|
||||
echo ""
|
||||
fi
|
||||
|
||||
# Check if AGENTS.md exists
|
||||
if [ -f "AGENTS.md" ]; then
|
||||
echo "Found AGENTS.md - project context ready"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "Launching OpenCode with task..."
|
||||
echo ""
|
||||
|
||||
# Launch OpenCode in server/headless mode for autonomous execution
|
||||
# The agent will read the project files and execute the task
|
||||
opencode run "$TASK_DESC"
|
||||
|
||||
# Exit with OpenCode's exit code
|
||||
exit $?
|
||||
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