OpenCode Vibe-Spec Plugin

Multi-agent plugin for OpenCode with 3 primary agent modes: Vibe (rapid prototyping), Spec (spec-driven development), and Ask (research assistant) — backed by 11 specialized subagents and an integrated quality gate workflow.

Quick Start

Add to your OpenCode config (~/.config/opencode/opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    "opencode-vibe-spec-plugin"
  ]
}

OpenCode will automatically install the plugin from npm on first launch.

Features

| Mode | Description | Key Capability | |------|-------------|----------------| | Vibe | Rapid prototyping agent | Creative exploration + quick implementation | | Spec | Spec-driven development agent | EARS requirements → phase-gated workflow → implementation | | Ask | Multi-function research assistant | Codebase analysis + context enhancement |

Spec-Driven Development

• EARS/GEARS Notation: Structured requirements using WHEN [trigger] THE SYSTEM SHALL [response] format
• Phase-Gated Workflow: requirements → design → tasks → implementation with validation at each gate
• Task Traceability: Requirements-to-tasks linkage with full traceability matrix
• Persistent Spec Storage: Per-feature specs organized under .opencode/specs/ with atomic write safety
• Steering Integration: Auto-loads product.md, tech.md, structure.md context

Quality Gate

• Phase Gates: Automatic quality validation at each spec phase transition
• Requirements Gate: Min 3 EARS requirements + acceptance criteria
• Design Gate: Architecture + technology stack validation
• Tasks Gate: Task count + requirement traceability

Additional Features

• Tab Key Switching: Seamless mode switching with context preservation
• 11 Specialized Subagents: Purpose-built for different tasks
• Smart Model Routing: Automatic model selection based on task type
• Steering Documents: Project conventions automatically followed
• Todo Enforcement: Mandatory/advisory task completion strategies

Agent Modes

Vibe Mode

Press Tab → Select Vibe → Describe your goal → Get executable prototype

Styles: Rapid Prototype | Inspiration Capture | Exploratory Coding

Spec Mode

Press Tab → Select Spec → Describe requirements → Get structured specification

Workflow:

requirements → [Quality Gate] → design → [Quality Gate] → tasks → [Quality Gate] → implementation

Ask Mode

Press Tab → Select Ask → Ask questions → Get research-backed answers

Architecture

Design Principles

| Principle | Description | Module | |-----------|-------------|--------| | Pure State Machine | 4 states (Inactive, Pending, Active, ExitPending) with snapshot/restore | src/utils/modeSwitcher.ts | | Scoring / I/O Separation | Pure scoring functions vs orchestration layer | src/quality/scorer.ts + engine.ts | | Atomic Writes | Temp-file-then-rename for crash-safe persistence | src/spec/spec-manager.ts | | Error Boundaries | All hooks wrapped with withErrorBoundary | src/hooks/shared.ts | | Snapshot Persistence | Lifecycle state survives process restarts via JSON | ModeLifecycleSnapshot |

State Machine: ModeSwitcher

Inactive → (enterPending) → Pending → (activate) → Active
Active → (userExit, idle) → Inactive
Active → (userExit, in-flight) → ExitPending → (completeDeferred) → Inactive
ExitPending → (enterPending) → Active  (cancel exit)

• 9 state transition methods, all pure functions
• 53 lifecycle tests covering all transitions, edge cases, snapshots
• ModeLifecycleSnapshot for JSON serialization/deserialization
• Legacy snapshot backward compatibility

Quality Engine: Scorer Separation

engine.ts (orchestration)
  ├── scorer.ts (16 pure dimension scoring functions)
  ├── negative-indicators.ts (pattern-based detection)
  ├── code-analyzer.ts (code structure analysis)
  └── security-scanner.ts (OWASP pattern detection)

• 65 pure-function tests for all 16 quality dimensions
• Agent-specific weight matrices (ISO 25010 aligned)

File System Safety

• Atomic writes: Write to .file.tmp.{pid} → renameSync() to target
• Path traversal protection: Validates resolved path stays within basePath
• Directory overwrite protection: Verifies target is not a directory
• Empty file prevention: Only writes non-empty content
• Validation before save: Preconditions checked before disk I/O

Configuration

Model Configuration

{
  "agent": {
    "vibe": { "model": "zhipu/glm-4-flash" },
    "spec": { "model": "zhipu/glm-5.2" },
    "ask": { "model": "zhipu/glm-4-flash" }
  }
}

Environment Variables

export VIBE_SPEC_MODEL_VIBE="zhipu/glm-4-flash"
export VIBE_SPEC_MODEL_SPEC="zhipu/glm-5.2"
export VIBE_SPEC_MODEL_ASK="zhipu/glm-4-flash"

Steering Documents

steering/
  product.md       # Business context and goals
  tech.md          # Technology stack and constraints
  structure.md     # File organization patterns

Spec Storage

.opencode/
  specs/
    user-authentication/
      requirements.md    # EARS-formatted requirements
      design.md          # Technical design document
      tasks.md           # Implementation tasks with traceability
      metadata.json      # Spec metadata (phase, version, etc.)

Quality Assessment

Scoring Dimensions

| Dimension | Description | Agent-Specific | |-----------|-------------|----------------| | functional_completeness | Coverage of requirements | Spec: +User Stories, +Acceptance Criteria | | functional_correctness | Output correctness | Ask: +Source Attribution, +Confidence | | code_readability | Code structure quality | Code analysis integration | | maintainability | Complexity & duplication | Code analysis integration | | documentation_quality | Markdown structure | Headings, tables, lists | | security_vulnerability | OWASP pattern detection | 10+ security patterns | | source_attribution | Citation quality | Ask: +librarian/oracle/architect | | actionability | Steps & recommendations | Next Steps, Follow-up | | relevance | Topic alignment | Per-agent keywords | | innovation | Creative keywords | 10 keyword matching |

Gate Decisions

• PROMOTE (Score ≥ 8/10): Output ready for use
• HOLD (Score 6-7/10): Needs improvements
• ROLLBACK (Score < 6/10): Requires significant rework

Hooks

| Hook | Purpose | Error Handling | |------|---------|----------------| | tool.execute.before | Pre-execution tool validation | withErrorBoundary | | message.updated | Incremental message processing | withErrorBoundary | | message.completed | Quality assessment + todo enforcement | withErrorBoundary | | stop.requested | Graceful shutdown with todo blocking | withErrorBoundary | | session.start | Session initialization | withErrorBoundary | | session.end | Session cleanup and persistence | withErrorBoundary |

All hooks use the shared withErrorBoundary wrapper from src/hooks/shared.ts for consistent error handling and logging.

Development

# Install dependencies
npm install

# Build the plugin
npm run build

# Run tests (512 tests across 27 files)
npm test

# Run specific test suites
npm test -- src/utils/modeSwitcher.test.ts    # 40 lifecycle tests
npm test -- src/quality/scorer.test.ts         # 65 pure function tests
npm test -- tests/unit/spec-manager-security.test.ts  # 21 security tests
npm test -- src/hooks/shared.test.ts            # 5 error boundary tests

From Source

1. Clone and build:

   git clone https://github.com/blank-1/opencode-vibe-spec-plugin.git
   cd opencode-vibe-spec-plugin
   npm install
   npm run build

2. Add to OpenCode config:

   {
     "plugin": [
       "file:///absolute/path/to/opencode-vibe-spec-plugin/dist/index.js"
     ]
   }

Test Coverage

| Module | Tests | Type | |--------|-------|------| | ModeSwitcher (state machine) | 53 | 40 lifecycle + 13 edge cases | | scorer.ts (pure functions) | 65 | All 16 dimensions + overall score | | SpecManager (security) | 21 | Path traversal, atomic writes, CRUD | | shared.ts (error boundary) | 5 | Error handling, logging | | EARS Parser | 22 | Requirement parsing, validation | | Phase Gate | 22 | Phase transitions, validation | | Spec Validator | 12 | Requirements, design, tasks validation | | Integration tests | 300+ | Real-env, scenarios, hooks |

Project Structure

src/
├── agents/           # Agent prompts (vibe, spec, ask, quality-gate)
├── config/           # Types, constants, agent configurations
├── hooks/            # Plugin hooks with error boundaries
│   ├── shared.ts     # withErrorBoundary, safeLog, PluginClient
│   ├── message-completed.ts
│   ├── message-updated.ts
│   ├── stop-requested.ts
│   ├── session-start.ts
│   ├── session-end.ts
│   └── tool-execute-before.ts
├── quality/          # Quality engine (scorer + engine separation)
│   ├── engine.ts     # Orchestration layer (I/O)
│   ├── scorer.ts     # Pure scoring functions (no I/O)
│   ├── code-analyzer.ts
│   ├── security-scanner.ts
│   ├── negative-indicators.ts
│   └── gate-controller.ts
├── spec/             # Spec management
│   ├── spec-manager.ts  # Atomic writes, path protection
│   ├── ears-parser.ts
│   ├── phase-gate.ts
│   ├── task-traceability.ts
│   └── spec-templates.ts
├── store/            # Session store
├── subagents/        # Subagent prompts (no dead config exports)
├── utils/            # Utilities
│   ├── modeSwitcher.ts  # Pure state machine
│   ├── todoParser.ts
│   ├── modelResolver.ts
│   └── spec-validator.ts
└── index.ts          # Plugin entry point

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'feat: add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE for details.