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.
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
# 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!
claude-pilot is a Claude Code plugin that brings structure and discipline to AI-assisted development.
- 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
Intelligent GPT Delegation: Context-aware, autonomous delegation to GPT experts
| 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 |
- 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
export CODEX_REASONING_EFFORT="medium" # low | medium | high | xhighFull Guide: docs/ai-context/codex-integration.md
| 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 |
/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
claude-pilot/
├── README.md
├── CHANGELOG.md # Version history
├── CLAUDE.md # Main project guide
├── .claude-plugin/ # Plugin manifests
│ ├── marketplace.json # Marketplace configuration
│ └── plugin.json # Plugin metadata
├── .claude/ # Plugin components
│ ├── agents/ # Agent configurations (8 agents)
│ ├── commands/ # Slash commands (11)
│ ├── skills/ # TDD, Ralph Loop, Vibe Coding
│ ├── guides/ # Methodology guides
│ ├── templates/ # CONTEXT.md, SKILL.md templates
│ ├── scripts/hooks/ # Pre-commit hook
│ └── settings.json # Example settings
├── .pilot/ # Plan management
│ └── plan/
│ ├── pending/ # Plans awaiting confirmation
│ ├── in_progress/ # Active plans
│ └── done/ # Completed plans
└── docs/ # Documentation
├── archive/ # Archived content (MIGRATION.md)
└── ai-context/ # 3-Tier integration docs
- Claude Code v1.0+ with plugin support
# Step 1: Add marketplace
/plugin marketplace add changoo89/claude-pilot
# Step 2: Install plugin
/plugin install claude-pilot
# Step 3: Run setup
/pilot:setup- Plugin files are copied to
.claude/directory - You'll be prompted to run
/pilot:setup - Setup automatically:
- Configures recommended MCP servers
- Creates
.pilot/directories for plan management - Sets hooks executable permissions
- Detects project type and configures LSP
- 11 Slash Commands: Plan, Confirm, Execute, Close, Review, Document, Init, Setup, Release, Cleanup, Continue
- 12 Agents: Coder, Tester, Validator, Documenter, Explorer, Researcher, Plan Reviewer, Code Reviewer, Frontend Engineer, Backend Engineer, Security Analyst, Build Error Resolver
- 30 Skills: TDD, Ralph Loop, Vibe Coding, Git Master, and 26 more
- MCP Servers: context7, sequential-thinking (configured via
/pilot:setup) - Hooks: Pre-commit hook for JSON validation and markdown link check
Run /pilot:setup to configure recommended MCPs:
| MCP | Purpose |
|---|---|
| context7 | Latest library documentation |
| sequential-thinking | Step-by-step reasoning for complex problems |
The setup command uses a merge strategy:
- Preserves existing
.mcp.jsonconfigurations - Adds only new servers
- Skips servers with conflicting names
# In Claude Code
/setup
# Automatically generates 3-Tier documentation structure# In Claude Code
/00_plan "Add user authentication with JWT"
# Review the generated plan in .pilot/plan/pending/
# Edit if needed, then:
/01_confirm # Approve the plan
/02_execute # Execute with TDD + Ralph Loop# After completing work
/document
# Automatically updates:
# - CLAUDE.md (Tier 1)
# - docs/ai-context/ files
# - Tier 2/3 CONTEXT.md files# Before committing
/review security performance accessibility
# Reviews code from multiple perspectives- Getting Started
- Claude-Code-Development-Kit - 3-Tier Documentation System
Contributions welcome! Please:
- Fork the repository
- Create a feature branch (
/00_plan "your feature") - Follow TDD workflow (
/02_execute) - Submit PR with
/reviewoutput
MIT License - Free to use, modify, and distribute.
A: Yes, MIT license allows commercial use.
A: Edit .claude/settings.json and remove unwanted hooks from the hooks section.
A: Yes, run /pilot:setup to add recommended MCPs, or manually edit .mcp.json.
A: Ralph Loop can be configured to skip tests. Edit /02_execute command to adjust.
A: No! The plugin is pure markdown/JSON - no Python required.
- Issues: GitHub Issues
- Discussions: GitHub Discussions
claude-pilot synthesizes best practices from these projects:
-
- Superpowers-style command architecture (skill invocation pattern)
- RED-GREEN-REFACTOR TDD enforcement
- Git worktrees for parallel development
-
- 3-Tier Documentation System (Foundation/Component/Feature)
- Hierarchical CONTEXT.md structure
- AI-context documentation patterns
-
- SPEC-First TDD methodology
- Multilingual support architecture
-
- Ralph Loop autonomous iteration
- Todo continuation enforcement
-
- Pure plugin architecture
- GitHub star prompting
- MCP server configuration
-
- Claude Code hooks system (PreToolUse, PostToolUse, Stop)
- Coding standards skill (TypeScript, React, API, testing)
- Battle-tested configurations from hackathon winner
- Claude Code Best Practices
- Official Anthropic guidelines
- Claude Code Plugins Reference
- Plugin development guide
Built with inspiration from the Claude Code community.