create-hq 5.0.0

package/template/knowledge/loom/weaver.md

@@ -0,0 +1,96 @@
+# Weaver (Remote Execution)
+
+Weavers are ephemeral Kubernetes pods for running remote Loom REPL sessions.
+
+**Source**: `crates/loom-weaver-*/`, `crates/loom-wgtunnel-*/`
+
+## Architecture
+
+```
+┌─────────────┐     WebSocket     ┌─────────────┐     K8s API      ┌─────────────┐
+│  loom-cli   │ ──────────────────▶│ loom-server │ ───────────────▶ │   K8s Pod   │
+│             │                    │             │                  │   (Weaver)  │
+│  attach     │ ◀─────────────────│  /weavers   │ ◀────────────────│             │
+└─────────────┘     Terminal I/O  └─────────────┘    WireGuard     └─────────────┘
+```
+
+## CLI Commands
+
+```bash
+# Login first
+loom --server-url https://loom.ghuntley.com login
+
+# Create new weaver
+loom --server-url https://loom.ghuntley.com new --image <image>
+
+# List weavers
+loom --server-url https://loom.ghuntley.com weaver ps
+
+# Attach to weaver
+loom --server-url https://loom.ghuntley.com attach <weaver-id>
+
+# Delete weaver
+loom --server-url https://loom.ghuntley.com weaver delete <weaver-id>
+```
+
+## K8s Namespace
+
+Weavers run in `loom-weavers` namespace:
+
+```bash
+# List pods
+sudo kubectl get pods -n loom-weavers
+
+# Describe pod
+sudo kubectl describe pod <pod-name> -n loom-weavers
+
+# Pod logs
+sudo kubectl logs <pod-name> -n loom-weavers
+
+# Delete stuck pod
+sudo kubectl delete pod <pod-name> -n loom-weavers
+```
+
+## Crates
+
+| Crate | Purpose |
+|-------|---------|
+| `loom-weaver-audit-sidecar` | Audit logging sidecar |
+| `loom-weaver-ebpf` | eBPF syscall tracing |
+| `loom-weaver-ebpf-common` | Shared eBPF types |
+| `loom-weaver-secrets` | Secret injection |
+| `loom-wgtunnel-common` | WireGuard common types |
+| `loom-wgtunnel-conn` | Connection handling |
+| `loom-wgtunnel-derp` | DERP relay support |
+| `loom-wgtunnel-engine` | Tunnel engine |
+| `loom-server-wgtunnel` | Server integration |
+| `loom-server-weaver` | Server weaver management |
+
+## Features
+
+### WireGuard Tunneling
+Secure tunnel between client and weaver pod via WireGuard with DERP relay fallback.
+
+### eBPF Audit
+`loom-weaver-ebpf` traces syscalls for security auditing:
+- File operations
+- Network activity
+- Process spawning
+
+### Secret Injection
+`loom-weaver-secrets` injects secrets into weaver environment without exposing them in pod spec.
+
+## Common Issues
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| ErrImagePull | Image doesn't exist or is private | Check `kubectl describe pod` |
+| Succeeded immediately | Container has no long-running entrypoint | Weaver images must run persistent process |
+| 401 Unauthorized | Not logged in | Run `loom login` first |
+
+## Server Logs
+
+```bash
+# Weaver-related logs
+journalctl -u loom-server -f
+```

package/template/knowledge/loom/web-frontend.md

@@ -0,0 +1,131 @@
+# Web Frontend
+
+Svelte 5 web application with SvelteKit, Tailwind CSS 4, and xstate state machines.
+
+**Source**: `web/loom-web/`
+
+## Tech Stack
+
+| Technology | Version | Purpose |
+|------------|---------|---------|
+| Svelte | 5 | UI framework (runes syntax) |
+| SvelteKit | 2 | App framework |
+| Tailwind CSS | 4 | Styling |
+| xstate | - | State machines |
+| xterm.js | - | Terminal emulator |
+| marked | - | Markdown rendering |
+| Storybook | - | Component development |
+| Vitest | - | Testing |
+| Lingui | - | i18n |
+
+## Svelte 5 Runes (NOT Svelte 4)
+
+**Always use Svelte 5 patterns. Never use Svelte 4.**
+
+| Category | Svelte 5 | Svelte 4 (DO NOT USE) |
+|----------|----------|----------------------|
+| State | `let count = $state(0);` | `let count = 0;` |
+| Derived | `const doubled = $derived(count * 2);` | `$: doubled = count * 2;` |
+| Effects | `$effect(() => { ... });` | `$: { ... }` |
+| Props | `let { foo, bar } = $props();` | `export let foo;` |
+| Events | `onclick={handler}` | `on:click={handler}` |
+| Custom events | `onsave={fn}` (callback props) | `createEventDispatcher` |
+| Slots | `{@render children()}` | `<slot />` |
+
+## Project Structure
+
+```
+web/loom-web/
+├── src/
+│   ├── app.html              # Root HTML
+│   ├── app.css               # Global styles
+│   ├── routes/               # SvelteKit routes
+│   │   ├── (app)/            # Protected app routes
+│   │   │   ├── admin/        # Admin panel
+│   │   │   ├── dashboard/    # Main dashboard
+│   │   │   ├── threads/      # Conversation threads
+│   │   │   └── weavers/      # Remote execution
+│   │   ├── (docs)/           # Documentation
+│   │   ├── api/              # API routes
+│   │   └── login/            # Auth flow
+│   └── lib/
+│       ├── api/              # HTTP client
+│       ├── auth/             # Auth store & machine
+│       ├── components/       # Page components
+│       ├── docs/             # Doc system
+│       ├── i18n/             # Internationalization
+│       ├── logging/          # Client logging
+│       ├── realtime/         # WebSocket/SSE
+│       ├── state/            # State machines
+│       └── ui/               # Reusable UI components
+├── package.json
+├── svelte.config.js
+├── tailwind.config.cjs
+└── vite.config.ts
+```
+
+## Key Components
+
+### Page Components (`src/lib/components/`)
+
+| Component | Purpose |
+|-----------|---------|
+| `MessageList.svelte` | Conversation message display |
+| `MessageBubble.svelte` | Individual message |
+| `MessageInput.svelte` | User input |
+| `ThreadListPane.svelte` | Thread sidebar |
+| `ThreadListItem.svelte` | Thread entry |
+| `ToolExecutionPanel.svelte` | Tool call display |
+| `WeaverTerminal.svelte` | xterm.js integration |
+| `AgentStateTimeline.svelte` | State visualization |
+| `ConnectionStatusIndicator.svelte` | Connection status |
+
+### UI Components (`src/lib/ui/`)
+
+| Component | Purpose |
+|-----------|---------|
+| `Button.svelte` | Button variants |
+| `Input.svelte` | Text input |
+| `Card.svelte` | Card container |
+| `Badge.svelte` | Status badges |
+| `Skeleton.svelte` | Loading skeleton |
+| `Modal.svelte` | Modal dialog |
+| `LoomFrame.svelte` | Main frame wrapper |
+| `ThemeProvider.svelte` | Theme context |
+
+## State Machines (`src/lib/state/`)
+
+Uses xstate for complex state management:
+
+| Machine | Purpose |
+|---------|---------|
+| `authMachine.ts` | Authentication flow |
+| `connectionMachine.ts` | WebSocket connection |
+| `conversationMachine.ts` | Conversation flow |
+| `threadListMachine.ts` | Thread list state |
+
+## Auth Store (`src/lib/auth/`)
+
+```typescript
+// authStore.svelte.ts - Svelte 5 runes store
+let user = $state<User | null>(null);
+let isAuthenticated = $derived(user !== null);
+```
+
+## Development
+
+```bash
+cd web/loom-web
+
+# Install dependencies
+pnpm install
+
+# Development server
+pnpm dev
+
+# Run tests
+pnpm test
+
+# Storybook
+pnpm storybook
+```

package/template/knowledge/projects/README.md

@@ -0,0 +1,72 @@
+# Projects
+
+Guidelines for creating and tracking projects in HQ.
+
+## When to Create a Project
+
+Create a `projects/{name}/` folder when:
+- Work spans multiple steps or sessions
+- There are tangible deliverables (code, content, launches)
+- You'd want to reference the work later
+
+**Do not create** for:
+- One-off questions or research
+- Quick fixes (< 30 min)
+- Pure conversation without deliverables
+
+## Project Structure
+
+```
+projects/{name}/
+├── README.md      # Required - overview, status, log
+├── prd.json       # Required for multi-feature projects
+└── CLAUDE.md      # Optional - project-specific rules
+```
+
+## README.md (Required)
+
+Use the template at `knowledge/projects/templates/README.template.md`.
+
+Key sections:
+- **Overview**: 1-2 sentences
+- **Status**: Phase + repo link
+- **Deliverables**: Checklist of what's being built
+- **Log**: Date/action/outcome table updated as work progresses
+
+## prd.json (Required for Multi-Feature)
+
+```json
+{
+  "project": "project-name",
+  "goal": "what it achieves",
+  "success_criteria": "how to know it's done",
+  "repo": "repos/private/{name}/",
+  "features": [
+    {"id": "F1", "title": "Feature name", "passes": false}
+  ]
+}
+```
+
+## Linking to Repos
+
+If project has code:
+- Repo goes in `repos/private/{name}/` or `repos/public/{name}/`
+- README.md references: `**Repo**: repos/private/{name}/`
+
+## Session Protocol
+
+1. **Start of session**: Create `projects/{name}/README.md` if new project
+2. **During session**: Update log table after major milestones
+3. **End of session**: Ensure README reflects current state
+
+## Examples
+
+Good project folders:
+- `projects/my-app/` - Mobile app
+- `projects/token-launch/` - Token launch
+- `projects/site-migration/` - Website migration
+
+Not projects (too small):
+- Fix a typo in docs
+- Answer a question about code
+- Run a one-time report

package/template/knowledge/projects/templates/README.template.md

@@ -0,0 +1,28 @@
+# {Project Name}
+
+{1-2 sentence description}
+
+## Status
+
+**Phase**: {Discovery|MVP|Launch|Complete}
+**Repo**: `repos/private/{repo-name}/` (if applicable)
+
+## Goals
+
+- {what success looks like}
+
+## Deliverables
+
+- [ ] {deliverable 1}
+- [ ] {deliverable 2}
+
+## Key Links
+
+- {link 1}
+- {link 2}
+
+## Log
+
+| Date | Action | Outcome |
+|------|--------|---------|
+| {YYYY-MM-DD} | {what was done} | {result} |

package/template/knowledge/workers/README.md

@@ -0,0 +1,195 @@
+# Workers
+
+Workers are autonomous AI assistants with specialized roles. This knowledge base documents the Workers framework and how to build/operate them.
+
+## Philosophy
+
+**Workers, not Agents**
+- "Agent" is technical jargon
+- "Worker" is human, relatable
+- Workers have jobs, context, and output
+- They do real work, not just assist
+
+**Built on Ralph Principles**
+- ONE task at a time
+- Fresh context per task (no context rot)
+- Back pressure verification before completion
+- Simple loops over complex orchestration
+
+## Worker Types
+
+| Type | Purpose | Example |
+|------|---------|---------|
+| **CodeWorker** | Implement features, fix bugs | dev-team workers |
+| **SocialWorker** | Draft posts, maintain presence | x-worker |
+| **ResearchWorker** | Competitive analysis, market research | analyst |
+| **OpsWorker** | Monitoring, automation, reports | cfo-worker |
+
+## Building Workers (Build Mode)
+
+When creating or modifying workers, follow this structure:
+
+### Worker Definition (`worker.yaml`)
+
+```yaml
+id: worker-id
+name: Human-readable Name
+type: WorkerType
+status: active|planned|deprecated
+
+context:
+  base:
+    - path/to/always/load.md
+  dynamic:
+    - pattern: "*.yaml"
+      when: "task.type == 'config'"
+
+skills:
+  - id: skill-name
+    description: What this skill does
+    inputs: [required, parameters]
+    outputs: [what, it, produces]
+    verification:
+      - command: "npm run typecheck"
+        must_pass: true
+
+schedule:
+  type: on-demand|cron|event
+  cron: "0 8 * * *"  # if cron type
+```
+
+### File Structure
+
+```
+workers/
+├── registry.yaml           # Index of all workers
+├── {category}/
+│   └── {worker-id}/
+│       ├── worker.yaml     # Definition
+│       ├── prd.json        # If code-based, task tracking
+│       └── skills/         # Skill implementations
+```
+
+### Build Checklist
+
+1. Add entry to `workers/registry.yaml`
+2. Create `workers/{category}/{id}/worker.yaml`
+3. Define skills with clear inputs/outputs/verification
+4. Test with on-demand execution first
+5. Document in this knowledge base if patterns emerge
+
+## Running Workers (Work Mode)
+
+### On-Demand Execution
+
+```
+"Run the analyst anomaly check"
+"Execute cfo-worker monthly report"
+```
+
+The agent will:
+1. Load the worker's context
+2. Execute the relevant skill
+3. Run verification checks
+4. Output results
+
+### Ralph Loop Pattern
+
+For multi-task projects (3+ tasks), use the orchestrator pattern:
+
+```
+Orchestrator (main agent):
+  - Read PRD/task list
+  - Pick ONE task (status: pending)
+  - Spawn sub-agent via Task tool
+  - Read checkpoint when done
+  - Update task status
+  - Repeat until all tasks done
+
+Sub-agent (spawned):
+  - Fresh 100% context
+  - Implements ONE task
+  - Runs back pressure (typecheck, build, tests)
+  - Writes checkpoint
+  - Exits
+```
+
+**Why this pattern:**
+- Main agent context stays light (<30%)
+- Sub-agents get full context per task
+- Parallel execution possible for independent tasks
+- Clear audit trail via checkpoints
+
+**Spawn template:**
+```
+Task({
+  subagent_type: "general-purpose",
+  prompt: `
+    Task: {id} - {title}
+
+    Acceptance criteria:
+    - {criteria}
+
+    Files: {file_paths}
+
+    Instructions:
+    1. Implement the task
+    2. Run verification: {verification_command}
+    3. Commit: "feat({id}): {title}"
+    4. Write checkpoint to workspace/checkpoints/{id}.json
+    5. Exit
+  `
+})
+```
+
+### Checkpointing
+
+After significant progress, write state:
+
+```json
+{
+  "task_id": "string",
+  "completed_at": "ISO8601",
+  "summary": "what was done",
+  "next_steps": ["array"],
+  "files_touched": ["paths"]
+}
+```
+
+Location: `workspace/checkpoints/{task-id}.json`
+
+## Back Pressure
+
+Every worker skill should define verification checks:
+
+| Type | Example | When |
+|------|---------|------|
+| Code | `npm run typecheck && npm run build` | After code changes |
+| Tests | `npm test` | After feature implementation |
+| Lint | `npm run lint` | Before commit |
+| Voice | Compare against style guide | Social/content workers |
+
+**Rule:** Never mark a task complete without passing verification.
+
+## Registry
+
+All workers are indexed in `workers/registry.yaml`:
+
+```yaml
+workers:
+  - id: worker-id
+    path: workers/category/worker-id/
+    type: WorkerType
+    status: active|planned
+    description: "What this worker does"
+```
+
+## See Also
+
+- [Ralph Methodology](../Ralph/) - Core principles
+- [ralph-loop-pattern.md](./ralph-loop-pattern.md) - Detailed loop docs
+- [state-machine.md](./state-machine.md) - Worker state machine (Loom pattern)
+- [skill-schema.md](./skill-schema.md) - Skill interface specification
+- [Thread Schema](../hq-core/thread-schema.md) - Thread persistence format
+- [Loom Patterns](../loom/) - Reference implementation
+- Individual worker docs in `workers/{category}/{id}/`

package/template/knowledge/workers/ralph-loop-pattern.md

@@ -0,0 +1,157 @@
+# Ralph Loop Pattern: Context-Preserving Task Execution
+
+## Problem
+Long implementation sessions drain orchestrator context. By task 7, context is 80%+ full, responses slow, risk of forgetting earlier decisions.
+
+## Solution
+Orchestrator stays lean. Sub-agents do heavy lifting.
+
+```
+┌─────────────────────────────────────┐
+│         ORCHESTRATOR                │
+│  - Reads PRD                        │
+│  - Picks ONE task (passes: false)   │
+│  - Spawns sub-agent with task spec  │
+│  - Reads checkpoint when done       │
+│  - Updates PRD (passes: true)       │
+│  - Repeats until all pass           │
+│                                     │
+│  Context usage: ~10-20% (stays low) │
+└─────────────────────────────────────┘
+              │
+              ▼ spawn
+┌─────────────────────────────────────┐
+│         SUB-AGENT                   │
+│  - Receives: task spec, file paths  │
+│  - Implements feature               │
+│  - Runs back pressure               │
+│  - Commits code                     │
+│  - Writes checkpoint                │
+│  - Exits                            │
+│                                     │
+│  Context: fresh per task, 100% avail│
+└─────────────────────────────────────┘
+```
+
+## Implementation
+
+### 1. Orchestrator Prompt Pattern
+
+When starting a Ralph loop:
+
+```
+I am the orchestrator. I will:
+1. Read PRD to find next task
+2. Use Task tool to spawn implementation agent
+3. Wait for checkpoint
+4. Update PRD and continue
+
+I will NOT write code directly. Sub-agents handle implementation.
+```
+
+### 2. Sub-Agent Spawn Template
+
+```typescript
+// Use Task tool with Bash subagent for implementation
+Task({
+  subagent_type: "Bash",  // or custom "implement" agent
+  prompt: `
+    ## Task: ${task.id} - ${task.title}
+
+    ## Acceptance Criteria
+    ${task.acceptance_criteria.join('\n')}
+
+    ## Files to Create/Modify
+    ${task.files.join('\n')}
+
+    ## Instructions
+    1. Read existing code in ${task.files[0]} (if exists)
+    2. Implement the feature
+    3. Run: npm run typecheck && npm run build
+    4. If pass, commit with message: "feat(${task.id}): ${task.title}"
+    5. Write checkpoint to workspace/checkpoints/${task.id}.json
+
+    ## Checkpoint Format
+    {
+      "task_id": "${task.id}",
+      "completed_at": "ISO8601",
+      "summary": "what was done",
+      "files_touched": ["paths"],
+      "build_passed": true/false
+    }
+
+    Exit when checkpoint is written.
+  `
+})
+```
+
+### 3. Worker Config Addition
+
+```yaml
+# workers/assistant/email/worker.yaml
+execution:
+  mode: on-demand
+  spawn_per_task: true  # KEY: spawn sub-agent per task
+  orchestrator_only: true  # orchestrator doesn't implement directly
+```
+
+### 4. HQ CLAUDE.md Addition
+
+Add to `.claude/CLAUDE.md`:
+
+```markdown
+## Ralph Loop Execution (Multi-Task Projects)
+
+For projects with 3+ tasks:
+
+1. **Act as orchestrator only** - don't implement directly
+2. **Spawn sub-agents** for each task using Task tool
+3. **Keep context lean** by delegating implementation
+
+### Spawning Implementation Agents
+
+Use Task tool with focused prompts:
+
+- Include ONLY the current task spec
+- List specific files to modify
+- Specify back pressure commands
+- Require checkpoint on completion
+
+### Example
+
+Instead of:
+```
+[Orchestrator reads PRD, implements task 1, implements task 2...]
+```
+
+Do:
+```
+[Orchestrator reads PRD]
+[Spawns agent for task 1]
+[Reads checkpoint]
+[Spawns agent for task 2]
+[Reads checkpoint]
+...
+```
+```
+
+## Context Budget Guidelines
+
+| Role | Target Context | Activities |
+|------|---------------|------------|
+| Orchestrator | <30% | Read PRD, spawn agents, read checkpoints |
+| Sub-agent | 100% fresh | Implement ONE task, full context available |
+
+## Benefits
+
+1. **Orchestrator stays fast** - small context, quick responses
+2. **Sub-agents get full context** - fresh start per task
+3. **Checkpoints preserve state** - handoff without context loss
+4. **Parallel execution possible** - spawn multiple sub-agents
+
+## Anti-Patterns
+
+❌ Orchestrator implements code directly
+❌ Sub-agent works on multiple tasks
+❌ Skipping checkpoints between tasks
+❌ Loading full PRD into sub-agent (only current task)