ColaFlow/docs/plans

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

---
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

---
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

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

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

Check sprint progress:

# Read the sprint overview file
cat docs/plans/sprint_1.md

Update task status:

# 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