levi-cortex-plugin

Status: Prompts/assets only — no compiled code.

This is an agent plugin (Claude Code / OpenCode skill pack) that gives agents access to the levi-cortex knowledge layer. It contains only markdown skill definitions, agent personas, and two Node hook scripts — there is no TypeScript source.

Decision (MAR-70/MAR-96)

This package is prompts and assets only, not a code package. The real content is the skills, agent manifests, and hooks consumed by the two runtimes directly.

The backing runtime is @arborship/context-engine (the MCP server at mcp-cortex). This plugin just wires the agent personas and skills to that server.

Contents

• claude/ — the Claude Code variant, and the source of truth:
  • .claude-plugin/plugin.json — identity only (name, version, description, author, license)
  • .mcp.json — the one declaration of the levi-cortex MCP server
  • skills/<name>/SKILL.md, agents/*.md, hooks/hooks.json — all auto-discovered
• opencode/skill/, opencode/agent/ — the OpenCode mirror of a subset

The Claude Code manifest is deliberately small

Claude Code auto-discovers skills/<name>/SKILL.md, agents/*.md and hooks/hooks.json from the plugin root, so plugin.json names none of them. Declaring them again is not redundant-but-harmless — it breaks the plugin:

• a skills entry pointing at a SKILL.md file (rather than its directory) makes claude plugin install reject the whole plugin;
• naming the auto-loaded hooks/hooks.json under hooks makes the installed plugin fail to load with "Duplicate hooks file detected" — and claude plugin validate does not catch this;
• an mcpServers entry that repeats a server already in .mcp.json registers it twice.

manifest.test.mjs guards all four cases. Verified against claude 2.1.252.

The MCP server

claude/.mcp.json is the single declaration, in Claude Code's stdio shape:

{
  "mcpServers": {
    "levi-cortex": {
      "command": "mcp-cortex",
      "args": ["--stdio"],
      "env": { "LEVI_JOB_TOKEN": "${LEVI_JOB_TOKEN:-}" }
    }
  }
}

OpenCode's shape for the same server is different — {"type": "local", "command": ["mcp-cortex"], "enabled": true, "environment": {…}} — and goes under mcp in opencode.json, never in plugin.json. See docker/Dockerfile.context-engine-worker for a worked OpenCode example.

LEVI_CORTEX_URL and CORTEX_URL are deliberately not declared here — Claude Code passes the ambient environment through to a stdio MCP server unchanged, and an undefined ${VAR} with no :- default is substituted literally, so declaring a passthrough would hand the server the string ${LEVI_CORTEX_URL} rather than a URL.

Ensure @arborship/context-engine is installed and its MCP server is reachable before invoking any cortex skills; the skills carry no logic of their own and are inert without it.