create-hq 5.0.0

package/template/knowledge/Ralph/02-core-concepts.md

@@ -0,0 +1,114 @@
+# Core Concepts
+
+## Key Terminology
+
+### Mallocing / Memory Allocation
+
+In the context of Ralph, "mallocing" refers to how you allocate and manage the AI's context window - similar to memory allocation in programming.
+
+> "Ralph is really just a mallocing orchestrator that avoids context rot and compaction."
+> — Geoffrey Huntley
+
+Good mallocing means:
+- Only loading relevant specifications into context
+- Clearing context between tasks
+- Being intentional about what information the AI sees
+
+### Context Rot
+
+Context rot occurs when the AI's context window becomes polluted with outdated or irrelevant information from earlier in the conversation. This degrades the quality of outputs over time.
+
+**Solution**: Start fresh for each task by spawning a new agent instance.
+
+### Compaction
+
+Compaction is when the context window gets filled with verbose or unnecessary content, leaving less room for the actual task at hand.
+
+> "Compaction is the devil"
+> — Geoffrey Huntley
+
+**Solution**: Use focused specifications and remove unnecessary content from the context.
+
+### Back Pressure
+
+Back pressure is the feedback mechanism that pushes back on the AI when it generates incorrect code. This is the key to making autonomous coding work.
+
+> "The back pressure if it generates something wrong, the test pushes back on the generative function to try again before the wheel is allowed to turn around."
+> — Geoffrey Huntley
+
+Forms of back pressure:
+- Unit tests
+- Integration tests
+- Type checking (TypeScript, etc.)
+- Linting
+- Build processes
+- Pre-commit hooks
+
+### Generative Function
+
+The AI model that generates code. In Ralph, we "engineer back pressure to keep the generative function on the rails."
+
+### The Loop / Wheel
+
+The core iteration cycle of Ralph:
+1. Pick a task from specifications
+2. Generate code
+3. Run back pressure checks
+4. If checks pass, commit and move to next task
+5. If checks fail, regenerate
+6. Repeat
+
+### Routing
+
+The process of directing the AI's attention to specific tasks or specifications. In Ralph, you control the routing by selecting which specifications to load into context.
+
+### Weavers
+
+Geoffrey's term for autonomous coding agents that work together. They can:
+- Introduce features with feature flags
+- Deploy code
+- Monitor analytics
+- Make autonomous decisions about optimizations
+
+### AFK Coding
+
+"Away From Keyboard" coding - running AI agents autonomously while you're not actively supervising.
+
+> "This front-end feedback loop makes AFK AI coding a lot more powerful. If you're looping an AI, for instance, in the Ralph Wiggum setup, then plugging a browser into your front end or full stack work will be such a massive improvement."
+> — Matt Pocock
+
+## The Six Stages of AI Adoption
+
+Geoffrey Huntley describes six stages software developers go through:
+
+1. **"It's not good enough"** - Dismissing AI capabilities
+2. **"Prove to me that this isn't hype"** - Skepticism
+3. **"Experimenting with LLMs"** - Trying it out
+4. **"Deer in headlights"** - Realizing implications ("Will I have a job in the future?")
+5. **"Alarmed - need to bin our planning and change priorities"** - Organizational response
+6. **"Engaged - realization that LLMs can be programmed"** - Active adoption
+
+## Key Principles
+
+### 1. Simplicity Over Complexity
+A for loop beats elaborate orchestration systems.
+
+### 2. Fresh Context Per Task
+Start each task with a clean context to avoid rot.
+
+### 3. Small, Atomic Changes
+Keep changes small enough to verify and commit independently.
+
+### 4. Robust Feedback Loops
+Invest heavily in automated testing and verification.
+
+### 5. No Human Tool Calls
+> "Anytime you tool call a human, that's not AGI, that's not Ralph."
+> — Geoffrey Huntley
+
+### 6. Fast Feedback
+Optimize for quick iteration cycles - slow compilation (like Rust) can be a bottleneck.
+
+### 7. Engineering Still Matters
+> "I still believe in engineering. Still believe in engineering and like the bridge collapses, that's on you."
+> — Geoffrey Huntley

package/template/knowledge/Ralph/03-how-ralph-works.md

@@ -0,0 +1,184 @@
+# How Ralph Works
+
+## The Basic Loop
+
+At its core, Ralph is a simple bash script that runs in a for loop:
+
+```bash
+#!/bin/bash
+for i in {1..N}; do
+    claude --print "Pick ONE incomplete item from plans/prd.json and implement it.
+    Run tests. If they pass, commit. Update the PRD passes field.
+    Write progress to progress.txt"
+done
+```
+
+> "Everyone's calling it Ralph Wiggum. This is credited to Geoffrey Huntley."
+> — Matt Pocock
+
+## The Components
+
+### 1. PRD (Product Requirements Document)
+
+A JSON file containing user stories with pass/fail status:
+
+```json
+{
+  "features": [
+    {
+      "id": "beat-display",
+      "description": "Beats should display as three orange ellipses dots below the clip",
+      "acceptance_criteria": [
+        "Add a beat to a clip",
+        "Verify three orange dots appear below the clip",
+        "Verify they're orange colored",
+        "Verify they form an ellipses pattern"
+      ],
+      "passes": false
+    }
+  ]
+}
+```
+
+The PRD serves dual purposes:
+- A specification for what to build
+- A test harness tracking what's done
+
+### 2. Progress File (progress.txt)
+
+A running log of what the agent has accomplished:
+
+```
+[2026-01-13 10:30] Implemented beat-display feature
+[2026-01-13 10:32] Tests passing, committed: abc123
+[2026-01-13 10:35] Started work on beat-animation
+```
+
+This provides:
+- Audit trail
+- Context for subsequent runs
+- Human review capability
+
+### 3. agents.md / CLAUDE.md
+
+Configuration file that tells the AI how to behave:
+
+```markdown
+# Project Context
+This is a video editing application built with TypeScript and React.
+
+# Build Commands
+- `npm run build` - Build the application
+- `npm test` - Run tests
+- `npm run lint` - Run linter
+
+# Coding Standards
+- Use TypeScript strict mode
+- All functions must have JSDoc comments
+- Keep files under 300 lines
+```
+
+### 4. Back Pressure Mechanisms
+
+The verification layer that ensures code quality:
+
+- **Type checking**: `tsc --noEmit`
+- **Linting**: `eslint .`
+- **Unit tests**: `npm test`
+- **Build verification**: `npm run build`
+- **Pre-commit hooks**: Run all checks before allowing commits
+
+## The Execution Flow
+
+```
+┌─────────────────┐
+│  Start Loop     │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  Load PRD.json  │
+│  Load agents.md │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│ Pick ONE task   │
+│ (not passing)   │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│ Generate code   │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│ Run back        │
+│ pressure checks │
+└────────┬────────┘
+         │
+    ┌────┴────┐
+    │ Pass?   │
+    └────┬────┘
+         │
+    Yes  │  No
+    ┌────┴────┐
+    │         │
+    ▼         ▼
+┌───────┐ ┌───────┐
+│Commit │ │Retry  │
+│Update │ │       │
+│PRD    │ └───┬───┘
+└───┬───┘     │
+    │         │
+    └────┬────┘
+         │
+         ▼
+┌─────────────────┐
+│  Next iteration │
+└─────────────────┘
+```
+
+## Key Implementation Details
+
+### Why --print Flag?
+
+The `--print` flag (or equivalent) ensures a fresh context for each task:
+
+> "What happens is you work out a unit economic cost for software development... but to get it working, you have to understand the bare bones fundamentals from first principles."
+> — Geoffrey Huntley
+
+### Small Changes Are Critical
+
+> "Keep these changes really small so that you still have context window left for the LLM to actually check that the change works."
+> — Matt Pocock
+
+### The Anthropic Recommendation
+
+> "Effective harnesses for long-running agents from Anthropic... they noticed Claude's tendency to mark a feature as complete without proper testing. But it did much better at verifying features end to end once explicitly prompted to use browser automation tools."
+> — Matt Pocock
+
+## Advanced: Visual Feedback Loops
+
+For frontend work, add browser automation:
+
+```javascript
+// MCP configuration for Chrome DevTools
+{
+  "mcpServers": {
+    "chrome-devtools": {
+      "url": "http://localhost:9222"
+    }
+  }
+}
+```
+
+This allows the AI to:
+- Take screenshots
+- Verify visual changes
+- Test user interactions
+- Check responsive design
+
+> "Without it, your LLM is essentially flying blind. It can't see the execution environment in which the changes are being made."
+> — Matt Pocock

package/template/knowledge/Ralph/04-back-pressure.md

@@ -0,0 +1,222 @@
+# Back Pressure Engineering
+
+## What is Back Pressure?
+
+Back pressure is the automated feedback mechanism that validates AI-generated code before it's allowed to proceed. It's the critical component that makes autonomous coding reliable.
+
+> "The back pressure if it generates something wrong, the test pushes back on the generative function to try again before the wheel is allowed to turn around."
+> — Geoffrey Huntley
+
+> "Our job is now engineering back pressure to the generative function to keep the generative function on the rails, the locomotive."
+> — Geoffrey Huntley
+
+## Why Back Pressure Matters
+
+Without back pressure:
+- AI will hallucinate solutions
+- Bugs accumulate silently
+- Context rot compounds errors
+- Human review becomes overwhelming
+
+With proper back pressure:
+- Errors are caught immediately
+- Each commit is verified working
+- The loop is truly autonomous
+- Code quality remains high
+
+## Types of Back Pressure
+
+### 1. Type Systems
+
+**TypeScript (Recommended)**
+```bash
+tsc --noEmit
+```
+
+Benefits:
+- Fast compilation
+- Comprehensive type checking
+- Excellent IDE integration
+- Good error messages for AI
+
+**Rust** (Trade-offs)
+> "The compilation speed on Rust is very, very, very slow. What happens if it does an invalid generation or hallucination and the compilation takes 30 minutes? Compare that against TypeScript - in that time how many generations has it done?"
+> — Geoffrey Huntley
+
+### 2. Linting
+
+```bash
+eslint . --max-warnings 0
+```
+
+Catches:
+- Code style violations
+- Potential bugs
+- Best practice violations
+- Security issues
+
+### 3. Unit Tests
+
+```bash
+npm test
+# or
+pytest
+# or
+cargo test
+```
+
+The most important form of back pressure:
+- Verifies functionality
+- Catches regressions
+- Documents behavior
+- Enables refactoring
+
+### 4. Integration Tests
+
+```bash
+npm run test:integration
+```
+
+Verifies:
+- Component interactions
+- API contracts
+- Database operations
+- External service integration
+
+### 5. Build Verification
+
+```bash
+npm run build
+```
+
+Ensures:
+- Code compiles
+- Dependencies resolve
+- Assets bundle correctly
+- No dead code
+
+### 6. Pre-commit Hooks
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: local
+    hooks:
+      - id: typecheck
+        name: Type Check
+        entry: npm run typecheck
+        language: system
+      - id: lint
+        name: Lint
+        entry: npm run lint
+        language: system
+      - id: test
+        name: Test
+        entry: npm test
+        language: system
+```
+
+### 7. Visual Verification (Frontend)
+
+For frontend applications, text-based back pressure isn't enough:
+
+> "The difficulty comes when you start adding visual elements... A feedback loop in a frontend: write some code, then look at the UI to see what changed, go back, write a bit more code, look at the UI again."
+> — Matt Pocock
+
+Solution: Browser automation via MCP:
+- Screenshot comparison
+- DOM inspection
+- User interaction simulation
+- Responsive design testing
+
+## Engineering Effective Back Pressure
+
+### Make It Fast
+
+Speed is critical for rapid iteration:
+
+```
+Fast back pressure:
+  TypeScript + ESLint + Jest = ~10 seconds
+
+Slow back pressure:
+  Rust compilation = ~5-30 minutes
+```
+
+> "If the compilation takes forever, what happens if it does an invalid generation? You got to be an engineer and make that back pressure fast."
+> — Geoffrey Huntley
+
+### Make It Comprehensive
+
+Cover all failure modes:
+- Syntax errors (compiler)
+- Logic errors (tests)
+- Style issues (linter)
+- Type errors (type checker)
+- Visual issues (browser automation)
+
+### Make It Deterministic
+
+Tests must be:
+- Reproducible
+- Not flaky
+- Independent
+- Fast
+
+### Make It Informative
+
+Error messages should help the AI fix issues:
+- Clear descriptions
+- Line numbers
+- Suggested fixes
+- Context
+
+## The Feedback Loop Cycle
+
+```
+┌──────────────────────────────────────────┐
+│                                          │
+│  Generate Code                           │
+│       │                                  │
+│       ▼                                  │
+│  ┌─────────┐                            │
+│  │Type     │──fail──► Fix & Retry       │
+│  │Check    │                     │      │
+│  └────┬────┘                     │      │
+│       │pass                      │      │
+│       ▼                          │      │
+│  ┌─────────┐                     │      │
+│  │Lint     │──fail──► Fix & Retry│      │
+│  └────┬────┘                     │      │
+│       │pass                      │      │
+│       ▼                          │      │
+│  ┌─────────┐                     │      │
+│  │Test     │──fail──► Fix & Retry│      │
+│  └────┬────┘                     │      │
+│       │pass                      │      │
+│       ▼                          │      │
+│  ┌─────────┐                     │      │
+│  │Build    │──fail──► Fix & Retry│      │
+│  └────┬────┘                     │      │
+│       │pass                      │      │
+│       ▼                          │      │
+│  Commit & Proceed                       │
+│                                          │
+└──────────────────────────────────────────┘
+```
+
+## Language Recommendations
+
+Based on back pressure speed and reliability:
+
+| Language | Back Pressure Speed | Recommendation |
+|----------|-------------------|----------------|
+| TypeScript | Very Fast | Highly Recommended |
+| Python | Fast | Recommended |
+| Go | Fast | Recommended |
+| Java | Medium | Acceptable |
+| Rust | Slow | Trade-offs |
+| C++ | Slow | Trade-offs |
+
+> "Any discipline where you can mechanically verify it is going to be automated. That's absolutely certain - when you can mechanically verify it, it's going to be automated."
+> — Geoffrey Huntley