Skip to content
archcore logo archcore logo Archcore

Built-in Agents

Plugin

The plugin ships two built-in agents: archcore-assistant writes documents, and archcore-auditor reviews them read-only. Each agent gets only the MCP tools its role requires.

You rarely invoke an agent directly. Skills call them, and the host can trigger them proactively from your intent, especially the auditor, which runs in the background. Knowing what each agent does helps you follow what happens when a skill delegates.

archcore-assistant

Section titled “archcore-assistant”

A universal read/write agent for complex multi-document tasks.

RoleRequirements engineering, multi-document planning, relation graph management.
Tools8 of the 11 MCP tools (list_documents, get_document, create_document, update_document, remove_document, add_relation, remove_relation, list_relations), plus Read, Grep, Glob. It has neither init_project nor install_host_config, which write outside .archcore/.
Max turns20
SafetyEvery .archcore/ write goes through MCP. Direct Write/Edit calls are not in its toolbox.

When skills call it

Section titled “When skills call it”
  • /archcore:plan iso builds the full BRS → StRS → SyRS → SRS cascade.
  • /archcore:document cascades wire ADR → spec → plan or ADR → rule → guide with the right relations.
  • Large-scope refactors of .archcore/ across many files.

What it’s good at

Section titled “What it’s good at”
  • Keeping the relation graph consistent across five or ten documents at once. It creates each relation right after the documents it connects.
  • Respecting document-type templates and filling the required sections.
  • Writing every change through MCP tools rather than editing files by hand. It confirms with you before creating more than about 10 documents in one pass.

archcore-auditor

Section titled “archcore-auditor”

A read-only auditor for documentation health reviews.

RoleDetects coverage gaps, orphaned documents, stale statuses, consistency issues.
Tools3 of the 11 MCP tools (list_documents, get_document, list_relations), plus Read, Grep, Glob.
Max turns15
ExecutionRuns in the background (background: true). The host invokes it proactively after a batch of document creations, or before a release. The audit is non-blocking, so you keep working while it reviews.
SafetyRead-only by design. It cannot create, update, or delete documents.

When skills call it

Section titled “When skills call it”
  • /archcore:review returns the branch review, the project health dashboard, or the full audit (--deep). Some dashboard numbers come from auditor queries.
  • /archcore:review --drift finds stale documents through code drift, cascade drift, and temporal signals. The auditor may run the checks, but the main thread confirms every verdict with you.

What it’s good at

Section titled “What it’s good at”
  • Returning structured audit reports rather than prose summaries.
  • Finding orphans: documents with no incoming or outgoing relations.
  • Spotting naming inconsistencies, tag hygiene issues, and missing frontmatter.

Host file formats

Section titled “Host file formats”

Both agents ship in three file formats:

  • .md under agents/ (archcore-assistant.md, archcore-auditor.md) for Claude Code and Cursor.
  • .toml under agents/ (archcore-assistant.toml, archcore-auditor.toml) for Codex CLI. The auditor TOML uses sandbox_mode = "read-only", model_reasoning_effort = "high", plus a disabled_tools list covering all seven mutating MCP tools; the assistant TOML uses sandbox_mode = "workspace-write".
  • .agent.md under copilot-agents/ for GitHub Copilot CLI.

Tool whitelists are identical across formats. The TOML variant translates the same safety boundaries into Codex’s native sandbox model.

The auditor’s deny list is exhaustive on purpose. sandbox_mode = "read-only" constrains the agent’s shell, not the MCP server process that executes the tools, so a mutating tool left off the list would still be callable.

Why two agents, not one

Section titled “Why two agents, not one”

Separating the write-capable agent from the read-only one is a deliberate safety boundary. The auditor runs on every review, so it handles more documents and contexts per week than the assistant. Because it is read-only, a review session cannot mutate state, which is why it can run in the background across a large knowledge base without blocking your work.

Next steps

Section titled “Next steps”