docs: define v1 requirements

18 requirements across 5 categories
6 requirements deferred to v2

.planning/REQUIREMENTS.md

@@ -0,0 +1,96 @@
+# Requirements: Telegram Claude Code Bridge
+
+**Defined:** 2026-02-04
+**Core Value:** Frictionless conversation with Claude Code from anywhere via Telegram
+
+## v1 Requirements
+
+### Core Messaging
+
+- [ ] **MSG-01**: Incoming Telegram message auto-triggers Claude Code session and sends response back
+- [ ] **MSG-02**: Typing indicator shown in Telegram while Claude is processing
+- [ ] **MSG-03**: Brief tool-call progress notifications sent to Telegram (e.g. "Reading file...")
+- [ ] **MSG-04**: Files/photos attached in Telegram saved to session folder and available to Claude
+
+### Session Management
+
+- [ ] **SESS-01**: Path-based sessions stored in `~/telegram/sessions/<name>/` with own Claude Code history
+- [ ] **SESS-02**: `/session <name>` command switches active session
+- [ ] **SESS-03**: `/sessions` command lists all sessions sorted by last activity
+- [ ] **SESS-04**: `/new <name>` creates new session; first-ever message auto-creates default session
+
+### Lifecycle
+
+- [ ] **LIFE-01**: Configurable idle timeout suspends Claude Code session after inactivity
+- [ ] **LIFE-02**: Suspended sessions resume with full conversation history via `claude --resume`
+- [ ] **LIFE-03**: Graceful process cleanup on bot stop/restart (no zombie processes)
+- [ ] **LIFE-04**: `/timeout <minutes>` command changes idle timeout from Telegram
+
+### Output Modes
+
+- [ ] **OUT-01**: Default mode: final answer + brief tool-call progress notifications
+- [ ] **OUT-02**: `/verbose` mode: stream full Claude Code output across multiple messages
+- [ ] **OUT-03**: `/smart` mode: smart truncation with long outputs sent as file attachments
+
+### Infrastructure
+
+- [ ] **INFRA-01**: Runs as systemd user service alongside existing bot
+- [ ] **INFRA-02**: Async subprocess management via asyncio (no PIPE deadlocks)
+- [ ] **INFRA-03**: Concurrent stdout/stderr draining prevents buffer overflow
+
+## v2 Requirements
+
+### Cost Optimization
+
+- **COST-01**: Haiku-based polling loop monitors for new messages, only spawns Opus for conversation
+- **COST-02**: Route simple commands (/status, /pbs) to Haiku instead of Opus
+- **COST-03**: Token usage tracking and reporting per session
+
+### Advanced Features
+
+- **ADV-01**: Session export (conversation history as markdown file)
+- **ADV-02**: Session archiving (compress and move inactive sessions)
+- **ADV-03**: Proactive notifications (Claude alerts about homelab events)
+
+## Out of Scope
+
+| Feature | Reason |
+|---------|--------|
+| Multi-user support | Personal use only, single admin |
+| Web UI | Telegram is the interface |
+| Rate limiting / abuse prevention | Trusted single user |
+| Voice messages | High complexity, text is sufficient |
+| Inline bot mode | Adds complexity, no benefit for single user |
+| Real-time character streaming | Telegram API not designed for it, causes rate limit issues |
+
+## Traceability
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| MSG-01 | - | Pending |
+| MSG-02 | - | Pending |
+| MSG-03 | - | Pending |
+| MSG-04 | - | Pending |
+| SESS-01 | - | Pending |
+| SESS-02 | - | Pending |
+| SESS-03 | - | Pending |
+| SESS-04 | - | Pending |
+| LIFE-01 | - | Pending |
+| LIFE-02 | - | Pending |
+| LIFE-03 | - | Pending |
+| LIFE-04 | - | Pending |
+| OUT-01 | - | Pending |
+| OUT-02 | - | Pending |
+| OUT-03 | - | Pending |
+| INFRA-01 | - | Pending |
+| INFRA-02 | - | Pending |
+| INFRA-03 | - | Pending |
+
+**Coverage:**
+- v1 requirements: 18 total
+- Mapped to phases: 0
+- Unmapped: 18
+
+---
+*Requirements defined: 2026-02-04*
+*Last updated: 2026-02-04 after initial definition*