> ## Documentation Index
> Fetch the complete documentation index at: https://specs.flux.employinc.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Wave 3: Candidate

# Wave 3: Candidate

**Status**: IN PROGRESS
**Domain**: Candidate identity, portal, agent-native self-service, campaign engagement, and multi-channel communication (web, SMS, WhatsApp, email, iMessage).
**Owner**: @pj

***

## Scope

Wave 3 transforms the candidate from a passive data record into an engaged participant with their own AI agent persona. It encompasses:

* **Identity**: The person-level `candidates` model (distinct from per-job `applications`), person-level source tracking.
* **Portal**: Agent-native self-service web surface — candidates chat with the candidate agent, see status cards, handle scheduling / offers / documents through the conversational flow.
* **Campaign Domain**: A new bounded context (`domains/campaign/`) modeling engagement lifecycle with templates, instances, channel preferences, commitment rules, employer-defined branding.
* **Multi-Channel Adapters**: Web, SMS (Bird toll-free for pilot; A2P 10DLC post-pilot), WhatsApp (Bird WABA), email (Resend + React Email), iMessage (Apple Messages for Business).
* **Notification Backbone Integration**: Wire the unified backbone (PR #386) to external channels.
* **Transactional SMS Gateway** (pilot-specific): A lean notification adapter that ships before the full campaign domain, for the Paychex Pilot.

Wave 3 does not own candidate selection / matching (Wave 4) or hiring decisions (Wave 4). It owns the candidate's experience and their communication with the employer's agent.

***

## Cycles

| Cycle     | Title                                                   | Status                            | Milestone                               |
| --------- | ------------------------------------------------------- | --------------------------------- | --------------------------------------- |
| 217       | Candidate Identity Split                                | ✅ Merged (PR #285)                | M1 foundation                           |
| 217.5     | Autonomous Agent Architecture (shared with Wave 4)      | Plan merged                       | M4 / M5 prerequisite                    |
| 323       | Campaign Domain & Data Foundation                       | Draft                             | M5                                      |
| 323.1     | Candidate Agent — Tools, Specialists, Employer Branding | Draft                             | M5                                      |
| 323.2     | Channel Adapter Framework + SMS (full agent)            | Draft                             | M5                                      |
| 323.3     | WhatsApp + Email Channels                               | Draft                             | M5                                      |
| 323.4     | iMessage + Campaign Analytics                           | Draft                             | M5                                      |
| 323.5     | Candidate Portal — Agent-Native Self-Service            | Draft (supersedes deprecated 206) | **M1 floor**                            |
| 323.6     | Notification External Delivery + Digest                 | Draft                             | M1 email subset; full digest post-pilot |
| **323.7** | **Pilot Transactional SMS Gateway**                     | New (2026-04-17)                  | **M1 floor**                            |

### Cycle sequencing

* **217 → (323.5 + 323.7)** enables the Paychex Pilot candidate experience: candidate applies, gets email + SMS updates, logs into portal via magic link, chats with candidate agent skeleton on web.
* **217.5 → 323 → 323.1 → 323.2 → 323.3 → 323.4** is the post-pilot build-out of the full candidate agent platform (M5).
* **323.7 is superseded by 323.2** post-pilot; 323.7 is deliberately lean and forward-compatible.

***

## M1 Paychex Pilot Contribution

**Floor**:

* 217 (already merged)
* 323.5 Candidate Portal (agent-native, chat-dominant, magic-link auth, status cards)
* 323.6 email subset — React Email templates wired via Resend, transactional only (digest is post-pilot)
* 323.7 Pilot Transactional SMS Gateway (new cycle, Bird toll-free, 4 templates, STOP compliance, forward-compatible with 323.2)

**Stretch**: two-way SMS reply handling (STOP only is floor; richer replies are post-pilot).

**Explicitly out of pilot**:

* 323 Campaign Domain
* 323.1 Candidate Agent (full persona with specialists + 9 tools + branding)
* 323.2 full-agent SMS via channel adapter framework
* 323.3 WhatsApp + email-via-agent
* 323.4 iMessage
* 217.5 Autonomous Agent Architecture (lands when Match Agent begins — M4)

***

## Dependencies & Prerequisites

* Wave 0: notification backbone (PR #386 merged), SSE chat infrastructure, magic-link primitives from Cycle 206 design (carried forward into 323.5).
* Wave 5: Cycle 382.1 production cluster (for real email + SMS delivery); Cycle 301.1 observability for channel metrics.
* Cross-wave: Cycle 222 (workflow outbox) for event-driven campaign workflows in post-pilot 323.
* External provider approvals (governed by the milestone doc's Phase 1 long-lead checklist):
  * A2P 10DLC registration (2–6 weeks; toll-free fallback in pilot)
  * WhatsApp Business template approval (1–2 weeks; post-pilot)
  * Apple Business Register (2–4 weeks; post-pilot)
  * Resend domain authentication (1–3 days; in pilot Phase 1)

***

## Historical Context

Wave 3 was previously labeled "Wave 4: Candidate Agent Platform" (a release-sequenced name). In the 2026-04-17 domain-reorganization, it was renumbered to Wave 3 to reflect that the candidate domain is peer to the job-posting domain in product structure, not sequentially-later. Cycle 206 (the original traditional candidate portal) was deprecated and superseded by 323.5, which is designed agent-first from day one.

**Flagged numbering collision**: Wave 4's "Cycle 217 nginx ingress migration" (infrastructure) collides with Wave 3's Cycle 217 (candidate identity). Recommend aliasing the infra cycle; tracked as post-pilot cleanup.