Align reviewer runtime and Telegram notifications

docs/TELEGRAM-NOTIFICATIONS.md

@@ -0,0 +1,96 @@
+# TELEGRAM-NOTIFICATIONS
+
+## Purpose
+
+Shared setup for Telegram completion notifications used by reviewer-driven skills such as `create-plan` and `implement-plan`.
+
+## Requirements
+
+- Telegram bot token in `TELEGRAM_BOT_TOKEN`
+- Telegram chat id in `TELEGRAM_CHAT_ID`
+- Notification helper installed beside the shared reviewer runtime:
+  - Codex: `~/.codex/skills/reviewer-runtime/notify-telegram.sh`
+  - Claude Code: `~/.claude/skills/reviewer-runtime/notify-telegram.sh`
+  - OpenCode: `~/.config/opencode/skills/reviewer-runtime/notify-telegram.sh`
+  - Cursor: `.cursor/skills/reviewer-runtime/notify-telegram.sh` or `~/.cursor/skills/reviewer-runtime/notify-telegram.sh`
+
+## Install
+
+The helper ships from `skills/reviewer-runtime/` together with `run-review.sh`.
+
+### Codex
+
+```bash
+mkdir -p ~/.codex/skills/reviewer-runtime
+cp -R skills/reviewer-runtime/* ~/.codex/skills/reviewer-runtime/
+```
+
+### Claude Code
+
+```bash
+mkdir -p ~/.claude/skills/reviewer-runtime
+cp -R skills/reviewer-runtime/* ~/.claude/skills/reviewer-runtime/
+```
+
+### OpenCode
+
+```bash
+mkdir -p ~/.config/opencode/skills/reviewer-runtime
+cp -R skills/reviewer-runtime/* ~/.config/opencode/skills/reviewer-runtime/
+```
+
+### Cursor
+
+Repo-local install:
+
+```bash
+mkdir -p .cursor/skills/reviewer-runtime
+cp -R skills/reviewer-runtime/* .cursor/skills/reviewer-runtime/
+```
+
+Global install:
+
+```bash
+mkdir -p ~/.cursor/skills/reviewer-runtime
+cp -R skills/reviewer-runtime/* ~/.cursor/skills/reviewer-runtime/
+```
+
+## Verify Installation
+
+```bash
+test -x ~/.codex/skills/reviewer-runtime/notify-telegram.sh || true
+test -x ~/.claude/skills/reviewer-runtime/notify-telegram.sh || true
+test -x ~/.config/opencode/skills/reviewer-runtime/notify-telegram.sh || true
+test -x .cursor/skills/reviewer-runtime/notify-telegram.sh || test -x ~/.cursor/skills/reviewer-runtime/notify-telegram.sh || true
+```
+
+## Configure Telegram
+
+Export the required variables before running a skill that sends completion notifications:
+
+```bash
+export TELEGRAM_BOT_TOKEN="<bot-token>"
+export TELEGRAM_CHAT_ID="<chat-id>"
+```
+
+Optional:
+
+```bash
+export TELEGRAM_API_BASE_URL="https://api.telegram.org"
+```
+
+## Test the Helper
+
+Example:
+
+```bash
+TELEGRAM_BOT_TOKEN="<bot-token>" \
+TELEGRAM_CHAT_ID="<chat-id>" \
+skills/reviewer-runtime/notify-telegram.sh --message "Telegram notification test"
+```
+
+## Rules
+
+- Telegram is the only supported completion notification path for these skills.
+- Notification failures are non-blocking, but they must be surfaced to the user.
+- Skills should report when Telegram is not configured instead of silently pretending a notification was sent.