Getting Started¶

A five-to-ten minute quickstart for wiring up a new repository to use vergil-tooling. For the detailed walkthrough with rationale, CI config, and troubleshooting, see Consuming Repo Setup.

Prerequisites¶

Install these on your host:

Docker — the dev container engine
uv — Python package manager (install)
gh CLI — GitHub CLI, authenticated (gh auth login)
macOS or Linux (Bash)

Everything else — language runtimes, linters, test frameworks, and most st-* tools — lives inside the dev container. The host-side st-* tools (vrg-docker-run, vrg-commit, vrg-submit-pr, etc.) are installed via uv tool install.

1. Install vergil-tooling on the host¶

uv tool install 'vergil-tooling @ git+https://github.com/vergil-project/vergil-tooling@v1.4'

This installs all st-* console scripts into ~/.local/bin/, which uv's installer already puts on PATH.

which vrg-docker-run    # should resolve to ~/.local/bin/vrg-docker-run
vrg-docker-run --help   # should print usage

2. Configure git hooks in your consuming repo¶

Every managed repo checks in a .githooks/pre-commit env-var gate (see Consuming Repo Setup for the gate content). Enable it once per clone:

git config core.hooksPath .githooks

3. Enable the Claude Code plugin¶

Create .claude/settings.json in your repo:

{
  "extraKnownMarketplaces": {
    "vergil-tooling-marketplace": {
      "source": {
        "source": "github",
        "repo": "vergil-project/vergil-claude-plugin"
      }
    }
  },
  "enabledPlugins": {
    "vergil-tooling@vergil-tooling-marketplace": true
  }
}

Commit this file — it's part of the repo's reproducible setup.

Plugin install is a known rough edge

The install/update flow for the plugin itself is tracked in vergil-claude-plugin#46. For now, this settings.json entry is enough for Claude Code to discover and enable the plugin on the next session restart.

4. Create your repository profile¶

Create docs/repository-standards.md with the six required attributes (and AI co-author entries if you'll use them):

# Repository Standards

## Table of Contents

- [AI co-authors](#ai-co-authors)
- [Repository profile](#repository-profile)

## AI co-authors

- Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

## Repository profile

- repository_type: library
- versioning_scheme: semver
- branching_model: library-release
- release_model: tagged-release
- supported_release_lines: 1
- primary_language: python

Pick the values that match your repo. See Consuming Repo Setup for the full attribute reference.

5. Adopt the worktree convention¶

Add .worktrees/ to your .gitignore:

echo '.worktrees/' >> .gitignore

Add a "Parallel AI agent development" section to your CLAUDE.md describing the convention. Every managed repo already has one you can copy from; the canonical source is the worktree convention spec.

6. Verify¶

# Host tooling reachable
vrg-docker-run --help

# Repo profile validates (runs inside the container)
vrg-docker-run -- uv run vrg-repo-profile

# Git hook blocks raw git commit
git commit --allow-empty -m "test"    # should be blocked by the gate

If all three behave as expected, you're wired up correctly.

Next steps¶

Consuming Repo Setup — detailed walkthrough including CI workflow, plugin nuances, and troubleshooting.
Git Workflow — branching, commit / PR / finalize cycle, two-layer enforcement, worktrees in practice.
Worktree convention spec — full rationale for the parallel-agent convention, failure modes, memory-path implications.