A living reference implementation of professional Claude Code commands and workflows

This is a working reference repository that demonstrates an opinionated set of practices for Claude Code development. The commands in .claude/commands/ are actively used in this repository's development, making it a living example of the patterns it teaches.

# Try the tools without installing anything
npx claude-setup                     # Initialize in current project
npx claude-setup learn add "insight" # Capture a learning
npx claude-setup tdd start           # Start TDD workflow
npx claude-setup docs                # Analyze documentation
npx claude-setup monitor status      # Check repo health

🎯 What NPX Setup Installs:

• Claude command templates (.claude/commands/) - 15+ battle-tested workflow commands
• AI agents (.claude/agents/) - Intelligent automation for complex tasks
• Configuration files (CLAUDE.md, AGENTS.md) - Project guidelines and agent documentation
• NPM scripts integration - Adds essential commands to your package.json (hygiene, todo, commit, etc.)
• Script utilities - Installs helper scripts for learn, tdd, docs, and monitoring features

Setup Options:

npx claude-setup                # Interactive setup (recommended)
npx claude-setup --skip         # Preserve all existing files
npx claude-setup --backup       # Backup existing files before replacing
npx claude-setup --force        # Replace all files without prompting
npx claude-setup --skip-scripts # Install commands only, don't modify package.json

Conflict Resolution: When existing files are detected, the interactive mode offers:

• Skip - Keep your customizations
• Backup - Save originals and install fresh
• Merge - Add only non-conflicting files
• Prefix - Add scripts with claude: prefix to avoid conflicts

# Install globally for frequent use
npm install -g claude-setup
claude-setup          # Initialize commands
claude-learn add "insight"
claude-tdd start
claude-docs
claude-monitor status

# Clone and use as your project base
git clone https://github.com/rmurphey/claude-setup.git my-project
cd my-project
# Commands are ready to use in .claude/commands/

✅ Living Reference: This repo uses its own commands - see our git history
✅ Token-Efficient: 87% reduction through npm script delegation (proven metrics)
✅ Best Practices: Based on Anthropic's guidelines and 2025 industry standards
✅ Production-Tested: Commands refined through real-world usage
✅ Self-Documenting: The repository demonstrates every pattern it teaches

This repository includes agents that can use the Claude API for advanced automation:

• Automated agent quality audits via GitHub Actions
• Intelligent code analysis beyond simple pattern matching
• Deep project insights using Claude's reasoning capabilities

👉 See API Setup Guide for configuration instructions

This repository demonstrates balanced approaches to Claude Code commands, optimizing for both learning and efficiency. We achieve 87% token reduction through strategic script delegation while maintaining flexibility where needed.

👉 See Token Efficiency Guide for detailed guidance on when to use different command approaches.

• /hygiene - Comprehensive project health check (view command)
• /todo - Task management with GitHub Issues (view command)
• /commit - Quality-checked commits (view command)
• /next - AI-recommended next steps (view command)

• /docs - Documentation generation (view command)
• /learn - Capture insights (view command)

• /push - Push with quality checks (view command)
• /tdd - Test-driven development workflow (view command)
• feature:check - Verify new features have tests & docs (documentation)

When commands aren't enough, agents provide intelligent analysis and complex automation.

• Commands: Routine tasks you do the same way every time (/hygiene, /commit)
• Agents: Complex analysis requiring "intelligence" and decision-making

• command-analyzer - Analyzes command usage patterns and suggests optimizations
• session-insights - Extracts patterns from development session history
• documentation-auditor - Audits documentation completeness and consistency
• repo-quality-auditor - Comprehensive repository audit for completeness and conflicts

• next-priorities - Analyzes project state to recommend next development priorities
• usage-estimator - Provides intelligent Claude usage estimates for development tasks

• test-coverage-advisor - Identifies untested code and recommends testing opportunities
• agent-auditor - Audits other agents for quality, correctness, and relevance

Use agents when you need:

• 🧠 Analysis: Analysis across multiple files with pattern recognition
• 📈 Insights: Deep understanding of your development practices
• 🔧 Optimization: Strategic improvements to your workflows
• 📋 Planning: Custom workflows for complex, multi-step processes
• 🤖 Self-Maintenance: Automated quality audits via GitHub Actions

# Use a command for routine tasks
/hygiene

# Use an agent for analysis
"Use the session-insights agent to analyze my development patterns from the last 3 months"

# Use an agent for optimization  
"Use the command-analyzer agent to find opportunities to streamline my command library"

📖 See AGENTS.md for the complete guide on when and why to use agents vs commands.

This repository uses Test-Driven Development (TDD) which helps Claude write focused, correct code. See TDD with Claude Guide for why it works so well with AI assistance.

Explore our git history to see these commands in action:

git log --grep="Generated with Claude Code" --oneline

Check our project health:

# In Claude Code
/hygiene

See our active work:

npm run todo:list  # Shows open GitHub issues

/hygiene                          # Check project health
/tdd start "new feature"          # Start with tests
/commit feat "add user auth"      # Quality-checked commit
/learn "TDD clarified the API"    # Capture insights

👉 See Complete Workflows Guide for detailed development patterns

All commands are customizable markdown files in .claude/commands/. Common customizations:

Edit /hygiene command to match your standards:

# In .claude/commands/hygiene.md
# Change from "max-warnings 10" to your preference
npx eslint . --max-warnings 0  # Strict: no warnings

Extend commands with your tools:

# In .claude/commands/commit.md
# Add your specific checks
npm run typecheck
npm run your-custom-check

Copy any template as a starting point:

cp .claude/commands/hygiene.md .claude/commands/deploy.md
# Edit to create deployment workflow

/todo, /next, /hygiene

/docs, /learn, /retrospective

/commit, /push, /tdd

Each command is a structured markdown file that guides Claude through specific workflows:

---
allowed-tools: [Bash, Read, Write]  # Tools Claude can use
description: Brief command description
---

# Command Name

Detailed instructions for Claude to execute...

When you type `/<command>` in Claude Code:
1. Claude reads the template from `.claude/commands/<command>.md`
2. Executes the workflow described in the template
3. Uses only the allowed tools specified
4. Provides consistent, professional assistance

.claude/
├── commands/           # Command templates (23+ files)
│   ├── hygiene.md     # Project health checks
│   ├── commit.md      # Quality-checked commits
│   ├── todo.md        # Task management
│   └── ...            # More production-ready commands
├── learnings/         # Monthly learning archives
├── agents/            # Claude Code agents
└── session-history/   # Development session archives

CLAUDE.md              # Project AI guidelines
GitHub Issues          # Task tracking (via /todo command)
package.json           # NPM scripts for token efficiency

docs/
├── BEST_PRACTICES.md  # Comprehensive best practices guide
├── COMMAND_CATALOG.md # Detailed command reference
├── TOKEN_EFFICIENCY.md # Token optimization strategies
└── QUICK_REFERENCE.md # Quick command lookup

Begin with core commands: /hygiene, /todo, /commit

Use /todo and /next to maintain focus

Run /hygiene before and after major changes

Use /learn to build project knowledge base

Adapt templates as you learn what works for your team

Run tests automatically as you code:

npm run test:watch    # Node.js watch mode - reruns on file changes

/hygiene && /todo list && /next
# Full status check → task list → recommendations

Create shortcuts for common workflows:

# In .claude/commands/status.md
# Combine hygiene + todo + next into one command

Use command patterns in your automation:

# In .github/workflows/ci.yml
# Implement same checks as /hygiene command

• Best Practices Guide - Claude Code best practices with citations
• Command Catalog - Detailed reference for all commands
• Token Efficiency - How we achieve 87% token reduction
• Quick Reference - Quick command lookup

• 💬 Issues: GitHub Issues
• 🤝 Discussions: GitHub Discussions
• 📧 Contact: Via GitHub profile

✅ 87% Token Reduction - Measured and documented savings
✅ Battle-Tested - Commands refined through real usage
✅ Living Documentation - See actual usage in git history
✅ Best Practices - Based on Anthropic guidelines and industry standards
✅ Self-Improving - Repository uses its own commands for development

• Anthropic's Claude Code Best Practices
• How Anthropic Teams Use Claude Code
• Conventional Commits v1.0.0
• Community patterns from Awesome Claude Code
• Real-world testing and metrics

This repository tracks its own usage metrics:

• Token usage per command
• Execution time statistics
• Error rates and recovery patterns
• Real workflow timings

See .claude/metrics.json for current data.

This repository uses Claude Code CLI to automatically audit agents via GitHub Actions.

Quick Setup: Add ANTHROPIC_API_KEY to GitHub Secrets → Actions

👉 Complete API Setup Guide - Detailed configuration, security, and troubleshooting

The audit runs weekly and validates agent quality using Claude's intelligence, not just pattern matching. See .claude/agents/agent-auditor.md for the audit logic.

This repository serves as a reference, so all contributions must:

• Include working examples
• Document token efficiency
• Provide citations for claims
• Pass our test suite
• Include tests as appropriate

• v2.0.0 - Complete restructure as living reference implementation
• v1.0.0 - Initial template collection

See git history for detailed change log.

MIT License - see LICENSE file for details.

A living reference implementation for the Claude Code community
This repository uses its own commands - explore our git history to see them in action

Explore how we use our own tools in practice. Each example demonstrates a key principle:

• feat: remove all detailed command variants for token efficiency — Less is more
• feat: remove 3 more complex maintenance commands — Ruthless simplification
• refactor: remove script tests in favor of utility testing — Focus testing effort

• feat: rewrite setup.js with intelligent conflict handling — Smart automation
• feat: add repo-quality-auditor agent for comprehensive quality analysis — Agent vs command pattern
• refactor: migrate to GitHub Issues for task management — Modern workflow

• fix: update docs script to count all commands recursively — Iterative refinement
• docs: add critical instruction to always use date command — Learning from mistakes