create-hq 5.0.0

package/template/knowledge/workers/skill-schema.md

@@ -0,0 +1,182 @@
+# Skill Interface Schema
+
+Formalized skill structure for consistent tooling and discovery. Inspired by Loom's tool system.
+
+## Skill Definition
+
+Skills can be defined as YAML (in worker.yaml) or as standalone .md files with YAML frontmatter.
+
+### Inline in worker.yaml
+
+```yaml
+worker:
+  id: cfo-worker
+  # ...
+
+skills:
+  - id: mrr
+    name: "MRR Report"
+    description: "Current MRR from Stripe subscriptions"
+
+    interface:
+      inputs:
+        - name: months
+          type: number
+          default: 1
+          description: "Months to include"
+      outputs:
+        - name: report
+          type: markdown
+          destination: workspace/reports/finance/
+
+    verification:
+      - command: "test -f {output}"
+        description: "Output file exists"
+
+    mutating: false
+```
+
+### Standalone Skill File
+
+`workers/{worker-id}/skills/{skill-id}.md`:
+
+```yaml
+---
+skill:
+  id: mrr
+  name: "MRR Report"
+  description: "Current MRR from Stripe subscriptions"
+
+  interface:
+    inputs:
+      - name: months
+        type: number
+        default: 1
+    outputs:
+      - name: report
+        type: markdown
+        destination: workspace/reports/finance/
+
+  verification:
+    - command: "test -f {output}"
+
+  mutating: false
+---
+
+# MRR Report Skill
+
+Instructions for executing this skill...
+```
+
+## Schema Reference
+
+### Core Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | yes | Unique skill identifier |
+| `name` | string | yes | Human-readable name |
+| `description` | string | yes | Brief description |
+| `mutating` | boolean | no | Triggers PostToolsHook if true |
+
+### Interface
+
+```yaml
+interface:
+  inputs:
+    - name: string         # parameter name
+      type: string         # string, number, boolean, array
+      required: boolean    # default: false
+      default: any         # default value
+      description: string  # help text
+
+  outputs:
+    - name: string         # output name
+      type: string         # markdown, json, file, git_commit
+      destination: string  # output path pattern
+```
+
+### Verification
+
+```yaml
+verification:
+  - command: string        # shell command (use {output} placeholder)
+    description: string    # what this verifies
+    must_pass: boolean     # default: true
+```
+
+### Mutating Flag
+
+If `mutating: true`:
+- PostToolsHook runs after execution
+- Thread auto-saved
+- Metrics logged
+
+Mutating skills typically:
+- Write files
+- Make git commits
+- Modify external state
+
+## Input Types
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `string` | Text input | `"customer-cube"` |
+| `number` | Numeric | `6` |
+| `boolean` | True/false | `true` |
+| `array` | List | `["a", "b"]` |
+| `date` | ISO date | `"2026-01-23"` |
+| `path` | File path | `"workspace/reports/"` |
+
+## Output Types
+
+| Type | Description |
+|------|-------------|
+| `markdown` | Markdown file |
+| `json` | JSON file |
+| `file` | Generic file |
+| `git_commit` | Creates commit |
+| `console` | Prints to console |
+
+## Example Skills
+
+### Read-Only (non-mutating)
+
+```yaml
+skills:
+  - id: mrr
+    name: "MRR Report"
+    description: "Current MRR"
+    interface:
+      outputs:
+        - type: console
+    verification: []
+    mutating: false
+```
+
+### File-Generating (mutating)
+
+```yaml
+skills:
+  - id: monthly-report
+    name: "Monthly Report"
+    description: "Generate monthly financial report"
+    interface:
+      inputs:
+        - name: month
+          type: string
+          required: true
+      outputs:
+        - name: report
+          type: markdown
+          destination: "workspace/reports/finance/{month}-report.md"
+    verification:
+      - command: "test -f workspace/reports/finance/{month}-report.md"
+    mutating: true
+```
+
+## See Also
+
+- [Worker Framework](./README.md)
+- [State Machine](./state-machine.md)
+- [Loom Tools](../loom/tools.md) - Inspiration

package/template/knowledge/workers/state-machine.md

@@ -0,0 +1,102 @@
+# Worker State Machine
+
+Workers follow an explicit state machine for predictable execution. Inspired by Loom's agent FSM.
+
+## States
+
+```
+Idle → Loading → Planning → Executing → Verifying → PostHook → Completed
+                              ↓
+                            Error → (retry or fail)
+```
+
+| State | Description |
+|-------|-------------|
+| `idle` | Worker ready, no active task |
+| `loading` | Loading context (worker.yaml, knowledge files) |
+| `planning` | Analyzing task, determining approach |
+| `executing` | Running skill logic |
+| `verifying` | Running verification checks |
+| `post_hook` | Auto-checkpoint, metrics logging |
+| `completed` | Skill finished successfully |
+| `error` | Recoverable error, may retry |
+
+## State Transitions
+
+| From | Event | To |
+|------|-------|----|
+| idle | skill_requested | loading |
+| loading | context_loaded | planning |
+| loading | load_failed | error |
+| planning | plan_ready | executing |
+| executing | execution_done | verifying |
+| executing | execution_failed | error |
+| verifying | verification_passed | post_hook |
+| verifying | verification_failed | error |
+| post_hook | hook_complete | completed |
+| error | retry | loading |
+| error | max_retries | completed (with error) |
+
+## State in Thread
+
+When saving a thread, capture current worker state:
+
+```json
+{
+  "worker": {
+    "id": "{worker-id}",
+    "skill": "mrr",
+    "state": "completed",
+    "started_at": "ISO8601",
+    "completed_at": "ISO8601",
+    "error": null
+  }
+}
+```
+
+## Hooks
+
+### post_execute
+
+Runs after successful execution, before completion:
+- `auto_checkpoint` - Save thread to workspace/threads/
+- `log_metrics` - Append to workspace/metrics/metrics.jsonl
+
+### on_error
+
+Runs when entering error state:
+- `log_error` - Record error details
+- `checkpoint_error_state` - Save thread with error info
+
+## worker.yaml Schema Addition
+
+```yaml
+worker:
+  id: example-worker
+  # ... existing fields ...
+
+state_machine:
+  enabled: true
+  max_retries: 1
+
+  hooks:
+    post_execute:
+      - auto_checkpoint
+      - log_metrics
+    on_error:
+      - log_error
+      - checkpoint_error_state
+```
+
+## Benefits
+
+1. **Predictable** - Every worker follows same lifecycle
+2. **Debuggable** - State captured in threads
+3. **Resilient** - Retry logic built-in
+4. **Observable** - Metrics on state transitions
+
+## See Also
+
+- [Thread Schema](../hq-core/thread-schema.md) - Thread format
+- [Loom State Machine](../loom/state-machine.md) - Inspiration
+- [Worker Framework](./README.md) - Worker docs

package/template/knowledge/workers/templates/base-worker.yaml

@@ -0,0 +1,73 @@
+# Base Worker Template
+# Copy and customize for your worker
+
+worker:
+  id: my-worker              # unique identifier
+  name: "My Worker"          # human-readable name
+  type: CodeWorker           # CodeWorker, SocialWorker, ResearchWorker, OpsWorker
+  version: "1.0"
+
+identity:
+  # Choose one:
+  # persona: your-name
+  # company_context: companies/acme/
+  # voice_guide: knowledge/my-brand/voice-style.md
+
+execution:
+  mode: on-demand            # on-demand, scheduled, event-triggered
+  # schedule: "0 9 * * *"    # cron format (if scheduled)
+  max_runtime: 15m
+  retry_attempts: 3
+
+context:
+  base:                      # always loaded
+    - path/to/required/file.md
+  dynamic:                   # loaded per task
+    - path/to/task/context/
+  exclude:                   # never load
+    - "*.test.*"
+    - node_modules/
+
+verification:
+  pre_execute: []            # checks before starting
+  post_execute:              # checks before marking done
+    - check: output_valid
+  approval_required: false   # true = human reviews before action
+
+tasks:
+  source: path/to/tasks.json # or prd.json
+  format: simple             # simple, prd
+  one_at_a_time: true        # always true (Ralph principle)
+
+output:
+  destination: path/to/output/
+  format: markdown           # markdown, json, git_commit
+
+audit:
+  log: workers/logs/my-worker.log
+  progress: workers/progress/my-worker.txt
+
+# State Machine (Loom pattern)
+state_machine:
+  enabled: true
+  max_retries: 1
+
+  hooks:
+    post_execute:
+      - auto_checkpoint          # save thread to workspace/threads/
+      - log_metrics              # append to workspace/metrics/metrics.jsonl
+    on_error:
+      - log_error
+      - checkpoint_error_state
+
+instructions: |
+  Worker-specific instructions go here.
+
+  Protocol:
+  1. Step one
+  2. Step two
+  3. Step three
+
+  Never:
+  - Thing to avoid
+  - Another thing to avoid

package/template/knowledge/workers/templates/code-worker.yaml

@@ -0,0 +1,85 @@
+# Code Worker Template
+# For implementing features, fixing bugs, refactoring
+
+worker:
+  id: code-{project}
+  name: "{Project} Code Worker"
+  type: CodeWorker
+  version: "1.0"
+
+identity:
+  company_context: companies/{company}/
+
+execution:
+  mode: on-demand
+  max_runtime: 30m
+  retry_attempts: 3
+
+context:
+  base:
+    - companies/{company}/README.md
+  dynamic:
+    - repos/{visibility}/{repo}/src/
+  exclude:
+    - "*.test.*"
+    - node_modules/
+    - dist/
+    - .git/
+
+verification:
+  pre_execute:
+    - check: branch_clean
+      command: "git status --porcelain"
+  post_execute:
+    - check: tests
+      command: "npm test"
+    - check: lint
+      command: "npm run lint"
+    - check: typecheck
+      command: "npm run typecheck"
+    - check: build
+      command: "npm run build"
+  approval_required: false  # auto-commit if all pass
+
+tasks:
+  source: workers/code/{id}/prd.json
+  format: prd
+  one_at_a_time: true
+
+output:
+  destination: null         # commits directly to repo
+  format: git_commit
+
+audit:
+  log: workers/code/logs/{id}.log
+  progress: workers/code/progress/{id}.txt
+
+instructions: |
+  You are a code worker for {project}.
+
+  Tech Stack:
+  - [List technologies]
+
+  Protocol:
+  1. Read PRD, find first item where passes: false
+  2. Implement ONLY that feature
+  3. Write tests for new functionality
+  4. Run all verification checks
+  5. If ALL pass: commit with conventional message, update PRD
+  6. If ANY fail: fix and retry (up to retry_attempts)
+  7. Log progress
+
+  Commit Format:
+  feat(scope): short description
+
+  - Detail 1
+  - Detail 2
+
+  Implements: {feature-id}
+
+  Never:
+  - Modify multiple features per iteration
+  - Skip tests
+  - Use `any` type (TypeScript)
+  - Leave console.logs in production
+  - Commit without passing all checks

package/template/knowledge/workers/templates/skill.yaml

@@ -0,0 +1,49 @@
+# Skill Template
+# Use as YAML frontmatter in .md skill files, or inline in worker.yaml
+
+skill:
+  id: my-skill               # unique within worker
+  name: "My Skill"           # human-readable name
+  description: "What this skill does"
+
+  interface:
+    inputs:
+      - name: param1
+        type: string         # string, number, boolean, array, date, path
+        required: false
+        default: "default-value"
+        description: "Parameter description"
+
+      - name: param2
+        type: number
+        required: false
+        default: 1
+
+    outputs:
+      - name: report
+        type: markdown       # markdown, json, file, git_commit, console
+        destination: "workspace/reports/{name}.md"  # path pattern
+
+  verification:
+    - command: "test -f {output}"
+      description: "Output file exists"
+      must_pass: true
+
+  # Triggers PostToolsHook (auto-checkpoint, metrics) if true
+  mutating: false
+
+# --- Below this line goes in the .md file body ---
+#
+# # My Skill
+#
+# ## Purpose
+# What this skill accomplishes.
+#
+# ## Process
+# 1. First step
+# 2. Second step
+# 3. Third step
+#
+# ## Notes
+# - Important consideration
+# - Another note

package/template/knowledge/workers/templates/social-worker.yaml

@@ -0,0 +1,70 @@
+# Social Worker Template
+# For X/Twitter, LinkedIn, etc.
+
+worker:
+  id: social-{platform}-{persona}
+  name: "{Persona}'s {Platform} Worker"
+  type: SocialWorker
+  version: "1.0"
+
+identity:
+  persona: {persona}
+  voice_guide: knowledge/{persona}/voice-style.md
+
+execution:
+  mode: scheduled
+  schedule: "0 9,14,19 * * *"  # 9am, 2pm, 7pm
+  max_runtime: 10m
+  retry_attempts: 2
+
+context:
+  base:
+    - knowledge/{persona}/voice-style.md
+    - knowledge/{persona}/profile.md
+  dynamic:
+    - social-content/trends/
+    - social-content/drafts/{platform}/
+
+verification:
+  post_execute:
+    - check: character_count
+      max: 280                 # adjust per platform
+    - check: voice_consistency
+      reference: knowledge/{persona}/voice-style.md
+  approval_required: true      # always review before posting
+
+tasks:
+  source: workers/social/{id}/queue.json
+  format: simple
+  one_at_a_time: true
+
+output:
+  destination: social-content/drafts/{platform}/
+  format: markdown
+  naming: "{date}-{time}-draft.md"
+
+audit:
+  log: workers/social/logs/{id}.log
+  progress: workers/social/progress/{id}.txt
+
+instructions: |
+  You are {persona}'s {platform} worker.
+
+  Task Types:
+  - generate: Create original post on given topic
+  - respond: Draft reply to specified thread
+  - curate: Find content to repost with commentary
+
+  Protocol:
+  1. Check queue for pending task
+  2. Execute based on task type
+  3. Save draft to output destination
+  4. Log progress
+
+  Style Guidelines:
+  - [Add platform-specific style notes]
+
+  Never:
+  - Post without approval
+  - Use corporate jargon
+  - Over-explain

package/template/modules/examples/full-manifest.yaml

@@ -0,0 +1,92 @@
+# Example: Full HQ Modules Manifest
+# Shows various module configurations for different use cases
+
+version: "1.0"
+
+modules:
+  # =============================================================================
+  # CORE MODULE
+  # Official HQ updates - recommended for all users
+  # =============================================================================
+  - name: hq-core
+    repo: https://github.com/coreyepstein/hq-starter-kit.git
+    branch: main
+    strategy: merge
+    access: public
+    paths:
+      # Core knowledge bases
+      knowledge/Ralph: knowledge/Ralph
+      knowledge/workers: knowledge/workers
+      # Commands and configuration
+      .claude/commands: .claude/commands
+      # Worker templates
+      workers/examples: workers/examples
+
+  # =============================================================================
+  # COMPANY MODULES
+  # Shared across your organization
+  # =============================================================================
+
+  # Company-wide shared resources
+  - name: acme-shared
+    repo: https://github.com/acme-corp/hq-shared.git
+    branch: main
+    strategy: link
+    access: team
+    paths:
+      # Company knowledge
+      knowledge/company: knowledge/acme
+      knowledge/processes: knowledge/acme/processes
+      # Shared worker configurations
+      workers/shared: workers/acme-shared
+      # Company templates
+      templates: templates/acme
+
+  # Engineering team module
+  - name: acme-engineering
+    repo: https://github.com/acme-corp/hq-engineering.git
+    branch: main
+    strategy: merge
+    access: "role:engineer"
+    paths:
+      # Tech stack documentation
+      knowledge/tech-stack: knowledge/tech-stack
+      # Code review guidelines
+      knowledge/code-review: knowledge/engineering/code-review
+      # Engineering-specific workers
+      workers/code: workers/engineering
+
+  # Design team module
+  - name: acme-design
+    repo: https://github.com/acme-corp/hq-design.git
+    branch: main
+    strategy: copy
+    access: "role:designer"
+    paths:
+      knowledge/design-system: knowledge/design-system
+      knowledge/brand: knowledge/brand
+
+  # =============================================================================
+  # COMMUNITY/THIRD-PARTY MODULES
+  # Optional integrations
+  # =============================================================================
+
+  # Social media management extension
+  - name: social-pro
+    repo: https://github.com/hq-community/social-pro.git
+    branch: stable
+    strategy: merge
+    access: public
+    paths:
+      workers/social: workers/social-extended
+      knowledge/social-strategy: knowledge/social
+
+  # Research and analysis tools
+  - name: research-toolkit
+    repo: https://github.com/hq-community/research-toolkit.git
+    branch: main
+    strategy: copy
+    access: public
+    paths:
+      workers/research: workers/research
+      knowledge/research-methods: knowledge/research

package/template/modules/examples/minimal.yaml

@@ -0,0 +1,14 @@
+# Example: Minimal modules.yaml
+# Just the essentials for getting started
+
+version: "1.0"
+
+modules:
+  - name: hq-core
+    repo: https://github.com/coreyepstein/hq-starter-kit.git
+    branch: main
+    strategy: merge
+    access: public
+    paths:
+      knowledge/Ralph: knowledge/Ralph
+      .claude/commands: .claude/commands