create-hq 5.0.0

package/template/knowledge/Ralph/07-implementation.md

@@ -0,0 +1,316 @@
+# Practical Implementation
+
+## Prerequisites
+
+Before implementing Ralph, you need:
+
+1. **AI Coding Tool**
+   - Claude Code (Anthropic)
+   - Cursor
+   - Other CLI-based AI tools
+
+2. **Project Setup**
+   - Version control (git)
+   - Test framework
+   - Linter
+   - Type checking (if applicable)
+
+3. **Specification Files**
+   - PRD in JSON format
+   - agents.md configuration
+   - Progress tracking file
+
+## Basic Ralph Script
+
+### Minimal Implementation
+
+```bash
+#!/bin/bash
+# ralph.sh - Basic Ralph loop
+
+ITERATIONS=${1:-10}  # Default 10 iterations
+
+for i in $(seq 1 $ITERATIONS); do
+    echo "=== Ralph Loop Iteration $i ==="
+
+    claude --print "Read plans/prd.json and find the first feature where passes is false.
+
+    Implement ONLY that feature.
+
+    Then run these commands in order:
+    1. npm test
+    2. npm run lint
+    3. npm run typecheck
+    4. npm run build
+
+    If ALL pass:
+    1. Commit the changes with a descriptive message
+    2. Update plans/prd.json to set passes: true for this feature
+    3. Append progress to progress.txt
+
+    If ANY fail:
+    1. Fix the issues
+    2. Try again
+
+    Exit when done with this ONE feature."
+
+    echo "Completed iteration $i"
+    sleep 2
+done
+
+echo "Ralph loop complete!"
+```
+
+### Running It
+
+```bash
+chmod +x ralph.sh
+./ralph.sh 20  # Run 20 iterations
+```
+
+## File Structure
+
+```
+project/
+├── ralph.sh              # The loop script
+├── agents.md             # Agent configuration
+├── plans/
+│   └── prd.json          # Product requirements
+├── progress.txt          # Progress log
+├── src/                  # Source code
+├── tests/                # Test files
+├── package.json          # Dependencies
+└── tsconfig.json         # TypeScript config
+```
+
+## Sample PRD Template
+
+```json
+{
+  "project": "my-project",
+  "updated": "2026-01-13",
+  "features": [
+    {
+      "id": "init-001",
+      "title": "Project Setup",
+      "description": "Initialize project with basic structure",
+      "acceptance_criteria": [
+        "package.json exists with correct dependencies",
+        "TypeScript configured with strict mode",
+        "Jest configured for testing",
+        "ESLint configured with recommended rules"
+      ],
+      "passes": true
+    },
+    {
+      "id": "feat-001",
+      "title": "User Authentication",
+      "description": "Implement login functionality",
+      "acceptance_criteria": [
+        "Login form with email and password",
+        "Form validation for required fields",
+        "API call to /auth/login endpoint",
+        "Error handling for failed login",
+        "Redirect to dashboard on success"
+      ],
+      "passes": false
+    }
+  ]
+}
+```
+
+## Sample agents.md Template
+
+```markdown
+# Project: My Project
+
+## Tech Stack
+- TypeScript 5.x
+- React 18.x
+- Jest for testing
+- ESLint for linting
+
+## Commands
+| Command | Purpose |
+|---------|---------|
+| `npm run dev` | Start dev server |
+| `npm run build` | Production build |
+| `npm test` | Run all tests |
+| `npm run lint` | Run linter |
+| `npm run typecheck` | Type check |
+
+## Task Protocol
+
+### When implementing a feature:
+1. Read the feature spec from plans/prd.json
+2. Implement the minimum code to satisfy acceptance criteria
+3. Write tests for the new functionality
+4. Run verification: `npm test && npm run lint && npm run typecheck`
+5. If verification passes, commit and update PRD
+6. Log progress to progress.txt
+
+### Commit message format:
+```
+feat(scope): short description
+
+- Bullet point details
+
+Implements: feature-id
+```
+
+### Never:
+- Modify multiple features in one iteration
+- Skip running tests
+- Use `any` type
+- Leave console.logs in production code
+
+## Project Structure
+- src/components/ - React components
+- src/hooks/ - Custom hooks
+- src/services/ - API services
+- src/types/ - TypeScript types
+- tests/ - Test files
+```
+
+## Advanced: Visual Feedback Loop
+
+For frontend applications, add browser automation:
+
+### MCP Configuration
+
+```json
+{
+  "mcpServers": {
+    "chrome-devtools": {
+      "command": "npx",
+      "args": ["@anthropic/mcp-server-chrome-devtools"],
+      "env": {
+        "CHROME_DEBUG_URL": "http://localhost:9222"
+      }
+    }
+  }
+}
+```
+
+### Chrome Launch Script
+
+```bash
+#!/bin/bash
+# start-chrome-debug.sh
+google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug
+```
+
+### Updated Ralph Script with Visual
+
+```bash
+#!/bin/bash
+# ralph-visual.sh - Ralph with visual feedback
+
+# Start Chrome in debug mode (background)
+./start-chrome-debug.sh &
+CHROME_PID=$!
+
+# Wait for Chrome to start
+sleep 3
+
+for i in $(seq 1 $ITERATIONS); do
+    claude --print "Read plans/prd.json, find first incomplete feature.
+
+    Implement the feature, then:
+    1. Run npm test, lint, typecheck
+    2. Use Chrome DevTools MCP to take screenshots
+    3. Verify the UI looks correct
+    4. If all checks pass, commit
+    5. Update PRD and progress.txt"
+done
+
+# Cleanup
+kill $CHROME_PID
+```
+
+## Running Overnight
+
+### With tmux
+
+```bash
+# Start a tmux session
+tmux new-session -d -s ralph
+
+# Run Ralph in the session
+tmux send-keys -t ralph './ralph.sh 100' Enter
+
+# Detach and go to sleep
+# Next morning:
+tmux attach-session -t ralph
+```
+
+### With nohup
+
+```bash
+nohup ./ralph.sh 100 > ralph.log 2>&1 &
+echo $! > ralph.pid
+
+# Check progress
+tail -f ralph.log
+
+# Stop if needed
+kill $(cat ralph.pid)
+```
+
+## Monitoring Progress
+
+### Simple Progress Check
+
+```bash
+# See current status
+cat progress.txt | tail -20
+
+# Count completed features
+grep -c '"passes": true' plans/prd.json
+```
+
+### Progress Dashboard Script
+
+```bash
+#!/bin/bash
+# status.sh
+
+echo "=== Ralph Status ==="
+echo ""
+echo "Completed features:"
+grep -c '"passes": true' plans/prd.json
+
+echo ""
+echo "Remaining features:"
+grep -c '"passes": false' plans/prd.json
+
+echo ""
+echo "Recent progress:"
+tail -10 progress.txt
+
+echo ""
+echo "Git log:"
+git log --oneline -5
+```
+
+## Troubleshooting
+
+### Loop Gets Stuck
+- Check if tests are flaky
+- Verify acceptance criteria is achievable
+- Look at progress.txt for error patterns
+
+### Context Window Exhaustion
+- Make features smaller
+- Clear conversation between iterations
+- Use `--print` flag for fresh context
+
+### Slow Iterations
+- Optimize test suite
+- Use faster type checker settings
+- Consider language choice (TypeScript > Rust)
+
+### Quality Issues
+- Add more specific acceptance criteria
+- Strengthen back pressure (more tests)
+- Add code review step for critical features

package/template/knowledge/Ralph/08-economics.md

@@ -0,0 +1,182 @@
+# Economic Impact
+
+## The New Economics of Software Development
+
+Ralph fundamentally changes the cost structure of software development.
+
+> "Software development now costs $10.42 US an hour. It's less than you would pay a fast food retail worker. It's cheap. And not only is it cheap, you can do it autonomously."
+> — Geoffrey Huntley
+
+## Cost Comparison
+
+### Traditional Software Development
+
+| Role | Hourly Rate (USD) | Annual Cost |
+|------|------------------|-------------|
+| Junior Developer | $35-50 | $70-100K |
+| Senior Developer | $75-150 | $150-300K |
+| Staff Engineer | $150-250 | $300-500K |
+| Team (5 people) | $350-750 | $700K-1.5M |
+
+### Ralph-Based Development
+
+| Component | Cost |
+|-----------|------|
+| AI API costs | ~$10/hour |
+| Compute | ~$0.50/hour |
+| **Total** | **~$10.50/hour** |
+
+Running 24/7: ~$250/day or ~$7,500/month
+
+## The Disruption Model
+
+Geoffrey references Clayton Christensen's "Disruptive Innovation":
+
+> "This is going to be coming. If you don't think this is not going to be coming, well, one, you should be the one doing it because the opportunity, it's the opportunity of a lifetime right now. Go do it."
+> — Geoffrey Huntley
+
+### The Disruption Pattern
+
+1. **Incumbent**: Large team, high costs, slow iteration
+2. **Disruptor**: Small team + Ralph, low costs, fast iteration
+
+> "What happens when there's a couple people that just in their 20s, they go to Bali and they run the Z80 and Ralph and instead of charging $100,000 a month for the enterprise SaaS, they go after your product and they charge $1,000 a month and they can turn things around faster."
+> — Geoffrey Huntley
+
+## Time Multiplication
+
+Ralph doesn't just reduce costs—it multiplies output:
+
+> "You get weeks worth of work of potentially multiple co-workers in a couple hours."
+> — Geoffrey Huntley
+
+### Traditional Timeline
+```
+Feature request → Planning → Development → Review → QA → Deploy
+     1 day          2 days      1-2 weeks    3 days  2 days  1 day
+Total: 3-4 weeks
+```
+
+### Ralph Timeline
+```
+Feature spec → Ralph overnight → Human review → Deploy
+   30 min        8 hours          2 hours      30 min
+Total: ~12 hours
+```
+
+## Impact on Companies
+
+### Startups
+- Can compete with well-funded incumbents
+- Need smaller teams
+- Faster time to market
+- Lower burn rate
+
+### Enterprises
+- Must adapt or face disruption
+- Over-hired engineering teams become liability
+- Need to transform workflows
+
+> "What about all these companies that raise these massive rounds and they've got so many people working for them? That's the old world."
+> — Geoffrey Huntley
+
+### Individuals
+- Solo developers can build enterprise-grade products
+- Location independence ("chill on a beach in Bali")
+- Skills shift from coding to directing
+
+## The Moat Question
+
+Ralph raises questions about competitive advantages:
+
+> "What is a moat in open source and SaaS now? What is a moat in SaaS now? What are software licenses now? If you can literally just create some plausible deniability."
+> — Geoffrey Huntley
+
+### Traditional Moats (Weakening)
+- Codebase size
+- Team expertise
+- Development velocity
+- Technical debt tolerance
+
+### New Moats (Strengthening)
+- Distribution / GTM
+- Customer relationships
+- Brand / trust
+- Domain expertise
+- Data advantages
+- Regulatory compliance
+
+## Clean Room Economics
+
+Ralph enables legal product cloning through clean room design:
+
+> "The way we came to have Intel and AMD CPUs is because of what was called a clean room design technique."
+> — Geoffrey Huntley
+
+Process:
+1. Analyze competitor's public behavior (spec generation)
+2. Generate specifications (new IP)
+3. Run Ralph forward on specs (clean implementation)
+4. Result: Similar functionality, original code
+
+This threatens:
+- SaaS businesses with replicable features
+- Open source with restrictive licenses (BSL, SSPL)
+- Products relying on implementation complexity as moat
+
+## Founder Perspective
+
+> "Right now, founders are scared. Absolutely scared."
+> — Geoffrey Huntley
+
+Why founders are concerned:
+1. Unit economics changed overnight
+2. Competitive advantages eroding
+3. Small teams can challenge large ones
+4. Time-to-clone shrinking
+
+## Career Implications
+
+### Skills That Matter More
+- System design
+- Prompt engineering / AI orchestration
+- Domain expertise
+- Product sense
+- Quality assurance
+
+### Skills That Matter Less
+- Raw coding speed
+- Language-specific expertise
+- Memorizing APIs
+- Typing speed
+
+> "If you're a senior software engineer right now and you're just picking up the tools now, how much is your paycheck? How much is a junior's paycheck? They got six months advantage on you."
+> — Geoffrey Huntley
+
+## The Opportunity
+
+> "The opportunity of a lifetime right now. Go do it."
+> — Geoffrey Huntley
+
+For individuals:
+- Build products with near-zero marginal development cost
+- Compete in markets previously requiring large teams
+- Work from anywhere
+- Own the output
+
+For companies:
+- Transform development workflows
+- Reduce costs dramatically
+- Increase iteration speed
+- Stay competitive
+
+## Timeline Predictions
+
+Based on Geoffrey's observations (as of early 2026):
+- **Now**: Early adopters seeing 10-100x productivity gains
+- **6-12 months**: Mainstream adoption
+- **1-2 years**: Companies that didn't adapt struggling
+- **2-5 years**: Software development unrecognizable
+
+> "The economics of software development has forever changed."
+> — Geoffrey Huntley

package/template/knowledge/Ralph/09-resources.md

@@ -0,0 +1,145 @@
+# Resources
+
+## Primary Sources
+
+### Original Article
+- **Ralph by Geoffrey Huntley**: https://ghuntley.com/ralph/
+  - The original article introducing the Ralph methodology
+
+### Video Resources
+
+#### By Geoffrey Huntley (Creator)
+
+1. **"The Ralph Wiggum Loop from 1st principles"**
+   - URL: https://www.youtube.com/watch?v=4Nna09dG_c0
+   - Duration: 36:13
+   - Key content: Fundamental explanation of Ralph as an orchestrator pattern for mallocing context windows
+   - Published: January 11, 2026
+
+2. **"AI Giants Interview with Geoffrey Huntley, Creator of the /ralph loop"**
+   - URL: https://www.youtube.com/watch?v=lQ2ihlUzlfs
+   - Duration: 1:08:45
+   - Key content: Comprehensive interview covering Ralph's creation, philosophy, and implications
+   - Published: January 13, 2026
+
+3. **"fundamental skills and knowledge you must have in 2026 for SWE"**
+   - URL: https://www.youtube.com/watch?v=Jr2auYrBDA4
+   - Duration: 39:29
+   - Key content: Context on AI adoption stages, the Z80 experiment, and software development economics
+   - Published: January 13, 2026
+
+4. **"the history of agents.md, the problems with agents.md and what makes a good one"**
+   - URL: https://www.youtube.com/watch?v=8gotGDhQKeQ
+   - Duration: 22:35
+   - Key content: Deep dive into agents.md configuration, common problems, and best practices
+   - Published: January 12, 2026
+
+#### By Matt Pocock
+
+5. **"Ship working code while you sleep with the Ralph Wiggum technique"**
+   - URL: https://www.youtube.com/watch?v=_IK18goX4X8
+   - Duration: 16:23
+   - Key content: Practical implementation guide with actual code examples
+   - Published: January 5, 2026
+   - Additional resources: https://www.aihero.dev/tips-for-ai-coding
+
+6. **"Frontend is HARDER for AI than backend (here's how to fix it)"**
+   - URL: https://www.youtube.com/watch?v=pSritFeoYFo
+   - Duration: 5:29
+   - Key content: Adding visual feedback loops to Ralph for frontend development
+   - Published: January 12, 2026
+
+7. **"How I use Claude Code for real engineering"**
+   - URL: https://www.youtube.com/watch?v=kZ-zzHVUrO4
+   - Duration: 10:11
+   - Key content: Complete workflow for multi-phase projects using Claude Code's plan mode
+   - Published: October 27, 2025
+   - Topics: Plan mode, context window management, multi-phase execution, GitHub issues for plan persistence, concision rules, auto-accept mode
+
+### Anthropic Documentation
+- **"Effective harnesses for long-running agents"**: Referenced by Matt Pocock
+  - Best practices for autonomous agent loops
+  - JSON PRD format recommendations
+  - Browser automation for verification
+
+## Tools & Dependencies
+
+### AI Tools
+- **Claude Code** (Anthropic): https://www.anthropic.com/claude-code
+  - Primary tool for running Ralph loops
+- **Cursor**: https://cursor.sh/
+  - Alternative AI coding environment
+
+### MCP Servers (for visual feedback)
+- **Chrome DevTools MCP**: Browser automation
+- **Playwright MCP**: Cross-browser automation
+- **dev-browser**: https://github.com/SawyerHood/dev-browser
+- **playwriter**: https://github.com/remorses/playwriter
+
+### Supporting Tools
+- **pre-commit**: https://pre-commit.com/
+  - For automating back pressure hooks
+- **Jest**: https://jestjs.io/
+  - JavaScript testing framework
+- **ESLint**: https://eslint.org/
+  - JavaScript linting
+- **TypeScript**: https://www.typescriptlang.org/
+  - Type checking
+
+## Community
+
+### Geoffrey Huntley
+- Website: https://ghuntley.com/
+- YouTube: https://www.youtube.com/@GeoffreyHuntley
+- Background: Former React Extensions maintainer, open source advocate, goat farmer
+
+### Matt Pocock
+- Website: https://www.mattpocock.com/
+- AI Hero: https://www.aihero.dev/
+- YouTube: https://www.youtube.com/@maaborern
+- Background: TypeScript educator, creator of Total TypeScript
+
+## Further Reading
+
+### Concepts Referenced
+- **Clayton Christensen's Disruptive Innovation**
+  - Book: "The Innovator's Dilemma"
+  - Explains how small players disrupt incumbents
+
+- **Clean Room Design**
+  - Legal technique for reverse engineering
+  - How AMD created x86 compatible CPUs
+
+### Related Techniques
+- **Test-Driven Development (TDD)**
+  - Writing tests before code
+  - Foundation for back pressure
+
+- **Continuous Integration (CI)**
+  - Automated testing on commit
+  - Infrastructure for verification
+
+## Glossary Quick Reference
+
+| Term | Definition |
+|------|------------|
+| Ralph | Autonomous AI coding loop methodology |
+| Mallocing | Managing context window allocation |
+| Context Rot | Degradation of AI performance over long conversations |
+| Compaction | Context filled with irrelevant information |
+| Back Pressure | Automated verification that catches AI errors |
+| PRD | Product Requirements Document (JSON format) |
+| agents.md | Configuration file for AI coding agents |
+| AFK Coding | Running AI agents without supervision |
+| Z80 | Geoffrey's original proof-of-concept experiment |
+| Clean Room | Legal technique for implementing specs without copying code |
+
+## Version History
+
+This knowledge repository compiled: January 2026
+
+Based on publicly available videos and talks through January 13, 2026.
+
+---
+
+*Note: URLs and resources current as of compilation date. Check original sources for updates.*