Skip to content

Commit f31191b

Browse files
QSchlegelQSchlegel
authored
Merge pull request #137 from MeshJS/feature/user-page
add Task readme and PRD for Userpage
2 parents 2bcdcdc + 7dd3ff8 commit f31191b

File tree

3 files changed

+566
-1
lines changed

3 files changed

+566
-1
lines changed

‎src/env.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,4 +66,4 @@ export const env = createEnv({
6666
* `SOME_VAR=''` will throw an error.
6767
*/
6868
emptyStringAsUndefined: true,
69-
});
69+
});

‎tasks/README.md‎

Lines changed: 326 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,326 @@
1+
# Tasks Directory
2+
3+
## Why Tasks Are in the Repository
4+
5+
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.
6+
7+
### Key Benefits of Co-located Tasks
8+
9+
#### 1. **IDE Integration & Context Awareness**
10+
- **AI Code Assistants**: Tools like Cursor can read and understand task requirements directly from the repository
11+
- **Contextual Help**: AI assistants can reference specific task requirements while suggesting code implementations
12+
- **Real-time Guidance**: Developers get task-aware code suggestions and can ask questions about requirements without leaving their IDE
13+
14+
#### 2. **Seamless Development Workflow**
15+
- **No Context Switching**: Developers don't need to switch between external project management tools and their code editor
16+
- **Version Control Integration**: Task updates are tracked alongside code changes, maintaining project history
17+
- **Branch Alignment**: Tasks can be updated in feature branches, keeping documentation in sync with development
18+
19+
#### 3. **Enhanced Collaboration**
20+
- **Single Source of Truth**: All project information lives in one repository
21+
- **Code-Requirement Traceability**: Easy to link specific code changes to task requirements
22+
- **Onboarding Efficiency**: New team members can understand both code and requirements from the same location
23+
24+
#### 4. **AI-Powered Development**
25+
- **Task-Driven Coding**: AI assistants can read task requirements and generate code that directly addresses the documented needs
26+
- **Requirement Validation**: AI can check if implemented code meets the documented requirements
27+
- **Automated Documentation**: AI can help keep task documentation updated as code evolves
28+
29+
### Directory Structure
30+
31+
```
32+
tasks/
33+
├── README.md # This file - explains the tasks directory
34+
├── Task_template.md # Template for creating new tasks
35+
├── env.js # Environment configuration for tasks
36+
└── wishlist/ # Future tasks and feature requests
37+
├── Task_01_XYZ.md # Task example
38+
```
39+
40+
### How to Use Tasks with Your IDE
41+
42+
#### For Cursor Users
43+
1. **Open tasks alongside code**: Use split-screen to keep task requirements visible while coding
44+
2. **Ask AI about tasks**: "Based on Task_01_Integration.md, how should I implement the authentication flow?"
45+
3. **Reference requirements**: AI can read task files and provide context-aware suggestions
46+
47+
#### For VS Code Users
48+
1. **Install markdown extensions**: Use "Markdown Preview Enhanced" for better task viewing
49+
2. **Use TODO extensions**: Track requirements as TODOs in your code
50+
3. **Workspace setup**: Configure workspace with tasks and code side-by-side
51+
52+
#### For Other IDEs
53+
- **JetBrains**: Use built-in markdown preview and TODO tracking
54+
- **Vim/Neovim**: Use markdown preview plugins and split windows
55+
- **Any IDE**: Keep task files open in tabs or side panels while coding
56+
57+
### Task Template Usage
58+
59+
The `Task_template.md` provides a comprehensive structure for documenting:
60+
- **Requirements**: Functional and non-functional requirements
61+
- **Technical Specifications**: API specs, database schema, integration points
62+
- **Implementation Plan**: Development phases and dependencies
63+
- **Testing Strategy**: Test cases and acceptance criteria
64+
- **Code Analysis**: Key issues and implementation details
65+
66+
### Best Practices
67+
68+
1. **Keep Tasks Updated**: Update task documentation as requirements evolve
69+
2. **Link Code to Tasks**: Use commit messages and code comments that reference task sections
70+
3. **Version Control**: Commit task updates alongside related code changes
71+
4. **AI Integration**: Leverage AI assistants to help implement task requirements
72+
5. **Regular Reviews**: Review and update tasks during development sprints
73+
74+
### Integration with Development Tools
75+
76+
- **Git**: Link task sections to specific commits and pull requests
77+
- **Project Management**: Create tickets based on task sections
78+
- **Code Reviews**: Reference task requirements in review comments
79+
- **Documentation**: Keep tasks as living documents that evolve with the project
80+
81+
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.
82+
83+
## How to Use the Tasks Directory
84+
85+
### Getting Started
86+
87+
#### 1. **Understanding the Structure**
88+
- **`Task_template.md`**: Use this as a starting point for new tasks
89+
- **`wishlist/`**: Contains future tasks and feature requests
90+
91+
#### 2. **Creating a New Task**
92+
1. Copy `Task_template.md` to create a new task file
93+
2. Name it descriptively: `Task_XX_FeatureName.md`
94+
3. Fill in all relevant sections based on the template
95+
4. Update the directory structure in this README if needed
96+
97+
#### 3. **Working with Existing Tasks**
98+
1. **Read the task thoroughly** before starting development
99+
2. **Open the task file** alongside your code editor
100+
3. **Reference specific requirements** while implementing features
101+
4. **Update task status** as you progress through implementation
102+
103+
### Development Workflow
104+
105+
#### Phase 1: Task Analysis
106+
```bash
107+
# 1. Read the task requirements
108+
cat tasks/wishlist/Task_XX_FeatureName.md
109+
110+
# 2. Understand the scope and requirements
111+
# 3. Identify key files and components to modify
112+
# 4. Plan your implementation approach
113+
```
114+
115+
#### Phase 2: Implementation
116+
```bash
117+
# 1. Create a feature branch
118+
git checkout -b feature/task-xx-feature-name
119+
120+
# 2. Keep the task file open while coding
121+
# 3. Reference requirements in your code comments
122+
# 4. Implement features according to the task specifications
123+
```
124+
125+
#### Phase 3: Validation
126+
```bash
127+
# 1. Check that your implementation meets all requirements
128+
# 2. Update task documentation with implementation notes
129+
# 3. Test against acceptance criteria
130+
# 4. Commit with task-referenced messages
131+
```
132+
133+
### IDE-Specific Usage
134+
135+
#### Cursor IDE
136+
```bash
137+
# 1. Open task file in split view
138+
# 2. Ask AI: "Based on Task_XX_FeatureName.md, how should I implement [specific requirement]?"
139+
# 3. Use AI to generate code that addresses task requirements
140+
# 4. Reference task sections in your prompts
141+
```
142+
143+
**Example Cursor Prompts:**
144+
- "Based on FR-1 in Task_01_Integration.md, generate the authentication service"
145+
- "How should I implement the database schema described in Task_02_UserPage.md?"
146+
- "Check if my implementation meets the requirements in section 3 of the task"
147+
148+
#### VS Code
149+
```bash
150+
# 1. Install extensions:
151+
# - Markdown Preview Enhanced
152+
# - TODO Tree
153+
# - GitLens (for linking commits to tasks)
154+
155+
# 2. Set up workspace with tasks and code side-by-side
156+
# 3. Use TODO comments referencing task requirements
157+
```
158+
159+
**Example VS Code Setup:**
160+
```json
161+
// .vscode/settings.json
162+
{
163+
"markdown.preview.breaks": true,
164+
"todo-tree.general.tags": ["FR-", "NFR-", "TC-"],
165+
"files.associations": {
166+
"Task_*.md": "markdown"
167+
}
168+
}
169+
```
170+
171+
#### JetBrains IDEs
172+
```bash
173+
# 1. Use built-in markdown preview
174+
# 2. Set up TODO patterns for task requirements
175+
# 3. Use the TODO tool window to track progress
176+
# 4. Link commits to task sections
177+
```
178+
179+
### Task Management Best Practices
180+
181+
#### 1. **Task Lifecycle**
182+
```
183+
[Planning] → [In Progress] → [Review] → [Complete]
184+
↓ ↓ ↓ ↓
185+
Create Update Validate Archive
186+
Task Progress Against Task
187+
Notes Criteria Notes
188+
```
189+
190+
#### 2. **Progress Tracking**
191+
```markdown
192+
# In your task file, update status like this:
193+
## Implementation Status
194+
- [x] FR-1: User authentication (COMPLETED - 2024-01-15)
195+
- [ ] FR-2: API integration (IN PROGRESS - 2024-01-16)
196+
- [ ] FR-3: Frontend implementation (PENDING)
197+
```
198+
199+
#### 3. **Code Integration**
200+
```typescript
201+
/**
202+
* Implements FR-1: User Authentication
203+
* Task: Task_01_Integration.md
204+
* Requirements: Functional Requirements section
205+
* Status: COMPLETED
206+
*/
207+
export class AuthService {
208+
// Implementation here
209+
}
210+
```
211+
212+
#### 4. **Commit Messages**
213+
```bash
214+
# Reference task sections in commits
215+
git commit -m "feat: implement user authentication (Task_01_Integration.md - FR-1)"
216+
git commit -m "fix: resolve API integration issue (Task_01_Integration.md - Technical Specs)"
217+
git commit -m "test: add test cases for user journey (Task_01_Integration.md - TC-1)"
218+
```
219+
220+
### Collaboration Guidelines
221+
222+
#### 1. **Team Workflow**
223+
- **Assign tasks** to team members with clear ownership
224+
- **Review tasks** before starting implementation
225+
- **Update progress** regularly in task files
226+
- **Link pull requests** to specific task requirements
227+
228+
#### 2. **Code Reviews**
229+
```markdown
230+
# In PR descriptions, reference tasks:
231+
## Changes Made
232+
- Implements FR-1: User authentication (Task_01_Integration.md)
233+
- Addresses NFR-2: Performance requirements (Task_01_Integration.md)
234+
- Includes tests for TC-1, TC-2 (Task_01_Integration.md)
235+
236+
## Testing
237+
- [x] Unit tests for authentication service
238+
- [x] Integration tests for API endpoints
239+
- [x] Manual testing of user flows
240+
```
241+
242+
#### 3. **Documentation Updates**
243+
- **Keep tasks current** as requirements evolve
244+
- **Add implementation notes** to task files
245+
- **Document architectural decisions** made during development
246+
- **Update acceptance criteria** based on new insights
247+
248+
### Troubleshooting
249+
250+
#### Common Issues
251+
252+
**Q: How do I handle changing requirements?**
253+
A: Update the task file with the new requirements and document the changes. Use version control to track requirement evolution.
254+
255+
**Q: What if a task is too large?**
256+
A: Break it down into smaller, more manageable tasks. Create sub-tasks or split into multiple task files.
257+
258+
**Q: How do I link code to specific requirements?**
259+
A: Use code comments, commit messages, and PR descriptions that reference task sections (e.g., "FR-1", "TC-2").
260+
261+
**Q: Can I use external project management tools too?**
262+
A: Yes, but keep the tasks directory as the source of truth for technical requirements. Sync with external tools as needed.
263+
264+
### Advanced Usage
265+
266+
#### 1. **Automated Task Validation**
267+
```bash
268+
# Create scripts to validate implementation against tasks
269+
# Example: Check if all FR-* requirements are implemented
270+
grep -r "FR-" tasks/ | while read line; do
271+
echo "Checking requirement: $line"
272+
# Add validation logic here
273+
done
274+
```
275+
276+
#### 2. **Task Templates for Different Types**
277+
- **Feature Tasks**: Use full template for new features
278+
- **Bug Fix Tasks**: Simplified template focusing on problem/solution
279+
- **Refactoring Tasks**: Template emphasizing code quality and architecture
280+
281+
#### 3. **Integration with CI/CD**
282+
```yaml
283+
# Example GitHub Actions workflow
284+
- name: Validate Task Requirements
285+
run: |
286+
# Check if implemented features match task requirements
287+
# Validate that all FR-* items are addressed
288+
# Ensure tests cover TC-* items
289+
```
290+
291+
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.
292+
293+
---
294+
295+
## ⚠️ Important Notice: Process Refinement
296+
297+
**All processes, workflows, and guidelines described in this README are open for refinement and continuous improvement.**
298+
299+
### We Encourage Modifications
300+
301+
- **Experiment with workflows**: Try different approaches and adapt them to your team's needs
302+
- **Suggest improvements**: If you find better ways to organize or use the tasks directory, share them
303+
- **Customize templates**: Modify the task template to better fit your project's requirements
304+
- **Evolve the structure**: The directory structure can be adapted as your project grows
305+
306+
### How to Contribute Improvements
307+
308+
1. **Document your changes**: When you modify processes, update this README
309+
2. **Share with the team**: Discuss improvements with your team members
310+
3. **Version your changes**: Use git to track process evolution
311+
4. **Test new approaches**: Validate improvements before making them standard
312+
313+
### Continuous Improvement
314+
315+
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.
316+
317+
**Remember**: The goal is to improve development efficiency and code quality. If a process isn't serving that goal, it should be changed.
318+
319+
### Feedback and Iteration
320+
321+
- **Regular reviews**: Schedule periodic reviews of your task management processes
322+
- **Team retrospectives**: Include process improvement in your team retrospectives
323+
- **Document lessons learned**: Keep track of what works and what doesn't
324+
- **Share best practices**: Contribute improvements back to the project
325+
326+
The processes outlined here are starting points, not rigid rules. Adapt them to create the most effective workflow for your specific context and team.

0 commit comments

Comments
 (0)