The Architect Workbench

The code plugin pushes a graph from code. The connect plugin pushes evidence links from documents. The architect plugin is for working with those boards: deciding what the architecture should become and turning documents, decisions, and insights into governed work.

What it is, and what it isn't

It is the only plugin that binds no repo. There is no .provenmap/config.json, board slug per project, or per-repo install. It connects over MCP access, with a token that stores workspace, scope, and optional board restriction.

Architecture authoring never edits local files. It stages board changes on the platform in your working copy. Account commands store credentials locally. It can read local material you point it at, such as RFCs or ADRs, but it produces board content, not a code diff.

Compared with chat, it uses the same boards and tools from a different surface. Chat is browser conversation; the plugin is longer or batch work in your AI host.

Connect

Install it from the marketplace as pmap-architect:

/plugin marketplace add provenmap/pmap-claude
/plugin install pmap-architect@provenmap
# Restart Claude Code so the commands and the MCP connection load.

Cursor is not supported yet. You can install it beside the code or connect plugin. Because they share short command names, prefix commands in practice: /pmap-architect:start, /pmap-architect:board. This page writes them short.

The credential is an MCP access token belonging to you, not to a repo. What differs is how the token reaches the plugin:

Sign in with OAuth

This follows the same shape as the code plugin's login:

/login      # browser sign-in — pick a workspace, a scope, an optional board restriction
/hub        # the morning sweep: what needs an architect right now

/login opens your browser and generates the token without exposing it in the conversation. It is stored user-scope in your home directory. Restart Claude Code afterwards so the MCP connection loads. Read + write is on every plan, Free included.

Two caveats: approving /login needs workspace admin, and Codex needs one manual step. On Codex, set PMAP_MCP_TOKEN from the stored file, then start a new Codex thread.

Generate a key, then configure

Use this where browser sign-in cannot complete, or when you cannot approve it. You handle the secret yourself.

1. Generate it. On the workspace command center, open Architect access → Generate a key. Pick a scope, expiry, and optional board restriction. The token is shown exactly once, with setup snippets.

2. Wire it in, using the row that matches where the session runs:

Add PMAP_MCP_URL alongside the token for a self-hosted endpoint.

3. Verify with /configure for the environment-variable rows. It reads PMAP_MCP_TOKEN, probes it, stores the grant owner-only, and on Claude Code writes the MCP entry.

Warning

A keyed connector URL is the secret. Anyone holding it has everything the token grants. Do not paste one into a ticket, chat, or repo.

Note

A token acts as its generating user. Its writes join that person's working copy, so a shared token would merge two architects' work in progress. Everyone should generate their own.

Signing In & Credentials has the decision table for every environment, and how this credential differs from the code plugin's.

The rest

Other commands:

• /status — endpoint, scope, restriction, and what's in your working copy
• /logout — removes the token from this machine; it stays live until you revoke it in Architect access
• /help and /update — every command with the installed version, or pull the latest build

Day zero

An empty workspace starts with /setup-workspace. It asks whether you are mapping systems that exist or founding something new, then asks how to describe the systems: conversation, named folders, or documents. Scanning only runs on folders you name.

Every system gets a kind (repo, no-repo, SaaS, planned), which decides whether it becomes an app board, plain node, external integration, or target state.

Getting Started — Plugin or Chat covers the day-zero path. Once a repo binds, systems join one at a time through /new-app.

The daily loop

/start is the command to remember. With no argument, it prints the command groups, then a ranked list of next steps under a one-line state summary: connection, boards, what needs attention, drafts in flight. It offers the top three as a choice and runs the one you pick. With free text, it proposes a sequence you confirm once.

Every command ends with an Outcome written for that run: what it did, what it left, and the next command with the reason, for the state you are in. After /new-app, for example, it names /prepare-app for the new app and says why: the app is marked new and has no sequenced intents yet. Work that belongs to developers in their repo, such as connecting it with the code plugin, appears as a Hand off line rather than a command. This plugin runs outside any repo, so those commands have no meaning here. A new session opens with a pointer at /start.

/hub is the morning check: decisions first, portfolio beneath.

/board [slug] opens a working session on one board.

/ask-board <question> answers a question about named boards. It can offer a context board when drawing the relationships is clearer than prose.

/discover reads the whole workspace once and scores what the graph can answer on its own. It offers ranked menus for insights and context boards, with a recommended set you can run as is (--auto). Agents author the picks in parallel. The insights become an Architecture Highlights batch, while the context boards remain in the hub's Context boards card until the next run replaces them. Each context board is drawn as a C4 diagram at the level its subject sits on: system context from the landscape, container from an app board, component from a drill-down.

Authoring

Use these commands to author board content:

/author-intent asks about gaps before creating an anchored draft intent.

/intents works the queue and creates drafts for platform review. /new-app places a new system and drafts its founding intent.

/prepare-app prepares a new app for implementation: review its requirements, create sequenced intents, and choose compiled skills.

/adopt-adr creates a decision record, checks systems against it, and turns existing disagreements into per-app remediation intents.

/archetypes reviews the archetype catalogue for a board kind and submits proposals for an admin to approve.

/style-board restyles one hand-authored board after you approve a styling plan. Boards pushed by the code plugin arrive styled.

Working from a document? Drop a PRD, RFC, or ADR into the session, or draft from the bound copy. Each intent includes a Drafted from line.

Reviewing

/assess runs a structured review: frame, sweep, defend each insight with you, and record. Frame against an insight skill or an ad-hoc dimension.

/insights creates draft intents from insights you have reviewed.

Every command

The write column describes changes to board content in the platform working copy. Account commands can store credentials locally. Run /help for the list generated from your installed build.

Two commands write more than their labels suggest: /board makes governed edits, and /insights generates a draft intent for every selected insight.

Working copies

Everything above is staged in your working copy on the platform. There are no prompts per edit because the whole working copy can be discarded.

Commit from the plugin or the portal Topbar pill; they are the same session. Commit generates a proposal per governed root and clears the undo log. Discard reverts the session and reports conflicts. MCP Access covers both endings.

Whatever the plugin proposes, a person still hands it off. The plugin creates intents as drafts.

What's next