opencode-boilerplate/docs/ideas/initial-requirements.md

# TaskCLI - Idea Notes

## Positioning of This Document

This document is the output of brainstorming and ideation; it is not a formal specification.

## Product Vision

A CLI tool that lets developers manage tasks without leaving the terminal. We want to integrate tightly with Git and GitHub, naturally connecting writing code with managing tasks.

**In a nutshell**: A task management tool integrated with Git

---

## Problems to Solve

### Current Pain Points

1. **Too much screen switching**
   - Write code in the terminal -> open Trello in the browser -> go back to the terminal again
   - Every switch breaks your concentration
   - You do this more than 20 times a day

2. **Tasks and code are disconnected**
   - You lose track of which branch you're working on for which task
   - You forget to write the task number in Git commit messages
   - The link between completed tasks and the PRs that were actually merged is ambiguous

3. **Too much manual work**
   - Complete a task -> manually update the status -> manually create a PR -> manually close the task
   - It seems automatable, but GUI tools don't integrate well

4. **The team's status is hard to see**
   - You want to know who is doing what right now, but you can't tell without opening a GUI
   - You can't quickly show a task list during pair programming

---

## Target Users

### Persona 1: Individual Developer

- **Age**: 25-35
- **Occupation**: Freelance engineer, someone building products on their own
- **Experience**: 5+ years of development, comfortable with CLI operations
- **Current pain points**:
  - Working on multiple projects in parallel, with tasks managed only in their head
  - Often thinks, "Wait, what was I supposed to do next on this project?"
  - Uses GitHub Issues, but it isn't integrated with local work

- **What they want**:
  - Task management that's completed entirely in the terminal
  - Automatic integration with Git branches
  - Simple and fast

### Persona 2: Small-Team Leader

- **Age**: 30-40
- **Occupation**: Startup lead engineer, tech lead
- **Team size**: 2-5 people
- **Experience**: 10+ years of development, with team management experience
- **Current pain points**:
  - Wants to know in real time what team members are working on right now
  - Checking tasks at the morning standup takes too long
  - Jira and Asana are too heavy, overkill for a small team

- **What they want**:
  - Quickly check the whole team's task status from the CLI
  - Task progress updated automatically via GitHub integration
  - Lightweight and easy to introduce

---

## Candidate Key Features

### P0 (Absolutely Required for MVP)

#### 1. Basic Task Operations
```bash
task add "Implement user authentication feature"
task list
task show 1
task done 1
task delete 1
```

#### 2. Automatic Linking of Tasks and Git Branches
```bash
task start 1
# Automatically creates and switches to the feature/task-1-user-authentication branch

git commit -m "Add login endpoint"
# Information about Task #1 is automatically appended to the commit message
```

#### 3. Task Status Management
- `open` (new)
- `in_progress` (in progress)
- `completed` (completed)
- `archived` (archived)

#### 4. Simple Task List Display
```bash
task list

ID  Status       Title                      Branch
1   in_progress  Implement user auth         feature/task-1-user-authentication
2   open         Data export feature         -
3   completed    Initial setup               feature/task-3-initial-setup
```

### P1 (Important but Can Wait)

#### 5. Integration with GitHub Issues
```bash
task sync
# Sync local tasks with GitHub Issues

task import --github
# Import tasks from GitHub Issues
```

#### 6. Automatic Processing on Task Completion
```bash
task done 1
# Automatically does the following:
# 1. Merge the branch into main
# 2. Push to remote
# 3. (Optional) Automatically create a GitHub PR
# 4. Change the task status to completed
```

#### 7. Task Filtering and Search
```bash
task list --status in_progress
task list --assignee me
task search "authentication"
```

#### 8. Priority and Due Date Management
```bash
task add "Urgent bug fix" --priority high --due 2025-01-20
task list --sort priority
```

### P2 (Nice to Have)

#### 9. Team Features
```bash
task list --team
# Task list for all team members

task assign 1 @alice
# Assign a task to another member
```

#### 10. Calendar Display
```bash
task calendar --week
task calendar --month
```

#### 11. Time Tracking
```bash
task start 1
# Start measuring work time

task done 1
# Record work time: 2 hours 30 minutes
```

#### 12. Task Templates
```bash
task template create bug-fix
task add --template bug-fix "Fix login screen bug"
```

---

## Differentiators

### Comparison with Existing Tools

| Feature | TaskCLI | Todoist | Trello | GitHub Issues | Linear |
|------|---------|---------|--------|---------------|--------|
| CLI operation | ✅ | ❌ | ❌ | Partial | ❌ |
| Git integration | ✅✅✅ | ❌ | ❌ | ✅ | ✅ |
| Automatic branch creation | ✅ | ❌ | ❌ | ❌ | ✅ |
| Completed in the terminal | ✅ | ❌ | ❌ | ❌ | ❌ |
| Lightweight and fast | ✅ | ✅ | △ | ✅ | △ |
| Team features | 🚧 | ✅ | ✅ | ✅ | ✅ |

### This Tool's Strengths

1. **No need to switch screens**
   - Write code -> check tasks -> back to code
   - Everything is completed in the terminal; no GUI needed

2. **A sense of unity with Git**
   - Tasks and branches are linked one-to-one
   - Commits, merges, and PRs are automatically linked with tasks
   - Always clear which task you're working on

3. **Blends into the development flow**
   - Start task -> create branch -> commit -> PR -> merge -> complete task
   - Automates and supports this entire flow

4. **Simple**
   - No need for complex features like Jira or Asana
   - Only the features developers truly need
   - You can start using it in one minute

---

## Technical Considerations

### Data Storage Method

**Option 1: Local file (JSON)**
- Simple, no special software required
- Stored in `.task/tasks.json`
- Can be managed with Git (shareable within a team)

**Option 2: SQLite**
- Fast search and filtering
- Can handle relational data
- File-based, easy to introduce

**Conclusion**: JSON for the MVP, migrate to SQLite when needed

### Method of Git Integration

- Use Node.js's `simple-git` library
- Automate branch creation, switching, and retrieving commit information

### Integration with the GitHub API

- Use GitHub REST API v3
- Authenticate with a Personal Access Token
- Retrieve, create, and update Issues

### CLI Framework

**Candidates**:
- Commander.js (popular, simple)
- oclif (made by Salesforce, feature-rich)
- yargs (flexible)

**Conclusion**: Commander.js (low learning cost, sufficient features)

---

## Non-Functional Requirements (For Now)

### Performance
- Command execution: within 100ms (feels instantly responsive)
- Task list display: within 1 second even for 1,000 items

### Usability
- Even first-time users can learn the basic operations in 5 minutes
- All features can be checked with the help command
- Error messages are easy to understand

### Reliability
- Data is never lost (automatic backup)
- Can be reverted if an error occurs
- Confirmation is required for dangerous operations

### Extensibility
- Plugin system (in the future)
- Can define custom commands
- Can integrate with other tools (Slack, Discord, etc.)

---

## Success Metrics (For Now)

### User Perspective
- **Adoption rate**: Introduce to 10 developers, and 3 or more keep using it for a week
- **Satisfaction**: Net Promoter Score (NPS) of 30 or above
- **Time savings**: Time spent on task management is cut in half

### Product Perspective
- **Active users**: 100 within 3 months of release
- **GitHub Stars**: 500 within 6 months of release
- **Retention rate**: 60% or more still using it after 1 month

---

## Future Considerations

### Things Not Yet Decided

1. **How far to take team features**
   - How many team-oriented features should we include?
   - The balance between individual developers and team development

2. **The money question (in the future)**
   - Completely free and open source?
   - Make the Pro version (team features) paid?

3. **Cloud sync**
   - Is sync via Git enough?
   - Should we provide a dedicated cloud service?

4. **Other version control systems**
   - Should we also support GitLab and Bitbucket?
   - What's the priority?

### Technical Concerns

1. **Environments without a Git repository**
   - How do we handle this? Throw an error? Limit functionality?

2. **Performance with large repositories**
   - What happens when tasks exceed 10,000?

3. **Cross-platform support**
   - Does it work on Windows, macOS, and Linux?
   - Does it work properly in Git Bash?

---

## Next Steps

1. **Review this document**
   - Are there any missing perspectives?
   - Are the priorities reasonable?

2. **Create the PRD (Product Requirements Document)**
   - Create the formal document with the `/setup-project` command
   - Based on these idea notes, make it more detailed and concrete

3. **Build a prototype**
   - A minimal prototype with only the MVP features (P0)
   - Actually use it and gather feedback