opencode-plugin-openspec — Summary

opencode-plugin-openspec is an OpenCode plugin that adds a dedicated openspec-plan agent mode to OpenCode for the planning phase of spec-driven development. The core problem it solves is that OpenCode's default "Build mode" agent starts implementing code immediately when working with OpenSpec planning documents, before the planning phase is complete. The plugin auto-detects OpenSpec projects, injects a specialized "OpenSpec Architect" agent with a distinctive system prompt that enforces planning-only behavior (no code implementation), and applies smart permission rules (read-only on source code; write access only to project.md, AGENTS.md, openspec/**, specs/**). It is installed by adding the package name to opencode.json — no npm install required. The plugin is TypeScript/Bun compiled.

differs_from_seeds: All seed frameworks work with Claude Code; this is the only framework in this batch targeting OpenCode specifically. It is analogous to opcode-plugin-openspec within the OpenCode ecosystem as superpowers is within the Claude Code ecosystem — a behavioral constraint layer for the planning phase. However, it adds only a single specialized agent rather than a full skill set.

opencode-plugin-openspec — Overview

Origin

Published by Octane0411, v0.1.4, MIT license. Built against OpenCode plugin API v1.1.19+ (@opencode-ai/plugin, @opencode-ai/sdk). TypeScript + Bun.

Philosophy

From the README: "The Problem: When using OpenCode's standard 'Build mode' to create or modify OpenSpec planning documents, AI agents often attempt to start implementing code changes immediately, before the planning phase is complete. This can lead to premature coding and a lack of focus on the architectural design."

The solution is a clean planning-implementation separation enforced by the plugin: the openspec-plan agent is allowed to write to spec files but not to implementation code. This is "permission-enforced phase separation" — not just instructional, but mechanically enforced through OpenCode's permission system.

Manifesto-style statements

• "Allow creating and editing OpenSpec documents. Prevent modifications to the implementation code."
• "Auto-Detection: Automatically detects if the current workspace is an OpenSpec project."
• "Read-Only Safety: Keeps the rest of the codebase read-only when using the openspec-plan agent."

Target user

Developers using OpenCode as their primary AI coding tool who also use OpenSpec for spec-driven development. The plugin bridges these two tools.

Agent color

#FF6B6B (distinctive coral/red) — visually distinguishes the OpenSpec Architect agent in the OpenCode agent selector.

opencode-plugin-openspec — Architecture

Distribution

• npm package: opencode-plugin-openspec (v0.1.4)
• Referenced in opencode.json — OpenCode auto-downloads on next run

Install method

Add to ~/.config/opencode/opencode.json or .opencode/opencode.json:

{
  "plugin": ["opencode-plugin-openspec"]
}

No npm install required. OpenCode fetches the plugin automatically.

Build

• TypeScript → compiled to dist/index.js via Bun
• bun build ./src/index.ts --outfile ./dist/index.js --target node

Directory structure

opencode-plugin-openspec/
├── src/
│   ├── index.ts        # Plugin entry point (Plugin function)
│   ├── config.ts       # createConfigHook (agent injection)
│   ├── prompts.ts      # OPENSPEC_SYSTEM_PROMPT constant
│   └── utils/
│       └── detection.ts  # isOpenSpecProject() detection
├── dist/index.js        # Compiled output
├── package.json
└── tsconfig.json

Plugin API usage

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

const OpenSpecPlugin: Plugin = async (ctx) => {
  const isActive = await isOpenSpecProject(ctx);
  if (!isActive) return {};
  return { config: createConfigHook(ctx) };
};

Peer dependencies

• @opencode-ai/plugin: ^1.1.19
• @opencode-ai/sdk: ^1.1.19

Required runtime

• Node.js (any version supporting ESM)
• OpenCode (any version supporting plugin API v1.1.19+)

Activation condition

Plugin is active only when isOpenSpecProject(ctx) returns true (checks for openspec/ directory or similar OpenSpec project markers).

opencode-plugin-openspec — Components

Plugin: OpenSpecPlugin (src/index.ts)

• Detects OpenSpec projects via isOpenSpecProject
• Returns config hook when active, empty object otherwise

Config hook: createConfigHook (src/config.ts)

• Injects the openspec-plan agent definition into OpenCode configuration
• Sets agent name, mode: "primary", description, prompt, permission rules, and color

Agent: openspec-plan

• Name: openspec-plan
• Mode: primary
• Color: #FF6B6B
• Description: "OpenSpec Architect - Plan and specify software architecture."
• Prompt: OPENSPEC_SYSTEM_PROMPT (see prompts.md)

Permission rules (src/config.ts)

read: { "*": "allow" }           # Full read on entire project
glob: allow, grep: allow, list: allow, lsp: allow
todoread: allow, todowrite: allow
webfetch: allow, websearch: allow, codesearch: allow
task: allow, skill: allow, question: allow
doom_loop: ask, external_directory: ask
edit: { "*": "deny", "project.md": "allow", "AGENTS.md": "allow", "openspec/**": "allow", "specs/**": "allow" }
bash: { "*": "deny", 
        "openspec": "allow", "openspec *": "allow",
        "grep *": "allow", "ls": "allow", "ls *": "allow", "cat *": "allow",
        "find *": "allow", "echo": "allow", "echo *": "allow", "pwd": "allow",
        "which *": "allow", "env": "allow", "printenv *": "allow",
        "git status*": "allow", "git log*": "allow", "git diff*": "allow", "git show*": "allow" }

Detection utility: isOpenSpecProject (src/utils/detection.ts)

• Checks if the current workspace is an OpenSpec project
• Content not fetched but inferred to check for openspec/ directory or openspec/config.yaml

No hooks, skills, commands (AI-facing), or MCP servers

The plugin's entire contribution is the single injected agent definition.

opencode-plugin-openspec — Uniqueness & Positioning

differs_from_seeds

This is the only framework in this batch targeting OpenCode (not Claude Code). All 11 seed frameworks target Claude Code or are multi-tool. The plugin's architecture mirrors the seed pattern of kiro (IDE extension that injects behavior into a specific AI coding tool) but implemented for OpenCode rather than an IDE. The permission-based planning-implementation separation (write access only to spec files) is mechanically enforced through OpenCode's permission system, which is stronger than prompt-only enforcement used by most seed frameworks. No seed framework implements this two-layer enforcement (prompt instruction + mechanical permission).

Positioning

• Category: OpenCode plugin — OpenSpec planning phase enforcement
• User: OpenCode users who also use OpenSpec for spec-driven development
• Integration: Transparent — auto-detected, auto-injected; no manual setup beyond opencode.json entry
• Value: Prevents premature implementation during the planning phase through mechanical permission enforcement

Observable failure modes

1. Single-agent limitation: The plugin adds only the planning agent; no implementation agent or workflow automation
2. isOpenSpecProject() detection: If detection logic is strict, non-standard OpenSpec setups may not trigger the plugin
3. Permission rules are last-match-wins: The edit: { "*": "deny", "project.md": "allow", ... } pattern depends on OpenCode's rule evaluation order — undocumented edge cases possible
4. OpenCode-specific: Zero portability to Claude Code, Cursor, or other tools

Notable meta-pattern

The README has a dedicated "For LLM Agents" section with different installation instructions than the "For Humans" section — "IMPORTANT: Do NOT run npm install... You only need to edit the configuration file." This shows the plugin author anticipates AI agents installing tools autonomously and writes installation docs for both audiences.

Cross-references

• Extends: OpenCode (AI coding tool)
• Integrates with: OpenSpec
• Analogous to intellij-openspec (this batch) — same intent, different target IDE/tool