claudecode-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

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

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

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

task sync
# Sync local tasks with GitHub Issues

task import --github
# Import tasks from GitHub Issues

6. Automatic Processing on Task Completion

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

task list --status in_progress
task list --assignee me
task search "authentication"

8. Priority and Due Date Management

task add "Urgent bug fix" --priority high --due 2025-01-20
task list --sort priority

P2 (Nice to Have)

9. Team Features

task list --team
# Task list for all team members

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

10. Calendar Display

task calendar --week
task calendar --month

11. Time Tracking

task start 1
# Start measuring work time

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

12. Task Templates

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