How the Plugin Works

Plugin

The plugin is invisible most of the time. Four mechanisms run underneath every conversation — they load context, enforce the MCP-only rule, validate every mutation, and warn you when a change might make other documents stale.

The session lifecycle

1. Session starts. The host fires SessionStart (Claude Code) or sessionStart (Cursor). The plugin’s hook loads your project’s document index and relations into the conversation before you type anything.
2. You ask for something. “Create an ADR for the caching decision”, “audit our rule coverage”, “plan the auth redesign”.
3. Skills activate. The agent matches your request to a skill — an intent command, a document-type skill, or a track. Each skill carries document-type knowledge, required sections, and relation guidance.
4. MCP tools execute. Every read and write goes through archcore mcp. Direct Write/Edit calls targeting .archcore/ are blocked by the PreToolUse hook.
5. Hooks validate. After every MCP mutation, the plugin runs archcore validate. If the updated document has dependents (via implements, extends, depends_on), a cascade check warns you that they may need review.

Mechanism 1 — session-start context

The session-start hook runs archcore hooks <host> session-start (or equivalent) and returns a document index plus a summary of existing relations. This is the agent’s starting point for the conversation — it knows what already exists before you ask the first question.

What gets loaded:

• List of documents with type, title, status, tags.
• Summary of relations (which documents reference which).
• Drift signal if any .archcore/ document references source code that has changed since the last check.

Mechanism 2 — the MCP-only principle

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

• Templated — new documents are generated from the right template for their type.
• Validated — required frontmatter, slug format, and allowed statuses are checked.
• Graph-aware — relations are added/removed through add_relation / remove_relation so the sync manifest stays consistent.

Direct writes bypass all three. The PreToolUse hook therefore blocks Write and Edit on anything matching .archcore/*.md and tells the agent to use the MCP tool instead.

Config files under .archcore/ (settings.json, .sync-state.json) are allowed through because they are managed by the CLI, not by the agent.

Mechanism 3 — post-mutation validation

After any MCP operation that writes to disk, the PostToolUse hook runs archcore validate with a short timeout. If validation fails — invalid frontmatter, broken relation, forbidden tag — the failure is reported back to the agent as tool output, so the agent can react in the same turn.

On Cursor this happens via afterMCPExecution; on Claude Code, the same hook is wired to PostToolUse with two matchers (one for Write|Edit, one for mcp__archcore_*).

Mechanism 4 — cascade staleness detection

When you update a document (via update_document), the plugin reads the relation graph from .sync-state.json and finds every document that is implements, extends, or depends_on the one you just changed. Each one becomes a cascade hint — a gentle warning that it may now be out of step with its source of truth.

Example:

You accept an updated jwt-strategy.adr.md. The plugin finds:

• auth-redesign.plan.md — depends_on the ADR.
• session-handling.rule.md — related to the ADR.

Both show up as cascade warnings on your next turn. You can resolve them, ignore them, or add them to a todo list — the plugin just surfaces the signal.

Hooks are not optional (but they are gentle)

The three PreToolUse / PostToolUse hooks run on every relevant tool call. They are:

• Fast — validation and cascade checks are capped at 2–3 seconds.
• Non-blocking for reads — only writes trigger the MCP-only guard.
• Recoverable — a failed validate doesn’t undo the write; it tells the agent to fix the file.

Want to see what the hook scripts actually do, or wire them up outside the plugin?

See CLI hook internals →

Next steps

• Skills — the 32-skill system that activates once context is loaded.
• Built-in agents — archcore-assistant and archcore-auditor.
• Troubleshooting — common hook and session issues.