debug

dot-claude

Claude Code plugins for productivity workflows - skills, agents, commands, and hooks.

Overview

dot-claude is a collection of plugins that extend Claude Code with specialized capabilities for software engineering workflows. It provides:

• 30 Skills - Reusable workflow patterns for TDD, debugging, documentation, and more
• 19 Agents - Specialized subagents for code review, security analysis, and expert domains
• 17 Commands - Slash commands for common tasks like commits, planning, and scaffolding
• Hooks - Automated enforcement of TDD, commit standards, and verification workflows

Plugins

Plugin	Purpose
core	Essential workflows: TDD enforcement, verification, brainstorming
workflow	Planning and execution: plans, subagents, worktrees, branch finishing
review	Code review: requesting reviews, receiving feedback, security analysis
testing	Test patterns: anti-patterns, condition-based waiting
commit	Git workflows with Conventional Commits, PR generation, branch organization
python	Python development with uv, pytest, FastAPI, Django, async patterns
doc	Documentation generation, API docs, tutorials, Amazon-style memos
shell	Shell scripting with Google Shell Style Guide
debug	Distributed systems debugging and log correlation
meta	Plugin development: writing skills, testing skills, marketplace analysis
blackbox	Flight recorder hooks for telemetry and recovery

Note: The super plugin has been split into focused modules: core, workflow, review, testing, and debug. See MIGRATION.md for migration guide.

Installation

Prerequisites

# macOS - install system dependencies
brew install jq yq ripgrep fd coreutils

# Install uv (fast Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

Setup

1. Clone the repository:

git clone https://github.com/pedroproenca/dot-claude.git
cd dot-claude

2. Install Python dependencies:

uv sync

3. Validate plugins:

uv run python scripts/validate-plugins.py

4. (Optional) Install pre-commit hooks for development:

uv run pre-commit install

5. Sync configuration (from within Claude Code):

/sync-claude-config

Quick Start

Using Skills

Skills are invoked automatically when relevant, or manually via the Skill tool:

# TDD workflow
skill: core:tdd

# Python project setup
skill: python:uv-package-manager

# Documentation writing
skill: doc:amazon-writing

Using Commands

Slash commands expand to full prompts:

/workflow:plan       # Create implementation plan
/commit:new          # Create Conventional Commit
/python:refactor     # Refactor Python file
/doc:gen             # Generate documentation

Using Agents

Agents are specialized subagents invoked via Task tool:

# Code review
Task(subagent_type="review:code-reviewer", prompt="Review the authentication module")

# Python expertise
Task(subagent_type="python:python-expert", prompt="Optimize async database queries")

# Security analysis
Task(subagent_type="review:security-reviewer", prompt="Audit API endpoints for OWASP vulnerabilities")

Key Features

TDD Enforcement

The core plugin enforces test-driven development through multiple mechanisms:

1. TDD Guard Hook - Blocks production file edits unless test files are edited first
2. Verification Hook - Requires test/build evidence before completion claims
3. core:tdd Skill - Guides writing tests first, watching them fail, then implementing minimal code to pass

Conventional Commits

The commit plugin validates git commits:

• Subject line format and length limits
• Type prefixes: feat, fix, docs, refactor, test, chore
• Body explains WHY, not WHAT
• One logical change per commit

Workflow Automation

Hook	Plugin	Type	Behavior
TDD Guard	core	PreToolUse	Blocks production file edits unless test files edited first
Verification	core	Stop	Requires test/build evidence before completion claims
Worktree Guard	workflow	PreToolUse	Warns about git worktree awareness
Git Safety	commit	PreToolUse	Validates git commands before execution
Commit Validation	commit	PostToolUse	Enforces Conventional Commits format
Shell Validation	shell	PreToolUse	Checks shell syntax before file creation
Context Preservation	shell	PreCompact	Preserves important context during compaction
Flight Recorder	blackbox	PreToolUse	Captures file modifications for telemetry

Plugin Details

core (Essential Workflows)

Skills (3):