create-hq 5.0.0

package/template/modules/modules.yaml

@@ -0,0 +1,59 @@
+# HQ Modules Manifest
+# Declares external modules to sync into your HQ instance
+#
+# Modules allow you to pull in functionality from other repos:
+# - Core HQ updates (workers, commands, knowledge)
+# - Company-specific modules (team workflows, shared knowledge)
+# - Community modules (third-party integrations)
+
+version: "1.0"
+
+modules:
+  # Core HQ module - official updates and improvements
+  - name: hq-core
+    repo: https://github.com/coreyepstein/hq-starter-kit.git
+    branch: main
+    strategy: merge  # merge updates with local changes
+    access: public
+    paths:
+      knowledge/Ralph: knowledge/Ralph
+      knowledge/workers: knowledge/workers
+      .claude/commands: .claude/commands
+
+  # Example: Company shared module
+  # - name: acme-workflows
+  #   repo: https://github.com/acme-corp/hq-module.git
+  #   branch: main
+  #   strategy: link  # symlink for real-time sync
+  #   access: team
+  #   paths:
+  #     knowledge/company: knowledge/acme
+  #     workers/shared: workers/acme
+
+  # Example: Role-specific module
+  # - name: engineering-tools
+  #   repo: https://github.com/acme-corp/engineering-hq.git
+  #   branch: main
+  #   strategy: copy  # one-time copy, no ongoing sync
+  #   access: "role:engineer"
+  #   paths:
+  #     workers/code: workers/engineering
+  #     knowledge/tech-stack: knowledge/tech-stack
+
+# Schema Reference:
+#
+# modules[]:
+#   name: string           # Unique identifier for this module
+#   repo: string           # Git repository URL
+#   branch: string         # Branch to sync from (default: main)
+#   strategy: enum         # Sync strategy:
+#                          #   - link: symlink (real-time, requires local clone)
+#                          #   - merge: git merge (preserves local changes)
+#                          #   - copy: one-time copy (no ongoing sync)
+#   access: string         # Access level for future RBAC:
+#                          #   - public: anyone can use
+#                          #   - team: team members only
+#                          #   - role:X: specific role required (e.g., role:admin)
+#   paths: object          # Source path -> destination path mappings
+#                          # Keys are paths in the source repo
+#                          # Values are paths in your local HQ

package/template/projects/incorporate-workers-into-pure-ralph/prd.json

@@ -0,0 +1,88 @@
+{
+  "project": "incorporate-workers-into-pure-ralph",
+  "goal": "Enhance pure-ralph to select and invoke the appropriate dev-team worker for each task",
+  "success_criteria": "Each task executed by specialist worker with audit trail and optional PRD overrides",
+  "target_repo": "C:/my-hq",
+  "has_ui": false,
+  "features": [
+    {
+      "id": "US-001",
+      "title": "Add worker selection logic to pure-ralph-base.md",
+      "description": "Add instructions for selecting the appropriate dev-team worker for each task based on keywords, files, and PRD hints",
+      "acceptance_criteria": [
+        "prompts/pure-ralph-base.md includes Worker Selection section",
+        "Instructions specify: after picking task, determine best worker",
+        "Selection criteria documented: task keywords, target files, PRD hints",
+        "Lists available dev-team workers with their specialties",
+        "Explains when each worker type applies"
+      ],
+      "files": ["prompts/pure-ralph-base.md"],
+      "passes": true,
+      "notes": "Worker: knowledge-curator. Selection reason: Documentation/prompt update task. Added Worker Selection section with: selection criteria (PRD hints, target files, keywords), table of all 12 dev-team workers with specialties/keywords/file patterns, usage guidelines for when to use each worker, and 4-step selection process."
+    },
+    {
+      "id": "US-002",
+      "title": "Add PRD worker override support",
+      "description": "Document optional worker field in PRD task JSON for manual override of automatic selection",
+      "acceptance_criteria": [
+        "prompts/pure-ralph-base.md documents optional worker field in task JSON",
+        "If worker field present, use that worker instead of auto-selecting",
+        "If worker field absent, Claude selects based on criteria",
+        "Example shown in prompt: worker: backend-dev"
+      ],
+      "files": ["prompts/pure-ralph-base.md"],
+      "passes": true,
+      "notes": "Worker: knowledge-curator. Selection reason: Documentation/prompt update task. Added PRD Task Schema section with full JSON schema showing optional worker field. Documented override behavior (present=use it, absent=auto-select). Added use cases and example overrides including backend-dev."
+    },
+    {
+      "id": "US-003",
+      "title": "Add worker invocation instructions to prompt",
+      "description": "Document how to fully invoke a worker within the loop - loading worker.yaml and following skills",
+      "acceptance_criteria": [
+        "prompts/pure-ralph-base.md includes Worker Invocation section",
+        "Instructions: read worker.yaml from workers/dev-team/{worker}/",
+        "Instructions: follow worker's skills and execution patterns",
+        "Instructions: apply worker's knowledge base if referenced",
+        "Worker context is used for implementation, not just reference"
+      ],
+      "files": ["prompts/pure-ralph-base.md"],
+      "dependsOn": ["US-001"],
+      "passes": true,
+      "notes": "Worker: knowledge-curator. Selection reason: Documentation/prompt update task. Added Worker Invocation section with: 4-step invocation process (load definition, load context, apply instructions, use skills), YAML examples showing context.base and instructions fields, checklist for pre-implementation verification, emphasis that worker context shapes HOW to implement."
+    },
+    {
+      "id": "US-004",
+      "title": "Add worker selection reasoning to task notes",
+      "description": "Specify that task notes must include which worker was selected and why for audit trail",
+      "acceptance_criteria": [
+        "prompts/pure-ralph-base.md specifies notes format includes worker info",
+        "Notes must include: Worker: {worker-id}",
+        "Notes must include: Selection reason: {brief explanation}",
+        "Example provided in prompt"
+      ],
+      "files": ["prompts/pure-ralph-base.md"],
+      "dependsOn": ["US-001"],
+      "passes": true,
+      "notes": "Worker: knowledge-curator. Selection reason: Documentation/prompt update task. Added 'Notes Format (Required)' subsection to PRD Updates with: required format spec (Worker + Selection reason + summary), three concrete examples for different worker types (backend-dev, frontend-dev, knowledge-curator), and separated required vs optional note content."
+    },
+    {
+      "id": "US-005",
+      "title": "Create worker selection reference table",
+      "description": "Add quick reference table mapping keywords and file patterns to recommended workers",
+      "acceptance_criteria": [
+        "prompts/pure-ralph-base.md includes worker reference table",
+        "Table maps: keywords/patterns to recommended worker",
+        "Covers all 12 dev-team workers",
+        "Includes file extension hints (e.g., .tsx to frontend-dev, .sql to database-dev)"
+      ],
+      "files": ["prompts/pure-ralph-base.md"],
+      "passes": true,
+      "notes": "Worker: knowledge-curator. Selection reason: Documentation/prompt update task. Added 'Worker Quick Reference' section with three tables: (1) By File Extension - 17 extension patterns mapped to workers including .tsx to frontend-dev, .sql to database-dev, .test.ts to qa-tester, etc. (2) By Directory Pattern - 12 directory patterns mapped to workers. (3) By Keyword Pattern - 35 keyword patterns mapped to all 12 dev-team workers. Covers architect, backend-dev, frontend-dev, database-dev, qa-tester, infra-dev, motion-designer, code-reviewer, knowledge-curator, project-manager, task-executor, and product-planner."
+    }
+  ],
+  "metadata": {
+    "created_at": "2026-01-26T20:15:00Z",
+    "created_by": "stefan",
+    "purpose": "Integrate dev-team workers into pure-ralph loop"
+  }
+}

package/template/projects/pure-ralph-branch-isolation/README.md

@@ -0,0 +1,114 @@
+# Pure Ralph Branch Isolation
+
+**Goal:** Ensure pure-ralph never commits to main, always uses feature branches, creates PRs on completion, and prevents concurrent execution conflicts.
+
+**Success:** Safe parallel execution of multiple pure-ralph loops on different PRDs without conflicts, with clean PR workflow.
+
+## Overview
+
+Currently pure-ralph commits directly to whatever branch is checked out (usually main). This causes:
+- Messy commit history on main
+- No PR review workflow
+- Conflicts when running multiple loops on same repo
+
+This project adds:
+1. **Automatic feature branch creation** - `feature/{project-name}`
+2. **Main branch protection** - Never commit directly to main
+3. **PR creation on completion** - Ready for review
+4. **Lock file mechanism** - Prevent concurrent runs on same target repo
+5. **Conflict detection** - Warn if another loop is already running
+
+## Quality Gates
+
+- None (documentation/config changes only)
+
+## User Stories
+
+### US-001: Add branch creation to pure-ralph prompt
+**Description:** As a pure-ralph user, I want the loop to automatically create and use a feature branch so that main stays clean.
+
+**Acceptance Criteria:**
+- [ ] `prompts/pure-ralph-base.md` includes "Branch Management" section
+- [ ] On session start: check if on feature branch for this project
+- [ ] If not: create `feature/{project-name}` from main and switch to it
+- [ ] If branch exists: switch to it
+- [ ] All commits go to the feature branch, never main
+
+### US-002: Add main branch protection to prompt
+**Description:** As a pure-ralph user, I want the system to refuse to commit to main so that I don't accidentally pollute the main branch.
+
+**Acceptance Criteria:**
+- [ ] `prompts/pure-ralph-base.md` includes check before commit
+- [ ] If current branch is main/master: ERROR, do not commit
+- [ ] Provide clear error message: "Cannot commit to main. Create feature branch first."
+- [ ] This is a hard block, not a warning
+
+### US-003: Add PR creation on project completion
+**Description:** As a pure-ralph user, I want a PR automatically created when all tasks complete so that changes can be reviewed.
+
+**Acceptance Criteria:**
+- [ ] `prompts/pure-ralph-base.md` includes PR creation step
+- [ ] When all tasks pass: push branch to origin
+- [ ] Create PR using `gh pr create` (if gh CLI available)
+- [ ] PR title: `feat: {project-name} - {goal from PRD}`
+- [ ] PR body: list of completed tasks with notes
+- [ ] If gh not available: output push command and PR URL for manual creation
+
+### US-004: Add lock file mechanism to orchestrator scripts
+**Description:** As a pure-ralph user, I want the system to prevent concurrent runs on the same target repo so that conflicts are avoided.
+
+**Acceptance Criteria:**
+- [ ] `.claude/scripts/pure-ralph-loop.ps1` creates lock file on start
+- [ ] Lock file location: `{target_repo}/.pure-ralph.lock`
+- [ ] Lock file contains: project name, PID, start timestamp
+- [ ] On exit (success or failure): remove lock file
+- [ ] `.claude/scripts/pure-ralph-loop.sh` has same behavior
+
+### US-005: Add conflict detection on loop start
+**Description:** As a pure-ralph user, I want to be warned if another loop is already running on the same repo so that I don't cause conflicts.
+
+**Acceptance Criteria:**
+- [ ] On loop start: check for existing `.pure-ralph.lock` in target repo
+- [ ] If lock exists: read contents, show warning with project name and duration
+- [ ] Prompt user: "Another pure-ralph is running on this repo. Continue anyway? (y/N)"
+- [ ] Default to N (abort)
+- [ ] If user chooses to continue: proceed but log warning
+
+### US-006: Update pure-ralph prompt with conflict awareness
+**Description:** As a pure-ralph session, I need to be aware of potential conflicts so that I can handle them gracefully.
+
+**Acceptance Criteria:**
+- [ ] `prompts/pure-ralph-base.md` mentions checking for lock file
+- [ ] If lock file found during session: warn and check if other process still running
+- [ ] If lock is stale (process dead): safe to remove and continue
+- [ ] Add learned pattern about conflict handling
+
+### US-007: Document branch workflow in knowledge base
+**Description:** As an HQ user, I want documentation on the branch workflow so that I understand how pure-ralph manages git.
+
+**Acceptance Criteria:**
+- [ ] `knowledge/pure-ralph/branch-workflow.md` created
+- [ ] Documents: automatic branch creation
+- [ ] Documents: PR creation process
+- [ ] Documents: lock file mechanism
+- [ ] Documents: handling concurrent execution attempts
+- [ ] Documents: manual recovery if lock file becomes stale
+
+## Non-Goals
+
+- CI/CD integration (that's separate infrastructure)
+- Automatic merge after PR approval
+- Branch naming customization (use standard `feature/{project}` pattern)
+- Multiple PRDs on same branch (one branch per project)
+
+## Technical Considerations
+
+- Requires `gh` CLI for automatic PR creation (graceful fallback if missing)
+- Lock file must be cleaned up even on script crash (trap signals)
+- Branch name derived from project name in PRD
+- Must handle case where branch already exists from previous partial run
+
+## Open Questions
+
+- Should we support custom branch prefixes (e.g., `fix/` vs `feature/`)?
+- Should lock file include expected completion time for better UX?

package/template/projects/pure-ralph-branch-isolation/prd.json

@@ -0,0 +1,123 @@
+{
+  "project": "pure-ralph-branch-isolation",
+  "goal": "Ensure pure-ralph never commits to main, always uses feature branches, creates PRs on completion, and prevents concurrent execution conflicts",
+  "success_criteria": "Safe parallel execution of multiple pure-ralph loops on different PRDs without conflicts, with clean PR workflow",
+  "target_repo": "C:/my-hq",
+  "has_ui": false,
+  "features": [
+    {
+      "id": "US-001",
+      "title": "Add branch creation to pure-ralph prompt",
+      "description": "Automatically create and use feature branch so main stays clean",
+      "acceptance_criteria": [
+        "prompts/pure-ralph-base.md includes Branch Management section",
+        "On session start: check if on feature branch for this project",
+        "If not on correct branch: create feature/{project-name} from main and switch to it",
+        "If branch exists: switch to it",
+        "All commits go to the feature branch, never main"
+      ],
+      "files": ["prompts/pure-ralph-base.md"],
+      "passes": true,
+      "notes": "Added Branch Management section to pure-ralph-base.md. Section includes: session start instructions for checking/creating feature branch, branch rules (never commit to main, naming convention, branch from main), and updated job steps to include BRANCH as step 1. Also added learned pattern about verifying branch first."
+    },
+    {
+      "id": "US-002",
+      "title": "Add main branch protection to prompt",
+      "description": "Refuse to commit to main/master branch",
+      "acceptance_criteria": [
+        "prompts/pure-ralph-base.md includes check before commit",
+        "If current branch is main/master: ERROR, do not commit",
+        "Provide clear error message: Cannot commit to main",
+        "This is a hard block, not a warning"
+      ],
+      "files": ["prompts/pure-ralph-base.md"],
+      "dependsOn": ["US-001"],
+      "passes": true,
+      "notes": "Added 'Commit Safety' section with hard block for main/master commits. Includes: bash check script, clear ERROR message, recovery steps (stash, switch branch, pop, commit). Added learned pattern about verifying branch before every commit."
+    },
+    {
+      "id": "US-003",
+      "title": "Add PR creation on project completion",
+      "description": "Automatically create PR when all tasks complete",
+      "acceptance_criteria": [
+        "prompts/pure-ralph-base.md includes PR creation step",
+        "When all tasks pass: push branch to origin",
+        "Create PR using gh pr create if available",
+        "PR title format: feat: {project-name}",
+        "PR body: list of completed tasks with notes",
+        "If gh not available: output manual instructions"
+      ],
+      "files": ["prompts/pure-ralph-base.md"],
+      "dependsOn": ["US-001"],
+      "passes": true,
+      "notes": "Added 'PR Creation (When All Tasks Complete)' section with: push to origin instructions, gh pr create command with title format 'feat: {project-name}', PR body format including summary from PRD goal and list of completed tasks with notes, manual instructions fallback if gh CLI not available, updated step 7 in 'Your Job' to include PR creation check when all tasks complete."
+    },
+    {
+      "id": "US-004",
+      "title": "Add lock file mechanism to orchestrator scripts",
+      "description": "Prevent concurrent runs on same target repo using lock file",
+      "acceptance_criteria": [
+        ".claude/scripts/pure-ralph-loop.ps1 creates lock file on start",
+        "Lock file location: {target_repo}/.pure-ralph.lock",
+        "Lock file contains: project name, PID, start timestamp",
+        "On exit (success or failure): remove lock file",
+        ".claude/scripts/pure-ralph-loop.sh has same behavior"
+      ],
+      "files": [".claude/scripts/pure-ralph-loop.ps1", ".claude/scripts/pure-ralph-loop.sh"],
+      "passes": true,
+      "notes": "Added lock file mechanism to both scripts. PowerShell: Create-LockFile and Remove-LockFile functions with try/finally for cleanup. Bash: create_lock_file and remove_lock_file functions with EXIT trap for cleanup. Lock file at {target_repo}/.pure-ralph.lock contains JSON with project name, PID, and ISO timestamp."
+    },
+    {
+      "id": "US-005",
+      "title": "Add conflict detection on loop start",
+      "description": "Warn if another loop is already running on same repo",
+      "acceptance_criteria": [
+        "On loop start: check for existing .pure-ralph.lock in target repo",
+        "If lock exists: read contents, show warning with project name and duration",
+        "Prompt user: Another pure-ralph is running. Continue anyway? (y/N)",
+        "Default to N (abort)",
+        "If user chooses to continue: proceed but log warning"
+      ],
+      "files": [".claude/scripts/pure-ralph-loop.ps1", ".claude/scripts/pure-ralph-loop.sh"],
+      "dependsOn": ["US-004"],
+      "passes": true,
+      "notes": "Added Check-ExistingLock function to PowerShell and check_existing_lock function to Bash. Both: (1) parse lock file JSON for project/PID/timestamp, (2) calculate and display duration, (3) check if process is still running (shows 'RUNNING' or 'stale lock'), (4) prompt user with y/N defaulting to abort, (5) log warning if user continues. Called before Create-LockFile in both scripts."
+    },
+    {
+      "id": "US-006",
+      "title": "Update pure-ralph prompt with conflict awareness",
+      "description": "Make Claude sessions aware of potential conflicts",
+      "acceptance_criteria": [
+        "prompts/pure-ralph-base.md mentions checking for lock file",
+        "If lock file found during session: warn and check if process still running",
+        "If lock is stale (process dead): safe to remove and continue",
+        "Add learned pattern about conflict handling"
+      ],
+      "files": ["prompts/pure-ralph-base.md"],
+      "dependsOn": ["US-004"],
+      "passes": true,
+      "notes": "Added 'Conflict Awareness' section with: lock file location, session start check instructions, handling logic for lock file detection (read contents, check PID running status), stale lock removal instructions, important notes clarifying orchestrator vs Claude responsibilities. Added learned pattern '[Conflict] Stale Lock Detection' for distinguishing active vs stale locks."
+    },
+    {
+      "id": "US-007",
+      "title": "Document branch workflow in knowledge base",
+      "description": "Create documentation on the branch workflow",
+      "acceptance_criteria": [
+        "knowledge/pure-ralph/branch-workflow.md created",
+        "Documents: automatic branch creation",
+        "Documents: PR creation process",
+        "Documents: lock file mechanism",
+        "Documents: handling concurrent execution attempts",
+        "Documents: manual recovery if lock file becomes stale"
+      ],
+      "files": ["knowledge/pure-ralph/branch-workflow.md"],
+      "passes": true,
+      "notes": "Created comprehensive branch-workflow.md documentation covering: (1) Automatic branch creation with naming convention and session start process, (2) PR creation process including gh CLI commands and manual fallback, (3) Lock file mechanism with location, contents, and lifecycle, (4) Concurrent execution handling with detection and user prompts, (5) Manual recovery for stale locks with verification steps for both bash and PowerShell. Includes summary diagram and related files reference."
+    }
+  ],
+  "metadata": {
+    "created_at": "2026-01-26T20:30:00Z",
+    "created_by": "stefan",
+    "purpose": "Add branch isolation and conflict prevention to pure-ralph"
+  }
+}

package/template/projects/purist-ralph-loop/README.md

@@ -0,0 +1,148 @@
+# Purist Ralph Loop
+
+**Goal:** Create an external terminal orchestrator that runs a canonical Ralph loop with fresh context per task and self-improving prompts.
+
+**Success:** `/pure-ralph my-project` opens terminal, executes PRD tasks autonomously, completes with zero intervention, and evolves its base prompt with learnings.
+
+## Overview
+
+The current `/run-project` command runs the orchestrator inside Claude's session, causing context accumulation and eventual compression. This project creates a true external orchestrator:
+
+1. **External loop** - Bash/PowerShell `while` loop runs outside Claude
+2. **Fresh context per task** - Each `claude -p` invocation starts clean
+3. **Self-modifying** - Loop can update its own prompts and CLAUDE.md
+4. **PRD as source of truth** - `passes` field = state, `notes` field = context
+5. **Cross-platform** - Works on Windows, Mac, Linux with remembered terminal preference
+
+## Quality Gates
+
+- None for MVP (shell scripts + markdown)
+- Task verification: `passes: true` + `notes` populated + git commit exists
+
+## User Stories
+
+### US-001: Create base prompt file
+**Description:** As a user, I want a low-fi base prompt that instructs Claude on Ralph principles so each spawned session knows the methodology.
+
+**Acceptance Criteria:**
+- [ ] `prompts/pure-ralph-base.md` exists in my-hq
+- [ ] Contains Ralph principles: one task, fresh context, update PRD, commit
+- [ ] Includes instructions for self-modification (how to update this file)
+- [ ] Under 500 lines (minimal, focused)
+
+**Files:** `prompts/pure-ralph-base.md`
+
+---
+
+### US-002: Create terminal settings mechanism
+**Description:** As a user, I want to set my preferred terminal once and have it remembered for subsequent runs.
+
+**Acceptance Criteria:**
+- [ ] `settings/pure-ralph.json` stores terminal preference
+- [ ] First run prompts user to choose terminal type
+- [ ] Supports: PowerShell (Windows), Windows Terminal, bash (Mac/Linux), iTerm (Mac)
+- [ ] Setting persists across sessions
+
+**Files:** `settings/pure-ralph.json`
+
+---
+
+### US-003: Create PowerShell loop script
+**Description:** As a Windows user, I want a PowerShell script that runs the canonical Ralph loop.
+
+**Acceptance Criteria:**
+- [ ] `.claude/scripts/pure-ralph-loop.ps1` exists
+- [ ] Reads PRD path and target repo as arguments
+- [ ] Spawns fresh `claude -p` per task with base prompt
+- [ ] Updates PRD `passes` and `notes` fields
+- [ ] Creates git commit per completed task
+- [ ] Logs to `workspace/orchestrator/{project}/pure-ralph.log`
+
+**Files:** `.claude/scripts/pure-ralph-loop.ps1`
+
+---
+
+### US-004: Create bash loop script
+**Description:** As a Mac/Linux user, I want a bash script that runs the canonical Ralph loop.
+
+**Acceptance Criteria:**
+- [ ] `.claude/scripts/pure-ralph-loop.sh` exists
+- [ ] Same functionality as PowerShell version
+- [ ] Works on macOS and Linux
+- [ ] Executable permissions set
+
+**Files:** `.claude/scripts/pure-ralph-loop.sh`
+
+---
+
+### US-005: Create /pure-ralph slash command
+**Description:** As a user, I want to run `/pure-ralph my-project` to launch the external orchestrator.
+
+**Acceptance Criteria:**
+- [ ] `.claude/commands/pure-ralph.md` exists
+- [ ] Accepts project name as argument
+- [ ] Prompts for target repo if not in PRD metadata
+- [ ] Checks terminal preference, prompts if not set
+- [ ] Spawns appropriate terminal with loop script
+- [ ] Provides feedback on how to monitor progress
+
+**Files:** `.claude/commands/pure-ralph.md`
+
+---
+
+### US-006: Add self-modification capability
+**Description:** As a user, I want the loop to improve its own prompts based on learnings so it gets better over time.
+
+**Acceptance Criteria:**
+- [ ] Base prompt includes section for "Learned Patterns"
+- [ ] Each task completion can append to learned patterns
+- [ ] CLAUDE.md gets updated with cross-project learnings
+- [ ] Changes are committed with clear messages
+
+**Files:** `prompts/pure-ralph-base.md`, `.claude/CLAUDE.md`
+
+---
+
+### US-007: Add learnings aggregation
+**Description:** As a user, I want learnings from completed projects aggregated into the knowledge base.
+
+**Acceptance Criteria:**
+- [ ] On project completion, learnings extracted from all task notes
+- [ ] Written to `knowledge/pure-ralph/learnings.md`
+- [ ] Patterns categorized (workflow, technical, gotchas)
+- [ ] Base prompt updated with high-value patterns
+
+**Files:** `knowledge/pure-ralph/learnings.md`, `prompts/pure-ralph-base.md`
+
+---
+
+### US-008: Add beads integration
+**Description:** As a user, I want the loop to sync with beads for task tracking visibility.
+
+**Acceptance Criteria:**
+- [ ] Loop checks if `bd` CLI is available
+- [ ] If available, syncs PRD tasks to beads on start
+- [ ] Updates bead status as tasks complete
+- [ ] Graceful fallback if beads not installed
+
+**Files:** `.claude/scripts/pure-ralph-loop.ps1`, `.claude/scripts/pure-ralph-loop.sh`
+
+## Non-Goals
+
+- GUI interface (this is CLI-focused)
+- Parallel task execution (sequential is intentional for Ralph purity)
+- Support for non-Claude AI providers
+- Real-time streaming output (batch per task is fine)
+
+## Technical Considerations
+
+- Cross-platform terminal detection is tricky - use environment variables and fallbacks
+- Self-modification requires careful prompting to avoid runaway changes
+- Git commits should be atomic per task, not batched
+- Base prompt should stay small to leave room for task context
+
+## Open Questions
+
+- Should there be a `--dry-run` flag to preview without executing?
+- Max iterations safety limit?
+- How to handle task failures - retry, skip, or pause?