3. System Scope and Context

System Boundary

Inside Scope (Plugin)

The opencode-semantic-anchors plugin covers:

  • Contract enforcement via hooks: Intercepts tool.execute.before, chat.message, agent.activate

  • Rule Engine: Evaluates incoming events against active Structural Coupling Contracts

  • Override mechanism: /anchor bypass, /anchor status, /anchor config-reload

  • Config loading: Reads opencode-semantic-anchors.yaml with contract definitions

  • Session state: Tracks tool-call counts, override counts, active role

  • Standalone steering rules: Contracts without anchorRefs — generic rules (e.g., "BLUF", "MECE", language constraints) work identically to Anchor-based contracts

Outside Scope (Plugin does NOT do)

Not in scope Handled by

Anchor recognition evaluation

LLM-Coding/Semantic-Anchors evaluation framework (Issue #329)

Contract authoring / template rendering

LLM-Coding/Semantic-Anchors contracts.json + website

Anchor catalog browsing

LLM-Coding/Semantic-Anchors website

CI/CD verdict gating

agentcontract/spec CI gate or custom workflow

Multi-agent contract sync

Semantic-Anchors onboarding skill (Issue #521)

Take before Buy before Make: The plugin intentionally avoids duplicating these existing solutions. It focuses on the opencode-specific gap — runtime enforcement via plugin hooks — which no existing project covers. Where possible, it aligns terminology with agentcontract/spec (e.g., YAML-based contracts, BLOCK/WARN modes).

Business Context

C4Context
  Person(user, "User", "Developer or team lead configuring contracts")
  System(opencode, "opencode", "Agent runtime with plugin hooks")
  System_Ext(anchorRepo, "LLM-Coding/Semantic-Anchors", "Anchor catalog + contract definitions")
  System_Ext(agentContract, "agentcontract/spec", "Contract specification standard")
  System_Ext(kiros, "Kiros", "Has /steering files (reference concept)")

  System_Boundary(plugin, "opencode-semantic-anchors") {
    Component(hooks, "Hook Handlers", "tool.execute.before, chat.message, agent.activate")
    Component(engine, "Rule Engine", "Evaluates contracts → verdict")
    Component(config, "Config Loader", "Reads YAML contract definitions")
    Component(tools, "Custom Tools", "/anchor bypass, status, config-reload")
  }

  Rel(user, opencode, "Uses")
  Rel(opencode, plugin, "Loads")
  Rel(plugin, anchorRepo, "References terms from", "design-time")
  Rel(plugin, agentContract, "Aligns schema with", "design-time")
  Rel(kiros, plugin, "Inspiration for", "steering mechanism")

Technical Context

Interfaces

Interface Direction Data Protocol

tool.execute.before

opencode → plugin

{ toolName, args, caller } → { allow, message, overrideTool? }

opencode Plugin SDK

chat.message

opencode → plugin

{ content, conversationContext } → { suggestions[] }

opencode Plugin SDK

agent.activate

opencode → plugin

{ agentConfig } → { state }

opencode Plugin SDK

Config file

filesystem → plugin

opencode-semantic-anchors.yaml

YAML file read

Custom tools

user → plugin

/anchor bypass [reason]

opencode custom tool API

Existing Solutions (Take before Buy before Make)

Checked before writing own code:

Solution What it does Why not sufficient alone

agentcontract/spec

Full contract spec with pre/post conditions, CI gating

No opencode plugin hook implementation; designed for CI gates, not runtime agent steering

gl0bal01/contract-agents

AGENTS_CONTRACT.md with agent roles

Prompt-based only, not hook-enforced; no opencode plugin

Kiros /steering

Runtime steering files

Proprietary to Kiros; opencode has no equivalent

Semantic-Anchors onboarding skill

Installs anchor blocks into AGENTS.md

Prompt-only, no enforcement; Claude Code plugin, not opencode

SpecAnchor

Three-tier spec system with drift detection

Not hook-based; no opencode integration

Decision: The opencode plugin fills a genuine gap — runtime enforcement inside opencode’s plugin system. None of the existing solutions provide this. Alignment with agentcontract/spec terminology is desirable to avoid ecosystem fragmentation.

Position in the Semantic-Anchors Ecosystem

The LLM-Coding/Semantic-Anchors repository already provides integrations for several coding agents:

Agent Integration Type

Claude Code

plugins/semantic-anchors/ + Skills

Plugin + AGENTS.md

Codex

AGENTS.md

Project Context

Gemini CLI

GEMINI.md

Native Context

Cursor

.cursor/rules/*.mdc

Path-scoped Rules

GitHub Copilot

.github/copilot-instructions.md

Repo Instructions

Windsurf

AGENTS.md + Windsurf Rules

Project Context

opencode

opencode-semantic-anchors (this plugin)

Runtime Enforcement via Hooks

This plugin is the opencode-specific contribution to the Semantic-Anchors ecosystem. It will be contributed as plugins/opencode-semantic-anchors/ into the repository and made available to the opencode community — analogous to the existing Claude Code plugin at plugins/semantic-anchors/.

Take before Buy before Make (applied): Instead of building another "Anchor-Block into AGENTS.md" tool (which already exists in the Onboarding Skill), this plugin focuses on the gap that no existing integration covers: Runtime Enforcement via Plugin Hooks.