Skip to content

docs: strengthen Telegram notifications to MUST when bridge active #205

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
v4lheru wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: strengthen Telegram notifications to MUST when bridge active #205

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 16 additions & 11 deletions pact-plugin/CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -239,35 +239,40 @@ When making decisions, consider which horizon applies. Misalignment indicates mo
**Remember**: `CLAUDE.md` is your single source of truth for understanding the project. Keep it updated and comprehensive to maintain effective development continuity
- To make updates, execute `/PACT:pin-memory`

### Telegram Notifications (Optional)
### Telegram Notifications (Optional — but MANDATORY when available)

Telegram is an **optional** add-on. Not all PACT users have it installed. **Before using any telegram tool, check if it exists in your available tools.** If `telegram_notify` is not listed, do NOT attempt to call it — skip all Telegram functionality silently with no errors or warnings to the user.

**How to check**: If `telegram_notify` appears in your tool list, the bridge is active. If not, ignore this entire section.

**Available tools** (only when bridge is active):
**When the bridge IS active, notifications are NOT optional — they are REQUIRED.** The user expects to be kept informed via Telegram. Failing to send notifications is a failure to communicate.

**Available tools:**
| Tool | Purpose | Blocking? |
|------|---------|-----------|
| `telegram_notify` | Send one-way notification (completions, deployments, alerts) | No |
| `telegram_ask` | Ask a blocking question with optional buttons; supports text/voice replies | Yes |
| `telegram_check_replies` | Poll for queued replies to notifications | No |
| `telegram_status` | Health check (connection, mode, queue depth) | No |

**When to notify** (target ~3-5 per session):
- Task or phase completions
- Blockers found or algedonic signals
- PR ready for review or merged
- Deployments pushed
**You MUST send `telegram_notify`** for these events (target ~3-5 per session):
- Task or phase completions — "Phase X complete: [summary]"
- Blockers found or algedonic signals — "Blocked: [issue]"
- PR created, ready for review, or merged — "PR #N: [title]"
- Deployments or pushes to production — "Deployed: [what]"
- Long-running operations started — "Starting: [task], will notify when done"

**When to use `telegram_ask`**:
- Blocking decisions where user may be away from terminal
- Scope clarifications that can't proceed without input
**You MUST use `telegram_ask`** when:
- User input is needed and they may be away from the terminal
- Scope clarifications that block progress

**When to check replies** (`telegram_check_replies`):
**You MUST check `telegram_check_replies`**:
- Between tasks or phases — check if user reacted to any notification
- After sending important notifications — user may reply with corrections or new instructions
- Replies include context snippet of the original notification

**Do NOT notify** for routine internal steps (agent spawning, file reads, minor progress).

**Multi-session behavior**:
- Messages are prefixed with `[ProjectName]` for session identification
- Multiple sessions coordinate via file-based polling — replies route to the correct session
Expand Down