create-hq 5.0.0

package/template/.claude/commands/setup.md

@@ -0,0 +1,381 @@
+---
+description: Interactive setup wizard for HQ Starter Kit
+allowed-tools: Read, Write, Edit, AskUserQuestion, Glob, Bash
+visibility: public
+---
+
+# HQ Setup Wizard
+
+Welcome! This wizard will configure your personal HQ.
+
+## Phase 0: Dependencies
+
+Check and guide installation of key dependencies before proceeding.
+
+### Required
+Run these checks silently. Only prompt user if something is missing.
+
+**qmd** (HQ search - semantic + full-text):
+```bash
+which qmd
+```
+If missing, show:
+```
+qmd not found. HQ uses qmd for semantic search across knowledge bases.
+
+Install: cargo install qmd
+  OR: brew install tobi/tap/qmd
+
+After install, index HQ: qmd index .
+```
+
+**Claude Code CLI**:
+```bash
+which claude
+```
+If missing, show:
+```
+Claude Code CLI not found. Required to run HQ.
+
+Install: npm install -g @anthropic-ai/claude-code
+```
+
+### Optional (check based on starter selection)
+
+**gh CLI** (for code workers):
+```bash
+which gh
+```
+If missing and Code Worker selected:
+```
+gh CLI recommended for code workers (PRs, issues).
+Install: brew install gh
+```
+
+### Post-install: Index HQ
+If qmd was just installed or index doesn't exist:
+```bash
+qmd index .
+```
+
+---
+
+## Context to Load
+
+1. Read `starter-projects/` to understand available options
+2. Read `knowledge/public/workers/templates/` for worker patterns
+
+## Phase 1: Identity
+
+Ask these questions one at a time. Wait for answers before proceeding.
+
+1. **What's your name or handle?** (used for folder naming)
+2. **What do you do?** (1-2 sentences about your roles/work)
+3. **What domains do you focus on?** (e.g., tech, business, creative, health)
+4. **Company/context name?** (default: "personal" - used for organizing your settings/knowledge)
+
+## Phase 2: Starter Project Selection
+
+Present these options:
+
+```
+Choose your starter project(s):
+
+1. PERSONAL ASSISTANT
+   - Daily email digest
+   - Task scanning
+   - Calendar awareness
+   Best for: Productivity-focused users
+
+2. SOCIAL MEDIA WORKER
+   - Content drafting (X, LinkedIn)
+   - Voice consistency
+   - Post scheduling queue
+   Best for: Personal brand builders
+
+3. CODE WORKER
+   - Ralph loop implementation
+   - Back pressure verification
+   - PRD-driven development
+   Best for: Developers shipping autonomously
+
+Enter numbers (e.g., "1,3" or "2" or "all"):
+```
+
+## Phase 3: Customization
+
+Based on selection, ask relevant questions:
+
+### If Personal Assistant selected:
+- How many email accounts do you manage?
+- Preferred digest time? (morning/evening)
+
+### If Social Media selected:
+- Which platforms? (X, LinkedIn, both)
+- Posting voice: professional / casual / direct
+- Content topics (3-5 keywords)
+
+### If Code Worker selected:
+- Primary tech stack? (Node/TypeScript, Python, Go, etc.)
+- Project name for first PRD?
+- Verification commands? (default: `npm run typecheck && npm run build`)
+
+## Phase 4: Generate Files
+
+### Always create company structure:
+
+```
+companies/{company}/
+├── settings/      # API credentials (gitignored)
+├── data/          # Exports, reports
+└── knowledge/
+    ├── profile.md
+    └── voice-style.md
+```
+
+Create directories with `mkdir -p companies/{company}/settings companies/{company}/data companies/{company}/knowledge`
+
+**companies/{company}/knowledge/profile.md:**
+```markdown
+# {Name}'s Profile
+
+## About
+{description from Phase 1, Q2}
+
+## Focus Areas
+{domains from Phase 1, Q3}
+
+## Preferences
+- Communication style: [direct/detailed/casual]
+- Working hours: [your timezone/schedule]
+- Autonomy level: [how much should agents do without asking?]
+
+## Context Notes
+[Add notes agents should know when working for you]
+```
+
+**companies/{company}/knowledge/voice-style.md:**
+```markdown
+# {Name}'s Voice Style
+
+## Tone
+{based on answers - professional/casual/direct}
+
+## Guidelines
+- [Customize as you use HQ]
+- [Add patterns you like]
+- [Note things to avoid]
+
+## Example Phrases
+- [Add phrases that sound like you]
+```
+
+### Based on selection:
+
+**If Personal Assistant:**
+1. Copy `starter-projects/personal-assistant/` to `projects/personal-assistant/`
+2. Create `workers/private/email-digest/worker.yaml`:
+```yaml
+worker:
+  id: email-digest
+  name: "Email Digest"
+  type: AssistantWorker
+  version: "1.0"
+
+identity:
+  voice_guide: companies/{company}/knowledge/voice-style.md
+
+execution:
+  mode: scheduled
+  schedule: "0 {hour} * * *"  # from digest time preference
+  max_runtime: 10m
+
+context:
+  base:
+    - companies/{company}/knowledge/profile.md
+    - companies/{company}/settings/email-accounts.json
+
+verification:
+  post_execute:
+    - check: digest_generated
+  approval_required: false
+
+tasks:
+  source: workers/private/email-digest/prd.json
+  one_at_a_time: true
+
+output:
+  destination: workspace/digests/
+  format: markdown
+  naming: "{date}-digest.md"
+
+instructions: |
+  Generate email digest following the Presidential Daily Brief format.
+  Classify emails: urgent | actionable | fyi | archive
+  Focus on what needs attention, not comprehensive summary.
+```
+3. Create `companies/{company}/settings/email-accounts.json.example`:
+```json
+{
+  "accounts": [
+    {
+      "name": "Primary",
+      "email": "you@example.com",
+      "provider": "gmail|outlook|imap"
+    }
+  ]
+}
+```
+4. Add to `workers/registry.yaml`
+
+**If Social Media:**
+1. Copy `starter-projects/social-media/` to `projects/social-presence/`
+2. Create `workers/private/{platform}-{name}/worker.yaml`:
+```yaml
+worker:
+  id: {platform}-{name}
+  name: "{Platform} Content"
+  type: SocialWorker
+  version: "1.0"
+
+identity:
+  voice_guide: companies/{company}/knowledge/voice-style.md
+
+execution:
+  mode: on-demand
+  max_runtime: 15m
+
+context:
+  base:
+    - companies/{company}/knowledge/profile.md
+    - companies/{company}/knowledge/voice-style.md
+  dynamic:
+    - workspace/content-ideas/
+
+verification:
+  post_execute:
+    - check: character_count
+      max: 280  # for X
+    - check: voice_consistency
+  approval_required: true
+
+tasks:
+  source: workers/private/{platform}-{name}/queue.json
+  one_at_a_time: true
+
+output:
+  destination: workspace/social-drafts/
+  format: markdown
+  naming: "{date}-{topic}.md"
+
+instructions: |
+  Draft content matching voice style guide.
+  Always verify character limits before marking complete.
+  Never post without human approval.
+```
+3. Create `workers/private/{platform}-{name}/queue.json`:
+```json
+{
+  "worker": "{platform}-{name}",
+  "queue": []
+}
+```
+4. Add to `workers/registry.yaml`
+
+**If Code Worker:**
+1. Copy `starter-projects/code-worker/` to `projects/{project-name}/`
+2. Create `workers/private/{project-name}-coder/worker.yaml`:
+```yaml
+worker:
+  id: {project-name}-coder
+  name: "{Project} Code Worker"
+  type: CodeWorker
+  version: "1.0"
+
+execution:
+  mode: on-demand
+  max_runtime: 30m
+
+context:
+  base:
+    - knowledge/public/Ralph/
+    - projects/{project-name}/prd.json
+  dynamic:
+    - "{repo-path}/"
+  exclude:
+    - node_modules/
+    - "*.log"
+    - dist/
+
+verification:
+  post_execute:
+    - check: typecheck
+      command: "{verify-command}"
+      must_pass: true
+    - check: build
+      command: "{build-command}"
+      must_pass: true
+  approval_required: false
+
+tasks:
+  source: projects/{project-name}/prd.json
+  format: prd
+  one_at_a_time: true
+
+output:
+  format: git_commit
+
+instructions: |
+  Implement features following Ralph methodology.
+  Run back pressure checks after each change.
+  Commit with format: feat({feature-id}): {description}
+  Write checkpoint after each completed feature.
+```
+3. Add to `workers/registry.yaml`
+
+### Update Registry
+
+Add entries to `workers/registry.yaml`:
+```yaml
+workers:
+  - id: {worker-id}
+    path: workers/private/{worker-id}/
+    type: {WorkerType}
+    visibility: private
+    status: active
+    description: "{1-sentence description}"
+```
+
+## Phase 5: Summary
+
+Output:
+```
+HQ Setup Complete!
+
+Created:
+- Company context: companies/{company}/
+  - knowledge/profile.md
+  - knowledge/voice-style.md
+  - settings/ (for credentials)
+  - data/ (for exports)
+- Workers: {list with paths}
+- Projects: {list with paths}
+
+Next steps:
+1. Review and customize companies/{company}/knowledge/profile.md
+2. {If email} Copy settings/email-accounts.json.example → email-accounts.json and add credentials
+3. Run `/search <topic>` to find relevant HQ knowledge
+4. Run `/nexttask` to see available work
+5. Run `/run {worker-id}` to execute a worker
+6. Run `/newworker` when you want to add more workers
+
+Happy building!
+```
+
+## Rules
+
+- Ask questions one at a time (avoid overwhelming)
+- Use defaults when user says "skip" or "default"
+- Always validate paths before writing
+- Never overwrite existing files without asking
+- Create parent directories as needed

package/template/.claude/scripts/pure-ralph-loop.ps1

@@ -0,0 +1,312 @@
+<#
+.SYNOPSIS
+    Pure Ralph Loop - Canonical external orchestrator
+
+.DESCRIPTION
+    Runs the SAME prompt in a loop. Claude picks the task.
+    Fresh context per iteration. Loop until all tasks pass.
+
+.PARAMETER PrdPath
+    Full path to the PRD JSON file
+
+.PARAMETER TargetRepo
+    Full path to the target repository
+
+.PARAMETER Manual
+    Run in manual mode (interactive TUI, manually close windows)
+    Default is auto mode (uses -p flag, auto-exits)
+
+.EXAMPLE
+    # Auto mode (default) - fully autonomous
+    .\pure-ralph-loop.ps1 -PrdPath "C:/my-hq/projects/my-project/prd.json" -TargetRepo "C:/my-hq"
+
+    # Manual mode - see chain of thought, close windows manually
+    .\pure-ralph-loop.ps1 -PrdPath "C:/my-hq/projects/my-project/prd.json" -TargetRepo "C:/my-hq" -Manual
+#>
+
+param(
+    [Parameter(Mandatory=$true)]
+    [string]$PrdPath,
+
+    [Parameter(Mandatory=$true)]
+    [string]$TargetRepo,
+
+    [string]$HqPath = "C:/my-hq",
+
+    [switch]$Manual
+)
+
+# ============================================================================
+# Configuration
+# ============================================================================
+
+$BasePromptPath = Join-Path $HqPath "prompts/pure-ralph-base.md"
+$ProjectName = (Split-Path (Split-Path $PrdPath -Parent) -Leaf)
+$LogDir = Join-Path $HqPath "workspace/orchestrator/$ProjectName"
+$LogFile = Join-Path $LogDir "pure-ralph.log"
+$LockFile = Join-Path $TargetRepo ".pure-ralph.lock"
+
+# Create log directory
+New-Item -ItemType Directory -Path $LogDir -Force | Out-Null
+
+# ============================================================================
+# Functions
+# ============================================================================
+
+function Write-Log {
+    param([string]$Message, [string]$Level = "INFO")
+    $timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
+    $entry = "[$timestamp] [$Level] $Message"
+    Add-Content -Path $LogFile -Value $entry
+
+    switch ($Level) {
+        "ERROR"   { Write-Host $entry -ForegroundColor Red }
+        "WARN"    { Write-Host $entry -ForegroundColor Yellow }
+        "SUCCESS" { Write-Host $entry -ForegroundColor Green }
+        default   { Write-Host $entry }
+    }
+}
+
+function Create-LockFile {
+    $lockContent = @{
+        project = $ProjectName
+        pid = $PID
+        started_at = (Get-Date -Format "o")
+    } | ConvertTo-Json
+    $lockContent | Out-File -FilePath $LockFile -Encoding utf8
+    Write-Log "Lock file created: $LockFile"
+}
+
+function Remove-LockFile {
+    if (Test-Path $LockFile) {
+        Remove-Item -Path $LockFile -Force
+        Write-Log "Lock file removed: $LockFile"
+    }
+}
+
+function Check-ExistingLock {
+    if (Test-Path $LockFile) {
+        try {
+            $lockContent = Get-Content $LockFile -Raw | ConvertFrom-Json
+            $lockProject = $lockContent.project
+            $lockPid = $lockContent.pid
+            $lockStarted = [DateTime]::Parse($lockContent.started_at)
+            $duration = (Get-Date) - $lockStarted
+            $durationStr = "{0:hh\:mm\:ss}" -f $duration
+
+            Write-Host ""
+            Write-Host "=== WARNING: Lock File Detected ===" -ForegroundColor Yellow
+            Write-Host "Another pure-ralph loop may be running on this repo." -ForegroundColor Yellow
+            Write-Host ""
+            Write-Host "  Project: $lockProject" -ForegroundColor Gray
+            Write-Host "  PID: $lockPid" -ForegroundColor Gray
+            Write-Host "  Started: $($lockContent.started_at)" -ForegroundColor Gray
+            Write-Host "  Duration: $durationStr" -ForegroundColor Gray
+            Write-Host ""
+
+            # Check if process is still running
+            $processRunning = $false
+            try {
+                $proc = Get-Process -Id $lockPid -ErrorAction SilentlyContinue
+                if ($proc) {
+                    $processRunning = $true
+                    Write-Host "  Process Status: RUNNING" -ForegroundColor Red
+                } else {
+                    Write-Host "  Process Status: NOT RUNNING (stale lock)" -ForegroundColor Yellow
+                }
+            } catch {
+                Write-Host "  Process Status: NOT RUNNING (stale lock)" -ForegroundColor Yellow
+            }
+            Write-Host ""
+
+            Write-Log "Existing lock file found for project '$lockProject' (PID: $lockPid, Duration: $durationStr)" "WARN"
+
+            # Prompt user
+            $response = Read-Host "Another pure-ralph is running. Continue anyway? (y/N)"
+            if ($response -match "^[Yy]$") {
+                Write-Log "User chose to continue despite existing lock" "WARN"
+                Write-Host "Continuing... (existing lock will be overwritten)" -ForegroundColor Yellow
+                return $true
+            } else {
+                Write-Log "User chose to abort due to existing lock" "INFO"
+                Write-Host "Aborting." -ForegroundColor Red
+                return $false
+            }
+        } catch {
+            Write-Log "Could not parse lock file: $_" "WARN"
+            # If we can't parse the lock file, ask the user
+            $response = Read-Host "Lock file exists but couldn't be read. Continue anyway? (y/N)"
+            if ($response -match "^[Yy]$") {
+                return $true
+            } else {
+                return $false
+            }
+        }
+    }
+    return $true
+}
+
+function Get-TaskProgress {
+    $prd = Get-Content $PrdPath -Raw | ConvertFrom-Json
+    $total = $prd.features.Count
+    $complete = ($prd.features | Where-Object { $_.passes -eq $true }).Count
+    return @{ Total = $total; Complete = $complete; Remaining = $total - $complete }
+}
+
+function Build-Prompt {
+    param([bool]$IsManual)
+
+    # Read base prompt and substitute only PRD_PATH and TARGET_REPO
+    $prompt = Get-Content $BasePromptPath -Raw
+    $prompt = $prompt -replace '\{\{PRD_PATH\}\}', $PrdPath
+    $prompt = $prompt -replace '\{\{TARGET_REPO\}\}', $TargetRepo
+
+    # In manual mode, add instruction for user to close window
+    if ($IsManual) {
+        $prompt += @"
+
+
+---
+
+## IMPORTANT: Manual Mode
+
+When you have completed the task and updated the PRD, output this message:
+
+```
+TASK COMPLETE - Please close this window to continue to the next task.
+```
+
+Do NOT exit automatically. Wait for the user to close the window.
+"@
+    }
+
+    return $prompt
+}
+
+# ============================================================================
+# Main Loop
+# ============================================================================
+
+$modeLabel = if ($Manual) { "MANUAL (interactive)" } else { "AUTO (autonomous)" }
+
+Write-Host ""
+Write-Host "=== Pure Ralph Loop ===" -ForegroundColor Cyan
+Write-Host "PRD: $PrdPath" -ForegroundColor Gray
+Write-Host "Target: $TargetRepo" -ForegroundColor Gray
+Write-Host "Log: $LogFile" -ForegroundColor Gray
+Write-Host "Mode: $modeLabel" -ForegroundColor $(if ($Manual) { "Yellow" } else { "Green" })
+Write-Host ""
+Write-Host "Same prompt every iteration. Claude picks the task." -ForegroundColor Yellow
+Write-Host ""
+
+Write-Log "Pure Ralph Loop started"
+Write-Log "PRD: $PrdPath"
+Write-Log "Target: $TargetRepo"
+Write-Log "Mode: $modeLabel"
+
+# Check for existing lock file (conflict detection)
+if (-not (Check-ExistingLock)) {
+    exit 1
+}
+
+# Create lock file to prevent concurrent execution
+Create-LockFile
+
+# Ensure lock file is removed on exit (success or failure)
+try {
+    # Build the prompt ONCE (only PRD_PATH and TARGET_REPO substituted)
+    $prompt = Build-Prompt -IsManual $Manual
+    $promptFile = Join-Path $LogDir "current-prompt.md"
+    $prompt | Out-File -FilePath $promptFile -Encoding utf8
+
+    Write-Log "Prompt built and saved to $promptFile"
+
+    $iteration = 0
+    $maxIterations = 50
+
+    while ($iteration -lt $maxIterations) {
+    $iteration++
+
+    $progress = Get-TaskProgress
+
+    Write-Host ""
+    Write-Host "--- Iteration $iteration ---" -ForegroundColor Cyan
+    Write-Log "Iteration $iteration - Progress: $($progress.Complete)/$($progress.Total)"
+
+    # Check if all done
+    if ($progress.Remaining -eq 0) {
+        Write-Host ""
+        Write-Host "=== ALL TASKS COMPLETE ===" -ForegroundColor Green
+        Write-Log "All tasks complete!" "SUCCESS"
+        break
+    }
+
+    Write-Host "Tasks remaining: $($progress.Remaining)" -ForegroundColor Yellow
+    Write-Host ""
+
+    if ($Manual) {
+        Write-Host "Opening Claude in new window (MANUAL MODE)..." -ForegroundColor Cyan
+        Write-Host ">>> Close the window when task completes to continue <<<" -ForegroundColor Yellow
+    } else {
+        Write-Host "Opening Claude in new window (AUTO MODE)..." -ForegroundColor Cyan
+        Write-Host ">>> Window will close automatically when done <<<" -ForegroundColor Green
+    }
+    Write-Host ""
+
+    Write-Log "Spawning Claude session"
+
+    # Build the Claude command based on mode
+    if ($Manual) {
+        # Manual mode: interactive TUI, user closes window
+        $claudeCmd = @"
+cd '$TargetRepo'
+Write-Host '=== Pure Ralph Session (MANUAL MODE) ===' -ForegroundColor Cyan
+Write-Host 'Reading PRD, picking task, implementing...' -ForegroundColor Gray
+Write-Host 'Close this window when done to continue the loop.' -ForegroundColor Yellow
+Write-Host ''
+claude --permission-mode bypassPermissions (Get-Content '$promptFile' -Raw)
+"@
+    } else {
+        # Auto mode: -p flag, auto-exits
+        $claudeCmd = @"
+cd '$TargetRepo'
+Write-Host '=== Pure Ralph Session (AUTO MODE) ===' -ForegroundColor Cyan
+Write-Host 'Reading PRD, picking task, implementing...' -ForegroundColor Gray
+Write-Host ''
+claude -p --permission-mode bypassPermissions (Get-Content '$promptFile' -Raw)
+Write-Host ''
+Write-Host 'Session complete. Window closing in 3 seconds...' -ForegroundColor Green
+Start-Sleep -Seconds 3
+exit
+"@
+    }
+
+    # Start new window and WAIT for it to close
+    $proc = Start-Process powershell -ArgumentList "-Command", $claudeCmd -PassThru
+
+    Write-Host "Waiting for Claude session (PID: $($proc.Id))..." -ForegroundColor Gray
+    $proc.WaitForExit()
+
+    Write-Log "Claude session ended"
+
+    # Brief pause before next iteration
+    Start-Sleep -Seconds 2
+}
+
+    if ($iteration -ge $maxIterations) {
+        Write-Log "Safety limit reached ($maxIterations iterations)" "WARN"
+    }
+
+    # Final summary
+    $progress = Get-TaskProgress
+    Write-Host ""
+    Write-Host "=== Final Summary ===" -ForegroundColor Cyan
+    Write-Host "Completed: $($progress.Complete)/$($progress.Total) tasks" -ForegroundColor $(if ($progress.Remaining -eq 0) { "Green" } else { "Yellow" })
+    Write-Host "Log: $LogFile" -ForegroundColor Gray
+
+    Write-Log "Loop ended. Final: $($progress.Complete)/$($progress.Total) complete"
+}
+finally {
+    # Always remove lock file on exit (success or failure)
+    Remove-LockFile
+}