Plugin

An architecture for Claude Code plugins that do sustained work on something, rather than answering a question and exiting.

A plugin ships capability. It is a poor place to keep the work that capability produces, and a worse place to keep the user's own configuration — but that is where both end up, because a plugin is the only piece most authors think to build. The result is a plugin that either carries someone's private data in a public repository, or loses that data every time it updates.

PWV splits it into three parts with three different lifecycles:

Leg	What it is	Lifecycle	Privacy
Plugin	Skills, agents, commands, MCP declarations	Replaced wholesale on /plugin update	Public
Workspace	A private repo instantiated from a public template repo, holding one project's working state	Created once per project, then diverges forever	Private, one per project
Vault	~/.claude-plugins/<name>/ — the user's own config, preferences and credential pointers	Persists across plugin updates; never committed anywhere	Private, local, one per user

The plugin references the other two by variable, never by hardcoded path, so the same published plugin serves its author and a stranger without either one's data touching the other's.

The decision rule

Almost every "where does this file go" question is answered by asking which clock it runs on:

• Does it get thrown away and replaced when the plugin updates? → Plugin
• Is it the thing being worked on, and would you want its history? → Workspace
• Is it true about the user rather than the project, and would you be unhappy to commit it? → Vault

Put a file on the wrong clock and the failure is specific and predictable:

Mistake	What happens
User config inside the plugin directory	Silently wiped by the next /plugin update
Working data in the plugin repo	Published, and mixed into every user's install
User preferences in the template repo	Instantiated into everyone's workspace as though they were defaults
Credentials anywhere but the vault	Committed, eventually

Why the workspace is a repo, not a folder

Because the point of a workspace is that it outlives the conversation, and a folder on one machine is a weak version of that.

Instantiating it from a GitHub template repository buys four things at once:

gh repo create <name> --template <owner>/<template> --private --clone

1. The folder structure is defined in one public, reviewable place — the template repo — rather than generated by code inside the plugin.
2. The workspace starts private and stays private. It is a fresh repo with a squashed initial commit and no upstream link, so nothing in it can flow back.
3. History becomes evidence. For workflows where the order of operations is the guarantee, a commit timestamp proves what a README can only claim.
4. The workspace carries its own instructions. If the template includes the skills, the resulting repo is runnable by any agent, with the plugin uninstalled.

An end user gets a working system by installing the plugin and letting it clone the author's template. An author who wants their own conventions forks the template and points the vault at it. Neither has to touch the other's copy.

Why the vault is outside everything

~/.claude-plugins/<name>/ is the one location that is neither replaced by /plugin update nor tracked by any repository. That is exactly the set of properties user configuration needs, and it is not available anywhere else in the layout.

It holds preferences, defaults, per-user registries, logs and credential pointers — op:// references, environment variable names, vault item titles — never credential values. See docs/vault.md.

Read next

Document	Covers
docs/anatomy.md	What belongs in each leg, file by file, with the awkward cases
docs/variables.md	The binding contract — how the plugin finds the workspace and the vault
docs/vault.md	The ~/.claude-plugins/<name>/ convention and credential handling
docs/sync.md	Keeping a vendored copy of the template in step with the template, and detecting drift
docs/worked-example.md	A real three-legged system, walked through
docs/checklist.md	Ship checklist
reference/	A reusable sync script and skill templates to copy

When not to use this

PWV is overhead, and most plugins should not pay it. A plugin that answers a question, performs a one-shot action, or wraps an API without accumulating anything needs no workspace and often no vault either.

Reach for it when at least two of these hold:

• The work accumulates across sessions and the user will come back to it
• There is state a user would want to read, correct, diff or keep
• The user has settings that should survive a plugin update
• The output should remain usable if the plugin is uninstalled or replaced

One of these on its own is usually served by a vault alone.

Licence

MIT — see LICENSE.