docs: create roadmap (4 phases)
Phases: 1. Session & Process Foundation: SESS-01, SESS-02, SESS-04, INFRA-02, INFRA-03 2. Telegram Integration: MSG-01, MSG-02, MSG-03, MSG-04, OUT-01, INFRA-01 3. Lifecycle Management: LIFE-01, LIFE-02, LIFE-03, LIFE-04, SESS-03 4. Output Modes: OUT-02, OUT-03 All 18 v1 requirements mapped to phases.
This commit is contained in:
parent
0edb076981
commit
6cf6bfb8d1
3 changed files with 182 additions and 21 deletions
|
|
@ -67,30 +67,32 @@
|
|||
|
||||
| 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 |
|
||||
| MSG-01 | Phase 2 | Pending |
|
||||
| MSG-02 | Phase 2 | Pending |
|
||||
| MSG-03 | Phase 2 | Pending |
|
||||
| MSG-04 | Phase 2 | Pending |
|
||||
| SESS-01 | Phase 1 | Pending |
|
||||
| SESS-02 | Phase 1 | Pending |
|
||||
| SESS-03 | Phase 3 | Pending |
|
||||
| SESS-04 | Phase 1 | Pending |
|
||||
| LIFE-01 | Phase 3 | Pending |
|
||||
| LIFE-02 | Phase 3 | Pending |
|
||||
| LIFE-03 | Phase 3 | Pending |
|
||||
| LIFE-04 | Phase 3 | Pending |
|
||||
| OUT-01 | Phase 2 | Pending |
|
||||
| OUT-02 | Phase 4 | Pending |
|
||||
| OUT-03 | Phase 4 | Pending |
|
||||
| INFRA-01 | Phase 2 | Pending |
|
||||
| INFRA-02 | Phase 1 | Pending |
|
||||
| INFRA-03 | Phase 1 | Pending |
|
||||
|
||||
**Coverage:**
|
||||
- v1 requirements: 18 total
|
||||
- Mapped to phases: 0
|
||||
- Unmapped: 18
|
||||
- Mapped to phases: 18
|
||||
- Unmapped: 0
|
||||
|
||||
**Coverage validation:** All 18 v1 requirements mapped to exactly one phase. No orphans.
|
||||
|
||||
---
|
||||
*Requirements defined: 2026-02-04*
|
||||
*Last updated: 2026-02-04 after initial definition*
|
||||
*Last updated: 2026-02-04 after roadmap creation*
|
||||
|
|
|
|||
91
.planning/ROADMAP.md
Normal file
91
.planning/ROADMAP.md
Normal file
|
|
@ -0,0 +1,91 @@
|
|||
# Roadmap: Telegram Claude Code Bridge
|
||||
|
||||
## Overview
|
||||
|
||||
This project transforms Telegram into a mobile interface for Claude Code, enabling frictionless AI assistance from anywhere. The journey starts with session and subprocess foundations, integrates Telegram messaging with file handling, adds idle timeout management to conserve resources, and finishes with advanced output modes for power users.
|
||||
|
||||
## Phases
|
||||
|
||||
**Phase Numbering:**
|
||||
- Integer phases (1, 2, 3): Planned milestone work
|
||||
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
|
||||
|
||||
Decimal phases appear between their surrounding integers in numeric order.
|
||||
|
||||
- [ ] **Phase 1: Session & Process Foundation** - Multi-session filesystem structure with subprocess management
|
||||
- [ ] **Phase 2: Telegram Integration** - Core messaging loop with file handling and typing indicators
|
||||
- [ ] **Phase 3: Lifecycle Management** - Idle timeout, suspend/resume, and graceful cleanup
|
||||
- [ ] **Phase 4: Output Modes** - Advanced output control for verbose and smart modes
|
||||
|
||||
## Phase Details
|
||||
|
||||
### Phase 1: Session & Process Foundation
|
||||
**Goal**: Path-based sessions with isolated directories spawn and manage Claude Code subprocesses safely
|
||||
**Depends on**: Nothing (first phase)
|
||||
**Requirements**: SESS-01, SESS-02, SESS-04, INFRA-02, INFRA-03
|
||||
**Success Criteria** (what must be TRUE):
|
||||
1. User can create named sessions via `/new <name>` command
|
||||
2. User can switch between sessions with `/session <name>` command
|
||||
3. Each session has isolated directory at `~/telegram/sessions/<name>/` with metadata and conversation log
|
||||
4. Claude Code subprocess spawns in session directory and processes input without pipe deadlock
|
||||
5. Subprocess terminates cleanly on session switch with no zombie processes
|
||||
**Plans**: TBD
|
||||
|
||||
Plans:
|
||||
- [ ] TBD
|
||||
|
||||
### Phase 2: Telegram Integration
|
||||
**Goal**: Messages flow bidirectionally between Telegram and Claude with file support and status feedback
|
||||
**Depends on**: Phase 1
|
||||
**Requirements**: MSG-01, MSG-02, MSG-03, MSG-04, OUT-01, INFRA-01
|
||||
**Success Criteria** (what must be TRUE):
|
||||
1. User sends message in Telegram and receives Claude's response back
|
||||
2. Typing indicator appears in Telegram while Claude is processing (10-60s responses)
|
||||
3. User sees brief progress notifications for tool calls (e.g. "Reading file...")
|
||||
4. User attaches file/photo in Telegram and Claude can access it in session folder
|
||||
5. Long responses split at 4096 char Telegram limit with proper code block handling
|
||||
6. Bot runs as systemd user service and survives container restarts
|
||||
**Plans**: TBD
|
||||
|
||||
Plans:
|
||||
- [ ] TBD
|
||||
|
||||
### Phase 3: Lifecycle Management
|
||||
**Goal**: Sessions suspend automatically after idle period and resume transparently with full context
|
||||
**Depends on**: Phase 2
|
||||
**Requirements**: LIFE-01, LIFE-02, LIFE-03, LIFE-04, SESS-03
|
||||
**Success Criteria** (what must be TRUE):
|
||||
1. Session suspends automatically after configurable idle timeout (default 10 minutes)
|
||||
2. User sends message to suspended session and conversation resumes with full history
|
||||
3. User can change idle timeout via `/timeout <minutes>` command
|
||||
4. User can list all sessions with last activity timestamp via `/sessions` command
|
||||
5. Bot restart leaves no zombie processes (systemd KillMode handles cleanup)
|
||||
**Plans**: TBD
|
||||
|
||||
Plans:
|
||||
- [ ] TBD
|
||||
|
||||
### Phase 4: Output Modes
|
||||
**Goal**: Users control response verbosity and format based on context
|
||||
**Depends on**: Phase 3
|
||||
**Requirements**: OUT-02, OUT-03
|
||||
**Success Criteria** (what must be TRUE):
|
||||
1. User enables `/verbose` mode and sees full Claude Code output streamed across multiple messages
|
||||
2. User enables `/smart` mode and long outputs are sent as file attachments instead of truncation
|
||||
3. Default mode (already from Phase 2) shows final answer with brief progress notifications
|
||||
**Plans**: TBD
|
||||
|
||||
Plans:
|
||||
- [ ] TBD
|
||||
|
||||
## Progress
|
||||
|
||||
**Execution Order:**
|
||||
Phases execute in numeric order: 1 → 2 → 3 → 4
|
||||
|
||||
| Phase | Plans Complete | Status | Completed |
|
||||
|-------|----------------|--------|-----------|
|
||||
| 1. Session & Process Foundation | 0/TBD | Not started | - |
|
||||
| 2. Telegram Integration | 0/TBD | Not started | - |
|
||||
| 3. Lifecycle Management | 0/TBD | Not started | - |
|
||||
| 4. Output Modes | 0/TBD | Not started | - |
|
||||
68
.planning/STATE.md
Normal file
68
.planning/STATE.md
Normal file
|
|
@ -0,0 +1,68 @@
|
|||
# Project State
|
||||
|
||||
## Project Reference
|
||||
|
||||
See: .planning/PROJECT.md (updated 2026-02-04)
|
||||
|
||||
**Core value:** Frictionless conversation with Claude Code from anywhere via Telegram — no SSH, no manual inbox checking, just message and get a response.
|
||||
**Current focus:** Phase 1 (Session & Process Foundation)
|
||||
|
||||
## Current Position
|
||||
|
||||
Phase: 1 of 4 (Session & Process Foundation)
|
||||
Plan: - (not yet planned)
|
||||
Status: Ready to plan
|
||||
Last activity: 2026-02-04 — Roadmap created with 4 phases, 18 requirements mapped
|
||||
|
||||
Progress: [░░░░░░░░░░] 0%
|
||||
|
||||
## Performance Metrics
|
||||
|
||||
**Velocity:**
|
||||
- Total plans completed: 0
|
||||
- Average duration: - min
|
||||
- Total execution time: 0.0 hours
|
||||
|
||||
**By Phase:**
|
||||
|
||||
| Phase | Plans | Total | Avg/Plan |
|
||||
|-------|-------|-------|----------|
|
||||
| - | - | - | - |
|
||||
|
||||
**Recent Trend:**
|
||||
- Last 5 plans: None yet
|
||||
- Trend: -
|
||||
|
||||
*Updated after each plan completion*
|
||||
|
||||
## Accumulated Context
|
||||
|
||||
### Decisions
|
||||
|
||||
Decisions are logged in PROJECT.md Key Decisions table.
|
||||
Recent decisions affecting current work:
|
||||
|
||||
- Claude Code CLI over raw API: Gets full tool access, --resume support, and all Claude Code features for free
|
||||
- Haiku polling + Opus conversation: Avoids burning expensive Opus tokens on idle monitoring (deferred to v2)
|
||||
- Path-based sessions: Leverages Claude Code's native session-per-directory behavior, files naturally scoped
|
||||
- Extend existing bot: Reuse proven Telegram integration rather than building from scratch
|
||||
|
||||
### Pending Todos
|
||||
|
||||
None yet.
|
||||
|
||||
### Blockers/Concerns
|
||||
|
||||
**Phase 2 (Process Management):**
|
||||
- Claude Code CLI --resume behavior with pipes vs PTY unknown — needs empirical testing
|
||||
- Output format for tool calls not documented — requires experimentation with --output-format stream-json
|
||||
|
||||
**Phase 3 (Telegram Integration):**
|
||||
- Message batching strategy needs validation against actual Claude output patterns
|
||||
- Optimal chunk split points require experimentation
|
||||
|
||||
## Session Continuity
|
||||
|
||||
Last session: 2026-02-04
|
||||
Stopped at: Roadmap creation complete, ready for Phase 1 planning
|
||||
Resume file: None
|
||||
Loading…
Add table
Reference in a new issue