feat(notify): Add support for sending plain text messages

[tbrandenburg]

Problem

Currently, the work notify send command only supports sending notifications about existing work items via query syntax (where <query> to <target> or TASK-001 to <target>). Users cannot send arbitrary messages like status updates, announcements, or free-form notifications without creating a work item first.

Solution

Extended the work notify send command to accept a third syntax: work notify send "message content" to <target>. The command parser detects quoted message strings and bypasses the work item query path, formatting and sending the message directly to the specified target.

Detection heuristic: Messages containing spaces or newlines are treated as plain messages; single-word inputs are treated as task IDs.

Implementation approach: Uses a special marker work item (__plain_message__ ID) to signal plain message mode to handlers, avoiding breaking changes to the TargetHandler interface.

Changes

Core Implementation

• src/cli/commands/notify/send.ts: Added third syntax branch for message detection
• src/core/engine.ts: Added sendPlainNotification() method
• src/core/notification-service.ts: Added sendPlainNotification() using marker work item
• src/core/target-handlers/telegram-handler.ts: Added formatPlainMessage() with 📬 icon formatting

Testing

• tests/e2e/telegram-notification.test.ts: Added e2e test for plain message delivery
• All 389 tests passing (added 1 new test, 0 regressions)

Documentation

• Added implementation plan and report in .claude/PRPs/

Testing

Validation Performed

• ✅ Type-check passes (0 errors)
• ✅ Lint passes (0 errors, 0 warnings)
• ✅ Unit tests: 389 passed
• ✅ E2E tests: All telegram tests pass including new plain message test
• ✅ Build succeeds

Target Support

Target	Plain Message Support	Notes
telegram	✅ Full support	Special formatting with 📬 icon, HTML escaping, 4096 char limit
bash	✅ Automatic	Scripts receive message in JSON, can detect __plain_message__ marker

Example Usage

# Single-line message
work notify send "Deployment complete - all systems operational" to alerts

# Multi-line message (shell handles quotes)
work notify send 'Status Update:
✅ Tests passing
✅ Build successful  
🚀 Ready for deployment' to team-notifications

# Existing syntaxes still work unchanged
work notify send TASK-001 to alerts
work notify send where priority=high to alerts

Implementation Details

Security & Best Practices

• HTML Escaping: User messages escaped (<, >, &) to prevent injection
• Input Validation: Explicit validation per oclif strict=false best practices
• Character Limits: Telegram 4096 char limit enforced with truncation notice
• Current Standards: Verified against Telegram Bot API docs (2026-02-01)

Architecture Decisions

• Marker Work Item Pattern: Chose __plain_message__ marker over interface extension for MVP simplicity
• Detection Heuristic: "Spaces OR newlines" intuitive for users (task IDs are single words)
• Handler-Level Formatting: Each handler formats according to its requirements

Notes

• Multi-line messages work with proper shell quoting (user responsibility)
• Bash handler automatically supports plain messages via JSON passthrough
• Future: Could extend to proper TargetHandler interface method if needed
• Implementation follows existing patterns and conventions throughout codebase

---

Related: Implementation of feature request for direct message notifications without work item dependency.