# Backend Schemas Restructure Implementation Plan

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

**Goal:** Hard-cut refactor backend schema modules into clear domain/shared/enums boundaries while keeping API contracts in `v1/*/schemas.py`.

**Architecture:** Introduce `schemas/enums.py` and move reusable schema models into `schemas/domain` and `schemas/shared`. Update all backend imports to explicit new module paths and remove old schema package wrappers and duplicate directories.

**Tech Stack:** Python 3.13, Pydantic v2, Ruff, Pytest, Alembic migration runner.

---

### Task 1: Create new schema module layout

**Files:**
- Create: `backend/src/schemas/enums.py`
- Create: `backend/src/schemas/domain/automation.py`
- Create: `backend/src/schemas/domain/inbox.py`
- Create: `backend/src/schemas/domain/schedule.py`
- Create: `backend/src/schemas/domain/memory.py`
- Create: `backend/src/schemas/domain/memory_content.py`
- Create: `backend/src/schemas/domain/chat_message.py`
- Create: `backend/src/schemas/domain/chat_session.py`
- Create: `backend/src/schemas/domain/todo.py`
- Create: `backend/src/schemas/domain/invite_code.py`
- Create: `backend/src/schemas/shared/user.py`

**Step 1: Write failing import checks**

```python
def test_new_schema_paths_importable() -> None:
    import schemas.domain.automation  # noqa: F401
```

**Step 2: Run test to verify it fails**

Run: `uv run pytest backend/tests/unit -k new_schema_paths_importable -v`
Expected: FAIL with import error

**Step 3: Implement new modules**

Copy and normalize existing reusable models into new modules.

**Step 4: Run test to verify it passes**

Run: `uv run pytest backend/tests/unit -k new_schema_paths_importable -v`
Expected: PASS

### Task 2: Update all backend imports to new schema paths

**Files:**
- Modify: `backend/src/**/*.py` (affected import lines)

**Step 1: Write failing grep assertions**

Run: `uv run python -c "..."` with assertions for old import patterns.

**Step 2: Verify failures with old paths present**

Run: `uv run ruff check backend/src`

**Step 3: Implement import rewrites**

Replace old paths (`schemas.model_enums`, `schemas.automation`, `schemas.memories.memory_content`, etc.) with new explicit modules.

**Step 4: Verify static checks pass**

Run: `uv run ruff check backend/src`
Expected: PASS

### Task 3: Remove legacy schema wrappers and duplicates

**Files:**
- Delete: `backend/src/schemas/model_enums.py`
- Delete: `backend/src/schemas/automation/__init__.py`
- Delete: `backend/src/schemas/inbox/messages.py`
- Delete: `backend/src/schemas/schedule/items.py`
- Delete: `backend/src/schemas/memories/__init__.py`
- Delete: `backend/src/schemas/memories/memory_content.py`
- Delete: `backend/src/schemas/messages/chat_message.py`
- Delete: `backend/src/schemas/messages/__init__.py`
- Delete: `backend/src/schemas/sessions/chat_session.py`
- Delete: `backend/src/schemas/sessions/__init__.py`
- Delete: `backend/src/schemas/todo/contracts.py`
- Delete: `backend/src/schemas/todo/__init__.py`
- Delete: `backend/src/schemas/user/context.py`
- Delete: `backend/src/schemas/user/__init__.py`
- Delete: `backend/src/schemas/inbox/__init__.py`
- Delete: `backend/src/schemas/invite_codes/__init__.py`
- Modify: `backend/src/schemas/__init__.py`

**Step 1: Remove old modules**

Delete legacy wrappers after all imports are rewritten.

**Step 2: Verify no old imports remain**

Run: `uv run python -c "..."` or grep-based assertion commands.
Expected: zero matches

### Task 4: Verification and migration

**Files:**
- Verify only

**Step 1: Run quality gates**

Run: `uv run ruff check backend/src`

**Step 2: Run impacted tests**

Run: `uv run pytest backend/tests/unit/v1/automation_jobs backend/tests/unit/v1/schedule_items backend/tests/unit/v1/todo backend/tests/unit/v1/friendships backend/tests/unit/v1/inbox_messages backend/tests/unit/v1/users backend/tests/unit/v1/agent backend/tests/unit/core/agentscope`

**Step 3: Run migration script**

Run: `./infra/scripts/dev-migrate.sh migrate`

**Step 4: Commit**

```bash
git add backend/src/schemas backend/src/v1 backend/src/models backend/src/core docs/plans
git commit -m "refactor: restructure backend schema modules by domain boundaries"
```