# CI Agent — Project Plan

## What we're building

A Competitive Intelligence monitoring web application. Users register (or run in local single-user dev mode), add companies to monitor, describe what they care about, and choose a monitoring schedule. The system collects public information from multiple sources, stores historical snapshots, uses an LLM to analyze evidence into a structured report, detects meaningful changes between runs, scores them for severity and confidence, and notifies the user by email (and optionally SMS). Everything is viewable from a web dashboard.

## Build strategy

Given the size of the full specification, we are building in the phased order below. Each phase leaves the application in a runnable state. We start with the vertical slice explicitly called out in the spec (local auth → fixture company → baseline report → fixture change → alert → Mailpit email → dashboard) and expand outward from there.

1. **Foundation** — monorepo, Docker Compose, FastAPI + Next.js skeletons, health checks, lint/format/test scaffolding.
2. **Auth & Users** — local dev-mode auth and JWT auth behind one interface.
3. **Company Management** — CRUD, monitoring configuration, dashboard, add-company wizard.
4. **Collection Pipeline** — collector interface, SSRF-safe fetching, website/RSS/custom-URL/SEC EDGAR/GitHub collectors, extraction & normalization.
5. **Background Processing** — Celery + Beat, dynamic per-company schedules, run-now, retries.
6. **Change Detection** — layered hash/structured/text/semantic diffing, significance scoring, severity classification.
7. **LLM Analysis** — provider-agnostic interface (Mock/Anthropic/Ollama), six discrete analysis tasks, evidence-linked reports.
8. **Notifications** — SMTP/Mailpit, Console, Twilio SMS, delivery tracking.
9. **Fixture Demo + Tests** — Acme Mobility Systems fixture company (v1/v2), full automated test suite, Playwright E2E.
10. **Hardening & Docs** — rate limiting, structured logging, retention, security review, Firebase migration doc.

## Non-goals for this pass

- Live scraping of sources with no reliable free public API (patents, customer reviews, most job boards) — these get a real interface + documented fixture adapter instead of a fabricated live integration, per the spec's own guidance.
- Payment/billing, multi-tenant admin console, OAuth social login — not in the spec's MVP.
- PDF export — documented as a later enhancement (Markdown/JSON export are implemented).

See `TASKS.md` for the live checklist, `ARCHITECTURE.md` for system design, `SECURITY.md` for the threat model, and `KNOWN_LIMITATIONS.md` for what's stubbed vs. fully live.