PROMPTLYSOCRATICSPECS
An AI product architect that Socratically interviews founders and turns the conversation into an engineering-grade spec — modules, an acyclic dependency graph, a living PRD, a consistency score. 16 AI agents propose; deterministic code decides, behind a four-gate cost guard that makes overspend structurally impossible.
01 / Overview
"The AI interviews you; the server owns every decision it proposes."
Founders show up with a vibe, not a spec — "an app like X but for Y" — and discovery burns weeks of expensive back-and-forth that produces prose, not artifacts. Promptly runs a guided six-phase workflow instead: Ember, the Socratic architect agent, interviews the founder while 16 AI agents propose modules, questions, dependency edges, and specs through typed tool calls that deterministic code validates, applies, or silently drops. The model never assigns an ID, never moves a phase, and can never overspend — a four-gate cost guard (account standing → per-user budget → per-project cap → hard call ceiling) sits in front of every single call, with a per-call cost ledger and a price table that refuses to boot on an unpriced model. The output is real and synchronized: a dependency graph and a living PRD that are two projections of one spec store, a consistency score recomputed on every mutation, and snapshots that make every risky operation reversible.
I architected and built Promptly end to end: the FastAPI/SQLAlchemy backend, all 16 agent pipelines, and the Next.js/React frontend hand-rolled on three runtime dependencies. The hardest problems were structural, not visual — drawing the "agents propose, code decides" boundary so a hallucinating model can never corrupt state (server-assigned IDs, a legal-transition graph, cycle detection on every edge); building the four-gate cost guard that makes overspend structurally impossible before a call ever fires; and making the whole system horizontally scalable from day one, with every coordination primitive — locks, buckets, streaks, pub/sub fan-out — living in Redis so N backend instances behave as one.
02 / System Architecture
hover to explore
PROMPTLY SOCRATIC SPECS system architecture: Browser (httpOnly · silent refresh); Next.js 16 (React 19 · 3 deps); FastAPI (api/ routers · N instances); Redis 7 (pub/sub · Lua locks); PostgreSQL 17 (only durable store); Chat Agents (Ember · retry · summary); Detail Agents (Bank Planner · Validator); Spec Agents (Extractor · Dep. Analyzer); Review Agents (Cross-Module Reviewer); Build Agents (Stack · Wireframe Gen.); Anthropic API (gated + metered).
Connections: Browser → Next.js 16 (HTTPS); Next.js 16 → FastAPI (REST + WS · 4 rooms); Next.js 16 → FastAPI; FastAPI → Redis 7 (pub/sub · locks · buckets); FastAPI → PostgreSQL 17 (SQLAlchemy 2.0 async); FastAPI → Anthropic API (core/claude.py · cost_guard); FastAPI → Chat Agents (overview → modules); Chat Agents → Detail Agents (→ detailing); Detail Agents → Spec Agents (→ finalizing); Spec Agents → Review Agents (→ review); FastAPI → Build Agents (on-demand · after specs exist).
03 / Features
Socratic Chat — Ember
Every message runs one guarded, metered, streaming turn against a 7-tool contract; when a turn produces no real side-effect, a forced-tool retry and then a deterministic fallback question mean the conversation can never dead-end.
Session Security Beyond Tutorial Tier
httpOnly cookies with refresh-token family rotation — a replayed token is treated as theft and revokes the entire family, committed before the 401 so a rollback can't undo it — plus enumeration-safe login with a dummy bcrypt verify.
16 Agents, Zero State Ownership
The Architect, Bank Planner, Extractor, Dependency Analyzer, Conflict Detector, and 11 more only propose via typed tool calls; the model never assigns an ID or moves a phase, and illegal requests are silently dropped against a legal transition graph.
Six-Phase State Machine
overview → modules → detailing → finalizing → review → complete moves through one guarded function with a full audit trail — from, to, trigger, rationale — on every transition.
One-Click AI Suggestions
Flagged vague terms and conflicts get one AI-generated fix — one measurable definition, one reconciliation sentence — alongside a Tech-Stack Matchmaker and a Wireframer that generate build-support artifacts grounded in the real spec.
Four-Gate Cost Guard
Account standing, per-user budget, per-project $5 cap, and a hard call ceiling all clear before a single model call fires; a per-call ledger prices every token, and an unpriced model refuses to boot rather than silently mis-bill.
Real-Time Everywhere
Four WebSocket rooms per project — chat, graph, document, score — fan out through Redis pub/sub; a per-session outbox flushes only on commit, so a rolled-back transaction never broadcasts a lie.
One Spec Store, Two Projections
The dependency graph and the living PRD can't drift — editing a document section is editing the graph node, and cycle detection on every edge insert keeps the graph provably acyclic.
Restorable by Design
Module-slice and whole-project snapshots auto-taken before every risky operation; every restore takes its own safety snapshot first, so restores are themselves reversible.
04 / Screens
Socratic Chat
Ember interviews the founder module by module. Each answer streams into the live question bank on the right — typed, picked, or AI-decided — and a module finalizes only when zero questions stay open.
Dependency Graph
Every extracted spec becomes a node keyed by a stable server-assigned FEAT-NNN code. The Dependency Analyzer proposes edges; cycle detection on every insert keeps the critical path provably acyclic.
Tech-Stack Matchmaker
A post-spec generator turns budget tier, team size, and priority into per-role tool picks grounded in the real spec — each with why, monthly cost, and alternatives — regenerated whenever the constraints change.
Wireframe Generator
The Wireframer proposes low-fi screens as a tiny typed layout schema — one commit per screen so they appear progressively — with plain-English refine and per-screen version history.
05 / Process
The trust boundary — agents propose, code decides
Designed the core guarantee before writing a single agent prompt: every one of 16 pipelines speaks only through typed tool calls, and deterministic code validates, applies, or drops them against a legal transition graph, server-assigned FEAT-NNN codes, and cycle detection on every edge. A model that hallucinates an ID or requests an illegal phase jump is simply ignored, not caught after the fact.
The cost and failure envelope
Built the four-gate cost guard — account standing, per-user budget, per-project cap, hard call ceiling — in front of every model call, with a per-call ledger pricing fresh, cached, and output tokens against a price table that refuses to boot on an unpriced model. Paired it with a designed fallback for every one of the 16 pipelines — retry, draft recovery, manual finalize, spec-less finalize — so a failed call degrades gracefully instead of wedging the state machine.
Real-time at scale, then hardening
Moved all coordination into Redis — Lua-scripted token buckets, compare-and-delete lock release, TTL'd streak counters — so N backend instances share zero in-process state while fanning four WebSocket rooms per project through pub/sub. Closed with a 30-flaw adversarial review of the chat pipeline, 60+ end-to-end flow tests including live reconnects across backend restarts, and a 63-entry decision log tying every non-obvious choice back to code.