## Phase 0: Submodule Infrastructure (Create Directories + __init__.py Files)

- [ ] 0.1 Create `apps/api/src/schemas/tool/__init__.py`
- [ ] 0.2 Create `apps/api/src/schemas/config/__init__.py`
- [ ] 0.3 Create `apps/api/src/schemas/user/__init__.py`
- [ ] 0.4 Create `apps/api/src/schemas/project/__init__.py`
- [ ] 0.5 Create `apps/api/src/schemas/system/__init__.py`
- [ ] 0.6 Create `apps/api/src/api/tool/__init__.py`
- [ ] 0.7 Create `apps/api/src/api/config/__init__.py`
- [ ] 0.8 Create `apps/api/src/api/workspace/__init__.py`
- [ ] 0.9 Create `apps/api/src/api/user/__init__.py`
- [ ] 0.10 Create `apps/api/src/api/project/__init__.py`
- [ ] 0.11 Create `apps/api/src/api/system/__init__.py`
- [ ] 0.12 Create `apps/api/src/services/instance/__init__.py`
- [ ] 0.13 Create `apps/api/src/services/config/__init__.py`
- [ ] 0.14 Create `apps/api/src/services/git/__init__.py`
- [ ] 0.15 Create `apps/api/src/services/build/__init__.py`
- [ ] 0.16 Create `apps/api/src/services/terminal/__init__.py`
- [ ] 0.17 Create `apps/api/src/services/shared/__init__.py`
- [ ] 0.18 Create `apps/api/src/models/tool/__init__.py`
- [ ] 0.19 Create `apps/api/src/models/config/__init__.py`
- [ ] 0.20 Create `apps/api/src/models/user/__init__.py`
- [ ] 0.21 Create `apps/api/src/models/project/__init__.py`
- [ ] 0.22 Create `apps/api/src/models/system/__init__.py`

## Phase 1: Model Subpackages

- [ ] 1.1 Move `models/tool_type.py` → `models/tool/tool_type.py`
- [ ] 1.2 Move `models/tool_instance.py` → `models/tool/tool_instance.py`
- [ ] 1.3 Move `models/tool_definition_manifest.py` → `models/tool/tool_definition_manifest.py`
- [ ] 1.4 Move `models/config_profile.py` → `models/config/config_profile.py`
- [ ] 1.5 Move `models/config_include.py` (if exists) → `models/config/config_include.py`
- [ ] 1.6 Move `models/config_mount.py` (if exists) → `models/config/config_mount.py`
- [ ] 1.7 Move `models/user.py` → `models/user/user.py`
- [ ] 1.8 Move `models/user_config.py` → `models/user/user_config.py`
- [ ] 1.9 Move `models/ssh_key.py` → `models/user/ssh_key.py`
- [ ] 1.10 Move `models/project.py` → `models/project/project.py`
- [ ] 1.11 Move `models/git_repository.py` → `models/project/git_repository.py`
- [ ] 1.12 Move `models/workspace.py` → `models/project/workspace.py`
- [ ] 1.13 Move `models/health_check.py` → `models/system/health_check.py`
- [ ] 1.14 Move `models/notification.py` → `models/system/notification.py`
- [ ] 1.15 Move `models/instance_event.py` → `models/system/instance_event.py`
- [ ] 1.16 Move `models/terminal_session.py` → `models/system/terminal_session.py`
- [ ] 1.17 Update `models/__init__.py` to import from subpackages
- [ ] 1.18 Update all backend imports to use `models.tool.tool_type` etc.
- [ ] 1.19 Verify `py_compile` and `ruff` pass

## Phase 2: Schema Extraction + Subpackages

- [ ] 2.1 Extract `schemas/tool/tool_type.py` from `api/tool_types.py`
- [ ] 2.2 Extract `schemas/tool/tool_instance.py` from `api/tool_instances.py`
- [ ] 2.3 Extract `schemas/config/config_profile.py` from `api/config_profiles.py`
- [ ] 2.4 Extract `schemas/system/health.py` from `api/health.py`
- [ ] 2.5 Extract `schemas/user/user.py` from `api/users.py`
- [ ] 2.6 Extract `schemas/user/user_config.py` from `api/user_config.py`
- [ ] 2.7 Extract `schemas/project/project.py` from `api/projects.py`
- [ ] 2.8 Extract `schemas/project/ssh_key.py` from `api/ssh_keys.py`
- [ ] 2.9 Extract `schemas/project/git_repository.py` from `api/git_repositories.py`
- [ ] 2.10 Update all API routers to import schemas from `src.schemas.*`
- [ ] 2.11 Verify `py_compile` and `ruff` pass

## Phase 3: Docker Service Package Split

- [ ] 3.1 Create `services/docker/__init__.py` with re-exports
- [ ] 3.2 Create `services/docker/compose.py` from `services/docker.py`
- [ ] 3.3 Create `services/docker/container.py` from `services/docker.py`
- [ ] 3.4 Create `services/docker/config_staging.py` from `services/docker.py`
- [ ] 3.5 Create `services/docker/tunnel.py` from `services/tunnel.py`
- [ ] 3.6 Remove `services/docker.py` after verifying imports
- [ ] 3.7 Update `services/tunnel.py` or remove if subsumed
- [ ] 3.8 Update all consumers to import from `services.docker`
- [ ] 3.9 Verify `py_compile` and `ruff` pass

## Phase 4: Service Subpackages

- [ ] 4.1 Move `services/lifecycle_hooks.py` → `services/instance/lifecycle_hooks.py`
- [ ] 4.2 Move `services/health_monitor.py` → `services/instance/health_monitor.py`
- [ ] 4.3 Move `services/event_bus.py` → `services/instance/event_bus.py`
- [ ] 4.4 Move `services/config_profile_resolver.py` → `services/config/config_profile_resolver.py`
- [ ] 4.5 Move `services/clone.py` → `services/git/clone.py`
- [ ] 4.6 Move `services/git_operations.py` → `services/git/git_operations.py`
- [ ] 4.7 Move `services/git_service.py` → `services/git/git_service.py`
- [ ] 4.8 Move `services/docker_build.py` → `services/build/docker_build.py`
- [ ] 4.9 Move `services/manifest_compiler.py` → `services/build/manifest_compiler.py`
- [ ] 4.10 Move `services/terminal_manager.py` → `services/terminal/terminal_manager.py`
- [ ] 4.11 Move `services/terminal_session.py` → `services/terminal/terminal_session.py`
- [ ] 4.12 Move `services/tunnel.py` → `services/shared/tunnel.py`
- [ ] 4.13 Move `services/notification_service.py` → `services/shared/notification_service.py`
- [ ] 4.14 Move `services/file_service.py` → `services/shared/file_service.py`
- [ ] 4.15 Move `services/permission_fixer.py` → `services/shared/permission_fixer.py`
- [ ] 4.16 Move `services/readiness_probe.py` → `services/shared/readiness_probe.py`
- [ ] 4.17 Move `services/ssh_keys.py` → `services/shared/ssh_keys.py`
- [ ] 4.18 Move `services/workspace_manager.py` → `services/shared/workspace_manager.py`
- [ ] 4.19 Move `services/correlation.py` → `services/shared/correlation.py`
- [ ] 4.20 Extract `services/instance/instance_lifecycle.py` from `api/tool_instances.py`
- [ ] 4.21 Extract `services/config/config_profiles.py` from `api/config_profiles.py`
- [ ] 4.22 Update all imports across the backend
- [ ] 4.23 Verify `py_compile` and `ruff` pass

## Phase 5: API Router Subpackages

- [ ] 5.1 Move `api/tool_instances.py` → `api/tool/tool_instances.py`
- [ ] 5.2 Move `api/tool_types.py` → `api/tool/tool_types.py`
- [ ] 5.3 Move `api/tool_definitions.py` → `api/tool/tool_definitions.py`
- [ ] 5.4 Move `api/tool_types_validation.py` → `api/tool/tool_types_validation.py`
- [ ] 5.5 Move sessions_router from `api/tool_instances.py` → `api/tool/sessions.py`
- [ ] 5.6 Move `api/config_profiles.py` → `api/config/config_profiles.py`
- [ ] 5.7 Move `api/user_config.py` → `api/config/user_config.py`
- [ ] 5.8 Move `api/workspaces.py` → `api/workspace/workspaces.py`
- [ ] 5.9 Move `api/workspace_files.py` → `api/workspace/workspace_files.py`
- [ ] 5.10 Move `api/workspace_git.py` → `api/workspace/workspace_git.py`
- [ ] 5.11 Move `api/workspace_instances.py` → `api/workspace/workspace_instances.py`
- [ ] 5.12 Move `api/users.py` → `api/user/users.py`
- [ ] 5.13 Move `api/auth.py` → `api/user/auth.py`
- [ ] 5.14 Move `api/ssh_keys.py` → `api/user/ssh_keys.py`
- [ ] 5.15 Move `api/projects.py` → `api/project/projects.py`
- [ ] 5.16 Move `api/git_repositories.py` → `api/project/git_repositories.py`
- [ ] 5.17 Move `api/health.py` → `api/system/health.py`
- [ ] 5.18 Move `api/events.py` → `api/system/events.py`
- [ ] 5.19 Move `api/notifications.py` → `api/system/notifications.py`
- [ ] 5.20 Move `api/dashboard.py` → `api/system/dashboard.py`
- [ ] 5.21 Move `api/terminal.py` → `api/system/terminal.py`
- [ ] 5.22 Move `api/instance_proxy.py` → `api/system/instance_proxy.py`
- [ ] 5.23 Update `main.py` to import from subpackages
- [ ] 5.24 Update all cross-router imports
- [ ] 5.25 Verify `py_compile` and `ruff` pass

## Phase 6: Auth Dependency Refactor

- [ ] 6.1 Add `get_current_user` to `auth/dependencies.py`
- [ ] 6.2 Migrate `api/user/users.py` to use `get_current_user`
- [ ] 6.3 Migrate `api/tool/sessions.py` to use `get_current_user`
- [ ] 6.4 Migrate other routers incrementally
- [ ] 6.5 Verify `py_compile` and `ruff` pass

## Phase 7: Frontend Reorganization

- [ ] 7.1 Rename API files to kebab-case
- [ ] 7.2 Rename page files to `*Page.tsx`
- [ ] 7.3 Move components into `features/` directories
- [ ] 7.4 Update `router.tsx`
- [ ] 7.5 Verify `npm run typecheck` passes
- [ ] 7.6 Verify `npm run build` passes

## Phase 8: Integration and Verification

- [ ] 8.1 Run backend tests: `docker exec hq-api pytest`
- [ ] 8.2 Run backend lint: `ruff check`
- [ ] 8.3 Run frontend typecheck: `npm run typecheck`
- [ ] 8.4 Run frontend build: `npm run build`
- [ ] 8.5 Run `docker compose up --build` and verify API starts
- [ ] 8.6 Verify key user flows manually
- [ ] 8.7 Verify no 404s or import errors in browser console

## Phase 9: Documentation

- [ ] 9.1 Update `AGENTS.md` with new module structure
- [ ] 9.2 Document `get_current_user` vs `get_current_user_id` pattern