diff --git a/docs/superpowers/specs/2026-04-21-master-agent-background-notification-design.md b/docs/superpowers/specs/2026-04-21-master-agent-background-notification-design.md
new file mode 100644
index 0000000..37796ad
--- /dev/null
+++ b/docs/superpowers/specs/2026-04-21-master-agent-background-notification-design.md
@@ -0,0 +1,32 @@
+# 主 Agent 后台通知设计
+
+目标：当用户不在 Boss App 前台时，如果主 Agent 会话收到新回复，Android 端必须像即时通讯工具一样给出系统通知；用户回到前台或正在查看该会话时，不重复通知。
+
+方案对比：
+1. 仅用现有 SSE 实时链路补本地通知。优点是改动最小、上线最快、复用现在已验证的实时链路；缺点是应用被系统彻底杀死时无法像 FCM 那样绝对到达。推荐先做这个。
+2. 引入 FCM 补离线推送。优点是彻底后台/杀进程场景覆盖更强；缺点是需要服务端推送凭据、设备 token 管理、通知路由与去重，改动面明显更大。
+3. 做前台服务常驻保活。优点是可提升存活率；缺点是侵入性强、耗电、系统限制更多，不适合作为第一批方案。
+
+本次设计：
+- 只针对 `master-agent` 会话里的“主 Agent -> 用户”回复发通知。
+- 触发源继续使用 `/api/v1/events` 的 SSE；收到 `project.messages.updated` 且 `projectId == master-agent` 时，从 `projectMessagesPayload.project.messages` 里取最后一条消息判断是否为主 Agent 回复。
+- 增加应用前后台跟踪器，判断 App 当前是否在前台、当前打开的会话是不是 `master-agent`。若正在前台看主 Agent 对话，则不通知；否则通知。
+- 增加通知去重：按最新消息 `message.id` 记忆，避免重连、补帧、重复事件导致连续弹多次。
+- 通知点击后直接打开 `ProjectDetailActivity(master-agent)`。
+- 若 Android 13+ 未授予通知权限，则静默跳过，不打断主流程。
+
+涉及文件：
+- 新增 `android/app/src/main/java/com/hyzq/boss/BossAppVisibilityTracker.java`
+- 新增 `android/app/src/main/java/com/hyzq/boss/BossNotificationRouter.java`
+- 修改 `android/app/src/main/java/com/hyzq/boss/BossApplication.java`
+- 修改 `android/app/src/main/java/com/hyzq/boss/BossRealtimeClient.java`
+- 修改 `android/app/src/main/java/com/hyzq/boss/MainActivity.java`
+- 修改 `android/app/src/main/java/com/hyzq/boss/ProjectDetailActivity.java`
+- 修改 `android/app/src/main/AndroidManifest.xml`
+- 新增测试 `android/app/src/test/java/com/hyzq/boss/BossNotificationRouterTest.java`
+- 修改测试 `android/app/src/test/java/com/hyzq/boss/ProjectDetailActivityRealtimeTest.java`
+- 修改测试 `android/app/src/test/java/com/hyzq/boss/BossRealtimeClientTest.java`
+
+边界：
+- 这批不做普通线程通知，不做群聊通知，不做 FCM。
+- 这批不解决“应用被系统彻底杀死时的绝对送达”，后续若你要补到微信级彻底离线送达，再上 FCM 第二期。