vergil

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
• 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.

Install

Recommended install path for consuming repositories is the full walkthrough documented in vergil-tooling:

• Quickstart: https://github.com/vergil-project/vergil-tooling/blob/develop/docs/site/docs/getting-started.md
• Detailed walkthrough with rationale: https://github.com/vergil-project/vergil-tooling/blob/develop/docs/site/docs/guides/consuming-repo-setup.md

The short version: add this to your repo's .claude/settings.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:

/plugin marketplace update vergil-marketplace
/reload-plugins

What each step does:

1. /plugin marketplace update <marketplace> — refreshes the marketplace index and downloads the new plugin version into the local cache at ~/.claude/plugins/cache/<plugin-id>/<version>/. The previous version stays on disk for 7 days as a grace window for concurrent sessions, then is removed automatically.
2. /reload-plugins — applies the new skills / hooks / agents to the current Claude Code session without restarting. Without this, the running session keeps using the old in-memory plugin state.

Verify the update

ls -1 ~/.claude/plugins/cache/vergil-marketplace/vergil/

You should see one directory per cached version. The newest version should match the latest tag on GitHub Releases.

References

Sourced from the official Claude Code documentation:

• Plugins reference — CLI commands
• Discover plugins — Apply changes without restarting

Component inventory

Hooks

PreToolUse, PostToolUse, and Stop hooks that enforce guardrails mechanically. Every hook below except block-heredoc is gated on a managed-repo check: a repo must contain vergil.toml at its root for the hook to fire. In repos without this marker, the gated hooks short-circuit to a no-op so the plugin doesn't interfere with ad-hoc git work in unrelated repositories. See the hooks reference for the rationale.