A plain-English walkthrough of the customer-support system Mo, Vlad, Gabriel, Hisham, and Ori are building together — what each person does, where the rules live, and how updates get pushed.
A shared knowledge base + workflow for replying to Sooner customers on WhatsApp. Run by humans, supercharged by Claude Code.
Every customer reply that lands on Sooner's WhatsApp goes through a CS operator (Mo, Vlad, Gabriel, or eventually Hisham). Each operator opens their own Claude Code session on their laptop, reads the shared rules from this repo, drafts a reply, gets it approved, and sends it via the Rasayel API.
The reason this works at scale is the shared rule book. Instead of every operator inventing how to answer a pricing question or a foreclosure question, we centralize all of that in one GitHub repo. Updates push out daily via GitHub issues. Everyone stays aligned.
Customer messages land in Rasayel → an assignment service routes each one to a specific operator → that operator handles it in their own Claude Code session using the shared rules from this repo → if they learn something new during the conversation, they suggest a rule update via a GitHub issue → Mo merges approved suggestions daily → everyone pulls the latest.
Three moving parts: Rasayel (where customers live), the assignment service (Ori's), and the playbook (where rules live).
Read it top to bottom. Solid arrows are the customer-facing message flow (numbered 1-8). Dashed arrows show what the operator's Claude Code reads from and writes to — the Playbook (the shared rule book) and the CRM (the buyer's record).
Six people. Clear lanes. Mo is the rule-writer; everyone else is an operator or builder.
main)From "open laptop" to "inbox zero" in well-defined steps. Everyone follows the same flow.
Open your terminal. Make sure you've got the latest changes from the playbook — Mo merged overnight suggestions into main while you slept.
cd ~/sooner-cs-playbook git pull origin main
From the playbook directory, fire up Claude. The SessionStart hook auto-runs /start-shift for you, which pulls the latest rules, reads SESSION_HANDOFF.md, runs a rescan, and posts a briefing within ~30 seconds. You're productive immediately.
claude # SessionStart hook fires /start-shift automatically. # Claude posts: today's calendar, live queue, in-flight items, recommended first action.
See who's awaiting a reply. Claude pulls the live queue from Rasayel and groups it into clusters (hot, pricing question, call setup, your court, etc).
python3 scripts/rescan.py
Tell Claude the conv ID or customer name. Claude pulls the last 5 messages of the conversation + the customer's CRM record + drafts a reply using the rules in the playbook.
You: draft a reply for conv 20940671
Claude: [pulls history + CRM]
[presents draft with 3-6 short WhatsApp bubbles]
[asks for approval]
Read the draft. If it's right, say "send". If not, push back — "make it shorter", "drop the personal loan comparison", "use her name". Claude revises and re-shows. Repeat until you're happy, then approve. Claude sends via Rasayel, logs the send, and updates CRM labels.
Mid-conversation a new rule lands — maybe pricing changed, maybe a phrasing didn't work, maybe a hard constraint surfaced. Open a GitHub issue using the Rule Suggestion template. Mo processes them daily.
gh issue create --template rule-suggestion.md
After each reply, Claude automatically re-pulls the queue (it's a rule). When the queue is empty for the day, you're done.
The repo is organized so you can find any rule, narrative, or script in under 10 seconds. Here's the map.
/refresh-handoff (manually or automatically at turn checkpoints). Tells the next session what's in-flight, who's awaiting a reply, what's in someone's court, today's calendar, what was decided. Read first thing in the morning. Updated by whoever closes shiftThree slash commands and two hooks. Built so no operator ever loses state between sessions, and so context-window degradation has a graceful recovery path.
/start-shiftAuto-fires on every new claude session via the SessionStart hook. Pulls latest from main, reads CLAUDE.md + SESSION_HANDOFF.md + docs/rules.md, runs the rescan, pulls today's calendar, posts a briefing. ~30 seconds.
/refresh-handoffCaptures current state into SESSION_HANDOFF.md and commits + pushes to GitHub. Use any time you want to ensure nothing in flight gets lost. Auto-recommended at turns 25 / 50 / 75 / 100.
/end-shiftClean close-out at end of day. Wraps refresh-handoff + a summary of today's outcomes + a "for tomorrow" briefing. Tells you it's safe to close the terminal.
Claude Code auto-compresses older messages as context fills. Since there's no first-class "context %" API, we use turn count as the cleanest proxy. The hook silently increments a counter on every prompt you send, and emits reminders at thresholds:
/refresh-handoff at next pause."/end-shift now and starting a fresh session." Quality starts to degrade past this point.1. Tell Claude: /end-shift — it refreshes handoff, commits, pushes, gives you a close-out summary.
2. Close the terminal.
3. Open a new one, run cd ~/sooner-cs-playbook && claude.
4. SessionStart hook auto-runs /start-shift. You have a fresh briefing in 30 seconds.
The new session won't remember running banter or specific draft revisions from the old one. But it WILL know every rule, every customer in flight, the live queue, today's calendar, and what was decided. That's enough to keep going at full effectiveness.
Mo is the only person who writes to main. Everyone else suggests via issues. This keeps the rule book trustworthy.
Maybe a customer asked about Ramadan greetings and we didn't have a rule. Maybe a competitor's offer surfaced. Maybe an old phrasing didn't land.
One-paragraph description: what the rule is, where it belongs (which doc), what triggered it. Optional: a link to the Rasayel conv.
Reads the suggestion, decides if it's a durable rule or a one-off. If durable, he opens a pull request that adds the rule to the right doc.
The repo is configured so no one can push directly to main. Every change requires a PR + code-owner review. Mo is the code owner for everything in docs/ and src/utils/.
One source of truth. One author. Full audit trail.
git pull origin main brings the latest rules into everyone's local clone. Claude reads the updated rule book on its next session.
If everyone could edit the rule book directly, we'd have conflicting versions of "what we charge", "how we phrase a refund", "what we say about offplan", etc. By funneling all changes through Mo + a daily review cycle, we keep the rule book accurate and avoid customers getting contradictory answers from different operators.
A short list. Most operators won't touch more than four of these in a typical day.
Each operator has their own Anthropic account and runs Claude Code locally in the sooner-cs-playbook directory. This is where the drafting and sending happens.
Opens issues, files rule suggestions, reads PRs. Most operators only use one command: gh issue create.
WhatsApp Business API. Claude reads and writes via the Rasayel GraphQL + REST APIs. Operators rarely log into the Rasayel UI directly — Claude handles it.
Vlad's dashboard at dist-gray-mu-70.vercel.app. Holds buyer records, labels, stage transitions. Claude updates this automatically after each customer reply.
For email follow-ups and calendar invites. Each operator auths their own Sooner email. Calendar invites for confirmed calls get sent automatically.
#sooner-ai-support is where Ori's assignment service posts notifications. When a conversation gets assigned to you, you'll see it there.
Two things land in the next week. After that, the system is at v1.
Routes inbound Rasayel conversations to a specific operator (round-robin), keeps assignments stable, posts Slack notifications with the conv link. Eliminates double-replies. Lives at rematched/sooner-customer-support.
Mo to register a new business number under Sooner Real Estate L.L.C. The current number's deliverability is throttled after the bulk send. New number goes into Rasayel.
Slash commands + turn-counter hook + SessionStart auto-boot. Session continuity is now automatic. See section 06 above for the full system.