punt-kit
Standards, compliance tooling, and Claude Code plugin development patterns.
Punt-kit serves two purposes. For Punt Labs projects, it is the standards authority — coding conventions, CI templates, naming rules, and an audit checklist that the punt CLI enforces automatically. For Claude Code plugin developers, it is a pattern library — ten reusable design patterns extracted from shipping plugins, plus nine standards documents covering Python, CLI, shell, distribution, and more.
Individual projects reference these standards from their CLAUDE.md rather than duplicating them. The standards/ directory is the source of truth; patterns/ documents the design patterns; AGENTS.md has the full audit checklist.
Platforms: macOS, Linux
punt CLI
Install
curl -fsSL https://raw.githubusercontent.com/punt-labs/punt-kit/e36a3bf/install.sh | sh
Manual install (if you already have uv)
uv tool install punt-kit
Commands
| Command | What it does |
|---|
punt init | Scaffold a new Punt Labs project (CI, linter config, CLAUDE.md, permissions, beads) |
punt audit | Check compliance against standards (read-only, no file changes) |
punt auto <target> | Render and merge managed sections in project files (claude, makefile, settings). Supports --dry-run |
punt release [version] | 11-phase release workflow (preflight → PyPI → cross-repo propagation). Supports --resume-from and --dry-run |
punt pii | Scan repo for PII (emails, home paths, hostnames). Supports --staged for pre-commit |
punt doctor | Check installation health (Python, uv, ruff, mypy, pyright) |
punt status | Show detected project type, standards version, and beads state |
punt version | Print version (punt 0.8.0) |
Global Flags
All commands accept these flags:
| Flag | What it does |
|---|
--json | Output as JSON (machine-readable) |
--verbose / -v | Verbose output |
--quiet / -q | Suppress non-essential output (errors only) |
Usage
# In any Punt Labs project directory:
punt init # Generate missing files
punt audit # Check compliance
punt doctor # Check installation health
punt status # Show project summary
punt pii # Scan for PII leaks
punt pii --staged # Pre-commit: scan only staged files
punt --json status # JSON output for scripting
punt init /path # Target a specific directory
punt init detects the project type (Python, Node.js, Swift, docs) and scaffolds everything a Punt Labs project needs to pass punt audit:
- CI workflows — lint, test, docs, and release workflows from Jinja2 templates
- Python tool config —
[tool.ruff], [tool.mypy], [tool.pyright], [tool.pytest] sections merged into pyproject.toml
- CLAUDE.md — standards references and quality gates tailored to the detected language
- Claude Code permissions —
.claude/settings.json with tool allowlists and standard deny rules
- Gitignore —
.claude/ exceptions appended to .gitignore
- Beads — issue tracking initialized via
bd init
After scaffolding, it reports manual steps that require GitHub access (branch protection rulesets, Copilot code review, Dependabot). Init is idempotent — re-running it updates existing files without overwriting customizations.
punt audit checks all standards without modifying files. It uses gh api to check GitHub-side settings when authenticated.
punt pii scans tracked files for personally identifiable information — email addresses, home directory paths (/Users/X/, /home/X/), and .local hostnames. Configure allow/deny lists in [tool.punt.pii] in pyproject.toml.
Claude Code Plugin
Punt-kit is also a Claude Code plugin (punt@punt-labs on the marketplace). The plugin surfaces CLI commands as slash commands and adds LLM-driven capabilities that are inherently prompt-driven.
