PRD Example 1: Todo CLI

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

---

Todo CLI

Overview

What	A command-line todo list manager that stores tasks in a local JSON file
Who	Developers who prefer terminal-based workflows
Why	Quick task capture without leaving the terminal

Features

1. Add Task: todo add "Buy groceries" → Adds task with auto-generated ID
2. List Tasks: todo list → Shows all tasks with status ([ ] or [x])
3. Complete Task: todo done 1 → Marks task #1 as complete
4. Delete Task: todo delete 1 → Removes task #1 from list

Non-Goals

Will NOT build:

• Due dates or reminders
• Priority levels or tags
• Multiple todo lists
• Cloud sync or backup
• Undo functionality

Will NOT use:

• Databases (SQLite, PostgreSQL, etc.)
• External APIs
• Rich terminal UI libraries (rich, textual)

Technical Constraints

Language	Python 3.11+
Framework	None (stdlib only)
Dependencies	argparse, json, pathlib (all stdlib)
Testing	pytest, minimum 4 test cases

Data Storage:

{
  "tasks": [
    {"id": 1, "text": "Buy groceries", "done": false},
    {"id": 2, "text": "Call mom", "done": true}
  ]
}

File location: ~/.todo.json

Phases

Phase 1: Add and List

Tasks: Create todo.py with add and list commands. Store in JSON file. Verify:

python todo.py add "Test task"
python todo.py list
# Output: [ ] 1. Test task

Phase 2: Complete and Delete

Tasks: Add done and delete commands. Handle invalid IDs gracefully. Verify:

python todo.py done 1
python todo.py list
# Output: [x] 1. Test task

Phase 3: Tests

Tasks: Create test_todo.py with tests for add, list, done, delete. Verify: pytest test_todo.py -v → All tests pass

Agent Rules

Always	Ask First	Never
Handle missing file gracefully	Before changing JSON schema	Use external packages
Validate task IDs exist	Before adding new commands	Store data outside ~/.todo.json
Show helpful error messages		Add features not in this PRD