vergil-project/vergil-claude-plugin

Claude Code plugin for the vergil-tooling ecosystem. Delivers
hooks, skills, and agents that enforce the fleet workflow mechanically
in every Claude Code session.
## Table of Contents
What this plugin does
Distribution model
Install
Update
Component inventory
Plugin namespace
Related repositories
Development and deployment
## What this plugin does
This plugin is the behavioral half of a two-repo system:
| Repo | Delivers | Via |
| vergil-tooling | Python CLIs (vrg-commit, vrg-submit-pr, vrg-container-run, …) and Claude Code hook guard | PATH + PreToolUse hook |
| vergil-claude-plugin (this repo) | Claude Code hooks, skills, agents, commands | Claude Code plugin system |
The two are complementary: vergil-tooling makes the tools
available; this plugin ensures Claude Code uses them correctly —
blocking raw git commit in favor of vrg-commit, blocking raw
gh pr create in favor of vrg-submit-pr, routing per-file
validation through the dev container, and so on.
## Distribution model
The plugin ships through a single channel: every consumer — every
vergil-project repo and every external org — registers
vergil-marketplace@main and runs the latest released version. There is no
per-version pinning and no SemVer. The plugin is behavioral guidance (skills,
hooks, agents), not a versioned API that code links against, so "track the
release" is the entire model — and releasing to main is the one act that makes
a new skill or hook live for everyone.
To run unreleased (develop) behavior you don't need a second channel:
Iterating on the plugin? Load the working tree directly with
claude --plugin-dir /path/to/vergil-claude-plugin — see
Develop against the source tree.
Need one unreleased skill ad hoc? Tell the agent to read that file on
develop and follow it — the AI-equivalent of running it by hand.
Full rationale and decision record:
epics/45-plugin-distribution-model/spec.md.
## Install
Recommended install path for consuming repositories is the full
walkthrough documented in vergil-tooling:
Quickstart:
Detailed walkthrough with rationale:
The short version: add this to your repo's .claude/settings.json:
json
"extraKnownMarketplaces": {
"vergil-marketplace": {
"source": {
"source": "github",
"repo": "vergil-project/vergil-claude-plugin",
"ref": "main"
},
"enabledPlugins": {
"vergil@vergil-marketplace": true
Commit that file. Claude Code discovers and enables the plugin on
session start. The "ref": "main" pins the marketplace to the
release branch, so marketplace update tracks the latest
released version (not the develop bleeding edge). The plugin loads
directly from that checkout — there is no separate clone to fail.
Prerequisite: this plugin's commands and skills shell out to
vrg-commit, vrg-submit-pr, vrg-await, and friends from
the vergil-tooling Python package. Install those on your host
PATH first — see the Getting Started guide above.
## Update
After a new release ships, refresh the local install with this
two-step sequence:
text
/plugin marketplace update vergil-marketplace
/reload-plugins
What each step does:
1. /plugin marketplace update — refreshes the
marketplace index and downloads the new plugin version into the
local cache at ~/.claude/plugins/cache/ / /.