WhyBuddy — an AI agent crew that questions your product idea and rehearses it before you build. One sentence in → goal clarification, multi-route plan, full spec (requirements/design/tasks), feasibility & architecture out. Decide what's worth building, in minutes.
The deep catalog scan for this skill is still queued. Run an instant dependency check now instead.
# Add to your Claude Code skills
git clone https://github.com/xiaojilele-glitch/WhyBuddyNo comments yet. Be the first to share your thoughts!
cp .env.example .env # then fill in LLM_API_KEY (see "MUST FILL" section)
docker compose up
Open http://localhost:3000 and you're in. The WhyBuddy server (3001 internally) is published on host port 3000 so you can navigate directly without remembering port numbers.
Three ways to run — pick whichever matches your environment:
- Online demo — https://opencroc.github.io/whybuddy/ (browser-only mode, no install).
- Docker compose — the snippet above; one MySQL + one WhyBuddy container.
- Local dev —
pnpm install && pnpm run dev:all(full stack, hot reload, see Local Dev below).
The server starts even when these are blank, but every autopilot bridge silently falls back to deterministic templates and you'll see the same canned answers regardless of input. Fill these two and you'll get real LLM-driven generation:
| Variable | What to put | Where to get one |
|:---------|:------------|:-----------------|
| LLM_API_KEY | An OpenAI-compatible API key | OpenAI · DashScope · OpenRouter · Moonshot · SiliconFlow · Zhipu · DeepSeek · any provider that speaks the OpenAI Chat / Responses API |
| SESSION_SECRET | Any 64-char hex string | openssl rand -hex 32 |
LLM_BASE_URL and LLM_MODEL should match the provider you picked
(default values target api.openai.com + gpt-5.4). Everything else in
.env.example ships with safe defaults — leave them alone unless you have
a reason.
You type one sentence. The system rehearses the entire product for you:
💬 "AI comic platform"
│
▼
① 🔍 Smart Clarification Goals · Constraints · Personas · Success criteria
│
▼
② 🗺️ Route Planning Main route + Alternatives + Risk + Cost
│
▼
③ 🌳 SPEC Tree Modular spec node decomposition
│
▼
④ 📄 Spec Documents Requirements / Design / Tasks (streaming)
│
▼
⑤ 🎨 Effect Preview Architecture + Prompts + Next steps
│
▼
📦 Export → Markdown / ZIP / Online
💡 The entire process is observable in real time: a 3D office scene shows the agent fleet collaborating, while the right-rail workbench streams generation progress with stage indicators.
Seven specialized AI roles collaborate on every rehearsal:
| Role | Responsibility | |:----:|:--------------| | 🧠 Planner | Breaks the goal into executable routes | | ❓ Clarifier | Fills gaps, resolves ambiguity | | 🔬 Researcher | Gathers context, validates assumptions | | ✍️ Generator | Produces spec documents & artifacts | | ⚙️ Operator | Executes in Docker sandbox when needed | | 👁️ Reviewer | Checks quality, flags issues | | 📋 Auditor | Maintains evidence trail & compliance |
Each role has access to 50+ AIGC capability nodes, Docker sandbox, MCP tools, Skills, and domain knowledge injection.
See every step: active roles, invoked capabilities, ReAct cycle stage, produced artifacts. No black boxes.
Quick / Standard / Deep / Conservative routes with risk, cost, and takeover points. Choose before anything runs.
Clarification, approval, risk, budget, delivery — all explicit pause points. Never silently fails.
Exportable artifacts, audit logs, replay timeline. Inspect any decision at any moment.
Real code execution in isolated containers with HMAC callbacks and live terminal streaming.
Markdown, ZIP, or online preview. Every rehearsal is a shareable document package.
git clone https://github.com/opencroc/whybuddy.git && cd whybuddy
pnpm install
pnpm run dev:all # Full stack: frontend + server + executor
pnpm run dev:frontend # Opens at localhost:5173
Or visit the Live Demo directly on GitHub Pages.
whybuddy-app (the server +
bundled frontend) and whybuddy-mysql (MySQL 8 with the
whybuddy schema kept for backward compat — the data shape is
unchanged, only the project brand changed).LOBSTER_EXECUTION_MODE=real and pointing the host's Docker daemon at
the executor service yourself.BLUEPRINT_*_ENABLED flags default to safe values matched to a
fresh dev environment; the AUTOPILOT_REAL_RUNTIME master switch is
on by default — bridges that find their dependencies will run real,
bridges that don't will fall back gracefully.Every rehearsal is a shareable piece of content. 50 rehearsals = 50 distribution opportunities.
| 💬 Input | 📦 Output | |:---------|:----------| | "AI comic platform" | 6 SPEC modules · content pipeline · monetization · architecture | | "Permission management SaaS" | 8 SPEC modules · RBAC · multi-tenant · API contracts | | "Sentiment analysis tool" | 5 SPEC modules · data pipeline · model selection · alerts | | "Indie dev bookkeeping app" | 4 SPEC modules · local-first · sync · privacy compliance | | "Enterprise knowledge base" | 7 SPEC modules · RAG pipeline · permissions · indexing | | "Cross-border product picker" | 6 SPEC modules · data sources · scoring · competitor analysis |
┌─────────────────────────────────────────────────────────────────┐
│ 🌐 ENTRY Browser · Feishu Relay · Destination Input │
├─────────────────────────────────────────────────────────────────┤
│ 🖥️ FRONTEND 3D Scene · Task Cockpit · Route View │
│ Drive State · Takeover Panel · Replay │
├─────────────────────────────────────────────────────────────────┤
│ 🧠 CUBE BRAIN 10-Stage Workflow · Mission Runtime │
│ Dynamic Roles · Cost Governance · Review │
├─────────────────────────────────────────────────────────────────┤
│ 🔮 PROJECTION Mission→Destination · Workflow→Route │
│ State→DriveState · Decision→Takeover │
├─────────────────────────────────────────────────────────────────┤
│ 💡 INTELLIGENCE 3-Level Memory · Knowledge Graph · RAG │
│ Self-Evolution · LLM Multi-Provider │
├─────────────────────────────────────────────────────────────────┤
│ 🛡️ TRUST Hash-Chain Audit · Lineage DAG · Evidence │
├─────────────────────────────────────────────────────────────────┤
│ ⚙️ EXECUTION Docker Containers · HMAC · Sandbox · Terminal│
├─────────────────────────────────────────────────────────────────┤
│ 🔗 INTEROP A2A Protocol · Swarm · Guest Agent Market │
└─────────────────────────────────────────────────────────────────┘
| Layer | Technology | |:------|:-----------| | Frontend | React 19 · Vite · TypeScript · Zustand · Three.js (R3F) · Framer Motion | | Server | Express · Socket.IO · TypeScript | | AI | OpenAI-compatible API (any provider) | | Execution | Docker (dockerode) · Browser Runtime · Native Runtime | | Testing | Vitest · fast-check (PBT) | | Storage | IndexedDB (browser) · JSON (server) |
| Metric | Count | |:-------|------:| | Project files | 4,707 | | TypeScript/TSX files | 2,130 | | Lines of Typ