Plugin Skills
The plugin is four slash commands. Each one names the outcome it produces before it runs.
You can also describe what you want in plain English: “record the decision to use PostgreSQL”. Archcore handles the request the same way, and the /archcore:* commands below are shortcuts to it.
Everyday context needs no command at all. Lifecycle hooks inject the applicable rules and specs when the agent edits a source file, and the session opens with a recap of what is decided and in progress. See How the plugin works.
All four commands at a glance
Section titled “All four commands at a glance”| Command | Outcome | When to use |
|---|---|---|
/archcore:init | Make your repo legible to AI agents | First-time setup. Detects repo scale, composes a first-day seed in one preview, and wires host configs |
/archcore:plan | Turn a request into the document package it needs | New feature, refactor, or initiative. Name sdd, sources, iso, research, rnd, or evidence to run that path directly |
/archcore:document | Record a decision or document what lives in code | A decision was made, or a module, API, or integration has tribal knowledge but no doc yet |
/archcore:review | Check your changes and your docs against each other | Before merge. Add --drift for staleness, --deep for a full documentation audit |
/archcore:document and /archcore:review classify your request into a track, a gated flow that creates documents step by step. /archcore:plan computes a route first, then runs the instruments that route names.
The diagram’s /archcore:plan branch shows the fixed tracks that shipped before plugin v0.8.0. The route model below is current.
/archcore:init
Section titled “/archcore:init”Outcome: Make your repo legible to AI agents.
/archcore:init/archcore:init --depth=deep/archcore:init --mode=medium/archcore:init --domain=payments/archcore:init --refreshRun this command once per project. It detects repo scale (small, medium, or large) and repo shape, composes a scale-appropriate seed of .archcore/ documents, shows them in one preview, and creates them on a single confirm. It writes nothing before you confirm.
Depending on the detected mode, the seed covers a stack rule, a run-the-app guide, the data model, integrations, config, entry points, the public surface, a linked architecture overview, and specs for the top hotspot modules.
The same confirm installs host wiring: the project MCP config, the SessionStart hook, and the usage hint in CLAUDE.md or AGENTS.md. That is the same wiring archcore init writes, so CLI-only teammates get a working repository.
| Flag | Effect |
|---|---|
--depth=light|standard|deep | Synthesis budget, independent of the scale mode. Sets the hotspot spec coverage rate. Default standard. |
--mode=small|medium|large | Force the scale mode instead of auto-detection. |
--domain=<slug> | Re-run focused on one domain of a large repo, scoping the data model and hotspot specs to that domain’s tree. |
--refresh | Re-run on a seeded repo to add facts that appeared since the first init, and to retrofit host wiring. |
If you already have CLAUDE.md, AGENTS.md, or .cursorrules, init imports them. Aggregate files become link stubs, and modular rule files such as .cursor/rules/*.mdc become rule documents.
After init, /archcore:document and /archcore:plan take over for day-to-day work.
What a depth buys
Section titled “What a depth buys”The hotspot spec budget is a coverage rate over the ranked candidate pool, with no absolute maximum: about 10% of the eligible pool at light, 25% at standard, and 60% at deep, with floors of 3, 4, and 6 specs. A 214-module pool budgets around 54 specs at standard; a 12-module pool budgets 4. Large mode keeps a floor of at least one spec per selected domain and fills the rest by repo-wide rank, and a --domain re-run applies the same formula to that domain’s narrowed pool.
A depth is a ceiling, not a quota. It raises the budget and never fabricates documents to reach a number: if the ranked pool holds 5 modules, deep produces at most 5 specs. Cross-cutting rule synthesis runs at every depth.
Above 25 specs the preview carries a high-volume notice naming the spec count, the estimated tokens, and the cheaper depth. Nothing is written before the single confirm, and the preview prices every depth, so you can switch depth after seeing the plan. The document count is a function of your repository, never a constant.
/archcore:plan
Section titled “/archcore:plan”Outcome: Turn a request into the document package it needs.
/archcore:plan auth redesign/archcore:plan csv export/archcore:plan sdd notifications platform/archcore:plan sources payment market research/archcore:plan iso payment gateway compliance/archcore:plan research vector store landscape/archcore:plan rnd vector store options/archcore:plan evidence https://example.com/benchmark-reportThe skill grounds in .archcore/ and in the code, computes a route from that grounding, announces the route, then runs the instruments the route names. Each instrument creates its documents through MCP and wires their relations. You are never asked to pick a route or a size.
What the route is computed from
Section titled “What the route is computed from”Before anything is created, the conductor derives four values.
| Value | What it holds |
|---|---|
| Δ (canon delta) | What the request does to the accepted document graph: the creates, modifies, and retires capability lists, decision for a settled choice, intent_gap for product intent no document records |
| Π (gap profile) | Where each missing piece of information has to come from: machine, user, world, undecided, or empirical |
| M (maturity) | The maturity of the zone the request touches: stone when an accepted document covers it or a dependent consumes it, pencil otherwise |
| R (risk flags) | external-contract, data-migration, security-compliance, irreversibility, multi-team |
Π decides who answers each open question. A machine need is composed from grounding with no question and cites its artifact. A user need opens an interview inside the question ceiling. A world need runs the research instrument, which produces a research or an rnd by the closing test, an undecided need runs the decision instrument, and an empirical need runs a timeboxed spike whose code never merges.
The five routes
Section titled “The five routes”| Route | Fires when | Package |
|---|---|---|
null | Every Δ list is empty, no decision, no intent gap | Nothing is created |
decision | Only a settled choice is delta | One adr, or an rfc for a proposal still open |
amendment | modifies names an existing capability | The change routed through the code-wrong or spec-wrong verdict against that capability’s spec |
capability | creates holds one capability | One spec plus one plan, plus a prd when intent_gap names goals or metrics beyond that capability’s purpose |
umbrella | creates holds two or more capabilities | One umbrella prd, one spec per capability, one plan |
Four composition rules apply on top of the route:
- A capability whose delta introduces an operational procedure (install, migrate, operate, or verify steps a person performs) adds one
guide. Adata-migrationflag adds a migration runbookguide. - A
decisionoramendmentroute whose implementation spans two or more tasks adds aplan. stonematurity or any risk flag raises the size label one step, and the announcement names the flag that raised it.security-complianceescalates the flagged capability into the ISO links, which raises the size label one further step. An unflagged capability is never escalated.
The size label is derived, never asked: S for null, decision, and amendment, M for capability, L for umbrella. Escalation raises it, capped at XL.
Graph state no longer decides the package. Inside an engaged instrument, a gate whose topic an existing document already covers still closes through skip_when.
The route announcement
Section titled “The route announcement”One line, before any instrument runs:
route: capability (size M) — Δ: creates=[csv-export]; Π: machine, user; M: pencil; R: none; raised by: none; instruments: contract, decomposeA produced plan carries the same declared Δ and route rationale in its ## Declared Delta section, so a later /archcore:review can reconcile what shipped against what the route declared.
When the answer is no document
Section titled “When the answer is no document”“Fix the Safari button overflow” computes to the null route: no capability is created, modified, or retired, no choice is settled, and no product intent is missing. The skill creates no document and reports the empty route. About 30% of the plugin’s 40 recorded routing traces resolve this way, so an empty package is the intended outcome rather than a failure.
Expert paths
Section titled “Expert paths”Naming a path skips the computation and runs it directly.
| Named | Runs |
|---|---|
sdd | The full package: prd, one spec per capability, then plan, each gate at its per-gate question maximum |
sources | The acquisition instrument: mrd → brd → urd, three peer source documents |
iso | The ISO 29148 links: brs → strs → syrs → srs, each requirement carrying a traceability identifier |
research | The research instrument with the type fixed to research: an open investigation closed by coverage of its declared scope |
rnd | The research instrument with the type fixed to rnd: a decision-bound investigation closed by a recommendation |
evidence | The gather gate of the research instrument, filing one external material as an evidence with its first supports or contradicts edge |
| A route name | null, decision, amendment, capability, or umbrella. Δ is still derived, and the name fixes only the route and the label |
| A document type | The instrument that produces that type, entered at its first gate |
When a settled decision surfaces at a gate, the skill records it as an adr through the decision instrument, then returns to the open gate.
Before plugin v0.8.2, research produced an rnd. It now produces a research; name rnd to get the earlier behavior. Without a named type, a request that names a pending decision or a set of candidates produces an rnd, and any other investigation produces a research. The gather gate may also file an evidence for a material two documents rely on, a material a contradicts edge involves, or a material a newer one supersedes; the document and its first edge are written in the same step. On a CLI older than v0.8.3, research falls back to rnd and the skill names the required version.
/archcore:document
Section titled “/archcore:document”Outcome: Record a decision, or document what already lives in code.
/archcore:document use PostgreSQL as the primary database/archcore:document webhook delivery pipeline/archcore:document src/orders/inventory-sync.ts specThe skill classifies your request and runs one of two tracks. Name a type in the invocation (adr, rfc, spec, doc, guide, rule, research, evidence) to skip classification. document research files a ready investigation report as a research; document evidence files one external material as an evidence.
Decision track
Section titled “Decision track”A settled decision becomes an adr. An open proposal (“should we switch to Kubernetes?”) becomes an rfc. After the ADR is recorded, the skill offers one continuation:
| Continuation | Documents | Relations created | Use when |
|---|---|---|---|
| Standard | rule, guide, optional cpat | rule implements adr, guide related rule, cpat implements adr, rule related cpat | The decision describes enforceable behavior everyone follows. |
| Architecture | spec, plan | spec implements adr, plan implements spec | The decision establishes or changes a boundary contract. |
The ADR alone is a valid endpoint. The skill creates continuation documents only after you confirm the cascade.
An open rfc resolves through the same track. Say “we accepted the proposal” or “resolve the RFC”, and the skill enters at decision.resolve: the proposal becomes an adr or is marked rejected. The status changes only after you confirm the verdict.
Describe track
Section titled “Describe track”For code documentation, the skill reads the subject first, then picks the type from that evidence: spec for behavior others rely on, doc for reference material, guide for how-to instructions.
Use this track when a module, API, pipeline, or integration has tribal knowledge but no document yet.
/archcore:review
Section titled “/archcore:review”Outcome: Check your changes and your docs against each other.
/archcore:review # branch review against .archcore//archcore:review --drift # staleness detection/archcore:review --deep # full documentation audit/archcore:review --deep tag:auth # full audit, scoped to a tagOn a branch with changes, review compares the branch diff with .archcore/ in both directions: whether the changed code still matches the documents that claim it, and whether the changed documents still match the code they describe. Each finding carries one verdict, spec-wrong, code-wrong, or ok, with the evidence cited.
On the default branch, or with an empty diff, review reports project health instead: counts by category, status, and type, relation counts, orphaned documents, and a one-line issues summary.
--driftruns the actualize track over the scope: code drift (a document references source that changed), cascade drift (a dependency was updated without the dependent being reviewed), and temporal drift.--deepwidens the scope to every document and adds coverage gaps, relation health, and consistency findings alongside the drift verdicts.- A path, tag, or scope argument narrows or replaces the branch scope.
Say “close out the feature” and review runs the closeout track: it verifies the plan against the branch diff, merges the document updates you approve, and moves the finished drafts to accepted. A document status changes only after you confirm the transition.
When the reviewed changes repeat a pattern that no document records, review offers to capture it as a cpat or a task-type. It asks once, and a decline writes nothing.
How a slash command activates
Section titled “How a slash command activates”- You type a slash command (
/archcore:document) or describe an intent in plain English (“record the decision to use PostgreSQL”). - The host matches your request to a skill definition shipped with the plugin.
- The host loads the skill into the conversation. Its description, gates, and relation rules become part of the agent’s working context.
- The agent executes the skill, calling MCP tools as needed.
Every command resolves to MCP tool calls. The plugin never writes to .archcore/ directly: the PreToolUse hook blocks Write and Edit on .archcore/*.md, so every mutation goes through create_document, update_document, or add_relation.
Next steps
Section titled “Next steps”- Built-in agents covers the two agents that back complex multi-document flows.
- Document types lists the 21 types these commands route to.
- Skills reference is a one-page lookup of all four commands.