Skip to content
/
Tier B A12 UI passthrough

VibeDoc

vibedoc · JasonRobertDestiny/VibeDoc · ★ 373 · last commit 2025-11-21

Generate structured development plans from natural language descriptions in 60-180 seconds via a Gradio web UI, exportable to MD/Word/PDF/HTML for handoff to any AI coding tool.

Best whenThe bottleneck in vibe-coding is the gap between an idea and a structured spec — automate that gap with a web UI accessible to non-technical stakeholders, no…
Skip ifStarting to code without a written plan, Spending hours manually writing PRDs
vs seeds
spec-kitmanages them. vs. openspec: openspec generates API specs specifically; VibeDoc generat…
Primitive shape 2 total
Commands 2
00

Summary

vibedoc — Summary

Slug: vibedoc GitHub: https://github.com/JasonRobertDestiny/VibeDoc Stars: 373 License: MIT Language: Python Last commit: 2025-11-21

One-Liner

Gradio web app that takes a project idea or requirement as input and generates a structured development plan (exported to MD/Word/PDF/HTML) in 60-180 seconds using SiliconFlow's DeepSeek API — with 2 Claude Code commands for arrangement and deployment.

Archetype

Archetype 5 (Closed IDE-like surface with proprietary backend) mixed with Archetype 4 (Markdown scaffold). A standalone web application — not an agent harness for an IDE — that generates spec documents as its output. The 2 Claude Code commands are thin wrappers for deploying the app itself, not for agent behavior within Claude Code.

Key Facts

  • Install: pip install -r requirements.txt + python app.py → http://localhost:7860
  • Backend: SiliconFlow API (deepseek-ai/deepseek-v3 default) via SILICONFLOW_API_KEY
  • UI: Gradio 5.34.1, browser-based
  • Generation time: 60-180 seconds per development plan
  • Export formats: Markdown, Word (.docx), PDF, HTML
  • 2 Claude Code commands: arrange.md (organize docs), deploy.md (deploy app)
  • Docker support: Dockerfile + docker-compose.yml
  • Bilingual: Chinese primary (README), English README.zh.md
  • Origin: "MCP&Agent challenge 2025" contest entry
  • Key modules: app.py, prompt_optimizer.py, plan_editor.py, explanation_manager.py, enhanced_mcp_client.py, export_manager.py
01

Overview

vibedoc — Overview

What It Is

VibeDoc is a Gradio-based web application that converts a project idea or requirement description into a structured development plan. The user opens a browser tab (http://localhost:7860), types a description, and receives a formatted development plan 60-180 seconds later, exportable to Markdown, Word, PDF, or HTML.

The "vibe" framing signals its philosophy: turn the imprecise intuitions developers have about a project ("vibes") into concrete, shareable documentation.

Problem It Solves

Developers and teams struggle to translate high-level ideas into structured development plans. Writing PRDs, architecture documents, and implementation steps manually is slow. VibeDoc automates the spec-document generation step, producing a development plan that can be handed off to an AI coding assistant or a human team.

This positions VibeDoc as an upstream step in the AI development workflow — it generates the specs that other tools (like Claude Code) then execute.

Target User

  • Individual developers in the vibe-coding space who want faster project planning
  • Chinese developer community (primary README language is Chinese; SiliconFlow is a Chinese AI infrastructure provider)
  • MCP/Agent challenge participants (origin context: MCP&Agent contest 2025)

Key Technical Facts

  • Framework: Gradio 5.34.1
  • Backend LLM: SiliconFlow API (configurable via .env)
  • Default model: deepseek-ai/deepseek-v3
  • Port: 7860
  • Configuration: .env file with SILICONFLOW_API_KEY
  • Deployment: Docker-ready (Dockerfile + docker-compose.yml)

Positioning vs. Spec-Driven Seeds

  • Unlike spec-kit (a CLI for managing spec files), VibeDoc is a web UI for generating them
  • Unlike openspec (developer-facing CLI + MCP server), VibeDoc targets non-technical stakeholders who can describe requirements in natural language
  • Unlike spec-driver (enforces specs through test execution), VibeDoc generates specs and stops — no enforcement
  • Most similar to vibe-architect in this batch (both are web apps that generate spec documents), but VibeDoc uses a Chinese API backend (SiliconFlow/DeepSeek) vs. vibe-architect's multi-provider Western API support, and VibeDoc has no live preview capability

Honest Scope

VibeDoc is a spec generator, not an agent harness. The 2 Claude Code commands it includes (arrange.md, deploy.md) are utility commands for managing VibeDoc itself, not for driving AI-assisted development workflows. Once VibeDoc generates a plan, the user must take that plan and use it elsewhere.

02

Architecture

vibedoc — Architecture

High-Level Structure

vibedoc/
├── app.py                        # Gradio app entry point
├── config.py                     # Configuration (API keys, model settings)
├── export_manager.py             # Export to MD/Word/PDF/HTML
├── prompt_optimizer.py           # Prompt construction and optimization
├── explanation_manager.py        # Explanation/annotation generation
├── plan_editor.py                # Plan editing and refinement
├── enhanced_mcp_client.py        # MCP client integration (experimental)
├── requirements.txt              # Python dependencies
├── Dockerfile                    # Container definition
├── docker-compose.yml            # Container orchestration
├── .env                          # API key configuration (not committed)
├── .claude/
│   └── commands/
│       ├── arrange.md            # CC command: organize documentation
│       └── deploy.md             # CC command: deploy the app
└── AGENTS.md                     # Module organization + coding guidelines

Processing Pipeline

User input (text) 
    → prompt_optimizer.py (prompt construction)
    → SiliconFlow API call (deepseek-v3)
    → plan_editor.py (post-processing/refinement)
    → explanation_manager.py (annotations/explanations)
    → Gradio display
    → export_manager.py (on export request)
    → MD / Word / PDF / HTML file

Module Responsibilities

Module Responsibility
app.py Gradio UI definition, event handlers, main entry point
config.py Loads .env, sets API endpoints and model names
prompt_optimizer.py Builds prompts from user input; applies prompt engineering patterns
plan_editor.py Post-processes LLM output into structured plan format
explanation_manager.py Generates explanations/rationale for plan decisions
export_manager.py Converts plan to MD/docx/PDF/HTML (python-docx, reportlab, html2text)
enhanced_mcp_client.py Experimental MCP client for connecting VibeDoc to external tools

External Dependencies

  • SiliconFlow API — Chinese LLM infrastructure provider hosting DeepSeek and other models
  • Gradio 5.34.1 — web UI framework
  • python-docx — Word export
  • reportlab — PDF generation
  • html2text — HTML export

Configuration

All configuration via .env:

  • SILICONFLOW_API_KEY — required
  • Model selection configurable (default: deepseek-ai/deepseek-v3)
  • API base URL configurable (for self-hosted or alternative providers)

Claude Code Integration

Two CC commands in .claude/commands/:

  • arrange.md — utility for organizing generated documentation
  • deploy.md — utility for deploying the VibeDoc application

These are app management utilities, not spec-execution commands.

AGENTS.md

Defines module organization conventions and coding style guidelines for contributors. Not an agent orchestration file — it's a developer guide for working on VibeDoc itself.

03

Components

vibedoc — Components

Web Application (Gradio)

Framework: Gradio 5.34.1 Port: 7860 Entry point: python app.py

Gradio provides the complete browser UI — text input for project description, plan output display, export buttons, and optional refinement controls.

LLM Backend

Provider: SiliconFlow API (Chinese AI infrastructure) Default model: deepseek-ai/deepseek-v3 Integration: REST API calls via Python requests or openai-compatible SDK Configuration: SILICONFLOW_API_KEY in .env

The backend is swappable — config.py can be pointed at any OpenAI-compatible API endpoint.

Prompt Optimizer (prompt_optimizer.py)

Constructs structured prompts from the user's natural language input. Applies prompt engineering patterns to improve plan quality:

  • Adds context about the target output format
  • Injects constraints (plan must include X sections)
  • Handles multi-turn refinement prompts

Plan Editor (plan_editor.py)

Post-processes the LLM's raw output:

  • Parses structured sections from the response
  • Normalizes formatting
  • Handles incomplete or malformed outputs gracefully

Explanation Manager (explanation_manager.py)

Generates human-readable explanations or rationale for plan decisions. Adds an "explanation" layer on top of the generated plan — useful for communicating the reasoning behind architectural choices to stakeholders.

Export Manager (export_manager.py)

Converts the finalized plan into multiple formats:

Format Library
Markdown Built-in string output
Word (.docx) python-docx
PDF reportlab
HTML html2text

Enhanced MCP Client (enhanced_mcp_client.py)

An experimental module for connecting VibeDoc to external MCP servers. This suggests future intent to make VibeDoc a participant in a broader MCP ecosystem — potentially sending generated plans to other tools. Not the primary user-facing feature.

Claude Code Commands (2)

Command Purpose
.claude/commands/arrange.md Organize and arrange generated documentation
.claude/commands/deploy.md Deploy the VibeDoc application

Both are utility commands for managing VibeDoc itself, not for running agent workflows.

Docker Support

  • Dockerfile — multi-stage build for the Gradio app
  • docker-compose.yml — single-service compose for easy deployment

Enables teams to run VibeDoc as a shared team service rather than a local developer tool.

05

Prompts

vibedoc — Prompts & Instructions

Prompt Construction

prompt_optimizer.py is responsible for converting the user's natural language project description into an effective LLM prompt. While the exact prompt templates are implementation details, the module's purpose is to:

  • Add structured output format requirements ("generate a plan with sections: Overview, Architecture, Implementation Steps, Testing, Deployment")
  • Inject domain-specific context based on keywords in the user's description
  • Apply prompt engineering patterns to improve plan quality and consistency

AGENTS.md (Developer Guide)

VibeDoc includes an AGENTS.md file, but its purpose is different from other frameworks in this batch. In VibeDoc, AGENTS.md is a developer contribution guide that defines:

  • Module organization conventions (which module handles which concern)
  • Coding style guidelines for contributors
  • Architecture principles for maintaining VibeDoc itself

This is NOT an agent orchestration file — it doesn't define agents that an AI coding assistant should embody.

Claude Code Commands

arrange.md

A CC custom command for organizing and arranging the documentation that VibeDoc generates. When invoked in Claude Code, it helps structure output files into a consistent directory layout.

deploy.md

A CC custom command for deploying the VibeDoc application. Guides Claude Code through the steps to set up and launch VibeDoc in a target environment.

SiliconFlow API Configuration

Model selection and API behavior are configured in config.py:

  • Default: deepseek-ai/deepseek-v3 on SiliconFlow
  • Endpoint: SiliconFlow's OpenAI-compatible API base URL
  • Temperature, max tokens, and other generation parameters set in config

Explanation Layer

explanation_manager.py adds a second LLM call (or a post-processing pass) to generate human-readable explanations for key plan decisions. This is analogous to "chain-of-thought" reasoning made visible to the user — not just "use PostgreSQL" but "use PostgreSQL because your requirements include ACID transactions and relational data".

Language Handling

No explicit multi-language prompt engineering is documented, but the Chinese-primary README and SiliconFlow backend suggest the default prompts may be optimized for Chinese input. DeepSeek-v3 handles both Chinese and English natively.

09

Uniqueness

vibedoc — Uniqueness

Differs from Seeds

VibeDoc has no close analog in the 11 seeds. The seeds are all agent harnesses (bmad-method, taskmaster-ai, claude-flow), documentation scaffolds (claude-conductor, agent-os), or CLI tools (spec-kit, openspec, spec-driver). VibeDoc is none of these — it's a standalone web application that generates spec documents.

Specific comparisons:

  • vs. spec-kit (CLI spec file manager): VibeDoc generates specs; spec-kit manages them. Opposite ends of the pipeline.
  • vs. openspec (OpenAPI + MCP): openspec generates API specs specifically; VibeDoc generates full development plans for any type of project.
  • vs. spec-driver (test-driven spec enforcement): spec-driver enforces specs; VibeDoc creates them and stops.
  • vs. kiro (IDE-integrated spec workflow): kiro integrates with the IDE; VibeDoc is a separate web tool with no IDE integration.

Positioning

  • Target user: Developers in the Chinese tech ecosystem who want rapid development plan generation with a familiar SiliconFlow/DeepSeek API stack
  • Key differentiator: The only framework in this batch with a full browser UI for spec generation. Multi-format export (MD/Word/PDF/HTML) makes it suitable for generating documents for non-technical stakeholders.
  • Honest limitation: VibeDoc is an upstream spec generator, not a development workflow tool. Once it generates a plan, the user must take it and use it elsewhere — VibeDoc provides no execution, tracking, or enforcement.

The MCP Client Signal

The presence of enhanced_mcp_client.py is the most interesting signal in the codebase. It suggests the author's intent to evolve VibeDoc from a standalone web app into an MCP-enabled tool that can:

  1. Pull context from external sources (codebases, existing docs) before generating plans
  2. Send generated plans to downstream MCP-aware tools for execution

If this module matures, VibeDoc would shift from Archetype 4 (markdown scaffold) toward Archetype 3 (MCP-anchored toolserver) — making it a source-of-truth spec server rather than just a document generator.

Observable Failure Modes

  1. No execution layer — the gap between "generated plan" and "running code" is the user's problem
  2. SiliconFlow dependency — Chinese API provider; teams outside China may face latency, access restrictions, or regulatory concerns
  3. No plan versioning — no built-in way to track how a plan evolves through refinement iterations
  4. No test suite — README notes reliance on "reproducible manual runs"
  5. Contest origin — built for MCP&Agent challenge 2025; long-term maintenance motivation is unclear
  6. 373 stars but no release tags — stars likely from contest discovery, not sustained adoption
04

Workflow

vibedoc — Workflow

Primary User Workflow

1. Start VibeDoc: python app.py (or docker-compose up)
2. Open browser: http://localhost:7860
3. Enter project description (NL text)
4. Click "Generate Plan"
5. Wait 60-180 seconds
6. Review generated plan in browser
7. Optionally refine (re-prompt or edit in plan_editor)
8. Export to preferred format (MD / Word / PDF / HTML)
9. Take the exported plan and use it with Claude Code or other tools

No Automated Execution

VibeDoc stops at step 9. It generates the specification document but does not:

  • Execute the plan
  • Create Claude Code commands from the plan
  • Track progress against the plan
  • Integrate with git

The user is responsible for taking the generated plan and feeding it to an agent or team.

Plan Generation Pipeline

User description
    ↓ prompt_optimizer.py
    ↓ SiliconFlow API (deepseek-v3)
    ↓ plan_editor.py (structure)
    ↓ explanation_manager.py (rationale)
    ↓ Display in Gradio UI
    ↓ (optional) export_manager.py
    ↓ MD / Word / PDF / HTML

Refinement Loop

After initial plan generation, users can:

  1. Edit the plan directly in the Gradio text area (plan_editor.py)
  2. Ask VibeDoc to refine a specific section (re-prompt)
  3. Repeat until satisfied

Export Step

On export, export_manager.py converts the current plan state:

  • Markdown: direct text export
  • Word: python-docx template with headings, sections
  • PDF: reportlab with basic formatting
  • HTML: html2text conversion

Claude Code Integration Workflow

The 2 CC commands provide a secondary workflow for VibeDoc's own management:

/arrange — reorganizes documentation output into a structured directory /deploy — deploys the VibeDoc application (useful for team-shared instances)

These are not part of the plan-generation workflow.

Deployment Workflow

For teams wanting a shared VibeDoc instance:

  1. Set SILICONFLOW_API_KEY in environment
  2. docker-compose up -d
  3. Access at http://<host>:7860
  4. Team members share the URL

Relation to Downstream Workflows

Generated plans from VibeDoc can feed into:

  • Claude Code as AGENTS.md or CLAUDE.md content
  • taskmaster-ai as the initial PRD
  • speccrew as the PRD for iteration i001
  • Any other spec-driven workflow in this research corpus
06

Memory Context

vibedoc — Memory & Context

Memory Model

VibeDoc has no persistent memory. Each plan generation is a stateless one-shot operation:

  1. User input arrives
  2. LLM is called with user input + system prompt
  3. Plan is returned and displayed
  4. No state is saved automatically

Session State

Within a single browser session, Gradio maintains the current plan in the UI state. The plan_editor.py module allows in-session refinement. But this state is lost when the browser tab is closed or the app is restarted.

Export as Persistence

The export mechanism (MD/Word/PDF/HTML) is VibeDoc's persistence story: save the generated plan to a file. That file then becomes a document in the team's normal file management system. There's no VibeDoc-managed store.

Context Window Usage

For the LLM call:

  • Input: user's project description + system prompt from prompt_optimizer.py
  • Output: structured development plan
  • Typical context usage is small (single-turn, ~1-5k tokens input, 2-8k tokens output)

No context compaction is needed — VibeDoc doesn't accumulate context across turns.

Enhanced MCP Client (Experimental)

enhanced_mcp_client.py is an experimental module suggesting future intent to:

  • Connect VibeDoc to external MCP servers for additional context (e.g., codebase analysis)
  • Send generated plans to downstream MCP-aware tools

This is not yet a functional memory/context system — it's exploratory infrastructure.

No Agent Memory

VibeDoc is not an agent system. It has no concept of:

  • Session memory across conversations
  • Tool call history
  • Learned preferences per user
  • Project history

Each use is a fresh start.

07

Orchestration

vibedoc — Orchestration

Multi-Agent: No

VibeDoc is a single-agent, single-turn system. One LLM call produces the development plan. There is no agent team, no orchestration, no delegation.

Orchestration Pattern: None

No orchestration. The application flow is:

User → Gradio UI → prompt_optimizer → SiliconFlow API → plan_editor → UI display

This is a web application with an LLM call in the middle, not an agent orchestration system.

Execution Mode: One-shot

Each plan generation is a single LLM call (or a small fixed number of calls if the explanation manager adds a second pass). The user gets a complete output in one cycle.

Multi-Model: No

Single model: deepseek-ai/deepseek-v3 on SiliconFlow. Model is configurable via config.py but there's no model routing or multi-model workflow.

Auto-Validators: None

No automated validation of the generated plan. Quality is assessed by the human user who decides whether to export, refine, or discard the output.

Concurrency

Gradio supports multiple concurrent users by default (each in a separate browser session). But there's no agent concurrency — each user's session is independent and single-threaded from an LLM perspective.

Enhanced MCP Client

enhanced_mcp_client.py is an experimental module that could enable VibeDoc to orchestrate external MCP tools as part of plan generation. If implemented, it would allow VibeDoc to call external tools (e.g., "scan the codebase for existing patterns") before generating the plan. This is not currently the primary feature.

Crash Recovery: None

No automated recovery. If the Gradio session crashes during plan generation, the work is lost. The Docker deployment provides process-level restart via restart: always, but not application-level recovery.

Comparison to Other Batch Frameworks

VibeDoc is the simplest orchestration model in the batch:

  • trw-mcp: 12 agents, 6 phases, quorum consensus
  • claude-bootstrap: 13-tier model routing, parallel agents
  • speccrew: 8 agents, 7 phases, human gates
  • vibedoc: 1 LLM call, 0 agents, 0 phases

The simplicity is a feature — it minimizes setup and maximizes accessibility.

08

Ui Cli Surface

vibedoc — UI / CLI Surface

Local Web UI

Framework: Gradio 5.34.1 Port: 7860 URL: http://localhost:7860 Launch: python app.py

Gradio provides a full browser-based UI with:

  • Text input area for project description
  • "Generate Plan" button
  • Plan output display (rendered markdown)
  • Refinement controls (edit / re-generate sections)
  • Export buttons: MD, Word, PDF, HTML

No CLI Binary

VibeDoc has no dedicated CLI binary. The only CLI interaction is:

python app.py          # Start the Gradio server
docker-compose up -d   # Start containerized

There are no subcommands, no REPL, no non-UI mode.

Claude Code Commands (2)

These are utility commands for managing VibeDoc itself:

File Command Purpose
.claude/commands/arrange.md /arrange Organize generated documentation files
.claude/commands/deploy.md /deploy Deploy the VibeDoc application

These commands operate on VibeDoc's deployment artifacts, not on spec-driven development workflows.

Docker Interface

# docker-compose.yml
services:
  vibedoc:
    build: .
    ports:
      - "7860:7860"
    env_file: .env
    restart: always

Teams can deploy VibeDoc as a shared service accessible to all members at a shared URL.

UI vs. Vibe-Architect Comparison

Both vibedoc and vibe-architect (batch frameworks 4 and 10) are browser-based spec generators:

Feature vibe-architect vibedoc
Framework Next.js 16 Gradio 5.34
Port 3000 7860
LLM backend 5 providers / 12 models SiliconFlow (DeepSeek)
Live preview Yes (JSX sandbox) No
Voice input Yes (Whisper) No
Export None MD/Word/PDF/HTML
Primary language English Chinese
Origin Independent MCP&Agent contest 2025

Related frameworks

same archetype · same primary tool · same memory type

Goose (Block/AAIF) ★ 46k
A12 UI passthrough

General-purpose AI agent (not just code) with security-first tool inspection, recipe-based shareable configurations, and 15+ LLM…

Vibe Kanban ★ 27k
A12 UI passthrough

Eliminate the overhead of planning, switching between agent terminals, and reviewing diffs by providing a single web dashboard…

1Code ★ 5.5k
A12 UI passthrough

Cursor-like desktop experience for Claude Code and Codex with cloud background agents, event-driven automations, and a full…

Crystal (stravu) ★ 3.1k
A12 UI passthrough

Manage multiple parallel AI coding sessions in isolated git worktrees from a single desktop GUI.

Maestro (RunMaestro) ★ 3.0k
A12 UI passthrough

Orchestrate unlimited parallel AI agent sessions with a keyboard-first desktop app including Group Chat coordination and Auto Run…

AgentsMesh ★ 2.1k
A12 UI passthrough

Multi-tenant workforce platform that gives every team member a squad of AI coding agents coordinated through channels, pod…