Work Broadcast

Compose a Slack broadcast for completed or proposed work. Channel posts are doorways, not documents — keep them short and link out to detail.

Arguments: [company] [context — PR URL, feature name, or description of what shipped]

Step 1 — Resolve company

Infer company from context (cwd, repo, manifest lookup, or explicit argument). Required for channel routing and credential lookup.

Step 2 — Assess tier

Measure the change size to determine the broadcast tier:

Tier	Size	Message format
Small	<50 lines changed, single-file	1 line: lead emoji, bold change name, PR link
Medium	50–300 lines, single feature/API	Up to 3 lines: one-sentence summary, 1–2 bullets max, PR link
Large	>300 lines, multi-file feature, infra rollout, project milestone	Deploy a marketing page with the deploy skill, then post 1 line: summary + page URL + PR link(s)

When unsure which tier applies, ask the user once with a one-line summary of why you're unsure.

Large tier — marketing page

For Large broadcasts, build and deploy a summary page before composing the Slack message:

1. Create a single-page site (HTML or Astro) summarizing the change — what shipped, why it matters, key details, screenshots if relevant
2. Deploy via the deploy skill (.claude/skills/deploy/SKILL.md)
3. Use the deployed URL as the primary link in the Slack message

The Slack message itself stays at 1 line — all detail lives on the page.

Step 3 — Load channel routing

Read companies/{co}/settings/slack/channels.yaml to determine the target channel.

The YAML maps channel purposes to Slack channel IDs or names. Pick the channel that best matches the work type (engineering, product, general, etc.). If no channels file exists or no channel matches, ask the user which channel to post to.

Step 4 — Compose message

All tiers follow these composition rules:

• Lead with :chart_with_upwards_trend: as the visual signature
• Bold the change name using Slack format (*name*)
• Never include file paths or function names
• Never include open questions, sub-sections, or multi-bullet lists in the Slack message itself — those belong on the marketing page or in the PR description
• No emoji decoration beyond the standard :chart_with_upwards_trend: lead

Templates

Small:

:chart_with_upwards_trend: *Change Name* — one-sentence summary. <PR-URL>

Medium:

:chart_with_upwards_trend: *Change Name* — one-sentence summary.
• Key detail or impact point
• Second detail (optional)
<PR-URL>

Large:

:chart_with_upwards_trend: *Change Name* — one-sentence summary. <PAGE-URL> | <PR-URL(s)>

Step 5 — Resolve the broadcaster's personal token

A work broadcast posts as the person running the skill, so the Slack user token must belong to that person — never a shared or company-wide token. A single shared user token makes every teammate's broadcast appear under one person's name, which is wrong and confusing.

Read companies/{co}/settings/slack/credentials.json for two fields:

• personal_secret — name of the per-person secret holding the Slack user token (xoxp-…). Defaults to SLACK_USER_TOKEN when the field is absent.
• slack_workspace — the Slack workspace the token must belong to (used only to guide onboarding).

Resolve the token from the running person's personal vault, never the company vault:

hq secrets --personal list   # confirms the name exists; never reveals the value

The --personal scope is keyed to the caller's own identity, so each teammate automatically resolves their own token with the same secret name. Never read this user token with --company — a company-scoped user token is exactly the shared-identity bug this design exists to prevent. (A company-scoped bot token is fine for other purposes, but work broadcasts post as the human, not the bot.)

• Personal secret present → continue to Step 6.
• Personal secret missing → run the onboarding in Step 5a first, then continue.

Never capture, echo, log, or command-substitute the token value. The agent never needs to see it — hq secrets … exec injects it directly into the child process at send time (Step 7).

Step 5a — Onboarding: help the person mint and store their token

Runs only when the running person has no personal Slack user token yet. It works for any person and any workspace — nothing here is company-specific. The agent guides; the agent never sees the token value.

1. Explain that posting as themselves requires their own Slack user token (xoxp-…), which only they can mint, and that they will paste it into a secure prompt the agent cannot read.

2. Acquire the token. If credentials.json provides a slack_app_oauth_url, send the person there to authorize and copy their User OAuth Token. Otherwise walk them through the generic self-serve path:

   • Open https://api.slack.com/apps → Create New App → From scratch.
   • Name it (e.g. "HQ Broadcasts") and select the {slack_workspace} workspace.
   • OAuth & Permissions → User Token Scopes → add chat:write.
   • Install to Workspace → authorize.
   • Copy the User OAuth Token — it starts with xoxp-.

3. Store it without exposing it — two ways, both keep the value out of the agent's process (never echoed, never a command argument, never pasted into chat or a file). Prefer (a) for remote teammates or anyone not sitting at a terminal with hq:

   (a) Browser self-capture link. The agent mints a one-time secrets-input link; the person opens it and pastes their token into the web form, so the value never touches a terminal:

   hq secrets --personal generate-link SLACK_USER_TOKEN --expires 30m
   

   generate-link works under --personal — the link is a one-time write-capability to the person's own secret, so only they need it. Render the URL to the person as EXACTLY ONE Markdown inline link (label carries no token, href carries the full token), per the hard policy hq-secure-link-render-as-markdown:

   [Capture your Slack user token — expires <ts>](<full-url-with-token>)
   

   Mint it only in this (parent) turn — never echo it as bare text or inside a code fence, never delegate minting to a sub-agent, and refer to it only in redacted form on any later turn. The exposed token is single-use: if it ever leaks as bare text, mint a fresh one.

   (b) Interactive terminal setter. The person runs this themselves in their own terminal:

   hq secrets --personal set SLACK_USER_TOKEN
   

   Use the personal_secret name from credentials.json if it differs from SLACK_USER_TOKEN. Never ask the person to paste the token into the chat, a file, or a command argument — only into the browser form or this interactive prompt.

4. Confirm it stored: hq secrets --personal list shows the name (not the value). Optionally validate the token works without printing it:

   hq secrets --personal exec --only SLACK_USER_TOKEN -- \
     bash -c 'curl -s -H "Authorization: Bearer $SLACK_USER_TOKEN" https://slack.com/api/auth.test | jq "{ok, user, team}"'
   

5. Resume the broadcast at Step 6.

Security: token writes and any capability minting happen in this (parent) turn — never delegate them to a sub-agent. Never reveal the value with get --reveal in this flow.

Step 6 — Confirm draft (MANDATORY)

Before presenting the draft, run the channel-aware humanize pass on the summary line per core/knowledge/public/hq-core/humanize-before-send.md (channel work-broadcast, intensity light). Clean only the prose a human reads: strip AI vocabulary, em/en dashes, and promotional framing from the one-sentence summary. Never touch the :chart_with_upwards_trend: signature, the PR/page links, the channel, or the Slack *bold* markup.

Present the composed message to the user exactly as it will appear in Slack, including the target channel:

Channel: #channel-name
Message:
:chart_with_upwards_trend: *Change Name* — summary...

Wait for explicit approval before sending. If the user edits the draft, use their version. Never auto-send.

Step 7 — Send

Post the message with the running person's personal token. Two rules make this safe and avoid the Bash-harness quoting trap (see policy work-broadcast-jq-inline-recipe-fails-bash-harness):

1. Build the JSON body with jq -n in the PARENT shell, using a single-quoted filter, and validate it with printf '%s' "$PAYLOAD" | jq -e . before sending — use printf, not echo, since some echo builtins re-interpret the \n escapes in the pretty-printed JSON and make jq reject a body that curl would post fine. Do not nest the jq -n "{…}" substitution inside the single-quoted bash -c — the harness mangles the brace filter and curl errors with option : blank argument.
2. Pass the validated payload to the child as an env var. The child bash -c runs only curl, so $SLACK_USER_TOKEN (injected by hq secrets … exec) still expands inside the child — keeping the token out of the parent shell and out of the agent's view.

PAYLOAD=$(jq -n --arg c "$CHANNEL" --arg t "$MESSAGE" '{channel:$c, text:$t, unfurl_links:true}')
printf '%s' "$PAYLOAD" | jq -e . >/dev/null && echo "payload-valid"
PAYLOAD="$PAYLOAD" hq secrets --personal exec --only SLACK_USER_TOKEN -- bash -c '
  curl -s -X POST https://slack.com/api/chat.postMessage \
    -H "Authorization: Bearer $SLACK_USER_TOKEN" \
    -H "Content-Type: application/json" \
    --data "$PAYLOAD"
' | jq -r 'if .ok then "OK ts=\(.ts)" else "ERROR: \(.error)" end'

If credentials.json sets a different personal_secret name, substitute it for SLACK_USER_TOKEN in both --only and the Bearer $… reference so they stay matched.

Confirm the output is OK ts=….

• On not_authed, token_revoked, invalid_auth, or a missing secret → the running person's token is absent or expired. Send them through Step 5a to (re)mint it. Never fall back to another person's token or a company-shared token — that reintroduces the shared-identity bug.
• On channel_not_found / not_in_channel → fix the channel (Step 3), not the credentials.

Report any other error to the user; do not silently retry with different credentials or channels.

Step 8 — Report

✓ Posted to #channel-name
  Tier: Small | Medium | Large
  Message: [first line of message]