# @codemcp/workflows-opencode

An [OpenCode](https://github.com/opencode-ai/opencode) plugin that enforces structured development workflows for AI coding agents.

## Why?

Small and mid-sized LLMs tend to skip process steps, edit code during exploration phases, and lose track of decisions after context compaction. This plugin addresses these problems:

| Problem                | Solution                                                            |
| ---------------------- | ------------------------------------------------------------------- |
| **Phase discipline**   | Hard-blocks file edits that violate current phase restrictions      |
| **Lost context**       | Automatically injects phase instructions on every turn              |
| **Context compaction** | Guides summary to preserve decisions and include phase continuation |

## How it works

The plugin hooks into OpenCode's message pipeline:

- **`chat.message`** — Injects phase instructions after each user message
- **`tool.execute.before`** — Blocks disallowed file edits with a clear error (hard enforcement)
- **`experimental.session.compacting`** — Guides compaction to preserve key info and end with phase continuation

This replaces the need for the agent to call `whats_next()` — guidance is injected automatically.

## Architecture: Synthetic Message Injection

Unlike the MCP server approach where agents must explicitly call `whats_next()`, this plugin uses **synthetic message injection**:

```
User Message (as seen by LLM)
├── Part 1: User's actual text
│   └── id: "prt_abc123..."
│
└── Part 2: Workflow guidance (INJECTED)
    └── id: "prt_workflows_{timestamp}"
```

The plugin intercepts each user message, fetches phase-specific instructions from the workflow engine, and appends them as an additional message part. The LLM sees both parts as coming from the user.

### Principles

1. **Zero tool overhead** — No LLM reasoning tokens spent on "should I call whats_next?"
2. **Guaranteed execution** — Every user message triggers guidance injection
3. **Invisible to the agent** — Instructions appear naturally in the conversation
4. **Consistent task management** — `bd` CLI commands with `--parent` flags are always included

### Efficiency Comparison

Measured from real sessions building a todo app:

| Metric                   | Plugin (synthetic) | MCP (tool calls) |
| ------------------------ | ------------------ | ---------------- |
| `whats_next` tool calls  | 0                  | 7                |
| Synthetic parts injected | 2                  | 3                |
| Total tool calls         | 82                 | 106              |
| Files created            | 36                 | 0 (incomplete)   |
| Task completion          | ✅ Full app        | ❌ Interrupted   |

The plugin approach reduces tool call overhead by ~23% while maintaining full workflow compliance. Agents correctly use hierarchical task management (`bd create --parent <phase-id>`) without explicit tool invocations.

## Installation

```json
// opencode.json
{
  "plugin": ["@codemcp/workflows-opencode"]
}
```

Or for local development:

```json
{
  "plugin": ["/path/to/responsible-vibe/packages/opencode-plugin"]
}
```

## Configuration

### Agent Filtering

By default, the plugin is active for all agents. Set `WORKFLOW_AGENTS` to a comma-separated list of agent names to restrict it to specific agents only:

```bash
# Only activate for the "coder" and "architect" agents
WORKFLOW_AGENTS=coder,architect npx opencode
```

When the env var is set, workflow hooks are skipped and tools throw a clear error for any agent not in the list. This prevents subagents (Tasks) from being interrupted by workflow instructions when they are not expected to follow the workflow.

**When unset**, workflows are active for all agents (default behavior).

### Auto-Compaction

When transitioning to a new phase via `proceed_to_phase`, the plugin automatically triggers a session compaction (summarize) to clear prior-phase context from the LLM window. This is enabled by default.

Set `WORKFLOW_AUTO_COMPACT=false` to disable this behavior:

```bash
WORKFLOW_AUTO_COMPACT=false npx opencode
```

**When unset or any value other than `false`**, compaction runs on every successful phase transition (default behavior).

### Per-Agent Behavior

- **Agent in filter**: Workflow instructions are injected on every message, tools work normally
- **Agent not in filter**: Workflow instructions are skipped, tools throw "not enabled for this agent" error

This design makes agent switching automatic—no session state needed. When the user switches agents, the TUI widget visibility and hook behavior adapt immediately based on the new agent.

## Status

Integrated with `@codemcp/workflows-core` for real state management and phase-based file restrictions.

## Related

- [`@codemcp/workflows-core`](../core) — The workflow engine (shared with MCP server)
- [`@codemcp/workflows-server`](../mcp-server) — MCP server for non-OpenCode hosts (Claude Code, Cline, etc.)
