Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/env.js
Original file line number Diff line number Diff line change
Expand Up @@ -66,4 +66,4 @@ export const env = createEnv({
* `SOME_VAR=''` will throw an error.
*/
emptyStringAsUndefined: true,
});
});
326 changes: 326 additions & 0 deletions tasks/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,326 @@
# Tasks Directory

## Why Tasks Are in the Repository

This `tasks/` directory contains project tasks and requirements documentation that lives alongside the codebase for optimal integration with modern coding IDEs like **Cursor**, **VS Code**, and other AI-powered development environments.

### Key Benefits of Co-located Tasks

#### 1. **IDE Integration & Context Awareness**
- **AI Code Assistants**: Tools like Cursor can read and understand task requirements directly from the repository
- **Contextual Help**: AI assistants can reference specific task requirements while suggesting code implementations
- **Real-time Guidance**: Developers get task-aware code suggestions and can ask questions about requirements without leaving their IDE

#### 2. **Seamless Development Workflow**
- **No Context Switching**: Developers don't need to switch between external project management tools and their code editor
- **Version Control Integration**: Task updates are tracked alongside code changes, maintaining project history
- **Branch Alignment**: Tasks can be updated in feature branches, keeping documentation in sync with development

#### 3. **Enhanced Collaboration**
- **Single Source of Truth**: All project information lives in one repository
- **Code-Requirement Traceability**: Easy to link specific code changes to task requirements
- **Onboarding Efficiency**: New team members can understand both code and requirements from the same location

#### 4. **AI-Powered Development**
- **Task-Driven Coding**: AI assistants can read task requirements and generate code that directly addresses the documented needs
- **Requirement Validation**: AI can check if implemented code meets the documented requirements
- **Automated Documentation**: AI can help keep task documentation updated as code evolves

### Directory Structure

```
tasks/
├── README.md # This file - explains the tasks directory
├── Task_template.md # Template for creating new tasks
├── env.js # Environment configuration for tasks
└── wishlist/ # Future tasks and feature requests
├── Task_01_XYZ.md # Task example
```

### How to Use Tasks with Your IDE

#### For Cursor Users
1. **Open tasks alongside code**: Use split-screen to keep task requirements visible while coding
2. **Ask AI about tasks**: "Based on Task_01_Integration.md, how should I implement the authentication flow?"
3. **Reference requirements**: AI can read task files and provide context-aware suggestions

#### For VS Code Users
1. **Install markdown extensions**: Use "Markdown Preview Enhanced" for better task viewing
2. **Use TODO extensions**: Track requirements as TODOs in your code
3. **Workspace setup**: Configure workspace with tasks and code side-by-side

#### For Other IDEs
- **JetBrains**: Use built-in markdown preview and TODO tracking
- **Vim/Neovim**: Use markdown preview plugins and split windows
- **Any IDE**: Keep task files open in tabs or side panels while coding

### Task Template Usage

The `Task_template.md` provides a comprehensive structure for documenting:
- **Requirements**: Functional and non-functional requirements
- **Technical Specifications**: API specs, database schema, integration points
- **Implementation Plan**: Development phases and dependencies
- **Testing Strategy**: Test cases and acceptance criteria
- **Code Analysis**: Key issues and implementation details

### Best Practices

1. **Keep Tasks Updated**: Update task documentation as requirements evolve
2. **Link Code to Tasks**: Use commit messages and code comments that reference task sections
3. **Version Control**: Commit task updates alongside related code changes
4. **AI Integration**: Leverage AI assistants to help implement task requirements
5. **Regular Reviews**: Review and update tasks during development sprints

### Integration with Development Tools

- **Git**: Link task sections to specific commits and pull requests
- **Project Management**: Create tickets based on task sections
- **Code Reviews**: Reference task requirements in review comments
- **Documentation**: Keep tasks as living documents that evolve with the project

This approach ensures that project requirements, technical specifications, and implementation details remain tightly coupled with the codebase, enabling more efficient and context-aware development workflows.

## How to Use the Tasks Directory

### Getting Started

#### 1. **Understanding the Structure**
- **`Task_template.md`**: Use this as a starting point for new tasks
- **`wishlist/`**: Contains future tasks and feature requests

#### 2. **Creating a New Task**
1. Copy `Task_template.md` to create a new task file
2. Name it descriptively: `Task_XX_FeatureName.md`
3. Fill in all relevant sections based on the template
4. Update the directory structure in this README if needed

#### 3. **Working with Existing Tasks**
1. **Read the task thoroughly** before starting development
2. **Open the task file** alongside your code editor
3. **Reference specific requirements** while implementing features
4. **Update task status** as you progress through implementation

### Development Workflow

#### Phase 1: Task Analysis
```bash
# 1. Read the task requirements
cat tasks/wishlist/Task_XX_FeatureName.md

# 2. Understand the scope and requirements
# 3. Identify key files and components to modify
# 4. Plan your implementation approach
```

#### Phase 2: Implementation
```bash
# 1. Create a feature branch
git checkout -b feature/task-xx-feature-name

# 2. Keep the task file open while coding
# 3. Reference requirements in your code comments
# 4. Implement features according to the task specifications
```

#### Phase 3: Validation
```bash
# 1. Check that your implementation meets all requirements
# 2. Update task documentation with implementation notes
# 3. Test against acceptance criteria
# 4. Commit with task-referenced messages
```

### IDE-Specific Usage

#### Cursor IDE
```bash
# 1. Open task file in split view
# 2. Ask AI: "Based on Task_XX_FeatureName.md, how should I implement [specific requirement]?"
# 3. Use AI to generate code that addresses task requirements
# 4. Reference task sections in your prompts
```

**Example Cursor Prompts:**
- "Based on FR-1 in Task_01_Integration.md, generate the authentication service"
- "How should I implement the database schema described in Task_02_UserPage.md?"
- "Check if my implementation meets the requirements in section 3 of the task"

#### VS Code
```bash
# 1. Install extensions:
# - Markdown Preview Enhanced
# - TODO Tree
# - GitLens (for linking commits to tasks)

# 2. Set up workspace with tasks and code side-by-side
# 3. Use TODO comments referencing task requirements
```

**Example VS Code Setup:**
```json
// .vscode/settings.json
{
"markdown.preview.breaks": true,
"todo-tree.general.tags": ["FR-", "NFR-", "TC-"],
"files.associations": {
"Task_*.md": "markdown"
}
}
```

#### JetBrains IDEs
```bash
# 1. Use built-in markdown preview
# 2. Set up TODO patterns for task requirements
# 3. Use the TODO tool window to track progress
# 4. Link commits to task sections
```

### Task Management Best Practices

#### 1. **Task Lifecycle**
```
[Planning] → [In Progress] → [Review] → [Complete]
↓ ↓ ↓ ↓
Create Update Validate Archive
Task Progress Against Task
Notes Criteria Notes
```

#### 2. **Progress Tracking**
```markdown
# In your task file, update status like this:
## Implementation Status
- [x] FR-1: User authentication (COMPLETED - 2024-01-15)
- [ ] FR-2: API integration (IN PROGRESS - 2024-01-16)
- [ ] FR-3: Frontend implementation (PENDING)
```

#### 3. **Code Integration**
```typescript
/**
* Implements FR-1: User Authentication
* Task: Task_01_Integration.md
* Requirements: Functional Requirements section
* Status: COMPLETED
*/
export class AuthService {
// Implementation here
}
```

#### 4. **Commit Messages**
```bash
# Reference task sections in commits
git commit -m "feat: implement user authentication (Task_01_Integration.md - FR-1)"
git commit -m "fix: resolve API integration issue (Task_01_Integration.md - Technical Specs)"
git commit -m "test: add test cases for user journey (Task_01_Integration.md - TC-1)"
```

### Collaboration Guidelines

#### 1. **Team Workflow**
- **Assign tasks** to team members with clear ownership
- **Review tasks** before starting implementation
- **Update progress** regularly in task files
- **Link pull requests** to specific task requirements

#### 2. **Code Reviews**
```markdown
# In PR descriptions, reference tasks:
## Changes Made
- Implements FR-1: User authentication (Task_01_Integration.md)
- Addresses NFR-2: Performance requirements (Task_01_Integration.md)
- Includes tests for TC-1, TC-2 (Task_01_Integration.md)

## Testing
- [x] Unit tests for authentication service
- [x] Integration tests for API endpoints
- [x] Manual testing of user flows
```

#### 3. **Documentation Updates**
- **Keep tasks current** as requirements evolve
- **Add implementation notes** to task files
- **Document architectural decisions** made during development
- **Update acceptance criteria** based on new insights

### Troubleshooting

#### Common Issues

**Q: How do I handle changing requirements?**
A: Update the task file with the new requirements and document the changes. Use version control to track requirement evolution.

**Q: What if a task is too large?**
A: Break it down into smaller, more manageable tasks. Create sub-tasks or split into multiple task files.

**Q: How do I link code to specific requirements?**
A: Use code comments, commit messages, and PR descriptions that reference task sections (e.g., "FR-1", "TC-2").

**Q: Can I use external project management tools too?**
A: Yes, but keep the tasks directory as the source of truth for technical requirements. Sync with external tools as needed.

### Advanced Usage

#### 1. **Automated Task Validation**
```bash
# Create scripts to validate implementation against tasks
# Example: Check if all FR-* requirements are implemented
grep -r "FR-" tasks/ | while read line; do
echo "Checking requirement: $line"
# Add validation logic here
done
```

#### 2. **Task Templates for Different Types**
- **Feature Tasks**: Use full template for new features
- **Bug Fix Tasks**: Simplified template focusing on problem/solution
- **Refactoring Tasks**: Template emphasizing code quality and architecture

#### 3. **Integration with CI/CD**
```yaml
# Example GitHub Actions workflow
- name: Validate Task Requirements
run: |
# Check if implemented features match task requirements
# Validate that all FR-* items are addressed
# Ensure tests cover TC-* items
```

This comprehensive usage guide ensures that developers can effectively leverage the co-located tasks directory for improved development workflows and better integration with AI-powered coding assistants.

---

## ⚠️ Important Notice: Process Refinement

**All processes, workflows, and guidelines described in this README are open for refinement and continuous improvement.**

### We Encourage Modifications

- **Experiment with workflows**: Try different approaches and adapt them to your team's needs
- **Suggest improvements**: If you find better ways to organize or use the tasks directory, share them
- **Customize templates**: Modify the task template to better fit your project's requirements
- **Evolve the structure**: The directory structure can be adapted as your project grows

### How to Contribute Improvements

1. **Document your changes**: When you modify processes, update this README
2. **Share with the team**: Discuss improvements with your team members
3. **Version your changes**: Use git to track process evolution
4. **Test new approaches**: Validate improvements before making them standard

### Continuous Improvement

This tasks directory and its associated processes should evolve with your project. What works for a small team might need adjustment for a larger organization. What works for one type of project might need modification for another.

**Remember**: The goal is to improve development efficiency and code quality. If a process isn't serving that goal, it should be changed.

### Feedback and Iteration

- **Regular reviews**: Schedule periodic reviews of your task management processes
- **Team retrospectives**: Include process improvement in your team retrospectives
- **Document lessons learned**: Keep track of what works and what doesn't
- **Share best practices**: Contribute improvements back to the project

The processes outlined here are starting points, not rigid rules. Adapt them to create the most effective workflow for your specific context and team.
Loading