How the Plugin Works

Plugin

The plugin ships skills, agents, and hook registrations. It carries no policy of its own. Since v0.7.0, every guard and advisory runs inside the Archcore CLI, and the plugin’s bin/ scripts only translate between the host’s protocol and archcore hooks <host> <event>.

Four mechanisms run underneath every conversation:

• Load a project recap at session start.
• Inject the documents that constrain a source file before the agent edits it.
• Block direct writes to .archcore/ documents.
• Report structure, cascade, and precision findings after a document mutation.

The session lifecycle

1. Session starts. The host fires its session event. The plugin’s bin/session-start hands the payload to archcore hooks <host> session-start, which returns a recap of your documents, relations, and branch state before you type anything.
2. You ask for something. “Record an ADR for the caching decision”, “review my branch”, “plan the auth redesign”.
3. A command activates. The agent matches your request to one of the four /archcore:* skills. Each one carries document-type knowledge, gate definitions, and relation guidance.
4. MCP tools execute. Every read and write goes through archcore mcp. The pre-write hook blocks direct Write and Edit calls that target .archcore/ documents.
5. Pre-edit context injection. When you ask the agent to edit a source file, the same pre-write hook finds the documents that reference that path and puts the most specific ones in front of the edit.
6. Post-write checks. After an Archcore MCP mutation, the post-write hook reports structure problems, cascade dependents, and precision findings as tool output, so the agent can react in the same turn.

Where the policy lives

The plugin’s three hook scripts are launchers. Each one normalizes the host’s stdin, refuses to run from a plugin-cache working directory, maps the host id to the CLI’s agent id, and delegates:

printf '%s' "$ARCHCORE_RAW_STDIN" | archcore hooks claude-code pre-tool-use

Two consequences follow.

The CLI is required. The plugin bundles no launcher and downloads nothing. It invokes whichever archcore is on the host’s PATH. If the hook cannot find the binary, it prints install instructions that link to the CLI install guide and exits. Skills, MCP tools, and agents do not work until you install the CLI.

Old CLIs fail open. The pre-write and post-write launchers check for CLI v0.7.0 or later and exit silently below that. A pre-0.7 CLI has no pre-tool-use leaf, and its usage error would read as a deny on GitHub Copilot, where any non-zero exit blocks the edit.

Mechanism 1: session-start recap

The recap tells the agent what already exists: document counts by category and status, work in progress, recently accepted documents, the most frequent tags, and the relation count. The output is budgeted rather than proportional to corpus size, so a 3000-document project produces a recap about as long as a 300-document one.

The same hook carries the staleness advisory. It compares the last commit that touched .archcore/ against everything committed since, names the documents that mention directories that moved, and rate-limits itself to once per 24 hours per project.

If .archcore/ does not exist yet, session-start emits guidance that routes the agent to call mcp__archcore__init_project on the first Archcore operation. You do not have to run archcore init yourself. On GitHub Copilot that instruction is different, because the plugin ships no MCP server there; see Supported AI agents.

Mechanism 2: pre-edit context injection

Before a write to a source file, the CLI finds the documents that mention the file’s directory and injects the most specific ones:

[Archcore Context] Before editing src/api/handlers/users.ts:
- rule: API Error Envelope [api/error-envelope.rule.md]
- adr: Handler Layering [api/handler-layering.adr.md]

Ranking is specificity-first: the deepest matching directory wins, with a type-priority tiebreaker of rule, cpat, adr, spec, guide. At most 3 documents and 2048 runes reach the host.

Source roots default to src, lib, app, pkg, cmd, internal, apps, packages, modules, and components. Setting codeAlignment.sourceRoots in .archcore/settings.json replaces that list rather than extending it.

This is why everyday work needs no command. The rules and decisions that apply to src/auth/ are in the agent’s working context the moment it starts editing there.

The injection never blocks an edit: on any error or empty result it exits silently. To turn it off globally, set ARCHCORE_DISABLE_INJECTION=1. It does not run on GitHub Copilot, whose pre-write event carries only a permission decision.

Mechanism 3: the MCP-only principle

The plugin treats .archcore/*.md as a schema-validated knowledge base, not a free text directory. Every change is:

• Templated. Each new document is generated from the template for its type.
• Validated. The CLI checks required frontmatter, slug format, and allowed statuses.
• Graph-aware. Relations go through add_relation and remove_relation, so the sync manifest stays consistent.

Direct writes bypass all three. The write guard therefore blocks Write and Edit on documents under .archcore/, and tells the agent to use the MCP tool instead. It refuses exactly what the MCP write tools refuse, because both consult the same predicate.

Config files under .archcore/ (settings.json, .sync-state.json) are allowed through, because the CLI manages them rather than the agent.

The guard runs first and alone. The deny verdict is computed before any advisory work starts, so a failure in the injection path cannot change the verdict on your edit.

Mechanism 4: post-write checks

The post-write hook fires after one of five Archcore MCP tools changed something: create_document, update_document, remove_document, add_relation, or remove_relation. It only reports. The tool has already run, so nothing here can deny.

Three checks run, and a failure in one does not silence the others.

Structure validation reports the same problems archcore doctor finds, capped at 5 per run.

Relation cascade notice fires only on update_document. It reads the relation graph and names the documents that reach the changed one through implements, depends_on, or extends. It skips related, which is an association rather than a dependency, so changes do not propagate through it. It also skips supports, contradicts, and supersedes: an evidential or temporal edge records a claim about a material, not a dependency on the changed document.

You accept an updated jwt-strategy.adr.md. The hook finds auth-redesign.plan.md, which depends_on the ADR, and token-refresh.spec.md, which implements it. Both surface as cascade hints on your next turn. Resolve them, ignore them, or add them to a todo list. The hook only surfaces the signal.

Precision findings measure the written document against the document contract: vague wording, missing required sections, frontmatter gaps, placeholder bodies, cross-document Markdown links that should be relations, and several spec-specific checks. They never block. The full list is in the CLI hooks reference.

Hook guarantees

• Fast. The pre-write hook is capped at 2 seconds, the post-write hook at 4.
• Non-blocking for reads. Only writes trigger the MCP-only guard.
• Non-blocking for source edits. The injection only adds context. It never blocks an edit, and it exits silently on error.
• Recoverable. A failed validation does not undo the write; it tells the agent to fix the document.
• Silent in the wrong place. Every script exits without output when the working directory looks like a host’s plugin cache, so a misrouted session never reports the plugin’s own .archcore/ as yours.

The full guard, recap, and advisory reference, including per-host wiring.

See CLI hook internals →

Next steps

• Plugin skills covers the four commands that activate once context is loaded.
• Built-in agents describes archcore-assistant and archcore-auditor.
• Plugin troubleshooting lists common hook and session issues.