OpenCode Conductor

OpenCode Conductor is a reusable plugin for the OpenCode ecosystem that implements the powerful "Context-Driven Development" (CDD) workflow. Originally popularized by the Gemini CLI Conductor, this approach enables AI agents to build complex features with high precision by grounding them in your project's specific product mission, technical stack, and development standards.

The Problem Conductor Solves

AI agents often fail on large tasks because they:

• Lose context between sessions and across long conversations
• Make assumptions that contradict your project's architecture
• Lack awareness of your coding standards and conventions
• Can't track progress on multi-step implementations

Conductor solves these problems through three core mechanisms:

1. Grounding: Every implementation is preceded by reading your core context files (product.md, tech-stack.md, workflow.md)
2. Tracking: Complex features are broken down into "Tracks," each with its own specification and step-by-step implementation plan
3. State Management: A clear record of what has been built, what is pending, and how each feature was specified

Installation

As an OpenCode Plugin (Recommended)

Add the plugin to your global opencode.jsonc configuration (usually found in ~/.config/opencode/opencode.jsonc):

{
  "plugin": [
    "opencode-conductor@latest"
  ]
}

OpenCode will automatically download and load the plugin the next time you start a session.

For Local Development

If you want to modify the plugin or use it locally without publishing:

# Clone the repository
git clone https://github.com/NocturnLabs/opencode-conductor.git
cd opencode-conductor

# Install dependencies
npm install

# Build and install locally using mise
mise run install

Verifying Installation

After installation, start OpenCode in any project directory and run:

/conductor-setup

If the plugin is correctly installed, you'll see the conductor directory being created with the core context files.

Getting Started

Step 1: Initialize the Project

In any project directory, run the setup command:

/conductor-setup

This creates a conductor/ directory at your project root with template files:

conductor/
├── product.md       # High-level product mission
├── tech-stack.md    # Frameworks, languages, and tools
├── workflow.md      # Coding standards and processes
└── tracks.md        # Index of all tracks (managed by plugin)

Step 2: Define Your Context

Open the generated files and fill them out with your project's specifics. The better the context, the better the AI's implementation.

product.md

Describe what your project is and who it serves:

# Product Context

## Mission
OpenCode Console is a web-based observability dashboard for AI coding agents.

## Target Users
- Developers using autonomous coding tools
- Teams who need visibility into AI agent decisions

## Core Value Proposition
Transform terminal-native AI agent experiences into rich visual dashboards
with real-time monitoring, debugging, and control capabilities.

tech-stack.md

List the technologies, frameworks, and specific versions:

# Tech Stack

## Frontend
- **Framework**: Next.js 15 (App Router)
- **UI Library**: React 19
- **Styling**: Tailwind CSS + Shadcn/UI
- **Icons**: Lucide React
- **State**: TanStack Query + Zustand

## Backend
- **Runtime**: Bun 1.1+
- **Database**: SQLite with Drizzle ORM
- **Real-time**: WebSockets via Socket.io

## Development
- **Language**: TypeScript 5.5+
- **Linting**: ESLint with Next.js config
- **Package Manager**: Bun

workflow.md

Document your coding standards and processes:

# Workflow

## Code Standards
- Use functional React components with hooks
- All components should be in `src/components/`
- Use TypeScript strict mode
- Follow ESLint rules without exceptions

## Testing
- Unit tests in `__tests__/` directories
- Use Vitest for testing
- Minimum 80% coverage for new features

## Git Conventions
- Conventional commits (feat:, fix:, docs:, etc.)
- Branch naming: feature/*, bugfix/*, hotfix/*
- All PRs require at least one review

Step 3: Create a New Track

When you're ready to build a feature, create a track with a unique ID and descriptive title:

/conductor-new id:"auth-system" title:"JWT Authentication System"

This creates a new track directory with template files:

conductor/tracks/auth-system/
├── spec.md          # Technical specification
├── plan.md          # Implementation checklist
└── metadata.json    # Status and timestamps

Step 4: Define the Specification

Open conductor/tracks/auth-system/spec.md and write a detailed technical specification:

# Spec: JWT Authentication System

## Goals
- Implement secure JWT-based authentication
- Support login, logout, and session refresh
- Integrate with existing user database

## Requirements

### Functional Requirements
1. Login endpoint accepts email/password, returns JWT token
2. Protected routes validate JWT before processing
3. Refresh token mechanism extends sessions without re-login
4. Logout invalidates tokens on server-side

### Non-Functional Requirements
- Token expiry: 15 minutes for access, 7 days for refresh
- Rate limiting: 5 failed login attempts per minute
- All tokens stored in HttpOnly cookies

### API Endpoints
- POST /api/auth/login
- POST /api/auth/logout
- POST /api/auth/refresh
- GET /api/auth/me

### Security Considerations
- Passwords hashed with bcrypt (cost factor 12)
- CSRF protection on all auth endpoints
- Secure cookie attributes in production

Step 5: Create the Implementation Plan

Open conductor/tracks/auth-system/plan.md and break down the work into discrete tasks:

# Plan: JWT Authentication System

## Tasks

### Database & Models
- [ ] Create users table with Drizzle schema
- [ ] Create refresh_tokens table for server-side token storage
- [ ] Run database migration

### Core Authentication
- [ ] Implement password hashing utility with bcrypt
- [ ] Create JWT signing and verification functions
- [ ] Build login endpoint with validation

### Session Management
- [ ] Implement refresh token generation and storage
- [ ] Create refresh endpoint
- [ ] Build logout endpoint with token invalidation

### Middleware & Protection
- [ ] Create authentication middleware
- [ ] Add protected route wrapper component
- [ ] Implement rate limiting for auth endpoints

### Testing
- [ ] Write unit tests for auth utilities
- [ ] Write integration tests for auth endpoints
- [ ] Test edge cases (expired tokens, invalid credentials)

Step 6: Implement the Feature

Run the "do" command to let the agent start working:

/conductor-do id:"auth-system"

The agent will:

1. Read all your core context files (product.md, tech-stack.md, workflow.md)
2. Read the track's specification and plan (spec.md, plan.md)
3. Execute the next uncompleted task in the plan
4. Mark the task as completed when finished

You can run /conductor-do repeatedly to continue implementing tasks until the plan is complete.

Step 7: Check Progress

View the status of all tracks and the overall project health:

/conductor-status

This displays the tracks index and helps you understand what's been completed and what remains.

Command Reference

/conductor-setup

Scaffolds the conductor/ directory and creates core context files.

Usage:

/conductor-setup

What it creates:

• conductor/product.md - Product mission template
• conductor/tech-stack.md - Technology stack template
• conductor/workflow.md - Development workflow template
• conductor/tracks.md - Tracks index (managed by plugin)
• conductor/tracks/ - Directory for feature tracks

Notes:

• Safe to run multiple times (won't overwrite existing files)
• Creates directories if they don't exist

/conductor-new

Creates a new development track with specification and plan templates.

Usage:

/conductor-new id:"<track-id>" title:"<Track Title>"

Arguments:

What it creates:

• conductor/tracks/<id>/spec.md - Specification template
• conductor/tracks/<id>/plan.md - Implementation plan template
• conductor/tracks/<id>/metadata.json - Status and timestamp metadata

Example:

/conductor-new id:"real-time-events" title:"Real-Time Event Streaming"

Notes:

• Track IDs should be URL-safe (use hyphens, not spaces)
• Automatically updates tracks.md index
• Fails if track ID already exists

/conductor-do

Reads context and implements pending tasks for a specific track.

Usage:

/conductor-do id:"<track-id>"

Arguments:

Execution Flow:

1. Calls conductor_get_context to read all core context files
2. Calls conductor_read_plan to get the current plan
3. Identifies the first uncompleted task (- [ ])
4. Implements the task following your project standards
5. Marks the task as complete (- [x]) using conductor_update_task

Example:

/conductor-do id:"auth-system"

Notes:

• Run repeatedly to implement all tasks in sequence
• Context is re-read each time to ensure consistency
• Safe to interrupt and resume later

/conductor-status

Provides a high-level summary of all tracks and context health.

Usage:

/conductor-status

Output includes:

• All tracks with their current status
• Links to track directories for detailed inspection
• Context file summaries

Directory Structure

After setup and creating tracks, your project will have this structure:

your-project/
├── conductor/
│   ├── product.md           # High-level product mission
│   ├── tech-stack.md        # Frameworks, languages, and tools
│   ├── workflow.md          # Coding standards and processes
│   ├── tracks.md            # Index of all tracks (auto-managed)
│   └── tracks/              # Feature-specific directories
│       ├── auth-system/
│       │   ├── spec.md      # Detailed technical specification
│       │   ├── plan.md      # Checkbox-list of implementation tasks
│       │   └── metadata.json # Status, title, and timestamps
│       └── real-time-events/
│           ├── spec.md
│           ├── plan.md
│           └── metadata.json
└── ... (your project files)

File Formats

metadata.json

Each track includes a metadata file tracking its lifecycle:

{
  "id": "auth-system",
  "title": "JWT Authentication System",
  "status": "pending",
  "created_at": "2025-12-19T10:30:00.000Z"
}

Status values:

• pending - Track created but no tasks started
• in_progress - At least one task completed
• completed - All tasks marked as done
• blocked - Waiting on external dependency

tracks.md

The tracks index is automatically updated when you create new tracks:

# Tracks Index
List of all development tracks.
- [ ] auth-system: JWT Authentication System
- [ ] real-time-events: Real-Time Event Streaming
- [x] database-setup: Initial Database Configuration

Plugin Architecture

Tools Exposed

The Conductor plugin registers the following MCP tools:

Plugin Implementation

The plugin is implemented as a TypeScript module using the @opencode-ai/plugin SDK:

import { tool } from "@opencode-ai/plugin/tool";
import type { Plugin } from "@opencode-ai/plugin";

export const ConductorPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {
  // Tool definitions...
  return {
    tool: {
      conductor_init,
      conductor_create_track,
      conductor_get_context,
      conductor_read_plan,
      conductor_update_task,
    },
  };
};

Best Practices

Writing Effective Context Files

1. Be specific: Instead of "use modern JavaScript," say "use ES2022+ features with TypeScript strict mode"
2. Include examples: Show code snippets that demonstrate your preferred patterns
3. Document decisions: Explain why you chose specific technologies, not just what
4. Keep updated: Revisit context files when your stack or standards evolve

Creating Good Tracks

1. One feature per track: Don't bundle unrelated functionality
2. Clear specifications: Include acceptance criteria and edge cases
3. Granular tasks: Each task should be completable in one implementation step
4. Dependencies first: Order tasks so prerequisites come before dependent work

Iterative Implementation

1. Run frequently: Execute /conductor-do often rather than trying to complete everything at once
2. Review between tasks: Check the agent's work before moving to the next task
3. Refine as you go: Update the spec or plan if you discover new requirements
4. Commit checkpoints: Use git commits between major milestones

Troubleshooting

"Track already exists" Error

The track ID must be unique. Either:

• Choose a different ID
• Delete the existing track directory if it's no longer needed

Context Not Being Read

Ensure your context files are in the correct location:

conductor/product.md
conductor/tech-stack.md
conductor/workflow.md

Tasks Not Being Marked Complete

The task matching is exact. Ensure the task text in the command matches the plan exactly, including whitespace.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

git clone https://github.com/NocturnLabs/opencode-conductor.git
cd opencode-conductor
npm install

Publishing to NPM

To publish a new version (org members only):

1. Update version in package.json
2. Commit and push:

   npm version patch # or minor/major
   git push --tags
   

3. GitHub Actions will handle the NPM release

License

This project is licensed under the MIT License - see the LICENSE file for details.