hq
HQ — the multi-repo command center. Turn a single utterance ("For project Acme, do X") into governance-aware action across every repo on this device. Resolves a project name (fuzzily) to a real repo v
SKILL.mdskills/2-daily/hq/SKILL.md
GitHub/hq — multi-repo command center
HQ is the front door for one-utterance, multi-repo tasking: resolve a project name to a real repo, report its governance state, land the request on that repo's own PDDA rails, and prepare dispatch. Read paths are safe; every write path previews by default.
Preconditions — install once, then locate (never hardcode a path)
/hq is user-level: it works from a session opened in any repo, not just the harness clone.
Two anchors make that true, both self-locating and free of any hardcoded machine path.
Install (once per clone). Claude Code only scans ~/.claude/skills/, not the repo's top-level
skills/. Symlink this skill in so a session can load it at all:
bash skills/2-daily/hq/install.sh # symlinks this clone's skills/2-daily/hq into ~/.claude/skills/ (idempotent)
Locate (every invocation). HQ is centralized — there is one utils/hq/hq.sh, shipping in the
harness clone beside this skill. The bundled locator find-hq.sh resolves it relative
to its own installed location (symlink-safe), so it works from any CWD. Run this first, then call
$HQ_SH:
# Find the bundled locator — anchored on $HOME or the CWD, never an absolute machine path:
for L in "${XYZ_HARNESS:+$XYZ_HARNESS/skills/2-daily/hq/find-hq.sh}" \
"$HOME/.claude/skills/hq/find-hq.sh" \
"./.claude/skills/hq/find-hq.sh" \
"$(git rev-parse --show-toplevel 2>/dev/null)/skills/2-daily/hq/find-hq.sh"; do
[ -n "$L" ] && [ -x "$L" ] && break
done
[ -x "$L" ] || { echo "hq: locator not found — set XYZ_HARNESS to your xyz-3-agents-swarm clone"; exit 1; }
eval "$("$L" --env)" # exports HQ_ROOT and HQ_SH (absolute path to hq.sh)
"$L" --check # one-glance readiness: hq root, sqlite3, rebalance registry
After this, $HQ_SH is the absolute dispatcher path. When standing in the harness repo you can
still call bash utils/hq/hq.sh … directly — the examples below use that short form; substitute
bash "$HQ_SH" … when you're in another repo.
What it does now
The skill drives utils/hq/hq.sh (or $HQ_SH from a foreign repo — see Preconditions):
hq.sh status <project|repo>— the project card: resolved repo + path (with a fuzzy-match note if the name was loose), capability tier (A/B/C), Rebalance priority, PDDA mode + startup docs, active-doc count, open marathon plan, XYZ install/drift stamps.hq.sh resolve <project|repo>— machine-readableKEY=valueresolution (addsRESOLVED_VIAexact|fuzzy; ambiguous names return rc=2 withCANDIDATES).hq.sh registries— introspection: what each registry knows and its coverage.hq.sh next [--limit N]— a Rebalance-priority board: projects ranked bypriority_tier(1 highest) with each one's resolved HQ capability tier (A dispatch-eligible / B / C / unresolved), answering "what should I pick up next across my repos?" Read-only.hq.sh park [--create] [--title T] <project> <request…>— issue-first intake in the target repo (GH issue →1-INBOXcapture → ROADMAP parking → dashboard regen if present → targetpdda.sh). Previews unless--create. The capture doc renders the full PDDA skeleton (ratings,non_goals/related/goal, Key Concepts/Idea/Why/Phase 0 checklist) with TODO stubs by default; a synthesis front end (e.g. a future/ideaskill) can fill the judgment-heavy fields in by exportingHQ_PARK_WHY/HQ_PARK_KEY_CONCEPTS/HQ_PARK_NON_GOALS/HQ_PARK_RELATED/HQ_PARK_COMPLEXITY/HQ_PARK_RISK/HQ_PARK_EFFORT/HQ_PARK_PHASESbefore calling--create— barehq.sh parkneeds none of these (GH-164 Phase 1).hq.sh queue [--create] [--gh-issue N] <project> <request…>— append an HQ-queued lane to the target's newest Marathon Plan (non-destructive appendix). Previews unless--create.hq.sh fire --gh-issue N [--risk 1-5] <project>— gated prepare-and-hand-off: resolve + gate (Tier A,risk < 3) + emit theswarm-preflightcommand. HQ never drives the harness itself — the operator runs it and drives via the relay-xyz skill (GUIDING-PRINCIPLES §8).
When the user invokes /hq
- Name given →
bash utils/hq/hq.sh status "<name>"; relay the card. On UNRESOLVED, show the find-recipe and ask; on AMBIGUOUS, show the candidates and ask which — never guess a path. - "For project X, do Y" →
hq.sh park "<X>" "<Y>"(preview), show the exact issue/doc/roadmap, then--createon the operator's go (creating a GH issue is outward-facing — confirm first). - "queue it" / "fire it" → the corresponding verb.
firestops at the gated hand-off: relay the emitted command and hand to the relay-xyz skill; do not auto-drive a marathon. - "what can HQ see" / "list projects" →
hq.sh registries.
Resolution ladder (how a name becomes a repo)
- Rebalance
project_registry(rebalance-OS/rebalance.db) — the semantic catalog: human project NAME (owner/repo) → repo list +priority_tier/value_level. No local path. - XYZ install registry (
~/.config/xyz/registry.tsv) — repo → absolute path + runnable/drift stamps. The path resolver; only covers XYZ-installed repos. - Git Pulse PDDA registry (
~/git-pulse-sync/pdda/registry-<device>.tsv) — repo → PDDAmode+startup_docs, across all devices. No path. - Filesystem
find— fallback when no registry knows the path.
Override any source for tests / non-default installs via HQ_PDDA_REGISTRY_DIR, HQ_XYZ_REGISTRY,
HQ_REBALANCE_DB, HQ_SEARCH_ROOTS (see utils/hq/hq-lib.sh).
Live marathon status (what's running right now, deterministically)
"What marathons are running now" is a different question than hq.sh status/registries (which
report governance/capability state) or utils/hq/marathon-scan.sh (which reports doc-level
status — what a MARATHON-PLAN-*.md's frontmatter claims — not live process state). Don't conflate
them: a repo can show "ready to fire" in a scan while a marathon is actively mid-turn in a sibling
worktree the doc scan never looks at.
Once GH-218's
utils/hq/marathon-live.sh exists (check ls utils/hq/marathon-live.sh first), run it — it does
the four checks below across every hq_known_repos repo in one shot and emits repo + marathon/lane +
task + claimant + live-or-idle. Until then, or to spot-check one repo by hand, walk these in
order — all deterministic, local file/process reads, no server or daemon involved:
- Which repos exist at all —
hq.sh registries(orhq_known_reposdirectly), which already aggregates the XYZ install registry (~/.config/xyz/registry.tsv), Rebalance's project registry, and Git Pulse's PDDA registry. This is the full list of repos to check, not just the current one. - What's claimed right now, per repo — run
tick projectinside that repo (nativebin/tick, or$XYZ_PATH/bin/tickfor a vendored install —$XYZ_PATHcomes fromhq_repo_resolve) to regenerate.tick/STATE.md, then read its## Claimedsection:- <task-id> by <claimant> paths: [...]. The task id already names the marathon/lane (e.g.MARATHON-GH208-WORKTREE-ISOLATION-RACE-TURN). - Is it actually driving this instant, or just claimed-and-idle — check for that repo's driver
lock:
.git/relay-driver.lock(native) or the vendored equivalent (seemarathon-drive.sh's own lock-path resolution, GH-149, for exactly how a linked-worktree/vendored install differs). Present = amarathon-drive.sh/relay-drive.shprocess holds it right now. - Corroborate with worktrees —
git worktree list(or-C <repo>) for amarathon/*-branch worktree with a commit or dirty status in roughly the last 30 minutes; a secondary signal, not ground truth on its own. - Any live agent CLI process —
ps aux | grep -E "marathon-drive|relay-drive.sh"machine-wide, as a final cross-check (catches a driver running against a repo you didn't think to check).
Capability tiers
- Tier A — PDDA + XYZ install → dispatch-eligible (Phase 3).
- Tier B — PDDA only → intake only, no dispatch.
- Tier C — bare repo → plain issue only; offer a PDDA install.
Guardrails (inherited from GH-128)
- Read-only in this phase. Rebalance is always read-only (mirrors the #96 seam discipline).
- Never fabricate a repo path — an UNRESOLVED result is a question for the operator, not a guess.
- Later dispatch will be park-by-default with a hard
risk >= 3gate; do not simulate it now.