feat: initial commit - opencode spec-driven development boilerplate
Converted from Claude Code boilerplate to opencode: - CLAUDE.md -> AGENTS.md (opencode instructions) - .claude/settings.json -> opencode.json (permissions schema) - .claude/agents/ -> .opencode/agent/ (subagents with mode: subagent) - .claude/commands/ -> .opencode/command/ (slash commands with ) - .claude/skills/ -> .opencode/skills/ (7 skills, removed allowed-tools) - DevContainer updated to install opencode - All .claude/ paths and Claude Code references updated
This commit is contained in:
336
docs/ideas/initial-requirements.md
Normal file
336
docs/ideas/initial-requirements.md
Normal file
@ -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
|
||||
Reference in New Issue
Block a user