Skip to content
/

Vibook (pinqy520)

roo-code-vibook · pinqy520/roo-code-vibook · ★ 16 · last commit 2025-05-13

Generate an AI-optimized documentation knowledge base for any existing codebase to enable efficient AI-assisted development and maintenance.

Best whenDocumentation that describes the project and rules that instruct the AI are fundamentally different artifacts and must be kept separate.
Skip ifUsing traditional documentation formats instead of AI-optimized metadata-tagged docs, Conflating project documentation with AI behavioral instructions
vs seeds
bmad-methodit has no personas. The closest conceptual parallel is claude-conductor's structured markdown templates, but Vibook gene…
Primitive shape
No installable primitives
00

Summary

Vibook (pinqy520) — Summary

Vibook is a Roo Code methodology that generates an AI-optimized documentation system ("knowledge base") for any existing codebase, enabling AI coding assistants to efficiently understand, navigate, and develop within legacy or complex projects. Rather than shipping a fixed set of rules, Vibook ships a single Roo Code prompt (ROO-PROMPT-EN.md) that the user pastes into Roo Code's architect or orchestrator mode; the prompt interactively guides the AI to analyze the project and create a structured docs/ directory with AI-readable metadata tags, navigation indexes, module documentation, and rule files. A minimal .roomodes file ships one helper mode (prompt-engineer). The framework's core insight is the separation between documentation (describes the project, lives in docs/) and rule files (instructs the AI how to work, lives in .roo/). Vibook differs from the agent-os seed (Archetype 4 — markdown scaffold) in that it bootstraps documentation from live code analysis via an interactive conversational setup flow, rather than shipping static templates; it differs from BMAD-METHOD in having no named sub-agent personas and no spec workflow, focusing entirely on knowledge-base construction.

01

Overview

Vibook (pinqy520) — Overview

Origin

Created by pinqy520 (GitHub user), first published around 2025. The repository roo-code-vibook is described as "The living knowledge base behind Vibe Coding." The creator is also the author of the Revas library (a React-based Canvas 2D UI library), and Vibook was born from the need to work with that legacy codebase using AI assistance.

Philosophy

From the README:

"Vibook creates an 'AI-understandable' knowledge network that helps AI coding assistants (Roo Code) efficiently maintain existing projects."

The framework draws a conceptual distinction:

  • Documentation Library (docs/) — describes the project; for AI to understand the codebase
  • Rule Files (.roo/ + .roomodes) — instructs the AI how to work; independent of documentation

Key capabilities the system targets:

Capability Implementation
Understand project Directory organization + relationship mapping
Locate information Metadata tags + importance markers
Comprehend intent Contextual marking system
Develop features Module implementation details
Troubleshoot issues Clear documentation navigation paths

Manifesto-Style Quotes

From ROO-PROMPT-EN.md:

"Unlike traditional documentation, this system is specifically optimized for AI tools, creating an 'AI-understandable' knowledge network through structured metadata and tagging systems, significantly enhancing AI assistant development efficiency and code quality."

"The documentation library (docs/) describes the project, while rule files are instructions guiding how AI assistants should work. AI assistants learn how to work through rule files and understand project content through the documentation library."

Target Audience

Developers working on existing (especially legacy) projects who want AI coding assistants to understand the codebase deeply rather than hallucinating about it. Particularly suited for projects that haven't been updated in years or use older dependencies.

Demonstration Case

The README showcases using Vibook to upgrade the Revas library (4 years dormant, React 17, outdated tooling) by first generating a documentation knowledge base, then performing the upgrade via AI assistance.

02

Architecture

Vibook (pinqy520) — Architecture

Distribution Type

template-bundle — the repository ships prompt files and minimal Roo mode configs. The user runs the prompts to generate project-specific documentation.

Install

# No installer — copy/paste the prompt
1. Install Roo Code with Claude 3.7 Sonnet or Gemini 2.5 Pro
2. Switch to 'architect' mode (small/medium project) or 'orchestrator' mode (large project)
3. Copy content from ROO-PROMPT-EN.md (or ROO-PROMPT.md for Chinese)
4. Paste into Roo Code chat and answer configuration questions

Source Repository Structure

roo-code-vibook/
├── .roo/
│   └── rules/
│       └── rules.md         # Single rule: "Use perplexity to inquire about unfamiliar information"
├── .roomodes                # Contains 'prompt-engineer' mode definition
├── README.md
├── README.zh.md
├── ROO-PROMPT-EN.md         # English setup prompt (main deliverable)
└── ROO-PROMPT.md            # Chinese setup prompt

Documentation System Generated In Target Project

After running the setup prompt, the target project gains:

<project>/
├── docs/
│   ├── ai-index/
│   │   ├── overview.md
│   │   ├── navigation-guide.md
│   │   └── documentation-guide.md
│   ├── architecture/
│   │   ├── system-overview.md
│   │   └── tech-stack.md
│   ├── modules/             # Per-module docs (generated from code analysis)
│   ├── dev-guides/
│   │   ├── setup.md
│   │   └── troubleshooting.md
│   ├── tasks/
│   │   └── current-task-plan.md
│   └── maintenance/
│       └── changelog.md
└── .roo/
    ├── rules/               # Generated mode collaboration rules
    └── [mode-specific rule files]

Project-type-specific additions (frontend, backend, CLI, etc.) are determined interactively.

Required Runtime

  • Roo Code extension (VS Code)
  • Claude 3.7 Sonnet or Gemini 2.5 Pro recommended

Target AI Tools

  • Roo Code (primary — uses .roomodes and .roo/rules/)
  • Mode collaboration features: architect or orchestrator mode

Config Files

  • .roomodes — defines prompt-engineer helper mode
  • .roo/rules/rules.md — single global rule (use Perplexity for unknowns)
03

Components

Vibook (pinqy520) — Components

Prompt Files (main deliverables)

File Purpose
ROO-PROMPT-EN.md English version of the full interactive setup prompt (~large file). When pasted into Roo Code, guides the AI through an 8-step documentation system setup.
ROO-PROMPT.md Chinese version of the same prompt.

Roo Mode Definitions

File Mode Description
.roomodes prompt-engineer Helper mode for designing, optimizing, and evaluating AI prompts. Has read + edit + MCP access.

Rule Files

File Purpose
.roo/rules/rules.md Single global rule: "Use perplexity to inquire about unfamiliar information."

Generated Artifacts (created by running the prompt)

The prompt instructs Roo Code to generate:

Artifact Description
docs/ai-index/overview.md System overview for AI navigation
docs/ai-index/navigation-guide.md Document navigation guide
docs/ai-index/documentation-guide.md Documentation standards guide
docs/architecture/system-overview.md Architecture overview
docs/architecture/tech-stack.md Technology stack details
docs/modules/<module>.md Per-module documentation (generated from code analysis)
docs/dev-guides/setup.md Environment setup guide
docs/dev-guides/troubleshooting.md Troubleshooting guide
docs/tasks/current-task-plan.md Current task plan
docs/maintenance/changelog.md Changelog
.roo/ rule files Mode collaboration rules and MCP usage scenarios
.roomodes Custom mode configurations for project-specific modes

MCP Servers

None bundled. The single rule mentions Perplexity as an external MCP tool, but no MCP config is shipped.

Scripts

None.

Hooks

None.

Total Component Count

  • Prompts: 2 (EN + ZH)
  • Modes: 1 (prompt-engineer)
  • Rules: 1 (global)
  • Scripts: 0
  • MCP servers: 0
05

Prompts

Vibook (pinqy520) — Prompts

Excerpt 1: Core Conceptual Framework (from ROO-PROMPT-EN.md)

## Key Concepts and Relationships

Please clearly understand the following key concepts and their relationships:

1. **Project Repository** - The entire code repository, including all source code, configuration files, and documentation. This is the top-level concept.

2. **Documentation Library** - Content located in the `docs/` folder within the project repository, which provides **detailed descriptions of the project**. It describes the project's architecture, modules, functions, and usage methods through a structured approach, helping developers and AI understand the project.

3. **Rule Files** - Including files in the `.roo/` directory of the project repository and the `.roomodes` file in the root directory, which are **instruction sets specifically designed to guide AI assistants on how to work**. Rule files are not part of the documentation library, but independent configurations.

4. **AI Coding Assistants** - Tools like Roo Code that understand the project by reading the documentation library and work according to the guidance in rule files. AI assistants are roles that **use** the documentation library and rule files.

> **Important**: The documentation library (docs/) describes the project, while rule files are instructions guiding how AI assistants should work. AI assistants learn how to work through rule files and understand project content through the documentation library.

Prompting technique: Explicit concept hierarchy with bold terminology definitions and a bold warning callout. The distinction between "documentation library" (project knowledge) and "rule files" (AI behavioral instructions) is the core mental model the prompt installs in the AI before any action.


Excerpt 2: Task Overview Section (from ROO-PROMPT-EN.md)

## Task Overview

1. **Deeply analyze current project**: Comprehensively understand the project architecture, implementation mechanisms of core modules, key code logic, and scan project directories, code, and existing documentation
2. **Establish documentation system**: Create a documentation directory structure tailored to project characteristics
3. **Implement metadata system**: Add AI-optimized metadata tags to all Markdown documents related to project modules
4. **Create core documents**: Establish navigation and index documents
5. **Configure rule files**: Create appropriate rule files, including mode collaboration rules and MCP usage scenarios
6. **Set up custom modes**: Create specific functional modes (e.g., test and summary)
7. **Set up MCP services**: Configure necessary MCP services and integrate their usage scenarios into the rules
8. **Integrate existing content**: Incorporate existing content into the new documentation structure

Prompting technique: Numbered imperative task list with bold phase names. Each task is a discrete, verifiable action. The ordering is significant: analyze before structuring, structure before populating, configure after the knowledge base exists.


Excerpt 3: Global Rule File (.roo/rules/rules.md)

Use `perplexity` to inquire about unfamiliar information.

Prompting technique: Minimalist single-sentence rule. The entire behavioral rule file is one line. This relies entirely on the Roo Code global rules loading mechanism — the rule applies to all modes and instructs the AI to use Perplexity MCP (if available) for any information gap.


Excerpt 4: Prompt-Engineer Mode Definition (.roomodes)

{
  "customModes": [
    {
      "slug": "prompt-engineer",
      "name": "📄 Prompt Engineer",
      "roleDefinition": "You are an expert Prompt Engineer specializing in designing, optimizing and evaluating AI prompts. You possess deep understanding of different AI models' capabilities, limitations and response patterns, and can craft precisely structured instructions that produce consistent, accurate and contextually appropriate outputs. Your expertise extends to prompt chain design, complex reasoning frameworks, and technical documentation of prompt systems.",
      "groups": ["read", "edit", "mcp"],
      "source": "project"
    }
  ]
}

Prompting technique: Expertise declaration with capability enumeration. The mode is scoped to the project (not global), with full read/edit/MCP access.

09

Uniqueness

Vibook (pinqy520) — Uniqueness

Differs From Seeds

Closest seed is agent-os (Archetype 4 — markdown scaffold), which also ships documentation templates that serve as the AI's working context. However, Vibook differs in a critical dimension: it is generative rather than prescriptive. Agent-os ships fixed standards/ content for the user to populate; Vibook ships a setup prompt that causes the AI to analyze the actual codebase and generate project-specific documentation. The output is tailored to the existing code structure, not a generic template.

Compared to kiro (spec-driven workflow with requirements/design/tasks files), Vibook has no spec workflow and makes no attempt to drive feature development; it is purely focused on understanding maintenance, not planning new features.

Compared to BMAD-METHOD (persona-driven agent roles), Vibook has no personas and no multi-agent orchestration — it is a single-agent knowledge base generator.

The framework is unique in the corpus for its explicit documentation/rules duality concept: it names and enforces the distinction between "documentation that describes the project" and "rules that instruct the AI."

Positioning

  • Niche: Legacy or complex projects where the AI needs project-specific context beyond what the codebase itself conveys
  • Key differentiator: Generates AI-readable documentation from the existing code rather than requiring the human to write it
  • Limitation: Only generates the knowledge base once (or on re-run); does not automatically keep docs in sync as code changes

Observable Failure Modes

  1. Documentation drift — generated docs/ becomes stale as code evolves; no automated sync mechanism
  2. Over-generated docs — for large projects, the AI may generate verbose or redundant module docs
  3. Single-mode dependency — the setup prompt only works well in Roo Code's architect/orchestrator modes; other tools won't use the .roo/ rules
  4. Perplexity rule without MCP — the single global rule references Perplexity, which won't work unless Perplexity MCP is separately configured

Cross-References

  • Shares Roo Code targeting with roomodes-sellisd and james-cherished-roo-community in this batch
  • Documentation-generation approach is philosophically adjacent to what claude-conductor (seed) does, but Vibook generates from code analysis rather than shipping fixed error/task ledger templates
04

Workflow

Vibook (pinqy520) — Workflow

Setup Workflow (one-time per project)

Phase Step Artifact
1 Deep project analysis AI reads all source code + existing docs
2 Project type determination Classification: frontend / backend / CLI / fullstack / other
3 Directory structure design Custom docs/ tree based on project type
4 Metadata system implementation Add AI-optimized metadata tags to all module .md docs
5 Core document creation docs/ai-index/ navigation and index files
6 Rule file configuration Mode collaboration rules + MCP usage scenarios
7 Custom mode setup Project-specific Roo Code modes (e.g., test, summary)
8 MCP service integration Configure MCP services and integrate into rules
9 Existing content integration Migrate existing docs into new structure

Approval Gates

The setup prompt is interactive: the user answers questions at each phase. The prompt explicitly states "answer questions to set up documentation system." Each major decision (directory structure, project type, MCP services) requires user confirmation.

Ongoing Usage Workflow

After setup, the workflow is:

  1. Developer starts task in Roo Code
  2. Roo Code reads docs/ai-index/overview.md to understand project structure
  3. Uses module docs to locate relevant code
  4. Implements change with context from documentation
  5. Documentation may be updated as part of the task

Re-configuration

Running the setup prompt again ("Adjust" step in README) allows reconfiguring the documentation system.

Phase-to-Artifact Map

Phase Primary Artifact
Analysis (none — read-only scan)
Project classification (decision output)
Doc structure docs/ directory skeleton
Metadata Updated .md files with YAML frontmatter tags
Core docs docs/ai-index/*.md
Rules .roo/rules/ files
Custom modes .roomodes additions
MCP config .roo/mcp.json (if applicable)
Content migration Populated docs/modules/*.md
06

Memory Context

Vibook (pinqy520) — Memory & Context

State Storage

All state is stored in the project's docs/ directory as plain Markdown files. No database, no vector store, no external service.

Documentation as Memory

The generated documentation system functions as the AI's persistent memory for the project:

Memory Layer Storage Location Content
System overview docs/ai-index/overview.md High-level project structure
Navigation guide docs/ai-index/navigation-guide.md How to find information
Module knowledge docs/modules/*.md Per-module implementation details
Architecture facts docs/architecture/*.md Tech stack, component relationships
Current task state docs/tasks/current-task-plan.md In-progress task tracking
Change history docs/maintenance/changelog.md What changed and when

Metadata System

Module documents include AI-optimized metadata tags (exact format is set up interactively, but the prompt describes "importance markers" and "contextual markers" for each document).

Persistence

Project-scoped. The docs/ directory is committed to version control with the codebase.

Context Handoff

When starting a new Roo Code session, the AI reads docs/ai-index/overview.md and docs/ai-index/navigation-guide.md first to orient itself. This is the handoff mechanism — the documentation library serves as the AI's memory across sessions.

Compaction

No automated compaction. The documentation grows as the project evolves.

Cross-Session Strategy

The documentation library itself is the cross-session handoff artifact. The prompt instructs the AI to maintain and update docs as part of ongoing development work.

07

Orchestration

Vibook (pinqy520) — Orchestration

Multi-Agent Pattern

None. Vibook is a single-agent framework. The setup prompt runs in one Roo Code session.

However, the README notes:

  • Small/medium projects: use architect mode
  • Large projects: use orchestrator mode

The orchestrator mode in Roo Code can spawn sub-agents, but Vibook itself does not define or coordinate them — it relies on Roo Code's built-in orchestration.

Execution Mode

interactive-loop during setup (user answers questions); one-shot per subsequent task.

Isolation

None. All operations happen in the working tree.

Multi-Model Routing

None defined. Uses whatever model is configured in Roo Code.

Prompt Chaining

Weak prompt chaining: the setup prompt's output (generated docs/ structure) becomes context for future sessions. This is a file-mediated chain rather than a within-session chain.

Mode Collaboration (Vibook's Concept)

The setup prompt creates a "Mode Collaboration System" documented in the project's rule files. From the README architecture diagram:

flowchart LR
  [architect mode] --> [knowledge base] --> [code mode]
  [orchestrator mode] --> [knowledge base] --> [multiple modes]

The knowledge base (docs/) acts as the coordination layer between modes.

Consensus

None.

Subagent Spawn Mechanism

None defined by Vibook. Deferred to Roo Code's orchestrator mode capabilities.

08

Ui Cli Surface

Vibook (pinqy520) — UI / CLI Surface

Dedicated CLI Binary

None.

Local Web Dashboard

None.

IDE Integration

Roo Code (VS Code extension) is the sole runtime:

  • .roomodes adds the prompt-engineer mode to Roo Code's mode switcher
  • .roo/rules/rules.md provides a global rule

User Interface

The entire interaction is via Roo Code's chat interface. The setup prompt is a conversational document — the user pastes it and the AI asks questions interactively.

Setup Surface

  1. User opens Roo Code in architect or orchestrator mode
  2. User pastes content from ROO-PROMPT-EN.md (or Chinese equivalent)
  3. AI asks project configuration questions
  4. AI generates documentation files autonomously
  5. User reviews generated structure

Observability

  • The generated docs/maintenance/changelog.md acts as an activity log
  • The docs/tasks/current-task-plan.md tracks current work
  • No structured audit log beyond these files

Languages

Bilingual: English (ROO-PROMPT-EN.md) and Chinese (ROO-PROMPT.md). The README itself is bilingual.

Related frameworks

same archetype · same primary tool · same memory type

BMAD-METHOD ★ 48k

Provides a full agile delivery lifecycle with named expert-persona AI collaborators that elicit the human's best thinking rather…

Agent OS ★ 4.6k

Extracts implicit codebase conventions into token-efficient markdown standards files and injects them selectively into AI agent…

Claude Conductor ★ 367

Gives Claude Code a persistent, cross-linked, auto-analyzed documentation system so it retains codebase context across sessions.

Spec-Driver (Greenfield Spec-Driven Development) ★ 25

Prevents spec rot in AI-assisted development by making implementation changes flow back into evergreen, authoritative specs via…

Anthropic Knowledge Work Plugins ★ 16k

Role-specialized plugin bundles with live MCP connectors that turn Claude into a domain expert for enterprise knowledge workers.

Codex Integration for Claude Code (skill-codex) ★ 1.3k

Single Claude Code skill that handles Codex CLI invocation correctly (stdin blocking, thinking token suppression, session resume)…