anvil-dev-framework 0.1.6

package/docs/boris-cherny-ralph-wiggum-insights.md

@@ -0,0 +1,608 @@
+# Boris Cherny & Ralph Wiggum: Claude Code Best Practices Research
+
+> Comprehensive analysis of Boris Cherny's (Claude Code creator) workflow and Geoffrey Huntley's Ralph Wiggum technique for integration into the Anvil framework.
+
+**Research Date**: 2026-01-04
+**Sources**:
+- [Boris Cherny's Twitter Thread](https://twitter-thread.com/t/2007179832300581177)
+- [DEV Community Breakdown](https://dev.to/sivarampg/how-the-creator-of-claude-code-uses-claude-code-a-complete-breakdown-4f07)
+- [Anthropic: Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices)
+- [nibzard: Boris Cherny's Guide](https://www.nibzard.com/claude-code/)
+- [Geoffrey Huntley: Ralph Wiggum as a Software Engineer](https://ghuntley.com/ralph-wiggum/)
+- [Ralph Wiggum Plugin](https://github.com/anthropics/claude-code/tree/main/plugins/ralph-wiggum)
+
+---
+
+## Table of Contents
+
+- [Part 1: Boris Cherny's Claude Code Setup](#part-1-boris-chernys-claude-code-setup)
+- [Part 2: Ralph Wiggum Technique](#part-2-ralph-wiggum-technique)
+- [Part 3: Gap Analysis - Anvil vs Best Practices](#part-3-gap-analysis---anvil-vs-best-practices)
+- [Part 4: Implementation Recommendations](#part-4-implementation-recommendations)
+
+---
+
+## Part 1: Boris Cherny's Claude Code Setup
+
+Boris Cherny created Claude Code as a side project in September 2024. His setup is "surprisingly vanilla" - he says Claude Code works great out of the box.
+
+### Core Principles
+
+| Principle | Details |
+|-----------|---------|
+| **Verification is #1** | "Give Claude a way to verify its work. It will 2-3x the quality of the final result" |
+| **Opus over Sonnet** | Fewer iterations with stronger model beats rapid weak iterations |
+| **Plan Mode First** | "Invest time upfront in planning, and save way more time in execution" |
+| **Inner Loop Commands** | Every repeated workflow becomes a slash command |
+
+### Parallel Session Architecture
+
+Boris runs **15+ concurrent Claude sessions**:
+- 5 terminal instances with numbered tabs and system notifications
+- 5-10 web sessions on claude.ai/code
+- iOS app sessions started from phone, monitored on desktop
+- Cross-platform handoff using `&` (background to web) and `--teleport <session-id>`
+
+### Model Selection
+
+> "Sonnet (fast) → 5 iterations → Total time: 5 minutes
+> Opus (slow) → 1 iteration → Total time: 2 minutes"
+
+**Rationale**: Fewer iterations with stronger model beats rapid weak iterations. Opus provides better autonomous tool selection without constant steering.
+
+### Results
+
+In thirty days, Boris landed **259 PRs** — 497 commits, 40k lines added, 38k lines removed. Every single line was written by Claude Code + Opus 4.5.
+
+### CLAUDE.md Structure
+
+Boris maintains a team-shared CLAUDE.md file:
+- **Checked into git**
+- **Updated multiple times weekly** by team members
+- When Claude makes errors, team adds entries so "Claude knows not to do it next time"
+- Captures tribal knowledge not in official docs
+
+**File Hierarchy**:
+```
+/<enterprise root>/CLAUDE.md    → Organizational policies
+~/.claude/CLAUDE.md             → User-global context
+<project>/CLAUDE.md             → Project-specific (checked into git)
+<project>/CLAUDE.local.md       → Local overrides (not in git)
+```
+
+**Best Practice**: Keep to 100-200 lines maximum. If larger, move details into per-folder CLAUDE.md files.
+
+### Automated Knowledge Extraction
+
+Boris's team has a GitHub Action triggered by `@.claude` PR comments that:
+1. Analyzes pull requests
+2. Extracts patterns, anti-patterns, conventions
+3. Auto-commits CLAUDE.md updates
+4. Implements "compounding engineering" where knowledge accumulates
+
+### Slash Commands
+
+Pre-configured workflows stored in `.claude/commands/`:
+
+**`/commit-push-pr`**:
+- Inline bash executes `git status`, `git branch`, `git log -5`
+- Stages and commits with conventional format
+- Creates PR with detailed description
+- Requests appropriate reviews
+
+**`/test-and-commit`**:
+- Runs `npm test`, `npm run typecheck`, `npm run lint`
+- Only commits if all checks pass
+- Reports failures without committing
+
+### Subagents
+
+Domain-specific AI personalities with:
+- Separate context windows (isolated from main)
+- Custom system prompts
+- Limited tool access
+
+**Examples**:
+- `code-simplifier` - Reduces complexity, extracts repeated logic
+- `verify-app` - Automated verification post-completion
+
+### Hooks
+
+**PostToolUse Hook for Formatting**:
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+"Last 10% to avoid formatting errors" - catches issues before CI.
+
+### Stop Hook for Verification Gate
+
+```bash
+#!/bin/bash
+npm test
+if [ $? -eq 0 ]; then
+  echo "✓ All tests passing"
+  exit 0
+else
+  echo "✗ Tests failing - continue working"
+  exit 1  # Block exit, force continuation
+fi
+```
+
+Non-zero exit blocks Claude from stopping, forcing iteration until tests pass.
+
+### Verification Methods
+
+Boris emphasizes verification as "probably the most important thing":
+
+| Type | Implementation |
+|------|----------------|
+| **Command-line** | `npm test`, `npm run typecheck`, `npm run lint` |
+| **Test Suite** | Unit, integration, e2e tests with >80% coverage |
+| **Browser** | Chrome Extension opens localhost, tests forms, validates UX |
+| **API** | curl tests for creation, validation, auth flows |
+| **Pre-commit** | Hooks run lint, typecheck, test before each commit |
+
+### Workflow Patterns
+
+**Explore, Plan, Code, Commit**:
+1. Request Claude read relevant files without writing code initially
+2. Ask Claude to create a detailed plan using thinking mode
+3. Have Claude implement solutions while verifying reasonableness
+4. Request commits and documentation updates
+
+> "Steps #1-#2 are crucial—without them, Claude tends to jump straight to coding."
+
+**Test-Driven Development (TDD)**:
+1. Request test cases based on input/output pairs
+2. Confirm tests fail initially
+3. Commit tests before implementation
+4. Have Claude code to pass tests with multiple iterations
+5. Verify implementation doesn't overfit
+6. Commit final code
+
+**Visual Iteration**:
+1. Provide browser screenshots via Puppeteer MCP or drag-and-drop
+2. Supply design mocks as reference points
+3. Request Claude iterate 2-3 times for refinement
+4. Commit when satisfied
+
+### Permission Management
+
+Instead of `--dangerously-skip-permissions`, use `/permissions` to pre-allow safe commands:
+- git operations (status, diff, commit, push)
+- npm scripts (test, build, lint)
+- File operations (cat, ls, grep)
+
+Stored in `.claude/settings.json` for team access.
+
+---
+
+## Part 2: Ralph Wiggum Technique
+
+Geoffrey Huntley's Ralph Wiggum is a technique for long-running, unattended Claude Code execution. Named after the Simpsons character, it embodies persistent iteration despite setbacks.
+
+### Core Philosophy
+
+> "The technique is deterministically bad in an undeterministic world."
+
+Ralph is designed to handle the non-determinism of LLMs through iteration. It requires:
+- Faith in eventual consistency
+- Belief that most issues can be resolved through more loops
+- Patience - "Ralph will test you"
+
+### The Basic Loop
+
+In its purest form, Ralph is a Bash loop:
+
+```bash
+while :; do cat PROMPT.md | npx --yes @sourcegraph/amp ; done
+```
+
+Ralph can be done with any tool that doesn't cap tool calls and usage.
+
+### Key Insight: One Item Per Loop
+
+> "To get good outcomes with Ralph, you need to ask Ralph to do one thing per loop. **Only one thing.**"
+
+You may relax this as the project progresses, but if Ralph goes off the rails, narrow it back to just one item.
+
+### Context Window Management
+
+> "The name of the game is that you only have approximately 170k of context window to work with. So it's essential to use as little of it as possible. The more you use the context window, the worse the outcomes you'll get."
+
+**Solution**: Don't allocate to primary context window. Spawn subagents instead.
+
+- Primary context window = **scheduler**
+- Subagents = **workers** doing expensive operations
+- Use up to **500 parallel subagents** for file searching/research
+- Use only **1 subagent** for build/tests (avoid backpressure)
+
+### The Three Phases
+
+#### Phase 1: Requirements
+
+- Have a long conversation about requirements
+- Don't ask the agent to implement - just discuss what you're about to implement
+- Once agent understands the task, write specifications out
+- One file per topic in the specifications folder
+
+#### Phase 2: TODO (Planning)
+
+- Study specs to learn about requirements
+- Manually allocate context window with discussion about the activity
+- Goal: shape the context window, not do implementation
+- Target the job-to-be-done with up to 100 subagents
+- Write out an `IMPLEMENTATION_PLAN.md`
+
+#### Phase 3: Implementation (Incremental Loop)
+
+- Study specs and IMPLEMENTATION_PLAN.md
+- Pick most important item to address
+- Update implementation plan once tests pass
+- Use as many subagents as needed for research
+- Only use **one subagent** when doing tests/builds
+- Commit on success
+
+### Key Files
+
+| File | Purpose |
+|------|---------|
+| `PROMPT.md` | Main prompt fed each loop |
+| `AGENT.md` | How Ralph should compile/run (self-improvement allowed) |
+| `fix_plan.md` | Living TODO list sorted by priority |
+| `specs/` | Specifications folder (one file per topic) |
+
+### Deterministic Stack Allocation
+
+> "Deterministically allocate the stack the same way every loop."
+
+Every loop should:
+1. Study specs/* to learn about specifications
+2. The source code is in src/
+3. Study fix_plan.md
+4. Then do the task
+
+This ensures consistent context regardless of iteration number.
+
+### Backpressure
+
+Backpressure = mechanisms that reject invalid code:
+- Type systems
+- Test suites
+- Linters
+- Security scanners
+- Static analyzers
+
+> "After implementing functionality or resolving problems, run the tests for that unit of code that was improved."
+
+For dynamically typed languages, strongly recommend wiring in static analyzers (e.g., Pyrefly for Python).
+
+### No Cheating (Anti-Placeholder Pattern)
+
+Claude has inherent bias toward minimal/placeholder implementations. Counter this:
+
+> "DO NOT IMPLEMENT PLACEHOLDER OR SIMPLE IMPLEMENTATIONS. WE WANT FULL IMPLEMENTATIONS. **DO IT OR I WILL YELL AT YOU**"
+
+If Ralph ignores this, you can always run more Ralphs to identify placeholders and transform them into a todo list.
+
+### Don't Assume It's Not Implemented
+
+> "Before making changes search codebase (don't assume not implemented) using subagents. Think hard."
+
+A common failure is when the LLM runs ripgrep and incorrectly concludes code hasn't been implemented. Erect a sign for Ralph: don't make assumptions.
+
+### Self-Learning
+
+> "When you learn something new about how to run the compiler or examples make sure you update @AGENT.md using a subagent but keep it brief."
+
+Allow Ralph to take himself to "university" - permit self-improvement of the AGENT.md file.
+
+### Commit on Success
+
+> "When the tests pass update the fix_plan.md, then add changed code and @fix_plan.md with 'git add -A' via bash then do a 'git commit' with a message that describes the changes. After the commit do a 'git push'."
+
+> "As soon as there are no build or test errors create a git tag. Start at 0.0.0 and increment patch by 1."
+
+### Loop Back is Everything
+
+> "You want to program in ways where Ralph can loop himself back into the LLM for evaluation. This is incredibly important."
+
+Examples:
+- Add additional logging
+- Compile the application and look at LLVM IR representation
+- Run the app and check output
+
+### The TODO List
+
+```
+study specs/* to learn about the compiler specifications and fix_plan.md to understand plan so far.
+
+The source code of the compiler is in src/*
+
+First task is to study @fix_plan.md (it may be incorrect) and is to use up to 500 subagents to study existing source code in src/ and compare it against the compiler specifications. From that create/update a @fix_plan.md which is a bullet point list sorted in priority of the items which have yet to be implemented.
+
+Consider searching for TODO, minimal implementations and placeholders. Study @fix_plan.md to determine starting point for research and keep it up to date with items considered complete/incomplete.
+```
+
+### Results
+
+- **Y Combinator hackathon**: Generated 6 repositories overnight
+- **Real contract**: $50k USD contract delivered, tested, reviewed for **$297** in API costs
+- **CURSED**: Built an entire programming language over 3 months using this technique
+
+### Three States of Ralph
+
+> "Ralph has three states. Under baked, baked, or baked with unspecified latent behaviours (which are sometimes quite nice!)"
+
+### When to Use Ralph
+
+**Good for**:
+- Greenfield projects
+- Well-defined tasks with clear success criteria
+- Tasks requiring iteration (getting tests to pass)
+- Tasks with automatic verification
+
+**Not good for**:
+- Existing codebases (Ralph works best for bootstrapping)
+- Tasks requiring human judgment
+- One-shot operations
+- Tasks with unclear success criteria
+
+---
+
+## Part 3: Gap Analysis - Anvil vs Best Practices
+
+### Verification Loops
+
+| Aspect | Boris's Approach | Anvil Current | Gap |
+|--------|------------------|---------------|-----|
+| Feedback loop | Chrome extension, test suites, API tests | `/validate`, `/evidence` capture | No **iteration on failure** |
+| Stop hook gate | Blocks exit until tests pass | No stop hook verification | **Missing** |
+| Retry mechanism | Ralph Wiggum pattern | None | **Missing** |
+
+### CLAUDE.md & Knowledge
+
+| Aspect | Boris's Approach | Anvil Current | Gap |
+|--------|------------------|---------------|-----|
+| Shared CLAUDE.md | Team-updated, git-tracked | Project `.claude/CLAUDE.md` | **Aligned** |
+| Auto-extraction | GitHub Action on PRs | `/insights` generates patches | **Manual application** |
+| Pattern capture | PR-triggered | Session-based via `/retro` | Different trigger |
+
+### Slash Commands
+
+| Aspect | Boris's Approach | Anvil Current | Gap |
+|--------|------------------|---------------|-----|
+| Workflow commands | `/commit-push-pr`, `/test-and-commit` | 23 workflow commands | Missing **atomic actions** |
+| Inner loops | Codified for daily tasks | Comprehensive but workflow-oriented | Could add action commands |
+
+### Subagents
+
+| Aspect | Boris's Approach | Anvil Current | Gap |
+|--------|------------------|---------------|-----|
+| code-simplifier | Reduces complexity | None | **Missing** |
+| verify-app | Post-completion verification | None | **Missing** |
+| Parallel research | Up to 500 subagents | Task tool with various agents | Could add Ralph-style limits |
+
+### Hooks
+
+| Aspect | Boris's Approach | Anvil Current | Gap |
+|--------|------------------|---------------|-----|
+| PostToolUse formatting | prettier/eslint on Edit/Write | None | **Missing** |
+| Stop verification | Tests must pass to exit | None | **Missing** |
+| Session tracking | StatusLine | StatusLine hook | **Aligned** |
+
+### Ralph Wiggum Integration
+
+| Aspect | Ralph Technique | Anvil Current | Gap |
+|--------|-----------------|---------------|-----|
+| Loop mechanism | Stop hook re-feeds prompt | No loop mechanism | **Missing** |
+| One item per loop | Single task focus | Multi-task capable | Philosophy difference |
+| fix_plan.md | Living TODO list | TodoWrite tool | Different format |
+| AGENT.md | Self-improvement allowed | CLAUDE.md static | Could enable |
+| Completion promise | `<promise>COMPLETE</promise>` | None | **Missing** |
+
+---
+
+## Part 4: Implementation Recommendations
+
+### Priority 1: Verification Feedback Loop (HIGH IMPACT)
+
+**Why**: Boris says this is "probably the most important thing" that "2-3x the quality."
+
+**Implementation**:
+
+1. **New `/verify` Command**
+   ```markdown
+   # /verify - Verification Feedback Loop
+
+   1. Run test suite, lint, typecheck
+   2. If failures:
+      - Parse error output structured: file, line, error type, message
+      - Return to Claude: "Fix these issues and run /verify again"
+      - Track iteration count
+   3. If passing:
+      - Output: "✅ Verification passed"
+      - Save evidence to .claude/evidence/
+
+   Options:
+   --loop       # Keep iterating until pass (max 10)
+   --strict     # Block session end until pass
+   ```
+
+2. **Stop Hook Verification Gate**
+   ```bash
+   # global/hooks/stop_verification.sh
+   if [ "$ANVIL_VERIFY_ON_STOP" = "true" ]; then
+     npm test && npm run lint && npm run typecheck
+     if [ $? -ne 0 ]; then
+       echo "⚠️ VERIFICATION FAILED - Fix issues before ending"
+       exit 1
+     fi
+   fi
+   ```
+
+### Priority 2: PostToolUse Formatting Hook
+
+**Why**: Catches "last 10%" of formatting issues before CI.
+
+**Implementation**:
+```json
+{
+  "hooks": {
+    "PostToolUse": [{
+      "matcher": {"tool_name": "Edit|Write"},
+      "hooks": [{
+        "type": "command",
+        "command": "prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null; eslint --fix \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
+      }]
+    }]
+  }
+}
+```
+
+### Priority 3: Ralph Wiggum Mode
+
+**Why**: Enables hands-off, long-running execution for well-defined tasks.
+
+**Implementation**:
+
+1. **New `/ralph` Command (or Plugin)**
+   ```markdown
+   # /ralph - Start Ralph Wiggum Loop
+
+   /ralph "<prompt>" --max-iterations 50 --completion-promise "COMPLETE"
+
+   Behavior:
+   1. Sets up stop hook to intercept exit
+   2. Re-feeds prompt until completion promise or max iterations
+   3. Tracks iteration count
+   4. On completion: reports summary
+   ```
+
+2. **Ralph-Compatible File Structure**
+   ```
+   .claude/
+   ├── ralph/
+   │   ├── PROMPT.md         # Current task prompt
+   │   ├── AGENT.md          # Self-improvement file
+   │   └── fix_plan.md       # Living TODO list
+   ```
+
+3. **Stop Hook for Ralph**
+   ```bash
+   # Check for completion promise in last output
+   if grep -q "<promise>COMPLETE</promise>" /tmp/claude_last_output; then
+     exit 0  # Allow exit
+   fi
+
+   if [ $RALPH_ITERATIONS -lt $RALPH_MAX_ITERATIONS ]; then
+     # Re-feed prompt
+     cat .claude/ralph/PROMPT.md
+     exit 1  # Block exit, continue loop
+   fi
+   ```
+
+### Priority 4: Atomic Action Commands
+
+**Why**: Boris has these for daily inner loops.
+
+**Implementation**:
+- `/commit-push-pr` - Stage, commit, push, create PR
+- `/test-and-commit` - Run tests, only commit if passing
+- `/format` - Run formatters on changed files
+
+### Priority 5: Verification Subagent
+
+**Why**: Boris uses `verify-app` for post-completion checks.
+
+**Implementation**:
+```yaml
+# .claude/agents/verify-app.yaml
+name: verify-app
+description: Post-implementation verification agent
+tools: [Bash, Read, Grep, Glob]
+system_prompt: |
+  You are a verification specialist. Your job is to:
+  1. Run the test suite and report results
+  2. Run lint and typecheck
+  3. Verify no regressions
+  4. Report pass/fail with specific errors
+
+  You do NOT fix issues - you only verify and report.
+```
+
+### Priority 6: Automated CLAUDE.md Updates
+
+**Why**: Boris's team has GitHub Action for this.
+
+**Implementation**:
+```yaml
+# .github/workflows/claude-knowledge.yml
+name: Extract Claude Knowledge
+on:
+  pull_request:
+    types: [closed]
+
+jobs:
+  extract:
+    if: github.event.pull_request.merged == true
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Extract patterns
+        run: |
+          # Analyze PR diff for patterns
+          # Update CLAUDE.md with findings
+          # Commit if changes made
+```
+
+---
+
+## Summary: Key Takeaways
+
+### From Boris Cherny
+
+1. **Verification is #1** - Build feedback loops into every workflow
+2. **Plan before code** - Steps 1-2 are crucial; Claude jumps to coding otherwise
+3. **Opus for fewer iterations** - Stronger model = less steering = faster results
+4. **Hooks for automation** - PostToolUse formatting catches the last 10%
+5. **Shared knowledge compounds** - Team CLAUDE.md updated multiple times weekly
+
+### From Ralph Wiggum
+
+1. **One item per loop** - Focus prevents derailing
+2. **Subagents for context management** - Don't pollute primary context
+3. **Backpressure is essential** - Tests/types/linters reject invalid code
+4. **No placeholders** - Full implementations or nothing
+5. **Self-learning** - Allow Ralph to update AGENT.md
+6. **Commit on success** - Tests pass → commit → push → tag
+7. **Loop back is everything** - Design ways for self-evaluation
+
+### Integration Philosophy
+
+The key insight is that **verification feedback loops** are the highest-leverage improvement. Everything else is optimization, but verification is transformational.
+
+Anvil already has strong workflow commands (`/explore`, `/spec`, `/plan`). What's missing is:
+1. **Automated iteration on failure** (Ralph Wiggum pattern)
+2. **Stop hooks that gate on verification** (Boris's approach)
+3. **PostToolUse formatting** (catch last 10%)
+4. **Atomic action commands** (inner loop efficiency)
+
+---
+
+*This research document should be used as the foundation for SPEC-ANV-verification-loops.md and related implementation work.*