myworkspace/docs/agent-tools-installation.md

# 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/)