PRD Example 4: Pomodoro Timer CLI

Difficulty: Beginner | Project Type: CLI Tool | Time: 2-3 hours

---

Overview

What	A command-line Pomodoro timer that tracks work sessions and breaks
Who	Students and developers who want to manage focus time
Why	Helps maintain productivity with timed work/break cycles without leaving the terminal

---

Core Features (MVP)

1. Start Timer: pomo start → Begins a 25-minute work session with countdown display
2. Take Break: pomo break → Starts a 5-minute break timer (or 15-min after 4 sessions)
3. Show Status: pomo status → Shows current session, time remaining, and total sessions today
4. View Stats: pomo stats → Shows daily/weekly summary of completed sessions

---

Non-Goals

Will NOT build:

• GUI or desktop notifications
• Sound alerts or audio cues
• Customizable timer durations (fixed 25/5/15 pattern)
• Task names or descriptions for sessions
• Cloud sync or multi-device support
• Historical data beyond 7 days
• Integration with calendar or task apps

Will NOT use:

• External APIs
• Database (SQLite, PostgreSQL, etc.)
• Rich terminal UI libraries (blessed, rich, etc.)
• Background processes or daemons

---

Technical Constraints

Language	Python 3.11+
Framework	None (stdlib only)
Dependencies	None — stdlib only
Data Storage	JSON file at ~/.pomo/sessions.json
Testing	pytest, minimum 3 tests
Code Style	Black formatter, type hints

---

Success Criteria

• [ ] pomo start begins 25-minute countdown with live display
• [ ] pomo break correctly alternates between 5-min and 15-min breaks
• [ ] pomo status shows accurate time remaining
• [ ] pomo stats displays sessions from JSON file
• [ ] All tests pass with pytest
• [ ] No external dependencies beyond stdlib

---

Implementation Phases

Phase 1: Core Timer Logic

Goal: Implement the basic timer functionality

Tasks:

1. Create project structure with pomo.py and tests/
2. Implement countdown timer with terminal display
3. Add start command for 25-minute sessions
4. Save completed sessions to JSON file

Verification:

python pomo.py start
# Shows countdown: "25:00 remaining..."
# After completion: "Session complete! Take a break."

cat ~/.pomo/sessions.json
# Shows: {"sessions": [{"date": "2025-02-12", "completed": 1}]}

Deliverables: pomo.py, ~/.pomo/sessions.json

---

Phase 2: Break Timer & Status

Goal: Add break functionality and status display

Tasks:

1. Implement break command with 5/15-minute logic
2. Track session count to determine break length
3. Add status command showing current state
4. Handle Ctrl+C gracefully (cancel without crashing)

Verification:

python pomo.py break
# After 4 work sessions: "Long break: 15:00 remaining..."
# Otherwise: "Short break: 5:00 remaining..."

python pomo.py status
# Shows: "Session 3 of 4 | Next: Long break"

Deliverables: Updated pomo.py with break logic

---

Phase 3: Stats & Testing

Goal: Add statistics display and tests

Tasks:

1. Implement stats command with daily/weekly view
2. Add pytest tests for timer logic
3. Test JSON file read/write
4. Add error handling for missing data file

Verification:

python pomo.py stats
# Shows:
# Today: 4 sessions (1h 40m focused)
# This week: 18 sessions (7h 30m focused)

pytest
# All tests pass

Deliverables: Complete CLI with tests

---

Agent Rules

Always	Ask First	Never
Handle missing JSON file gracefully	Before changing JSON schema	Use external packages
Validate timer is not already running	Before adding new commands	Store data outside ~/.pomo/
Show helpful error messages	Before changing countdown display format	Add features not in this PRD
Use type hints for all functions		Implement background/daemon mode