Workspace Plugin
Relevant source files
The following files were used as context for generating this wiki page:
The Workspace Plugin is a core component of the OCX orchestration harness designed to manage implementation plans, enforce strict agent routing, and inject targeted system rules into AI sessions. It serves as the primary management layer for complex development workflows within OpenCode, ensuring that agents operate within defined boundaries and maintain persistent progress tracking.
The plugin implements the "Elegant Defense" philosophy—Safe, Flat, and Fast—by utilizing rigorous schema validation and early-exit patterns. It facilitates a multi-agent environment where orchestrators like plan and build coordinate specialists such as coder, researcher, and reviewer.
Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:219-224, facades/opencode-workspace/README.md:5-15
Architecture and Role Orchestration
The Workspace Plugin operates as a read-only orchestrator that coordinates specialized agents through defined delegation boundaries. It uses system-level reminders to enforce strict separation of concerns, such as distinguishing between internal codebase exploration and external research.
The diagram shows how the Workspace Plugin manages the routing between different agent roles and their respective scopes.
Sources: facades/opencode-workspace/README.md:19-35, workers/kdco-registry/files/plugin/workspace-plugin.ts:251-274
Agent Routing Boundaries
The plugin injects workspace-routing policies that define the strict operational scope for each specialist:
| Agent | Scope | Primary Use Case |
|---|---|---|
explore | Internal | Codebase navigation, logic tracing, finding files. |
researcher | External | Documentation, APIs, npm packages, web tutorials. |
scribe | Human-facing | Documentation, commit messages, PR descriptions. |
coder | Execution | Implementation, running builds, executing tests. |
Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:254-260, facades/opencode-workspace/README.md:38-46
Implementation Planning (Plan Protocol)
One of the primary features of the Workspace Plugin is the management of implementation plans through the plan_save and plan_read tools. Plans are stored as Markdown files with YAML frontmatter and are subject to strict validation rules before being persisted.
Plan Schema Validation
The plugin uses Zod to enforce a hierarchical task structure and state machine consistency.
The state machine for phase and plan status markers.
Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:15-50, workers/kdco-registry/files/skill/plan-protocol/SKILL.md:65-75
Critical Plan Rules
- One Current Task: Only one task in the entire plan may be marked with the
← CURRENTmarker. - Frontmatter Requirements: Plans must include a status (
not-started,in-progress,complete,blocked), a phase number, and an updated date inYYYY-MM-DDformat. - Citation Mandate: Any decision based on research must be cited using a
ref:delegation-id.
Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:314-323, workers/kdco-registry/files/skill/plan-protocol/SKILL.md:25-33
Code Snippet: Plan Structure
---
status: in-progress
phase: 2
updated: 2024-05-20
---
# Implementation Plan
## Goal
Add JWT authentication with refresh token support
## Context & Decisions
| Decision | Rationale | Source |
|---|---|---|
| Use bcrypt | Security | `ref:delegation-id` |
Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:302-312, workers/kdco-registry/files/skill/plan-protocol/SKILL.md:37-55
Tooling and System Hooks
The Workspace Plugin provides specific tools for session persistence and rule enforcement.
Key Tools
| Tool | Description | Parameters |
|---|---|---|
plan_save | Validates and saves a plan to the local workspace directory. | content: Markdown string |
plan_read | Retrieves the current implementation plan for the session. | reason: String explanation |
Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:373-426
Lifecycle Hooks
The plugin utilizes OpenCode system hooks to maintain context:
experimental.chat.system.transform: Injectsdate-awarenessand agent-specific rules (e.g.,PLAN_RULESorBUILD_RULES) at the start of a session.tool.execute.after: Automatically triggers reminders to delegate to arevieweronce a plan is saved or coder tasks are finished.experimental.session.compacting: Injects the current plan and the specific "Resume Point" (Current Task) when a session is compacted to prevent context loss.
Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:429-509
Verification and Review Workflow
The plugin enforces a strict "Verification Workflow" where orchestrators must delegate all execution to the coder and all audits to the reviewer.
Code Review Protocol
When the coder finishes a task, the Workspace Plugin monitors the tool.execute.after hook. If all active coder calls are resolved, it injects a reminder for the orchestrator to delegate to the reviewer agent with findings formatted by severity (🔴 Critical, 🟠 Major, 🟡 Minor, 🟢 Nitpick).
Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:358-371, workers/kdco-registry/files/skill/plan-review/SKILL.md:65-73
The Workspace Plugin acts as the connective tissue for OCX, transforming OpenCode into a structured, multi-agent development environment that prioritizes plan persistence, role isolation, and automated verification.