claude-pilot

claude-pilot ⭐

Claude Code workflow engine - SPEC-first planning, TDD automation, GPT delegation, and context engineering. From idea to production, discipline included.

Autonomous agents. TDD-driven. Documentation sync.

---

💡 Why claude-pilot?

Claude Code is powerful, but unstructured. claude-pilot adds discipline:

• ❌ Vague prompts → ✅ PRP pattern (What, Why, How, Success Criteria)
• ❌ Manual iteration → ✅ Ralph Loop (autonomous TDD until tests pass)
• ❌ Context bloat → ✅ 3-Tier docs (optimized token usage)
• ❌ Stuck on bugs → ✅ GPT delegation (fresh perspective after 2nd failure)
• ❌ Documentation drift → ✅ Auto-sync (docs stay in sync with code)

Result: Higher quality code, faster iteration, happier team.

Key Benefits:

• ✅ SPEC-First: Requirements before code
• 🤖 Autonomous: Ralph Loop runs until tests pass
• 🔄 Persistent: Plan state saved to .pilot/ directories
• 📚 Documented: Auto-sync 3-tier documentation
• 🧠 Intelligent: GPT Codex delegation for complex problems

---

Quick Start

# Add marketplace (use #release branch)
/plugin marketplace add changoo89/claude-pilot#release

# Install plugin
/plugin install claude-pilot

# Initial setup
/pilot:setup

⭐ Star this repo if it helps your workflow!

---

What is claude-pilot?

claude-pilot is a Claude Code plugin that brings structure and discipline to AI-assisted development.

Core Features

• SPEC-First TDD: Test-Driven Development with clear success criteria
• Ralph Loop: Autonomous iteration until all tests pass
• 3-Tier Documentation: Foundation/Component/Feature hierarchy for efficient context
• PRP Pattern: Structured prompts for unambiguous requirements
• Pre-commit Hook: JSON validation and markdown link check
• Pure Plugin: No Python dependency, native Claude Code integration

---

GPT Codex Integration

Intelligent GPT Delegation: Context-aware, autonomous delegation to GPT experts

Expert Mapping

Situation	GPT Expert
Architecture decisions	Architect
Security-related code	Security Analyst
Large plans (5+ SCs)	Plan Reviewer
2+ failed fix attempts	Architect
Coder blocked (automatic)	Architect

Delegation Triggers

• Explicit: "ask GPT", "review architecture"
• Semantic: Architecture decisions, security issues, ambiguity
• Automatic: After 2nd failure (not first) → Progressive escalation
• Self-Assessment: Agent confidence scoring < 0.5 → Delegation

Configuration

export CODEX_REASONING_EFFORT="medium"  # low | medium | high | xhigh

Full Guide: docs/ai-context/codex-integration.md

---

claude-pilot vs Vanilla Claude Code

Feature	claude-pilot	Vanilla Claude Code
SPEC-First Planning	✅ PRP format, success criteria	❌ Ad-hoc planning
TDD Automation	✅ Ralph Loop autonomous	❌ Manual test-run cycle
Session Persistence	✅ Plan file persistence	❌ Context lost on exit
Documentation Sync	✅ 3-tier auto-update	❌ Manual docs only
Quality Gates	✅ Type check, lint, coverage	❌ No enforcement
GPT Delegation	✅ Intelligent escalation	❌ Manual delegation
Multi-Angle Review	✅ Parallel verification	❌ Single perspective

---

Core Workflow

/00_plan     → Create spec-driven plan with PRP format
/01_confirm  → Review and approve plan
/02_execute  → Execute with Ralph Loop + TDD
/03_close    → Complete and commit
/review   → Auto-review code (multi-angle)
/document → Auto-document changes
/pilot:setup → Configure MCP servers

---

Project Structure