feat: add parallel 4-agent MVP implementation plan

[Paddy1981]

Introduces accelerated 4-week MVP delivery using 4 parallel Claude agents:

Agent ALPHA (Detection Engine):

• Transit detection, BLS, phase folding, vetting
• Branch: claude/mvp-alpha-detection
• Files: src/detection/, src/skills/

Agent BETA (Backend API):

• FastAPI, PostgreSQL, Redis job queue
• Branch: claude/mvp-beta-backend
• Files: src/api/, alembic/

Agent GAMMA (Frontend UI):

• Next.js, Tailwind, Plotly visualizations
• Branch: claude/mvp-gamma-frontend
• Files: web/

Agent DELTA (Platform/DevOps):

• Docker, NextAuth, Stripe, CI/CD
• Branch: claude/mvp-delta-platform
• Files: docker/, infrastructure/

Includes:

• Detailed interface contracts between agents
• Weekly sprint plans with daily tasks
• Coordination templates (STATUS, INTERFACES, WORKLOGS)
• File ownership matrix to prevent conflicts
• Handoff and blocking communication protocols

https://claude.ai/code/session_011NWj4qHMpnJqseDYB5et8R

Summary

Type of Change

• Bug fix (non-breaking change fixing an issue)
• New feature (non-breaking change adding functionality)
• Breaking change (fix or feature causing existing functionality to change)
• Documentation update
• Refactoring (no functional changes)
• CI/CD changes

Related Issues

Changes Made

Testing

• Unit tests added/updated
• Manual testing performed
• All existing tests pass

Skill Updates (if applicable)

• ANAL-xxx:
• STAR-xxx:
• MISSION-xxx:
• DISC-xxx:
• RES-xxx:

Multi-IDE Coordination

• Updated .coordination/TASK_LOG.md
• Checked .coordination/FILE_LOCKS.md for conflicts
• Updated .coordination/HANDOFF_NOTES.md if needed

Checklist

• Code follows project style guidelines
• Self-review completed
• Comments added for complex logic
• Documentation updated (if needed)
• No new warnings introduced

In general, to fix an unused local variable you either (a) remove the variable and any assignment to it when it has no side effects, or (b) if the variable is intentionally unused (for documentation or future use), rename it to a pattern like _ or unused_<name> so tools recognize it as deliberately unused.

Here, the variable vetting is initialized to None and never used. The right-hand side (None) has no side effects, so we can safely remove the assignment line without changing functionality. The if data.get("vetting"): block already contains only a pass, so the method’s behavior is unchanged whether or not we keep the vetting variable. The best minimal fix is to delete the line vetting = None (line 372) from DetectionResult.from_dict in src/detection/models.py. No imports or additional methods are required.

To fix this, we should avoid importing User from src.api.models.user in this module, even under TYPE_CHECKING, and instead use a forward reference string in the type annotation for any attribute that refers to User. Python’s typing allows annotations like "User" (a string) without requiring the class to be imported, which completely breaks the cycle at the typing level and removes the need for the problematic import.

Concretely, in src/api/models/analysis.py:

1. Remove the if TYPE_CHECKING: block that imports User.
2. Wherever User is referenced in type annotations (most likely on a relationship attribute such as user: Mapped["User"] = relationship(...)), ensure the annotation uses a string "User" instead of the symbol User. Using a string literal does not require the import and is understood by type checkers and modern Python runtimes.

This preserves all existing functionality: SQLAlchemy relationship() continues to work because it normally takes string targets like "User" or resolves relationships by table/foreign key; type checkers still understand the "User" forward reference without needing the actual import. No runtime behavior changes, and the cyclic import is broken.

In general, to fix module-level cyclic imports in Python models, you either (1) move shared definitions into a third module, or (2) avoid importing the other model at module import time and instead use forward references (string annotations) or local imports inside functions/methods. Here, User is only needed for type checking, not for actual runtime behavior, because SQLAlchemy relationships can be declared by the target table name or via string class names.

The best minimal fix that preserves functionality is:

• Remove the TYPE_CHECKING import and the guarded from src.api.models.user import User block from subscription.py.
• Rely on string-based type hints where a User type is needed (in this snippet, there is no explicit annotation referencing User; relationships usually use a string name like "User" in the relationship() call, which does not require importing the class). This completely eliminates the cyclic import path without altering runtime semantics.

Concretely:

• In src/api/models/subscription.py, delete TYPE_CHECKING from typing imports.
• Remove the if TYPE_CHECKING: block that imports User.
  No other code in the shown snippet depends on a direct User symbol, so no further changes are necessary.

In general, cyclic imports between models should be avoided by relying on forward references in type annotations and SQLAlchemy’s string-based relationship targets, rather than importing peer model classes at module level (or even under TYPE_CHECKING if tools complain). A robust pattern is to turn on postponed evaluation of annotations (from __future__ import annotations) and then refer to related models by their name as a plain string type annotation, without needing any import solely for typing.

For this file, the single best change that preserves all existing functionality and relationships is:

1. Add from __future__ import annotations at the very top of src/api/models/user.py so type annotations are treated as strings and evaluated later.
2. Remove the if TYPE_CHECKING: block that imports Analysis and Subscription, since they are only used for type hints and SQLAlchemy already uses string relationship targets ("Analysis", "Subscription").
3. Leave the relationship definitions as-is (Mapped[List["Analysis"]] and Mapped[Optional["Subscription"]]); with postponed evaluation, the quotes are optional but still valid. No runtime behavior or database schema changes.

This eliminates the type-time cyclic import while keeping type hints and SQLAlchemy relationships functional.

---

In general, to fix “variable defined multiple times” where the first assignment is unused, remove the redundant first assignment, ensuring that any side effects in its expression are preserved if needed. Here, the first assignment to sort_idx on line 73 is redundant because the variable is reassigned on line 76 before any use, and both assignments are simple np.argsort calls with no side effects beyond computing the array.

The best minimal fix is to delete the line sort_idx = np.argsort(((time - t0) % period) / period) and keep the later logic that builds phase_for_sort, adjusts it, and then computes sort_idx = np.argsort(phase_for_sort). This preserves the existing functionality—flux_err_sorted is still sorted consistently with phase/flux_sorted—and removes the dead assignment. No imports, new methods, or additional definitions are required; we only remove a single unused assignment within the fold method in src/detection/phase_folder.py.

To fix the problem, we should remove the unused Optional symbol from the import statement while keeping Annotated, which is actively used in the route function signatures. This avoids changing any runtime logic or public interfaces and only cleans up the type-related import.

Concretely, in src/api/routes/user.py, on the line from typing import Annotated, Optional, remove Optional so the line imports only Annotated. No other code changes are necessary, and no new imports or definitions are required.

To fix the problem, remove the unused import of datetime from this module. This eliminates an unnecessary dependency and resolves the CodeQL warning without altering runtime behavior.

Concretely, in src/api/routes/user.py, delete the line from datetime import datetime (line 9 in your snippet). No additional methods, imports, or definitions are needed because nothing in this file uses datetime. All other code remains unchanged.

To fix an unused import, remove the unused symbol from the import statement while leaving any still-used symbols intact. This reduces unnecessary dependencies and makes the file clearer.

In this file, we should edit the import on line 18 to drop SubscriptionPlan but keep Subscription and SubscriptionStatus unchanged. The rest of the file’s behavior is unaffected, since SubscriptionPlan is not referenced in the shown code. Concretely, in src/api/routes/subscription.py, update the from src.api.models.subscription import ... line so it only imports Subscription and SubscriptionStatus.

In general, unused imports should be removed to avoid unnecessary dependencies and to keep the code clear. Here, the problem is that the combined import from datetime import datetime, timedelta includes timedelta, which is not used anywhere in the file.

The best fix without changing any existing functionality is to modify that import line so that it only imports what is actually used. Since only timedelta is reported as unused, we should remove it and keep datetime. Concretely, in src/api/routes/auth.py, update line 9 from from datetime import datetime, timedelta to from datetime import datetime. No additional methods, imports, or definitions are needed beyond this one-line edit.

To fix an unused import, remove only the unused symbol from the import statement (or delete the entire import if none of its names are used), ensuring that all still-used symbols remain imported. This reduces unnecessary dependencies and slightly improves readability.

In this file, the import line from sqlalchemy import String, DateTime, Float, Integer, Text, ForeignKey, JSON, func should be edited to remove Integer while keeping all other imports intact. No other code changes or new definitions are required, and existing functionality will remain unchanged as long as Integer truly is not used elsewhere in this module.

Specifically, in src/api/models/analysis.py, edit line 13 so that Integer is no longer listed among the imported names from sqlalchemy. All other lines can remain as they are.