Waiting List

Waiting-list portals

Use this skill to turn “we need a waitlist” into a truthful product promise, an appropriate system boundary, and a buildable delivery plan. A list of interested people, a fair order of service, a traffic gate, and a reservation are different things. Never let a polished landing page silently choose the semantics.

When to load

Load this skill when the user is designing, reviewing, implementing, or comparing a portal for early access, product launch demand, scarce goods, appointments, memberships, events, beta programs, or high-traffic admission.

When not to use

• For copy, visual design, SEO, or accessibility in isolation, use the relevant frontend or content skill and bring this skill in only for the list behavior.
• For a general API, database, email, security, or payment implementation, use the owning specialist skill; this skill supplies the waitlist-specific contract and failure modes.
• For a live waiting-room vendor or queue datastore, read its current official documentation. This skill is a design method, not a substitute for vendor runbooks or legal advice.
• For a standalone CRM migration or email/SMS campaign, use the owning integration skill. Load this skill when the CRM is a downstream of the waitlist's verified-contact lifecycle.

Core workflow

Default posture and marketer experience

For a new marketing waitlist, use one static HTML page, Alpine.js (CSP build), Vite packaging, custom CSS, TypeScript API functions on Vercel's Node.js runtime, and managed Neon Postgres. Use Twilio Verify codes for email (with SendGrid) and optional SMS verification; keep the CRM selectable through server-side runtime configuration. Avoid Python backends and Rails. Go or Rust are explicit alternatives for a campaign whose existing hosting or requirements warrant them. These are defaults, not reasons to replace an existing working integration.

Read references/default-stack.md before building or deploying. It defines the provider posture, Vercel limitations, repository shape, worker execution, and escape hatches. Read references/brand-and-marketer-workflow.md for all new portals: gather the campaign brief, brand guide, logos, reference images, and optional video; show a branded preview before connecting production. Use templates/campaign-brief.md as the plain-language intake. The agent fills technical records; do not ask a marketer to select an ORM, framework, retry algorithm, or database schema. For a premium, cinematic, motion-rich, or reference-led campaign, also read references/engagement-and-visual-system.md and record its relevant experience brief, fallback, performance, and visual-test decisions. Treat a reference site as a source of observable interaction principles, not as permission to copy its brand, assets, source, layout, scarcity language, or product claims. Use approved supplied assets or original image-generated artwork for campaign heroes, product scenes, and editorial illustration. Preview generated artwork for approval before publication. Do not substitute CSS shapes or gradients, inline SVG drawings, canvas sketches, emoji, ASCII, or icon collages for campaign artwork unless the user explicitly requests that aesthetic. Programmatic graphics remain appropriate when geometry is the information, such as charts, diagrams, controls, and status indicators. Use templates/campaign-config.example.json as a server-side configuration example; its unset production choices must be resolved before enabling live sends.

Default campaign: email interest capture with required email confirmation, phone collection off, referrals off, no displayed rank, no implied reservation, and CRM awaiting connection. If SMS is enabled without a specified interaction, prefer managed OTP. An explicit SMS magic-link requirement overrides that default; preserve it and explain the provider capability boundary.

This skill can create deployments and send messages when used to implement a portal. Confirm the target, scope, and rollback path before acting. Read-only discovery may proceed without confirmation. Use existing authorization where it already covers those details; prepare local artifacts and previews first. Never describe a mock form as collecting real registrations.

1. Write the promise before choosing technology

Answer these questions in plain language:

1. What does joining mean: interest, a place in line, eligibility for an invitation, a chance in an allocation, or a request for a service slot?
2. What, if anything, is guaranteed? State explicitly that joining does not reserve inventory, payment priority, an appointment, or admission unless a separate confirmed action does so.
3. What event advances the person: verification, capacity, a scheduled release, a cancellation, a score, a referral, a lottery, or an operator decision?
4. Which contact proofs are optional, required, or absent? What does a verified email or phone actually authorize, for how long, and what happens when an invitation expires, a person unsubscribes, or a duplicate arrives?
5. What must be true at launch: peak arrivals, acceptable loss, fairness rule, regions, accessibility, languages, data residency, integrations, and rollback path?

Record assumptions as assumptions. Do not use “current position” when the operator may select by segment or fit; call it an interest list or an estimated rank instead.

2. Select one primary pattern

Use the smallest pattern that makes the promise true. Combine patterns only when the boundary and transition are explicit.

For a simple prelaunch page, start with the interest-list pattern. For a launch-day traffic spike, start with a virtual waiting-room or edge product. For a product or service whose scarce resource is the real problem, design the inventory or scheduling boundary first and attach the list to it.

Load references/architecture-patterns.md when comparing patterns, modeling scale, or deciding whether a queue, referral loop, reservation, or vendor is warranted.

3. Define the state machine and data contract

When implementing, read references/implementation-contract.md for concrete endpoint, persistence, verification, CRM, and failure contracts.

Use opaque IDs and keep contact data out of URLs, logs, analytics labels, and public ranking pages. A useful baseline is:

submitted -> verification_pending -> active -> invited -> claimed
                                  \-> suppressed/removed
invited -> expired

Use a separate queue/admission state for a waiting room:

identified -> queued -> admitted -> consumed
                     \-> abandoned/expired

If the portal validates contacts, model each channel independently rather than using one overloaded verified flag:

email: unrequested -> sent -> clicked/verified | expired/revoked
phone: unrequested -> sent -> clicked/verified | expired/revoked

“Verified” means the channel's proof was accepted under a named method and timestamp. It does not prove legal identity, that the supplied person owns the account, that the number is suitable for marketing, or that the contact will remain accurate. Load references/contact-verification-and-crm.md when either contact proof or CRM delivery is in scope.

For each transition define the actor, precondition, side effect, retry behavior, audit event, and user-visible message. Store at least:

• program_id, opaque entry_id, created_at, and a stable tie-break key;
• normalized-contact uniqueness with a documented normalization version and protected original; plan key rotation if keyed lookup hashes are introduced;
• consent purpose, source/UTM attribution, verification and suppression times;
• explicit status, policy/version identifiers, invitation/claim expiry, and only the attributes needed for selection or service matching;
• referral code ownership and referral events, if enabled; never infer counts from mutable client state;
• per-channel verification method, proof ID, verified_at, expiry/revocation, and consent purpose; do not store raw tokens;
• CRM sync status, mapping/version, provider record ID, idempotency key, and last error; keep this as integration state, not as the waitlist's source of truth;
• an append-only audit/event record for state changes and outbound effects.

Make POST safe to retry with an idempotency key or a database uniqueness constraint. Define duplicate behavior deliberately: normally return a generic success for an already-known contact so the endpoint does not become an email enumeration oracle. Do not expose a raw row count as a personal position unless the ordering and visibility rules make that claim true.