184 lines
5.3 KiB
Markdown
184 lines
5.3 KiB
Markdown
# 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
|