메뉴
OpenCode SDK + Plugin internals for feature development, architecture, auditing, quality checking, test building, and gatekeeping. Contains BEYOND-DOCS expert knowledge extracted from source.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
Use when detecting and guardrailing against premature completion claims — verifying that subagent "done" assertions are backed by fresh runtime evidence, enforcing dual-signal completion protocol (doer + verifier must agree), and catching hollow "it works" claims that skip verification. Triggers on: "verify completion", "completion detection", "dual-signal", "premature completion", "evidence before claims", "hollow done", "fake done", "completion guardrail", "verify before complete", "block completion until verified", "done but not verified", "did it actually work", "completion verification", "dual-signal completion", "two-agent completion", "fresh evidence requirement". NOT for loop mechanics (iterative-loop), delegation patterns (subagent-delegation-patterns), or quality gate triad orchestration (quality-gate-orchestration).
Use when making cross-cutting changes, cross-pane modifications, framework migrations, or breaking changes that span multiple layers or frameworks (GSD, BMAD, Hivemind, or other). Triggers on: "cross-cutting change", "cross-pane change", "multi-layer change", "framework migration", "breaking change across frameworks", "change impact analysis", "cross-framework change", "multi-pane impact", "test-first change ordering", "dependency ordering across layers", "consumer impact tracing", "interface-first change", "ordered change management". NOT for single-layer changes, single-framework refactors, or cosmetic edits. Framework-agnostic — works across GSD, BMAD, Hivemind, or any project governance framework.
Evaluates whether implementation evidence is sufficient to pass quality gates. Enforces an evidence hierarchy from live runtime proof (L1) down to documentation summaries (L5), and refuses gate passage when evidence is missing, mocked where integration is claimed, or insufficient for the gate type. Use during code review gates, phase audits, milestone verification, integration checks, and deployment readiness. Activates after gate-spec-compliance clears spec alignment — this is the terminal gate in the triad (lifecycle → spec → evidence). Triggers: "evidence check", "gate evidence", "verify runtime proof", "evidence truth", "is there proof this works", "evidence hierarchy", "gate truth", "runtime evidence", "integration evidence", "mock-only detection", "completion honesty", "gate passed", "gate failed". Terminal skill in the quality gate triad — if evidence PASSES, all 3 gates clear.
Internal quality gate that evaluates whether Hivemind harness implementations correctly participate in the runtime lifecycle — covering 9-surface mutation authority, CQRS boundaries, actor hierarchy, event-driven wiring, classification fit (src/ vs .opencode/ vs .hivemind/), and OpenCode SDK surface compliance. Synthesized from .planning/codebase/ARCHITECTURE.md (9-surface authority table) and ingested @opencode-ai/plugin SDK v1.14.44 from anomalyco/opencode (tool(), hook() signatures). Use when performing a lifecycle gate check, auditing harness module integration, verifying CQRS boundary compliance, checking delegation hierarchy constraints, evaluating tool/hook registration correctness, running a harness quality gate, validating plugin composition integrity, or running phase audit on src/ modules. Activates during code review of src/ files, phase audit, milestone verification, integration check, and deployment readiness workflows.
Spec compliance gate performing bidirectional traceability, gap detection (4 types), EARS acceptance criteria validation, and anti-pattern scanning. Use during code review gates, phase audits, milestone verification, and deployment readiness. Middle gate in the quality triad (lifecycle → spec → evidence). Routes to gate-evidence-truth on PASS; STOPS with gap report on FAIL. Includes remediation routing to hm-spec-driven-authoring, hm-test-driven-execution, and hm-debug for fix workflows. Triggers on: "spec compliance", "verify against spec", "gap analysis", "compliance gate", "phase audit gate", "acceptance criteria check", "spec-to-code", "deployment readiness", "triad gate", "spec gate middle", "quality triad".
Detects and fixes drift between AGENTS.md documentation and actual codebase state. Scans source files and .opencode/ directories, compares claims against reality, produces a structured drift report, then applies targeted edits. Triggers on: 'sync agents md', 'update AGENTS.md', 'fix agents md drift', 'AGENTS.md out of date', 'check agent instruction drift'. NOT for generic documentation writing or README refreshes.
| name | stack-l3-opencode |
| version | 1.14.28 |
| description | OpenCode SDK + Plugin internals for feature development, architecture, auditing, quality checking, test building, and gatekeeping. Contains BEYOND-DOCS expert knowledge extracted from source. |
| triggers | ["opencode sdk","opencode plugin","definePlugin","tool registration","hook registration","session management","delegate task","opencode api","plugin development","opencode tool","opencode hook","tool.execute","chat.params","chat.headers","shell.env","permission.ask","session.compacting","ToolContext","ToolResult","PluginInput","Hooks","AuthHook","ProviderHook","createOpencodeClient","BunShell","hook composition","tool schema validation","opencode sse","opencode abort signal"] |
Version: 1.14.28 | Source: sst/opencode | Bundled: 20,546 lines
tool() is an identity function — zero runtime validation, pure TypeScript brandingcontext.ask() returns Effect, not Promise — await does nothing; use Effect.runPromise()z.transform()/.refine()/z.lazy() silently break in tool schemas — only use primitivesConfig.plugin[] array position| Document | What You'll Find | When to Load |
|---|---|---|
| Expert: Hook Composition | Multi-plugin ordering, output mutation, compaction flow, event types (32-40+), permission override | Writing hooks, debugging hook chains, compaction recovery |
| Expert: Tool Internals | tool() zero-validation, Zod→JSON Schema failures, ToolResult shape, ToolState machine | Creating tools, debugging tool errors, schema design |
| Expert: Client-Server | SSE event bus, session lifecycle, prompt_async, part mutations, v1 vs v2 differences | SDK integration, delegation, session recovery |
| API: Plugin | Hook signatures, PluginInput shape, auth/provider hooks | Looking up exact TypeScript signatures |
| API: SDK | Session CRUD, messaging, client setup | SDK client usage |
| API: Types | All exported TypeScript types | Type lookup |
| Patterns: Dev | Tool creation, hook wiring, plugin assembly | Feature development |
| Patterns: Testing | Mock SDK, tool testing, hook testing | Writing tests |
| Patterns: Gatekeeping | Quality gates, type safety, hook correctness | Code review |
Need the LLM to call it? → TOOL (tool.execute flow)
Need to modify LLM behavior? → HOOK (chat.params, tool.definition)
Need to observe events? → EVENT hook (fire-and-forget)
Need to inject env vars? → SHELL.ENV hook (not tool args!)
Need to auto-approve permissions? → PERMISSION.ASK hook
Need to recover from compaction? → SESSION.COMPACTING + AUTOCONTINUE hooks
z.string/number/boolean/array/object/enum/optional → ✅ Reliable
z.record/tuple/union/default → ⚠️ Partial conversion
z.transform/refine/lazy/any → ❌ Silent failure
Need workspace isolation or session restore? → v2 (createOpencodeClient v2)
Just basic session/message CRUD? → v1 works fine
Writing a plugin (hooks/tools)? → Plugin API is version-independent
| When working on... | Also load... | Because... |
|---|---|---|
| Tool schemas with Zod | stack-zod | Zod→JSON Schema conversion has silent failures |
| Testing plugin behavior | stack-vitest | SDK mocking patterns, ToolContext mock setup |
| Next.js sidecar dashboard | stack-nextjs | Sidecar reads SSE events, consumes SDK client |
| Quality gate for plugin code | gate-lifecycle-integration | 9-surface mutation authority table, CQRS boundaries |
| Evidence for tool outputs | gate-evidence-truth | L1-L5 hierarchy, ToolStateCompleted as evidence |
| Spec compliance for features | gate-spec-compliance | Traceability between specs and tool/hook implementations |
| Package | Key Files |
|---|---|
@opencode-ai/plugin | index.ts (types), tool.ts (helper), shell.ts (BunShell), tui.ts (TUI API) |
@opencode-ai/sdk | index.ts, client.ts, server.ts, gen/sdk.gen.ts, gen/types.gen.ts |
Run scripts/update.sh to re-download source when OpenCode version changes.
Reference documents provide facts, not workflows. When facts conflict with reality, this section guides resolution.
scripts/update.sh to re-download source from sst/opencode and refresh bundled references.context.ask() returning Effect (not Promise) and tool() being an identity function are behavioral claims — verify against source if the version changes.references/expert/tool-internals.md for tool behavior, references/expert/hook-composition.md for hook ordering.sst/opencode on GitHub are canonical. Check the tag matching the installed version.z.transform() behavior changes in a newer SDK, the matrix must be re-verified.@opencode-ai/plugin version in node_modules."npm list @opencode-ai/plugin @opencode-ai/sdk to compare installed versions.references/expert/) cover deep internals.sst/opencode repo for known SDK bugs.