Skip to content

Agent Overlays

Jump to bottom
Chris Sweet edited this page May 31, 2026 · 3 revisions

type: concept up: "Template-vs-Derived-Projects" tags: [architecture, agents]

Agent Overlays

The wiki-llm pattern is agent-agnostic. The template supports multiple coding assistants by overlaying agent-specific surfaces on top of the same core pattern. Each overlay implements the same operations but uses the surfaces the chosen agent supports.

Current overlays

Overlay Surface files Status
claude-code .claude/commands/wiki-*.md, .claude/skills/wiki-*.md, .claude/settings.json, optional .claude/hooks/posttooluse-hook.sh Behaviorally validated in a live Claude Code session. See Lesson-Validation-Methodology.
cursor .cursor/rules/wiki-*.mdc Structurally validated only. See Limitation-Untested-Overlays.

Minimal mode (--agent=none)

scripts/instantiate.sh accepts --agent=none, which installs no overlay at all. There is no wiki/agents/none/ directory; the derived project ships only the llm-wiki core (the wiki, the SCHEMA, and the generated CLAUDE.md). The hypothesis is that a non-instructed agent (OpenCode, Pi, or any other coding assistant) can still benefit from the pattern by reading CLAUDE.md and following the documented procedures manually. Whether any specific agent actually does is empirical and currently open; see Limitation-Untested-Overlays.

Pattern: same procedure, different invocation

Each overlay implements the Three-Operations (ingest, query, lint) plus the Verification-Gate using the surfaces that the agent supports:

  • Claude Code ships both slash commands (user-invoked from the UI) and skills (model-side procedures). The slash commands are a safety net; the skills are the proactive default. Each operation has both forms, and both forms must stay in sync; see Lesson-Parallel-File-Drift.
  • Cursor ships rules. wiki-as-memory.mdc is alwaysApply (injected into every prompt). The three operation rules (wiki-experiment, wiki-source, wiki-lint) are Agent Requested and can be invoked explicitly with @wiki-experiment, etc.

DRY across overlays

Two policy files in wiki/agents/ are agent-agnostic:

Slash commands, skills, and rules reference these files instead of duplicating their content. The same pattern is used for the Log-Entry-Attribution rule, which lives in the generated SCHEMA and is referenced from the per-overlay procedures. References eliminate the drift class that plagues the parallel-file pairs.

The setup script

Each overlay has its own wiki/agents/<overlay>/setup.sh that wires its surfaces into a fresh project. The Claude Code variant supports flags like --seed-memory (initialize Claude Code's memory with the wiki maintenance subsection) and --posttooluse-hook (install the optional advisory hook; see PostToolUse-Hook).

See also

Clone this wiki locally