Project Planning

Directory Structure

docs/project-management/
├── README.md                          # Project overview + phase index
└── phase-{N}-{name}/
    ├── README.md                      # Phase overview
    ├── epics/
    │   ├── README.md                  # Epic backlog index
    │   └── epic-{NN}-{name}/
    │       ├── README.md              # Epic summary + story table
    │       └── stories/
    │           ├── README.md          # Story index
    │           └── story-e{NN}-s{NN}-{name}/
    │               ├── README.md      # Story overview
    │               ├── tasks.md       # Task breakdown with checkboxes
    │               └── acceptance.md  # Acceptance criteria
    └── sprints/
        ├── README.md                  # Sprint index table
        └── sprint-{NN}-{name}/
            ├── README.md              # Sprint scope + exit criteria
            └── execution-plan.md      # Day-wise sequencing

ID Conventions

Directory names: kebab-case. Example: epic-01-auth-and-onboarding, story-e01-s03-store-resolution.

File Templates

Epic README.md

# E{NN} - {Epic Name}

{Brief description of epic goal — 1-2 sentences.}

## Priority

{HIGH | MEDIUM | LOW} - {Justification if HIGH}

## Dependencies

- {E{NN} - Name} (if applicable)
- None

## Sprint Coverage

- Sprint {N}
- Sprint {N+1} (if spans multiple)

## Stories

| Story ID  | Story                                                | Sprint     | Planned Window     | Status  |
| --------- | ---------------------------------------------------- | ---------- | ------------------ | ------- |
| E{NN}-S01 | [{Name}](./stories/story-e{nn}-s01-{name}/README.md) | Sprint {N} | Week {X} Day {Y-Z} | Planned |

## Progress Snapshot ({YYYY-MM-DD})

- [ ] E{NN}-S01 {name}
- [ ] E{NN}-S02 {name}

## Story Folder

- [Story Index](./stories/README.md)

Story README.md

# E{NN}-S{NN} - {Story Name}

## Overview

- Epic: [E{NN} - {Epic Name}](../../README.md)
- Sprint: Sprint {N}
- Planned window: Week {X} Day {Y-Z}
- Status: Planned

## Goal

{Single sentence — what this story accomplishes.}

## Deliverables

- {Concrete output 1}
- {Concrete output 2}
- {Concrete output 3}

## Dependencies

- [{E{NN}-S{NN}}](../path/to/dependency/README.md)
- None

## Detail Files

- [Task Breakdown](./tasks.md)
- [Acceptance Criteria](./acceptance.md)

tasks.md

# E{NN}-S{NN} Task Breakdown

## Execution Checklist

## T1. {Task group name}

- [ ] {Actionable subtask with technical detail}
- [ ] {Another subtask}

## T2. {Next task group}

- [ ] {Subtask}
- [ ] {Subtask}

## T3. {Testing/validation group}

- [ ] {Test subtask}

---

Total Estimate: {X} hours ({Y} days)

Task grouping conventions: Group by functional concern (data model, API, UI, testing), not chronologically.

acceptance.md

# E{NN}-S{NN} Acceptance Criteria

- [ ] {User-facing outcome — what, not how}
- [ ] {Another outcome}
- [ ] {Technical validation if appropriate}

## Verification Notes

- Capture evidence links (PR, screenshots, logs, test reports).
- Mark criteria done only after review and demo sign-off.

Write acceptance criteria as outcomes: "User can create and list products" not "Build product API endpoints."

Sprint README.md

# Sprint {N} - {Name}

## Status: Planned

## Scope

- Sprint ID: SPR-{NN}
- Duration: Weeks {X}-{Y}
- Goal: {Single sentence sprint objective}

## Committed Stories

| Story ID    | Story                      | Epic  | Planned Window     |
| ----------- | -------------------------- | ----- | ------------------ |
| E{NN}-S{NN} | [{Name}](path/to/tasks.md) | E{NN} | Week {X} Day {Y-Z} |

## Exit Criteria

- [ ] {Sprint-level success criterion}
- [ ] {Another criterion}

## Detailed Plan

- [Execution Plan](./execution-plan.md)

execution-plan.md

# SPR-{NN} Execution Plan

## Week {X} Day {Y-Z}

- [ ] [E{NN}-S{NN} - {Name}](../../epics/epic-{nn}-{name}/stories/story-e{nn}-s{nn}-{name}/tasks.md)

## Week {X} Day {Y-Z}

- [ ] [E{NN}-S{NN} - {Name}](path/to/tasks.md)

## Sprint Cadence

- Daily standup: track blockers and story progress.
- Mid-sprint review: re-plan only if exit criteria are at risk.
- Sprint demo and retrospective: capture carry-over decisions explicitly.

Time windows: Week {X} Day {Y} or Week {X} Day {Y-Z}. Sprints are 2 weeks (10 working days).

Mode: Create Plan

When starting from scratch:

1. Understand scope — Ask the user about project goals, features, timeline, team size
2. Identify epics — Group related features into 4-8 epics
3. Break into stories — Each epic gets 3-7 stories. Each story is 1-5 days of work.
4. Write tasks — Each story gets task groups (T1, T2...) with checkbox subtasks
5. Write acceptance criteria — User-facing outcomes per story
6. Plan sprints — 2-week sprints. Assign stories to sprints respecting dependencies.
7. Create execution plans — Day-wise sequencing within each sprint
8. Generate all files — Create full directory structure with all markdown files
9. Create index files — README.md at every level linking children

Dependency ordering: Foundation/infrastructure epics first. Stories within an epic should have clear dependency chains noted in their README.md.

Sprint capacity: ~5-8 stories per 2-week sprint depending on story size. Don't overload.

Mode: Add Epic/Story

When adding work to an existing plan:

1. Read existing plan — Understand current epics, sprints, their capacity
2. Determine epic — New epic or fits under existing one?
3. Create story files — Full set (README, tasks, acceptance) with correct IDs
4. Assign sprint — Find sprint with capacity or create new sprint
5. Update all indexes — Epic story table, sprint committed stories, execution plan, phase README
6. Check dependencies — Link to existing stories this depends on or blocks

ID sequencing: New epics get next available E{NN}. New stories get next S{NN} within their epic.

Mode: Restructure Sprints

When priorities change (hotfix, scope change, customer escalation):

1. Read current sprint state — What's in progress, what's planned, what's done
2. Identify the change — What's being added/removed/reprioritized
3. Create new epic/stories if needed — With Priority: HIGH marker
4. Restructure affected sprints:
   • Move displaced stories to later sprints
   • Update execution plans with new day-wise sequencing
   • Update sprint committed story tables
   • Adjust total timeline if scope increased
5. Update all cross-references — Sprint coverage in epics, story planned windows
6. Flag risks — If restructuring pushes stories past deadline, call it out

Never silently drop stories. Displaced stories must land in a specific sprint, not disappear.

Mode: Update Status

When work is completed:

1. Mark tasks done — Check off subtasks in tasks.md ([x])
2. Mark acceptance criteria — Check off in acceptance.md
3. Update story status — Change Status: Planned → Done in story README
4. Update epic progress — Check off in epic's Progress Snapshot section
5. Update sprint status — If all stories done, set Status: Done
6. Add verification snapshot — Date-stamped section with evidence (file paths, test results, PR links)

## Verification Snapshot ({YYYY-MM-DD})

- Auth flow implemented in `apps/api/src/modules/auth/auth.service.ts`
- Tests pass: `pnpm test` (15 tests passing)
- PR: #{number}

Mode: Audit Completion

When verifying that a feature is truly done (doc + code audit):

1. Read story's acceptance.md — List all criteria
2. Read story's tasks.md — List all subtasks
3. Scan codebase for deliverables:
   • Files mentioned in tasks exist?
   • Endpoints mentioned are implemented?
   • Tests mentioned pass?
   • Components mentioned render?
4. Flag gaps:
   • Unchecked acceptance criteria
   • Missing deliverables in code
   • Tasks marked done but code not found
   • Code exists but not checked off in docs
5. Generate audit report:

## Audit: E{NN}-S{NN} ({YYYY-MM-DD})

### Acceptance Criteria

- [x] {Criterion 1} — Verified: {file/endpoint}
- [ ] {Criterion 2} — GAP: {what's missing}

### Tasks

- T1: 4/4 complete
- T2: 3/5 complete — Missing: {specific subtasks}

### Code Verification

- {endpoint}: Found at {path} ✓
- {component}: NOT FOUND ✗
- Tests: {N}/{M} passing

### Verdict: PASS | GAPS FOUND

Common Mistakes

Quick Reference

Create: Scope → Epics → Stories → Tasks → Acceptance → Sprints → Execution Plans → All Files

Add: Read existing → Create files with correct IDs → Assign sprint → Update all indexes

Restructure: Read state → Create new work → Move displaced stories → Update all refs → Flag risks

Update: tasks.md [x] → acceptance.md [x] → story status → epic progress → sprint status → verification snapshot

Audit: Read acceptance → Read tasks → Scan code → Flag gaps → Generate report