# People Flow Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Build a standalone Python project that counts unique line crossings in street videos and adds track-level age/gender summaries.

**Architecture:** Use Ultralytics YOLO to detect and track persons frame by frame, then run DeepFace on sampled person crops to infer face attributes. Keep counting, tracking, and attribute voting in separate modules so the demographic backend can be swapped later.

**Tech Stack:** Python, Ultralytics YOLO, OpenCV, DeepFace, PyYAML, pandas

---

### Task 1: Scaffold the project

**Files:**
- Create: `README.md`
- Create: `requirements.txt`
- Create: `pyproject.toml`
- Create: `configs/default_config.yaml`
- Create: `docs/plans/2026-04-07-people-flow-design.md`

**Step 1: Write the initial files**

Add installation instructions, runtime expectations, and default settings.

**Step 2: Verify structure**

Run: `find . -maxdepth 3 | sed -n '1,120p'`
Expected: project files and directories exist.

**Step 3: Commit**

This workspace is not a git repository. Skip the commit step unless the user later initializes git here.

### Task 2: Build the CLI and config loader

**Files:**
- Create: `main.py`
- Create: `src/people_flow/__init__.py`
- Create: `src/people_flow/config.py`
- Create: `src/people_flow/models.py`

**Step 1: Implement argument parsing**

Support `video` and `batch` subcommands, config overrides, output directory selection, and line overrides.

**Step 2: Implement config loading**

Load YAML defaults and merge CLI overrides into typed dataclasses.

**Step 3: Verify**

Run: `python3 -m compileall main.py src`
Expected: compile succeeds without syntax errors.

### Task 3: Implement tracking and counting

**Files:**
- Create: `src/people_flow/tracking.py`
- Create: `src/people_flow/counting.py`

**Step 1: Extract tracked `person` detections**

Convert YOLO result objects into simple track observations with `track_id`, bounding box, confidence, and center point.

**Step 2: Implement line-cross counting**

Count one crossing per track by monitoring the sign change of the track center relative to the configured line.

**Step 3: Verify**

Run: `python3 -m compileall src`
Expected: compile succeeds.

### Task 4: Implement attribute voting and output helpers

**Files:**
- Create: `src/people_flow/attributes.py`
- Create: `src/people_flow/io_utils.py`

**Step 1: Integrate DeepFace**

Sample person crops, run `age` and `gender` analysis, normalize labels, and store per-track votes.

**Step 2: Implement output helpers**

Write JSON summaries, CSV summaries, and draw overlays onto frames.

**Step 3: Verify**

Run: `python3 -m compileall src`
Expected: compile succeeds.

### Task 5: Implement the processing pipeline

**Files:**
- Create: `src/people_flow/pipeline.py`

**Step 1: Build the main loop**

Open the video, run YOLO tracking on frames, update counters, sample attributes, draw overlays, and save artifacts.

**Step 2: Build batch mode**

Discover supported video files recursively and run the same pipeline per file, then write `outputs/batch_summary.csv`.

**Step 3: Verify**

Run: `python3 -m compileall main.py src`
Expected: compile succeeds.

### Task 6: Final verification

**Files:**
- Modify: `README.md`

**Step 1: Smoke-check the CLI**

Run: `python3 main.py --help`
Expected: help text shows the `video` and `batch` commands.

**Step 2: Document limitations**

Make sure README notes Python version constraints and face-quality limitations.

**Step 3: Commit**

Skip commit because this workspace is not a git repository.