Archcore commands and examples

Use Archcore in your agent to record project knowledge, plan a change, or review work against existing decisions. Describe the outcome in conversation or use one of the four slash commands below.

Slash commands require the Archcore plugin in a supported host. Other MCP agents can read and write the same documents through natural-language requests. For terminal operations, use the CLI command reference.

Choose an action

You want to	Command	Result
Create initial context from this repository	`/archcore:init`	A preview of project documents and host wiring
Scope a change before implementation	`/archcore:plan`	A document package based on the request and existing context
Record a decision or describe existing code	`/archcore:document`	A typed document based on the supplied facts
Check changes against project context	`/archcore:review`	Findings about code and recorded documents

/archcore:init

/archcore:init

Use this in a repository with existing code. The agent examines its structure and proposes an initial set of documents. Review the preview before confirming document creation and host wiring. An empty project has no implemented architecture to describe.

This is separate from terminal archcore init, which creates .archcore/ and configures your agent. See installation.

The first word selects the kind of run. Settings follow it.

Argument	Effect
`refresh` (first word)	Adds missing context in a previously seeded repository and refreshes host wiring
`domain <slug>` (first word)	Focuses a run on one domain
`--depth=light\|standard\|deep`	Sets the synthesis budget; the default is `standard`
`--scale=small\|medium\|large`	Overrides detected repository scale

/archcore:init --depth=light
/archcore:init domain payments
/archcore:init refresh

Depth limits the proposed coverage; it is not a target number of documents. Review the count in the preview, especially for a large repository.

/archcore:plan

/archcore:plan add CSV export to the reporting API

Describe the work in free text. The agent reads the request, open drafts, accepted documents, the branch, and the code, then creates only the documents a later reader needs. A small fix needs no documents. A sequenced migration needs a plan. One capability needs a spec and a plan. Several capabilities need a PRD, one spec per capability, and a plan. A traceability obligation adds only the requirement levels it names.

You write	The agent produces
`plan a new feature for CSV export`	A `spec` and a `plan`
`upgrade the HTTP client across three services with a coordinated rollout`	A `plan`
`plan the notifications platform`	A `prd`, one `spec` per capability, and a `plan`
`fix the typo in the onboarding copy`	No document
`I need market research before we plan`	Market, business, and user requirements sources
`we must trace these requirements for the auditor`	The requirement levels the obligation names, from the BRS, StRS, SyRS, and SRS chain
`investigate X before we plan`	A `research`
`compare the alternatives for Y`	An `rnd`

A first word that is a document type name requests that type; a leading research requests the type research. Any other first word is part of the topic. The plugin source owns the selection rules.

The agent asks at most five questions per run, and only about information it could not find in the available sources. Remaining questions wait for the next run. Without arguments, the command resumes an open planning draft or offers what to plan next. Review the resulting plan before choosing whether to implement it.

Research and evidence vocabulary requires Archcore CLI 0.8.3 or later. On an older CLI, research falls back to rnd and reports the required version.

When a planned capability has a user-facing surface, such as a UI or a conversational skill, or the repository has features/*.feature files or a BDD test runner, the package adds a journey beside the prd and a scenario after the capability’s spec. See document types. Scenario and journey support requires Archcore CLI 0.8.4 or later; on an older CLI, the agent skips both and reports the required version.

/archcore:document

Describe the present fact in free text. The agent classifies the request from its wording, the branch changes, and the existing documents, then picks the document type.

You write	What it records	Types it can produce
`we decided …`, `document why we chose X`, `make this our standard`	A decision your project made	`adr`, `rule`
`draft an RFC for …`, `should we switch to Y?`	An open proposal	`rfc`
`document the auth module`, `write a guide for the release process`	Existing code, reference material, or a procedure	`spec`, `doc`, `guide`, `task-type`, `scenario`
`file this benchmark report`, `file this vendor PDF as evidence`	A finished report or one external material you already have	`research`, `rnd`, `evidence`

Use a decision your project actually made:

/archcore:document record our decision to use PostgreSQL and the reasons we discussed

A settled decision is an adr. For an open choice such as should we switch to Kubernetes?, the agent asks one question with three exits: record an adr now, draft an rfc first, or investigate first through /archcore:plan. A later we accepted the proposal resolves the rfc into an adr. Review the result before marking it accepted. The agent can offer related rules, guides, or implementation documents when the decision calls for them.

To describe existing code, name the module and the information you need:

/archcore:document how src/payments works and its public boundaries

Use document types to distinguish a behavioral contract (spec) from a reference description (doc). Record current behavior from source; do not turn an undocumented assumption into an accepted contract. When the repository has features/*.feature files, the agent reads them as evidence for specs and scenarios.

To skip the type question, put the type name first. Any type works here, including rule, journey, prd, idea, and cpat:

/archcore:document scenario for checkout

To file a ready report or one external material:

/archcore:document file https://example.com/report as evidence

The URL above is a placeholder: replace it with the material you want to record. A report that ends in a recommendation becomes an rnd; a report that covers a scope becomes a research; one material becomes an evidence. A leading research requests the type research.

The agent asks at most five questions per run. Without arguments, it resumes an open draft, offers a short menu of facts the branch changes suggest, or asks what to record. Planning future work and intended user journeys belong to /archcore:plan.

/archcore:review

/archcore:review
/archcore:review are docs out of date
/archcore:review audit the knowledge base
/archcore:review close out the export feature
/archcore:review capture this repeated change as a pattern

On a branch with changes, the plain command checks the work against recorded context in both directions: whether the changed code still matches the documents that claim it, and whether the changed documents still match the code. Each conflict gets one verdict: spec-wrong, code-wrong, or ok. A matching plan is checked for completion. On the default branch, the scope is the work not pushed to the upstream plus the uncommitted changes. Without any change to review, the command asks for a path, topic, or ref; it has no project-health dashboard.

The wording of the request selects a different run:

You write	Effect
`are docs out of date`, `check if documentation matches the code`	A staleness check
`audit the knowledge base`, `documentation gaps`	A full audit, with coverage and relation findings
`close out <feature>`, `ship the feature and close it out`	Closes a finished feature: reconciles the recorded plan with the implementation
`capture this repeated change as a pattern`	Records a repeated change as a `cpat` or a `task-type`

Name a path, tag, topic, or ref to narrow the review. When the scope includes scenarios, closeout reports whether each example was run, confirmed, or unconfirmed, and lists spec clauses that have no example. Document acceptance and permanent removal remain explicit decisions. Review is the only command that removes a document: a completed plan at closeout, or a long-stale draft, each after your confirmation.

Import existing instructions

Start with one decision, rule, or procedure that the agent will need soon. Ask:

Extract the API error convention from AGENTS.md into an Archcore rule. Preserve its meaning and show me the draft before changing the source instructions.

Review the new document and check retrieval in a fresh session. Then remove duplicated project knowledge from the source instruction file, keeping agent-specific settings and the Archcore managed block.

/archcore:init can also import existing CLAUDE.md, AGENTS.md, and .cursorrules content as part of its preview. Review the import before approving it. Project context explains file organization and relations.

Delegation

Some commands delegate multi-document work to archcore-assistant or read-only auditing to archcore-auditor. You normally request the outcome through the commands above; the skill chooses its helper. The host controls tool permissions.

Next steps

Quick start demonstrates the plan, implement, record, and review loop.
What to expect explains automatic behavior and its limits.
Document types provides the full type-selection reference.