The Architect Workbench

The code and docs plugins push boards up from your sources. The architect plugin is for the people who work those boards — deciding what the architecture should become, and turning documents, decisions, and findings into governed work.

It runs in the AI host your developers already use, and it reaches your workspace over the platform's MCP endpoint. No repo binding, no project files: an MCP access token carries the whole identity — workspace, scope, and an optional board restriction. MCP Access covers minting, fencing, and revoking them.

Install

/plugin marketplace add provenmap/prov-claude
/plugin install prov-architect@provenmap

Install it alongside the code or docs plugin in the same host — they don't overlap. Cursor isn't supported yet.

Note

Commands are namespaced: /prov-architect:start, /prov-architect:board, and so on. That matters if you also run the code plugin, since both answer to names like /login and /intents. This page writes them short — prefix them in practice.

Connect

Run /login. The browser opens, you pick a workspace, a scope, and optionally a board restriction, and we store the minted token for you — owner-only, outside any repo. It never appears in the chat.

Approving needs workspace admin permission. If that's not you, an admin mints a token under workspace settings → MCP access tokens and /configure walks you through wiring it.

Tip

In a container-backed session — a cloud workspace, a fresh devbox — a stored login won't carry over, because it lives in your home directory on the machine that ran it. Set the token as a PROV_MCP_TOKEN environment secret instead and the plugin picks it up with no browser round-trip per session.

/status probes the connection and reports the token's workspace, scope, and restriction. /logout disconnects this machine; revoking the token itself happens in workspace settings and takes effect on the very next call. /help lists every command with the installed version, and /update pulls the latest plugin build.

Start here

One command is worth remembering:

/prov-architect:start

With no argument it reads your actual state — connection, drafts you left mid-interview, sessions still open, what's waiting in the attention queue — and tells you the single most useful next thing to run. An empty workspace leads with setup. A half-finished spec offers to resume. Bounced intents surface before inventory.

Give it free text and it routes instead: "we're acquiring Northwind — absorb their systems" becomes a proposed sequence (extend the landscape, plan each system, adopt the integration decisions), confirmed once, then run. You don't have to learn the command list to use the plugin — /start is a door into all of it.

The workflows

Set up the estate

/setup-workspace is a one-time window: once the first repo binds, systems get added one at a time with /new-app. App boards are born empty on purpose — their content arrives from developer pushes, not from the interview. When a repo later pushes, analysis reconciles reality against the sketch, and disagreements surface as intents.

Ask and explore

/ask-board escalates when prose isn't the right answer. If what you asked for is a subgraph — a trace, a cross-app flow, more than a handful of related elements — it offers to draw a context board instead, hands back the slug, and offers to clean it up at the end of the session.

/hub leads with a "since your last visit" delta and a ranked queue rather than an inventory, so a morning sweep starts with the things that moved.

Author what should change

/adopt-adr is the one to notice. It doesn't just record a decision — it sweeps the affected apps for where reality already disagrees, classifies each as compliant, violating, or unclear, and offers to turn the violations into remediation work. The decision and its enforcement land together.

Working from a document? Drop a PRD, RFC, or ADR into the session and the plugin reads it directly — no upload to the workspace first — then drafts specs or intents anchored to the right board elements. Documents already bound to a board are readable too.

Review what's there

/assess reviews findings in reverse — it walks each one with you and keeps only what survives the challenge, so a recorded run reflects your judgment rather than the model's first pass.

Every write is a draft

There are no confirmation gates, because there don't need to be. A change to a governed board stages itself and mints a reviewable intent. The session narrates it plainly — "staged as intent X — delete it to revert" — and deleting or rejecting the draft reverts everything it staged.

Multi-step work goes further: related changes are grouped into a write session that commits or discards as one unit. Walk away mid-setup and the entire scaffold — landscape, boards, and all — unwinds together. Conflicts are reported, never silently overwritten.

That's why handing someone a read_write token is safe: review stays with your team, on the board, where it always was. You release intents when they're ready, and developers pull them with the code plugin's /intents and deliver. See Intents and Specs for how drafts flow through review.

Two things worth knowing up front

Specs and intents need a code-bound board. They anchor to elements a repo actually owns, so they live on app boards — not on the system landscape, and not on a plain layer beneath an app board. The plugin routes around this rather than failing at you: authoring on a layer walks up to the owning app board and says so, a request spanning several apps is federated into one spec per app, and an unbound board gets the binding offered in-session instead of an error.

Interviews survive interruption. The longer workflows keep their running draft on disk, so losing context or closing the session doesn't lose the work. /start and /status surface what's in flight and offer to resume.

When to use it instead of chat

Chat does the same governed work inside the portal, and for most questions it's the better door: it's in the browser, needs no install, and the thread is a shared team space.

Reach for the workbench when chat's shape gets in the way:

Both write to the same boards through the same fences, so there's no wrong choice — only a slower one.

Troubleshooting

What's next