Skip to content

refactor: simplify harness topology and managed runtime state #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cemalturkcan merged 1 commit into from
Apr 13, 2026
Merged

refactor: simplify harness topology and managed runtime state #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 43 additions & 49 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,44 +1,41 @@
# opencode-pair

OpenCode harness with opinionated agent orchestration. One coordinator, eight specialized workers, automatic verification, and risk-based review.
OpenCode harness with a three-agent setup: one primary, one general subagent, one validation-focused subagent.

## What it does

- **Yang Wenli** as coordinator — plans, delegates, synthesizes, never asks for routine permission
- Automatic workflow: scout/packetize → implement → verify → repair/re-verify as needed → risk-based review
- Plan/Execute mode switching via `/go` and `/plan` commands
- Session memory with cross-session continuity
- Observation logging and pattern learning
- Comment guard that catches AI-slop in generated code
- Emotion-informed prompt design based on [Anthropic's research](https://www.anthropic.com/research/emotion-concepts-function)
- **MrRobot** is the primary agent. He routes work and answers plainly.
- **Eliot** is the general subagent. He handles implementation, refactors, repo exploration, and other scoped task work.
- **Validator** is the validation-focused subagent. It reviews changes again after implementation and can also execute work when routed.
- No plan/execute mode or harness slash-command flow.
- No session memory, pattern learning, observation logs, or cross-session state injection.
- Comment guard blocks suspicious AI-style comments before file writes and surfaces anything that still slips through.

## Agents

| Agent | Character | Role | Model |
| ------------ | -------------------- | ------------------------------ | ----------------- |
| **yang** | Yang Wenli | Coordinator — plans, delegates | openai/gpt-5.4-fast |
| **thorfinn** | Thorfinn | Backend and refactor implementation | openai/gpt-5.4-fast |
| **ginko** | Ginko | Web and doc research | openai/gpt-5.4-fast |
| **rust** | Rust Cohle | Default senior review, faster lane (read-only) | openai/gpt-5.4-fast |
| **rust_deep**| Rust Deep | Escalation review, slower/deeper lane (read-only) | openai/gpt-5.4-fast |
| **spock** | Spock | Build, test, lint verification | openai/gpt-5.4-fast |
| **geralt** | Geralt of Rivia | Scoped failure repair | openai/gpt-5.4-fast |
| **edward** | Edward Elric | Frontend, browser testing | openai/gpt-5.4-fast |
| **killua** | Killua Zoldyck | Fast codebase exploration | openai/gpt-5.4-fast |
| Agent | Character | Role | Model |
| ----- | --------- | ---- | ----- |
| **mrrobot** | Mr. Robot | Primary agent — routes, synthesizes, answers | openai/gpt-5.4-fast |
| **eliot** | Elliot | General-purpose subagent | openai/gpt-5.4-fast |
| **validator** | Validator | Validation-focused review and verification | openai/gpt-5.4-fast |

All three use the `high` variant.

## MCP Servers

| MCP | What | API Key |
| ------------- | ----------------------------------------------------- | ------- |
| `context7` | Library and framework documentation | No |
| `grep_app` | GitHub code search across public repos | No |
| `searxng` | Web search (Google/Bing/DDG via self-hosted SearXNG) | No |
| `web-agent-mcp` | CloakBrowser — browser testing, screenshots | No |
| `pg-mcp` | PostgreSQL read-only client | No |
| `ssh-mcp` | Remote command execution on configured SSH hosts | No |
| `mariadb` | MariaDB client | No |
| MCP | What | API Key |
| --- | ---- | ------- |
| `context7` | Library and framework documentation | No |
| `grep_app` | GitHub code search across public repos | No |
| `searxng` | Web search via self-hosted SearXNG | No |
| `web-agent-mcp` | Browser testing and automation | No |
| `pg-mcp` | PostgreSQL read-only client | No |
| `ssh-mcp` | Remote command execution on configured SSH hosts | No |
| `mariadb` | MariaDB client | No |

Shared managed MCP roots stay under `~/.config/{mcp_name}`.

MCP access is controlled per-agent via `src/prompts/mcp-access.ts` — single source of truth.
All three agents receive the same enabled MCP set and the same default full tool access. The harness does not add per-agent MCP or tool restrictions.

## Prerequisites

Expand All @@ -51,11 +48,12 @@ bunx opencode-pair install
```

The installer will:
1. Wire agents, MCPs, and commands into OpenCode config
1. Wire agents and MCPs into OpenCode config
2. Install shell strategy instructions
3. Vendor `pg-mcp`, `ssh-mcp`, bundled skills
4. Auto-provision SearXNG Docker container (`--restart unless-stopped`)
5. Enable JSON format in SearXNG settings
3. Vendor `pg-mcp`, `ssh-mcp`, `web-agent-mcp`, and bundled skills
4. Install dependencies inside each shared managed MCP root
5. Auto-provision SearXNG Docker container (`--restart unless-stopped`)
6. Enable JSON format in SearXNG settings

From source:

Expand Down Expand Up @@ -89,33 +87,29 @@ Create project config:
opencode-pair init
```

Workflow defaults are quality-balanced: complex tasks scout first, broad work is packetized into focused changes, verification starts targeted when possible, Rust is the default faster review lane, and Rust Deep is escalation-only for deeper high-risk review.

`workflow.compact_subagent_context` defaults to `true`. It shortens the project-fact line injected into subagent sessions; set it to `false` to keep the longer human-readable format.

## Hooks

| Hook | What it does |
| --------------------- | ---------------------------------------------------------------------------------- |
| `session.created` | Prepare session context injection |
| `chat.message` | Inject mode, project docs, session memory (coordinator) or project facts (workers) |
| `tool.execute.before` | Plan mode gate, git push build gate, WSL auto-transform |
| `tool.execute.after` | Comment guard, file tracking, compact suggestions |
| `session.idle` | Save session summary, promote learned patterns, cleanup old sessions |
| `session.compacting` | Pre-compact observation snapshot |
| Hook | What it does |
| ---- | ------------ |
| `chat.message` | Inject project docs and WSL notes for MrRobot; inject compact project facts for subagents |
| `tool.execute.before` | Block suspicious AI-style comments before writes, enforce git-push build gate, auto-transform Node commands on WSL |
| `tool.execute.after` | Surface suspicious comments that still remain after a write |
| `session.deleted` | Clear ephemeral runtime state |

## Architecture

```
src/
├── prompts/
│ ├── mcp-access.ts # Single source of truth for agent MCP access
│ ├── shared.ts # Coordinator core, worker cores, response discipline
│ ├── workers.ts # Per-worker character prompts + MCP guidance
│ └── coordinator.ts # Worker catalog, delegation, plan mode, workflows
├── agents.ts # Agent definitions (models, tools, permissions)
│ ├── mcp-access.ts # Enabled MCP list and prompt guidance
│ ├── shared.ts # Shared prompt rules and response style
│ ├── workers.ts # Eliot + validator prompt builders
│ └── coordinator.ts # MrRobot prompt and routing rules
├── agents.ts # Agent definitions (models and prompts)
├── mcp.ts # MCP server registration
├── hooks/ # Runtime hooks (plan gate, comment guard, etc.)
├── hooks/ # Runtime hooks (comment guard, WSL, cleanup)
├── config.ts # Config schema + loading
├── installer.ts # CLI installer
└── index.ts # Plugin entry point
Expand Down
92 changes: 27 additions & 65 deletions docs/agent-matrix.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,81 +1,43 @@
# Agent Matrix

## Coordinator
## Topology

| Agent | Character | Model | Variant | Role |
| ------ | ---------- | --------------------------- | ------- | ------------------------------------------------- |
| `yang` | Yang Wenli | `openai/gpt-5.4-fast` | `high` | Plans, argues, delegates, synthesizes. Never asks for routine permission. |
| Agent | Mode | Character | Model | Variant | Role |
| ----- | ---- | --------- | ----- | ------- | ---- |
| `mrrobot` | `primary` | Mr. Robot | `openai/gpt-5.4-fast` | `high` | Primary agent. Routes work, synthesizes, and gives the final answer. |
| `eliot` | `subagent` | Elliot | `openai/gpt-5.4-fast` | `high` | General subagent for implementation, refactors, repo exploration, and scoped execution. |
| `validator` | `subagent` | Validator | `openai/gpt-5.4-fast` | `high` | Validation-focused pass. Reviews diffs, runs checks, and returns approve/request-changes. |

## Workers
## MCP Model

| Agent | Character | Model | Variant | Role |
| ---------- | --------------- | ----------------------------- | ------- | --------------------------------------------- |
| `thorfinn` | Thorfinn | `openai/gpt-5.4-fast` | `high` | Main implementation — backend changes, refactoring, migrations, server ops. |
| `ginko` | Ginko | `openai/gpt-5.4-fast` | `medium`| Web and doc research. Search, synthesize, report. |
| `rust` | Rust Cohle | `openai/gpt-5.4-fast` | `high` | Default senior reviewer. Read-only. Faster lane for medium/high-risk review. |
| `rust_deep`| Rust Deep | `openai/gpt-5.4-fast` | `xhigh` | Escalation reviewer. Read-only. Slower/deeper analysis for subtle or high-risk cases. |
| `spock` | Spock | `openai/gpt-5.4-fast` | `medium`| Build, test, typecheck, lint verification. Pass or fail, nothing more. |
| `geralt` | Geralt of Rivia | `openai/gpt-5.4-fast` | `medium`| Scoped failure repair. One problem in, one fix out. |
| `edward` | Edward Elric | `openai/gpt-5.4-fast` | `high` | Frontend specialist. Design-aware implementation and visual validation. |
| `killua` | Killua Zoldyck | `openai/gpt-5.4-fast` | `medium`| Fast codebase exploration. Scans structure, reports locations and patterns. |
Defined in `src/prompts/mcp-access.ts`.

## MCP Access Matrix
- MCP availability is configured globally through harness config toggles.
- All agents receive the same enabled MCP set.
- Managed local MCPs run from shared roots under `~/.config/{mcp_name}` with their own dependencies installed there.

Defined in `src/prompts/mcp-access.ts` — single source of truth.
## Task and Permission Model

| Agent | context7 | grep_app | searxng | web-agent-mcp | pg-mcp | ssh-mcp | mariadb |
| ------------ | -------- | -------- | ------- | ------------- | ------ | ------- | ------- |
| **yang** | yes | yes | — | — | yes | yes | yes |
| **thorfinn** | yes | yes | — | — | yes | yes | yes |
| **ginko** | yes | yes | yes | — | — | — | — |
| **rust** | yes | yes | — | — | — | — | — |
| **rust_deep**| yes | yes | — | — | — | — | — |
| **spock** | — | — | — | — | — | — | — |
| **geralt** | yes | — | — | — | yes | yes | yes |
| **edward** | yes | yes | yes | yes | — | — | — |
| **killua** | — | — | — | — | — | — | — |
| Agent | Can spawn subagents? | Can edit files? | Can use bash? | Notes |
| ----- | -------------------- | --------------- | -------------- | ----- |
| **mrrobot** | yes | yes | yes | Primary agent. Uses real OpenCode `primary` mode. |
| **eliot** | yes | yes | yes | General-purpose subagent. Uses real OpenCode `subagent` mode. |
| **validator** | yes | yes | yes | Validation-focused subagent. Review behavior comes from prompt/persona, not harness restrictions. |

`—` = denied at OpenCode runtime level (tool calls blocked).
The harness does not add per-agent MCP or tool restrictions. There is no delegate lane and no background-agent flow. All subagent work goes through OpenCode Task semantics.

## Automatic Workflow
## Workflow

The coordinator uses a quality-balanced workflow:
1. Inspect the repo and shape the packet.
2. Route implementation to `eliot` when delegation is useful.
3. Run a `validator` pass after implementation for any non-trivial change.
4. If `validator` requests changes, send the fix back to `eliot`, then run `validator` again.
5. Stop after two repair cycles if risk remains unresolved.

Low risk means narrow single-path changes with no public behavior change and no auth, billing, queue, or DB-write impact.

1. Scout first for complex tasks (`killua`, `ginko` only when external research is needed).
2. Packetize broad work into focused implementation scopes.
3. Implement with `thorfinn` or `edward`.
4. Low-risk packets may start with targeted `spock` checks, but completion still requires the relevant full `spock` pass.
5. Medium/high-risk changes run full `spock`, then `rust` (default faster lane).
6. Spock failures go to `geralt`, then back to `spock`. Max 2 cycles.
7. Rust request-changes go to `geralt`, then `spock`, then `rust`. Max 2 cycles; unresolved cases escalate to `rust_deep`.
8. `rust_deep` is escalation-only for subtle/high-risk edge cases or unresolved reviewer concerns.
9. Rust Deep request-changes go to `geralt`, then `spock`, then `rust_deep`. Max 2 cycles; if still unresolved, stop and escalate to user as blocker.
10. Verification and review are automatic by workflow; do not ask the user whether to run them.

## Delegation Tools

| Tool | For | Session Continuation |
| ------------ | ---------------------------------------------------- | ------------------------ |
| **Task** | Write-capable workers only (thorfinn, spock, geralt, edward) | Pass task_id to continue |
| **Delegate** | Fresh async lane for read-only workers (ginko, rust, rust_deep, killua) | Always fresh, runs async |

`rust_deep` is escalation-only (after Rust escalation or unresolved subtle/high-risk concerns), not a default planning scout.
Task continuation is explicit: call Task with an existing task_id to continue; omit task_id to spawn fresh.
Delegate IDs are for async result retrieval only; they do not support session continuation.
Read-only workers remain in the coordinator task allowlist only for internal Delegate plumbing; continuation remains Task-only for write-capable workers.

## Model Tier Policy

- **Coordinator**: openai/gpt-5.4-fast `high`
- **Default senior reviewer**: openai/gpt-5.4-fast `high`
- **Escalation reviewer**: openai/gpt-5.4-fast `xhigh`
- **UI worker**: openai/gpt-5.4-fast `high`
- **Implementation workers**: openai/gpt-5.4-fast (`high` / `medium`)
- **Read-only scout/research workers**: openai/gpt-5.4-fast `medium`
There is no plan mode, `/go`, `/plan`, or `/execute` harness flow.

## Language Policy

- All internal prompts, delegation packets, and structured outputs are in English.
- User-facing replies follow the user's language.
- Internal prompts and subagent reports stay in English.
- Code and other durable technical artifacts stay in English.
2 changes: 1 addition & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "opencode-pair",
"version": "0.1.0",
"description": "OpenCode harness with opinionated agent orchestration. One coordinator, seven specialized workers, automatic verify+review pipeline.",
"description": "OpenCode harness with a three-agent topology: mrrobot, eliot, validator.",
"type": "module",
"main": "dist/index.js",
"types": "dist/index.d.ts",
Expand Down
Loading
Loading