From e917387d4f578ea33c8748272fedbcfa3bcc362b Mon Sep 17 00:00:00 2001 From: Stefano Fiorini Date: Wed, 25 Mar 2026 11:59:10 -0500 Subject: [PATCH] Force sending Telegram notification upon stopping for user input --- docs/CREATE-PLAN.md | 3 ++- docs/IMPLEMENT-PLAN.md | 3 ++- docs/TELEGRAM-NOTIFICATIONS.md | 7 ++++--- skills/create-plan/claude-code/SKILL.md | 9 +++++---- skills/create-plan/codex/SKILL.md | 13 +++++++------ skills/create-plan/cursor/SKILL.md | 13 +++++++------ skills/create-plan/opencode/SKILL.md | 9 +++++---- skills/implement-plan/claude-code/SKILL.md | 9 +++++---- skills/implement-plan/codex/SKILL.md | 13 +++++++------ skills/implement-plan/cursor/SKILL.md | 13 +++++++------ skills/implement-plan/opencode/SKILL.md | 9 +++++---- .../tests/claude-review-template-guard.sh | 1 + 12 files changed, 57 insertions(+), 45 deletions(-) diff --git a/docs/CREATE-PLAN.md b/docs/CREATE-PLAN.md index 59f4ce2..26c4aaa 100644 --- a/docs/CREATE-PLAN.md +++ b/docs/CREATE-PLAN.md @@ -197,9 +197,10 @@ For all three CLIs, the preferred execution path is: ## Notifications -- Telegram is the only supported completion notification path. +- Telegram is the only supported notification path. - Shared setup: [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md) - Notification failures are non-blocking, but they must be surfaced to the user. +- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured. ## Template Guardrails diff --git a/docs/IMPLEMENT-PLAN.md b/docs/IMPLEMENT-PLAN.md index ea19e38..051e0fe 100644 --- a/docs/IMPLEMENT-PLAN.md +++ b/docs/IMPLEMENT-PLAN.md @@ -209,9 +209,10 @@ For all three CLIs, the preferred execution path is: ## Notifications -- Telegram is the only supported completion notification path. +- Telegram is the only supported notification path. - Shared setup: [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md) - Notification failures are non-blocking, but they must be surfaced to the user. +- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured. The helper also supports manual override flags for diagnostics: diff --git a/docs/TELEGRAM-NOTIFICATIONS.md b/docs/TELEGRAM-NOTIFICATIONS.md index 77b0c4f..31e9ad2 100644 --- a/docs/TELEGRAM-NOTIFICATIONS.md +++ b/docs/TELEGRAM-NOTIFICATIONS.md @@ -2,7 +2,7 @@ ## Purpose -Shared setup for Telegram completion notifications used by reviewer-driven skills such as `create-plan` and `implement-plan`. +Shared setup for Telegram notifications used by reviewer-driven skills such as `create-plan` and `implement-plan`, both for completion and for pauses that need user attention. ## Requirements @@ -66,7 +66,7 @@ test -x .cursor/skills/reviewer-runtime/notify-telegram.sh || test -x ~/.cursor/ ## Configure Telegram -Export the required variables before running a skill that sends completion notifications: +Export the required variables before running a skill that sends Telegram notifications: ```bash export TELEGRAM_BOT_TOKEN="" @@ -91,6 +91,7 @@ skills/reviewer-runtime/notify-telegram.sh --message "Telegram notification test ## Rules -- Telegram is the only supported completion notification path for these skills. +- Telegram is the only supported notification path for these skills. - Notification failures are non-blocking, but they must be surfaced to the user. +- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured. - Skills should report when Telegram is not configured instead of silently pretending a notification was sent. diff --git a/skills/create-plan/claude-code/SKILL.md b/skills/create-plan/claude-code/SKILL.md index 1ff3303..f6a7808 100644 --- a/skills/create-plan/claude-code/SKILL.md +++ b/skills/create-plan/claude-code/SKILL.md @@ -460,7 +460,7 @@ When handing off to execution, instruct: Private plan files under `~/.claude/plans/` are planning artifacts and must not be used as execution source of truth. -### Phase 10: Telegram Completion Notification (MANDATORY) +### Phase 10: Telegram Notification (MANDATORY) Resolve the Telegram notifier helper from the installed Claude Code skills directory: @@ -477,9 +477,10 @@ fi ``` Rules: -- Telegram is the only supported completion notification path. Do not use desktop notifications, `say`, email, or any other notifier. +- Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier. - Notification failures are non-blocking, but they must be surfaced to the user. -- If Telegram is not configured, state that no completion notification was sent. +- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured. +- If Telegram is not configured, state that no Telegram notification was sent. ## Tracker Discipline (MANDATORY) @@ -527,7 +528,7 @@ After completing any story: - [ ] `story-tracker.md` created with all stories as `pending` - [ ] `continuation-runbook.md` present - [ ] Handoff explicitly says to read runbook first and execute from plan folder -- [ ] Telegram completion notification attempted if configured +- [ ] Telegram notification attempted if configured ## Exit Triggers for Question Phase User says: "ready", "done", "let's plan", "proceed", "enough questions" diff --git a/skills/create-plan/codex/SKILL.md b/skills/create-plan/codex/SKILL.md index 040f9c3..3d04ac0 100644 --- a/skills/create-plan/codex/SKILL.md +++ b/skills/create-plan/codex/SKILL.md @@ -478,7 +478,7 @@ Always instruct the executing agent: Do not rely on planner-private files during implementation. -### Phase 10: Telegram Completion Notification (MANDATORY) +### Phase 10: Telegram Notification (MANDATORY) Resolve the Telegram notifier helper from the installed Codex skills directory: @@ -495,9 +495,10 @@ fi ``` Rules: -- Telegram is the only supported completion notification path. Do not use desktop notifications, `say`, email, or any other notifier. +- Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier. - Notification failures are non-blocking, but they must be surfaced to the user. -- If Telegram is not configured, state that no completion notification was sent. +- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured. +- If Telegram is not configured, state that no Telegram notification was sent. ## Quick Reference @@ -512,7 +513,7 @@ Rules: | 7 | Initialize `ai_plan/` + `.gitignore` | Local planning workspace ready | | 8 | Build plan package from templates | Full plan folder with required files | | 9 | Handoff with runbook-first instruction | Resumable execution context | -| 10 | Send Telegram completion notification | User notified or notification status reported | +| 10 | Send Telegram notification | User notified or notification status reported | ## Execution Rules to Include in Plan (MANDATORY) @@ -539,7 +540,7 @@ Rules: - Handoff without explicit "read runbook first" direction. - Skipping the reviewer phase without explicit user opt-out. - Not capturing the Codex session ID for resume in subsequent review rounds. -- Using any completion notification path other than Telegram. +- Using any notification path other than Telegram. ## Rationalizations and Counters @@ -575,4 +576,4 @@ Rules: - [ ] `story-tracker.md` present - [ ] `continuation-runbook.md` present - [ ] Handoff explicitly says to read runbook first and execute from plan folder -- [ ] Telegram completion notification attempted if configured +- [ ] Telegram notification attempted if configured diff --git a/skills/create-plan/cursor/SKILL.md b/skills/create-plan/cursor/SKILL.md index 4ec2cdd..528c882 100644 --- a/skills/create-plan/cursor/SKILL.md +++ b/skills/create-plan/cursor/SKILL.md @@ -488,7 +488,7 @@ Always instruct the executing agent: Do not rely on planner-private files during implementation. -### Phase 10: Telegram Completion Notification (MANDATORY) +### Phase 10: Telegram Notification (MANDATORY) Resolve the Telegram notifier helper from Cursor's installed skills directory: @@ -509,9 +509,10 @@ fi ``` Rules: -- Telegram is the only supported completion notification path. Do not use desktop notifications, `say`, email, or any other notifier. +- Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier. - Notification failures are non-blocking, but they must be surfaced to the user. -- If Telegram is not configured, state that no completion notification was sent. +- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured. +- If Telegram is not configured, state that no Telegram notification was sent. ## Quick Reference @@ -526,7 +527,7 @@ Rules: | 7 | Initialize `ai_plan/` + `.gitignore` | Local planning workspace ready | | 8 | Build plan package from templates | Full plan folder with required files | | 9 | Handoff with runbook-first instruction | Resumable execution context | -| 10 | Send Telegram completion notification | User notified or notification status reported | +| 10 | Send Telegram notification | User notified or notification status reported | ## Tracker Discipline (MANDATORY) @@ -567,7 +568,7 @@ After completing any story: - Omitting one or more required files in the plan package. - Handoff without explicit "read runbook first" direction. - Skipping the reviewer phase without explicit user opt-out. -- Using any completion notification path other than Telegram. +- Using any notification path other than Telegram. ## Red Flags - Stop and Correct @@ -593,7 +594,7 @@ After completing any story: - [ ] `story-tracker.md` present - [ ] `continuation-runbook.md` present - [ ] Handoff explicitly says to read runbook first and execute from plan folder -- [ ] Telegram completion notification attempted if configured +- [ ] Telegram notification attempted if configured ## Exit Triggers for Question Phase User says: "ready", "done", "let's plan", "proceed", "enough questions" diff --git a/skills/create-plan/opencode/SKILL.md b/skills/create-plan/opencode/SKILL.md index ca8702f..84ee3d1 100644 --- a/skills/create-plan/opencode/SKILL.md +++ b/skills/create-plan/opencode/SKILL.md @@ -468,7 +468,7 @@ Use templates from this skill's `templates/` folder. Always instruct the executing agent: > Read `ai_plan/YYYY-MM-DD-/continuation-runbook.md` first, then execute from `ai_plan` files only. -### Phase 11: Telegram Completion Notification (MANDATORY) +### Phase 11: Telegram Notification (MANDATORY) Resolve the Telegram notifier helper from the installed OpenCode skills directory: @@ -485,9 +485,10 @@ fi ``` Rules: -- Telegram is the only supported completion notification path. Do not use desktop notifications, `say`, email, or any other notifier. +- Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier. - Notification failures are non-blocking, but they must be surfaced to the user. -- If Telegram is not configured, state that no completion notification was sent. +- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured. +- If Telegram is not configured, state that no Telegram notification was sent. ## Tracker Discipline (MANDATORY) @@ -533,7 +534,7 @@ After completing any story: - [ ] `story-tracker.md` created with all stories as `pending` - [ ] `continuation-runbook.md` present - [ ] Handoff explicitly says to read runbook first and execute from plan folder -- [ ] Telegram completion notification attempted if configured +- [ ] Telegram notification attempted if configured ## Exit Triggers for Question Phase User says: "ready", "done", "let's plan", "proceed", "enough questions" diff --git a/skills/implement-plan/claude-code/SKILL.md b/skills/implement-plan/claude-code/SKILL.md index c518cc7..2268133 100644 --- a/skills/implement-plan/claude-code/SKILL.md +++ b/skills/implement-plan/claude-code/SKILL.md @@ -544,7 +544,7 @@ Present summary: **Branch:** implement/ (merged and deleted) ``` -### Phase 8: Telegram Completion Notification (MANDATORY) +### Phase 8: Telegram Notification (MANDATORY) Resolve the Telegram notifier helper from the installed Claude Code skills directory: @@ -561,9 +561,10 @@ fi ``` Rules: -- Telegram is the only supported completion notification path. Do not use desktop notifications, `say`, email, or any other notifier. +- Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier. - Notification failures are non-blocking, but they must be surfaced to the user. -- If Telegram is not configured, state that no completion notification was sent. +- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured. +- If Telegram is not configured, state that no Telegram notification was sent. ## Tracker Discipline (MANDATORY) @@ -599,4 +600,4 @@ Note: Commit hashes are backfilled into story Notes after the milestone commit ( - [ ] Final test suite passes - [ ] Worktree branch merged to parent and worktree deleted - [ ] Story tracker updated with final status -- [ ] Telegram completion notification attempted if configured +- [ ] Telegram notification attempted if configured diff --git a/skills/implement-plan/codex/SKILL.md b/skills/implement-plan/codex/SKILL.md index bebb82d..2f3c20d 100644 --- a/skills/implement-plan/codex/SKILL.md +++ b/skills/implement-plan/codex/SKILL.md @@ -577,7 +577,7 @@ Present summary: **Branch:** implement/ (merged and deleted) ``` -### Phase 8: Telegram Completion Notification (MANDATORY) +### Phase 8: Telegram Notification (MANDATORY) Resolve the Telegram notifier helper from the installed Codex skills directory: @@ -594,9 +594,10 @@ fi ``` Rules: -- Telegram is the only supported completion notification path. Do not use desktop notifications, `say`, email, or any other notifier. +- Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier. - Notification failures are non-blocking, but they must be surfaced to the user. -- If Telegram is not configured, state that no completion notification was sent. +- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured. +- If Telegram is not configured, state that no Telegram notification was sent. ## Quick Reference @@ -609,7 +610,7 @@ Rules: | 5 | Milestone review loop (per milestone) | Reviewer approval or max rounds + user override | | 6 | Invoke `superpowers:finishing-a-development-branch` | Branch merged to parent, worktree deleted | | 7 | Final report | Summary presented | -| 8 | Send Telegram completion notification | User notified or notification status reported | +| 8 | Send Telegram notification | User notified or notification status reported | ## Tracker Discipline (MANDATORY) @@ -637,7 +638,7 @@ Note: Commit hashes are backfilled into story Notes after the milestone commit ( - Not capturing the Codex session ID for resume in subsequent review rounds. - Forgetting to update `story-tracker.md` between stories. - Creating a new worktree when one already exists for a resumed plan. -- Using any completion notification path other than Telegram. +- Using any notification path other than Telegram. ## Rationalizations and Counters @@ -675,4 +676,4 @@ Note: Commit hashes are backfilled into story Notes after the milestone commit ( - [ ] Final test suite passes - [ ] Worktree branch merged to parent and worktree deleted - [ ] Story tracker updated with final status -- [ ] Telegram completion notification attempted if configured +- [ ] Telegram notification attempted if configured diff --git a/skills/implement-plan/cursor/SKILL.md b/skills/implement-plan/cursor/SKILL.md index 6b40671..3f3e65e 100644 --- a/skills/implement-plan/cursor/SKILL.md +++ b/skills/implement-plan/cursor/SKILL.md @@ -587,7 +587,7 @@ Present summary: **Branch:** implement/ (merged and deleted) ``` -### Phase 8: Telegram Completion Notification (MANDATORY) +### Phase 8: Telegram Notification (MANDATORY) Resolve the Telegram notifier helper from Cursor's installed skills directory: @@ -608,9 +608,10 @@ fi ``` Rules: -- Telegram is the only supported completion notification path. Do not use desktop notifications, `say`, email, or any other notifier. +- Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier. - Notification failures are non-blocking, but they must be surfaced to the user. -- If Telegram is not configured, state that no completion notification was sent. +- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured. +- If Telegram is not configured, state that no Telegram notification was sent. ## Quick Reference @@ -623,7 +624,7 @@ Rules: | 5 | Milestone review loop (per milestone) | Reviewer approval or max rounds + user override | | 6 | Invoke `superpowers:finishing-a-development-branch` | Branch merged to parent, worktree deleted | | 7 | Final report | Summary presented | -| 8 | Send Telegram completion notification | User notified or notification status reported | +| 8 | Send Telegram notification | User notified or notification status reported | ## Tracker Discipline (MANDATORY) @@ -649,7 +650,7 @@ Note: Commit hashes are backfilled into story Notes after the milestone commit ( - Skipping worktree setup and working directly on the main branch. - Forgetting to update `story-tracker.md` between stories. - Creating a new worktree when one already exists for a resumed plan. -- Using any completion notification path other than Telegram. +- Using any notification path other than Telegram. ## Red Flags - Stop and Correct @@ -678,4 +679,4 @@ Note: Commit hashes are backfilled into story Notes after the milestone commit ( - [ ] Final test suite passes - [ ] Worktree branch merged to parent and worktree deleted - [ ] Story tracker updated with final status -- [ ] Telegram completion notification attempted if configured +- [ ] Telegram notification attempted if configured diff --git a/skills/implement-plan/opencode/SKILL.md b/skills/implement-plan/opencode/SKILL.md index 49f355d..d2e076b 100644 --- a/skills/implement-plan/opencode/SKILL.md +++ b/skills/implement-plan/opencode/SKILL.md @@ -562,7 +562,7 @@ Present summary: **Branch:** implement/ (merged and deleted) ``` -### Phase 9: Telegram Completion Notification (MANDATORY) +### Phase 9: Telegram Notification (MANDATORY) Resolve the Telegram notifier helper from the installed OpenCode skills directory: @@ -579,9 +579,10 @@ fi ``` Rules: -- Telegram is the only supported completion notification path. Do not use desktop notifications, `say`, email, or any other notifier. +- Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier. - Notification failures are non-blocking, but they must be surfaced to the user. -- If Telegram is not configured, state that no completion notification was sent. +- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured. +- If Telegram is not configured, state that no Telegram notification was sent. ## Tracker Discipline (MANDATORY) @@ -615,4 +616,4 @@ Note: Commit hashes are backfilled into story Notes after the milestone commit ( - [ ] Final test suite passes - [ ] Worktree branch merged to parent and worktree deleted - [ ] Story tracker updated with final status -- [ ] Telegram completion notification attempted if configured +- [ ] Telegram notification attempted if configured diff --git a/skills/reviewer-runtime/tests/claude-review-template-guard.sh b/skills/reviewer-runtime/tests/claude-review-template-guard.sh index c65c1fa..45a42de 100755 --- a/skills/reviewer-runtime/tests/claude-review-template-guard.sh +++ b/skills/reviewer-runtime/tests/claude-review-template-guard.sh @@ -37,6 +37,7 @@ check_skill_file() { assert_contains "$file" "### P0" assert_contains "$file" "In progress N" assert_contains "$file" "notify-telegram.sh" + assert_contains "$file" "Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured." assert_not_contains "$file" "--allowedTools Read" }