A blueprint repository for setting up and running projects with Claude Code. Contains the RPI (Research-Plan-Implement) methodology, a catalog of known agent errors, and operational rules learned from hundreds of real sessions.
- Claude Code CLI installed and configured
- Git
Clone the repository:
git clone https://github.com/juan294/cc-rpi.gitThen tell Claude Code in your target project:
Go read the cc-rpi repository and set up this project following all the best practices. Read the quick reference, error catalog, and methodology, then configure CLAUDE.md and slash commands for this project.
New here? Read GUIDE.md — a human-readable walkthrough of the philosophy, the workflow, and every command. It covers everything you need to know without diving into every file. Also works great as source material for NotebookLM podcasts or articles.
The full Research-Plan-Implement pattern adapted for Claude Code, based on HumanLayer's opencode-rpi and ACE-FCA framework. Organized by topic (10 files, in reading order):
- Philosophy — Core tenets, error amplification principle, mental alignment
- Context Engineering — The foundational discipline: compaction, context quality, settings & permissions
- Four Phases — Research, Plan, Implement, Validate with detailed processes
- Agent Design — Documentarian rule, tool restrictions, subagent catalog, Anthropic-native commands (
/simplify,/batch), agent teams, autonomy principles - Pseudocode Notation — Compact notation for writing implementation plans
- Testing — Automated-first verification hierarchy, TDD protocol
- Push Accountability — Post-push CI ownership, background polling, fix-and-repush cycle
- CI & Guardrails — Pre-commit hooks, CI workflows, development guardrails, enforcement stack
- Scheduled Agents — Recurring quality agents on cron/launchd, shared context system
- Error & Success Logging — Framework for systematic improvement
A catalog of recurring Claude Code agent errors documented from real sessions. Each entry includes the symptom, root cause, correct approach, and what to avoid:
- Shell behavior (parallel calls, cwd resets, tilde paths)
- Git operations (worktrees, pre-commit hooks, push rejections)
- GitHub CLI (
ghfield names, CI status checking) - Node.js/TypeScript (ESM shebangs, Buffer vs string)
- CI & workflow (push-and-forget, skipping TDD, suggesting manual steps)
Sample documents illustrating the methodology in practice — a research document, implementation plan with phase files, error/success log entries, and additional pseudocode notation examples. Use these as reference when producing your own RPI artifacts.
Ready-to-use starting points for new projects:
- CLAUDE.md template — Comprehensive project configuration with all operational rules baked in
- settings.json template —
.claude/settings.jsonwith Agent Teams, hooks, and permissions - Setup checklist — Step-by-step guide including pre-commit hooks, CI setup, push accountability, and scheduled agents
- Slash commands —
/bootstrap,/adopt,/update,/research,/plan,/implement,/validate,/describe-pr,/pre-launch,/remediate,/triage,/status,/fix-ci— plus integration with Anthropic-native/simplifyand/batch - Scheduled agent scripts — Nightly blueprint sync (
cc-rpi-update-agent.sh) and multi-project morning triage (morning-triage.sh), both with retry logic and launchd/cron templates
When you discover a new recurring error or best practice:
- Add it to
patterns/agent-errors.md(detailed entry with symptom/root cause/solution) - Add a one-liner to
patterns/quick-reference.md - Keep entries generic — no project-specific references
See CONTRIBUTING.md for full guidelines.
- GitHub Discussions — Ask questions, share ideas, discuss the methodology
- Contributing Guide — How to report patterns, propose improvements, submit PRs
- Code of Conduct — Expected behavior for all participants
- HumanLayer — ACE-FCA framework and opencode-rpi implementation
- Adapted for Claude Code's native capabilities (CLAUDE.md, Task tool, slash commands)
See CHANGELOG.md for release history.
