create-hq 5.0.0 → 5.2.0

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

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

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

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

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

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

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

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

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