create-hq 5.0.0

package/template/README.md

@@ -0,0 +1,368 @@
+<p align="center">
+  <img src="docs/images/hq-banner.svg" alt="HQ - Your Personal Operating System" width="600">
+</p>
+
+<h1 align="center">HQ - Personal OS for AI Workers</h1>
+
+<p align="center">
+  <strong>Build your AI team. Ship projects autonomously. Never lose context.</strong>
+</p>
+
+<p align="center">
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
+  <a href="https://github.com/coreyepstein/hq-cli"><img src="https://img.shields.io/badge/CLI-hq--cli-green.svg" alt="HQ CLI"></a>
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#whats-new-in-v20">What's New</a> •
+  <a href="#core-concepts">Core Concepts</a> •
+  <a href="#commands">Commands</a> •
+  <a href="#workers">Workers</a>
+</p>
+
+---
+
+## What is HQ?
+
+HQ is infrastructure for orchestrating **AI workers** - autonomous agents that code, write content, research, and automate tasks.
+
+Not just files. Active systems that:
+- **Execute** - Workers do real work autonomously
+- **Learn** - Knowledge bases grow smarter over time
+- **Scale** - Add workers for new domains
+- **Survive** - Checkpoints persist across sessions
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                           YOUR HQ                               │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│   ┌─────────────┐    ┌─────────────┐    ┌─────────────┐        │
+│   │   WORKERS   │    │  KNOWLEDGE  │    │  COMMANDS   │        │
+│   │  Do things  │    │   Learn &   │    │ Orchestrate │        │
+│   │ autonomously│    │   remember  │    │  workflows  │        │
+│   └─────────────┘    └─────────────┘    └─────────────┘        │
+│          │                  │                  │                │
+│          └──────────────────┼──────────────────┘                │
+│                             ▼                                   │
+│                    ┌─────────────┐                              │
+│                    │ CHECKPOINTS │                              │
+│                    │   Survive   │                              │
+│                    │   sessions  │                              │
+│                    └─────────────┘                              │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Quick Start
+
+```bash
+# 1. Clone
+git clone https://github.com/coreyepstein/hq-starter-kit.git my-hq
+cd my-hq
+
+# 2. Open in Claude Code
+claude
+
+# 3. Run setup wizard
+/setup
+```
+
+That's it. You now have a personal OS with 18 workers ready to deploy.
+
+## What's New in v2.0
+
+### Project Orchestration
+Execute entire projects autonomously with the Ralph loop:
+```bash
+/prd "Build a dashboard"     # Create PRD through discovery
+/run-project my-dashboard    # Execute all tasks via workers
+```
+
+### Content Pipeline
+Full content workflow from idea to publish:
+```bash
+/contentidea "AI agents"     # Build out idea → drafts
+/suggestposts               # Research-driven suggestions
+/scheduleposts              # Smart timing for posting
+```
+
+### Dev Team (13 Workers)
+Complete development team for autonomous coding:
+- `project-manager` - PRD lifecycle
+- `task-executor` - Route tasks to workers
+- `architect` - System design
+- `backend-dev` / `frontend-dev` / `database-dev`
+- `qa-tester` - Testing & validation
+- `code-reviewer` - PR management
+- And more...
+
+### Auto-Checkpoint
+Never lose work. Sessions auto-save to `workspace/threads/`.
+
+### Design Iteration
+A/B test designs with git branches:
+```bash
+/design-iterate hero-section  # Create variations
+# Review, compare, choose winner
+```
+
+---
+
+## Core Concepts
+
+### Workers
+Autonomous agents with defined skills. They *do things*.
+
+| Type | Purpose | Examples |
+|------|---------|----------|
+| **CodeWorker** | Implement features, fix bugs | frontend-dev, backend-dev |
+| **ContentWorker** | Draft content, maintain voice | content-brand, content-sales |
+| **SocialWorker** | Post to platforms | x-worker, linkedin-worker |
+| **ResearchWorker** | Analyze data, markets | analyst, researcher |
+| **OpsWorker** | Reports, automation | cfo-worker, cmo-worker |
+
+### Knowledge Bases
+Workers learn from and contribute to shared knowledge:
+
+- `knowledge/Ralph/` - Autonomous coding methodology
+- `knowledge/workers/` - Worker patterns & templates
+- `knowledge/ai-security-framework/` - Security best practices
+- `knowledge/dev-team/` - Development patterns
+- `knowledge/design-styles/` - Design guidelines
+
+### Commands
+Slash commands orchestrate everything:
+
+```bash
+/run worker-name skill    # Execute a worker skill
+/checkpoint my-work       # Save session state
+/handoff                  # Prepare for fresh session
+```
+
+### Checkpoints
+Work survives context limits:
+
+```bash
+/checkpoint feature-x     # Save state
+# ... context fills up ...
+/nexttask                 # Finds checkpoint, continues work
+```
+
+---
+
+## Commands
+
+### Session Management
+| Command | What it does |
+|---------|--------------|
+| `/checkpoint` | Save progress, survive context limits |
+| `/handoff` | Prepare handoff for fresh session |
+| `/reanchor` | Pause, show state, realign |
+| `/nexttask` | Find next thing to work on |
+
+### Workers
+| Command | What it does |
+|---------|--------------|
+| `/run` | List all workers |
+| `/run {worker}` | Show worker's skills |
+| `/run {worker} {skill}` | Execute a skill |
+| `/newworker` | Create a new worker |
+| `/metrics` | View worker execution metrics |
+
+### Projects
+| Command | What it does |
+|---------|--------------|
+| `/prd` | Generate PRD through discovery |
+| `/run-project` | Execute project via Ralph loop |
+| `/pure-ralph` | External terminal loop (fully autonomous) |
+| `/execute-task` | Run single task with workers |
+
+### Content
+| Command | What it does |
+|---------|--------------|
+| `/contentidea` | Build idea into full content suite |
+| `/suggestposts` | Research-driven post suggestions |
+| `/scheduleposts` | Choose what to post now |
+
+### System
+| Command | What it does |
+|---------|--------------|
+| `/search` | Full-text search across HQ |
+| `/hq-sync` | Sync modules from manifest |
+| `/cleanup` | Audit and clean HQ |
+| `/design-iterate` | Manage design A/B tests |
+
+---
+
+## Workers
+
+### Dev Team (13 workers)
+Full development team for autonomous project execution:
+
+```yaml
+project-manager    → PRD lifecycle, task selection
+task-executor      → Analyze & route to workers
+architect          → System design, API design
+backend-dev        → API endpoints, business logic
+frontend-dev       → React/Next components
+database-dev       → Schema, migrations
+qa-tester          → Testing, validation
+motion-designer    → Animations, polish
+infra-dev          → CI/CD, deployment
+code-reviewer      → PR review, quality gates
+knowledge-curator  → Update knowledge bases
+product-planner    → Technical specs
+```
+
+### Content Team (5 workers)
+Specialized content analysis:
+
+```yaml
+content-brand     → Voice, messaging, tone
+content-sales     → Conversion copy, CTAs
+content-product   → Technical accuracy
+content-legal     → Compliance, claims
+content-shared    → Shared utilities (library)
+```
+
+### Creating Your Own
+
+```bash
+/newworker  # Interactive scaffold
+```
+
+Or manually create `workers/my-worker/worker.yaml`:
+
+```yaml
+worker:
+  id: my-worker
+  name: "My Worker"
+  type: OpsWorker
+
+skills:
+  - name: do-thing
+    description: "Does the thing"
+    execution:
+      steps:
+        - "Step 1"
+        - "Step 2"
+```
+
+---
+
+## Project Execution
+
+HQ uses the **Ralph Methodology** for autonomous coding.
+
+### The Loop
+
+```
+1. Pick task from PRD (passes: false)
+2. Execute in fresh context
+3. Run back pressure (tests, lint, typecheck)
+4. If passing → commit, mark complete
+5. Repeat until done
+```
+
+### Why It Works
+
+- **Fresh context per task** - No accumulated confusion
+- **Back pressure validates** - Code that doesn't pass isn't done
+- **Atomic commits** - One task = one commit
+- **PRD is truth** - Simple JSON, easy to inspect
+
+### Running a Project
+
+```bash
+# 1. Create PRD
+/prd "Build user authentication"
+
+# 2. Execute via Ralph loop
+/run-project auth-system
+
+# 3. Monitor progress
+/run-project auth-system --status
+```
+
+### Pure Ralph Mode
+
+For fully autonomous execution, use `/pure-ralph` to spawn an external terminal that runs the loop independently:
+
+```bash
+# Auto mode (default) - fully autonomous, no intervention needed
+/pure-ralph my-project
+
+# Manual mode - see chain of thought, close windows between tasks
+/pure-ralph my-project -m
+```
+
+**Why Pure Ralph?**
+- **Fresh context every task** - Each task runs in a new Claude session, preventing context rot
+- **External orchestrator** - Loop runs outside Claude, immune to context compression
+- **Self-improving** - Claude can update its own prompt as it learns
+- **Watchable** - See progress in a visible terminal window
+
+---
+
+## Directory Structure
+
+```
+my-hq/
+├── .claude/
+│   ├── CLAUDE.md              # Session protocol
+│   └── commands/              # 22 slash commands
+├── knowledge/
+│   ├── Ralph/                 # Coding methodology
+│   ├── workers/               # Worker framework + templates
+│   ├── ai-security-framework/ # Security practices
+│   ├── dev-team/              # Development patterns
+│   ├── design-styles/         # Design guidelines
+│   └── loom/                  # Agent patterns
+├── workers/
+│   ├── registry.yaml          # Worker index
+│   ├── dev-team/              # 13 dev workers
+│   └── content-*/             # Content workers
+├── projects/                  # Your PRDs
+├── social-content/
+│   └── drafts/                # Content drafts (x/, linkedin/)
+├── workspace/
+│   ├── checkpoints/           # Manual saves
+│   ├── threads/               # Auto-saved sessions
+│   ├── orchestrator/          # Project state
+│   └── learnings/             # Captured insights
+└── companies/                 # Multi-company setup
+```
+
+---
+
+## Part of the HQ Framework
+
+| Component | Purpose |
+|-----------|---------|
+| **hq-starter-kit** | This repo - personal OS template |
+| **[hq-cli](https://github.com/coreyepstein/hq-cli)** | Module management CLI |
+
+---
+
+## Customization
+
+This is a **template**. Make it yours:
+
+- Add workers for your workflows
+- Build knowledge bases for your domains
+- Create commands for your patterns
+- Connect tools via MCP
+
+---
+
+## Credits
+
+- **Ralph Methodology** by [Geoffrey Huntley](https://ghuntley.com/ralph/)
+- **Loom Agent Architecture** by [Geoffrey Huntley](https://github.com/ghuntley/loom) - Thread system, state machine, and agent patterns
+- Inspired by personal knowledge systems and AI workflow patterns
+
+## License
+
+MIT - Do whatever you want with it.

package/template/docs/images/ascii-banner-options.md

@@ -0,0 +1,122 @@
+# ASCII Banner Options for HQ Starter Kit
+
+## Option 1: Command Center
+
+```
+                    ╔═══════════════════════════════════════════════════════════╗
+                    ║                                                           ║
+   ██╗  ██╗ ██████╗ ║  WORKERS ────────┬─────── KNOWLEDGE ────────┬─────────    ║
+   ██║  ██║██╔═══██╗║     │            │            │              │             ║
+   ███████║██║   ██║║     ▼            ▼            ▼              ▼             ║
+   ██╔══██║██║▄▄ ██║║  [CODE]      [CONTENT]    [RALPH]      [SECURITY]         ║
+   ██║  ██║╚██████╔╝║     │            │            │              │             ║
+   ╚═╝  ╚═╝ ╚══▀▀═╝ ║     └────────────┴────────────┴──────────────┘             ║
+                    ║                         │                                  ║
+                    ║                    ORCHESTRATE                             ║
+                    ║                         │                                  ║
+                    ║              ┌──────────┴──────────┐                       ║
+                    ║              ▼                     ▼                       ║
+                    ║         /run-project         /checkpoint                   ║
+                    ╚═══════════════════════════════════════════════════════════╝
+                                     Personal OS for AI Workers
+```
+
+## Option 2: Clean System Flow
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                                                                                 │
+│     ██╗  ██╗ ██████╗      ─────────────────────────────────────────────────     │
+│     ██║  ██║██╔═══██╗     P E R S O N A L   O S   F O R   A I   W O R K E R S   │
+│     ███████║██║   ██║     ─────────────────────────────────────────────────     │
+│     ██╔══██║██║▄▄ ██║                                                           │
+│     ██║  ██║╚██████╔╝              ┌────────────────────┐                       │
+│     ╚═╝  ╚═╝ ╚══▀▀═╝               │      YOU           │                       │
+│                                    └─────────┬──────────┘                       │
+│                                              │                                  │
+│          ┌───────────────────────────────────┼───────────────────────────────┐  │
+│          │                                   │                               │  │
+│          ▼                                   ▼                               ▼  │
+│    ┌──────────┐                        ┌──────────┐                   ┌──────────┐
+│    │ WORKERS  │                        │ PROJECTS │                   │KNOWLEDGE │
+│    │  18 AI   │◄──── orchestrate ─────►│   PRDs   │◄───── learn ─────►│  Ralph   │
+│    │  agents  │                        │  Tasks   │                   │  Bases   │
+│    └──────────┘                        └──────────┘                   └──────────┘
+│          │                                   │                               │  │
+│          └───────────────────────────────────┼───────────────────────────────┘  │
+│                                              │                                  │
+│                                    ┌─────────┴─────────┐                        │
+│                                    │    CHECKPOINTS    │                        │
+│                                    │  Never lose work  │                        │
+│                                    └───────────────────┘                        │
+│                                                                                 │
+└─────────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Option 3: Minimal Bold
+
+```
+
+     ██╗  ██╗ ██████╗        ███████╗████████╗ █████╗ ██████╗ ████████╗███████╗██████╗
+     ██║  ██║██╔═══██╗       ██╔════╝╚══██╔══╝██╔══██╗██╔══██╗╚══██╔══╝██╔════╝██╔══██╗
+     ███████║██║   ██║       ███████╗   ██║   ███████║██████╔╝   ██║   █████╗  ██████╔╝
+     ██╔══██║██║▄▄ ██║       ╚════██║   ██║   ██╔══██║██╔══██╗   ██║   ██╔══╝  ██╔══██╗
+     ██║  ██║╚██████╔╝       ███████║   ██║   ██║  ██║██║  ██║   ██║   ███████╗██║  ██║
+     ╚═╝  ╚═╝ ╚══▀▀═╝        ╚══════╝   ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝   ╚══════╝╚═╝  ╚═╝
+
+          ╦╔═╦╔╦╗
+          ╠╩╗║ ║     Build your AI team. Ship projects autonomously. Never lose context.
+          ╩ ╩╩ ╩
+
+                    [WORKERS]────────[KNOWLEDGE]────────[COMMANDS]────────[CHECKPOINTS]
+
+```
+
+## Option 4: Retro Terminal
+
+```
+╔════════════════════════════════════════════════════════════════════════════════════╗
+║  ┌──────────────────────────────────────────────────────────────────────────────┐  ║
+║  │ █ HQ STARTER KIT v2.0                                              [_][□][X] │  ║
+║  ├──────────────────────────────────────────────────────────────────────────────┤  ║
+║  │                                                                              │  ║
+║  │   > SYSTEM ONLINE                                                            │  ║
+║  │   > LOADING MODULES...                                                       │  ║
+║  │                                                                              │  ║
+║  │   ╦ ╦╔═╗   ┌─────────────────────────────────────────────────────────────┐   │  ║
+║  │   ╠═╣║═╬╗  │  WORKERS: 18 active    │  KNOWLEDGE: 5 bases               │   │  ║
+║  │   ╩ ╩╚═╝╚  │  COMMANDS: 22 loaded   │  CHECKPOINTS: ready               │   │  ║
+║  │            └─────────────────────────────────────────────────────────────┘   │  ║
+║  │                                                                              │  ║
+║  │   > Personal OS for AI Workers                                               │  ║
+║  │   > Type /setup to begin                                                     │  ║
+║  │                                                                              │  ║
+║  │   $ _                                                                        │  ║
+║  │                                                                              │  ║
+║  └──────────────────────────────────────────────────────────────────────────────┘  ║
+╚════════════════════════════════════════════════════════════════════════════════════╝
+```
+
+## Option 5: Circuit Board
+
+```
+
+    ●━━━━━━━━━━━━━━━━━━━━━━━━━━━━●━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━●━━━━━━━━━━━━━━━●
+    ┃                            ┃                               ┃               ┃
+    ┃   ██╗  ██╗ ██████╗         ┃    ┏━━━━━━━━━━━━━━━━━━━━━┓    ┃               ┃
+    ┃   ██║  ██║██╔═══██╗        ┃    ┃  STARTER KIT v2.0   ┃    ┃               ┃
+    ┃   ███████║██║   ██║━━━━━━━━┫    ┗━━━━━━━━━┳━━━━━━━━━━━┛    ┃               ┃
+    ┃   ██╔══██║██║▄▄ ██║        ┃              ┃                ┃               ┃
+    ┃   ██║  ██║╚██████╔╝        ┃    ━━━━━━━━━━╋━━━━━━━━━━━━    ┃               ┃
+    ┃   ╚═╝  ╚═╝ ╚══▀▀═╝         ┃              ┃                ┃               ┃
+    ┃                            ┃              ┃                ┃               ┃
+    ●━━━━┳━━━━━━━━━━━━━━━━━━━━━━━●━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━●━━━━━━━━┳━━━━━●
+         ┃                                      ┃                         ┃
+         ┃    ┌─────────┐  ┌─────────┐  ┌───────┴───────┐  ┌─────────┐   ┃
+         ┗━━━━┥ WORKERS ├──┤KNOWLEDGE├──┤   COMMANDS    ├──┤CHECKPTS ├━━━┛
+              └─────────┘  └─────────┘  └───────────────┘  └─────────┘
+
+              Personal OS for AI Workers ━━ Build your team. Ship autonomously.
+
+```
+

package/template/docs/images/hq-banner.svg

@@ -0,0 +1,105 @@
+<svg width="900" height="320" viewBox="0 0 900 320" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <style>
+      @import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;700;900&amp;family=JetBrains+Mono:wght@400;500&amp;display=swap');
+      .title { font-family: 'Inter', system-ui, sans-serif; font-weight: 900; }
+      .subtitle { font-family: 'Inter', system-ui, sans-serif; font-weight: 700; }
+      .body { font-family: 'Inter', system-ui, sans-serif; font-weight: 400; }
+      .mono { font-family: 'JetBrains Mono', monospace; font-weight: 500; }
+    </style>
+  </defs>
+
+  <!-- Background -->
+  <rect width="900" height="320" fill="#0A0A0A"/>
+
+  <!-- Corner Brackets -->
+  <g stroke="#F0F0F0" stroke-width="2" fill="none">
+    <!-- Top Left -->
+    <path d="M 30 30 L 30 60" />
+    <path d="M 30 30 L 60 30" />
+    <!-- Top Right -->
+    <path d="M 870 30 L 870 60" />
+    <path d="M 870 30 L 840 30" />
+    <!-- Bottom Left -->
+    <path d="M 30 290 L 30 260" />
+    <path d="M 30 290 L 60 290" />
+    <!-- Bottom Right -->
+    <path d="M 870 290 L 870 260" />
+    <path d="M 870 290 L 840 290" />
+  </g>
+
+  <!-- Orbital Glyph - Node Network -->
+  <g transform="translate(160, 160)">
+    <!-- Outer orbit -->
+    <ellipse cx="0" cy="0" rx="90" ry="50" fill="none" stroke="#333333" stroke-width="1" transform="rotate(-20)"/>
+    <!-- Middle orbit -->
+    <ellipse cx="0" cy="0" rx="70" ry="35" fill="none" stroke="#444444" stroke-width="1" transform="rotate(25)"/>
+    <!-- Inner orbit -->
+    <circle cx="0" cy="0" r="40" fill="none" stroke="#555555" stroke-width="1" stroke-dasharray="4 4"/>
+
+    <!-- Crosshair -->
+    <line x1="-100" y1="0" x2="100" y2="0" stroke="#333333" stroke-width="1"/>
+    <line x1="0" y1="-70" x2="0" y2="70" stroke="#333333" stroke-width="1"/>
+
+    <!-- Central node -->
+    <circle cx="0" cy="0" r="8" fill="#F0F0F0"/>
+
+    <!-- Orbiting nodes (workers) -->
+    <circle cx="65" cy="-30" r="5" fill="#F0F0F0"/>
+    <circle cx="-70" cy="20" r="5" fill="#F0F0F0"/>
+    <circle cx="20" cy="45" r="5" fill="#F0F0F0"/>
+    <circle cx="-40" cy="-40" r="5" fill="#666666"/>
+    <circle cx="50" cy="35" r="4" fill="#666666"/>
+
+    <!-- Connection lines -->
+    <line x1="0" y1="0" x2="65" y2="-30" stroke="#F0F0F0" stroke-width="1" opacity="0.5"/>
+    <line x1="0" y1="0" x2="-70" y2="20" stroke="#F0F0F0" stroke-width="1" opacity="0.5"/>
+    <line x1="0" y1="0" x2="20" y2="45" stroke="#F0F0F0" stroke-width="1" opacity="0.5"/>
+  </g>
+
+  <!-- Title Block -->
+  <g transform="translate(320, 100)">
+    <!-- HQ -->
+    <text x="0" y="0" class="title" fill="#F0F0F0" font-size="72" letter-spacing="-2">HQ</text>
+    <!-- Registered symbol -->
+    <circle cx="155" cy="-45" r="14" fill="none" stroke="#F0F0F0" stroke-width="2"/>
+    <text x="155" y="-38" class="body" fill="#F0F0F0" font-size="18" text-anchor="middle">R</text>
+
+    <!-- STARTER KIT -->
+    <text x="0" y="35" class="subtitle" fill="#F0F0F0" font-size="28" letter-spacing="8">STARTER KIT</text>
+
+    <!-- Divider line -->
+    <line x1="0" y1="55" x2="280" y2="55" stroke="#333333" stroke-width="2"/>
+
+    <!-- Tagline -->
+    <text x="0" y="85" class="body" fill="#666666" font-size="14" letter-spacing="2">PERSONAL OS FOR AI WORKERS</text>
+  </g>
+
+  <!-- Status Bar -->
+  <g transform="translate(320, 240)">
+    <text class="mono" fill="#666666" font-size="12" letter-spacing="1">
+      <tspan x="0">STATUS</tspan>
+      <tspan x="55" fill="#F0F0F0">DEPLOYED</tspan>
+      <tspan x="150" fill="#333333">/</tspan>
+      <tspan x="170">WORKERS</tspan>
+      <tspan x="245" fill="#F0F0F0">18</tspan>
+      <tspan x="280" fill="#333333">/</tspan>
+      <tspan x="300">COMMANDS</tspan>
+      <tspan x="395" fill="#F0F0F0">22</tspan>
+      <tspan x="430" fill="#333333">/</tspan>
+      <tspan x="450">KNOWLEDGE</tspan>
+      <tspan x="555" fill="#F0F0F0">5</tspan>
+    </text>
+  </g>
+
+  <!-- Unit ID (bottom right) -->
+  <text x="830" y="280" class="mono" fill="#333333" font-size="10" text-anchor="end" letter-spacing="1">HQ-SK-V2.0</text>
+
+  <!-- Small decorative elements -->
+  <!-- Top status indicator -->
+  <g transform="translate(750, 50)">
+    <circle cx="0" cy="0" r="4" fill="#F0F0F0"/>
+    <text x="12" y="4" class="mono" fill="#666666" font-size="10" letter-spacing="1">ACTIVE</text>
+  </g>
+
+</svg>

package/template/knowledge/Ralph/01-overview.md

@@ -0,0 +1,71 @@
+# Overview: What is Ralph?
+
+## Definition
+
+**Ralph** (formally known as the "Ralph Wiggum Loop") is an orchestrator pattern for autonomous AI coding that manages the context window in a way that avoids compaction and context rot. It's a methodology for running AI coding agents that allows you to ship working code while you sleep.
+
+> "Ralph is really just a mallocing orchestrator that avoids context rot and compaction."
+> — Geoffrey Huntley
+
+## The Core Insight
+
+The breakthrough of Ralph is its simplicity. While the AI industry has been building increasingly complex agent swarms, meshes, and orchestrators, Ralph achieves better results with just a **for loop**.
+
+> "What if I told you that the way to get this to work is with a for loop?"
+> — Matt Pocock
+
+## Why "Ralph Wiggum"?
+
+The name comes from the Simpsons character Ralph Wiggum, known for his comedic simplicity and the famous "I'm in danger!" meme. The name reflects the approach's deceptive simplicity - it looks almost too simple to work, but it does.
+
+## The Problem Ralph Solves
+
+Traditional AI coding approaches suffer from:
+
+1. **Context Rot** - As conversations grow longer, the AI loses track of earlier context
+2. **Compaction** - The context window gets filled with irrelevant information
+3. **Complexity** - Orchestrators and agent swarms add layers of abstraction that introduce failure points
+4. **Human Dependencies** - Many workflows require human intervention, breaking the autonomous loop
+
+Ralph solves these by:
+- Starting fresh for each task (avoiding context rot)
+- Using specifications to focus the context (avoiding compaction)
+- Using a simple loop instead of complex orchestration
+- Removing humans from the loop entirely
+
+## The Vision
+
+> "One of the dreams of coding agents is that you can wake up in the morning to working code that your coding agent has worked through your backlog and has just spit out a whole bunch of code for you to review and it works."
+> — Matt Pocock
+
+Ralph makes this dream a reality by mimicking how real engineers work:
+1. Pick a task
+2. Complete it
+3. Commit it
+4. Repeat
+
+## Economic Impact
+
+Ralph fundamentally changes the economics 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
+
+> "The new world is you run a Ralph loop and then you chill on a beach in Bali."
+> — Geoffrey Huntley
+
+## Key Differentiator
+
+Ralph works in **both directions**:
+
+1. **Forward** - Build software from specifications
+2. **Reverse** - Generate clean room specifications from existing code
+
+> "A lot of people right now are missing the point that Ralph goes forward, meaning you can use it to build software. No, run Ralph in reverse to create a clean room specification."
+> — Geoffrey Huntley
+
+This bidirectional capability enables:
+- New product development (forward)
+- Product cloning/clean room design (reverse)
+- Documentation generation (reverse)
+- Specification refinement (iterative)