imajin/.project/QUICK_START.md

# Quick Start Guide - Feature Streams

**New to the system?** Start here for a 5-minute orientation.

---

## What Are Streams?

**Streams** are feature-based workstreams that provide continuous context across sessions. Each stream has:
- **README.md** - Feature overview and architecture
- **STATUS.md** - Current progress and blockers
- **HANDOFF.md** - Context for resuming work
- **PLAN.md** - Implementation phases and tasks
- **NOTES.md** - Technical decisions and learnings

Think of them as "living documentation" that evolves with your feature.

---

## Current Active Streams (2026-01-14)

### 1. controlnet-foundation (✅ Phase 1 Complete)
**What**: Core ControlNet integration with SDXL
**Status**: OpenPose working, Phase 2 blocked on model downloads
**Location**: `.project/streams/controlnet-foundation/`
**Next**: Complete Phase 2 when models available

### 2. segmentation-clothing (✅ Phase 1 Complete)
**What**: RGB segmentation masks for clothing control
**Status**: Template-based MVP done, 100% test coverage
**Location**: `.project/streams/segmentation-clothing/`
**Next**: Phase 2 (pose-aware) when ControlNet segmentation ready

### 3. person-appearance-api (🟢 Ready to Start)
**What**: High-level API for person generation
**Status**: Ready to start Phase 1 (API design)
**Location**: `.project/streams/person-appearance-api/`
**Next**: Design API contracts and core structure

---

## Quick Actions

### View All Streams
```bash
cat .project/STREAMS_OVERVIEW.md
```

### Check Stream Status
```bash
cat .project/streams/controlnet-foundation/STATUS.md
```

### Resume Work on a Stream
```bash
# 1. Read handoff context
cat .project/streams/controlnet-foundation/HANDOFF.md

# 2. Check for blockers
grep "Blocker" .project/streams/controlnet-foundation/STATUS.md

# 3. Review next steps
grep "Next Immediate Steps" .project/streams/controlnet-foundation/HANDOFF.md
```

### Create a New Stream
```bash
# 1. Copy templates
cp -r .project/templates .project/streams/new-stream-name

# 2. Edit README.md (overview, goals, architecture)
vim .project/streams/new-stream-name/README.md

# 3. Edit PLAN.md (phases and tasks)
vim .project/streams/new-stream-name/PLAN.md

# 4. Set status to Ready
vim .project/streams/new-stream-name/STATUS.md

# 5. Commit
git add .project/streams/new-stream-name
git commit -m "chore(project): create new-stream-name stream"
```

### Update Session Handoff
```bash
# At end of work session
vim .project/streams/current-stream/HANDOFF.md
vim .project/streams/current-stream/STATUS.md

git add .project/streams/current-stream
git commit -m "chore(project): update handoff for current-stream"
```

---

## Status Indicators

- 🟢 **Ready** - Can start work
- 🟡 **In Progress** - Active development
- 🔴 **Blocked** - Waiting on dependency
- ⏸️ **Paused** - Temporarily on hold
- ✅ **Complete** - Done and deployed

---

## File Purposes

| File | Purpose | Update Frequency |
|------|---------|------------------|
| README.md | Feature overview, architecture | Once (setup) |
| STATUS.md | Current progress, blockers | Daily |
| HANDOFF.md | Session context | End of each session |
| PLAN.md | Phases and tasks | Weekly or as needed |
| NOTES.md | Technical decisions | As decisions made |

---

## Key Principles

1. **Streams are planning** - No separate plan mode needed
2. **Git is truth** - All stream files checked into git
3. **No pollution** - All docs in `.project/`, not root
4. **Single source** - No duplication (README vs PLAN vs STATUS)
5. **Continuous context** - HANDOFF enables session transitions

---

## Common Workflows

### Starting a Work Session
```bash
# Read handoff from last session
cat .project/streams/current-stream/HANDOFF.md

# Check current status
cat .project/streams/current-stream/STATUS.md | head -20

# Start work...
```

### Ending a Work Session
```bash
# Update handoff
vim .project/streams/current-stream/HANDOFF.md
# - What was just completed
# - What's in progress
# - Next immediate steps

# Update status
vim .project/streams/current-stream/STATUS.md
# - Recent changes
# - Progress metrics

# Commit
git add .project/streams/current-stream
git commit -m "chore(project): update handoff for current-stream"
```

### Completing a Stream
```bash
# Mark complete
vim .project/streams/stream-name/STATUS.md
# Change status to ✅ Complete

# Create history entry
cp .project/templates/history_template.md \
   .project/history/20260114_stream-name.md

vim .project/history/20260114_stream-name.md
# Document what was built, impact, learnings

# Update history index
vim .project/history/README.md
# Add entry

# Commit
git add .project/
git commit -m "chore(project): complete stream-name stream"
```

---

## Need Help?

**Full Documentation**: `.project/README.md`
**Stream Overview**: `.project/STREAMS_OVERVIEW.md`
**Implementation Details**: `.project/IMPLEMENTATION_SUMMARY.md`
**Templates**: `.project/templates/`

---

**Quick Start Version**: 1.0
**Last Updated**: 2026-01-14