@magic-ingredients/tiny-brain-local 0.11.0 → 0.13.0

package/templates/prd/README.md

@@ -0,0 +1,252 @@
+# Product Requirements Documents (PRDs)
+
+This directory contains Product Requirements Documents (PRDs) for tiny-brain features and capabilities. PRDs provide structured documentation of product requirements with clear feature breakdown and implementation tracking.
+
+## Purpose
+
+PRDs in tiny-brain serve to:
+- **Document requirements systematically** - Capture product needs with clear acceptance criteria
+- **Organize features hierarchically** - Break down complex projects into manageable features and tasks
+- **Track implementation progress** - Monitor completion through git commit integration
+- **Maintain project history** - Preserve planning decisions and implementation details in the repository
+
+## Directory Structure
+
+```
+docs/prd/
+├── README.md                          # This file
+├── _template/                         # Templates for creating new PRDs
+│   ├── prd-template.md               # Blank PRD template
+│   └── feature-template.md           # Blank feature template
+│
+└── {prd-id}/                         # Each PRD gets its own directory
+    ├── prd.md                        # Main PRD document
+    └── features/                     # Feature subdirectory
+        ├── feature-1.md              # Feature implementation plan
+        ├── feature-2.md              # Feature implementation plan
+        └── ...
+```
+
+## Creating a New PRD
+
+### Method 1: Using the Plan Tool (Recommended)
+
+The easiest way to create a PRD is through the tiny-brain plan tool:
+
+```bash
+# Start planning mode and describe your PRD
+# The tool will help you create the PRD structure interactively
+```
+
+When using the plan tool with Claude Code:
+1. Describe your project requirements in a planning discussion
+2. Use `plan accept` to create the PRD from your discussion
+3. Use `plan feature` to add individual features
+4. Use `plan implement` to start task-by-task implementation
+
+### Method 2: Manual Creation
+
+You can also create PRDs manually by copying the templates:
+
+1. **Copy the template directory:**
+   ```bash
+   cp -r _template/ your-prd-name/
+   ```
+
+2. **Rename files:**
+   ```bash
+   cd your-prd-name/
+   mv prd-template.md prd.md
+   mkdir features
+   ```
+
+3. **Fill in the template:**
+   - Update YAML frontmatter with your PRD details
+   - Replace placeholders with your content
+   - Create feature files in the `features/` subdirectory
+
+## PRD Document Structure
+
+### YAML Frontmatter
+
+Every PRD must include YAML frontmatter at the top:
+
+```yaml
+---
+id: unique-prd-id              # Unique identifier (kebab-case)
+title: Human Readable Title    # Display title
+version: 1.0.0                 # Semantic version
+status: not_started            # not_started | in_progress | complete
+created: YYYY-MM-DD            # Creation date (ISO format)
+updated: YYYY-MM-DD            # Last update date (ISO format)
+author: Author Name            # Who created this PRD
+---
+```
+
+### Required Sections
+
+1. **Purpose and Goals** - What problem are you solving and why?
+2. **User Needs** - Who are the users and what do they need?
+3. **Features and Functionality** - List of features with links to feature files
+4. **Release Criteria** - What defines "done" for this PRD?
+5. **Success Metrics** - How will you measure success?
+6. **Constraints and Dependencies** - Technical and external considerations
+
+See `_template/prd-template.md` for the full structure with placeholders.
+
+## Feature Document Structure
+
+### YAML Frontmatter
+
+Every feature must include YAML frontmatter:
+
+```yaml
+---
+id: feature-id                 # Unique identifier (kebab-case)
+prd_id: parent-prd-id         # Reference to parent PRD
+title: Feature Title           # Display title
+status: planned                # planned | in_progress | complete
+created: YYYY-MM-DD           # Creation date (ISO format)
+updated: YYYY-MM-DD           # Last update date (ISO format)
+---
+```
+
+### Required Sections
+
+1. **Description** - What does this feature do?
+2. **Acceptance Criteria** - Testable requirements (use checkboxes)
+3. **Tasks** - Implementation tasks with file details
+4. **Dependencies** - Other features or systems this depends on
+5. **Testing Strategy** - How will you test this?
+
+See `_template/feature-template.md` for the full structure with placeholders.
+
+## Task Tracking with Git Commits
+
+Features support automatic commit SHA tracking through git hooks. When you follow the TDD (Test-Driven Development) workflow with conventional commit messages, your tasks will automatically track commit SHAs.
+
+### Commit Message Convention
+
+Use these prefixes for automatic tracking:
+
+- **`test:`** - Writing tests (Red phase)
+  - Tracked in: `testCommitSha` field
+  - Example: `test: add user authentication tests`
+
+- **`feat:`** - Implementing feature (Green phase)
+  - Tracked in: `commitSha` field
+  - Example: `feat: implement user authentication`
+
+- **`refactor:`** - Refactoring code (Refactor phase)
+  - Tracked in: `refactorCommitSha` field
+  - Example: `refactor: simplify authentication logic`
+
+### How It Works
+
+1. You commit with a structured message (e.g., `feat: add login button`)
+2. A post-commit git hook captures the commit SHA and message
+3. The hook calls `tiny-brain track-commit` to update feature markdown files
+4. The appropriate SHA field is updated based on the commit prefix
+5. Your feature file shows progress with commit references
+
+### Example Task Tracking
+
+In your feature markdown:
+
+```markdown
+### 1. Add user authentication (test: abc1234, impl: def5678, refactor: ghi9012)
+✅ **Status**: complete
+```
+
+The SHAs are automatically populated as you commit with the appropriate prefixes.
+
+## Example PRD
+
+The `plan-system-refactoring/` directory contains a complete, real-world example PRD that demonstrates all the concepts:
+
+- **Main PRD**: `plan-system-refactoring/prd.md`
+- **6 Features**: In `plan-system-refactoring/features/`
+- **Complete structure**: Shows all sections properly filled in
+- **Active tracking**: Being actively worked on with commit SHAs
+
+Use this as a reference when creating your own PRDs.
+
+## Integration with Tiny-Brain
+
+### Storage Locations
+
+PRDs live in two places:
+
+1. **Repository**: `docs/prd/{prd-id}/` (markdown files - version controlled)
+   - Contains the PRD structure, features, and tasks
+   - Tracked in git for history and collaboration
+
+2. **Tiny-Brain Storage**: `~/.tiny-brain/{persona}/plans/` (JSON - progress tracking)
+   - Contains current state, progress metrics, and metadata
+   - Updated in real-time as work progresses
+   - References the PRD markdown files
+
+### Plan Tool Operations
+
+The plan tool provides several operations for working with PRDs:
+
+- **`plan accept`** - Create a new PRD from planning discussion
+- **`plan feature`** - Add a feature to the current PRD
+- **`plan implement`** - Start implementing tasks one by one
+- **`plan status`** - Show current progress
+- **`plan list`** - List all plans
+
+### Dashboard Integration
+
+The tiny-brain dashboard displays:
+- All PRDs with their current status
+- Feature breakdown and progress
+- Task-level detail with commit SHAs
+- Real-time updates via Server-Sent Events (SSE)
+
+## Best Practices
+
+### 1. Keep PRDs Focused
+- One PRD per major feature or capability
+- Break large projects into multiple PRDs
+- Each PRD should have a clear, single purpose
+
+### 2. Write Clear Acceptance Criteria
+- Make criteria testable and measurable
+- Use checkboxes to track completion
+- Be specific about what "done" means
+
+### 3. Break Features into Tasks
+- Each task should be completable in one session
+- Tasks should be small enough for a single commit (or TDD cycle)
+- Include file paths and expected changes
+
+### 4. Follow TDD Workflow
+- Write tests first (`test:` commit)
+- Implement to pass tests (`feat:` commit)
+- Refactor if needed (`refactor:` commit)
+- Git hooks will track your progress automatically
+
+### 5. Keep PRDs Updated
+- Update status as features complete
+- Add new features as scope evolves
+- Document decisions and changes
+- Commit PRD updates along with code changes
+
+### 6. Link Related Work
+- Reference related PRDs in dependencies
+- Link to external documentation
+- Cross-reference features that interact
+- Maintain a clear hierarchy
+
+## Questions?
+
+For more information about the tiny-brain planning system:
+- See the main README at the repository root
+- Check the dashboard for visual progress tracking
+- Review `plan-system-refactoring/` as a working example
+- Use the plan tool for interactive guidance
+
+---
+
+**Note**: This PRD system is part of the tiny-brain planning refactoring project. The templates and structure are designed to support interactive PRD creation with Claude Code and automatic progress tracking through git hooks.

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

@@ -0,0 +1,105 @@
+---
+id: feature-id
+prd_id: parent-prd-id
+title: Feature Title
+status: defined
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+
+# Feature: [Feature Title]
+
+## Description
+
+[Provide a comprehensive description of what this feature does, why it's needed, and how it fits into the larger PRD. Be specific about the functionality it provides.]
+
+## Acceptance Criteria
+
+[List the specific, testable criteria that must be met for this feature to be considered complete. Use checkboxes for tracking.]
+
+- [ ] Criterion 1: [Specific requirement]
+- [ ] Criterion 2: [Specific requirement]
+- [ ] Criterion 3: [Specific requirement]
+- [ ] Criterion 4: [Specific requirement]
+
+## Tasks
+
+[List all implementation tasks. Each task should be a discrete unit of work that can be completed with a single commit (or small set of commits for TDD: test/impl/refactor). Tasks will automatically track commit SHAs when using git hooks with conventional commit messages.]
+
+### 1. Task Name
+[Brief description of what needs to be done]
+
+**Files to modify/create:**
+- `path/to/file1.ts`
+- `path/to/file2.ts`
+
+**Expected changes:**
+- Change 1: [Description]
+- Change 2: [Description]
+- Change 3: [Description]
+
+### 2. Task Name
+[Brief description of what needs to be done]
+
+**Files to modify/create:**
+- `path/to/file1.ts`
+
+**Expected changes:**
+- Change 1: [Description]
+- Change 2: [Description]
+
+[Add more tasks as needed. Each task will track:
+- testCommitSha: When you commit with "test: ..." prefix
+- commitSha: When you commit with "feat: ..." prefix
+- refactorCommitSha: When you commit with "refactor: ..." prefix]
+
+## Dependencies
+
+[List any dependencies this feature has on other features or external systems]
+
+- **Feature/System 1**: [Description of dependency]
+- **Feature/System 2**: [Description of dependency]
+
+## Testing Strategy
+
+[Describe how this feature will be tested]
+
+### Unit Tests
+- Test scenario 1
+- Test scenario 2
+- Test scenario 3
+
+### Integration Tests
+- Integration scenario 1
+- Integration scenario 2
+
+### Manual Testing
+- Manual test case 1
+- Manual test case 2
+
+## Implementation Notes
+
+[Optional: Add any technical notes, considerations, or important details for implementers]
+
+- Note 1: [Important consideration]
+- Note 2: [Technical detail]
+- Note 3: [Edge case to handle]
+
+## Workflow Example
+
+[Optional: If this feature involves a specific workflow or process, document it here]
+
+```bash
+# Example command or workflow
+step 1
+step 2
+step 3
+```
+
+## Benefits
+
+[Optional: Highlight the key benefits this feature provides]
+
+- ✅ Benefit 1
+- ✅ Benefit 2
+- ✅ Benefit 3

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.