# Build Roadmap

> **STATUS (2026-07-07): all 8 phases shipped.** Phases 0–7 below are complete
> and the platform is **built and LIVE**; the later channel-agnostic refactor
> (waves 0–4) is deployed too. This is the **original build plan, kept as
> history** — for current state read [`HANDOFF.md`](../HANDOFF.md). (The "Docker"
> listed as a Phase-0 outcome was later replaced by native PM2 + systemd.)

> The phased plan for building the WhatApp Inhouse platform. Phase 0 has a
> complete, ready-to-execute plan ([phase-0-scaffold.md](phase-0-scaffold.md)).
> Phases 1–7 are expanded into their own plans by Claude Code, one at a time, as
> it reaches them — see "Per-phase process" below.

## Phases

| Phase | Name | Spec(s) | Outcome |
|---|---|---|---|
| 0 | Scaffold | [08](../specs/08-admin-auth.md) (auth skeleton) | The monorepo, database schema, shared clients, app skeletons, auth, Docker, CI — a running but featureless platform |
| 1 | Meta Gateway | [01](../specs/01-meta-gateway.md) | Webhook ingestion + the unified send service, live on the fresh number. The spine. |
| 2 | Contacts & Inbox | [02](../specs/02-contacts.md), [03](../specs/03-inbox.md) | Contact directory, consent, segments, and the investigative conversation viewer |
| 3 | Templates | [04](../specs/04-templates.md) | Template authoring, Meta submission, status/quality sync |
| 4 | Campaigns | [05](../specs/05-campaigns.md) | Rate-limited broadcasts with per-recipient tracking — **AiSensy outbound replaced** |
| 5 | Automation | [06](../specs/06-automation.md) | n8n integration; the reminder engine; migration of the 13 existing workflows |
| 6 | Quality & Analytics | [07](../specs/07-quality-analytics.md) | Quality monitoring, analytics dashboards, alerting |
| 7 | Cutover | — | Verify parity, switch off AiSensy, decommission |

Phases are sequential — each depends on the ones before it. Phase 8 of the spec
set, Admin & Auth, is started in Phase 0 and finished incrementally: each later
phase adds the settings screens it needs.

## Per-phase process

Phase 0 is executed directly from its plan. For **every phase from 1 onward**,
Claude Code performs this loop (see `../CLAUDE.md` for the authoritative
instructions):

1. **Read** the phase's spec(s) in `../specs/`, plus `../docs/design.md`,
   `../docs/data-model.md`, and `../docs/integrations.md`.
2. **Plan** — invoke the `superpowers:writing-plans` skill to expand the phase
   into a bite-sized, test-driven implementation plan saved as
   `plans/phase-N-<name>.md`. The plan must cover every functional requirement
   and acceptance criterion in the spec.
3. **Review** the generated plan against the spec (the writing-plans self-review:
   spec coverage, no placeholders, type consistency).
4. **Execute** the plan with `superpowers:subagent-driven-development` (preferred)
   or `superpowers:executing-plans` — task by task, test-first, committing
   frequently.
5. **Verify** — every acceptance criterion in the spec passes. Use
   `superpowers:verification-before-completion`: run the checks, confirm the
   output, then claim done.
6. **Commit & continue** to the next phase.

This is what makes the foundation "execute until ready": the process is encoded,
so a single Claude Code run can carry the build from Phase 0 to cutover.

## Definition of done (per phase)

A phase is complete only when:

- Every functional requirement in its spec(s) is implemented.
- Every acceptance criterion in its spec(s) passes, verified by a real run — not
  assumed.
- `pnpm lint`, `pnpm typecheck`, `pnpm test`, and `pnpm build` all pass.
- New database changes are additive Prisma migrations that apply cleanly.
- No secret is hardcoded or committed.
- Work is committed with clear messages.

## Tracking

As each phase completes, tick it here:

- [x] Phase 0 — Scaffold
- [x] Phase 1 — Meta Gateway
- [x] Phase 2 — Contacts & Inbox
- [x] Phase 3 — Templates
- [x] Phase 4 — Campaigns
- [x] Phase 5 — Automation
- [x] Phase 6 — Quality & Analytics
- [x] Phase 7 — Cutover (AiSensy retired; live on test number)

## Notes for cutover (Phase 7)

Phase 7 has no module spec — it is an operational checklist, executed with the
business:

1. The platform runs end to end on the fresh number; AiSensy still runs on the
   old number.
2. Templates needed by the reminder engine are created and approved on the new
   number's WABA.
3. The migrated Gen-1 reminder workflows and Gen-2 conversational workflows are
   verified at parity on the new number.
4. Inbound traffic and automations are switched to the new number.
5. The AiSensy subscription is cancelled; legacy workflows are archived.