imajin/.project/README.md

Imajin Project Management

Purpose: Feature-based workstream organization for the imajin AI image generation pipeline.

Philosophy: Streams provide continuous context across sessions. No plan mode pollution, no root-level summaries.

---

Directory Structure

.project/
├── README.md              # This file - project management guide
├── streams/               # Active feature workstreams
│   ├── <stream-name>/    # Individual stream directory
│   │   ├── README.md      # Feature overview and architecture
│   │   ├── STATUS.md      # Current progress and blockers
│   │   ├── HANDOFF.md     # Session handoff context
│   │   ├── PLAN.md        # Implementation phases and tasks
│   │   └── NOTES.md       # Technical decisions and learnings
├── history/               # Completed work records
│   ├── YYYYMMDD_description.md
│   └── README.md          # History index
└── templates/             # Stream templates
    ├── README.md          # Template for feature overview
    ├── STATUS.md          # Template for status tracking
    ├── HANDOFF.md         # Template for handoff context
    ├── PLAN.md            # Template for planning
    └── NOTES.md           # Template for notes

---

Stream Management

When to Create a Stream

Create a new stream when:

• New major feature requiring multiple sessions (e.g., ControlNet integration)
• Significant architectural change (e.g., multi-ControlNet support)
• Cross-service integration (e.g., person appearance API)
• Complex technical challenge (e.g., anatomy enhancement)

DO NOT create streams for:

• Bug fixes (use git commits)
• Minor tweaks (use git commits)
• One-off tasks (use git commits)
• Documentation updates (use git commits)

Stream Lifecycle

1. Create Stream

# Copy templates
cp -r .project/templates .project/streams/new-feature-name
cd .project/streams/new-feature-name

# Fill out README.md (overview, goals, architecture)
# Fill out PLAN.md (phases, tasks, dependencies)
# Set STATUS.md to 🟢 Ready

2. Active Development

• Update STATUS.md at end of each session (🟡 In Progress)
• Update HANDOFF.md when switching contexts
• Add technical decisions to NOTES.md
• Update PLAN.md as implementation evolves

3. Session Handoffs

When pausing work:

1. Update STATUS.md with current state
2. Update HANDOFF.md with:
   • What was just completed
   • What's in progress
   • Next immediate steps
   • Any blockers or context needed
3. Commit changes to git

When resuming work:

1. Read HANDOFF.md for context
2. Check STATUS.md for blockers
3. Review PLAN.md for next tasks

4. Complete Stream

When feature is production-ready:

1. Set STATUS.md to ✅ Complete
2. Create history entry: .project/history/YYYYMMDD_stream-name_complete.md
3. Archive or move stream to streams/_archived/ (optional)

Status Indicators

Use in STATUS.md for clear visibility:

• 🟢 Ready - Planning complete, ready to start
• 🟡 In Progress - Active development
• 🔴 Blocked - Waiting on dependency, decision, or external work
• ⏸️ Paused - Temporarily deprioritized
• ✅ Complete - Feature deployed and verified

---

History Management

What to Record

Record in .project/history/:

• Stream completions (major features shipped)
• Significant architectural decisions
• Production deployments
• Major refactorings

DO NOT record:

• Daily summaries (streams track ongoing work)
• Routine commits (git history is sufficient)
• Agent summaries (cleanup protocol prevents pollution)
• Temporary documentation (use streams instead)

History Format

Filename: YYYYMMDD_description.md

Content:

# Feature Name - Completion Summary

**Date**: YYYY-MM-DD
**Stream**: stream-name
**Status**: ✅ Complete

## What Was Built
- Key components
- Files changed
- Tests added

## Technical Decisions
- Why approach X over Y
- Trade-offs considered

## Impact
- What this enables
- Performance improvements
- Next steps unlocked

## References
- Commits: abc123, def456
- Related streams: other-feature

---

Stream Naming Conventions

Use kebab-case, descriptive names:

Good:

• controlnet-foundation (clear scope)
• person-appearance-api (describes intent)
• segmentation-clothing (specific feature)
• multi-controlnet (technical capability)

Bad:

• phase1 (no context)
• integration (too vague)
• new-feature (meaningless)
• CONTROLNET (wrong case)

---

Relationship to Plan Mode

Key Principle: Streams ARE the planning system.

When to use streams (always):

• Feature development
• Architecture changes
• Multi-session work
• Complex integrations

When to use plan mode (NEVER for stream work):

• Streams provide README.md, STATUS.md, PLAN.md, HANDOFF.md
• Plan mode creates ~/.claude/plans/ files (pollution)
• Plan mode duplicates stream context
• Plan mode not shared across sessions via git

Self-check: If ~/.claude/plans/ exists during stream work, investigate why.

---

Stream Templates

Templates are in .project/templates/. Copy entire directory when creating new stream.

README.md Template

• Feature overview
• Goals and non-goals
• Architecture diagram (mermaid)
• Service dependencies
• API contracts

STATUS.md Template

• Current status indicator (🟢🟡🔴⏸️✅)
• Completed phases
• Current phase
• Blockers
• Next immediate steps

HANDOFF.md Template

• Last updated timestamp
• What was just completed
• What's in progress
• Next immediate steps
• Blockers/context for next session

PLAN.md Template

• Phases (Phase 1, 2, 3...)
• Tasks per phase (with checkboxes)
• Dependencies
• Estimates (optional)

NOTES.md Template

• Technical decisions
• Why approach X over Y
• Learnings and gotchas
• Performance observations
• Future considerations

---

Cross-Stream Dependencies

When streams depend on each other:

1. Document in README.md:

   ## Dependencies
   - Requires: `controlnet-foundation` (Phase 1 complete)
   - Blocks: `anatomy-enhancement` (needs person appearance API)
   

2. Reference in PLAN.md:

   ### Phase 1 - Foundation
   - [ ] Wait for `controlnet-foundation` completion
   - [ ] Design PersonAppearance API
   

3. Update STATUS.md when unblocked:

   ## Blockers
   ~~Waiting on controlnet-foundation completion~~ ✅ Unblocked 2026-01-14
   

---

Current Active Streams

See .project/streams/ for all streams.

As of 2026-01-14:

• controlnet-foundation - ✅ Complete (Phase 1)
• person-appearance-api - 🟡 In Progress (Phase 2-3)
• segmentation-clothing - 🟡 In Progress (Template-based complete)
• multi-controlnet - 🟢 Ready (waiting on foundation)
• anatomy-enhancement - 🟢 Ready (hybrid approach)

---

Anti-Patterns to Avoid

DO NOT:

• Create root-level *_SUMMARY.md, *_REPORT.md, *_MERGE_SUMMARY.md
• Create documentation in services/, orchestrators/, or source directories
• Use ~/.claude/plans/ for stream work (EnterPlanMode)
• Create streams for bug fixes or minor changes
• Let streams become stale (update or archive)
• Duplicate content between README, PLAN, STATUS (single source of truth)

DO:

• Keep streams updated throughout development
• Archive completed streams (move to streams/_archived/)
• Record major completions in .project/history/
• Reference git commits for detailed changes
• Use HANDOFF.md for clean session transitions

---

Quick Reference Commands

# Create new stream
cp -r .project/templates .project/streams/new-stream-name

# Update current stream status
vim .project/streams/current-stream/STATUS.md

# Record session handoff
vim .project/streams/current-stream/HANDOFF.md
git add .project/streams/current-stream/HANDOFF.md
git commit -m "chore(project): update handoff for current-stream"

# Complete stream
mv .project/streams/stream-name .project/streams/_archived/
echo "# Stream Name Complete" > .project/history/20260114_stream-name.md
git add .project/history/20260114_stream-name.md
git commit -m "chore(project): complete stream-name stream"

# List active streams
ls .project/streams/

# View stream status
cat .project/streams/*/STATUS.md | grep -E "^##|🟢|🟡|🔴|✅"

---

Last Updated: 2026-01-14 Maintainers: The Collective Philosophy: Streams provide shared context. History provides memory. Git provides truth.