Claude Code Custom Commands

Version: 2.1.0 | Expert Panel Reviewed Constitutional Hash: cdd01ef066bc6cf2

This directory contains custom slash commands for the ACGS-2 project.

Available Commands

Development Workflow

| Command | Purpose | Usage | |---------|---------|-------| | /architect | Structured development workflow with state machine | /architect [0-5] | | /scope | Quick discovery & planning | /scope [task] | | /tdd | Test-Driven Development workflow | /tdd [feature] | | /verify | 6-step quality gate (build, types, lint, tests, debug, git) | /verify [--quick\|--pre-pr] | | /build-fix | Diagnose and fix build errors | /build-fix [--python\|--typescript] | | /test-coverage | Check and improve test coverage | /test-coverage [--improve] |

Code Quality

| Command | Purpose | Usage | |---------|---------|-------| | /review | Security & performance audit with severity matrix | /review [path] [--depth] | | /debug | Expert debugging with 2-attempt protocol | /debug [error] | | /security-gate | Security review before code merge | /security-gate [feature] | | /analyze | Comprehensive code analysis | /analyze [target] [--focus] |

Planning & Coordination

| Command | Purpose | Usage | |---------|---------|-------| | /prd-review | Product requirements document review | /prd-review [path] | | /debate | Multi-perspective analysis and decision making | /debate [topic] | | /swarm-init | Initialize swarm coordination topology | /swarm-init [--topology] | | /task-orchestrate | Orchestrate complex tasks across swarm | /task-orchestrate [task] | | /init | Initialize coordination framework | /init [--topology] | | /pm | Project manager agent orchestration | /pm [request] [--strategy] |

v2.1 Key Improvements

Explicit State Machine: IDLE → DISCOVERY → PLANNING → IMPLEMENTING → COMPLETE
Definition of Done: Measurable exit criteria for each phase
Error Handling: Invalid input responses, recovery commands
2-Attempt Rule: Clear definition of what counts as an attempt
Integration Matrix: Command handoffs documented

v2.2 Additions (everything-claude-code Integration)

TDD Workflow: /tdd command with Red-Green-Refactor cycle
Verification Pipeline: /verify with 6-step quality gate
Build Automation: /build-fix for automatic error resolution
Coverage Tracking: /test-coverage for 80%+ enforcement
Rules System: Always-on guidelines (security, testing, style, git, performance)
Enhanced Hooks: Auto-formatting, type checking, console.log detection
New Agents: tdd-guide, code-reviewer with proactive usage

Architect Protocol State Machine

IDLE → DISCOVERY → EXPLORATION → PLANNING → APPROVED → IMPLEMENTING → VERIFYING → COMPLETE
                                                            ↓ (2 failures)
                                                         BLOCKED

Phases

| Phase | Purpose | Exit Criteria | |-------|---------|---------------| | 0 | Discovery & Scoping | Goal restated, files identified, risk assigned | | 1 | Exploration | Code paths traced, build verified, tests found | | 2 | Strategic Planning | 2+ options presented, user selected | | 3 | Implementation Roadmap | Atomic steps with verification commands | | 4 | Execution & Test-Loop | Each step verified, TodoWrite updated | | 5 | Hardening & Memory | Full test suite passed, CLAUDE.md updated |

Recovery Commands

/architect resume    # Resume from TodoWrite state
/architect status    # Show current state and progress
/architect reset     # Clear state, start fresh

Quick Start

# Start a new feature
/scope Add user authentication to the API

# Execute phase by phase
/architect 0    # Discovery
/architect 2    # Get strategic options
# [select option]
/architect 3    # Create implementation plan
/architect 4    # Execute with tests
/architect 5    # Finalize

# Review code
/review src/core/enhanced_agent_bus/ --depth comprehensive

# Debug a test failure
/debug python -m pytest tests/test_api.py -v

# Security gate check before merge
/security-gate user authentication feature

# Review product requirements
/prd-review docs/prd/auth-requirements.md

# Multi-perspective decision analysis
/debate "Should we use JWT or session-based auth?"

# Initialize swarm coordination
/swarm-init --topology hierarchical --max-agents 8

# Analyze codebase quality
/analyze --focus security --depth deep

# Project management orchestration
/pm "Implement payment processing system"

Review Depth Levels

| Level | Description | When to Use | |-------|-------------|-------------| | quick | Surface-level scan | Pre-commit checks | | standard | Balanced analysis | PR reviews | | comprehensive | Deep audit | Security-critical changes |

Debug 2-Attempt Rule

| Scenario | Attempt Count | Reasoning | |----------|---------------|-----------| | Fix typo, still fails, fix import | 1 | Same investigation | | Try approach A, fails, try approach B | 2 | Distinct strategies | | Misdiagnose, correct diagnosis, fix | 1 | Same debugging session |

After 2 failed attempts → BLOCKED state → Suggest /debug with context

Integration with Task Agents

| Command | Agents Used | |---------|-------------| | /architect | architect-review, code-reviewer | | /review | code-reviewer, security-auditor | | /debug | debugger, error-detective | | /scope | Explore agent | | /security-gate | security-engineer, constitutional-validator | | /prd-review | requirements-analyst, pm-agent | | /debate | visionary, skeptic, pm-agent | | /swarm-init | coordination-manager | | /task-orchestrate | task-coordinator, pm-agent | | /init | coordination-manager | | /analyze | code-analyzer, quality-assurance | | /pm | pm-agent, all sub-agents |

Constitutional Compliance

All commands respect the constitutional hash: cdd01ef066bc6cf2

The architect protocol ensures:

Changes are verified against constitutional principles
MACI role separation is maintained
Audit trails are properly generated

File Structure

.claude/commands/
├── architect.md          # v2.1 (455 lines)
├── debug.md              # v2.1 (400 lines)
├── review.md             # v2.1 (328 lines)
├── scope.md              # v2.1 (397 lines)
├── security-gate.md      # v2.1 (91 lines)
├── prd-review.md         # v2.1 (87 lines)
├── debate.md             # v2.1 (55 lines)
├── swarm-init.md         # v2.1 (86 lines)
├── task-orchestrate.md   # v2.1 (26 lines)
├── init.md               # v2.1 (45 lines)
├── analyze.md            # v2.1 (90 lines)
├── pm.md                 # v2.1 (593 lines)
├── README.md             # This file
└── SPEC_COMPARISON_v1_vs_v2.1.md  # Comparison document

Setup

To install the global dev-claude command:

./scripts/setup-dev-claude.sh
source ~/.zshrc  # or ~/.bashrc

Then use from any directory:

dev-claude                 # Start architect mode
dev-claude "new feature"   # Start with task
dev-claude --review        # Review mode
dev-claude --debug         # Debug mode

/README Command