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

package/templates/prd/PRD_CREATION_INSTRUCTIONS.md

@@ -0,0 +1,268 @@
+# PRD Creation Instructions for Claude Code
+
+## When to Create a PRD
+
+Create a PRD automatically when the user describes:
+- A new product feature or capability
+- A system enhancement or improvement
+- A major technical initiative
+- A user-facing functionality change
+- Multi-step implementation requiring planning
+
+## PRD Creation Process
+
+### Step 1: Engage in Interactive Planning
+
+When a user describes requirements, engage in collaborative discussion:
+- Ask clarifying questions about scope and goals
+- Discuss constraints (technical, time, budget, team)
+- Explore user needs and pain points
+- Consider alternatives and trade-offs
+- Validate understanding before creating PRD
+
+### Step 2: Determine PRD Structure
+
+From the conversation, extract:
+- **Purpose**: What problem are we solving?
+- **Goals**: What do we want to achieve?
+- **User needs**: Who benefits and how?
+- **Features**: What functionality is needed?
+- **Success criteria**: How do we measure success?
+- **Constraints**: What limitations exist?
+
+### Step 3: Create PRD Document
+
+Use the template at `docs/prd/_template/prd-template.md` and populate:
+
+**YAML Frontmatter:**
+```yaml
+id: [descriptive-kebab-case-id]
+title: "[Clear, User-Focused Title]"
+version: 1.0.0  # Start with 1.0.0
+status: not_started  # or in_progress if work has begun
+created: [YYYY-MM-DD - today's date]
+updated: [YYYY-MM-DD - today's date]
+author: [Claude Code or user name if provided]
+```
+
+**Content Sections:**
+
+1. **Purpose and Goals**
+   - Clear problem statement
+   - High-level objectives
+   - Value proposition
+
+2. **User Needs**
+   - Target audience definition
+   - User stories in "As a [role], I want [action] so that [benefit]" format
+   - Pain points being addressed
+
+3. **Features and Functionality**
+   - List each major feature
+   - Link to separate feature markdown files
+   - Brief description of each feature
+   - Initial status (usually "planned")
+
+4. **Design and User Experience** (Optional)
+   - Directory structures if relevant
+   - Workflow visualizations
+   - UI/UX considerations
+
+5. **Release Criteria**
+   - Functional requirements (must-haves)
+   - Usability requirements
+   - Technical requirements
+   - Use checkboxes for trackability
+
+6. **Success Metrics (KPIs)**
+   - Measurable goals
+   - Target values
+   - How success will be evaluated
+
+7. **Constraints and Dependencies**
+   - Technical constraints
+   - Dependencies on other systems
+   - Known limitations or trade-offs
+
+### Step 4: Create Feature Files
+
+For each feature identified in the PRD:
+
+1. Create `docs/prd/{prd-id}/features/{feature-name}.md`
+2. Use the feature template at `docs/prd/_template/feature-template.md`
+3. Fill out:
+   - **YAML frontmatter** with feature metadata
+   - **Description** of what the feature does
+   - **Acceptance Criteria** with checkboxes
+   - **Tasks** broken down with files and expected changes
+   - **Dependencies** on other features
+   - **Testing Strategy** for validation
+
+**Feature YAML Frontmatter:**
+```yaml
+id: [feature-kebab-case-id]
+prd_id: [parent-prd-id]
+title: "[Feature Title]"
+status: planned  # planned | in_progress | complete
+created: [YYYY-MM-DD]
+updated: [YYYY-MM-DD]
+```
+
+### Step 5: Organize Directory Structure
+
+Create the following structure:
+```
+docs/prd/{prd-id}/
+├── prd.md
+└── features/
+    ├── feature-1.md
+    ├── feature-2.md
+    └── feature-3.md
+```
+
+### Step 6: Save and Confirm
+
+1. Save PRD to `docs/prd/{prd-id}/prd.md`
+2. Save features to `docs/prd/{prd-id}/features/{feature-name}.md`
+3. Tell user: "I've created PRD '{title}' with {N} features at docs/prd/{prd-id}/"
+4. Offer to make adjustments or add more features
+
+## Quality Checklist
+
+Before finalizing a PRD, verify:
+
+- [ ] All YAML frontmatter fields are filled
+- [ ] ID is in kebab-case and unique
+- [ ] Purpose clearly states the problem being solved
+- [ ] User needs include specific user stories
+- [ ] Each feature has its own markdown file
+- [ ] Features link correctly from main PRD
+- [ ] Acceptance criteria are testable
+- [ ] Tasks are broken down granularly
+- [ ] Success metrics are measurable
+- [ ] No TODO or FIXME comments remain
+- [ ] Markdown formatting is correct
+- [ ] File names follow conventions
+
+## Example Workflows
+
+### Workflow 1: New Feature Request
+
+```
+User: "We need to add user authentication to our app"
+
+Claude:
+1. Ask: "What authentication methods? Email/password? OAuth? Both?"
+2. Ask: "Any specific security requirements or compliance needs?"
+3. Ask: "Do we need password reset, MFA, session management?"
+4. Once clarified, create PRD:
+   - ID: user-authentication-system
+   - Features: email-auth, oauth-integration, password-reset, session-management
+5. Create feature files for each
+6. Save and confirm
+```
+
+### Workflow 2: Enhancement to Existing System
+
+```
+User: "Let's add real-time notifications to our chat app"
+
+Claude:
+1. Ask: "What events should trigger notifications?"
+2. Ask: "Desktop, mobile, or both? Browser notifications?"
+3. Ask: "How should users control notification preferences?"
+4. Create PRD:
+   - ID: real-time-notifications
+   - Features: push-notifications, notification-preferences, notification-history
+5. Create feature files
+6. Reference any existing PRDs if relevant
+7. Save and confirm
+```
+
+### Workflow 3: Technical Initiative
+
+```
+User: "We should refactor our API to use GraphQL"
+
+Claude:
+1. Ask: "What's driving this? Performance? Developer experience?"
+2. Ask: "Full migration or gradual? Timeline?"
+3. Ask: "Keep REST endpoints or deprecate them?"
+4. Create PRD:
+   - ID: graphql-api-migration
+   - Features: graphql-schema-design, resolver-implementation, client-migration
+5. Include migration strategy in PRD
+6. Create feature files with detailed tasks
+7. Save and confirm
+```
+
+## Common Pitfalls to Avoid
+
+❌ **Don't**: Create PRD without understanding user needs
+✅ **Do**: Have a collaborative discussion first
+
+❌ **Don't**: Write vague acceptance criteria like "Works well"
+✅ **Do**: Be specific "User can log in within 2 seconds"
+
+❌ **Don't**: Lump all functionality into one feature
+✅ **Do**: Break down into logical, testable features
+
+❌ **Don't**: Skip the constraints section
+✅ **Do**: Document limitations upfront to set expectations
+
+❌ **Don't**: Forget to link features in the main PRD
+✅ **Do**: Use relative links: `[features/auth.md](features/auth.md)`
+
+❌ **Don't**: Use technical jargon without explanation
+✅ **Do**: Write for both technical and non-technical stakeholders
+
+## Template Shortcuts
+
+### Simple Feature PRD
+```
+Purpose: Add [capability] to [system] for [user benefit]
+Features: 1-3 core features, each in separate file
+Success: [Measurable outcome]
+Timeline: [Estimated completion]
+```
+
+### System Enhancement PRD
+```
+Purpose: Improve [existing system] by [enhancement]
+Current Problems: [List pain points]
+Proposed Solution: [High-level approach]
+Features: Broken down by component or workflow
+Migration Strategy: If replacing existing functionality
+```
+
+### Technical Initiative PRD
+```
+Purpose: [Technical improvement] to achieve [business goal]
+Technical Context: Current architecture and limitations
+Proposed Architecture: New approach
+Features: Implementation phases or components
+Validation: How to test and measure success
+```
+
+## Integration with Planning System
+
+PRDs work alongside the planning system:
+- **Plan tool**: Use `plan accept` to create implementation plans
+- **Plan feature**: Add features to existing PRDs
+- **Plan implement**: Execute task-by-task with TDD
+- **Git hooks**: Automatically track commit SHAs in feature files
+
+When creating a PRD, you can offer to:
+1. Create the PRD structure
+2. Use the plan tool to create an implementation plan
+3. Begin implementation with `plan implement`
+
+## Final Notes
+
+- **Be collaborative**: PRDs are living documents; expect iteration
+- **Be thorough**: Better to over-document than under-document
+- **Be clear**: Write for diverse audiences
+- **Be realistic**: Set achievable goals and acknowledge constraints
+- **Be helpful**: Offer to create PRD even if not explicitly requested
+
+When in doubt, ask the user: "Would you like me to create a PRD to document these requirements?"

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: planned
+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