convez.ai
SkillDevOps & InfraestruturaAvançado
vergil-project

VERGIL Claude Plugin

vergil-project/vergil-claude-plugin

Hooks e agents que enforçam o fluxo VERGIL em Claude Code

Ver no GitHub
BomPluginScore · de 0 a 100

Plugin para Claude Code que integra o ecossistema VERGIL, fornecendo hooks, skills e agents que garantem a execução correta do fluxo de trabalho em sessões de codificação. Bloqueia operações diretas (como git commit raw) em favor de comandos validados através da toolchain VERGIL, roteando validações por arquivo através do container de desenvolvimento.

Instalação

$npx convez-ai vergil-project/vergil-claude-plugin

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
87%
Último commit
há 1 dia
Versão
v2.1.77
Issues abertas
14
Contribuidores
2

Casos de uso

  • Enforçar commits validados via vrg-commit em vez de git commit direto
  • Bloquear PRs raw em favor de vrg-submit-pr com validação
  • Rotear validações per-arquivo através de dev containers
  • Orquestrar workflows complexos com agents e skills VERGIL

Veredito

Ferramenta especializada para times que já adotaram a arquitetura VERGIL. Exige instalação da toolchain Python vergil-tooling prévia e é mais relevante para repositórios sob governança de workflow rígida. Integração robusta, mas não é plug-and-play para novos usuários.

README

A tradução para o português deste README ainda está na fila.

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

This plugin is the behavioral half of a two-repo system:

RepoDeliversVia
vergil-toolingPython CLIs (vrg-commit, vrg-submit-pr, vrg-container-run, …) and Claude Code hook guardPATH + PreToolUse hook
vergil-claude-plugin (this repo)Claude Code hooks, skills, agents, commandsClaude 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:

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:

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.

HookMatcherPurpose
block-raw-git-commitPreToolUse/BashRedirects raw git commit to vrg-commit
block-raw-gh-pr-createPreToolUse/BashRedirects raw gh pr create to vrg-submit-pr
block-protected-branch-workPreToolUse/BashBlocks commits from outside .worktrees/* on repos that adopt the worktree convention; otherwise blocks commits on develop/main
block-heredocPreToolUse/BashBlocks <<EOF in CLI args (use --body-file or $(cat <file>))
block-associative-arraysPreToolUse/BashBlocks bash 4+ associative arrays — host scripts must run on macOS bash 3.2
enforce-host-container-splitPreToolUse/BashDenies wrapping host-only tools in vrg-container-run; warns on bare container-only tools
block-autoclose-linkagePreToolUse/BashBlocks --linkage Fixes/Closes/Resolves in vrg-submit-pr — use Ref instead
block-agent-mergePreToolUse/BashUnconditionally blocks gh pr merge / gh pr review --approve — merging is the human's Phase-6 action
block-github-contents-apiPreToolUse/BashBlocks write-method gh api calls to the Contents API — file changes go through the local workflow
block-worktree-bypass-writePreToolUse/Write|EditBlocks edits to the main worktree when the worktree convention is active
guard-audit-writesPreToolUse/Write|Edit|NotebookEditAUDIT identity may write only .vergil/audit-* and build/ — soft gate on the audit's read-only discipline
detect-deprecation-warningsPostToolUse/BashSurfaces deprecation warnings from test output for triage

Full reference: https://github.com/vergil-project/vergil-claude-plugin/blob/develop/docs/site/docs/hooks/index.md.

Skills

Shared workflow skills, invoked as /vergil:<name>.

SkillPurpose
implementUSER agent: implement an issue, validate to green, hand off to the audit pair
auditAUDIT agent: review the change delta read-only, write the verdict
pr-watchPost-PR loop — monitor/reconcile (USER) or re-review and gate (AUDIT)
deprecation-triageTriage deprecation warnings into tracking issues
summarizeDecision / operation / stream-of-consciousness summaries
handoffSession-to-session continuity (capture/resume)
memory-auditCollaborative review of memory files
memory-initInitialize the memory directory with the policy header

Full reference: https://github.com/vergil-project/vergil-claude-plugin/blob/develop/docs/site/docs/skills/index.md.

Agents

AgentPurpose
bootstrapSession-start preflight: repository profile, branch state, standards reference, hook guard availability

Plugin namespace

All skills are namespaced under vergil (the plugin's name):

/vergil:<skill-name>

Example: /vergil:implement.

Related repositories

  • vergil-tooling — Python CLIs, bash validators, git hooks (consumed via PATH).
  • vergil-docker — Dev container images (ghcr.io/vergil-project/dev-python, dev-go, etc.) that vrg-container-run dispatches into.
  • vergil-actions — Shared GitHub Actions composite actions consumed by CI.

Development and deployment

This section covers contributing to the plugin itself — how to set up a working environment and ship a change. Distinct from the Install and Update sections, which cover how a consumer of the plugin uses it.

Set up a worktree

Sessions on this repo always start at the project root (~/dev/github/vergil-claude-plugin/), never inside a worktree. Each in-flight issue gets its own worktree under .worktrees/issue-<N>-<slug>/ on a feature/<N>-<slug> branch. The full procedure (issue resolution, sub-issue creation, worktree+branch creation, agent prompt template) lives at docs/development/starting-work-on-an-issue.md.

The worktree convention is enforced by the block-protected-branch-work hook: commits originating from outside .worktrees/*/ are denied.

Ship a change

Under the Vergil 2.1 workflow, the agent prepares the change and the human opens the PR:

  1. The USER agent runs /vergil:implement <issue> — implement, validate to green, and write .vergil/pr-template.yml.
  2. You run vrg-submit-pr to open the PR (agents cannot).
  3. Paste the emitted /vergil:pr-watch <PR_URL> into both the USER and AUDIT agent sessions for the post-PR loop; the AUDIT identity gates merge via the vergil-audit/approved check.

Auto-merge is disabled fleet-wide; you review and merge feature/bugfix PRs manually.

Transition note. This flow requires vergil-tooling 2.1 installed site-wide. Until then, submit changes manually the 2.0 way; the 2.1 skills are authored but not yet wired into daily dev.

Cut a release

Releases are cut via vrg-publish, a standalone CLI in vergil-tooling. See the vergil-tooling documentation for usage.

Develop against the source tree

When iterating on hooks or skills before release, load the plugin directly from the source tree to avoid the marketplace round-trip:

claude --plugin-dir /path/to/vergil-claude-plugin

This bypasses ~/.claude/plugins/cache/ and mounts the working tree as the plugin source.

Reporting issues

Open an issue at https://github.com/vergil-project/vergil-claude-plugin/issues.

Ver o original no GitHub

Bom para

Relacionados