create-hq 5.1.0 → 5.2.0

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

@@ -1,348 +0,0 @@
----
-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

@@ -1,110 +0,0 @@
----
-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

@@ -1,62 +0,0 @@
----
-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

@@ -1,100 +0,0 @@
----
-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