The Workspace Plugin

The code plugin pushes a graph from code, and its /ground pushes evidence links from documents. The workspace plugin works with those boards: you decide what the architecture should become, and it turns documents, decisions, and insights into governed work.

What it is, and what it isn't

The workspace plugin binds no repo: it has no .provenmap/config.json or per-repo install, and connects over MCP access with a token that carries its workspace and scope. Its authoring commands stage board changes on the platform in its token's working copy, never a local file or a code diff; the only thing it stores locally is credentials.

Connect

Important

Changed 12 October 2026: the plugin installs as pmap-workspace, and its commands run as /pmap-workspace:<command>. An installed pmap-architect only points here; your sign-in carries over.

Install it from the marketplace as pmap-workspace:

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

codex plugin marketplace add provenmap/pmap-codex
codex plugin add pmap-workspace@provenmap
# Start a new Codex thread so the commands and the MCP connection load.

The plugin doesn't support Cursor. You can install it beside the code plugin. The two share short command names, so use the prefixed form in practice: /pmap-workspace:start, /pmap-workspace:board. This page writes them short.

The credential is an MCP access token that belongs to you, not to a repo. The two setup paths differ in how the token reaches the plugin:

Sign in with OAuth

/login      # browser sign-in — pick a workspace and a scope

/login opens your browser and generates the token without showing it in the conversation. The plugin stores it 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 path when browser sign-in cannot complete, or when you cannot approve it. You handle the secret yourself.

1. Generate it. On the root hub, open Workspace agent access → Use a key (changed 12 October 2026). Name the token in Label, pick a Scope, set Expires (days), and choose Generate token. Every token covers the whole workspace. The sheet shows the token 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. /configure reads PMAP_MCP_TOKEN, probes it, and stores the grant owner-only. On Claude Code it also writes the MCP entry.

Warning

A keyed connector URL is the secret: anyone who holds it has everything the token grants. Don't paste one into a ticket, chat, or repo.

Note

A token acts as its generating user. Its writes go into the token's own working copy, apart from that person's edits in the portal, and what it writes is recorded under that person's name. Two architects sharing a token would mix their work in progress under one name. Each person 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 the token's working copy
• /logout — removes the token from this machine; it stays live until you revoke it in Workspace agent access
• /help and /update — every command with the installed version and links to what the plugin sends to ProvenMap, or pull the latest build

When a newer plugin version is published, the message at the start of each session names it and says in one sentence what it brings. Run /update, then restart the session. If ProvenMap stops supporting your installed version, the plugin's commands stop with a message that says why and asks you to update. Board tools your assistant calls directly keep working, so only the commands wait on the update.

Day zero

Important

Changed 12 October 2026: the command that sets up an empty workspace is /setup.

Start an empty workspace with /setup. It asks whether you are mapping systems that exist or founding something new, then how you want to describe the systems: in conversation, from named folders, or from documents. It scans only the folders you name. When a folder holds a .NET Aspire AppHost, the landscape comes from the AppHost instead of being inferred:

• Each project resource becomes a system node named after the resource, on an app archetype so it can become an app.
• Postgres, Redis, RabbitMQ, YARP and model runtimes such as Ollama become infrastructure nodes. Each database sits inside its server.
• Each WithReference and each YARP route becomes an edge. WaitFor is noted on its edge as start order and never becomes an edge of its own.
• A resource the AppHost adds only inside a condition is proposed and marked conditional, and you keep or drop it.
• Anything the scan couldn't follow is listed, and the plugin asks you about it.

Each project node matches the scanned repo that contains its project. A repo already bound to a board keeps that board, which moves under its node; every other repo binds when its developer runs the code plugin's /login. If the folders hold more than one AppHost, the plugin asks which one describes your systems.

Every system gets a kind (repo, no-repo, SaaS, planned). The kind decides whether the system becomes an app board, a plain node, an external integration, or a 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

Most sessions begin with /start. With no argument, it prints the command groups, a one-line state summary and a ranked list of next steps, and runs the one you pick from the top three. With free text, it proposes a sequence you confirm once.

Every command ends with an Outcome: what the command did, what it left, and the next command for your current state, with the reason. 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.

/discover reads the whole workspace once and ranks the insights and context boards worth showing. You take the suggested set as is (--auto skips the question), pick from the ranked menus, or refocus the ranking. The insights become an Architecture Highlights batch. The context boards stay in the hub's Context boards card until the next run replaces them, each drawn as a C4 diagram at the level its subject sits on. A board the next run draws again keeps its address, so a link you shared still opens it.

Ask about dependencies

/ask-board gives the same results as the Dependencies panel. Ask in your own words; exact names aren't needed, and when a name matches more than one element it asks which you meant.

Tables, endpoints, channels and pages can be asked about as well as nodes. /ask-board root … follows dependencies between apps; naming an app's board keeps the answer inside that app. With the workspace plugin covers what each result shows and where to go from it.

Authoring

Every work item the plugin creates is a Draft, and a person still hands off each one. Every command lists what each authoring command makes.

/author-playbook turns a job your organization repeats into a playbook. It asks what someone should have finished at the end, checks whether a playbook already does that job, and proposes the stages and steps. You can also start from an existing playbook.

After you approve the read-back, it saves the playbook disabled and links to the composer, where you preview and enable it. /author-playbook needs a Read + write token and a plan that includes custom playbooks (Pro).

/run-playbook carries out a playbook instead of composing one: it works the steps in order with the tools each step names, and reports what proved each step.

It answers a playbook's questions from the board and marks each one once you are satisfied. It asks the named person for a sign-off before recording it, and asks you before it publishes. When a step can only happen elsewhere, such as a command for the repo, it names where and stops.

It never marks a step done. The board decides that, the same way it does when you follow the playbook yourself. A work item step that ends at ✓ Confirmed is handed off and left: it ticks later, when a sync confirms the work item.

For a playbook that runs on an epic, name the epic with --epic <slug>. /run-playbook needs a Read + write token.

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

To work from a document, add a PRD, RFC, or ADR to the session, or draft from the bound copy. Each work item then includes a Drafted from line.

Name a Confluence, Notion or Jira page or paste its link; the session reads it through the connections the token's generating user set up in Settings → Connectors. See MCP Access.

Reviewing

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

Every command

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

Working copies

Every write above is staged in the token's working copy on the platform, apart from your own edits in the portal. The plugin doesn't prompt for each edit; discard the working copy to undo.

Each authoring command ends by previewing what will land, asking you for a one-line reason, and committing with it. The commit accepts the changes and clears the undo log; it creates no work items. A command that hands work to developers, such as /author-work-item, creates its work items itself.

You can also accept or discard the token's working copy in the portal, under Plugin pushes awaiting commit in the top bar's pill. Discard reverts the working copy and reports conflicts. MCP Access covers both endings.

What's next