create-hq 5.0.0

package/template/.claude/commands/learn.md

@@ -0,0 +1,218 @@
+---
+description: Auto-capture and classify learnings from task execution
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+argument-hint: [json-event or "rule description"]
+visibility: public
+---
+
+# /learn - Automated Learning Pipeline
+
+Capture a learning, classify it, and inject the rule directly into the file it governs.
+
+Called programmatically by `/execute-task` and `/run-project` after task completion or failure. Also callable manually. `/remember` delegates here.
+
+**Input:** $ARGUMENTS
+
+## Core Principle
+
+No separate learnings files. Rules go into the files they pertain to:
+
+| Scope | Target file | Section |
+|-------|------------|---------|
+| `worker:{id}` | `workers/*/{id}/worker.yaml` | `instructions:` → `## Learnings` subsection |
+| `command:{name}` | `.claude/commands/{name}.md` | `## Rules` section |
+| `knowledge:{path}` | The relevant knowledge file | Append as rule/note |
+| `project:{slug}` | Related knowledge or prd.json metadata | Context-dependent |
+| `global` | `.claude/CLAUDE.md` | `## Learned Rules` section |
+
+## Step 1: Parse Input
+
+**If structured JSON** (from /execute-task):
+```json
+{
+  "task_id": "TASK-001",
+  "project": "my-project",
+  "source": "back-pressure-failure|user-correction|success-pattern|task-completion|build-activity",
+  "severity": "critical|high|medium|low",
+  "scope": "global|worker:{id}|command:{name}|knowledge:{path}|project:{slug}",
+  "workers_used": ["backend-dev"],
+  "back_pressure_failures": [{"worker": "frontend-dev", "check": "lint", "error": "..."}],
+  "retries": 0,
+  "key_decisions": ["..."],
+  "issues_encountered": ["..."],
+  "patterns_discovered": ["..."]
+}
+```
+
+**If free text** (manual invocation or /remember delegation):
+- Parse for keywords to determine scope
+- Generate rule statement from description
+
+## Step 2: Extract Rules
+
+From structured input, generate rules:
+
+- `back_pressure_failures` → `NEVER: {anti-pattern that caused failure}` (scope: worker:{id})
+- `retries > 0` → Rule about what caused retry and how to avoid it
+- `key_decisions` → `ALWAYS: {pattern}` if broadly applicable
+- `issues_encountered` → Scoped rule to prevent recurrence
+- `patterns_discovered` → `ALWAYS: {pattern}` for success patterns
+
+From free text:
+- Extract the core rule in NEVER/ALWAYS/condition→action format
+
+If no meaningful rules can be extracted (task completed cleanly, no failures, no notable patterns), skip injection — log to event log only.
+
+## Step 3: Classify Scope & Resolve Target File
+
+For each extracted rule, determine scope (most specific wins):
+
+| Signal | Scope | Target |
+|--------|-------|--------|
+| Failure in specific worker | `worker:{id}` | `workers/*/{id}/worker.yaml` |
+| Error in specific command | `command:{name}` | `.claude/commands/{name}.md` |
+| Relevant to specific knowledge | `knowledge:{path}` | The knowledge file |
+| Universal pattern | `global` | `.claude/CLAUDE.md` |
+| User correction via /remember | From context, default global | Detected target or CLAUDE.md |
+
+**Resolve the target file path:**
+- For workers: Glob `workers/*/{id}/worker.yaml` or `workers/public/dev-team/{id}/worker.yaml`
+- For commands: `.claude/commands/{name}.md`
+- For knowledge: the specific knowledge file mentioned in context
+- For global: `.claude/CLAUDE.md`
+
+If the target file doesn't exist, fall back to `.claude/CLAUDE.md`.
+
+## Step 4: Dedup Check
+
+```bash
+qmd vsearch "{rule text}" --json -n 5
+```
+
+Check results for similarity to the new rule:
+- Similarity > 0.85 → **Skip** (already captured somewhere)
+- Similarity 0.6–0.85 → **Merge** (update existing rule to be more precise)
+- Similarity < 0.6 → **Add new**
+
+Report dedup action taken.
+
+## Step 5: Inject Rule into Target File
+
+### For worker.yaml (`instructions:` block)
+
+Read the file, find `instructions: |` block. Look for `## Learnings` subsection:
+- If exists: append rule under it
+- If not: create `## Learnings` subsection at end of instructions block
+
+```yaml
+instructions: |
+  ...existing instructions...
+
+  ## Learnings
+  - NEVER: {new rule}
+```
+
+### For command .md (`## Rules` section)
+
+Find `## Rules` section, append rule:
+```markdown
+## Rules
+
+...existing rules...
+- **{NEVER|ALWAYS}**: {rule}
+```
+
+If no `## Rules` section exists, create it at end of file.
+
+### For knowledge files
+
+Append rule as a note at end of file, or under most relevant section.
+
+**Knowledge files live in separate git repos** (symlinked into HQ). After injecting a rule into a knowledge file, commit the change to the knowledge repo:
+
+```bash
+# Resolve the real repo path through the symlink
+repo_dir=$(cd "$(dirname "$(readlink -f "{target_file}")")" && git rev-parse --show-toplevel)
+cd "$repo_dir"
+git add -A
+git commit -m "learn: {short rule summary}"
+```
+
+### For CLAUDE.md (`## Learned Rules`)
+
+Append rule:
+```markdown
+- **{NEVER|ALWAYS}**: {rule} <!-- {source} | {date} -->
+```
+
+## Step 6: Evaluate Global Promotion
+
+If the rule was injected into a scoped file (worker/command/knowledge), also add to `.claude/CLAUDE.md` `## Learned Rules` if ANY:
+- `severity == critical`
+- `source == user-correction` (explicit /remember invocation)
+- Rule triggered 3+ times (check event log)
+
+### Cap Enforcement
+
+`## Learned Rules` is capped at 20 rules.
+
+1. Count existing rules in section
+2. If >= 20: find the oldest rule (by date in comment), remove it from CLAUDE.md
+   - The rule still lives in its source file — only the CLAUDE.md copy is removed
+3. Append new rule
+
+## Step 7: Log Event
+
+```bash
+mkdir -p workspace/learnings
+```
+
+Write `workspace/learnings/learn-{YYYYMMDD-HHMMSS}.json`:
+```json
+{
+  "event_id": "learn-{timestamp}",
+  "rules": [
+    {
+      "rule": "NEVER: ...",
+      "scope": "worker:frontend-dev",
+      "target_file": "workers/public/dev-team/frontend-dev/worker.yaml",
+      "severity": "high"
+    }
+  ],
+  "source": "back-pressure-failure",
+  "task_id": "TASK-001",
+  "project": "my-project",
+  "dedup_action": "new|merged|skipped",
+  "promoted_to_global": true,
+  "created_at": "{ISO8601}"
+}
+```
+
+## Step 8: Reindex
+
+```bash
+qmd update 2>/dev/null || true
+```
+
+## Step 9: Report
+
+```
+Learning captured:
+  Rule: {rule}
+  Injected: {target file path} → {section}
+  Global: {promoted|not promoted}
+  Dedup: {new|merged|skipped}
+  Event: workspace/learnings/learn-{timestamp}.json
+```
+
+If multiple rules extracted, report each.
+
+## Rules
+
+- **Never inject empty/trivial rules** — "task completed successfully" is not a learning
+- **Dedup is mandatory** — always check before injecting
+- **Global cap is hard** — never exceed 20 rules in CLAUDE.md `## Learned Rules`
+- **Reindex after every injection** — keeps qmd search current
+- **Preserve existing rules** — append only, never overwrite existing rules
+- **User corrections always promote** — /remember delegations go to both target file AND CLAUDE.md
+- **Match existing style** — use the same rule format as existing rules in the target file

package/template/.claude/commands/metrics.md

@@ -0,0 +1,118 @@
+---
+description: View worker execution metrics
+allowed-tools: Bash, Read
+argument-hint: [worker-id] [--days N]
+visibility: public
+---
+
+# /metrics - Worker Observability
+
+View worker execution metrics and statistics.
+
+**Arguments:** $ARGUMENTS
+
+## Usage
+
+```bash
+/metrics                      # Summary of all workers
+/metrics cfo-{company}        # Metrics for specific worker
+/metrics --days 7             # Last 7 days only
+/metrics cfo-{company} mrr    # Specific worker + skill
+```
+
+## Metrics File
+
+Location: `workspace/metrics/metrics.jsonl`
+
+Each line is a JSON object:
+
+```json
+{"ts":"2026-01-23T14:30:52.000Z","worker":"cfo-{company}","skill":"mrr","duration_ms":5000,"status":"completed","files":1}
+```
+
+## Fields
+
+| Field | Description |
+|-------|-------------|
+| `ts` | ISO8601 timestamp |
+| `worker` | Worker ID |
+| `skill` | Skill executed |
+| `duration_ms` | Execution time in milliseconds |
+| `status` | `completed` or `error` |
+| `files` | Number of files created/modified |
+| `error` | Error message (if status=error) |
+
+## Process
+
+1. **Read metrics file**
+   ```bash
+   cat workspace/metrics/metrics.jsonl
+   ```
+
+2. **Filter by arguments**
+   - If worker-id provided: filter to that worker
+   - If --days N: filter to last N days
+   - If skill provided: filter to that skill
+
+3. **Calculate statistics**
+   - Total runs
+   - Success rate
+   - Average duration
+   - Most used skills
+
+4. **Display summary**
+
+   ```
+   Worker Metrics (last 30 days)
+   ═══════════════════════════════════════════════════
+
+   cfo-{company}
+     Runs: 45 (98% success)
+     Avg duration: 3.2s
+     Top skills: mrr (20), pnl (12), cash-position (8)
+
+   x-{your-name}
+     Runs: 23 (100% success)
+     Avg duration: 8.5s
+     Top skills: suggestposts (15), scheduleposts (8)
+
+   {company}-analyst
+     Runs: 12 (92% success)
+     Avg duration: 15.3s
+     Top skills: anomaly-check (10), forecast (2)
+
+   ───────────────────────────────────────────────────
+   Total: 80 runs | 97% success | 6.2s avg
+   ```
+
+## Detailed View
+
+For specific worker:
+
+```
+/metrics cfo-{company}
+
+cfo-{company} Metrics (last 30 days)
+═══════════════════════════════════════════════════
+
+Skills:
+  mrr             20 runs   2.1s avg   100% success
+  pnl             12 runs   4.5s avg   100% success
+  cash-position    8 runs   3.8s avg    88% success
+  burn-rate        5 runs   2.9s avg   100% success
+
+Recent runs:
+  2026-01-23 14:30   mrr           completed   2.1s
+  2026-01-23 09:15   pnl           completed   4.2s
+  2026-01-22 16:00   cash-position error       0.5s
+  2026-01-22 11:30   mrr           completed   2.3s
+
+Errors (1):
+  2026-01-22 16:00 cash-position: "QuickBooks token expired"
+```
+
+## Notes
+
+- Metrics auto-appended by PostToolsHook after each skill run
+- File is append-only JSONL for efficiency
+- Rotate/archive manually if file grows large

package/template/.claude/commands/newworker.md

@@ -0,0 +1,162 @@
+---
+description: Scaffold a new worker with skills, tools, and knowledge
+allowed-tools: Read, Write, Edit, AskUserQuestion
+visibility: public
+---
+
+# New Worker Builder
+
+Create a new worker with proper structure, skills, and verification.
+
+**Technology:** All HQ workers use TypeScript + Node.js (ESM). No Python for new workers.
+
+**PRDs live in `projects/`** - Workers reference them, don't create their own. If the worker needs a PRD:
+1. Run `/prd {worker-name}` first to create the PRD
+2. Then return to `/newworker` to create the worker that references it
+
+## Context to Load First
+
+1. `knowledge/public/workers/README.md` - Worker framework
+2. `knowledge/public/workers/templates/` - Worker templates
+3. `workers/registry.yaml` - Existing workers
+
+## Interactive Setup
+
+Ask these questions (can batch related ones):
+
+### 1. Identity
+- **What type of worker?** (CodeWorker, SocialWorker, ResearchWorker, OpsWorker)
+- **What's its name/id?** (e.g., "competitive-researcher", "x-{your-name}")
+- **What does it do?** (1-sentence purpose)
+
+### 2. Skills
+- **What skills does it have?** (list specific capabilities)
+- **What inputs does it need?** (context, triggers, data)
+- **What outputs does it produce?** (reports, code, posts, etc.)
+
+### 3. Execution
+- **When does it run?** (on-demand, scheduled, event-triggered)
+- **Schedule if applicable** (cron format: "0 9,14,19 * * *" = 9am, 2pm, 7pm)
+
+### 4. Context
+- **What files should always be loaded?** (base context)
+- **What files should be loaded per-task?** (dynamic context)
+- **What should be excluded?** (noise reduction)
+
+### 5. Verification
+- **What checks ensure quality?** (type checks, character limits, voice consistency)
+- **Does it need human approval?** (before external actions)
+
+## Generate Worker
+
+Create folder: `workers/{worker-id}/` (flat structure, no categories)
+
+### worker.yaml
+
+```yaml
+worker:
+  id: {worker-id}
+  name: "{Human Name}"
+  type: {WorkerType}
+  version: "1.0"
+
+identity:
+  persona: {your-username}  # or company_context, voice_guide
+
+execution:
+  mode: {on-demand|scheduled|event-triggered}
+  schedule: "{cron if scheduled}"
+  max_runtime: 10m
+  retry_attempts: 2
+
+context:
+  base:
+    - {always-loaded-files}
+  dynamic:
+    - {per-task-files}
+  exclude:
+    - "*.log"
+    - "node_modules/"
+
+verification:
+  post_execute:
+    - {checks}
+  approval_required: {true|false}
+
+tasks:
+  source: projects/{associated-project}/prd.json  # Or queue.json for simple task queues
+  one_at_a_time: true
+
+output:
+  destination: workspace/{output-folder}/
+  format: {markdown|json}
+
+instructions: |
+  {Worker-specific instructions and constraints}
+```
+
+### Update Registry
+
+Add to `workers/registry.yaml`:
+
+```yaml
+  - id: {worker-id}
+    path: workers/{worker-id}/
+    type: {WorkerType}
+    status: active
+    description: "{1-sentence description}"
+```
+
+### Task Source Options
+
+Workers can get tasks from:
+
+1. **Project PRD** (recommended): `projects/{project-name}/prd.json`
+   - For workers that implement features
+   - Reference existing project or create one with `/prd`
+
+2. **Queue file**: `workers/{worker-id}/queue.json`
+   - For workers with simple, repeating tasks (posting, monitoring)
+   - Create with:
+     ```json
+     {
+       "worker": "{worker-id}",
+       "tasks": []
+     }
+     ```
+
+**Do NOT create prd.json inside worker directories.** PRDs belong in `projects/`.
+
+## Rules
+
+- Follow existing worker patterns
+- One task at a time (Ralph principle)
+- Always include verification
+- Default to `approval_required: true` for external actions
+
+## After Creation
+
+### Capture Learning (Auto-Learn)
+
+Run `/learn` to register the new worker in the learning system:
+```json
+{
+  "source": "build-activity",
+  "severity": "medium",
+  "scope": "global",
+  "rule": "Worker {worker-id} exists at workers/{path}/ for {1-sentence purpose}",
+  "context": "Created via /newworker"
+}
+```
+
+Also reindex: `qmd update 2>/dev/null || true`
+
+**Update INDEX.md:** Regenerate `workers/public/INDEX.md` or `workers/private/INDEX.md` (whichever the worker was created in) per `knowledge/public/hq-core/index-md-spec.md`.
+
+### Report to User
+
+Provide next steps:
+1. "Worker created at `workers/{worker-id}/`"
+2. "Test with on-demand execution first"
+3. If using queue: "Add tasks to queue.json to get started"
+4. If using PRD: "Run `/prd {project-name}` to create the PRD, then link it in worker.yaml"

package/template/.claude/commands/nexttask.md

@@ -0,0 +1,67 @@
+---
+description: Scan HQ and suggest next tasks or projects to work on
+allowed-tools: Read, Glob, Bash, AskUserQuestion
+visibility: public
+---
+
+# /nexttask - Find Work
+
+Scan HQ to surface actionable work. Prioritize by: beads tasks, checkpoints, projects.
+
+## Process
+
+### 1. Check Beads (Primary Source)
+```bash
+bd list --status open --limit 10
+```
+Beads is the canonical task tracker. Open issues are the primary work queue.
+
+### 2. Check Checkpoints (In-Progress Work)
+```
+workspace/checkpoints/*.json
+```
+Look for recent checkpoints with `next_steps`. These are work that was started.
+
+Also check `workspace/checkpoints/handoff.json` for explicit handoffs.
+
+### 3. Check Projects (Secondary)
+```
+projects/*/prd.json
+```
+Scan for projects with incomplete features (beads syncs from PRDs, so this is backup).
+
+## Output Format
+
+```
+Next Tasks:
+
+BEADS (open issues):
+  1. [PROJECT-123] Task title
+  2. [PROJECT-456] Another task
+
+IN PROGRESS (checkpoints):
+  3. skills-redesign - "Rewriting HQ skills per plan"
+     Next: Move content skills to worker
+
+PROJECTS (with work):
+  4. customer-cube - 3 features remaining
+
+Pick a number, or:
+  /run {worker}    Run a worker skill
+  /prd             Create a new project
+```
+
+## Priority Rules
+
+1. **Handoff work** - explicit continuations from last session
+2. **Beads open issues** - canonical task queue
+3. **In-progress checkpoints** - finish what was started
+4. **Projects with defined features** - clear work to do
+
+## After Presenting
+
+Use AskUserQuestion:
+- "Which task to work on?"
+- Options: numbered list + "Something else"
+
+Then execute the chosen work in the current session.