hq-packages

Run an HQ-issued Slack bot — arm a per-bot @-mention watcher that spawns an autonomous Claude worker per mention. Pass the bot's slug (e.g. `hassaan`), a scope flag (`-c <company-slug>` or `--personal`), and optionally a workspace (`-w <slack-team-domain>`; auto-derived for `--personal` from SLACK_CREDENTIALS_JSON). The watcher resolves scope/workspace before personUid, using the sole local cache entry or an exact selected-vault bot-token namespace match; pass `-u <prs_…>` to override. It verifies and injects scoped `ANTHROPIC_API_KEY` into detached workers, handles the one-time bypass-permissions gate, resolves `<personUid>/HQ_SLACK_BOT_TOKEN_<NAME>_<WORKSPACE>`, infers the creator's Slack user_id (used as a DM gate), enumerates channels, and dispatches workers. Workers respond in-thread, ignore DMs from non-creators, and never call AskUserQuestion.

Surface architectural friction and propose deepening opportunities — turn shallow modules into deep ones for better testability and AI-navigability. Output: ranked candidate list with deletion-test outcome, leverage/locality scoring, file refs. Never edits code directly; presents candidates and walks the user through grilling-style design decisions for picked candidates. Use when the codebase is hard to change, when /diagnose hands off "no good test seam," or when planning a refactor wave.

Shared vocabulary and discipline for designing deep modules (a lot of behaviour behind a small interface, at a clean seam). Use when designing module boundaries or interfaces, or when another skill needs the deep-module vocabulary. Triggers on "deep module", "interface design", "design it twice".

Disciplined diagnosis loop for hard bugs, performance regressions, and intermittent failures. Build a deterministic feedback loop FIRST, then reproduce → hypothesise (3-5 ranked) → instrument (one variable at a time, tagged probes) → fix at the correct seam → cleanup + post-mortem. Use when the dominant problem is "I cannot reliably reproduce or measure this." For bugs that reproduce reliably with unknown root cause, use /investigate instead.

Actively build and sharpen a project's domain model — challenge fuzzy or overloaded terms against a glossary, stress-test with edge cases, and maintain CONTEXT.md as the source of truth for a ubiquitous language. Use when the user wants to pin down domain terminology, resolve a naming conflict, define a ubiquitous language, or when another skill needs to produce or sharpen the domain model. Triggers on "what should we call this", "domain model", "ubiquitous language", "define these terms", "update CONTEXT.md".

Enforce test-driven development with RED→GREEN→REFACTOR cycle and coverage validation

Break a plan, spec, or conversation into tracer-bullet vertical-slice tickets, each declaring its blocking edges (dependency order). Use when you have a plan/spec/PRD and need it decomposed into independently-executable tickets. Triggers on "break into tickets", "slice this into tasks", "vertical slices", "tracer bullets".

Plan a chunk of work too big for one agent session with a foggy destination — chart a shared map of investigation tickets and resolve them one per session until the path is clear. Use when the effort is too large to hold in one planning pass and the destination is unclear. Triggers on "too big to plan", "chart a map", "investigation tickets", "foggy scope".

Post structured Slack status messages via Block Kit using the pack's slack-ui.sh helper (header, body, fields, context). Prefer this over raw chat.postMessage curl for short inline replies and status updates. Supports dry-run payloads, plain-text fallback, auto-split for Slack block limits, canvas reports, and interactive decision asks with timeout/fallback.

Meta pipeline: review → land → deploy → smoke → heal → monitor. Takes one or more PRs from "open" through merged, deployed, live-verified, and monitored until every declared KPI is healthy. Use when asked to "ship this", "land and monitor", "take this all the way to prod", or when a feature spans repos and needs the full loop closed (per policy hq-smoke-cross-repo-contracts-before-done).

Host a full-stack or static app directly on the HQ Outpost / EC2 VM this session is running on, served through nginx. Finds a free port on the box, installs and configures nginx (static file serving or reverse-proxy to a running app), and returns the public URL. HARD-GATED — refuses to run anywhere that is not an HQ Outpost or EC2 instance and tells the user why. Use when the user says "host this app on the outpost", "serve this on the VM", "deploy my app to the outpost", "put this site on the box", or wants to expose a locally-running app from their Outpost. For sharing a generated artifact or vault file instead, use /deploy or /hq-share.

Summarize where a client stands across their lifecycle — pipeline stage, last touch, open items, and contract/billing state — joined read-only from the company's configured GTM silos, with the cross-source flags that mean someone needs to act. Company-agnostic; resolves every silo from companies/{co}/client-management.yaml. Read-first; any external side effect is confirmation-gated.

Compose a follow-up email for a given account/contact from their CRM record + recent activity, written in plain English for the recipient and shown as a draft for human approval. Reads the company's mail silo for thread context (connected) or degrades to a paste-ready body (native). Never sends. Company-agnostic; resolves owner, voice, and silos from companies/{co}/client-management.yaml.

Track a person's action items with mutable status, ingested from a company's signals store. Use when the user wants to process or work through their action items, check or update the action-item tracker, mark an item done or dismissed, or ingest new action items from signals. The read-only "what are my action items" query belongs to client-signals — this skill owns the mutable tracker. Company-agnostic: resolves company + owner from companies/{co}/client-management.yaml.

Surface a person's action items, commitments, decisions, risks, and open questions from a company's signals store — meeting intelligence extracted from that company's meeting notes. Use when the user asks "what are my action items", "what do I need to do", "what's on my plate", "what did I commit to", "check signals", or wants follow-ups, decisions, or risks pulled from recent meetings. Company-agnostic: resolves the company and owner from companies/{co}/client-management.yaml.

Stand up HQ's native CRM for a company, end to end — connect the services it already uses or build native HQ capabilities for the ones it doesn't, then turn the CRM on. Use when the user says "set up the CRM", "onboard <company> to the CRM", "turn on CRM for <company>", "get our pipeline into HQ", or is starting client management in HQ. Service-agnostic: no vendor is required. Writes companies/{co}/client-management.yaml, wires each GTM silo via /new-connection or a native-entity capability, enables crmEnabled, syncs, and verifies /crm returns data.

Pull a company's recent meeting notes, resolve attendees against its pipeline/CRM, and synthesize prioritized next steps per meeting. Use when the user asks "what are my next steps from this week's meetings", "follow-ups from my calls", "prep for my next touchpoint with {company}", or any variation combining recent meetings + CRM context + action planning. Company-agnostic: resolves the meeting source and pipeline from companies/{co}/client-management.yaml. Read-only.

Assemble a pre-call war room for a prospect from a company's entire GTM memory — the positioning that fits, proven objection rebuttals (cited to the call they landed in), a recommended demo/call path, and opening lines. Company-agnostic; resolves the corpus from the active company's qmd collections and client-management.yaml.

Post, read, reply, DM, search, and upload to Slack from the CLI — acting AS the owner via their own Slack app's user token (xoxp-, no MCP). Use whenever the user asks to send/post a Slack message, drop a note in a channel (e.g. "#general"), reply in a thread, DM someone, read recent messages, or search Slack. MCP-free and durable. First-time setup creates the user's own full-access Slack app — see the bundled guide.

Turn a self-contained HTML deck into an hq-deploy–hosted presentation with TWO cloud-synced links — a presentation link (the slides) and a notes/transcript link (your teleprompter) that stay in sync across devices over a zero-backend PubNub bridge. Use when asked to "set up presenter mode", "present this deck", "give me a synced presentation + notes link", "deploy the deck with speaker notes", or "two links — one for the slides, one for my script".

Double-entry accounting for a company — the umbrella entry point. Use when the user asks to set up books / a chart of accounts, record a transaction or journal entry, import a bank or QuickBooks statement, reconcile/map transactions to accounts, or read financial statements (trial balance, profit & loss, balance sheet). Routes to the focused sub-skills. Requires hq-pack-crm and the company's accountingEnabled setting.

Import a bank or QuickBooks CSV statement and turn each transaction into a balanced journal entry, mapping rows onto the chart of accounts. Use when the user asks to import transactions, load a bank/QuickBooks export, categorize or reconcile a statement, or bring outside transactions into the books. Drives scripts/acct-import.mjs and the account-map.json mapping.

Set up or extend a company's chart of accounts — the list of accounts (assets, liabilities, equity, income, expenses) that transactions post to. Use when the user asks to create a chart of accounts, set up their books, add a new account, or stamp the default accounts. Creates `account` ontology entities.

Issue and collect customer invoices (accounts receivable) and enter and pay vendor bills (accounts payable), each posting the correct double-entry. Use when the user asks to invoice a customer, record a payment received, enter a vendor bill, pay a bill, or check who owes them / what they owe. Ties each invoice/bill to a CRM company or contact.

Read a company's financial statements — trial balance, profit & loss (income statement), balance sheet, and account balances. Use when the user asks for their books, financials, P&L, income statement, balance sheet, trial balance, what an account's balance is, or how the business is doing financially. Reads the vault-synced accounting-projection.json.

Find any client's status from HQ's canonical client record — the native ontology CRM. Use when asked "where is this client?", "what's the status of <company>?", "show the pipeline by stage", "what's happened with <client> lately?", or "do we have a record for <company>?". Reads the vault-synced CRM projection that already joins every GTM silo (inbound, pipeline, contract, billing) plus the activity timeline onto one account record. Company-agnostic; requires the company's crmEnabled setting.

Create an execution-ready PRD for a project. Creates prd.json + README.md with full HQ context awareness. Runtime-agnostic — executes identically in Claude Code and Codex. Lightweight by default — uses batched questions and adapts interview depth to brainstorm context if available. For deep research subagents + 3-tier 15-question interview, use /deep-plan instead.

Codex-native router for executing HQ PRD stories. Default inline uses filesystem-mediated worker-phase spawn_agent workers; explicit interactive mode runs directly in the parent; Ralph/headless runs the same inline worker loop unattended (auto-advance, no pauses).

Deep project planning — research subagents (codebase / HQ / repo) + 3-tier 15-question interview (Strategic / Architecture / Quality) with smart-skip and pushback. Use for large or strategically important PRDs. For lightweight planning, use /plan instead. Adversarial spec review is delegated to /review-plan after generation.

Clean up an HQ git worktree — merge a detached worktree branch back into local main in the primary HQ tree, then remove the worktree and delete the branch. Use when HQ work happened in a separate worktree (e.g. .claude/worktrees/<name> on claude/*, or workspace/worktrees/<name> on codex/*) and needs to land and be cleaned up — including right after /handoff when HQ itself is running from a separate worktree. HQ is local-only; this workflow never pushes to a remote.

Commit every dirty file in the current repo, only when on main.

Pull a repo into HQ at latest main, fan out parallel exploration, and synthesize structured knowledge + (gated) policies under the owning company. Use when the user says "discover this repo", "ingest <repo>", "pull <repo> into HQ", or asks to learn a codebase HQ doesn't yet know.

Post-ship documentation sync — updates README, CLAUDE.md, architecture docs, and INDEX files to match what actually shipped. Use after merging a PR, completing a project, or deploying a release. Triggers on "update docs", "sync documentation", "docs are stale", "document what shipped".

Execute a single PRD story through coordinated worker phases (Ralph pattern). Each worker handles its domain, passes context to the next, with back-pressure (tests/lint/typecheck) keeping code on rails.

Iron Law debugging — systematic root cause investigation before any fixes. Scope lock, pattern classification, hypothesis testing with 3-strike rule, structured DEBUG REPORT. Use when debugging, fixing bugs, or tracing unexpected behavior. Triggers on "debug this", "fix this bug", "why is this broken", "root cause analysis".

Triage, review, and sequentially merge multiple open PRs. Handles CI monitoring, conflict resolution between PRs, Codex-style review, and post-merge deploy verification. Use when asked to "land all PRs", "merge open PRs", or "triage and ship".

Land a PR: monitor CI, resolve review issues, merge, monitor production. Use when asked to "land this", "merge and monitor", "ship this PR", or after PR creation when next step is merge + prod verification.

Universal pre-commit quality checks (typecheck, lint, test, coverage, dead code) with auto-detection and --fix support

Paranoid pre-landing code review. Reads git diff, runs two-pass analysis (CRITICAL blocks PR, INFORMATIONAL goes in body), surfaces issues with file:line references. Use when reviewing code before creating a PR, after finishing implementation, or when asked to review changes.

Multi-project pipeline orchestrator — triage, execute, PR, review, deploy with safety gates