Plugin Initialization and Pipeline
Relevant source files
The following files were used as context for generating this wiki page:
The Plugin Initialization and Pipeline system in oh-my-opencode manages the setup, configuration, and execution flow of a multi-agent AI development environment. It orchestrates the lifecycle of the plugin from initial configuration loading to the coordination of specialized agents like Sisyphus (Primary Orchestrator), Prometheus (Strategic Planner), and Hephaestus (Deep Worker).
This system ensures that high-level user intents are correctly classified and routed through a structured pipeline that includes research, planning, execution, and verification. By utilizing a 5-step initialization process and a tiered hook system, the pipeline provides a robust framework for autonomous software engineering tasks.
Sources: src/AGENTS.md:1-10, README.md:140-160
Plugin Initialization Lifecycle
The plugin follows a deterministic 5-step initialization sequence triggered at the index.ts entry point. This sequence transforms raw configuration into a functional plugin interface capable of handling OpenCode hook handlers.
The diagram above illustrates the sequential execution of the initialization pipeline.
Sources: src/AGENTS.md:5-10
Step 1: Configuration Loading
The configuration process involves a multi-level merge of user-specific and project-specific settings.
- User Config: Located at
~/.config/opencode/oh-my-opencode.jsonc. - Project Config: Located at
.opencode/oh-my-opencode.jsonc. - Merge: Performs a
deepMergefor agents/categories and aSetunion for disabled hooks. - Validation: Uses Zod v4 for safe parsing and providing defaults for omitted fields.
- Migration: Automatically transforms legacy configuration keys.
Sources: src/AGENTS.md:15-22
Step 2: Manager Creation
Managers are initialized to handle state and background processes, including:
TmuxSessionManager: Manages interactive terminal sessions.BackgroundManager: Orchestrates asynchronous tasks.SkillMcpManager: Handles Model Context Protocol (MCP) servers associated with skills.ConfigHandler: Maintains the validated configuration state.
Sources: src/AGENTS.md:11-12
Pipeline Execution and Agent Orchestration
The execution pipeline is driven by the Intent Gate, which classifies user requests before any action is taken. This prevents the system from misinterpreting research requests as implementation tasks.
Intent Classification (Phase 0)
Every message passing through the pipeline undergoes classification to determine the appropriate routing strategy.
| Surface Form | True Intent | Routing Decision |
|---|---|---|
| "explain X" | Research | explore/librarian -> synthesize -> answer |
| "implement X" | Implementation | plan -> delegate or execute |
| "investigate X" | Investigation | explore -> report findings |
| "fix bug X" | Fix | diagnose -> fix minimally |
| "refactor X" | Open-ended | assess codebase -> propose -> execute |
Sources: src/agents/sisyphus.ts:95-110, src/agents/prometheus/gpt.ts:70-80
The Planning Pipeline (Prometheus)
For non-trivial implementation tasks, the pipeline transitions to Phase 2: Planning, handled by the Prometheus agent. Prometheus is strictly a planner and is forbidden from writing implementation code.
Prometheus follows a "Decision Complete" principle, ensuring the executor has zero judgment calls to make.
Sources: src/agents/prometheus/gpt.ts:20-40, src/agents/prometheus/plan-generation.ts:60-100
Hook Composition and Pipeline Extensions
The pipeline is extended through a 3-tier hook system that monitors sessions, guards tools, and transforms messages.
| Tier | Count | Examples |
|---|---|---|
| Core Hooks | 43 | thinkMode, intentGate, writeExistingFileGuard, modelFallback |
| Continuation Hooks | 7 | todoContinuationEnforcer, atlas, stopContinuationGuard |
| Skill Hooks | 2 | categorySkillReminder, autoSlashCommand |
Sources: src/AGENTS.md:25-33
Specialized Execution (Hephaestus)
For deep engineering tasks, the pipeline utilizes Hephaestus, an autonomous worker that operates on an "Explore → Plan → Decide → Execute → Verify" loop. Hephaestus is optimized to work independently and is instructed to only ask the user as a last resort.
Sources: src/agents/hephaestus/gpt.ts:160-180
Verification and Quality Assurance
The final stage of the implementation pipeline is the Verification Wave. No task is considered complete until it passes four parallel audit gates:
- F1: Plan Compliance Audit: Verified by the
oracleagent. - F2: Code Quality Review: Checking for linting, types, and "AI slop" patterns.
- F3: Real Manual QA: Executing defined QA scenarios with tools like Playwright.
- F4: Scope Fidelity Check: Ensuring no "scope creep" occurred during implementation.
Sources: src/agents/prometheus/plan-template.ts:160-190, src/agents/prometheus/gpt.ts:250-265
Summary
The oh-my-opencode initialization and pipeline system provides a highly structured environment for AI-driven development. By separating concerns between planning (Prometheus) and execution (Sisyphus/Hephaestus) and enforcing strict intent gating, the system ensures that complex architectural changes are handled with professional-grade precision and verified through a mandatory multi-agent audit wave.