initial commit

2026-06-13 07:24:13 +02:00
commit 99a10def2a
47 changed files with 11330 additions and 0 deletions
--- a/docs/ideas/initial-requirements.md
+++ b/docs/ideas/initial-requirements.md
@ -0,0 +1,336 @@
+# 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