maverick: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Maverick is a Claude Code plugin and Python CLI that enables autonomous AI-driven software development with enforced quality, security, and operational best practices. It has three components:

1. Claude Code Plugin — markdown skills (in skills/) and agents (in agents/) that define workflows, best practices, and execution patterns
2. Python CLI (src/maverick/, aliased from cli/) — project initialization, plugin management, and AWS infrastructure provisioning
3. Documentation (docs/) — architecture, philosophy, and enforcement mechanisms

Build & Run Commands

# Install dependencies
uv sync

# Run CLI from source
uv run maverick --help
uv run maverick init --dry-run

# Install system-wide
uv tool install .

# Install in dev mode
uv tool install -e .

# Load plugin from local source for testing
claude --plugin-dir ./maverick-plugin

# Run integration tests
bash tests/integration/test_cli.sh
bash tests/integration/test_real_repos.sh

# Wire up local git hooks (one-time per clone). Installs:
#   - pre-commit: auto-rebuilds skills/agents when src/ templates change
#   - pre-push:   runs `make lint typecheck test` + build-sync check
make install-hooks

# Create a release (two-phase: local prep + CI finalize)
# Phase 1 — run locally from the main branch:
./scripts/release.sh patch   # or: minor, major
# This creates a release/<version> branch from main, bumps version, and opens a PR.
# Phase 2 — automatic after squash-merging the PR:
# CI tags main, creates GitHub Release, then opens a follow-up PR
# that bumps main to the next -dev version.

Architecture

Skills (skills/<name>/SKILL.md)

Markdown files with YAML frontmatter that define machine-readable workflows and best practices. Two categories:

• Best-practice skills (non-invocable): Universal standards for logging, alerting, linting, testing, CI/CD, git workflow, scope boundaries
• Workflow skills (user-invocable): Orchestrate multi-step processes — do-issue-solo (autonomous from GitHub issue), do-issue-guided (interactive with checkpoints from GitHub issue), do-epic (autonomous epic-driven, parallel-wave dispatch), upskill (generate project-specific skills), maverick-alignment (codebase audit). All development work must originate from a GitHub issue — there is no local-file workflow.