create-hq 5.0.0

package/template/.claude/commands/run-project.md

@@ -0,0 +1,348 @@
+---
+description: Run a project through the Ralph loop - orchestrator for multi-task execution
+allowed-tools: Task, Read, Write, Glob, Grep, Bash, AskUserQuestion
+argument-hint: [project-name] or [--resume project] or [--status]
+visibility: public
+---
+
+# /run-project - Project Orchestrator Loop
+
+Ralph loop with fresh context per task. The orchestrator is an ultra-lean state machine — it delegates each task entirely to a sub-agent via `/execute-task`, receiving only a structured summary back. Each task gets clean context; nothing accumulates.
+
+**Arguments:** $ARGUMENTS
+
+## Core Pattern (Ralph Fresh-Context)
+
+The orchestrator is an **ultra-lean state machine**. It picks tasks and delegates each one entirely to a sub-agent via `/execute-task`. The orchestrator:
+- Selects the next incomplete task from the PRD
+- Spawns ONE sub-agent per task (fresh context per task)
+- Receives only a structured JSON summary back
+- Updates state.json and progress.txt
+- Never accumulates worker outputs, handoff blobs, or implementation details
+
+Classification, worker selection, worker pipelines, PRD updates, and learning capture all happen inside the sub-agent. This mirrors Pure Ralph's fresh-terminal-per-task model.
+
+## Usage
+
+```bash
+/run-project campaign-migration        # Start new
+/run-project --resume campaign-migration # Resume paused
+/run-project --status                   # Check all projects
+```
+
+## Process
+
+### 1. Parse Arguments
+
+**If `--status`:**
+- Scan `workspace/orchestrator/*/state.json`
+- Display all project statuses
+- Exit
+
+**If `--resume {project}` (first-class operation — not a fallback):**
+- Load state from `workspace/orchestrator/{project}/state.json`
+- Read PRD to find next incomplete task
+- Continue from next incomplete + unblocked task
+- The orchestrator starts with ZERO accumulated context — only state.json + PRD
+- If a task was mid-pipeline (has execution state with incomplete phases), `/execute-task` will resume from the incomplete phase inside its sub-agent
+
+**If `{project}`:**
+- Check `projects/{project}/prd.json` exists
+- If prd.json **MISSING**: STOP immediately. Do not fall back to README.md.
+  ```
+  ERROR: projects/{project}/prd.json not found.
+
+  /run-project requires prd.json (not README.md).
+  Fix: Run /prd {project} to generate prd.json.
+  ```
+- If prd.json **EXISTS**: validate structure (see Step 2)
+- Check if state.json exists (offer resume or restart)
+- Initialize fresh state if new
+
+### 2. Load Project
+
+Read and validate `projects/{project}/prd.json`:
+```javascript
+const prd = JSON.parse(read(`projects/${project}/prd.json`))
+
+// Strict: userStories required. No fallback.
+const stories = prd.userStories
+if (!stories || !Array.isArray(stories) || stories.length === 0) {
+  STOP: "prd.json has no userStories array (or it's empty). Migrate legacy 'features' key to 'userStories'."
+}
+
+// Validate each story has required fields
+for (const story of stories) {
+  const required = ['id', 'title', 'description', 'passes']
+  const missing = required.filter(f => !(f in story))
+  if (missing.length > 0) {
+    STOP: `Story ${story.id || '?'} missing fields: ${missing.join(', ')}`
+  }
+}
+
+const total = stories.length
+const completed = stories.filter(s => s.passes).length
+const remaining = stories.filter(s => !s.passes)
+```
+
+### 3. Display Status
+
+```
+Project: {project}
+Progress: {completed}/{total} ({percentage}%)
+
+Remaining:
+  1. {id}: {title} (next)
+  2. {id}: {title}
+
+Continue? [Y/n]
+```
+
+### 4. Initialize/Load State
+
+```bash
+mkdir -p workspace/orchestrator/{project}/executions
+```
+
+Write `workspace/orchestrator/{project}/state.json`:
+```json
+{
+  "project": "{project}",
+  "prd_path": "projects/{project}/prd.json",
+  "status": "in_progress",
+  "started_at": "{ISO8601}",
+  "updated_at": "{ISO8601}",
+  "progress": { "total": 0, "completed": 0, "failed": 0, "in_progress": 0 },
+  "current_task": null,
+  "completed_tasks": [],
+  "retries": 0
+}
+```
+
+### 5. The Loop
+
+The orchestrator is an **ultra-lean state machine**. It picks tasks and delegates everything to sub-agents. Classification, worker selection, worker pipelines, PRD updates, and learning capture all happen inside the sub-agent via `/execute-task`. The orchestrator NEVER accumulates implementation context.
+
+```
+while (remaining tasks with passes: false):
+
+    5a. SELECT next task
+        - Priority order from PRD
+        - Respect dependsOn (skip if deps incomplete)
+        - First incomplete + unblocked task
+
+        Report:
+        ```
+        Next: {task.id} - {task.title}
+        Progress: {completed}/{total}
+        ```
+
+    5b. EXECUTE task via sub-agent
+
+        Spawn a SINGLE sub-agent for the entire task.
+        The sub-agent handles classification, worker selection,
+        the full worker pipeline, PRD update, execution state,
+        and learning capture — all via /execute-task.
+
+        Task({
+          subagent_type: "general-purpose",
+          description: "Execute {task.id}: {task.title}",
+          prompt: "Run /execute-task {project}/{task.id}
+
+                   After completion, output ONLY this structured JSON:
+                   {
+                     \"task_id\": \"{task.id}\",
+                     \"status\": \"completed|failed|blocked\",
+                     \"summary\": \"1-sentence summary\",
+                     \"workers_used\": [\"list\"],
+                     \"back_pressure\": {
+                       \"tests\": \"pass|fail|skipped\",
+                       \"lint\": \"pass|fail|skipped\",
+                       \"typecheck\": \"pass|fail|skipped\",
+                       \"build\": \"pass|fail|skipped\"
+                     }
+                   }"
+        })
+
+        The sub-agent's full context (worker outputs, handoff blobs,
+        file diffs, error traces) is freed when it returns.
+        Only the structured JSON crosses the boundary.
+
+    5c. POST-TASK (orchestrator side — minimal)
+
+        Parse the sub-agent's JSON output.
+
+        i. If status == "completed":
+           - Update state.json:
+             completed_tasks.push({id, completed_at, workers_used})
+             progress.completed++
+             current_task = null
+           - Log 1-line to progress.txt:
+             [{timestamp}] {task.id}: {summary} ({completed}/{total})
+
+        ii. If status == "failed" or "blocked":
+            - Log error
+            - AskUserQuestion:
+              1. Retry this task
+              2. Skip and continue
+              3. Pause project (run /run-project --resume {project})
+
+        iv. Update `workspace/orchestrator/INDEX.md` with new progress.
+
+        v. DISCARD everything else.
+             The orchestrator MUST NOT store worker outputs,
+             handoff blobs, file lists, or error traces.
+             Only retain: task_id, status, 1-sentence summary.
+
+    5c.5 AUTO-REANCHOR (between tasks, silent)
+
+        After processing each task result, refresh context:
+        1. Re-read PRD from disk (sub-agent may have updated passes/notes)
+        2. Refresh git state: `git log --oneline -3`
+        3. If task failed: search for known fixes via `qmd vsearch "{error}" --json -n 5`
+           (searches across all knowledge, worker yamls, and command files)
+        4. Re-read CLAUDE.md `## Learned Rules`
+           (another session may have added rules via /learn)
+
+        This is silent — no user interaction. Prevents stale context
+        between tasks, especially for multi-session projects.
+
+    5d. CONTEXT SAFETY NET
+
+        If > 10 tasks completed this session OR context heavy:
+          - Save state.json
+          - Print: "Context boundary reached. Run: /run-project --resume {project}"
+          - STOP
+
+        This rarely triggers because each task sub-agent releases
+        its context. But it provides a hard ceiling.
+```
+
+### 6. Handle Task Failure
+
+If any worker phase fails after retry:
+
+```
+Phase {N} ({worker}) failed for {task.id}
+
+Error: {details}
+Attempts: {count}
+
+Options:
+1. Retry this worker phase
+2. Skip worker, continue pipeline
+3. Pause project (/run-project --resume {project})
+4. Abort
+```
+
+Use AskUserQuestion.
+
+### 7. Complete Project
+
+When all stories have `passes: true`:
+
+**Generate report:**
+```
+Project Complete: {project}
+
+Tasks: {completed}/{total}
+Workers Used: {worker}: {N} tasks, ...
+Learnings: {count}
+```
+
+**Aggregate learnings:**
+1. Scan Tier 3 logs: `workspace/learnings/learn-*.json` matching this project
+2. Identify repeated patterns (same rule triggered 3+ times across tasks)
+3. Promote repeated patterns to Tier 1 via `/learn` (severity: high, source: pattern-repetition)
+4. Write project retrospective to `workspace/reports/{project}-retro.md`
+
+**Update state:** `status: "completed"`, `completed_at: "{ISO8601}"`
+
+**Update INDEX.md files:** Regenerate `projects/INDEX.md` and `workspace/orchestrator/INDEX.md` per `knowledge/public/hq-core/index-md-spec.md`.
+
+### 8. Status Display (--status)
+
+```
+Project Status
+
+ACTIVE:
+  campaign-migration — 5/11 (45%) — backend-dev phase on CAM-006
+
+PAUSED:
+  (none)
+
+COMPLETED:
+  user-auth (3d ago) — 8/8
+```
+
+## Worker Pipeline Reference
+
+| Task Type | Worker Sequence |
+|-----------|----------------|
+| schema_change | database-dev → backend-dev → code-reviewer → dev-qa-tester |
+| api_development | backend-dev → code-reviewer → dev-qa-tester |
+| ui_component | frontend-dev → motion-designer → code-reviewer → dev-qa-tester |
+| full_stack | architect → database-dev → backend-dev → frontend-dev → code-reviewer → dev-qa-tester |
+| content | content-brand → content-product → content-sales → content-legal |
+| enhancement | (relevant dev) → code-reviewer |
+
+Prepend **product-planner** if task spec is unclear or acceptance criteria are vague.
+
+## Handoff Context Format
+
+```json
+{
+  "from_worker": "backend-dev",
+  "to_worker": "code-reviewer",
+  "timestamp": "ISO8601",
+  "summary": "What was accomplished",
+  "files_created": ["src/services/foo.ts"],
+  "files_modified": ["src/index.ts"],
+  "key_decisions": ["Used strategy pattern"],
+  "context_for_next": "Focus review on cache invalidation",
+  "back_pressure": { "tests": "pass", "lint": "pass", "typecheck": "pass" }
+}
+```
+
+## State File Format
+
+`workspace/orchestrator/{project}/state.json`:
+```json
+{
+  "project": "campaign-migration",
+  "prd_path": "projects/campaign-migration/prd.json",
+  "status": "in_progress|paused|completed",
+  "started_at": "ISO8601",
+  "updated_at": "ISO8601",
+  "progress": { "total": 11, "completed": 5, "failed": 0, "in_progress": 1 },
+  "current_task": {
+    "id": "CAM-006",
+    "started_at": "ISO8601",
+    "phase": 2,
+    "worker": "backend-dev"
+  },
+  "completed_tasks": [
+    { "id": "CAM-001", "completed_at": "ISO8601", "workers_used": ["backend-dev", "code-reviewer"] }
+  ],
+  "retries": 0
+}
+```
+
+## Rules
+
+- **ONE project at a time**
+- **Sub-agent per task** — each task runs in its own Task() sub-agent via `/execute-task`. The orchestrator NEVER executes worker phases directly.
+- **Context discipline** — the orchestrator stores ONLY task_id, status, and 1-sentence summary per task. No worker outputs, no handoff blobs, no file lists.
+- **Fresh context per task** — sub-agent context is freed when it returns.
+- **Resume is first-class** — `--resume` is how multi-session projects continue. Not a fallback — the expected path for large projects.
+- **Back pressure is mandatory** — enforced inside `/execute-task`, not by the orchestrator
+- **Fail fast** — pause on errors, surface to user
+- **prd.json is required** — never read or fall back to README.md
+- **Validate prd.json on load** — fail loudly on missing/malformed fields
+
+## Integration
+
+- `/prd` → creates PRD → `/run-project {name}` executes it
+- `/execute-task {project}/{id}` → runs single task with same pipeline (standalone or as sub-agent)
+- `/run-project --resume` → continues from next incomplete task with fresh context
+- `/nexttask` → shows active projects from /run-project

package/template/.claude/commands/run.md

@@ -0,0 +1,110 @@
+---
+description: Run a worker or list available workers
+allowed-tools: Task, Read, Glob, Grep, Bash, Edit, Write, WebSearch, WebFetch, AskUserQuestion
+argument-hint: [worker-id] [skill] [args]
+visibility: public
+---
+
+# /run - Worker Execution
+
+Unified interface to run workers and their skills.
+
+**Usage:**
+```
+/run                          # List available workers
+/run {worker-id}              # Show worker skills
+/run {worker-id} {skill}      # Run specific skill
+/run {worker-id} {skill} arg  # Run with argument
+```
+
+**User's input:** $ARGUMENTS
+
+## Process
+
+### No Arguments → List Workers
+
+If no arguments provided, read `workers/registry.yaml` and display:
+
+```
+Available Workers:
+
+  x-{your-name}       X/Twitter posting
+  cfo-{company}       Financial reporting
+  {company}-analyst    Data analysis
+  ...
+
+Usage: /run {worker-id} to see skills
+```
+
+### Worker ID Only → Show Skills
+
+If only worker-id provided:
+1. Find worker in registry
+2. Read `workers/{worker-path}/worker.yaml`
+3. List available skills
+
+```
+Worker: x-{your-name}
+Description: X/Twitter posting
+
+Skills:
+  contentidea   Build out a content idea into posts
+  suggestposts  Research and suggest posts
+  scheduleposts Choose what to post now
+
+Usage: /run x-{your-name} {skill}
+```
+
+### Worker + Skill → Execute
+
+1. Load worker context from `workers/{path}/`
+2. Load skill definition from `workers/{path}/skills/{skill}.md`
+3. Execute the skill instructions
+4. Write checkpoint after completion
+
+### Worker + Skill + Args → Execute with Args
+
+Pass arguments to the skill. The skill file will reference `$ARGUMENTS`.
+
+## Execution Pattern
+
+When executing a skill:
+1. **Load context** - Read worker.yaml (includes accumulated learnings in `instructions:`), any knowledge files referenced
+2. **Execute** - Follow the skill's instructions
+3. **Verify** - Run any verification steps defined
+4. **PostToolsHook** - Auto-save thread to `workspace/threads/`
+
+### PostToolsHook (Auto-Checkpoint)
+
+After skill completion, automatically create a thread:
+
+```json
+{
+  "thread_id": "T-{YYYYMMDD}-{HHMMSS}-{worker}-{skill}",
+  "worker": { "id": "{worker-id}", "skill": "{skill}", "state": "completed" },
+  "git": { /* capture current git state */ },
+  "conversation_summary": "What was accomplished",
+  "files_touched": ["files created/modified"],
+  "metadata": { "tags": ["{worker-id}", "{skill}"] }
+}
+```
+
+Write to: `workspace/threads/{thread_id}.json`
+
+Also append to metrics: `workspace/metrics/metrics.jsonl`
+
+## Examples
+
+```
+/run                              # See all workers
+/run x-{your-name}                # See skills
+/run x-{your-name} contentidea    # Run contentidea
+/run x-{your-name} contentidea "AI workforce" # Run with topic
+/run cfo-{company} mrr            # Run MRR report
+```
+
+## Notes
+
+- Mode (work vs build) is determined by what the skill does, not declared upfront
+- Workers have scoped permissions - only tools listed in their worker.yaml
+- Skills can reference knowledge bases and other workers

package/template/.claude/commands/search-reindex.md

@@ -0,0 +1,62 @@
+---
+description: Reindex and re-embed HQ for qmd search
+allowed-tools: Bash
+argument-hint: [--force]
+visibility: public
+---
+
+# /search-reindex - Rebuild Search Index
+
+Re-index and re-embed HQ content for qmd search.
+
+**Args:** $ARGUMENTS
+
+## Process
+
+### 1. Update index (re-scan files)
+```bash
+qmd update
+```
+
+### 2. Re-embed
+
+If `--force` in $ARGUMENTS:
+```bash
+qmd embed -f
+```
+
+Otherwise (incremental — only new/changed files):
+```bash
+qmd embed
+```
+
+### 3. Show status
+```bash
+qmd status
+```
+
+Display collection stats, document count, embedding coverage.
+
+## When to Reindex
+
+Run after:
+- Adding new knowledge bases or company docs
+- Creating new workers or skills
+- Generating reports or content
+- Major workspace changes
+
+## Full Reset
+
+To completely rebuild:
+```bash
+qmd cleanup
+qmd collection add ~/Documents/HQ --name hq --mask "**/*.md"
+qmd context add qmd://hq "HQ knowledge base: company knowledge, AI worker definitions, project PRDs, slash commands, reports, social drafts, and session threads."
+qmd context add qmd://hq/knowledge "HQ-level knowledge bases: Ralph coding methodology, worker framework patterns, dev-team practices, design styles, security framework, project templates."
+qmd context add qmd://hq/.claude/commands "Claude Code slash commands: agent skills for session management, worker execution, project management, content creation, design, deployment."
+qmd context add qmd://hq/companies "Company-scoped directories (your companies -- configure in companies/ dir) each with knowledge bases, settings, and data."
+qmd context add qmd://hq/workers "AI worker definitions with YAML configs and skill markdown files. Top-level ops workers, 12-person dev-team, 5-person content team."
+qmd context add qmd://hq/projects "Project PRDs and READMEs for active and planned projects across all companies."
+qmd context add qmd://hq/workspace "Runtime workspace: session threads, checkpoints, orchestrator state, reports, social drafts, content ideas, metrics."
+qmd embed
+```

package/template/.claude/commands/search.md

@@ -0,0 +1,100 @@
+---
+description: Search across HQ (qmd-powered semantic + full-text)
+allowed-tools: Bash, Read
+argument-hint: <query> [--mode search|vsearch|query] [-n count] [--full]
+visibility: public
+---
+
+# /search - HQ Search (qmd)
+
+Semantic + full-text search across all HQ content using qmd.
+
+**Query:** $ARGUMENTS
+
+## Parse Arguments
+
+Extract from $ARGUMENTS:
+- `query` — search text (everything except flags)
+- `--mode` — `search` (BM25), `vsearch` (semantic), `query` (hybrid). Default: `search`
+- `-n` — result count (default: 10)
+- `--full` — show full content of top result
+
+## Execute Search
+
+Run the matching qmd command:
+
+**Default (BM25 full-text):**
+```bash
+qmd search "$QUERY" -n 10 --json
+```
+
+**Semantic (conceptual match):**
+```bash
+qmd vsearch "$QUERY" -n 10 --json
+```
+
+**Hybrid (BM25 + vector + re-rank):**
+```bash
+qmd query "$QUERY" -n 10 --json
+```
+
+## Display Results
+
+Parse JSON output. Display:
+
+```
+Search: "{query}" (mode: {mode})
+
+Results:
+  1. [0.92] knowledge/public/Ralph/02-core-concepts.md
+     "Ralph methodology emphasizes small loops with human checkpoints..."
+
+  2. [0.84] .claude/commands/run-project.md
+     "Run a project through the Ralph loop..."
+
+  3. [0.71] workers/public/dev-team/architect/skills/design-review.md
+     "Architecture review following Ralph back-pressure patterns..."
+
+{n} results. Use --full to show top result content.
+```
+
+- Score in brackets
+- Relative path (strip `qmd://hq/` prefix)
+- Snippet truncated to ~100 chars
+
+## Full Content
+
+If `--full` flag, after listing results, read top result file with Read tool.
+
+## Fallback
+
+If qmd errors or isn't installed:
+
+```bash
+grep -rl "$QUERY" ~/Documents/HQ/knowledge/ \
+  ~/Documents/HQ/companies/ \
+  ~/Documents/HQ/workers/ \
+  ~/Documents/HQ/.claude/commands/ \
+  ~/Documents/HQ/workspace/ 2>/dev/null | head -20
+```
+
+Display: "qmd unavailable, falling back to grep"
+
+## Examples
+
+```bash
+/search ralph                           # BM25 keyword search (default)
+/search "how do workers execute" --mode vsearch  # Semantic
+/search acme brand --mode query         # Hybrid with re-ranking
+/search stripe -n 20                    # More results
+/search authentication --full           # Show top match content
+```
+
+## Notes
+
+- Default `search` mode is fastest — use for exact keywords
+- Use `--mode vsearch` for conceptual/semantic queries
+- Use `--mode query` for highest quality (slower, uses LLM re-ranking)
+- Scores 0.0-1.0; above 0.5 is a good match
+- Run `/search-reindex` after adding new content
+- For code search in repos, use Grep tool directly