ForgeBot Mention Apple Watch Alert

Step-by-step plan

1. Choose the alert path

   Use option A: a direct ForgeBot Slack mention creates a ForgeBot DM to Adam, and Slack mobile notification mirroring carries that DM to Apple Watch.

2. Keep Hermes as the Slack harness

   Handle the Slack event inside Hermes, where ForgeBot gateway traffic already enters the system. The alert should fire before the agent run continues.

3. Keep the scope narrow

   Do not add a native Apple Watch push path, phone bridge, iMessage route, Reminders workflow, or macOS Notification Center dependency.

4. Start with the red TDD tracer

   Use the focused TypeScript behavior test as the contract for turning a Hermes Slack mention context into one Adam DM alert payload.

5. Build the alert payload policy

   The policy should produce a stable dedupe key, disable link unfurling, and include concise channel, sender, permalink, and trimmed source message details.

6. Require Doppler-injected auth

   Verify the required Slack credential names through Doppler and fail loudly if any are missing. Do not read dotenv files or create local fallback secrets.

7. Run the gateway under Doppler

   The live Hermes gateway should inherit its Slack credentials from Doppler at process launch. Restarting the gateway remains an owner-gated action.

8. Confirm the hook loads

   Check gateway logs for the mention-alert hook loading successfully before testing detection or Slack delivery.

9. Dry-run the mention detector

   Feed a synthetic direct mention into the hook with sending disabled. The dry run should print the alert text and prove dedupe behavior without calling Slack.

10. Send one controlled live mention

    Use a safe test mention in a controlled Slack location. Success means exactly one ForgeBot DM reaches Adam with usable source context.

11. Verify the Apple Watch side

    Confirm the Slack DM appears on Adam's phone and Apple Watch mirrors it. If the DM arrives but the Watch does not buzz, the remaining issue is notification configuration.

12. Monitor and tighten

    Watch for duplicate DMs, missing channel metadata, failed Slack sends, or suppressed Watch notifications, then tune dedupe, permissions, and notification settings.

Numbered verification checklist

1. Doppler access works

   The host can authenticate to Doppler and fetch the configured environment without printing secret values.

2. Required Slack credentials exist

   The expected Slack credential names are present in the production Doppler config.

3. Hermes is running with injected secrets

   The gateway process receives credentials from Doppler at launch, not from dotenv files or local fallbacks.

4. The alert hook is loaded

   Gateway logs show the ForgeBot mention-alert hook loaded without errors.

5. Dry run succeeds

   A synthetic mention produces the expected alert text and does not call Slack.

6. Live Slack delivery succeeds

   A controlled direct mention sends exactly one ForgeBot DM to Adam.

7. Phone and Watch receive it

   The Slack DM appears on Adam's iPhone and Apple Watch mirrors the notification.

Numbered failure handling

1. Missing Slack credential in the gateway environment

   Meaning: the gateway was not launched with the required Doppler-injected credential. Fix: confirm the required secret names exist, then relaunch through Doppler.

2. Channel lookup fails

   Meaning: ForgeBot lacks access to the source channel or Slack does not allow metadata lookup. Fix: invite ForgeBot to the channel or use an ID-only label.

3. DM does not arrive

   Meaning: the Slack API send path failed. Fix: check gateway auth injection, bot scopes, and Slack API errors in gateway logs.

4. DM arrives but Watch does not buzz

   Meaning: Hermes and Slack delivery worked; notification configuration is the remaining issue. Fix: adjust Slack iPhone notifications, Watch mirroring, or Focus rules.

5. Duplicate DMs appear

   Meaning: the dedupe key is unstable or dedupe state is not persisting. Fix: use Slack event identity and persist state near the hook runtime.

Numbered open questions

1. Adam's own mentions: Should Adam's own mentions trigger alerts during testing only, or stay suppressed by default?
2. Who can trigger alerts: Should every direct ForgeBot mention alert Adam, or only mentions from other people?
3. Alert content: Should alerts include message text, or only sender, channel, and permalink for privacy?
4. Hook failure routing: Should hook failures stay in local logs, or send a rate-limited failure DM?

This page is a sanitized public preview. The implementation plan in the ForgeApps repo keeps exact identifiers, commands, and file paths for local execution.