Skip to content
archcore logo archcore logo Archcore

Mental Model

Shared

CLI = context infrastructure. Plugin = the command surface and guardrails. Archcore = one product system.

Archcore is one product built from two pieces:

  • The Archcore CLI is the engine. It reads .archcore/, builds the context graph, and exposes it over MCP.
  • The Archcore plugin is the runtime on top of it. It applies that context inside your AI agent through skills, slash commands, gated tracks, and guardrails.

Neither is the primary path. Which one you use is decided by the agent you run, not by a recommendation.

Why two pieces?

Section titled “Why two pieces?”

The two pieces do different jobs and change at different rates.

  1. Parsing and exposing context. Read files, validate structure, track relations, speak MCP. This part changes slowly, has to be a single stable binary, and must run anywhere (CI, editor, agent subprocess).
  2. Applying context inside a conversation. Know when to use an ADR vs. a spec vs. a guide. Drive multi-step tracks. Register the host’s lifecycle hooks so the CLI’s guardrails run. Audit the knowledge base. This part changes fast, is tied to the coding agent’s API (skills, hooks, prompts), and is host-specific.

Putting both in one package would couple their release cadences. Every plugin change would need a full CLI release. Splitting them lets each ship on its own schedule.

Who does what

Section titled “Who does what”
ResponsibilityCLI (engine)Plugin (runtime)
Initialize .archcore/ in a repoarchcore initNo
Parse and validate document frontmatterYesNo
Build the relation graph (.sync-state.json)YesNo
Expose MCP tools to agentsarchcore mcpNo
Install MCP configs and session hooksYesNo
Provide outcome-focused slash commands (/archcore:document, /archcore:plan, …)NoYes
Block direct writes to .archcore/*.mdYesRegisters the hook only (delegates to the CLI)
Detect cascade staleness after update_documentYesRegisters the hook only (delegates to the CLI)
Host-specific plugin manifests and hook filesNoYes

The plugin does not implement its own MCP server. It reuses the one started by archcore mcp, so both layers read the same graph.

Neither layer runs the method behind a document. Archcore stores knowledge in typed documents and relations; a gated track fills a document and checks its shape against what the type requires. How to decide, how to investigate, how to gather sources, and which tools to use stay with the host and with you. A template records the method that was used and never prescribes one. A new capability enters Archcore as vocabulary first: document types, templates, required sections, relation types, and conventions.

How they interact at runtime

Section titled “How they interact at runtime”
┌─────────────────────────┐         ┌──────────────────────────┐
│  AI coding agent (host) │         │  Your .archcore/ directory │
│  Claude Code / Cursor   │         │                          │
├─────────────────────────┤         ├──────────────────────────┤
│  Plugin (runtime)       │         │   *.md documents         │
│  • Skills               │         │   settings.json          │
│  • Built-in agents      │         │   .sync-state.json       │
│  • Hook launchers       │         └──────────▲───────────────┘
│    (call archcore hooks)│                    │
└──────────┬──────────────┘                    │
           │ MCP tools                         │
           │ (list/get/create/update/…)        │
┌──────────▼──────────────┐                    │
│  CLI (compiler)         │  parse / validate  │
│  archcore mcp (stdio)   ├────────────────────┘
└─────────────────────────┘
  • On session start, the host spawns archcore mcp as a subprocess.
  • The plugin’s session-start hook calls the CLI to emit a summary of documents and relations.
  • When you issue a slash command, the plugin loads the matching skill and makes MCP calls.
  • Every MCP mutation validates the document’s frontmatter before writing. An update also triggers a cascade staleness check.

When to use each path

Section titled “When to use each path”

Use the plugin when:

  • You work in Claude Code, Cursor, Codex CLI, or GitHub Copilot CLI day to day.
  • You want outcome-focused slash commands (/archcore:document, /archcore:plan, /archcore:review) without explaining document types to the agent.
  • You want guardrails on by default, including MCP-only writes, post-mutation validation, and cascade warnings.

Use the CLI directly when:

  • Your host is Gemini CLI, OpenCode, Roo Code, or Cline. The plugin does not target these hosts.
  • You script Archcore in CI, pre-commit, or other non-interactive contexts.
  • You want the smallest possible install surface.

Both paths read and write the same .archcore/. You can switch between them or run both at once.

Next steps

Section titled “Next steps”