Home/ai-coding-skills
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Force sending Telegram notification upon stopping for user input

Browse Source
This commit is contained in:
Stefano Fiorini
2026-03-25 11:59:10 -05:00
parent 63a048a26c
commit e917387d4f
12 changed files with 57 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
docs/CREATE-PLAN.md
View File

@@ -197,9 +197,10 @@ For all three CLIs, the preferred execution path is:
## Notifications ## Notifications
- Telegram is the only supported completion notification path. - Telegram is the only supported notification path.
- Shared setup: [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md) - Shared setup: [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md)
- Notification failures are non-blocking, but they must be surfaced to the user. - 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 ## Template Guardrails

3
docs/IMPLEMENT-PLAN.md
View File

@@ -209,9 +209,10 @@ For all three CLIs, the preferred execution path is:
## Notifications ## Notifications
- Telegram is the only supported completion notification path. - Telegram is the only supported notification path.
- Shared setup: [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md) - Shared setup: [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md)
- Notification failures are non-blocking, but they must be surfaced to the user. - 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: The helper also supports manual override flags for diagnostics:

7
docs/TELEGRAM-NOTIFICATIONS.md
View File

@@ -2,7 +2,7 @@
## Purpose ## 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 ## Requirements
@@ -66,7 +66,7 @@ test -x .cursor/skills/reviewer-runtime/notify-telegram.sh || test -x ~/.cursor/
## Configure Telegram ## 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 ```bash
export TELEGRAM_BOT_TOKEN="<bot-token>" export TELEGRAM_BOT_TOKEN="<bot-token>"
@@ -91,6 +91,7 @@ skills/reviewer-runtime/notify-telegram.sh --message "Telegram notification test
## Rules ## 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. - 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. - Skills should report when Telegram is not configured instead of silently pretending a notification was sent.

9
skills/create-plan/claude-code/SKILL.md
View File

@@ -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. 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: Resolve the Telegram notifier helper from the installed Claude Code skills directory:
@@ -477,9 +477,10 @@ fi
``` ```
Rules: 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. - 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) ## Tracker Discipline (MANDATORY)
@@ -527,7 +528,7 @@ After completing any story:
- [ ] `story-tracker.md` created with all stories as `pending` - [ ] `story-tracker.md` created with all stories as `pending`
- [ ] `continuation-runbook.md` present - [ ] `continuation-runbook.md` present
- [ ] Handoff explicitly says to read runbook first and execute from plan folder - [ ] 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 ## Exit Triggers for Question Phase
User says: "ready", "done", "let's plan", "proceed", "enough questions" User says: "ready", "done", "let's plan", "proceed", "enough questions"

13
skills/create-plan/codex/SKILL.md
View File

@@ -478,7 +478,7 @@ Always instruct the executing agent:
Do not rely on planner-private files during implementation. 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: Resolve the Telegram notifier helper from the installed Codex skills directory:
@@ -495,9 +495,10 @@ fi
``` ```
Rules: 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. - 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 ## Quick Reference
@@ -512,7 +513,7 @@ Rules:
| 7 | Initialize `ai_plan/` + `.gitignore` | Local planning workspace ready | | 7 | Initialize `ai_plan/` + `.gitignore` | Local planning workspace ready |
| 8 | Build plan package from templates | Full plan folder with required files | | 8 | Build plan package from templates | Full plan folder with required files |
| 9 | Handoff with runbook-first instruction | Resumable execution context | | 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) ## Execution Rules to Include in Plan (MANDATORY)
@@ -539,7 +540,7 @@ Rules:
- Handoff without explicit "read runbook first" direction. - Handoff without explicit "read runbook first" direction.
- Skipping the reviewer phase without explicit user opt-out. - Skipping the reviewer phase without explicit user opt-out.
- Not capturing the Codex session ID for resume in subsequent review rounds. - 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 ## Rationalizations and Counters
@@ -575,4 +576,4 @@ Rules:
- [ ] `story-tracker.md` present - [ ] `story-tracker.md` present
- [ ] `continuation-runbook.md` present - [ ] `continuation-runbook.md` present
- [ ] Handoff explicitly says to read runbook first and execute from plan folder - [ ] Handoff explicitly says to read runbook first and execute from plan folder
- [ ] Telegram completion notification attempted if configured - [ ] Telegram notification attempted if configured

13
skills/create-plan/cursor/SKILL.md
View File

@@ -488,7 +488,7 @@ Always instruct the executing agent:
Do not rely on planner-private files during implementation. 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: Resolve the Telegram notifier helper from Cursor's installed skills directory:
@@ -509,9 +509,10 @@ fi
``` ```
Rules: 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. - 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 ## Quick Reference
@@ -526,7 +527,7 @@ Rules:
| 7 | Initialize `ai_plan/` + `.gitignore` | Local planning workspace ready | | 7 | Initialize `ai_plan/` + `.gitignore` | Local planning workspace ready |
| 8 | Build plan package from templates | Full plan folder with required files | | 8 | Build plan package from templates | Full plan folder with required files |
| 9 | Handoff with runbook-first instruction | Resumable execution context | | 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) ## Tracker Discipline (MANDATORY)
@@ -567,7 +568,7 @@ After completing any story:
- Omitting one or more required files in the plan package. - Omitting one or more required files in the plan package.
- Handoff without explicit "read runbook first" direction. - Handoff without explicit "read runbook first" direction.
- Skipping the reviewer phase without explicit user opt-out. - 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 ## Red Flags - Stop and Correct
@@ -593,7 +594,7 @@ After completing any story:
- [ ] `story-tracker.md` present - [ ] `story-tracker.md` present
- [ ] `continuation-runbook.md` present - [ ] `continuation-runbook.md` present
- [ ] Handoff explicitly says to read runbook first and execute from plan folder - [ ] 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 ## Exit Triggers for Question Phase
User says: "ready", "done", "let's plan", "proceed", "enough questions" User says: "ready", "done", "let's plan", "proceed", "enough questions"

9
skills/create-plan/opencode/SKILL.md
View File

@@ -468,7 +468,7 @@ Use templates from this skill's `templates/` folder.
Always instruct the executing agent: Always instruct the executing agent:
> Read `ai_plan/YYYY-MM-DD-<short-title>/continuation-runbook.md` first, then execute from `ai_plan` files only. > Read `ai_plan/YYYY-MM-DD-<short-title>/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: Resolve the Telegram notifier helper from the installed OpenCode skills directory:
@@ -485,9 +485,10 @@ fi
``` ```
Rules: 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. - 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) ## Tracker Discipline (MANDATORY)
@@ -533,7 +534,7 @@ After completing any story:
- [ ] `story-tracker.md` created with all stories as `pending` - [ ] `story-tracker.md` created with all stories as `pending`
- [ ] `continuation-runbook.md` present - [ ] `continuation-runbook.md` present
- [ ] Handoff explicitly says to read runbook first and execute from plan folder - [ ] 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 ## Exit Triggers for Question Phase
User says: "ready", "done", "let's plan", "proceed", "enough questions" User says: "ready", "done", "let's plan", "proceed", "enough questions"

9
skills/implement-plan/claude-code/SKILL.md
View File

@@ -544,7 +544,7 @@ Present summary:
**Branch:** implement/<plan-folder-name> (merged and deleted) **Branch:** implement/<plan-folder-name> (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: Resolve the Telegram notifier helper from the installed Claude Code skills directory:
@@ -561,9 +561,10 @@ fi
``` ```
Rules: 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. - 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) ## Tracker Discipline (MANDATORY)
@@ -599,4 +600,4 @@ Note: Commit hashes are backfilled into story Notes after the milestone commit (
- [ ] Final test suite passes - [ ] Final test suite passes
- [ ] Worktree branch merged to parent and worktree deleted - [ ] Worktree branch merged to parent and worktree deleted
- [ ] Story tracker updated with final status - [ ] Story tracker updated with final status
- [ ] Telegram completion notification attempted if configured - [ ] Telegram notification attempted if configured

13
skills/implement-plan/codex/SKILL.md
View File

@@ -577,7 +577,7 @@ Present summary:
**Branch:** implement/<plan-folder-name> (merged and deleted) **Branch:** implement/<plan-folder-name> (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: Resolve the Telegram notifier helper from the installed Codex skills directory:
@@ -594,9 +594,10 @@ fi
``` ```
Rules: 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. - 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 ## Quick Reference
@@ -609,7 +610,7 @@ Rules:
| 5 | Milestone review loop (per milestone) | Reviewer approval or max rounds + user override | | 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 | | 6 | Invoke `superpowers:finishing-a-development-branch` | Branch merged to parent, worktree deleted |
| 7 | Final report | Summary presented | | 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) ## 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. - Not capturing the Codex session ID for resume in subsequent review rounds.
- Forgetting to update `story-tracker.md` between stories. - Forgetting to update `story-tracker.md` between stories.
- Creating a new worktree when one already exists for a resumed plan. - 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 ## Rationalizations and Counters
@@ -675,4 +676,4 @@ Note: Commit hashes are backfilled into story Notes after the milestone commit (
- [ ] Final test suite passes - [ ] Final test suite passes
- [ ] Worktree branch merged to parent and worktree deleted - [ ] Worktree branch merged to parent and worktree deleted
- [ ] Story tracker updated with final status - [ ] Story tracker updated with final status
- [ ] Telegram completion notification attempted if configured - [ ] Telegram notification attempted if configured

13
skills/implement-plan/cursor/SKILL.md
View File

@@ -587,7 +587,7 @@ Present summary:
**Branch:** implement/<plan-folder-name> (merged and deleted) **Branch:** implement/<plan-folder-name> (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: Resolve the Telegram notifier helper from Cursor's installed skills directory:
@@ -608,9 +608,10 @@ fi
``` ```
Rules: 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. - 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 ## Quick Reference
@@ -623,7 +624,7 @@ Rules:
| 5 | Milestone review loop (per milestone) | Reviewer approval or max rounds + user override | | 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 | | 6 | Invoke `superpowers:finishing-a-development-branch` | Branch merged to parent, worktree deleted |
| 7 | Final report | Summary presented | | 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) ## 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. - Skipping worktree setup and working directly on the main branch.
- Forgetting to update `story-tracker.md` between stories. - Forgetting to update `story-tracker.md` between stories.
- Creating a new worktree when one already exists for a resumed plan. - 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 ## 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 - [ ] Final test suite passes
- [ ] Worktree branch merged to parent and worktree deleted - [ ] Worktree branch merged to parent and worktree deleted
- [ ] Story tracker updated with final status - [ ] Story tracker updated with final status
- [ ] Telegram completion notification attempted if configured - [ ] Telegram notification attempted if configured

9
skills/implement-plan/opencode/SKILL.md
View File

@@ -562,7 +562,7 @@ Present summary:
**Branch:** implement/<plan-folder-name> (merged and deleted) **Branch:** implement/<plan-folder-name> (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: Resolve the Telegram notifier helper from the installed OpenCode skills directory:
@@ -579,9 +579,10 @@ fi
``` ```
Rules: 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. - 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) ## Tracker Discipline (MANDATORY)
@@ -615,4 +616,4 @@ Note: Commit hashes are backfilled into story Notes after the milestone commit (
- [ ] Final test suite passes - [ ] Final test suite passes
- [ ] Worktree branch merged to parent and worktree deleted - [ ] Worktree branch merged to parent and worktree deleted
- [ ] Story tracker updated with final status - [ ] Story tracker updated with final status
- [ ] Telegram completion notification attempted if configured - [ ] Telegram notification attempted if configured

1
skills/reviewer-runtime/tests/claude-review-template-guard.sh
View File

@@ -37,6 +37,7 @@ check_skill_file() {
assert_contains "$file" "### P0" assert_contains "$file" "### P0"
assert_contains "$file" "In progress N" assert_contains "$file" "In progress N"
assert_contains "$file" "notify-telegram.sh" 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" assert_not_contains "$file" "--allowedTools Read"
} }