Skip to content

agent-installation.adoc

Latest commit

 

History

History
105 lines (79 loc) · 4.77 KB

agent-installation.adoc

File metadata and controls

105 lines (79 loc) · 4.77 KB
Raw

Installing Semantic Anchors for Coding Agents

Table of Contents

When Do You Need This?

Most frontier LLMs (GPT-4, Claude, Gemini) already have semantic anchors in their training data — saying "TDD, London School" or "Clean Architecture" is enough to activate the right concepts.

However, local or smaller LLMs (Llama, Mistral, Phi, etc.) may not recognize all anchors reliably. For these models, you can inject explicit anchor definitions into your project’s agent instruction files. This ensures consistent behavior regardless of the model’s training data.

Tip
 The higher-value install is Semantic Contracts, not bare anchors. A contract pins which anchors apply in your project and carries a rendered template the model cannot guess (e.g. "Specification" = Cockburn use cases + Gherkin + EARS). The semantic-contracts-installer skill installs contracts by default and keeps the bare-anchor flow below as its --anchors-only sub-mode.

Portable Baseline (Recommended)

For the widest compatibility, install anchors into a project-level AGENTS.md first, then add agent-specific mirrors only where the official docs say they help.

Use the bundled installer to inject a managed anchor block into the best available project instruction file. If none exists yet, it creates AGENTS.md.

First, copy the template and fill in your chosen anchors:

cp skill/semantic-contracts-installer/assets/templates/anchor-block.md my-anchors.md
# Edit my-anchors.md — replace {{PRIMARY_ANCHOR_*}} / {{PRIMARY_EXPLAINER_*}} placeholders

Then run the installer:

./skill/semantic-contracts-installer/scripts/install.sh \
  --source my-anchors.md \
  --target-dir . \
  --scope project

Agent-Specific Setup

Codex

Codex supports AGENTS.md for repository instructions.

  • Keep shared semantic anchors in AGENTS.md.

  • Use this as the canonical file when you want the same anchors to work across multiple agents.

Claude Code

Claude Code uses CLAUDE.md for project memory and also supports hooks.

  • Static Context: Mirror the same anchor block into CLAUDE.md if Claude Code is a target.

  • Optional Hook: If you want Claude to re-inject the managed block at session start, run:

    ./skill/semantic-contracts-installer/scripts/install.sh \
  --source my-anchors.md \
  --target-dir . \
  --scope project \
  --claude-hook

Gemini CLI

Current Gemini CLI docs center on GEMINI.md and configurable context file names.

  • Native Gemini Context: Mirror your selected anchors into GEMINI.md.

  • Shared Cross-Agent Context: Set Gemini’s context.fileName to AGENTS.md if you want one portable project file.

  • Current Gemini CLI docs no longer describe .gemini/skills/ or gemini skills link as the primary path for always-on instructions.

Cursor

Cursor supports AGENTS.md and project rules in .cursor/rules/*.mdc.

  • Use AGENTS.md for shared, repo-wide semantic anchors.

  • Use .cursor/rules/*.mdc only when you need path-scoped or feature-scoped behavior inside Cursor itself.

GitHub Copilot

Copilot supports repository instruction files, and its coding agent can also consume AGENTS.md.

  • Create or update .github/copilot-instructions.md when you want the same anchors to influence Copilot chat and review flows.

  • Keep AGENTS.md as the shared baseline if other coding agents are also in use.

Windsurf

Windsurf supports AGENTS.md alongside Windsurf Rules.

  • Use AGENTS.md for portable project context shared with other agents.

  • Use Windsurf Rules only when you need editor-specific or scoped behavior.

OpenCode

OpenCode supports AGENTS.md for project-level instructions and a plugin system for runtime enforcement.

  • Static Context: Use AGENTS.md as the shared baseline — OpenCode reads it automatically.

  • Runtime Enforcement: Install the opencode-semantic-anchors plugin to enforce anchors as runtime contracts via plugin hooks (BLOCK/WARN modes, step confirmation, source verification):

    npm install opencode-semantic-anchors

    Then add to opencode.jsonc:

    {
  "plugin": "opencode-semantic-anchors",
  "config": "opencode-semantic-anchors.yaml"
}

    This enforces anchors at runtime without consuming LLM context tokens. See the plugin documentation for configuration details.