VumbuaAI - Customer Discovery Co-Pilot
"Vumbua" is Swahili for "discover". VumbuaAI is a conversational AI agent that helps early-stage entrepreneurs test customer and business-model assumptions using Blank and Dorf's Customer Discovery method. Founders chat with it like a coach; it updates a structured workspace (hypotheses, interview guide, evidence, decisions) and produces a Customer Discovery Evidence Report.
Core principle: the app helps founders discover and interpret evidence - it never manufactures evidence or makes decisions for them. The methodology is enforced in code (lib/rules.ts), not just in AI prompts.
Architecture
| Layer | Technology | Files |
|---|
| Web application | Next.js 15 / React 19, responsive, keyboard-accessible | app/, components/ |
| Application backend | Next.js API route: session validation, rate limiting, business rules, agent loop | app/api/agent/route.ts, lib/rules.ts |
| AI service | Anthropic Claude via tool use (10 tools) | lib/agent-tools.ts, lib/prompt.ts |
| Data storage | Supabase Postgres + Auth with row-level security; browser fallback | lib/store.ts, supabase/schema.sql |
| Hosting | Vercel | - |
How the agent works
- The founder sends a chat message. The backend runs deterministic checks (vague customer, unsupported claim, personal data) and appends a
[Rules engine] note the AI must address.
- Claude replies and calls tools (
propose_hypotheses, add_interview_questions, record_evidence, record_assessment, recommend_next_action, etc.) to update the workspace - up to 8 tool rounds per message.
- Every tool call passes through the rules engine, which can reject it (e.g. invented evidence, a solution experiment with no evidence) and tells the AI why.
- The updated session is returned and saved.
Business rules enforced in code
| Rule | Enforcement |
|---|
| 1. No evidence, no validation | Statuses are computed by computeStatus(); the AI cannot set them. No real evidence = Untested. Validating recommendations without evidence are rejected. |
| 2. Behaviour over enthusiasm | Provisionally Supported needs 3+ supporting observations, 2+ interviews and at least one observed behaviour. Opinions alone cap at Evidence Emerging. Founder interpretations and simulated responses never count. |
| 3. Contradictions stay visible | applyRules() restores any contradicting evidence an AI assessment omits and notes it. Evidence Lab shows supporting and contradicting side by side. |
| 4. Traceability | AI-recorded evidence must quote an exact excerpt from the founder's own messages; assessments and recommendations may only cite existing evidence ids. |
| 5. Human-led decisions | AI hypotheses arrive as unapproved drafts; recommendations arrive as pending. Only the founder can approve, accept, reject or modify. |
| 6. Iteration | Revisions create a new version and preserve the original and its evidence in revision history. |
Setup (about 15 minutes)
1. Supabase
- Create a free project at supabase.com.
- SQL Editor -> New query -> paste
supabase/schema.sql -> Run.
- Authentication -> Providers -> Email: enabled. For a classroom demo you may turn off "Confirm email" so students can sign in immediately.
- Project Settings -> API: copy the Project URL and anon public key.
2. Anthropic
Create an API key at console.anthropic.com and set a monthly spend limit.
3. Environment variables (Vercel -> Project -> Settings -> Environment Variables)
| Name | Value |
|---|
ANTHROPIC_API_KEY | your Claude key (server-only - never prefix with NEXT_PUBLIC_) |
ANTHROPIC_MODEL | optional, default claude-sonnet-5-5 |
RATE_LIMIT_PER_HOUR | optional, default 60 per user |
NEXT_PUBLIC_SUPABASE_URL | Supabase project URL |
NEXT_PUBLIC_SUPABASE_ANON_KEY | Supabase anon key |
Then redeploy.
Sign-in is on by default, so each user keeps a saved history across devices. For open access without accounts (sessions saved only in the visitor's browser), add NEXT_PUBLIC_REQUIRE_LOGIN=false in Vercel and redeploy.
Background knowledge
VumbuaAI reads lib/knowledge.ts before every reply (currently the five-step Customer Discovery playbook: hypothesis, persona, validation, gate checks, MVP). Add new sections there to teach it more.
Local development
npm install
cp .env.example .env.local # fill in values
npm run dev # http://localhost:3000
npm test # business-rule and agent-guard checks
Acceptance tests (lecturer demo script)
| # | Test | How to run it | Expected |
|---|
| 1 | Vague customer | Chat: "Everyone needs my app" | Rules engine note + AI asks for a specific segment and early adopters |
| 2 | Unsupported claim | Chat: "Customers will definitely buy it" | AI asks what customers have actually done; does not endorse |
| 3 | Leading question | Interview coach -> add "Would you buy our product?" (or ask the AI to review it) | Flagged hypothetical + solution-biased, with explanation and a better question |
| 4 | Mixed evidence | Evidence Lab -> record 3 supporting (one as observed behaviour) + 1 contradicting from 4 interviews | Both columns shown; contradiction visible in status, assessment and report |
| 5 | No interviews | Decision tab before recording evidence; or ask the AI to recommend a solution experiment | "No real customer evidence... remain Untested"; AI recommendation rejected by rules engine |
| 6 | Revision | Hypotheses -> Revise a tested problem hypothesis | New version active; original and its evidence kept in revision history |
| 7 | Full process | Get assessment -> accept recommendation -> Report | Structured report with next action; Download PDF / Markdown |
| 8 | AI failure | Tick "Demo: simulate AI outage", send a message | Message preserved, clear error, Retry button; untick and retry succeeds |
npm test runs automated checks for tests 1-6 and the agent guards (18 checks).
Requirements traceability
- Module A FR-01-06: home page (create/resume), Venture tab,
propose_hypotheses + approve/edit, computed statuses, autosave.
- Module B FR-07-11: Customers & problem lists,
lintText, priority ordering, six hypothesis types incl. value proposition, channel, revenue.
- Module C FR-12-16: AI-drafted guide,
lintQuestion + critique_question, edit/reorder/export, explanations.
- Module D FR-17-23: Evidence form + chat logging, statement/behaviour/interpretation, four statuses, linked findings, simulated flag excluded.
- Module E FR-24-29: Decision tab, unresolved assumptions, four actions, rationale + uncertainty, accept/reject/modify, revisions.
- Module F FR-30-34: Report tab, PDF (print) + Markdown, journey stepper + next-step hint, edit/delete everywhere.
- NFRs: labelled controls and keyboard navigation (01-02); loading state and 60s timeout (03); key server-side only (04); personal-data warnings and privacy page (05-06); local copy + retry (07); "AI guidance, not verified fact" labels (08); per-user hourly limit, 8-round cap, 2,000-token replies, 4,000-char inputs (09); Vercel URL (10).
