create-hq 5.0.0

package/template/CHANGELOG.md

@@ -0,0 +1,220 @@
+# Changelog
+
+## v4.0.0 (2026-01-31)
+
+### Added
+- **`/learn`** — Automated learning pipeline: captures learnings from task execution/failure and injects rules directly into the files they govern (worker.yaml, command .md, knowledge files, or CLAUDE.md). Deduplicates via qmd, supports global promotion, event logging.
+- **INDEX.md System** — Hierarchical INDEX.md files provide navigable maps of HQ. Auto-updated by `/checkpoint`, `/handoff`, `/reanchor`, `/prd`, `/run-project`, `/newworker`. Spec at `knowledge/hq-core/index-md-spec.md`
+- **Knowledge Repos** — Knowledge folders can now be independent git repos, symlinked into HQ for versioning and sharing
+- **Learning System** — Rules injected directly into source files (worker.yaml, commands, knowledge, CLAUDE.md). `/learn` + `/remember` pipeline with dedup, event logging, and global cap (20 rules)
+- **Auto-Learn (Build Activities)** — `/newworker`, `/prd`, new knowledge/commands auto-register themselves via `/learn`
+- **Search rules** — Formal policy: use qmd for HQ content search, never Grep/Glob for topic search
+- `knowledge/Ralph/11-team-training-guide.md` — Team training guide for Ralph methodology
+- `knowledge/hq-core/checkpoint-schema.json` — Checkpoint data format
+- `knowledge/hq-core/index-md-spec.md` — INDEX.md specification
+
+### Changed
+- **`.claude/CLAUDE.md`** — Major rewrite: added INDEX.md System, Knowledge Repos, Learning System, Auto-Learn, Search rules sections. Command count 16 → 17
+- **All 14 public commands refreshed** — `/checkpoint` (knowledge repo state), `/cleanup` (INDEX.md audit + knowledge repo checks), `/execute-task` (learnings integration, orchestrator output), `/handoff` (knowledge repo commits, INDEX.md regen), `/metrics`, `/newworker` (auto-learn + INDEX updates), `/prd` (auto-learn + INDEX updates), `/reanchor` (INDEX-based context loading), `/remember` (delegates to /learn), `/run-project` (fresh-context sub-agent pattern, auto-reanchor between tasks), `/run` (learnings loading), `/search-reindex`, `/search`
+- `workers/registry.yaml` — Version 3.0 → 4.0, dev team count 13 → 12
+- `knowledge/hq-core/thread-schema.md` — Added knowledge repo tracking
+- `knowledge/workers/README.md`, `skill-schema.md`, `state-machine.md` — Updated
+- `knowledge/projects/README.md` — Updated
+- `workers/dev-team/code-reviewer/skills/review-pr.md` — Generalized E2E checks
+- `workers/dev-team/frontend-dev/worker.yaml` — Generalized E2E requirements
+- `workers/dev-team/qa-tester/worker.yaml` — Generalized E2E testing
+- `workers/dev-team/task-executor/skills/validate-completion.md` — Added E2E manifest validation
+
+### Removed
+- `knowledge/pure-ralph/` — Removed (pure-ralph patterns merged into Ralph methodology core)
+
+---
+
+## v3.3.0 (2026-01-28)
+
+### Added
+- **Auto-Handoff** — Claude now auto-runs `/handoff` when context usage hits 70%, preserving session continuity without manual intervention
+- `/setup` and `/exit-plan` now included in starter kit
+
+### Changed
+- **Command visibility overhaul** — 16 public commands (down from 29). Content, design, and company-specific commands moved to private
+- All 16 public commands refreshed with latest improvements
+- `.claude/CLAUDE.md` — Updated command tables, added Auto-Handoff section, count 29 → 16
+- `workers/registry.yaml` — Paths updated to flat structure (`workers/` not `workers/public/`)
+- Knowledge files PII-scrubbed
+
+### Removed
+- `/contentidea`, `/suggestposts`, `/scheduleposts`, `/preview-post`, `/post-now` — moved to private (content pipeline)
+- `/humanize` — moved to private (content polish)
+- `/generateimage`, `/svg`, `/style-american-industrial`, `/mj-abacus`, `/design-iterate` — moved to private (design tools)
+- `/publish-kit`, `/pure-ralph` — moved to private
+- `/hq-sync` — moved to private
+
+---
+
+## v3.2.0 (2026-01-28)
+
+### Added
+- **`/remember`** - Capture learnings when things don't work right. Injects rules directly into relevant files (worker.yaml, commands, CLAUDE.md, skills) instead of a separate database. Supports deduplication via qmd search and Ralph integration for auto-capture on back-pressure failures.
+- `workers/registry.yaml` - Added `frontend-designer` and `qa-tester` standalone workers
+
+### Changed
+- All 28 existing public commands refreshed with latest improvements
+- `.claude/CLAUDE.md` - Command count 28 → 29, added `/remember` to session management
+- `workers/registry.yaml` - Version 2.0 → 3.0
+
+---
+
+## v3.1.0 (2026-01-28)
+
+### Changed
+- **`/prd`** - Merged `/newproject` into `/prd`. Single command now handles discovery, PRD generation (prd.json + README.md), orchestrator registration, beads sync, and execution choice
+- **`/run-project`** - Strict prd.json validation: hard stop if missing, field validation on load, no README.md fallback
+- **`/execute-task`** - Same strict prd.json validation as `/run-project`
+- **`/newworker`** - Updated `/newproject` references to `/prd`
+- **`/nexttask`** - Updated `/newproject` reference to `/prd`
+- **`.claude/CLAUDE.md`** - Command count 29 → 28, removed `/newproject` from project commands
+
+### Removed
+- **`/newproject`** - Merged into `/prd`. Use `/prd` for all project planning
+
+### Breaking
+- `/newproject` no longer exists. Use `/prd` instead (same discovery flow + now outputs prd.json)
+- `/run-project` and `/execute-task` require `prd.json` with `userStories` array (not `features`). Legacy PRDs must be migrated.
+
+---
+
+## v3.0.0 (2026-01-27)
+
+### Added
+- **`/humanize`** - Remove AI writing patterns from drafts
+- **`/pure-ralph`** - External terminal orchestrator for autonomous PRD execution
+- **`/svg`** - Generate minimalist abstract white line SVG graphics
+- **`/search-reindex`** - Reindex and re-embed HQ for qmd search
+- `knowledge/pure-ralph/` - Pure Ralph loop patterns, branch workflow, and learnings
+- `knowledge/design-styles/ethereal-abstract.md` - Ethereal abstract style guide
+- `knowledge/design-styles/liminal-portal.md` - Liminal portal style guide
+- `knowledge/hq/checkpoint-schema.json` - Checkpoint data format
+- `knowledge/projects/` - Project creation guidelines and templates
+
+### Changed
+- **`/search`** - Upgraded to qmd-powered semantic + full-text search (BM25, vector, hybrid modes)
+- **`/handoff`** - Added search index update step (`qmd update && qmd embed`)
+- **`/run-project`** - Updated orchestration pattern with inline worker pipeline execution
+- **`/execute-task`** - Worker names aligned with actual dev-team worker IDs; added `content` task type
+- **`.claude/CLAUDE.md`** - Updated command count (22 → 29), added Design section, qmd Search section, new knowledge refs
+
+### Breaking
+- `/search` syntax changed to qmd-based queries. Install [qmd](https://github.com/tobi/qmd) or use the built-in grep fallback.
+
+---
+
+## v2.1.0 (2026-01-26)
+
+### Added
+- **`/generateimage`** - Generate images via Gemini Nano Banana (gnb)
+- **`/post-now`** - Post approved content to X or LinkedIn immediately
+- **`/preview-post`** - Preview social drafts, select images, approve for posting
+- **`/publish-kit`** - Sync HQ → hq-starter-kit with PII scrubbing
+
+### Changed
+- **`/contentidea`** - Enhanced multi-platform workflow with:
+  - Image generation per approved style (7 styles)
+  - Visual prompt patterns by theme
+  - Anti-AI slop rules (humanizer)
+  - Preview site sync
+- **`/scheduleposts`** - Improved queue management and image generation workflow
+- **`/style-american-industrial`** - Expanded monochrome variant with CSS variables
+- **`/metrics`** - Updated example worker names
+- **`/run`** - Updated example worker names
+- **`/search`** - Updated example worker names
+- **`/suggestposts`** - Generalized for any user
+
+### Fixed
+- Consistent PII scrubbing across all skills
+
+---
+
+## v2.0.0 (2026-01-25)
+
+Major release: Project orchestration, content pipeline, and 18 production workers.
+
+### Project Orchestration
+- **`/run-project`** - Execute entire projects via Ralph loop
+- **`/execute-task`** - Worker-coordinated task execution
+- **`/prd`** - Enhanced PRD generation with HQ context awareness
+- `workspace/orchestrator/` - Project state tracking
+- `workspace/learnings/` - Captured insights from executions
+
+### Content Pipeline
+- **`/contentidea`** - Build raw idea into full content suite (one-liner → post → article)
+- **`/suggestposts`** - Research-driven post suggestions aligned with goals
+- **`/scheduleposts`** - Smart timing for posting based on content inventory
+- `social-content/drafts/` - Platform-specific draft storage (x/, linkedin/)
+- `workspace/content-ideas/inbox.jsonl` - Idea capture
+
+### Dev Team (13 workers)
+Complete development team for autonomous coding:
+- `project-manager` - PRD lifecycle, issue selection
+- `task-executor` - Analyze & route to workers
+- `architect` - System design, API design
+- `backend-dev` - API endpoints, business logic
+- `frontend-dev` - React/Next components
+- `database-dev` - Schema, migrations
+- `qa-tester` - Testing, validation
+- `motion-designer` - Animations, polish
+- `infra-dev` - CI/CD, deployment
+- `code-reviewer` - PR review, quality gates
+- `knowledge-curator` - Update knowledge bases
+- `product-planner` - Technical specs
+
+### Content Team (5 workers)
+Specialized content analysis workers:
+- `content-brand` - Voice, messaging, tone
+- `content-sales` - Conversion copy, CTAs
+- `content-product` - Technical accuracy
+- `content-legal` - Compliance, claims
+- `content-shared` - Shared utilities (library)
+
+### New Commands
+- **`/search`** - Full-text search across threads, checkpoints, PRDs, workers
+- **`/design-iterate`** - Design A/B testing with git branches
+- **`/metrics`** - Worker execution metrics
+- **`/cleanup`** - Audit and clean HQ
+- **`/exit-plan`** - Force exit from plan mode
+
+### Auto-Checkpoint
+- Sessions auto-save to `workspace/threads/`
+- Format: `T-{timestamp}-{slug}.json`
+- Triggers: worker completion, git commit, file generation
+- Never lose work to context limits
+
+### Knowledge Bases
+- `knowledge/hq-core/` - Thread schema, workspace patterns
+- `knowledge/ai-security-framework/` - Security best practices
+- `knowledge/design-styles/` - Design guidelines + swipes
+- `knowledge/dev-team/` - Development patterns
+- `knowledge/loom/` - Agent patterns reference
+- Updated `knowledge/workers/` with templates
+
+### Registry
+- Upgraded to version 2.0 format
+- Added team grouping
+- Worker type taxonomy (CodeWorker, ContentWorker, SocialWorker, ResearchWorker, OpsWorker, Library)
+
+---
+
+## 2026-01-21
+
+### PRD-First Planning
+Added rules to redirect Claude's built-in planning to HQ's PRD system.
+
+**Problem:** Claude Code triggers session-local plan mode for "complex" tasks. These plans live in `.claude/plans/`, are ephemeral, and compete with HQ's persistent PRD workflow.
+
+**Solution:** Skills now redirect to `/newproject` when complex planning is needed. Plans belong in `prd.json` files that persist across sessions and integrate with `/ralph-loop`.
+
+**Changes:**
+- All skills: Redirect `EnterPlanMode` → suggest `/newproject` instead
+- All skills: Redirect `TodoWrite` → PRD features track tasks
+
+**Result:** Planning happens in the right place (PRD), not session-local files.

package/template/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Corey Epstein
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/template/MIGRATION.md

@@ -0,0 +1,259 @@
+# Migration Guide
+
+Instructions for updating existing HQ installations to new versions.
+
+---
+
+## Migrating to v4.0.0 (from v3.3.0)
+
+### What Changed
+Major architecture upgrade: INDEX.md navigation system, knowledge repos (independent git repos), automated learning pipeline (`/learn`), and significant command updates.
+
+### New Command
+Copy to `.claude/commands/`:
+- `learn.md` — Automated learning pipeline (captures learnings, injects rules into source files, deduplicates)
+
+### New Knowledge Files
+Copy to `knowledge/`:
+- `Ralph/11-team-training-guide.md` — Team training guide
+- `hq-core/checkpoint-schema.json` — Checkpoint data format
+- `hq-core/index-md-spec.md` — INDEX.md specification
+
+### Updated Files
+All 13 existing public commands have been refreshed. Copy from starter kit:
+- `.claude/commands/*.md` (all public commands)
+- `.claude/CLAUDE.md` (major rewrite — merge carefully with your customizations)
+- `workers/registry.yaml` (v4.0)
+
+Updated workers:
+- `workers/dev-team/code-reviewer/skills/review-pr.md`
+- `workers/dev-team/frontend-dev/worker.yaml`
+- `workers/dev-team/qa-tester/worker.yaml`
+- `workers/dev-team/task-executor/skills/validate-completion.md`
+
+Updated knowledge:
+- `knowledge/hq-core/thread-schema.md`
+- `knowledge/workers/README.md`
+- `knowledge/workers/skill-schema.md`
+- `knowledge/workers/state-machine.md`
+- `knowledge/projects/README.md`
+
+### Removed
+- `knowledge/pure-ralph/` — Delete this directory. Pure Ralph patterns have been merged into the Ralph methodology core.
+
+### New Features to Adopt
+
+**INDEX.md System:** Create INDEX.md files at key directories. See `knowledge/hq-core/index-md-spec.md` for spec. Commands like `/checkpoint`, `/handoff`, `/prd` auto-update them.
+
+**Knowledge Repos (Optional):** Knowledge folders can be independent git repos symlinked into HQ. See "Knowledge Repos" section in CLAUDE.md.
+
+**Learning System:** `/learn` and `/remember` now inject rules directly into source files. Add a `## Learned Rules` section to your CLAUDE.md and `## Rules` sections to your commands.
+
+### Migration Steps
+1. Copy `.claude/commands/learn.md` (new command)
+2. Copy all updated `.claude/commands/*.md`
+3. Merge `.claude/CLAUDE.md` — add INDEX.md System, Knowledge Repos, Learning System, Auto-Learn, and Search rules sections
+4. Copy `workers/registry.yaml`
+5. Copy new knowledge files (`Ralph/11-team-training-guide.md`, `hq-core/checkpoint-schema.json`, `hq-core/index-md-spec.md`)
+6. Copy updated knowledge and worker files
+7. Delete `knowledge/pure-ralph/`
+8. Run `/search-reindex`
+9. Run `/cleanup --reindex` to generate INDEX.md files
+
+### Breaking Changes
+- `knowledge/pure-ralph/` removed — if you reference it, update to `knowledge/Ralph/`
+
+---
+
+## Migrating to v3.3.0 (from v3.2.0)
+
+### What Changed
+Commands split into public (16) and private (15). Only generic, reusable commands ship in the starter kit now. Content, design, and company-specific commands are private.
+
+### New Feature: Auto-Handoff
+Claude auto-runs `/handoff` at 70% context usage. This is in `.claude/CLAUDE.md` — copy the "Auto-Handoff (Context Limit)" section to yours.
+
+### Removed Commands (now private)
+If you use any of these, keep your existing copies — they just won't be in future starter kit releases:
+- Content: `contentidea`, `suggestposts`, `scheduleposts`, `preview-post`, `post-now`, `humanize`
+- Design: `generateimage`, `svg`, `style-american-industrial`, `mj-abacus`, `design-iterate`
+- System: `publish-kit`, `pure-ralph`, `hq-sync`
+
+### Migration Steps
+1. Copy `.claude/CLAUDE.md` from starter kit (or merge the Auto-Handoff section into yours)
+2. Copy refreshed `.claude/commands/*.md` for the 16 public commands
+3. Copy `workers/registry.yaml`
+4. Run `/search-reindex`
+
+### Breaking Changes
+- (none — removed commands still work if you keep your local copies)
+
+---
+
+## Migrating to v3.2.0 (from v3.1.0)
+
+### New Skills
+Copy this file to `.claude/commands/`:
+- `remember.md` — Capture learnings when things don't work right
+
+### Updated Files
+All 28 existing commands have been refreshed. Copy from starter kit to your HQ:
+- `.claude/commands/*.md` (all public commands)
+- `.claude/CLAUDE.md`
+- `workers/registry.yaml`
+
+### Breaking Changes
+- (none)
+
+### Migration Steps
+1. Copy `.claude/commands/remember.md` to your HQ
+2. Optionally update other commands by copying from starter kit
+3. Run `/search-reindex` to include new command in search
+
+---
+
+## Migrating to v3.1.0 (from v3.0.0)
+
+### Breaking Changes
+- **`/newproject` removed** -- Merged into `/prd`. Delete `.claude/commands/newproject.md` from your HQ.
+- **prd.json now required** -- `/run-project` and `/execute-task` require `projects/{name}/prd.json` with a `userStories` array. README.md is no longer accepted as a fallback.
+- **`features` key deprecated** -- If your prd.json files use `"features"` instead of `"userStories"`, rename the key. Also rename `"acceptance_criteria"` to `"acceptanceCriteria"` (camelCase).
+
+### Updated Skills
+Replace these files in `.claude/commands/`:
+- `prd.md` -- **Major rewrite.** Now outputs both `prd.json` (source of truth) and `README.md` (derived). Includes orchestrator registration, beads sync, and execution choice.
+- `run-project.md` -- Strict prd.json validation on load. Hard stop if missing.
+- `execute-task.md` -- Same strict validation.
+- `newworker.md` -- `/newproject` references updated to `/prd`
+- `nexttask.md` -- `/newproject` reference updated to `/prd`
+
+### Migration Steps
+1. Delete `.claude/commands/newproject.md`
+2. Copy updated `prd.md`, `run-project.md`, `execute-task.md`, `newworker.md`, `nexttask.md`
+3. If you have prd.json files using `"features"`, rename to `"userStories"` and `"acceptance_criteria"` to `"acceptanceCriteria"`
+4. If you have projects with only README.md (no prd.json), run `/prd {project}` to generate the JSON
+
+---
+
+## Migrating to v3.0.0 (from v2.1.0)
+
+### New Skills
+Copy these files to your `.claude/commands/`:
+- `humanize.md` - Remove AI writing patterns from drafts
+- `pure-ralph.md` - External terminal orchestrator for autonomous PRD execution
+- `svg.md` - Generate minimalist abstract white line SVG graphics
+- `search-reindex.md` - Reindex and re-embed HQ for qmd search
+
+### Updated Skills
+The following skills have significant updates. Review and merge:
+- `search.md` - **Breaking:** Complete rewrite to qmd-powered search (BM25, semantic, hybrid). Includes grep fallback if qmd is not installed.
+- `handoff.md` - Added step 4: search index update (`qmd update && qmd embed`)
+- `run-project.md` - Updated orchestration pattern with inline worker pipeline execution
+- `execute-task.md` - Worker names aligned with dev-team IDs (`backend-dev`, `frontend-dev`, `dev-qa-tester`, etc.); added `content` task type
+
+### New Knowledge
+Copy these directories to your `knowledge/`:
+- `pure-ralph/` - Branch workflow, learnings
+- `hq/` - Checkpoint schema
+- `projects/` - Project creation guidelines and templates
+- `design-styles/ethereal-abstract.md` - Ethereal abstract style guide
+- `design-styles/liminal-portal.md` - Liminal portal style guide
+
+### Install qmd (Optional)
+[qmd](https://github.com/tobi/qmd) powers the new `/search` command with semantic + full-text search.
+
+```bash
+# Install qmd (requires Go)
+go install github.com/tobi/qmd@latest
+
+# Index your HQ
+cd ~/Documents/HQ
+qmd update && qmd embed
+```
+
+If qmd is not installed, `/search` falls back to grep-based search.
+
+### Breaking Changes
+- `/search` syntax changed from grep-based to qmd queries. Install qmd or use the built-in fallback.
+
+---
+
+## Migrating to v2.1.0 (from v2.0.0)
+
+### New Skills
+Copy these files to your `.claude/commands/`:
+- `generateimage.md` - Generate images via Gemini Nano Banana
+- `post-now.md` - Post to X/LinkedIn immediately
+- `preview-post.md` - Preview drafts, select images, approve posting
+- `publish-kit.md` - Sync your HQ to hq-starter-kit
+
+### Updated Skills
+The following skills have significant updates. Review and merge:
+- `contentidea.md` - Enhanced multi-platform workflow with:
+  - Image generation per approved style (7 styles)
+  - Visual prompt patterns organized by theme
+  - Anti-AI slop rules (humanizer section)
+  - Preview site sync workflow
+- `scheduleposts.md` - Improved queue management
+- `style-american-industrial.md` - Expanded monochrome variant with CSS variables
+- `metrics.md`, `run.md`, `search.md`, `suggestposts.md` - Generalized examples
+
+### New Directories (if using image generation)
+```
+workspace/social-drafts/images/   # Generated images for posts
+repos/private/social-drafts/      # Preview site (optional)
+```
+
+### Breaking Changes
+None in this release.
+
+---
+
+## Migrating to v2.0.0 (from v1.x)
+
+### Major Changes
+v2.0.0 is a significant upgrade with new project orchestration and 18 workers.
+
+### New Directories
+Create these if missing:
+```
+workspace/
+  threads/          # Auto-saved sessions
+  orchestrator/     # Project state
+  learnings/        # Captured insights
+  content-ideas/    # Idea inbox
+social-content/
+  drafts/
+    x/              # X/Twitter drafts
+    linkedin/       # LinkedIn drafts
+```
+
+### New Skills
+Copy all files from `.claude/commands/`.
+
+### New Workers
+Copy `workers/dev-team/` and `workers/content-*/` directories.
+
+### Knowledge Bases
+Copy new knowledge directories:
+- `knowledge/hq-core/`
+- `knowledge/ai-security-framework/`
+- `knowledge/design-styles/`
+- `knowledge/dev-team/`
+
+### Registry Update
+Replace `workers/registry.yaml` with the new v2.0 format.
+
+### Breaking Changes
+- Registry format changed (version: "2.0")
+- Thread format changed (see `knowledge/hq-core/thread-schema.md`)
+- `/ralph-loop` renamed to `/run-project`
+
+---
+
+## General Update Process
+
+1. **Backup your HQ** before updating
+2. **Diff files** before overwriting - preserve your customizations
+3. **Merge knowledge** - don't overwrite, combine with your additions
+4. **Test skills** after copying to ensure they work with your setup