create-hq 5.0.0

package/template/knowledge/hq/index-md-spec.md

@@ -0,0 +1,74 @@
+# INDEX.md Specification
+
+Standard for hierarchical INDEX.md files across HQ directories.
+
+## Template
+
+```markdown
+# {Directory Name}
+
+> Auto-generated. Updated: {YYYY-MM-DD}
+
+| Name | Description |
+|------|-------------|
+| `item/` | 1-line description |
+```
+
+Optional 1-2 line notes section at bottom for usage hints (e.g., "Load workers via `/run {id}`").
+
+## Description Extraction
+
+| File type | Source |
+|-----------|--------|
+| `.md` | First `#` heading |
+| `.yaml` | `description:` field |
+| `.json` | `name` or `description` field |
+| Directory | File count + purpose summary |
+
+Max 80 chars per description. If no metadata extractable, use filename.
+
+## Variants
+
+- `projects/INDEX.md` → add `Status` column (active/completed/archived)
+- `workspace/orchestrator/INDEX.md` → add `Progress` column (e.g. "5/11 45%")
+- `workspace/reports/INDEX.md` → add `Date` column
+
+## Locations (10 directories)
+
+1. `projects/`
+2. `companies/{company-1}/knowledge/`
+3. `companies/{company-2}/knowledge/`
+4. `companies/{company-3}/knowledge/`
+5. `knowledge/`
+6. `workers/public/`
+7. `workers/private/`
+8. `workspace/orchestrator/`
+9. `workspace/reports/`
+10. `workspace/social-drafts/`
+
+Root `INDEX.md` and `workspace/threads/INDEX.md` also exist but follow their own formats.
+
+## Regeneration Rules
+
+- Always full-rewrite (not incremental patch). Idempotent.
+- Skip: `INDEX.md` itself, `.DS_Store`, `node_modules/`, dotfiles
+- Sort entries: directories first, then files, alphabetical within each group
+- Timestamp: use current date in YYYY-MM-DD format
+
+## Update Triggers
+
+| Command | INDEX.md files updated |
+|---------|----------------------|
+| `/checkpoint` | Root, threads/, + touched company knowledge dirs |
+| `/handoff` | Root, threads/, orchestrator/, + touched company knowledge dirs |
+| `/reanchor` | Validates freshness, reads indexes for context |
+| `/cleanup --reindex` | ALL INDEX.md files (full rebuild) |
+| `/prd` | `projects/` |
+| `/run-project` | `projects/`, `workspace/orchestrator/` |
+| `/newworker` | `workers/public/` or `workers/private/` |
+| `/contentidea`, `/suggestposts`, `/post-now` | `workspace/social-drafts/` |
+| Report generation | `workspace/reports/` |
+
+## qmd
+
+INDEX.md files are excluded from qmd indexing via `.qmdignore`. They are navigation aids, not searchable content.

package/template/knowledge/hq/thread-schema.md

@@ -0,0 +1,153 @@
+# Thread Schema
+
+Threads persist complete session state including conversation summary, git context, and worker execution info. Inspired by Loom's thread-system.
+
+## Location
+
+`workspace/threads/{thread_id}.json`
+
+## Thread ID Format
+
+`T-{YYYYMMDD}-{HHMMSS}-{slug}`
+
+Example: `T-20260123-143052-mrr-report`
+
+## Schema
+
+```json
+{
+  "thread_id": "T-20260123-143052-mrr-report",
+  "version": 1,
+  "created_at": "2026-01-23T14:30:52.000Z",
+  "updated_at": "2026-01-23T14:35:00.000Z",
+
+  "workspace_root": "~/Documents/HQ",
+  "cwd": "repos/private/{company}",
+
+  "git": {
+    "branch": "main",
+    "remote_url": "git@github.com:user/repo.git",
+    "initial_commit": "abc1234",
+    "current_commit": "def5678",
+    "commits_made": [
+      "def5678: feat: add MRR calculation"
+    ],
+    "dirty": false
+  },
+
+  "worker": {
+    "id": "{worker-id}",
+    "skill": "mrr",
+    "state": "completed",
+    "started_at": "2026-01-23T14:30:52.000Z",
+    "completed_at": "2026-01-23T14:35:00.000Z"
+  },
+
+  "conversation_summary": "Generated MRR report showing $45,230 current MRR with 3.2% growth",
+  "files_touched": [
+    "workspace/reports/finance/2026-01-23-mrr.md"
+  ],
+  "next_steps": [],
+
+  "metadata": {
+    "title": "MRR Report Jan 2026",
+    "tags": ["finance", "{company}", "mrr"]
+  }
+}
+```
+
+## Fields
+
+### Core
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `thread_id` | string | Unique identifier |
+| `version` | number | Schema version (currently 1) |
+| `created_at` | ISO8601 | Thread creation time |
+| `updated_at` | ISO8601 | Last update time |
+
+### Context
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `workspace_root` | string | HQ root path |
+| `cwd` | string | Working directory (relative to root) |
+
+### Git State
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `git.branch` | string | Current branch |
+| `git.remote_url` | string | Origin remote URL |
+| `git.initial_commit` | string | Commit SHA at thread start |
+| `git.current_commit` | string | Commit SHA at thread end |
+| `git.commits_made` | string[] | Commits created during session |
+| `git.dirty` | boolean | Uncommitted changes present |
+
+### Worker State
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `worker.id` | string | Worker ID (if applicable) |
+| `worker.skill` | string | Skill executed |
+| `worker.state` | enum | `idle`, `loading`, `executing`, `verifying`, `completed`, `error` |
+| `worker.started_at` | ISO8601 | Execution start |
+| `worker.completed_at` | ISO8601 | Execution end |
+
+### Results
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `conversation_summary` | string | What was accomplished |
+| `files_touched` | string[] | Files created/modified |
+| `next_steps` | string[] | Remaining work |
+
+### Metadata
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `metadata.title` | string | Human-readable title |
+| `metadata.tags` | string[] | Searchable tags |
+
+## State Values
+
+Worker states follow the FSM:
+
+```
+idle → loading → executing → verifying → completed
+                    ↓
+                  error
+```
+
+## Usage
+
+### Creating a Thread
+
+```bash
+# Captured by /checkpoint command
+/checkpoint mrr-report
+```
+
+### Searching Threads
+
+```bash
+# Via /search command
+/search mrr
+```
+
+### Listing Recent
+
+```bash
+ls -lt workspace/threads/ | head -10
+```
+
+## Backward Compatibility
+
+Old checkpoints in `workspace/checkpoints/` remain valid. Threads are a superset with richer git context.
+
+## See Also
+
+- [Loom thread-system](../loom/thread-system.md) - Inspiration
+- `/checkpoint` command - Creates threads
+- `/search` command - Searches threads

package/template/knowledge/hq-core/checkpoint-schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "hq-checkpoint-schema",
+  "title": "HQ Checkpoint Schema",
+  "description": "Canonical checkpoint format for HQ task progress tracking",
+  "type": "object",
+  "required": ["task_id", "completed_at", "summary"],
+  "properties": {
+    "task_id": {
+      "type": "string",
+      "description": "Unique identifier for the task (e.g., US-001, feature-name)"
+    },
+    "completed_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO8601 timestamp when checkpoint was created"
+    },
+    "summary": {
+      "type": "string",
+      "description": "Brief description of work completed"
+    },
+    "files_touched": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "List of files modified during this work"
+    },
+    "build_passed": {
+      "type": "boolean",
+      "description": "Whether build/tests passed after this work"
+    },
+    "commit": {
+      "type": "string",
+      "description": "Git commit hash if code was committed"
+    },
+    "next_steps": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Suggested next actions for future sessions"
+    },
+    "notes": {
+      "type": "string",
+      "description": "Additional context or observations"
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Arbitrary additional data",
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": false
+}

package/template/knowledge/hq-core/index-md-spec.md

@@ -0,0 +1,74 @@
+# INDEX.md Specification
+
+Standard for hierarchical INDEX.md files across HQ directories.
+
+## Template
+
+```markdown
+# {Directory Name}
+
+> Auto-generated. Updated: {YYYY-MM-DD}
+
+| Name | Description |
+|------|-------------|
+| `item/` | 1-line description |
+```
+
+Optional 1-2 line notes section at bottom for usage hints (e.g., "Load workers via `/run {id}`").
+
+## Description Extraction
+
+| File type | Source |
+|-----------|--------|
+| `.md` | First `#` heading |
+| `.yaml` | `description:` field |
+| `.json` | `name` or `description` field |
+| Directory | File count + purpose summary |
+
+Max 80 chars per description. If no metadata extractable, use filename.
+
+## Variants
+
+- `projects/INDEX.md` → add `Status` column (active/completed/archived)
+- `workspace/orchestrator/INDEX.md` → add `Progress` column (e.g. "5/11 45%")
+- `workspace/reports/INDEX.md` → add `Date` column
+
+## Locations (10 directories)
+
+1. `projects/`
+2. `companies/{company-1}/knowledge/`
+3. `companies/{company-2}/knowledge/`
+4. `companies/{company-3}/knowledge/`
+5. `knowledge/`
+6. `workers/public/`
+7. `workers/private/`
+8. `workspace/orchestrator/`
+9. `workspace/reports/`
+10. `workspace/social-drafts/`
+
+Root `INDEX.md` and `workspace/threads/INDEX.md` also exist but follow their own formats.
+
+## Regeneration Rules
+
+- Always full-rewrite (not incremental patch). Idempotent.
+- Skip: `INDEX.md` itself, `.DS_Store`, `node_modules/`, dotfiles
+- Sort entries: directories first, then files, alphabetical within each group
+- Timestamp: use current date in YYYY-MM-DD format
+
+## Update Triggers
+
+| Command | INDEX.md files updated |
+|---------|----------------------|
+| `/checkpoint` | Root, threads/, + touched company knowledge dirs |
+| `/handoff` | Root, threads/, orchestrator/, + touched company knowledge dirs |
+| `/reanchor` | Validates freshness, reads indexes for context |
+| `/cleanup --reindex` | ALL INDEX.md files (full rebuild) |
+| `/prd` | `projects/` |
+| `/run-project` | `projects/`, `workspace/orchestrator/` |
+| `/newworker` | `workers/public/` or `workers/private/` |
+| `/contentidea`, `/suggestposts`, `/post-now` | `workspace/social-drafts/` |
+| Report generation | `workspace/reports/` |
+
+## qmd
+
+INDEX.md files are excluded from qmd indexing via `.qmdignore`. They are navigation aids, not searchable content.

package/template/knowledge/hq-core/thread-schema.md

@@ -0,0 +1,153 @@
+# Thread Schema
+
+Threads persist complete session state including conversation summary, git context, and worker execution info. Inspired by Loom's thread-system.
+
+## Location
+
+`workspace/threads/{thread_id}.json`
+
+## Thread ID Format
+
+`T-{YYYYMMDD}-{HHMMSS}-{slug}`
+
+Example: `T-20260123-143052-mrr-report`
+
+## Schema
+
+```json
+{
+  "thread_id": "T-20260123-143052-mrr-report",
+  "version": 1,
+  "created_at": "2026-01-23T14:30:52.000Z",
+  "updated_at": "2026-01-23T14:35:00.000Z",
+
+  "workspace_root": "~/Documents/HQ",
+  "cwd": "repos/private/{company}",
+
+  "git": {
+    "branch": "main",
+    "remote_url": "git@github.com:user/repo.git",
+    "initial_commit": "abc1234",
+    "current_commit": "def5678",
+    "commits_made": [
+      "def5678: feat: add MRR calculation"
+    ],
+    "dirty": false
+  },
+
+  "worker": {
+    "id": "{worker-id}",
+    "skill": "mrr",
+    "state": "completed",
+    "started_at": "2026-01-23T14:30:52.000Z",
+    "completed_at": "2026-01-23T14:35:00.000Z"
+  },
+
+  "conversation_summary": "Generated MRR report showing $45,230 current MRR with 3.2% growth",
+  "files_touched": [
+    "workspace/reports/finance/2026-01-23-mrr.md"
+  ],
+  "next_steps": [],
+
+  "metadata": {
+    "title": "MRR Report Jan 2026",
+    "tags": ["finance", "{company}", "mrr"]
+  }
+}
+```
+
+## Fields
+
+### Core
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `thread_id` | string | Unique identifier |
+| `version` | number | Schema version (currently 1) |
+| `created_at` | ISO8601 | Thread creation time |
+| `updated_at` | ISO8601 | Last update time |
+
+### Context
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `workspace_root` | string | HQ root path |
+| `cwd` | string | Working directory (relative to root) |
+
+### Git State
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `git.branch` | string | Current branch |
+| `git.remote_url` | string | Origin remote URL |
+| `git.initial_commit` | string | Commit SHA at thread start |
+| `git.current_commit` | string | Commit SHA at thread end |
+| `git.commits_made` | string[] | Commits created during session |
+| `git.dirty` | boolean | Uncommitted changes present |
+
+### Worker State
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `worker.id` | string | Worker ID (if applicable) |
+| `worker.skill` | string | Skill executed |
+| `worker.state` | enum | `idle`, `loading`, `executing`, `verifying`, `completed`, `error` |
+| `worker.started_at` | ISO8601 | Execution start |
+| `worker.completed_at` | ISO8601 | Execution end |
+
+### Results
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `conversation_summary` | string | What was accomplished |
+| `files_touched` | string[] | Files created/modified |
+| `next_steps` | string[] | Remaining work |
+
+### Metadata
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `metadata.title` | string | Human-readable title |
+| `metadata.tags` | string[] | Searchable tags |
+
+## State Values
+
+Worker states follow the FSM:
+
+```
+idle → loading → executing → verifying → completed
+                    ↓
+                  error
+```
+
+## Usage
+
+### Creating a Thread
+
+```bash
+# Captured by /checkpoint command
+/checkpoint mrr-report
+```
+
+### Searching Threads
+
+```bash
+# Via /search command
+/search mrr
+```
+
+### Listing Recent
+
+```bash
+ls -lt workspace/threads/ | head -10
+```
+
+## Backward Compatibility
+
+Old checkpoints in `workspace/checkpoints/` remain valid. Threads are a superset with richer git context.
+
+## See Also
+
+- [Loom thread-system](../loom/thread-system.md) - Inspiration
+- `/checkpoint` command - Creates threads
+- `/search` command - Searches threads

package/template/knowledge/loom/README.md

@@ -0,0 +1,51 @@
+# Loom
+
+AI-powered coding agent built in Rust by Geoffrey Huntley.
+
+**Repo**: `repos/public/loom/` | **GitHub**: https://github.com/ghuntley/loom
+
+## What Is Loom?
+
+Loom is a REPL-based AI coding agent with:
+- **96 Rust crates** organized as a Cargo workspace
+- **Server-side LLM proxy** - API keys never leave the server
+- **Tool system** for file ops, bash, web search
+- **Weaver** - remote execution via K8s pods
+- **Svelte 5 web frontend**
+
+## Core Principles
+
+1. **Modularity** - Clean separation via trait implementations
+2. **Extensibility** - Easy addition of LLM providers and tools
+3. **Reliability** - Retry mechanisms, structured logging
+
+## Knowledge Base
+
+| Doc | Description |
+|-----|-------------|
+| [architecture.md](architecture.md) | System design, crate organization, tech stack |
+| [state-machine.md](state-machine.md) | Core agent loop (7-state FSM) |
+| [tools.md](tools.md) | Tool trait, registry, built-in tools |
+| [llm-proxy.md](llm-proxy.md) | LLM provider abstraction, SSE streaming |
+| [thread-system.md](thread-system.md) | Conversation persistence, search |
+| [weaver.md](weaver.md) | Remote execution, K8s, WireGuard |
+| [web-frontend.md](web-frontend.md) | Svelte 5 runes, xstate patterns |
+| [code-style.md](code-style.md) | Rust/Svelte conventions |
+
+## Quick Reference
+
+```
+loom/
+├── crates/           # 96 Rust crates
+├── web/loom-web/     # Svelte 5 frontend
+├── specs/            # 57 design specs
+├── infra/            # Nix/K8s infrastructure
+└── AGENTS.md         # Development guidelines
+```
+
+## Key Files
+
+- `AGENTS.md` - Build commands, deployment, code style
+- `specs/README.md` - Spec index by category
+- `specs/state-machine.md` - Agent FSM spec
+- `crates/loom-common-core/src/` - Core types and state machine

package/template/knowledge/loom/architecture.md

@@ -0,0 +1,125 @@
+# Loom Architecture
+
+## Workspace Layout
+
+```
+loom/
+├── crates/           # 96 Rust crates
+├── web/loom-web/     # Svelte 5 frontend
+├── specs/            # 57 design specifications
+├── infra/            # Nix/K8s infrastructure
+│   ├── nixos-modules/
+│   ├── pkgs/
+│   └── machines/
+├── docker/           # Container configs
+├── scripts/          # Build utilities
+├── tools/            # Tool definitions
+└── ide/vscode/       # VS Code extension
+```
+
+## Crate Categories
+
+### Core (shared types & abstractions)
+| Crate | Purpose |
+|-------|---------|
+| `loom-common-core` | State machine, agent, LLM types, tool types |
+| `loom-common-thread` | Thread/conversation model |
+| `loom-common-config` | Shared configuration |
+| `loom-common-http` | reqwest wrapper with retry |
+| `loom-common-secret` | Secret handling (auto-redact) |
+
+### CLI
+| Crate | Purpose |
+|-------|---------|
+| `loom-cli` | Main CLI application |
+| `loom-cli-tools` | Tool implementations |
+| `loom-cli-auto-commit` | Git auto-commit hook |
+| `loom-cli-git` | Git integration |
+| `loom-cli-spool` | VCS (spool/jj) support |
+
+### Server
+| Crate | Purpose |
+|-------|---------|
+| `loom-server` | HTTP API (axum), migrations, main service |
+| `loom-server-api` | API endpoints |
+| `loom-server-db` | SQLite via sqlx |
+| `loom-server-llm-service` | LLM orchestration |
+| `loom-server-llm-proxy` | Client-side proxy handling |
+| `loom-server-llm-anthropic` | Claude integration |
+| `loom-server-llm-openai` | OpenAI integration |
+| `loom-server-llm-vertex` | Google Vertex AI |
+
+### Server Auth
+| Crate | Purpose |
+|-------|---------|
+| `loom-server-auth` | Auth framework |
+| `loom-server-auth-github` | GitHub OAuth |
+| `loom-server-auth-google` | Google OAuth |
+| `loom-server-auth-magiclink` | Magic link auth |
+| `loom-server-auth-okta` | Okta SAML |
+| `loom-server-auth-devicecode` | Device code flow |
+
+### TUI (Terminal UI)
+| Crate | Purpose |
+|-------|---------|
+| `loom-tui-app` | Main TUI application |
+| `loom-tui-core` | Core types |
+| `loom-tui-component` | Component framework |
+| `loom-tui-widget-*` | Widgets (header, input, markdown, message-list, modal, scrollable, spinner, status-bar, thread-list, tool-panel) |
+
+### Observability
+| Crate | Purpose |
+|-------|---------|
+| `loom-analytics` | PostHog-style analytics |
+| `loom-crash` | Crash reporting |
+| `loom-crons` | Cron job monitoring |
+| `loom-server-sessions` | Session tracking |
+
+### Weaver (Remote Execution)
+| Crate | Purpose |
+|-------|---------|
+| `loom-weaver-*` | Remote execution stack |
+| `loom-wgtunnel-*` | WireGuard tunneling |
+| `loom-weaver-ebpf` | eBPF syscall tracing |
+
+## Server-Client Architecture
+
+```
+┌─────────────┐      HTTP       ┌─────────────┐     Provider API    ┌─────────────┐
+│  loom-cli   │ ───────────────▶│ loom-server │ ──────────────────▶ │  Anthropic  │
+│             │ /proxy/{provider}│             │                     │   OpenAI    │
+│ ProxyLlm-   │  /complete      │  LlmService │                     │  Vertex AI  │
+│ Client      │  /stream        │             │                     │             │
+└─────────────┘ ◀─────────────  └─────────────┘ ◀────────────────── └─────────────┘
+                  SSE stream                        SSE stream
+```
+
+**Key insight**: API keys stay server-side. Clients use proxy endpoints.
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|------------|
+| Backend | Rust, Tokio async runtime, axum HTTP |
+| Database | SQLite with sqlx |
+| Web Frontend | Svelte 5 (runes), SvelteKit, Tailwind CSS 4, xstate |
+| Build | Cargo, Nix (cargo2nix for reproducible builds) |
+| Containers | Nix + Docker |
+| Orchestration | Kubernetes (for Weaver pods) |
+| i18n | GNU gettext with Lingui |
+| Testing | proptest (property-based), vitest (web) |
+| TUI | Ratatui 0.30 |
+
+## Database
+
+- SQLite via sqlx with compile-time query checking
+- Migrations in `crates/loom-server/migrations/`
+- Naming: `NNN_description.sql` (e.g., `020_scm_repos.sql`)
+- Auto-run on server startup
+
+## Deployment
+
+- Production runs NixOS with auto-update
+- `git push origin trunk` triggers deployment
+- Update service polls every 10 seconds
+- Health endpoint: `https://loom.ghuntley.com/health`