# ColaFlow Sprint Planning System

This directory contains all Sprint, Story, and Task planning files managed by the `product-manager` sub agent.

## File Naming Convention

The system uses a hierarchical file naming system for easy pattern matching and retrieval:

### File Types
- **Sprint files**: `sprint_{N}.md` (e.g., `sprint_1.md`, `sprint_2.md`)
- **Story files**: `sprint_{N}_story_{M}.md` (e.g., `sprint_1_story_1.md`, `sprint_1_story_2.md`)
- **Task files**: `sprint_{N}_story_{M}_task_{K}.md` (e.g., `sprint_1_story_1_task_1.md`)

### Example Structure
```
docs/plans/
├── sprint_1.md                      # Sprint 1 overview
├── sprint_1_story_1.md              # Story 1 in Sprint 1
├── sprint_1_story_1_task_1.md       # Task 1 of Story 1 in Sprint 1
├── sprint_1_story_1_task_2.md       # Task 2 of Story 1 in Sprint 1
├── sprint_1_story_2.md              # Story 2 in Sprint 1
├── sprint_1_story_2_task_1.md       # Task 1 of Story 2 in Sprint 1
├── sprint_2.md                      # Sprint 2 overview
├── sprint_2_story_1.md              # Story 1 in Sprint 2
└── sprint_2_story_1_task_1.md       # Task 1 of Story 1 in Sprint 2
```

## How to Query Files

### Using Glob Patterns

**Get all sprints:**
```
docs/plans/sprint_*.md
```
This will match: `sprint_1.md`, `sprint_2.md`, etc. (excluding story and task files)

**Get all stories in Sprint 1:**
```
docs/plans/sprint_1_story_*.md
```
This will match: `sprint_1_story_1.md`, `sprint_1_story_2.md`, etc. (excluding task files)

**Get all tasks in Sprint 1, Story 2:**
```
docs/plans/sprint_1_story_2_task_*.md
```
This will match: `sprint_1_story_2_task_1.md`, `sprint_1_story_2_task_2.md`, etc.

## Status Tracking

### Status Values
- **not_started**: Item created but not yet started
- **in_progress**: Item is actively being worked on
- **completed**: Item finished, all acceptance criteria met
- **blocked**: Item cannot proceed due to dependency or issue

### Auto-Completion Logic

**Task Completion:**
- When a task is marked as `completed`, the system checks if all tasks in the story are completed
- If yes, the story is automatically marked as `completed`

**Story Completion:**
- When a story is marked as `completed`, the system checks if all stories in the sprint are completed
- If yes, the sprint is automatically marked as `completed`

## File Metadata

Each file contains frontmatter metadata for easy tracking:

### Sprint Metadata
```yaml
---
sprint_id: sprint_1
sprint_number: 1
milestone: M2
status: in_progress
created_date: 2025-11-05
start_date: 2025-11-11
end_date: 2025-11-24
---
```

### Story Metadata
```yaml
---
story_id: story_1
sprint_id: sprint_1
status: in_progress
priority: P0
story_points: 5
created_date: 2025-11-05
assignee: Backend Team
---
```

### Task Metadata
```yaml
---
task_id: task_1
story_id: story_1
sprint_id: sprint_1
status: completed
type: backend
estimated_hours: 4
actual_hours: 3.5
created_date: 2025-11-05
completion_date: 2025-11-06
assignee: John Doe
---
```

## Usage Examples

### For Product Manager Sub Agent

**Create a new sprint:**
1. Use Glob to find the latest sprint number
2. Create new sprint file with incremented number
3. Fill in sprint details using the template

**Add stories to sprint:**
1. Use Glob to find latest story number in the sprint
2. Create new story file with incremented number
3. Link story to sprint by updating sprint file

**Add tasks to story:**
1. Use Glob to find latest task number in the story
2. Create new task file with incremented number
3. Link task to story by updating story file

**Mark task completed:**
1. Update task file status to `completed`
2. Check if all tasks in story are completed
3. If yes, auto-complete the story
4. Check if all stories in sprint are completed
5. If yes, auto-complete the sprint

### For Developers

**Find your assigned tasks:**
```bash
# Search all task files for your name
grep -r "assignee: John Doe" docs/plans/*_task_*.md
```

**Check sprint progress:**
```bash
# Read the sprint overview file
cat docs/plans/sprint_1.md
```

**Update task status:**
```bash
# Edit the task file and update status, hours, etc.
# The product-manager will handle auto-completion logic
```

## Benefits of This System

1. **Easy Pattern Matching**: Glob patterns make it simple to find related files
2. **Clear Hierarchy**: File names explicitly show Sprint → Story → Task relationships
3. **Unique IDs**: Each item has a unique, sequential ID that never repeats
4. **Auto-Completion**: Parent items are automatically marked completed when all children are done
5. **Metadata Tracking**: Frontmatter provides structured data for queries and reporting
6. **Cross-Linking**: Markdown links connect all related files
7. **Git-Friendly**: Plain text markdown files work well with version control

## Best Practices

1. **Always use Glob** to find the latest number before creating new files
2. **Keep metadata updated** - status, dates, hours, assignees
3. **Use descriptive titles** for sprints, stories, and tasks
4. **Link dependencies** between stories and tasks
5. **Add notes** for important decisions, blockers, or risks
6. **Update progress summaries** when task/story status changes
7. **Follow naming convention** strictly to enable pattern matching

---

**Managed by**: product-manager sub agent
**Last Updated**: 2025-11-05