Build the home-game trainer without the casino-app smell.
This walkthrough turns plan.md into an operating map: what the product
is, what the other agent should build, where loops are safe, where human taste
matters, and which gates define a real MVP.
12/9
32/26
45/8
22/18
review
The wedge is fun NLHE now, variant depth later.
The product sits between expensive solver tools and play-money casino rooms: it should feel like playing poker, while producing post-session insight that actually improves decisions.
Target users
The plan weights casual learning, home-game realism, and serious review without letting any one audience pull the product off center.
Trust
Seedable RNG, reproducible hands, full history, explicit rules, and property tests are product features, not engineering garnish.
Taste
"Casino Library" is the screenshot-test standard: felt, leather, brass, editorial typography, deliberate motion, no neon clutter.
Moat
Hand review gets disproportionate investment because competitors either skip it or make it feel like homework.
Build in order, with testable exits.
Each phase has a working deliverable. The other agent should complete acceptance criteria before moving forward, and should treat UI-heavy phases as supervised work.
The engine and AI packages are the differentiated IP.
The monorepo keeps the pure poker engine, AI opponents, review engine, hand history, and web app behind clean package boundaries.
End-to-end product flow
Magic link or Google OAuth, no password flow.
Stakes, archetypes, custom rules, free-tier limits.
Engine resolves legal actions and deterministic bot decisions.
Canonical JSON captures every state transition.
Replay, EV deltas, leak detection, export, coaching.
The engine is the one place loops should cook hard.
NLHE correctness is foundational: known-good vectors, benchmark equity, property tests, fuzzing, and strict TypeScript gates all come before higher-level polish.
Correctness stack
State machine path
Legal action validation, side-pot handling, all-in players, folds, and chip conservation are the high-risk edges.
Variant adapter
NLHE is fully implemented for MVP. PLO and PLO8 should be architecture stubs until Phase 7, where exact-two-card and low qualifier rules get their own plan.
Archetypes are teaching tools, not celebrity replicas.
Bot decisions must be pure deterministic TypeScript and return in under 50ms. LLMs are reserved for async review narration after the hand is complete.
VPIP / PFR map
Each dot shows the target personality space. Loose-passive and maniac are intentionally far apart even when VPIP is high.
Decision pipeline
Position and action select range tables.
Hand strength, board texture, villain range.
Pot, stack, street, and archetype style.
Deterministic randomization for replays.
Fold, check, call, bet, raise in under 50ms.
Review is the moat; coach mode stays light.
Post-hand and post-session review should reveal decision quality without turning live play into a solver lecture.
Replay
Scrub action-by-action with table state restoration, step forward/back, speed controls, and hole-card reveal.
Decision EV
Show the user action, two or three alternatives, EV error in chips, and a plain-English explanation.
Session leaks
Scan patterns only after enough samples and only surface leaks costing more than 2 BB on average.
Drill / coach
Repeat spots like blind defense or c-bet decisions, then show one-line feedback after decisions.
Equity timeline concept
Every meaningful action should be inspectable: equity before and after, alternative action EV, and opponent range explanation.
Leak detector gates
The review engine should suppress low-confidence takes. Better to say one true thing than five noisy things.
Loop only where the feedback is mechanical.
The plan is explicit: loops are excellent for correctness and calibration, but harmful for aesthetics, UX taste, and qualitative insight quality.
Nightly regression watcher
From Phase 1A onward, run the full test suite, fuzz checks, lint, and typecheck every 30 minutes. Capture failures; do not auto-fix them.
Bug-mining loop
After engine completion, fuzz with fresh seeds, minimize crashes, write regression tests, and continue until 100 consecutive seeds run clean.
MVP means users can play, learn, pay, and trust it.
Launch is not just feature presence. The product has to pass engine stability, archetype calibration, review accuracy, payment flows, design quality, legal review, and distribution readiness.
Resource dependencies
Agent execution prompts
Read plan.md end-to-end. Execute Phase 0 only. Run acceptance checks.
Stop.
Build Phase 1A prerequisite infrastructure. Do not implement engine logic
yet.
Kick off the Phase 1A /loop prompt verbatim from plan.md. Run overnight.
Run full tests manually. Hand-trace 5 random fuzz hands. Mark Phase 1A done
only if sound.
Explicit no-list
These are not accidental omissions. They protect scope and legal simplicity.
The scariest failures are trust failures.
The plan's mitigations cluster around correctness, believable opponents, high-confidence review, distinctive design, and early distribution.