Start here
Everything about ClearList on one page, in the order you'd actually think it through. Read left to right across the tabs: first the proof it's worth building, then how it feels to use, then the plan to build it.
The goal
Clear out a whole house fast, before a moving deadline, without it eating your week.
What people do today
Facebook Marketplace plus a spreadsheet plus endless texts, juggled across apps.
Why that hurts
Writing listings is tedious, buyers no-show, haggling is draining, and nothing's in one place.
The numbers at a glance
Complexity
6 / 10
Real, but doable with AI help
V1 timeline
2–3 wks
Core flow, photo to pickup
Cost to start
~ $0
Free tiers cover the early days
How to use this doc
The tabs follow the journey: Evidence (proof it's real), Experience (how it works, with the blueprint), Build Plan + Coding Guidelines (how to build it well), Distribution and Before Launch (getting it out safely). Hand to Your AI has the plan to paste into your coding tool. Continue lets you take this one file anywhere and pick up where you left off.
The evidence
This is what makes it a plan and not a hunch. Before designing anything, we cast a wide net across Reddit and the reviews of the tools people already pay for, then scored every need by how much it hurts and how badly it's served.
The opportunity map
Every need, placed by pain and how well today's tools handle it. The green corner is where ClearList wins.
Where everyone's weak
Four of six needs are wide open. That gap is the moving-sale opportunity.
In their own words
"I gave up and just left a pile on the curb. Writing all those listings wasn't worth it."
"Three people said they'd come for the couch. None showed. I wasted a whole Saturday."
#1 to build · opportunity 15 Create an accurate listing in seconds. Hurts a lot, handled badly everywhere.
The experience
The experience wasn't guessed. We sketched several directions for the core moment, combined the best into one, and that chosen direction is what the blueprint maps. Here's the lineage.
1 · We explored the core moment (Crazy 8)
Many rough directions for the one main interaction, side by side, so we react to real options instead of marrying the first idea.
2 · We combined the best into one
The picks fused into a single direction (snap, talk if you want, swipe to sort), simpler than any one sketch.
★ This is the most important part
That combined direction is the one experience that solves the biggest problem from the Evidence tab: the proven aha moment, the thing people will actually switch for. The blueprint below maps this flow end to end, because it is where ClearList earns its place. Everything else in this document exists to support it.
3 · The Experience Blueprint, buyer reserves an item
Read left to right for the journey, top to bottom for everything standing behind each step.
The build plan
What to build, in what order, on what stack. V1 is the smallest thing that is genuinely useful, photo to pickup for one seller. Everything else waits.
The tech stack
What users see
Next.js · App RouterTypeScriptTailwindPWA (sellers)
The AI brain
Gemini 3.0, writes & prices listings
Where data lives
Firestore (database)Firebase Storage (photos)Firebase Auth (email codes)
Money & messages
Stripe (paid tiers)SendGrid (email)FCM (push)Bannerbear (social cards)
Lives online
Vercel (hosting)clearlist.me
Boring, modern, beginner-friendly: managed services over self-hosted, one codebase, no DevOps hire. Your code stays on GitHub, so you can always walk with it.
What to build first
V1, build now
- Snap photos, AI writes & prices each listing
- Review and edit every field, mark an item FREE
- Publish a shareable sale page (city + payment note)
- Buyers reserve with an email code
- Inbox, and share your address only after you confirm
V2+, build later
- Queue (max 3) + the 48-hour hold timer
- Pickup scheduling (availability, time slots)
- Push notifications + the full email set
- Auto social cards + custom URL (paid)
- Paid tiers via Stripe
The story map
The seller's journey across the top, each capability hung under its step in V1 / V2 / Later lanes. The same V1/V2 split above, seen as the build spine.
Build order, with checkpoints
1
Sign in + try it free. Email-code login, plus a visitor can try the AI on one photo before signing up.
Checkpoint: you log in with a code, and the try-before-signup demo works.
Checkpoint: you log in with a code, and the try-before-signup demo works.
2
Snap to listing. Photograph an item, the AI fills title, price, size, condition; you edit and save.
Checkpoint: one photo becomes an editable, saved listing.
Checkpoint: one photo becomes an editable, saved listing.
3
Dashboard + manage. All items in a list with status badges; edit, delete, mark FREE.
Checkpoint: you manage several items and change their status.
Checkpoint: you manage several items and change their status.
4
Publish + share. Set city + payment note, get a sale-page link with a clean preview card.
Checkpoint: a shared link shows a real preview and a live page.
Checkpoint: a shared link shows a real preview and a live page.
5
Buyers reserve. A buyer browses, verifies email, reserves; it lands in your inbox.
Checkpoint: a reservation flows end to end into the inbox.
Checkpoint: a reservation flows end to end into the inbox.
6
Coordinate pickup. Message the buyer and share your address only after you confirm.
Checkpoint: address sharing requires your explicit tap.
Checkpoint: address sharing requires your explicit tap.
Data model, 5 collections
users
Seller accounts: email, tier, location, custom URL, availability.
items
Listings: status, title, price, dimensions, photos.
reservations
Buyer holds: item ids, expiry, queue position, cancel token.
conversations
Inbox threads: seller, buyer email, unread count.
messages
Inside a conversation: sender, content, read state.
house rule
Every action goes through an API route, so an AI agent can do anything the UI can.
Coding guidelines
The house rules your AI coding tool should follow on every line, so the build starts on solid ground and stays one your AI can keep working in. Paste the block at the bottom into your project guide.
How to work with your AI
- Think first. Before non-trivial code, have it say what it'll build and ask about anything unclear. No guessing.
- Keep it simple. The simplest thing that solves the problem. No extra features, no "just in case" code.
- Change only what you asked. Don't let it rewrite unrelated code. If it spots something, it tells you, it doesn't do it.
- When it loops, stop and reset. If the AI goes in circles or breaks things, revert to the last working version, then give it the exact error and what you already tried.
How the code should be built
- One home per thing. The same logic lives in exactly one place (one place for prices, one for login).
- Call things the same name everywhere. If it's a "pickup," it's always a "pickup," in the code and on the screens.
- Self-contained features. Each feature is one tidy piece (the "microwave": lots inside, one simple front), not smeared across the app.
- Keep the layers apart. Screens, decisions, and where data is saved stay separate.
- Handle the sad path. Every failure shows a friendly message and a way out, never a blank screen.
- Leave a trail. Important actions log what happened, so the day it breaks, your AI finds it in minutes.
Safety basics (do these from day one)
- Secrets stay out of the code. API keys live in environment variables, never in a file you commit.
- Never trust what users type. Check and clean input before you use it.
- Commit small and often. Save your work in little steps so you can always roll back.
- Backups on. Make sure your database keeps automatic backups (most managed ones do).
Paste this into your project guide (CLAUDE.md or similar)
# House Rules for ClearList You're the engineer. I'm the product manager. Follow these on every change. ## How to work - Think first: before non-trivial code, say what you'll build and ask about anything unclear. - Keep it simple: the simplest thing that solves the problem. No extra features. - Change only what I asked: don't rewrite unrelated code. If you spot something, tell me. - If you get stuck or start looping: stop, tell me, and we revert to the last working version. ## How to write code - One home for each piece of logic (don't repeat yourself). - Same name everywhere: if it's a "pickup," it's always a "pickup." - Self-contained features: each feature in its own folder as one tidy piece. - Keep layers apart: screens vs. decisions vs. where data is saved. - Handle the sad path: every failure shows a friendly message and a way out. - Leave a trail: log important actions (what happened, worked or failed, any error). ## Safety - Secrets in environment variables, never in committed code. - Validate all user input before using it. - Commit small and often.
These are the architecture essentials (deep, navigable modules, a single source of truth, consistent names) in plain language. They're enough to start on solid ground. You do not need decision-record formalism or coverage gates on a first app.
Distribution & growth
The question that kills more apps than bad code: once it's built, how does a single human find out it exists? Good news, you already did this research. The communities where you found the pain are where your first users live.
Your first 10 users
Who, specifically
The people in r/declutter ranting about the "death pile," and posters in the moving subreddits with a deadline.
Where they gather
r/declutter, the moving subreddits, and local "moving sale" Facebook groups, the exact place you mined for pain.
Your first move
Be genuinely useful there for two weeks, then one honest "I built this because I had a pile too" post. Stand up a waitlist now.
The growth loop
Seller lists items→
Public sale page→
Found on Google & shared→
Buyer has a great sale→
Buyer moves, becomes a seller
↻
A content loop: every sale page is public, so it gets found on Google, and the happy buyer becomes your next seller. The product markets itself.
Will the loop start? (the cold-start check)
ClearList is useful to one seller on day one, no network required, so the core has no cold-start trap. The future city directory does need liquidity, so hold it closed until about 50 sale pages exist in a city. Otherwise the first visitor lands on a near-empty page and never comes back.
Before launch
The things beginners never see coming. Each is tagged so you know when to deal with it, not all at once.
Handle now
- Secrets. API keys live in environment variables, never in committed code.
- Privacy. Show only city + state in public; the seller's address is shared only on explicit confirm.
- Backups. Make sure the database keeps automatic backups (most managed ones do).
- Accessibility. Usable by keyboard and screen reader. Far harder to bolt on later.
Before you launch
- Legal. A privacy policy and terms; a refund policy once you take money (14-day cooling-off for EU buyers).
- Payments early. Apply to Stripe before writing payment code; keep a backup (Shopify buy button).
- Error tracking. Know when it breaks at 3am before your users do.
Hand to your AI
This is the instruction manual for your AI coding tool. Copy it, paste it into your tool, and start building. The more specific the plan, the better it builds the first time.
# ClearList, build plan for your AI coding tool ## The problem People moving with a deadline need to clear out a whole house fast. Today they juggle Facebook Marketplace, a spreadsheet, and endless texts. Writing listings is tedious, buyers no-show, and nothing is in one place. ## The goal Photograph your stuff, the AI writes and prices the listings, buyers reserve and schedule pickup. One place, photo to pickup. ## Who it is for People in a move with a pile to sell and a deadline (the r/declutter and moving-subreddit crowd). ## V1 features (build now) - Snap photos, AI writes and prices each listing - Review and edit every field, mark an item FREE - Publish a shareable sale page (city + payment note) - Buyers reserve with an email code - Inbox; share address only after the seller confirms ## V2+ (later) - Queue (max 3) + the 48-hour hold timer - Pickup scheduling (availability, time slots) - Push notifications + the full email set - Auto social cards + custom URL (paid) - Paid tiers via Stripe ## Tech stack - Frontend: Next.js (App Router), TypeScript, Tailwind; PWA for sellers - AI: Gemini 3.0 (writes and prices listings) - Data: Firestore, Firebase Storage, Firebase Auth (email codes) - Money and messages: Stripe, SendGrid, FCM, Bannerbear - Hosting: Vercel; domain clearlist.me ## Data model (5 collections) - users: email, tier, location, custom_url, availability - items: status, title, price, dimensions, photos - reservations: item_ids, expires_at, queue_position, cancel_token - conversations: seller_id, buyer_email, unread_count - messages (subcollection): sender, content, read ## Build order (each ends with a checkpoint) 1. Sign in + try-before-signup 2. Snap to AI listing 3. Dashboard + manage 4. Publish + share 5. Buyers reserve 6. Coordinate pickup (then V2: queue/timer, scheduling, push, social cards, payments) ## House rules - Think first; keep it simple; change only what is asked; if you loop, stop and reset. - One home per piece of logic; same name everywhere; self-contained features; keep layers apart. - Handle the sad path; leave a trail (logging). - Secrets in environment variables; validate user input; commit small and often. - Every action goes through an API route, so an agent can do anything the UI can.
Continue anywhere
This file carries the whole session inside it. Take it to a new chat, a different AI tool, or hand it to a teammate, and nothing is lost.
Pick up where you left off
A complete machine-readable snapshot of this session is embedded in this file. To resume: open a new vibe-check chat, attach this HTML file, and say "continue from this PRD." Your AI reads the snapshot and has every decision, every piece of evidence, and the full plan, no context lost.
Snapshot status: embedded