OpenCode VKB-OSCR Plugin

Orchestrate OpenSpec Change Requests through Vibe-Kanban with a 4-phase workflow: intake → plan → execute → finalize.

Overview

This plugin provides a complete orchestration system for managing OpenSpec change requests by delegating implementation work to Vibe-Kanban (VKB) executor agents.

Components

Component	Name	Description
Agent	vibe-orchestrator	Primary orchestrator — loads skills per phase
Subagent	oscr-reviewer	Read-only code reviewer for worktree output
Subagent	oscr-verifier	Test/verification runner for worktree output
Skill	oscr-intake	Phase 0: Interactive Q&A via octto
Skill	oscr-plan	Phase 1: Create VKB cards for each change
Skill	oscr-execute	Phase 2: Launch, wait, review, fix, merge
Skill	oscr-finalize	Phase 3: Sync, verify, archive
Skill	oscr-vkb-quirks	Reference: VKB API quirks and workarounds
Tool	oscr_save	Persist orchestration state to disk
Tool	oscr_load	Load persisted state from disk
Tool	oscr_wait	Server-side poll with timeout (prevents context explosion)
Tool	oscr_follow_up	Send instructions to VKB executor sessions
Template	card-template.md	User-modifiable instructions for VKB executors

Usage

Primary Entry Point

Invoke the orchestrator agent directly:

@vibe-orchestrator implement openspec active changes

Or use a slash command:

/oscr user-authentication-v2
/oscr active

Slash Commands

Command	Description
/oscr	Full workflow (intake → plan → execute → finalize)
/oscr-plan	Planning phase only — creates VKB cards
/oscr-exec	Resume execution from saved state
/oscr-fin	Finalization phase only — sync and archive
/oscr-status	Show current orchestration status (read-only)

Change Name Input

The orchestrator accepts:

• Single change: @vibe-orchestrator implement user-auth-v2
• Multiple changes: @vibe-orchestrator implement auth,logging,cache
• All active: @vibe-orchestrator implement active (uses openspec status --json)

Workflow Phases

Phase 0: Intake (oscr-intake)

Interactive confirmation via octto:

1. Determine change names from input
2. Infer VKB server URL from opencode.json MCP config
3. Confirm push preference (local vs remote)
4. Choose executor model (OPENCODE, CLAUDE, CODEX, etc.)
5. Validate changes exist and are active
6. Save initial state

Phase 1: Plan (oscr-plan)

Create VKB cards:

1. Load state
2. For each change: get instructions via openspec instructions --json
3. Create kanban issue via MCP create_issue
4. Build CardState entries with "pending" status
5. Save state, transition to execute phase

Phase 2: Execute (oscr-execute)

The 5-step execution loop per card:

Step 1: Create & Launch

• Call VKB create-and-start API
• Get session ID
• Immediately send follow-up with rendered card template

Step 2: Wait for Completion

• Poll via oscr_wait (server-side, prevents context explosion)
• Completion signal: has_in_progress_attempt === false
• Stall handling: nudge once, escalate on second timeout

Step 3: Review

• Invoke @oscr-reviewer subagent
• If blocking issues and fix cycles remaining: send fix instructions via follow-up
• Loop back to Step 2

Step 4: Merge

• git merge {branch} --no-ff into base
• Push to remote if configured
• Explicitly update issue status to "done"

Step 5: Checkpoint

• Save state, log summary, continue to next card

Phase 3: Finalize (oscr-finalize)

For each completed card:

1. openspec sync <change>
2. openspec verify <change>
3. openspec archive <change>
4. Generate summary report
5. Clean up state file

Requirements

• OpenCode with plugin support
• Bun runtime (v1.0.0+)
• Vibe KanBan configured with repositories
• OpenSpec project structure at openspec/changes/
• octto plugin (for Phase 0 interactive Q&A)

Installation

Add to your project's .opencode/opencode.json:

{
  "plugins": [
    "opencode-vkb-oscr"
  ]
}

The plugin's config hook installs:

• Agents to .opencode/agents/
• Skills to .opencode/skills/
• Commands to .opencode/commands/
• Templates to .opencode/templates/

See INSTALLATION.md for detailed instructions.

VKB API Quirks

The plugin handles these known VKB behaviors (documented in oscr-vkb-quirks skill):

• Descriptions not passed to executors — always use follow-up API
• Two project systems — legacy for tasks, remote for issues
• No auto-transition to Done — explicitly update status after merge
• Completion signal — has_in_progress_attempt === false is more reliable than status

Development

• CONTRIBUTING.md — Setup and workflow
• AGENTS.md — Guidelines for AI agents
• CHANGELOG.md — Version history

License

MIT — See LICENSE file.