create-hq 5.0.0

package/template/.claude/commands/checkpoint.md

@@ -0,0 +1,127 @@
+---
+description: Save checkpoint and check context status
+allowed-tools: Write, Bash, Read
+argument-hint: [task-id]
+visibility: public
+---
+
+# /checkpoint - Save Progress
+
+Save current work state as a thread to survive context loss.
+
+**Task ID (optional):** $ARGUMENTS
+
+## Process
+
+1. **Generate thread ID** if not provided
+   - Format: `T-{YYYYMMDD}-{HHMMSS}-{slug}`
+   - Derive slug from recent work (e.g., `mrr-report`, `email-fix`)
+
+2. **Capture git state**
+   ```bash
+   git rev-parse --abbrev-ref HEAD          # branch
+   git remote get-url origin 2>/dev/null    # remote
+   git rev-parse --short HEAD               # current commit
+   git log --oneline -5                     # recent commits
+   git diff --name-only HEAD~3              # recently touched files
+   git status --porcelain                   # dirty check
+   ```
+
+3. **Capture knowledge repo git states**
+   Knowledge folders are separate git repos (symlinked). For any knowledge path in files_touched, capture its repo state:
+   ```bash
+   # For each knowledge repo with changes:
+   for symlink in knowledge/public/* knowledge/private/* companies/*/knowledge; do
+     [ -L "$symlink" ] || continue
+     repo_dir=$(cd "$symlink" && git rev-parse --show-toplevel 2>/dev/null) || continue
+     dirty=$(cd "$repo_dir" && git status --porcelain)
+     [ -z "$dirty" ] && continue
+     echo "$symlink: $(cd "$repo_dir" && git rev-parse --short HEAD) (dirty)"
+   done
+   ```
+   Include dirty knowledge repos in the thread JSON under `git.knowledge_repos`.
+
+4. **Gather session state**
+   - Summarize what was accomplished
+   - List files touched
+   - Identify next steps
+
+5. **Write thread** to `workspace/threads/{thread_id}.json` (include knowledge_repos from step 3):
+   ```json
+   {
+     "thread_id": "T-20260123-143052-mrr-report",
+     "version": 1,
+     "created_at": "ISO8601",
+     "updated_at": "ISO8601",
+
+     "workspace_root": "~/Documents/HQ",
+     "cwd": "current/working/dir",
+
+     "git": {
+       "branch": "main",
+       "remote_url": "git@github.com:...",
+       "initial_commit": "abc1234",
+       "current_commit": "def5678",
+       "commits_made": ["hash: message"],
+       "dirty": false,
+       "knowledge_repos": {
+         "knowledge-acme": {"commit": "abc1234", "dirty": true},
+         "knowledge-ralph": {"commit": "def5678", "dirty": false}
+       }
+     },
+
+     "worker": {
+       "id": "worker-id or null",
+       "skill": "skill-name or null",
+       "state": "completed"
+     },
+
+     "conversation_summary": "1-2 sentence summary",
+     "files_touched": ["relative/paths"],
+     "next_steps": ["remaining tasks"],
+
+     "metadata": {
+       "title": "Human-readable title",
+       "tags": ["searchable", "tags"]
+     }
+   }
+   ```
+
+6. **Also write legacy checkpoint** to `workspace/checkpoints/{task-id}.json` for backward compat
+
+7. **Update INDEX.md files**
+   - Regenerate `INDEX.md` at HQ root with current:
+     - Workers from `workers/registry.yaml`
+     - Recent threads from `workspace/threads/`
+     - Update timestamp
+   - Regenerate `workspace/threads/INDEX.md` (all threads, full table)
+   - Check files_touched for any `companies/*/knowledge/` paths — if found, regenerate that company's `knowledge/INDEX.md`
+   - See `knowledge/public/hq-core/index-md-spec.md` for INDEX format
+
+8. **Report**
+   ```
+   Thread saved: workspace/threads/{thread_id}.json
+
+   Summary: {summary}
+   Git: {branch} @ {commit} ({dirty ? "dirty" : "clean"})
+   Files: {count} files touched
+   Next: {next_steps or "Work complete"}
+
+   To hand off to fresh session: /handoff
+   ```
+
+## Thread vs Checkpoint
+
+| Feature | Thread (new) | Checkpoint (legacy) |
+|---------|--------------|---------------------|
+| Git context | Full (branch, commits, dirty) | Minimal |
+| Worker state | Captured | Not captured |
+| Location | workspace/threads/ | workspace/checkpoints/ |
+| Format | Rich JSON | Simple JSON |
+
+## Notes
+
+- Threads ensure work survives context clears
+- Run frequently during long sessions
+- If session feels long, suggest `/handoff`
+- Threads are searchable via `/search`

package/template/.claude/commands/cleanup.md

@@ -0,0 +1,307 @@
+---
+description: Audit and clean HQ to enforce current policies and migrate outdated structures
+allowed-tools: Task, Read, Glob, Grep, Bash, Write, Edit, AskUserQuestion
+argument-hint: [--audit | --migrate | --fix]
+visibility: public
+---
+
+# /cleanup - HQ Maintenance
+
+Audit HQ for policy violations, migrate outdated structures, and fix inconsistencies.
+
+**User's input:** $ARGUMENTS
+
+## Modes
+
+- **No args / --audit**: Report issues only (default, safe)
+- **--migrate**: Convert old formats to new (prd.json → README.md)
+- **--fix**: Auto-fix simple issues (git cleanup, archive stale files)
+- **--reindex**: Regenerate ALL INDEX.md files from disk (full rebuild)
+
+## The Job
+
+1. Run audit checks
+2. Report findings
+3. If --migrate or --fix: propose changes, ask confirmation, execute
+
+---
+
+## Audit Checks
+
+### 1. Project Structure
+
+**Policy**: All projects in `projects/` folder with `README.md`
+
+```bash
+# Find projects with only prd.json (no README)
+for dir in projects/*/; do
+  if [[ -f "${dir}prd.json" && ! -f "${dir}README.md" ]]; then
+    echo "MIGRATE: $dir has prd.json but no README.md"
+  fi
+done
+
+# Find projects outside projects/ folder
+find companies apps -name "prd.json" 2>/dev/null
+```
+
+**Violations**:
+- prd.json without README.md → needs migration
+- prd.json in companies/ or apps/ → needs relocation
+
+### 2. Worker Registry
+
+**Policy**: All workers indexed in `workers/registry.yaml`
+
+```bash
+# Find workers not in registry
+for dir in workers/public/*/ workers/private/*/; do
+  worker=$(basename "$dir")
+  if ! grep -q "id: $worker" workers/registry.yaml; then
+    echo "UNINDEXED: $worker"
+  fi
+done
+```
+
+### 3. Deprecated Directories
+
+**Policy**: No apps/ directory (use projects/ or workers/)
+
+```bash
+# Check if apps/ still exists
+if [[ -d "apps" ]]; then
+  echo "DEPRECATED: apps/ directory still exists"
+  ls apps/
+fi
+```
+
+### 4. Git Status
+
+**Policy**: Clean working tree, no orphaned deletions
+
+```bash
+git status --short
+```
+
+**Issues**:
+- Deleted files not committed
+- Untracked new files (should commit or ignore)
+- Modified submodules
+
+**Note:** Knowledge folders are symlinks to repos in `repos/public/` and `repos/private/` (gitignored). Symlinks themselves should be tracked by HQ git. Knowledge file changes are invisible to HQ git (they live in their own repos).
+
+### 4b. Knowledge Repo Status
+
+**Policy**: Knowledge repos should be clean (committed)
+
+```bash
+for symlink in knowledge/public/* knowledge/private/* companies/*/knowledge; do
+  [ -L "$symlink" ] || continue
+  repo_dir=$(cd "$symlink" && git rev-parse --show-toplevel 2>/dev/null) || continue
+  dirty=$(cd "$repo_dir" && git status --porcelain)
+  [ -z "$dirty" ] && continue
+  echo "DIRTY: $symlink → $repo_dir"
+done
+```
+
+**With --fix**: Auto-commit dirty knowledge repos:
+```bash
+(cd "$repo_dir" && git add -A && git commit -m "chore: cleanup commit")
+```
+
+### 5. Stale Threads & Checkpoints
+
+**Policy**: Archive threads/checkpoints older than 30 days
+
+```bash
+# Stale threads (new format)
+find workspace/threads -name "*.json" -mtime +30 2>/dev/null
+
+# Stale checkpoints (legacy format)
+find workspace/checkpoints -name "*.json" -mtime +30 2>/dev/null
+```
+
+### 6. Worker State Machine
+
+**Policy**: Workers should have state_machine section (Loom pattern)
+
+```bash
+# Find workers without state_machine
+for f in workers/*/worker.yaml workers/public/dev-team/*/worker.yaml; do
+  if [[ -f "$f" ]] && ! grep -q "state_machine:" "$f"; then
+    echo "MISSING: $f lacks state_machine section"
+  fi
+done
+```
+
+### 7. Orphaned Skills
+
+**Policy**: Skills only in `.claude/commands/` (not SKILL.md format)
+
+```bash
+# Find old SKILL.md format
+find . -name "SKILL.md" -not -path "./repos/*"
+```
+
+### 8. Stale INDEX.md Files
+
+**Policy**: INDEX.md files should exist and match directory contents. See `knowledge/public/hq-core/index-md-spec.md` for spec.
+
+**Expected locations:**
+- `projects/INDEX.md`
+- `companies/{company}/knowledge/INDEX.md` (for each company)
+- `knowledge/public/INDEX.md`
+- `workers/public/INDEX.md`
+- `workers/private/INDEX.md`
+- `workspace/orchestrator/INDEX.md`
+- `workspace/reports/INDEX.md`
+- `workspace/social-drafts/INDEX.md`
+
+For each:
+1. Check if INDEX.md exists → flag MISSING if not
+2. Count entries in INDEX table vs actual directory contents → flag STALE if mismatch
+
+**With --reindex or --fix**: Regenerate all INDEX.md files from disk per spec.
+
+---
+
+## Migration: prd.json → README.md
+
+For each project with only `prd.json`:
+
+1. Read prd.json
+2. Extract fields:
+   - `name` → title
+   - `description` → overview
+   - `metadata.goal` → Goal line
+   - `metadata.successCriteria` → Success line
+   - `userStories[]` → User Stories section
+3. Generate README.md
+4. Keep prd.json as backup (rename to `prd.json.bak`)
+
+**Template**:
+```markdown
+# {name}
+
+**Goal:** {metadata.goal}
+**Success:** {metadata.successCriteria}
+
+## Overview
+{description}
+
+## User Stories
+
+### US-001: {story.title}
+**Description:** {story.description}
+
+**Acceptance Criteria:**
+{story.acceptanceCriteria as checklist}
+
+## Non-Goals
+{if present}
+
+## Technical Considerations
+{if present}
+```
+
+---
+
+## Fix Actions
+
+### Git Cleanup
+```bash
+# Stage deleted files
+git add -u
+
+# Commit cleanup
+git commit -m "chore: cleanup orphaned files"
+```
+
+### Archive Stale Threads & Checkpoints
+```bash
+mkdir -p archives/threads archives/checkpoints
+find workspace/threads -name "*.json" -mtime +30 -exec mv {} archives/threads/ \;
+find workspace/checkpoints -name "*.json" -mtime +30 -exec mv {} archives/checkpoints/ \;
+```
+
+### Relocate Misplaced Projects
+```bash
+# Move apps/{name}/prd.json to projects/{name}/
+mkdir -p projects/{name}
+mv apps/{name}/prd.json projects/{name}/
+```
+
+### Regenerate INDEX.md Files (--reindex)
+
+For each expected INDEX.md location (see Audit Check #8):
+1. List all files and subdirectories (skip INDEX.md, .DS_Store, node_modules, dotfiles)
+2. Extract description per spec: `.md` → first `#` heading, `.yaml` → `description:`, `.json` → `name`/`description`, dirs → file count + purpose
+3. Write INDEX.md using template from `knowledge/public/hq-core/index-md-spec.md`
+4. Directories first, then files, alphabetical within each group
+
+---
+
+## Output Format
+
+### Audit Report
+```
+HQ Cleanup Audit
+================
+
+✓ Worker registry: 15 workers indexed
+✗ Project structure: 8 issues
+  - projects/customer-cube: prd.json without README.md
+  - projects/deel-analytics: prd.json without README.md
+  ...
+✗ Deprecated directories: apps/ still exists (4 items)
+✗ Git status: 3 uncommitted changes
+✓ Checkpoints: all recent
+✗ INDEX.md: 2 stale, 1 missing
+  - projects/INDEX.md: 30 entries vs 33 actual (stale)
+  - workspace/reports/INDEX.md: missing
+
+Summary: 14 issues found
+Run `/cleanup --migrate` to convert prd.json files
+Run `/cleanup --fix` to clean git and archive stale files
+Run `/cleanup --reindex` to regenerate all INDEX.md files
+```
+
+### After Migration
+```
+Migrated 8 projects to README.md format:
+- projects/customer-cube/README.md (created)
+- projects/deel-analytics/README.md (created)
+...
+
+Original prd.json files renamed to prd.json.bak
+Run `/cleanup --fix` to commit changes
+```
+
+---
+
+## Rules
+
+- **--audit is safe**: Never modifies files, only reports
+- **Always ask before destructive actions**: deletions, moves
+- **Backup before migration**: rename, don't delete
+- **Commit after changes**: keep git clean
+
+---
+
+## Current HQ Policies
+
+Reference for what we're enforcing:
+
+| Area | Policy |
+|------|--------|
+| Projects | Live in `projects/{name}/` with `README.md` |
+| PRD format | Markdown README.md (not prd.json) |
+| Workers | Indexed in `workers/registry.yaml` |
+| Worker FSM | `state_machine:` section in worker.yaml (Loom pattern) |
+| Apps | Deprecated - migrate to projects/ or workers/ |
+| Skills | `.claude/commands/*.md` format |
+| Threads | Primary session persistence (`workspace/threads/`) |
+| Checkpoints | Legacy format, archive after 30 days |
+| Metrics | Append to `workspace/metrics/metrics.jsonl` |
+| Git | Clean working tree |
+| Knowledge repos | Symlinks in `knowledge/` and `companies/*/knowledge/` point to repos; all repos committed |
+| INDEX.md | Exist at key dirs, match contents (see spec) |