@magic-ingredients/tiny-brain-local 0.10.2 → 0.12.2

package/templates/prd/_template/prd-template.md

@@ -0,0 +1,126 @@
+---
+id: your-prd-id-here
+title: Your PRD Title Here
+version: 1.0.0
+status: not_started
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+author: Your Name or Claude Code
+---
+
+# [PRD Title]
+
+## Purpose and Goals
+
+[Describe the purpose of this PRD and the high-level goals it aims to achieve. What problem are you solving? What value will this provide?]
+
+Example:
+- Enable [capability X]
+- Provide [benefit Y]
+- Support [use case Z]
+
+## User Needs
+
+### Target Audience
+[Who are the primary users? Who will benefit from this work?]
+
+Example:
+- Software developers using [product] for [purpose]
+- Teams needing [capability]
+- Individual users tracking [activity]
+
+### User Stories
+[List user stories in the format: "As a [role], I want [action] so that [benefit]"]
+
+1. As a [role], I want to [action] so that [benefit]
+2. As a [role], I want to [action] so that [benefit]
+3. As a [role], I want to [action] so that [benefit]
+
+## Features and Functionality
+
+[List all features that make up this PRD. Each feature should have its own markdown file in the features/ subdirectory]
+
+### Feature 1: [Feature Name]
+**File**: [features/feature-name.md](features/feature-name.md)
+**Status**: planned | in_progress | complete
+**Description**: [Brief description of what this feature does]
+
+### Feature 2: [Feature Name]
+**File**: [features/feature-name.md](features/feature-name.md)
+**Status**: planned | in_progress | complete
+**Description**: [Brief description of what this feature does]
+
+[Add more features as needed]
+
+## Design and User Experience
+
+[Optional: Describe the overall design approach, user experience considerations, directory structures, or workflows]
+
+### Directory Structure
+[If applicable, show how files/folders are organized]
+
+```
+example/
+  directory/
+    structure/
+```
+
+### Workflow Visualization
+[If applicable, show the user workflow or process flow]
+
+```
+1. Step 1 → Action
+2. Step 2 → Action
+3. Step 3 → Result
+```
+
+## Release Criteria
+
+### Functional Requirements
+[List must-have functional requirements that define "done"]
+
+- [ ] Requirement 1
+- [ ] Requirement 2
+- [ ] Requirement 3
+
+### Usability Requirements
+[List user experience and usability requirements]
+
+- [ ] Requirement 1
+- [ ] Requirement 2
+- [ ] Requirement 3
+
+### Technical Requirements
+[List technical constraints and requirements]
+
+- [ ] Requirement 1
+- [ ] Requirement 2
+- [ ] Requirement 3
+
+## Success Metrics (KPIs)
+
+[Define measurable success criteria]
+
+- Metric 1: [target value]
+- Metric 2: [target value]
+- Metric 3: [target value]
+
+## Constraints and Dependencies
+
+### Technical Constraints
+[List technical limitations or constraints]
+
+- Constraint 1
+- Constraint 2
+
+### Dependencies
+[List external dependencies or prerequisites]
+
+- Dependency 1
+- Dependency 2
+
+### Known Limitations
+[List known limitations or trade-offs]
+
+- Limitation 1
+- Limitation 2

package/templates/prd/example-task-management/features/task-collaboration.md

@@ -0,0 +1,84 @@
+---
+id: task-collaboration
+prd_id: task-management-system
+title: "Task Assignment and Collaboration"
+status: planned
+created: 2025-01-15
+updated: 2025-01-15
+---
+
+# Feature: Task Assignment and Collaboration
+
+## Description
+
+Enable team collaboration on tasks through assignment, comments, mentions, and notifications. Users can assign tasks to team members, discuss implementation details in comments, mention colleagues for input, and receive real-time notifications on updates.
+
+## Acceptance Criteria
+
+- [ ] Users can assign tasks to any team member
+- [ ] Users can reassign tasks to different team members
+- [ ] Assignee receives notification when assigned
+- [ ] Users can add comments to tasks
+- [ ] Comments support @mentions to notify specific users
+- [ ] Comments support markdown formatting
+- [ ] Users can edit their own comments
+- [ ] Users can delete their own comments
+- [ ] Notifications appear in-app and via email
+- [ ] Users can subscribe/unsubscribe to task updates (watchers)
+- [ ] Comment count displayed on task list items
+
+## Tasks
+
+### 1. Implement Task Assignment Logic
+Add assignee field and assignment change tracking.
+
+**Files:** `src/api/controllers/taskController.ts`, `src/models/task.ts`
+
+### 2. Build Assignment UI
+Create assignee dropdown and assignment interface.
+
+**Files:** `src/components/TaskAssignee.tsx`, `src/hooks/useTaskAssign.ts`
+
+### 3. Implement Comments System
+Database schema and API for task comments.
+
+**Files:** `db/migrations/003_add_task_comments.sql`, `src/api/routes/comments.ts`
+
+### 4. Build Comments UI
+Comment thread display and creation interface.
+
+**Files:** `src/components/TaskComments.tsx`, `src/components/CommentForm.tsx`
+
+### 5. Add @Mention Functionality
+Parse @mentions and notify mentioned users.
+
+**Files:** `src/utils/mentionParser.ts`, `src/services/notificationService.ts`
+
+### 6. Implement Notification System
+Real-time and email notifications for task updates.
+
+**Files:** `src/services/notificationService.ts`, `src/api/websocket/taskUpdates.ts`
+
+### 7. Add Watchers Feature
+Allow users to watch tasks they're interested in.
+
+**Files:** `db/migrations/004_add_task_watchers.sql`, `src/api/routes/watchers.ts`
+
+## Dependencies
+
+- Task CRUD operations must exist
+- User directory API for assignee selection
+- Email service for email notifications
+- WebSocket infrastructure for real-time updates
+
+## Testing Strategy
+
+- Test assignment notifications
+- Test comment creation and mentions
+- Test notification delivery (in-app and email)
+- Test watchers subscription
+- E2E test full collaboration workflow
+
+## Success Criteria
+
+Feature complete when users can effectively collaborate on tasks through assignments, comments, and notifications with high engagement metrics.

package/templates/prd/example-task-management/features/task-crud.md

@@ -0,0 +1,222 @@
+---
+id: task-crud
+prd_id: task-management-system
+title: "Task Creation and Management"
+status: planned
+created: 2025-01-15
+updated: 2025-01-15
+---
+
+# Feature: Task Creation and Management
+
+## Description
+
+Implement core CRUD (Create, Read, Update, Delete) operations for tasks. Users should be able to create new tasks with rich metadata, view task details, update task information, and delete tasks when needed. This forms the foundation of the task management system.
+
+### Key Capabilities
+- Create tasks with title, description, priority, assignee, and due date
+- View task details in both list and detail views
+- Edit any task field with proper validation
+- Delete tasks with confirmation
+- Auto-save drafts to prevent data loss
+
+## Acceptance Criteria
+
+- [ ] User can create a task with all required fields (title, description)
+- [ ] User can create a task with optional fields (priority, assignee, due date)
+- [ ] Task title is required and limited to 200 characters
+- [ ] Task description supports markdown formatting
+- [ ] User can view a list of all tasks
+- [ ] User can click a task to view full details
+- [ ] User can edit any field of an existing task
+- [ ] Changes are validated before saving
+- [ ] User can delete a task after confirmation
+- [ ] Deleted tasks are soft-deleted (recoverable for 30 days)
+- [ ] API returns appropriate error messages for invalid data
+- [ ] All operations are logged for audit purposes
+
+## Tasks
+
+### 1. Create Task Database Schema
+Design and implement the tasks table with all required fields, indexes, and constraints.
+
+**Files to modify/create:**
+- `db/migrations/001_create_tasks_table.sql`
+- `db/models/task.ts`
+
+**Expected changes:**
+- Create tasks table with fields: id, title, description, status, priority, assignee_id, reporter_id, due_date, created_at, updated_at, deleted_at
+- Add indexes on status, assignee_id, due_date for query performance
+- Add foreign key constraints to users table
+- Create TypeScript type definitions for Task model
+
+### 2. Implement Task API Endpoints
+Create RESTful API endpoints for all CRUD operations with proper validation and error handling.
+
+**Files to modify/create:**
+- `src/api/routes/tasks.ts`
+- `src/api/controllers/taskController.ts`
+- `src/api/validators/taskValidator.ts`
+
+**Expected changes:**
+- POST /api/tasks - Create new task
+- GET /api/tasks - List all tasks (with pagination)
+- GET /api/tasks/:id - Get single task
+- PUT /api/tasks/:id - Update task
+- DELETE /api/tasks/:id - Soft delete task
+- Add request validation using Zod or Joi
+- Add proper error handling and HTTP status codes
+- Add authentication middleware
+
+### 3. Build Task Creation UI Component
+Create a form component for creating new tasks with all fields and validation.
+
+**Files to modify/create:**
+- `src/components/TaskForm.tsx`
+- `src/components/TaskForm.test.tsx`
+- `src/hooks/useTaskCreate.ts`
+
+**Expected changes:**
+- Form with inputs for title, description, priority, assignee, due date
+- Client-side validation matching API validation
+- Loading states and error handling
+- Success feedback (toast/notification)
+- Markdown editor for description field
+- Assignee dropdown populated from team members API
+
+### 4. Build Task List View
+Create a component to display all tasks in a filterable, sortable list.
+
+**Files to modify/create:**
+- `src/components/TaskList.tsx`
+- `src/components/TaskListItem.tsx`
+- `src/components/TaskList.test.tsx`
+- `src/hooks/useTaskList.ts`
+
+**Expected changes:**
+- Fetch and display tasks from API
+- Show key fields: title, status, priority, assignee, due date
+- Click item to view details (navigation)
+- Loading skeleton while fetching
+- Empty state when no tasks
+- Error state with retry option
+- Pagination controls
+
+### 5. Build Task Detail and Edit Views
+Create components for viewing and editing individual tasks.
+
+**Files to modify/create:**
+- `src/components/TaskDetail.tsx`
+- `src/components/TaskEdit.tsx`
+- `src/components/TaskDetail.test.tsx`
+- `src/hooks/useTaskUpdate.ts`
+- `src/hooks/useTaskDelete.ts`
+
+**Expected changes:**
+- Display all task fields in readable format
+- Edit button to switch to edit mode
+- Reuse TaskForm component for editing
+- Delete button with confirmation modal
+- Handle update and delete operations
+- Optimistic UI updates
+
+### 6. Write API Integration Tests
+Comprehensive tests for all API endpoints covering success and error cases.
+
+**Files to modify/create:**
+- `tests/integration/tasks.test.ts`
+
+**Expected changes:**
+- Test task creation with valid data
+- Test validation errors for invalid data
+- Test task retrieval (list and single)
+- Test task updates
+- Test task deletion and soft delete behavior
+- Test authorization (users can only delete own tasks)
+- Test pagination and filtering
+
+### 7. Write Component Unit Tests
+Unit tests for all React components using React Testing Library.
+
+**Files to modify/create:**
+- Component test files (already listed above)
+
+**Expected changes:**
+- Test form submission and validation
+- Test list rendering and interactions
+- Test detail view display
+- Test edit mode toggle
+- Test delete confirmation flow
+- Test loading and error states
+- Test accessibility (ARIA labels, keyboard navigation)
+
+## Dependencies
+
+- **User Authentication**: Must integrate with existing auth system to identify task reporter
+- **Team Member API**: Need endpoint to fetch list of team members for assignee dropdown
+- **Database**: PostgreSQL database must be available and configured
+
+## Testing Strategy
+
+### Unit Tests
+- Task model validation logic
+- API controller business logic
+- React component behavior
+- Custom hooks (useTaskCreate, useTaskList, etc.)
+- Form validation functions
+
+### Integration Tests
+- Full API endpoint flows (create → read → update → delete)
+- Database operations and constraints
+- Authentication and authorization
+- Error handling across layers
+
+### End-to-End Tests
+- Complete user flows: create task → view in list → edit → delete
+- Form validation error messages
+- Navigation between views
+- Cross-browser compatibility
+
+### Manual Testing Checklist
+- [ ] Create task with various field combinations
+- [ ] Edit task and verify changes persist
+- [ ] Delete task and confirm soft delete
+- [ ] Test with long titles/descriptions
+- [ ] Test with special characters in text fields
+- [ ] Test date picker with various date formats
+- [ ] Verify markdown rendering in description
+- [ ] Test on mobile viewport sizes
+
+## Implementation Notes
+
+### Technical Considerations
+- Use optimistic updates for better perceived performance
+- Implement proper loading states to avoid layout shift
+- Add debouncing for auto-save functionality (future enhancement)
+- Consider using React Query for caching and state management
+- Ensure proper SQL injection protection in database queries
+
+### UI/UX Guidelines
+- Follow existing design system and component library
+- Maintain consistent spacing and typography
+- Use appropriate loading skeletons matching content layout
+- Provide clear error messages with actionable guidance
+- Ensure keyboard accessibility (Tab navigation, Enter to submit)
+
+### Security Considerations
+- Validate all inputs on both client and server
+- Sanitize user-generated content (especially markdown)
+- Implement rate limiting on API endpoints
+- Check user permissions before allowing updates/deletes
+- Log all CRUD operations for audit trail
+
+## Success Criteria
+
+This feature is complete when:
+- All acceptance criteria are met
+- All tests are passing (unit, integration, E2E)
+- Code review approved
+- Documentation updated
+- Security review passed
+- Performance benchmarks met (API < 200ms, UI < 2s load)
+- Accessibility audit passed (WCAG 2.1 AA compliance)

package/templates/prd/example-task-management/features/task-workflow.md

@@ -0,0 +1,62 @@
+---
+id: task-workflow
+prd_id: task-management-system
+title: "Task Status Workflow"
+status: planned
+created: 2025-01-15
+updated: 2025-01-15
+---
+
+# Feature: Task Status Workflow
+
+## Description
+
+Implement a clear state machine for task progression through defined statuses: Todo → In Progress → In Review → Done. Include validation rules to ensure tasks follow logical transitions and provide visual indicators for current status.
+
+## Acceptance Criteria
+
+- [ ] Tasks can transition between statuses: Todo → In Progress → In Review → Done
+- [ ] Invalid transitions are prevented (e.g., Todo → Done directly)
+- [ ] Status changes are logged with timestamp and user
+- [ ] Visual status indicators use consistent colors
+- [ ] Users can view status history for any task
+- [ ] Bulk status updates supported (select multiple tasks)
+- [ ] Status change triggers notifications to assignee and watchers
+
+## Tasks
+
+### 1. Implement Status State Machine
+Define valid state transitions and validation logic.
+
+**Files:** `src/models/taskWorkflow.ts`, `src/models/taskWorkflow.test.ts`
+
+### 2. Create Status Update API
+Add endpoint for status changes with validation.
+
+**Files:** `src/api/routes/tasks.ts` (PATCH /api/tasks/:id/status)
+
+### 3. Build Status UI Components
+Create status badges, dropdown, and transition buttons.
+
+**Files:** `src/components/TaskStatus.tsx`, `src/components/StatusHistory.tsx`
+
+### 4. Add Status History Tracking
+Log all status changes to audit trail.
+
+**Files:** `db/migrations/002_add_task_history.sql`, `src/models/taskHistory.ts`
+
+## Dependencies
+
+- Task CRUD operations must be implemented first
+- Notification system for status change alerts
+
+## Testing Strategy
+
+- Unit test all valid and invalid state transitions
+- Test status history recording
+- Test UI components for all status values
+- E2E test complete workflow from Todo to Done
+
+## Success Criteria
+
+Feature complete when tasks follow clear workflow, invalid transitions are blocked, and status history is fully auditable.

package/templates/prd/example-task-management/prd.md

@@ -0,0 +1,177 @@
+---
+id: task-management-system
+title: "Task Management System"
+version: 1.0.0
+status: not_started
+created: 2025-01-15
+updated: 2025-01-15
+author: Product Team
+---
+
+<!--
+📚 EXAMPLE PRD
+This is an example PRD showing the recommended structure and content.
+Use this as a reference when creating your own PRDs.
+See ../README.md for full documentation.
+-->
+
+# Task Management System
+
+## Purpose and Goals
+
+Build a task management system that enables team members to:
+- Create and organize tasks efficiently
+- Track progress on work items
+- Collaborate on task completion
+- Meet deadlines consistently
+
+**Key Objectives:**
+- Reduce time spent on task organization by 50%
+- Increase team visibility into work progress
+- Improve on-time task completion rate to 90%
+- Enable seamless collaboration across distributed teams
+
+## User Needs
+
+### Target Audience
+- Software development teams (5-50 members)
+- Project managers coordinating multiple initiatives
+- Individual contributors tracking their workload
+- Team leads monitoring team progress
+
+### User Stories
+
+1. As a developer, I want to create tasks with clear descriptions so that I know exactly what needs to be done
+2. As a project manager, I want to see all tasks across the team so that I can identify bottlenecks
+3. As a team lead, I want to assign tasks to team members so that work is distributed effectively
+4. As a developer, I want to update task status so that everyone knows what I'm working on
+5. As a user, I want to filter tasks by priority so that I can focus on what's most important
+
+## Features and Functionality
+
+### Feature 1: Task Creation and Management
+**File**: [features/task-crud.md](features/task-crud.md)
+**Status**: planned
+**Description**: Core functionality for creating, reading, updating, and deleting tasks with rich metadata (title, description, priority, assignee, due date).
+
+### Feature 2: Task Status Workflow
+**File**: [features/task-workflow.md](features/task-workflow.md)
+**Status**: planned
+**Description**: State management system with clear transitions (Todo → In Progress → In Review → Done) and validation rules.
+
+### Feature 3: Task Assignment and Collaboration
+**File**: [features/task-collaboration.md](features/task-collaboration.md)
+**Status**: planned
+**Description**: Assign tasks to team members, add comments, mention colleagues, and receive notifications on task updates.
+
+## Design and User Experience
+
+### Data Model
+```
+Task {
+  id: string
+  title: string
+  description: string
+  status: 'todo' | 'in_progress' | 'in_review' | 'done'
+  priority: 'low' | 'medium' | 'high' | 'urgent'
+  assignee: User | null
+  reporter: User
+  dueDate: Date | null
+  createdAt: Date
+  updatedAt: Date
+  comments: Comment[]
+}
+```
+
+### User Workflow
+```
+1. User clicks "New Task" button
+2. Fill out task form (title, description, priority, assignee, due date)
+3. Click "Create" → Task appears in task list
+4. Assignee receives notification
+5. Assignee updates status as they work
+6. Team members can view progress in real-time
+```
+
+## Release Criteria
+
+### Functional Requirements
+- [ ] Users can create tasks with all required fields
+- [ ] Users can update task status through defined workflow
+- [ ] Users can assign tasks to team members
+- [ ] Users can view all tasks in a list/board view
+- [ ] Users can filter and search tasks
+- [ ] Users can add comments to tasks
+- [ ] Users receive notifications for task updates
+- [ ] Task data persists across sessions
+
+### Usability Requirements
+- [ ] Task creation takes less than 30 seconds
+- [ ] Status updates require single click
+- [ ] Task list loads in under 2 seconds
+- [ ] Interface is intuitive without training
+- [ ] Mobile-responsive design
+- [ ] Keyboard shortcuts for common actions
+
+### Technical Requirements
+- [ ] RESTful API for all operations
+- [ ] Real-time updates via WebSockets
+- [ ] Data validation on client and server
+- [ ] Secure authentication and authorization
+- [ ] Comprehensive error handling
+- [ ] 99.9% uptime SLA
+- [ ] Database indexes for performant queries
+
+## Success Metrics (KPIs)
+
+- **Adoption Rate**: 80% of team members create at least one task per week
+- **Task Completion**: 90% of tasks completed by due date
+- **Time to Create Task**: Average < 45 seconds
+- **User Satisfaction**: 4.5/5 rating in user surveys
+- **System Performance**: Page load < 2 seconds, API response < 200ms
+- **Collaboration**: Average 3+ comments per task
+- **Active Usage**: 70% of team members log in daily
+
+## Constraints and Dependencies
+
+### Technical Constraints
+- Must integrate with existing authentication system
+- Must work on existing tech stack (React, Node.js, PostgreSQL)
+- Must support 500 concurrent users
+- Must be deployed on current AWS infrastructure
+- Must meet company security and data privacy standards
+
+### Dependencies
+- User authentication service (existing)
+- Notification system (to be enhanced)
+- Email service (existing)
+- Team member directory API (existing)
+
+### Known Limitations
+- Initial version limited to text-based tasks (no file attachments)
+- No offline support in v1.0
+- No recurring tasks in v1.0
+- Task history limited to 90 days
+- Maximum 1000 tasks per user
+
+## Notes
+
+### Future Enhancements (Post-v1.0)
+- File attachments and media support
+- Recurring tasks and task templates
+- Advanced analytics and reporting
+- Time tracking integration
+- Gantt chart / timeline views
+- Mobile native apps
+- Third-party integrations (Slack, GitHub)
+- Custom fields and task types
+
+### Open Questions
+- Should we support task dependencies? (Decision: Not in v1.0)
+- What's the max number of assignees per task? (Decision: 1 assignee, multiple watchers)
+- How long should we keep completed tasks? (Decision: Indefinitely, with archive option)
+
+---
+
+**Related PRDs:**
+This is a standalone PRD for initial launch. Future enhancements may spawn related PRDs for advanced features.