Skip to content
/

Vibe Architect

vibe-architect · mohdhd/vibe-architect · ★ 34 · last commit 2026-02-17

Convert a raw app idea into a coding-agent-ready implementation spec through guided multi-phase conversation with live visual design previews.

Best whenAI should proactively propose concrete options (not ask open-ended questions) — the user is the Creative Director approving decisions, not generating them.
Skip ifAsking open-ended questions (What fonts? What database?), Auto-locking phases without explicit user confirmation
vs seeds
kiro's spec generation phase, but Vibe Architect is a standalone browser application with live React design previews, voice …
Primitive shape
No installable primitives
00

Summary

Vibe Architect — Summary

Vibe Architect is a Next.js 16 web application (deployable to Vercel) that converts a raw app idea into a coding-agent-ready implementation spec through a guided 4-phase conversation: Vision & Scope → Design System → Tech Stack → Implementation Spec. Each phase follows a Propose→Refine→Lock workflow where the AI proactively suggests concrete options (not open-ended questions) using multi-model LLM support (OpenAI GPT-5.2, Google Gemini 3, Anthropic Claude, Mistral, Zhipu GLM). Voice input via OpenAI Whisper API, live design system previews via Babel-transformed React JSX, and spec export to markdown ZIP files complete the experience. State is stored entirely in IndexedDB (browser-local, no backend), and API keys never leave the browser. This is a spec generation tool, not an agent harness — it produces the markdown spec that humans or coding agents then consume.

Differs from seeds: This framework has no equivalent in the 11 seeds. The closest analogy is the "planning" phase of kiro (requirements.md, design.md generation) or the PRD creation phase of taskmaster-ai, but Vibe Architect is a full browser application with a visual design preview sandbox — not a CLI tool, not a Claude Code plugin, not a markdown file set. It is a standalone web app that sits upstream of the coding pipeline, producing specs that any AI agent then consumes. Voice input and multi-model support are unique in the spec-generation category.

01

Overview

Vibe Architect — Overview

Origin

GitHub: mohdhd/vibe-architect (34 stars, 7 forks, MIT, TypeScript). Live demo at specs-gen.vercel.app. Author: mohdhd.

Philosophy

From README:

"AI-powered project spec generator — go from idea to implementation-ready spec in minutes. Multi-model support (GPT-5.2, Gemini 3, Claude), live design previews, voice input, and export to markdown."

The Propose → Refine → Lock workflow:

"The AI always asks for your confirmation before locking a phase and moving on." "You don't have to complete all steps. Stop at any phase when your plan feels complete."

Key features as stated:

  • Guided brainstorming: "The AI proposes concrete options (not open-ended questions)"
  • Live design previews: Real-time React component rendering
  • Voice input: Speak ideas, Whisper transcribes
  • Fully client-side: No backend, API calls direct to providers
  • Spec editor: Built-in markdown editor

Design Philosophy

  • User retains control at every gate (AI proposes, human approves, lock before advancing)
  • No vendor lock-in on LLM (BYOK, 5 providers)
  • Privacy-first (no backend, no analytics, keys in localStorage)
  • Stop at any phase — not a rigid pipeline

What It Produces

A coding-agent-ready markdown spec covering:

  1. MVP scope (features in/out)
  2. Visual identity / design system
  3. Tech stack recommendation
  4. Implementation spec with file structure and module breakdown

This spec is then handed to Claude Code, Copilot, Cursor, or any coding agent.

02

Architecture

Vibe Architect — Architecture

Distribution

  • Type: Web application (self-hosted or Vercel deploy)
  • Install: git clone + npm install + npm run dev or "Deploy with Vercel" one-click
  • License: MIT
  • Language: TypeScript (Next.js 16)
  • Live demo: https://specs-gen.vercel.app

Install

git clone https://github.com/mohdhd/vibe-architect.git
cd vibe-architect
npm install
npm run dev
# Open http://localhost:3000

Or one-click Vercel deploy.

Tech Stack

Layer Technology
Framework Next.js 16
UI React 19, Tailwind CSS 4
State Zustand
Persistence IndexedDB via idb-keyval
Markdown react-markdown + remark-gfm
Export JSZip + FileSaver
Voice Browser MediaRecorder + OpenAI Whisper API
Preview Sandbox Babel (runtime JSX) + React CDN

Project Structure

src/
  app/
    page.tsx              # Main page with layout
  components/
    chat-panel.tsx        # Chat interface
    sandbox-panel.tsx     # Design preview + spec editor
    settings-modal.tsx    # API key configuration
    export-modal.tsx      # Spec export dialog
    mic-button.tsx        # Voice input (Whisper)
    usage-guide.tsx       # First-time onboarding
  lib/
    llm-client.ts         # Multi-provider LLM streaming
    system-prompt.ts      # AI persona + workflow prompts
  store/
    project-store.ts      # Projects, conversations, specs (IndexedDB)
    settings-store.ts     # API keys, model selection (localStorage)
  types/
    index.ts              # TypeScript types + model configs

Supported Models

Provider Models
OpenAI GPT-5.2 (High/Medium/XHigh)
Google Gemini 3 Pro, Gemini 3 Flash
Anthropic Claude Opus 4.6, Claude Sonnet 4.5
Mistral Mistral Medium 3.1, Mistral Small 3.2
GLM (Zhipu AI) GLM-5, GLM-4.7, GLM-4.7 Flash, GLM-4.6, GLM-4.6V

Privacy Model

All API keys stored in browser localStorage. API calls go directly from browser to LLM providers. No backend server, no data collection.

Required Runtime

  • Node.js 18+
  • Browser (for voice: MediaRecorder API support)
03

Components

Vibe Architect — Components

Workflow Phases (4)

Phase What Happens
1. Vision & Scope Define MVP — AI suggests features to include and cut
2. Design System Pick visual identity from AI-proposed "vibes" with live previews
3. Tech Stack Opinionated, tailored stack recommendation
4. Implementation Spec Generate complete, coding-agent-ready markdown spec

Each phase follows Propose → Refine → Lock with human confirmation before advancing.

UI Components

Component Purpose
chat-panel.tsx Main chat interface for conversation with AI
sandbox-panel.tsx Right panel: design preview + spec editor
settings-modal.tsx API key configuration per provider
export-modal.tsx Export spec as markdown ZIP
mic-button.tsx Voice input — records via MediaRecorder, sends to Whisper
usage-guide.tsx First-time onboarding modal

Core Library Components

Module Purpose
lib/llm-client.ts Multi-provider streaming LLM client
lib/system-prompt.ts AI persona definition + 4-phase workflow prompts

State Stores (Zustand)

Store Contents
project-store.ts Projects, conversations, generated specs (IndexedDB)
settings-store.ts API keys, selected model (localStorage)

Export Formats

  1. Markdown ZIP — All generated spec files as .md, ready for any AI coding agent
  2. (Only markdown export confirmed in README)

Unique Capabilities

  • Live design sandbox: Babel transforms AI-generated React JSX at runtime for instant preview
  • Voice input: Browser microphone → MediaRecorder → WAV/MP3 → Whisper API → text in chat
  • Multi-provider streaming: Single llm-client.ts abstracts all 5 providers
  • Offline-capable: State in IndexedDB, no backend required
05

Prompts

Vibe Architect — Prompts

Excerpt 1: Full System Prompt (from src/lib/system-prompt.ts)

Technique: State-machine persona with explicit Propose→Refine→Lock loop, anti-question mandate, and <ui_preview> tag convention for live rendering.

export const SYSTEM_PROMPT = `<role>
You are the "Proactive Vibe Architect," an elite software architect and UI/UX visionary. You are the lead driver of this project. Your job is to take the user's raw app idea and proactively generate highly specific, opinionated proposals for the design system, product scope, and tech stack. 

The user is your Creative Director. They are here to approve, reject, or tweak your proposals. Do NOT force the user to come up with technical or design specifics from scratch. 
</role>

<core_loop>
For every phase of the brainstorming process, you must follow the "Propose -> Refine -> Ask to Lock -> Prompt Next" loop.
1. PROPOSE: Generate 2 to 3 highly specific, contrasting options based on the user's initial idea.
2. REFINE: Accept the user's feedback (e.g., "I like Option A, but make it darker").
3. ASK TO LOCK: When the user seems satisfied, explicitly ask: "Would you like to lock this phase and move on to the next one?" NEVER lock a phase automatically.
4. PROMPT NEXT: After the user confirms the lock, acknowledge it (e.g., "✅ Vision & Scope locked!"), give a brief summary, then preview the next phase.
</core_loop>

<instructions>
- NEVER ask open-ended questions like "What fonts do you want?" or "What database should we use?"
- ALWAYS do the heavy lifting. Give the user concrete options to react to.
- When generating design system options, ALWAYS include a <ui_preview> block with React code so the user can see a live visual.
- NEVER lock a phase on your own. ALWAYS ask the user "Would you like to lock this phase?" and wait for their explicit "yes" before locking.
- If the user says something like "looks good" or "I like it," that is NOT automatic approval to lock.
</instructions>`

Excerpt 2: Design System Phase Prompt

Technique: Anti-vague-question mandate + concrete token output format + live preview convention.

<state_2_design_system>
Goal: Establish the "Anti-Slop" visual identity.
Action: Do not ask the user what colors they want. Propose 3 distinct Design System "Vibes". For each, provide:
- A stylistic name (e.g., "Neo-Brutalist", "Hyper-Minimal Apple-esque", "Dark Mode Cyberpunk").
- Exact Typography (e.g., Space Grotesk for headers, Inter for body).
- Semantic Color Tokens (Base, Primary Action, Accent) with exact Hex codes.
- Component anatomy (e.g., "Harsh 2px black borders, no shadows").

When presenting design options, wrap each option's preview code in <ui_preview> tags so the user can see a live visual preview. The code inside MUST be plain React (no import/export statements). For example:
<ui_preview>
function DesignPreview() {
  return (
    <div style={{ background: '#09090B', padding: '2rem', color: '#fafafa' }}>
      <h1 style={{ fontFamily: 'Space Grotesk', fontSize: '2rem' }}>Option A: Neo-Brutalist</h1>
      <button style={{ background: '#fafafa', color: '#09090B', padding: '0.75rem 1.5rem', border: 'none', cursor: 'pointer' }}>
        Primary Action
      </button>
    </div>
  );
}
</ui_preview>
</state_2_design_system>

Excerpt 3: Spec Generation Phase

Technique: Output format specification with delimiters for downstream consumption by coding agents.

<state_4_spec_generation>
Goal: Output the Markdown implementation plan.
Action: Once the user has signed off on the Vision, Design, and Stack, automatically generate the rigorous, coding-agent-ready Markdown files. Structure the output as four clearly delimited sections with headers: @01-vision.md, @02-design.md, @03-stack.md, @04-implementation.md.
</state_4_spec_generation>
09

Uniqueness

Vibe Architect — Uniqueness

Differs from Seeds

No seed framework matches Vibe Architect's category. It is a spec generation web application that sits upstream of the entire coding pipeline — it produces the spec that seeds like kiro, openspec, and spec-driver then consume. The closest analogy within the seeds is kiro's requirements.md / design.md generation phase, but kiro is an IDE that also handles implementation; Vibe Architect does only spec generation. Compared to SPEC-KIT (the seed for comparison): SPEC-KIT ships CLI commands that run within a coding session; Vibe Architect is a standalone web app with live design previews, voice input, and multi-model BYOK support — completely outside the IDE. The <ui_preview> tag convention + Babel JSX sandbox is unique across the entire corpus.

Positioning

  • Category: Pre-coding spec generator (upstream tool)
  • Target user: Product managers, solo founders, developers who want to think through a project before opening an IDE
  • Key differentiator: Live React design previews in a browser — no other framework in the corpus lets you see a rendered design system before committing to it
  • Voice input: Only framework in the batch with voice-to-spec capability (Whisper-powered)
  • Multi-model: 5 providers, 12 models — broadest model support in the batch

Observable Failure Modes

  1. OpenAI dependency for voice: Voice input requires an OpenAI API key even if using Gemini or Claude for chat — Whisper is OpenAI-only
  2. Context window limits: No compaction handling — if a project conversation gets long, provider limits apply without graceful degradation
  3. Browser-only persistence: IndexedDB state lost if browser data cleared; no export-on-close prompt
  4. Spec quality ceiling: Output quality depends entirely on the LLM; the state machine structure helps but doesn't validate spec completeness
  5. No integration with coding agents: Spec is exported as a ZIP; user must manually inject into their coding workflow (no direct GitHub/IDE integration)

Novel Pattern

The <ui_preview> tag convention is novel: the system prompt instructs the AI to wrap React component code in <ui_preview> tags, and sandbox-panel.tsx detects these tags and renders them via Babel at runtime. This creates a feedback loop where the AI generates visual UI code and the user sees it rendered immediately in the same interface — not a pattern present in any seed or batch framework.

04

Workflow

Vibe Architect — Workflow

User Journey

Open app → Settings (add API keys)
    ↓
Start conversation (or voice input)
    ↓
Phase 1: Vision & Scope
  AI proposes MVP features → user refines → Lock
    ↓
Phase 2: Design System  
  AI proposes visual "vibes" → live React preview → user selects → Lock
    ↓
Phase 3: Tech Stack
  AI recommends stack → user confirms → Lock
    ↓
Phase 4: Implementation Spec
  AI generates full markdown spec
    ↓
Export (markdown ZIP)
    ↓
Hand off to coding agent (Claude Code, Cursor, Copilot, etc.)

Approval Gates

  1. Phase 1 Lock: User confirms MVP scope before design phase
  2. Phase 2 Lock: User selects design system before stack recommendation
  3. Phase 3 Lock: User confirms tech stack before spec generation
  4. Each lock is explicit — AI asks for confirmation, does not auto-advance

Phase to Artifact Map

Phase Artifact
Vision & Scope Feature list (in/out), MVP definition
Design System Visual identity spec, color palette, typography
Tech Stack Technology selection with rationale
Implementation Spec Complete markdown spec with file structure
Export ZIP of markdown spec files

Voice Input Flow

  1. User clicks mic button
  2. Browser MediaRecorder captures audio
  3. Audio sent to OpenAI Whisper API
  4. Transcribed text inserted into chat input
  5. User reviews and submits

Design Preview Flow

  1. AI generates React component code in response
  2. sandbox-panel.tsx detects JSX in response
  3. Babel (browser) transforms JSX at runtime
  4. Component renders in preview iframe with React from CDN
  5. User sees live design before accepting

Spec Editor

The sandbox-panel.tsx includes a built-in markdown editor for editing generated specs before export.

06

Memory Context

Vibe Architect — Memory & Context

State Storage

  • Type: IndexedDB (browser-native)
  • Persistence scope: Browser session (project-local)
  • Library: idb-keyval

State Files

Store Contents
project-store (IndexedDB) Projects, conversations, generated specs
settings-store (localStorage) API keys, selected model

What Is Persisted

  • All conversation history within a project
  • Generated spec files for each phase
  • Project name and metadata
  • User's phase progression state (which phases are locked)

Memory Model

The application is a single-page React app with Zustand stores backed by IndexedDB. There is no server-side memory, no user accounts, and no cross-browser persistence.

The conversation history IS the memory — the full chat including AI responses is stored in IndexedDB and replayed to the LLM on continuation. Context window limits apply per provider.

Context Injection

The SYSTEM_PROMPT from system-prompt.ts is sent with every request. Phase-specific prompts are injected when phases are locked, instructing the LLM to generate spec documents from the conversation so far.

Compaction Handling

None. When context window is exceeded, the LLM provider returns an error. No automatic compaction, summarization, or truncation in the client.

Cross-Session Handoff

Within browser: Yes (IndexedDB persists). Cross-device: No. Export to markdown ZIP enables cross-session handoff by transferring the spec files.

Privacy

API keys stored only in localStorage. No data sent to any server other than the selected LLM provider directly. The app has no backend.

07

Orchestration

Vibe Architect — Orchestration

Multi-Agent: No

Single LLM session. No agent spawning, no parallel execution. One conversation, one model at a time.

Orchestration Pattern: Sequential

Linear 4-phase state machine: Vision → Design → Stack → Spec. Each phase blocks on human lock confirmation.

Isolation Mechanism: None

Browser application. No code execution, no file system access.

Execution Mode: Interactive-loop

User-driven conversation. The AI proposes; the user responds. Not a CLI tool, not a background process.

Multi-Model: Yes

User-selectable per session via settings modal:

  • OpenAI: GPT-5.2 (High/Medium/XHigh)
  • Google: Gemini 3 Pro, Gemini 3 Flash
  • Anthropic: Claude Opus 4.6, Claude Sonnet 4.5
  • Mistral: Mistral Medium 3.1, Mistral Small 3.2
  • GLM (Zhipu AI): GLM-5, GLM-4.7, GLM-4.6, GLM-4.6V (vision)

All models supported for all phases via the unified llm-client.ts streaming client.

Model Role Mapping

No role-based routing. One model handles all phases within a session. User can switch model between sessions.

Auto-Validators

None. This is a spec generation tool, not a code quality tool. No tests, linting, or validation.

TDD Enforcement

Not applicable.

Git Automation

Not applicable. The tool outputs markdown spec files; git integration is outside scope.

Consensus Mechanism: None

Prompt Chaining: Yes

Phase 1 output (MVP scope) → Phase 2 input context. Phase 2 output (design system) → Phase 3 context. Each phase's locked output feeds the next phase's prompt context via conversation history.

Voice Input

Optional input method (not multimodal generation). The mic-button.tsx captures voice → Whisper API transcription → text in chat. Only supported on models where text input is applicable.

Cross-Tool Portability: High

The output is plain markdown spec files that any coding agent (Claude Code, Cursor, Copilot, ChatGPT) can consume. The tool itself is model-agnostic via BYOK.

08

Ui Cli Surface

Vibe Architect — UI / CLI Surface

CLI Binary

None. This is a web application, not a CLI tool.

Local Web Dashboard

  • Exists: Yes — this IS the tool (a web app)
  • Type: web-dashboard
  • Port: 3000 (local dev)
  • Tech stack: Next.js 16, React 19, Tailwind CSS 4
  • Live demo: https://specs-gen.vercel.app

UI Layout

Two-panel interface:

  1. Left panel (chat-panel.tsx): Conversation with AI architect
  2. Right panel (sandbox-panel.tsx): Live design preview + spec editor

Key UI Features

  • Chat interface: Streaming responses from selected LLM
  • Live design preview: Babel-transforms AI-generated React code for instant visual rendering
  • Voice input: Mic button → MediaRecorder → Whisper API transcription
  • Spec editor: Built-in markdown editor for spec refinement
  • Export modal: Download spec as markdown ZIP
  • Settings modal: Per-provider API key management
  • Onboarding modal: First-time usage guide
  • Phase progression indicator: Visual state machine display

Voice Input

  • Browser MediaRecorder API captures audio
  • Audio sent to OpenAI Whisper API (requires OpenAI API key even if using other model for chat)
  • Transcribed text inserted into chat input
  • User reviews before submitting

Export

  • Format: Markdown ZIP with 4 files:
    • @01-vision.md
    • @02-design.md
    • @03-stack.md
    • @04-implementation.md
  • Library: JSZip + FileSaver

Deployment

  • Self-hosted: npm run dev or npm run build + start
  • Vercel: One-click deploy button in README
  • Docker: Not provided

Related frameworks

same archetype · same primary tool · same memory type

Context-Engineering Handbook ★ 9.0k

Provides a first-principles, research-grounded vocabulary and learning path for context engineering — the discipline of designing…

walkinglabs/learn-harness-engineering ★ 6.6k

Teach harness engineering from first principles (12 lectures + 6 projects) and provide a scaffolding skill (harness-creator) that…

Awesome Harness Engineering (walkinglabs) ★ 2.7k

Curate the authoritative reference list of articles, benchmarks, and tools for harness engineering — the practice of shaping the…

cline-memory-bank (nickbaumann98) ★ 581

Custom instructions + 6-file hierarchical Markdown memory bank so Cline maintains full project context across sessions, with a…

FPF (First Principles Framework) ★ 372

Provides a formal pattern language for making reasoning explicit, traceable, and publishable in mixed human/AI engineering work —…

nexu-io/harness-engineering-guide ★ 134

Provide a practical, code-first reference guide to harness engineering — from first principles to production patterns —…