Skip to content
Indigo HQ Docs

hq-core

hq-core is the HQ scaffold: the starter kit that npx create-hq downloads from GitHub and lays down as a new HQ instance. It is the seed that every HQ directory grows from.

What it is

  • The create-hq scaffold — distributed as a GitHub release of indigoai-us/hq-core, not as an npm package. Its version is tracked as hqVersion in core/core.yaml (currently 16.0.x). The same file sets requiresHqCli, the minimum hq CLI version the scaffold needs.
  • A minimal scaffold for orchestrating autonomous AI workers across sessions. HQ is a team AI operating system that scales from solo operator to enterprise.
  • Ships the orchestration layer and the engineering surface (/tdd, /review, /execute-task, /run-project, /architect, /land, and related workers and policies). Other capabilities install separately as content packs.

Engineering surface ships in core

hq-core v15.0.0 moved the engineering toolkit into a separate hq-pack-engineering pack. A later release reversed that: the engineering skills, workers, knowledge, and policies ship in core again, and hq-pack-engineering is no longer a recommended package. Nothing needs installing. If you upgraded from a version that installed the pack, remove the redundant copy once:

Terminal window
hq packs uninstall hq-pack-engineering

Who uses it / when

Anyone standing up a new HQ instance. You touch hq-core once at install time; afterward you operate the instance with the hq CLI and upgrade with /update-hq.

Key flows

Terminal window
# scaffold a new HQ instance
npx create-hq ~/my-hq


# full vs minimal install
npx create-hq ~/my-hq --full      # install all recommended packs without prompting
npx create-hq ~/my-hq --minimal   # scaffold only, skip recommended packs
FlagEffect
[directory]Where to create HQ (prompts if omitted; the prompt defaults to hq)
--skip-depsSkip dependency checks
--skip-cliDon’t install @indigoai-us/hq-cli globally
--skip-syncDon’t prompt for cloud sync setup
--skip-packagesDon’t prompt for package discovery and installation
--minimalInstall the hq-core scaffold only
--fullInstall the scaffold plus all recommended content packs without prompting
--tag <version>Fetch a specific hq-core version tag (for example v16.0.0)
--local-template <path>Use a local hq-core directory instead of fetching from GitHub

create-hq downloads the latest hq-core release from GitHub (or the --tag version, or --local-template), scaffolds the directory, and can install the recommended packs declared in core/core.yaml. It runs git init in the new HQ and makes an initial commit, “Initial HQ setup via create-hq” (no remote; the HQ root stays local). When qmd is installed, it registers the HQ as a qmd collection and runs a first qmd update to index it for search; otherwise it skips that step. Prerequisites: Node.js 22.13 or later and git are required. The GitHub CLI, Claude Code, qmd, yq, and the hq CLI are optional; the installer offers to install them. (The Vercel CLI is not an HQ dependency — /deploy uses hq-deploy; install Vercel yourself only if you deploy your own projects to it.)

What the scaffold contains

core/core.yaml defines the rule tiers (locked / reviewable / open) and recommended packages. The scaffold lays down the runtime folders (.claude/ skills, .codex/, .agents/, .cursor/, .grok/), core/ (workers, knowledge, policies, scripts), companies/, personal/, repos/, and workspace/.

Composition

  • The scaffold seeds, it does not run — after npx create-hq, hq-core has no runtime dependency on the other repos. Upgrades flow through /update-hq.
  • Capabilities arrive as packs — see hq-packages and install them with hq install.