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

cat .project/STREAMS_OVERVIEW.md

Check Stream Status

cat .project/streams/controlnet-foundation/STATUS.md

Resume Work on a Stream

# 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

# 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

# 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

# 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

# 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

# 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