The Code Plugin

The code plugin is how your codebase and your boards stay in step. It runs inside the AI coding agent you already use — Claude Code, Codex, or Cursor — and it doesn't try to replace it: your agent still reads and writes the code, while the plugin keeps track of the system that code adds up to.

That traffic runs both ways. Going up, the plugin analyses your project locally and builds a structured graph of services, APIs, databases and how they connect — so you never draw the diagram. Coming down, the board sends back everything your app has learned about how it should be built: compiled skills, the intents someone authored on the board, unbuilt design, and aspect contracts.

This page is the complete reference. For a guided first run, start with Getting Started — Hands-On.

Note

Everything the plugin does runs inside your own AI coding session and needs no model provider connected. Connecting a model is only for the portal's in-app Chat.

What the code plugin is

It's one of three plugins, and the one that maps code. It binds a single repo to a single board as a governing Code Plugin source, analyses that repo on your machine, and pushes a finished graph. That one governing slot is what turns the board into an app board.

The other two do different jobs, and it's worth knowing which you want before you install anything:

• The connect plugin also binds a repo, but the repo holds documents rather than code, and it grounds a board someone already authored instead of building one. Its /sync is a different command from this one's.
• The architect plugin binds nothing. It reaches your whole workspace over an MCP token and works the boards rather than building them.

Install and connect

The install id is pmap-code. Add the marketplace for your host, install the plugin, then restart the host so its commands load.

/plugin marketplace add provenmap/pmap-claude
/plugin install pmap-code@provenmap

Then connect the repo to its board:

• /login opens your browser, signs you in, and lets you pick a workspace and board. The plugin writes the credentials into .provenmap/config.json itself — nothing to copy by hand. Already bound and want a different board? /login switch reopens the picker and rebinds.
• /configure is the manual path, for hand-managed credentials, self-hosted instances and CI. It reads the config file, validates it, and tests the connection. It will never ask you to paste a bindingToken or apiSecret into chat.
• /status is read-only and offline: what's configured, which boards exist, what's synced, and which files have changed since each board was last analysed.
• /start reads the same local state and names the single most useful next command — blocking problems first, and alone. Run it whenever you're unsure.
• /logout clears this project's credentials; /update pulls the latest plugin build.

Expand

Credentials

/login writes four things into .provenmap/config.json and adds .provenmap/ to your .gitignore:

The API secret leaves our servers at exactly two moments: when the governing binding is created, and when you regenerate it. The bind-time dialog shows it once, with per-line copy buttons; after that, asking for the binding's credentials returns ck_cp_live_**** and nothing more.

So if you miss the moment, there's one way back — open the binding's row on the board's hub and choose Regenerate secret & copy. That mints a fresh secret and invalidates the old one immediately, which means anything else using the old secret stops working until you re-copy. Connecting Sources walks the bind flow; the Boards API reference covers the headers underneath.

The lifecycle

The commands fall into five stages, and they form a loop rather than a line: /monitor findings become insights an architect turns into intents; /build and /intents change the code; /analyze and /sync put the change on the board; /insights evaluates the new state.

You don't have to memorise any of it — /start works out where you are and names the next command. The stages are the map behind its answer.

Map

/analyze-archetypes comes first. It settles the archetype vocabulary — the node types your board will use — by scanning for patterns your workspace's catalogue has no type for and submitting proposals for admin review. Every node then lands on a fitting type instead of a misfit you'd have to re-type later. This is a real precondition: /analyze stops on it via an exit code, not a suggestion in prose, and it re-prompts whenever the catalogue or your commit has drifted. Admins review the proposals in Archetypes.

/analyze maps the system. It scans the project for services, APIs, databases and queues and builds a structured graph of how they connect. It runs entirely locally and pushes nothing, and it never touches your source files.

/analyze                                           # incremental pass over what changed
/analyze --clean                                   # full re-analysis from scratch
/analyze --drill <parent-board-slug>/<node-slug>   # map one node into its own child board
/analyze --all                                     # progressive pass across all layers

Analysis is incremental by default — it reads the git diff since the commit it last analysed and only re-touches what moved. Reach for --clean when an incremental result looks stale. Each run also reports analysis coverage: how much of the repo your boards actually describe, what's still pending, and which nodes have gone stale. Those numbers land on the hub's coverage card, described in App Boards.

/sync pushes. It pulls the board's current server state, computes the difference, and pushes only that.

/sync                  # one board (prompts if you have several)
/sync --board <slug>   # a specific board
/sync --all            # the whole layered tree

/sync is also what proves intents: where an intent proposed a structural change, a push that matches it stamps the intent verified.

Warning

By default every synced node and edge carries a source reference — the relative file path it came from, plus a link into your git host when a remote is configured. If those paths are sensitive, set "includeSourceReferences": false in .provenmap/config.json and /sync pushes no file paths at all. Your local analysis under .provenmap/boards/ keeps them, so you can turn it back on later without re-analysing.

/adopt, in full

Beyond nodes and edges, a board carries aspects — typed detail hanging off the graph. /adopt extracts one aspect from the code and reconciles it onto the bound board; rows a person authored on the portal are never overwritten.

/adopt --aspect <kind> [--mode replace|merge] [--dry-run]

Five kinds ship today:

--db and --api are back-compat shorthand for the first two — they resolve to --aspect database.schema and --aspect api.surface. Extraction reads definitions only: it never runs your app, connects to a live database, or evaluates a policy against real inputs.

One precondition: the board's spine has to be synced first. Run /analyze and /sync before /adopt, or it stops and tells you to.

/inspect

/inspect turns what you see into something the board can carry. It opens your running app in a real browser, on a throwaway profile, with a small draggable toolbar: browse the app normally, arm Pick to select a component, or arm Annotate to drag a box over a region and attach a note.

/inspect                          # open the running app and record a session
/inspect --url http://localhost:3000
/inspect --capture <url>          # headless: screenshot + element map, no human
/inspect --list | --show <id>     # review recorded sessions

Each session is saved locally and needs no credentials to capture — only sharing it back does. When you push one, two things happen: the screenshots become an intent's visual context for an architect to annotate, and each correlated page's clean screenshot plus element map is stored on its ui.page aspect as a page capture. That's the board's live picture of the screen, and it's what the Pages screen renders.

Expand

Understand

/insights runs the insight skills your workspace defines — security checks, quality reviews, dependency audits. The server defines what each skill looks for; the plugin does the reasoning locally, reading the board and your source files, then pushes the findings back. Each finding ties to a specific element and highlights it on the diagram. From there an architect can create an intent from a finding, which is how an analysis becomes a change.

/demo-insights makes a freshly mapped board presentable: a small set of path-rich findings, each tracing a legible route across several nodes, using the same skills and push pipeline.

/monitor is the Operate stage, and it closes the loop from the other end. It pulls recent signals from your monitoring tools — error trackers, CloudWatch alarms and log patterns, cloud-cost deltas — and correlates them with the board: a deterministic matcher maps stack frames, resource names, routes and tags onto board elements, and uncertain matches become teach-once prompts you answer exactly once. The shaped findings land as insights an architect reviews.

/monitor                          # pull signals from connected monitoring tools
/monitor --input <signals-file>   # or feed an exported, normalized signals file
/monitor setup                    # configure sources and a recurring run

/monitor setup scaffolds the config, prints the connect one-liners for your vendors, and — where the host supports it — creates the recurring run. Unattended runs read credentials from the PMAP_* environment variables, so secrets never transit the chat.

Build

The Build stage is what makes the pipeline two-way: the platform carries your app's build context, and these three commands make it real in code. All three write files in your project — they're the only ones that do.

/skills compiles the skills composed for this app into IDE-native files in your repo (for Claude Code, .claude/skills/). A compiled skill is more than a SKILL.md: it can ship reference files the agent loads on demand and executable scripts/ for the deterministic steps it defines. Related skills arrive grouped into a recipe, with a short index over its members.

The write is never-clobber. A committed lock manifest, pmap-skills.lock.json, records every file the command wrote, so a file you edited locally is detected, reported, and left alone. The CLI owns the writing — the agent never edits skill files itself. Commit the compiled skills and the lock, and the whole team shares them.

/skills            # compile the bundle into the repo
/skills --status   # read-only: up to date? changed upstream? edited locally?

/build implements that build context for this app, including in an empty repo. It assembles a build pack in order of primacy — compiled skills first, then open intents, then board design with no source mapping yet, then aspect contracts materialized as migrations and endpoint contracts. It classifies the repo, presents a plan, and touches nothing until you approve it.

/build           # assemble the build context, plan, then implement after approval
/build --plan    # present the plan only — no files touched

It's incremental and idempotent: the build context keeps evolving on the platform, and re-running builds only the delta.

/intents pulls the queue of work an architect authored on the board. The flow is deliberate — claim (single-winner, so two developers can't silently duplicate work), implement from the intent's Instructions and its anchor-to-file map, verify with the project's own checks, then resolve as implemented, rejected, or resolved elsewhere, with a note the architect reads. It never edits before the claim and a mandatory gap review, and it never resolves an intent as implemented without recorded verify evidence. Stale intents — where the board moved after authoring — are flagged and blocked from silent implementation.

Authoring intents, releasing them and assigning them happens on the portal; see Intents.

Every command

Eighteen commands. Only three write files in your project.

Configuration reference

/login writes .provenmap/config.json and keeps it out of git. You come here for two reasons: to tune what gets analysed, or to run without a browser.

For scheduled and CI runs, every credential can come from the environment instead: PMAP_BINDING_TOKEN, PMAP_API_SECRET, PMAP_BOARD_SLUG, PMAP_BRANCH, PMAP_BASE_URL. Environment values win over the file, so you can override one field without rewriting the config.

Everything else the plugin writes lives under .provenmap/, gitignored: boards/ (the board registry and per-board analysis), skeletons/ and coverage.json (the file inventories and the analysis-coverage ledger), aspects/tmp/ (adopted aspect payloads), inspections/ (/inspect sessions), intents/, insights/, build/ and monitoring/. Two things are meant to be committed, both written by /skills: the compiled skill files and their pmap-skills.lock.json.

There is no background auto-sync. Analysis, sync and monitoring happen only when you — or a schedule you created — run the commands.

When a run fails

Four failures account for most of them.

Expand

What's next