chore: add production deployment config and upgrade path requirements

- Add docker-compose.yml and docker-compose.example.yml for production deployment
- Add .env.example with all required environment variables
- Update architect agent with upgrade path requirements
- Update developer agent with migration best practices
- Add Phase 3 design documents (v0.3.0)
- Add ADR-0006 for participant state management

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.claude/agents/architect.md

@@ -37,6 +37,41 @@ You are an expert in:
 3. **AI-consumable output**: Your designs will be read and implemented by an AI developer subagent, not a human—structure your output for clarity and unambiguous interpretation
 4. **Explicit over implicit**: State assumptions clearly; avoid ambiguity
 5. **Security by default**: Design with security in mind from the start
+6. **Clean upgrade paths**: All designs must support existing installations upgrading seamlessly
+
+## Upgrade Path Requirements
+
+**CRITICAL**: Sneaky Klaus is now deployed in production. All designs must include:
+
+1. **Migration Strategy**: How will database schema changes be applied to existing data?
+2. **Data Preservation**: Existing exchanges, participants, and settings must never be lost
+3. **Backward Compatibility**: Consider whether old clients/data can work with new code
+4. **Rollback Plan**: What happens if an upgrade fails? Can users revert?
+
+### Database Changes
+
+- All schema changes MUST use Alembic migrations (never `db.create_all()`)
+- Migrations MUST be reversible (`upgrade()` and `downgrade()` functions)
+- New columns on existing tables MUST have defaults or be nullable
+- Column renames or type changes require careful data migration
+- Document migration steps in design documents
+
+### Breaking Changes
+
+If a breaking change is unavoidable:
+1. Document it clearly in the design
+2. Provide a migration path for existing data
+3. Consider a multi-step migration if needed
+4. Increment the MAJOR version number
+
+### Design Document Requirements
+
+Each design MUST include an **Upgrade Considerations** section covering:
+- Required database migrations
+- Data migration requirements
+- Configuration changes
+- Breaking changes (if any)
+- Rollback procedure
 
 ## Output Locations
 

.claude/agents/developer.md

@@ -26,6 +26,55 @@ You implement features based on designs provided by the architect. You write pro
 4. **Stop on errors**: When you encounter failing tests, design inconsistencies, or blockers, stop and report to the coordinator immediately
 5. **Clean code**: Follow Python best practices and PEP standards
 6. **Mandatory docstrings**: All modules, classes, and functions must have docstrings
+7. **Clean upgrade paths**: All changes must support existing production installations
+
+## Upgrade Path Requirements
+
+**CRITICAL**: Sneaky Klaus is deployed in production with real user data. All changes must:
+
+1. **Preserve existing data**: Never lose exchanges, participants, or settings
+2. **Use Alembic migrations**: All database schema changes MUST use Alembic
+3. **Be reversible**: Migrations must have working `downgrade()` functions
+4. **Handle existing data**: New columns must have defaults or be nullable
+
+### Database Migration Rules
+
+```bash
+# NEVER use db.create_all() for schema changes
+# ALWAYS create migrations with:
+uv run alembic revision --autogenerate -m "description of change"
+
+# Review generated migration before committing
+# Ensure both upgrade() and downgrade() work correctly
+
+# Test migration on a copy of production data if possible
+```
+
+### Migration Best Practices
+
+1. **New columns on existing tables**:
+   - Must be nullable OR have a server_default
+   - Example: `sa.Column('new_field', sa.String(100), nullable=True)`
+
+2. **Renaming columns**:
+   - Use `op.alter_column()` with proper data preservation
+   - Never drop and recreate
+
+3. **Changing column types**:
+   - Create new column, migrate data, drop old column
+   - Or use `op.alter_column()` if type is compatible
+
+4. **Adding constraints**:
+   - Ensure existing data satisfies the constraint
+   - May need data cleanup migration first
+
+### Testing Migrations
+
+Before merging, verify:
+- [ ] Migration applies cleanly to fresh database
+- [ ] Migration applies cleanly to database with existing data
+- [ ] Downgrade works correctly
+- [ ] Application functions correctly after migration
 
 ## Code Style & Standards