import{_ as a,c as n,o as s,a0 as t}from"./chunks/framework.FdfEk_gD.js";const g=JSON.parse('{"title":"Architecture","description":"","frontmatter":{},"headers":[],"relativePath":"dev/ARCHITECTURE.md","filePath":"dev/ARCHITECTURE.md"}'),i={name:"dev/ARCHITECTURE.md"};function o(r,e,l,p,c,h){return s(),n("div",null,[...e[0]||(e[0]=[t(`<h1 id="architecture" tabindex="-1">Architecture <a class="header-anchor" href="#architecture" aria-label="Permalink to &quot;Architecture&quot;">​</a></h1><p>This document provides detailed information about the Responsible Vibe MCP Server architecture, components, and design principles.</p><h2 id="information-architecture" tabindex="-1">Information Architecture <a class="header-anchor" href="#information-architecture" aria-label="Permalink to &quot;Information Architecture&quot;">​</a></h2><p>Responsible-Vibe-MCP implements a <strong>plan-file-centric information architecture</strong> with clear separation of responsibilities across different components:</p><h3 id="information-component-responsibilities" tabindex="-1">Information Component Responsibilities <a class="header-anchor" href="#information-component-responsibilities" aria-label="Permalink to &quot;Information Component Responsibilities&quot;">​</a></h3><table tabindex="0"><thead><tr><th><strong>Component</strong></th><th><strong>Responsibility</strong></th><th><strong>Information Type</strong></th><th><strong>Maintenance</strong></th></tr></thead><tbody><tr><td><strong>System Prompt</strong></td><td>Generic workflow guidance</td><td>How to use the system</td><td>Static</td></tr><tr><td><strong>Tool Descriptions</strong></td><td>Generic tool usage</td><td>What each tool does</td><td>Static</td></tr><tr><td><strong>Tool Responses</strong></td><td>Dynamic phase guidance</td><td>What to do right now</td><td>Dynamic</td></tr><tr><td><strong>Plan File</strong></td><td>Project context &amp; tasks</td><td>What we&#39;ve done/decided</td><td>LLM-maintained</td></tr></tbody></table><h3 id="core-principles" tabindex="-1">Core Principles <a class="header-anchor" href="#core-principles" aria-label="Permalink to &quot;Core Principles&quot;">​</a></h3><h4 id="_1-static-components-stay-generic" tabindex="-1"><strong>1. Static Components Stay Generic</strong> <a class="header-anchor" href="#_1-static-components-stay-generic" aria-label="Permalink to &quot;**1. Static Components Stay Generic**&quot;">​</a></h4><ul><li><strong>System Prompt</strong>: Workflow-agnostic instructions on tool usage patterns</li><li><strong>Tool Descriptions</strong>: Generic tool purposes without hardcoded phase names</li><li><strong>Benefit</strong>: Works with any workflow (built-in or custom)</li></ul><h4 id="_2-dynamic-guidance-through-tool-responses" tabindex="-1"><strong>2. Dynamic Guidance Through Tool Responses</strong> <a class="header-anchor" href="#_2-dynamic-guidance-through-tool-responses" aria-label="Permalink to &quot;**2. Dynamic Guidance Through Tool Responses**&quot;">​</a></h4><ul><li><strong>Tool responses provide</strong>: Phase-specific instructions, user interaction guidance, completion criteria</li><li><strong>Plan-file-referential</strong>: &quot;Check your plan file&#39;s Design section for current tasks&quot;</li><li><strong>Context-aware</strong>: Adapts to current project state and progress</li></ul><h4 id="_3-plan-file-as-single-source-of-truth" tabindex="-1"><strong>3. Plan File as Single Source of Truth</strong> <a class="header-anchor" href="#_3-plan-file-as-single-source-of-truth" aria-label="Permalink to &quot;**3. Plan File as Single Source of Truth**&quot;">​</a></h4><ul><li><strong>Contains</strong>: Task lists per phase, key decisions, project context</li><li><strong>Structure</strong>: Simple, LLM-maintainable (no complex dynamic elements)</li><li><strong>Purpose</strong>: Task tracker and decision log, not workflow guide</li></ul><h4 id="_4-clear-separation-of-concerns" tabindex="-1"><strong>4. Clear Separation of Concerns</strong> <a class="header-anchor" href="#_4-clear-separation-of-concerns" aria-label="Permalink to &quot;**4. Clear Separation of Concerns**&quot;">​</a></h4><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>System Prompt: &quot;How to use tools&quot;</span></span>
<span class="line"><span>Tool Descriptions: &quot;What tools do&quot; (generic)</span></span>
<span class="line"><span>Tool Responses: &quot;Check plan file section X, work on tasks Y, Z&quot; (specific)</span></span>
<span class="line"><span>Plan File: &quot;[ ] Task 1  [x] Task 2  Decision: chose approach A&quot; (tracking)</span></span></code></pre></div><h3 id="benefits-of-this-architecture" tabindex="-1">Benefits of This Architecture <a class="header-anchor" href="#benefits-of-this-architecture" aria-label="Permalink to &quot;Benefits of This Architecture&quot;">​</a></h3><ul><li><strong>✅ Workflow Flexibility</strong>: Static components work with any workflow type</li><li><strong>✅ Maintainable</strong>: No hardcoded workflow information in static descriptions</li><li><strong>✅ User Transparency</strong>: Users see the same plan file the LLM follows</li><li><strong>✅ Consistent Guidance</strong>: All dynamic instructions come from tool responses</li><li><strong>✅ Simple Maintenance</strong>: LLM only updates simple task lists and decisions</li></ul><h2 id="monorepo-architecture" tabindex="-1">Monorepo Architecture <a class="header-anchor" href="#monorepo-architecture" aria-label="Permalink to &quot;Monorepo Architecture&quot;">​</a></h2><p>Responsible-Vibe-MCP is organized as a monorepo with clear package separation and dependency management:</p><h3 id="package-structure" tabindex="-1">Package Structure <a class="header-anchor" href="#package-structure" aria-label="Permalink to &quot;Package Structure&quot;">​</a></h3><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>@codemcp/workflows/</span></span>
<span class="line"><span>├── packages/</span></span>
<span class="line"><span>│   ├── core/                    # @codemcp/workflows-core</span></span>
<span class="line"><span>│   │   ├── src/                 # Core functionality (state machine, workflow management, database)</span></span>
<span class="line"><span>│   │   └── dist/                # Compiled TypeScript output</span></span>
<span class="line"><span>│   ├── mcp-server/              # @codemcp/workflows-server</span></span>
<span class="line"><span>│   │   ├── src/                 # MCP server implementation and tool handlers</span></span>
<span class="line"><span>│   │   └── dist/                # Compiled server with bundled dependencies</span></span>
<span class="line"><span>│   ├── cli/                     # @codemcp/workflows-cli</span></span>
<span class="line"><span>│   │   ├── src/                 # CLI tools and main entry point</span></span>
<span class="line"><span>│   │   └── dist/                # CLI executables</span></span>
<span class="line"><span>│   ├── visualizer/              # @codemcp/workflows-visualizer</span></span>
<span class="line"><span>│   │   ├── src/                 # Vue.js workflow visualization component</span></span>
<span class="line"><span>│   │   └── dist/                # Built component for reuse</span></span>
<span class="line"><span>│   └── docs/                    # @codemcp/workflows-docs</span></span>
<span class="line"><span>│       ├── .vitepress/          # VitePress documentation site</span></span>
<span class="line"><span>│       └── dev/                 # Developer documentation</span></span>
<span class="line"><span>├── resources/                   # Workflow definitions and templates</span></span>
<span class="line"><span>└── pnpm-workspace.yaml         # Monorepo configuration</span></span></code></pre></div><h3 id="package-dependencies" tabindex="-1">Package Dependencies <a class="header-anchor" href="#package-dependencies" aria-label="Permalink to &quot;Package Dependencies&quot;">​</a></h3><div class="language-mermaid vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">mermaid</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">graph TD</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    CLI[CLI Package] --&gt; Core[Core Package]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    MCP[MCP Server] --&gt; Core</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    Visualizer[Visualizer] --&gt; Core</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    Docs[Documentation] --&gt; Visualizer</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    CLI --&gt; MCP</span></span></code></pre></div><h3 id="key-architectural-benefits" tabindex="-1">Key Architectural Benefits <a class="header-anchor" href="#key-architectural-benefits" aria-label="Permalink to &quot;Key Architectural Benefits&quot;">​</a></h3><ul><li><strong>🔧 Separation of Concerns</strong>: Each package has a single, well-defined responsibility</li><li><strong>📦 Independent Deployment</strong>: Packages can be built and tested independently</li><li><strong>🔄 Workspace Dependencies</strong>: Development uses workspace imports for type safety</li><li><strong>📱 Dual Import Strategy</strong>: Published packages use relative imports for Node.js compatibility</li><li><strong>🎯 CLI as Main Entry</strong>: CLI package serves as the main entry point, routing to MCP server or CLI functionality</li></ul><h3 id="build-system" tabindex="-1">Build System <a class="header-anchor" href="#build-system" aria-label="Permalink to &quot;Build System&quot;">​</a></h3><ul><li><strong>Turbo</strong>: Orchestrates builds across packages with dependency awareness</li><li><strong>TypeScript</strong>: Shared configuration via <code>tsconfig.base.json</code></li><li><strong>PNPM Workspaces</strong>: Efficient dependency management and linking</li><li><strong>Independent Testing</strong>: Each package can run its own test suite</li></ul><h3 id="publishing-strategy" tabindex="-1">Publishing Strategy <a class="header-anchor" href="#publishing-strategy" aria-label="Permalink to &quot;Publishing Strategy&quot;">​</a></h3><p>The monorepo publishes as a single <code>@codemcp/workflows</code> package containing all built packages, maintaining backward compatibility while providing the benefits of modular development.</p><h2 id="static-architecture" tabindex="-1">Static Architecture <a class="header-anchor" href="#static-architecture" aria-label="Permalink to &quot;Static Architecture&quot;">​</a></h2><div class="language-mermaid vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">mermaid</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">graph TB</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    subgraph &quot;Vibe Feature MCP Server&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        CM[Conversation Manager]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        TM[Transition Engine]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        IM[Instruction Generator]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        PM[Plan Manager]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        FS[(FileStorage)]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    end</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    subgraph &quot;Development Phases&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        IDLE[Idle]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        REQ[Requirements]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        DES[Design]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        IMP[Implementation]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        QA[Quality Assurance]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        TEST[Testing]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        COMP[Complete]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    end</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    subgraph &quot;Persistent Storage&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        STATEFILE[.vibe/conversations/{id}/state.json]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        LOGFILE[.vibe/conversations/{id}/interactions.jsonl]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        PF[Project Plan Files]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        GIT[Git Repository Context]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    end</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    subgraph &quot;LLM Client&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        LLM[LLM Application]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        USER[User]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        CWD[Current Working Directory]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    end</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    USER --&gt; LLM</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    LLM --&gt; CM</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    CM --&gt; FS</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    CM --&gt; TM</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    TM --&gt; IM</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    IM --&gt; PM</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    FS --&gt; STATEFILE</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    FS --&gt; LOGFILE</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    PM --&gt; PF</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    CM --&gt; GIT</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    IDLE --&gt; TM</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    REQ --&gt; TM</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    DES --&gt; TM</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    IMP --&gt; TM</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    QA --&gt; TM</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    TEST --&gt; TM</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    COMP --&gt; TM</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    IM --&gt; LLM</span></span></code></pre></div><h2 id="core-building-blocks" tabindex="-1">Core Building Blocks <a class="header-anchor" href="#core-building-blocks" aria-label="Permalink to &quot;Core Building Blocks&quot;">​</a></h2><h3 id="_1-conversation-manager" tabindex="-1">1. <strong>Conversation Manager</strong> <a class="header-anchor" href="#_1-conversation-manager" aria-label="Permalink to &quot;1. **Conversation Manager**&quot;">​</a></h3><p>The Conversation Manager handles conversation identification, state persistence, and coordination between components.</p><p><strong>Responsibilities:</strong></p><ul><li>Generate unique conversation identifiers from project path + git branch</li><li>Load and persist conversation state from/to database</li><li>Coordinate state updates across components</li><li>Handle conversation lifecycle (creation, updates, cleanup)</li><li>Provide conversation-scoped state isolation</li><li>Manage project-specific development context</li></ul><p><strong>Key Features:</strong></p><ul><li><strong>Project-Aware Identification</strong>: Uses absolute project path + current git branch as conversation identifier</li><li><strong>Git Integration</strong>: Automatically detects git branch changes and creates separate conversation contexts</li><li><strong>Stateless Operation</strong>: Does not store conversation history, relies on LLM-provided context</li><li><strong>Multi-Project Support</strong>: Handles multiple concurrent project conversations</li><li><strong>State Validation</strong>: Ensures state consistency and handles corrupted state recovery</li><li><strong>Context Processing</strong>: Analyzes LLM-provided conversation summary and recent messages</li></ul><h3 id="_2-transition-engine" tabindex="-1">2. <strong>Transition Engine</strong> <a class="header-anchor" href="#_2-transition-engine" aria-label="Permalink to &quot;2. **Transition Engine**&quot;">​</a></h3><p>The Transition Engine manages the development state machine and determines appropriate phase transitions.</p><p><strong>Responsibilities:</strong></p><ul><li>Analyze user input and conversation context</li><li>Determine current development phase</li><li>Evaluate phase completion criteria</li><li>Trigger phase transitions based on conversation analysis</li><li>Implement development state machine logic</li></ul><p><strong>Key Features:</strong></p><ul><li><strong>Context Analysis</strong>: Processes LLM-provided conversation summary and recent messages</li><li><strong>Phase Detection</strong>: Intelligently determines appropriate development phase</li><li><strong>Transition Logic</strong>: Implements rules for phase progression and regression</li><li><strong>Completion Assessment</strong>: Evaluates when phases are sufficiently complete</li><li><strong>State Machine Management</strong>: Handles the core development workflow logic</li></ul><h3 id="_3-instruction-generator" tabindex="-1">3. <strong>Instruction Generator</strong> <a class="header-anchor" href="#_3-instruction-generator" aria-label="Permalink to &quot;3. **Instruction Generator**&quot;">​</a></h3><p>The Instruction Generator creates phase-specific guidance for the LLM based on current conversation state.</p><p><strong>Responsibilities:</strong></p><ul><li>Generate contextual instructions for each development phase</li><li>Customize instructions based on project context and history</li><li>Provide task completion guidance</li><li>Generate plan file update instructions</li></ul><p><strong>Key Features:</strong></p><ul><li><strong>Phase-Specific Guidance</strong>: Tailored instructions for each development phase</li><li><strong>Context-Aware Customization</strong>: Adapts instructions based on project type and history</li><li><strong>Task Management</strong>: Provides clear guidance on task completion and progress tracking</li><li><strong>Plan File Integration</strong>: Ensures consistent plan file updates and maintenance</li></ul><h3 id="_4-plan-manager" tabindex="-1">4. <strong>Plan Manager</strong> <a class="header-anchor" href="#_4-plan-manager" aria-label="Permalink to &quot;4. **Plan Manager**&quot;">​</a></h3><p>The Plan Manager handles the creation, updating, and maintenance of project development plan files.</p><p><strong>Responsibilities:</strong></p><ul><li>Generate and maintain markdown plan files</li><li>Track task completion and progress</li><li>Manage plan file structure and content</li><li>Handle plan file versioning per git branch</li></ul><p><strong>Key Features:</strong></p><ul><li><strong>Markdown Generation</strong>: Creates structured development plans in markdown format</li><li><strong>Progress Tracking</strong>: Maintains task completion status and project progress</li><li><strong>Branch-Aware Plans</strong>: Separate plan files for different git branches when needed</li><li><strong>Template Management</strong>: Consistent plan file structure across projects</li></ul><h3 id="_5-file-based-persistence" tabindex="-1">5. <strong>File-Based Persistence</strong> <a class="header-anchor" href="#_5-file-based-persistence" aria-label="Permalink to &quot;5. **File-Based Persistence**&quot;">​</a></h3><p>The persistence layer provides transparent, human-readable storage for conversation state and interaction logs.</p><p><strong>Storage Structure:</strong></p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>.vibe/</span></span>
<span class="line"><span>  conversations/</span></span>
<span class="line"><span>    {conversationId}/</span></span>
<span class="line"><span>      state.json          - Conversation state (JSON)</span></span>
<span class="line"><span>      interactions.jsonl  - Interaction logs (one JSON per line)</span></span></code></pre></div><p><strong>State File Format (state.json):</strong></p><ul><li><strong>conversationId</strong>: Unique identifier based on project path + git branch</li><li><strong>projectPath</strong>: Absolute path to the project</li><li><strong>gitBranch</strong>: Current git branch name</li><li><strong>currentPhase</strong>: Current workflow phase</li><li><strong>planFilePath</strong>: Path to the development plan file</li><li><strong>workflowName</strong>: Name of the active workflow</li><li><strong>gitCommitConfig</strong>: Git commit behavior configuration (optional)</li><li><strong>requireReviewsBeforePhaseTransition</strong>: Review requirements flag</li><li><strong>createdAt</strong>, <strong>updatedAt</strong>: Timestamps</li></ul><p><strong>Key Features:</strong></p><ul><li><strong>Transparent Storage</strong>: Human-readable JSON files for easy inspection</li><li><strong>Persistent State</strong>: Survives server restarts and system reboots</li><li><strong>Graceful Degradation</strong>: Handles user file manipulation (edits, deletions)</li><li><strong>Atomic Writes</strong>: Uses temp file + rename pattern for data safety</li><li><strong>Automatic Migration</strong>: Detects and migrates legacy SQLite databases on first run</li><li><strong>Isolated Storage</strong>: Each conversation has its own directory</li></ul><p><strong>Migration Support:</strong></p><p>The system automatically detects legacy SQLite databases (<code>conversation.sqlite</code> or <code>conversation-state.sqlite</code>) and migrates them to the file-based structure on first initialization. Original SQLite files are backed up with timestamps before migration.</p><h2 id="dynamic-behavior" tabindex="-1">Dynamic Behavior <a class="header-anchor" href="#dynamic-behavior" aria-label="Permalink to &quot;Dynamic Behavior&quot;">​</a></h2><div class="language-mermaid vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">mermaid</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">sequenceDiagram</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    participant User as User</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    participant LLM as LLM</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    participant SM as State Manager</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    participant CM as Conversation Manager</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    participant FS as FileStorage</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    participant TM as Transition Engine</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    participant IM as Instruction Generator</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    participant PM as Plan Manager</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    participant Files as File System</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    User-&gt;&gt;LLM: &quot;implement auth&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    LLM-&gt;&gt;CM: whats_next(context, user_input, conversation_summary, recent_messages)</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    Note over LLM,CM: Server stores NO message history - LLM provides context</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    CM-&gt;&gt;Files: detect project path + git branch</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    CM-&gt;&gt;FS: lookup/create conversation state</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    FS--&gt;&gt;CM: conversation state (phase, plan path only)</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    CM-&gt;&gt;TM: analyze phase transition</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    TM-&gt;&gt;TM: analyze LLM-provided context</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    TM-&gt;&gt;TM: evaluate current phase</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    TM--&gt;&gt;CM: phase decision</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    CM-&gt;&gt;IM: generate instructions</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    IM-&gt;&gt;FS: get project context</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    IM--&gt;&gt;CM: phase-specific instructions</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    CM-&gt;&gt;PM: update plan file path</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    PM--&gt;&gt;CM: plan file location</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    CM-&gt;&gt;FS: update conversation state (phase only)</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    CM--&gt;&gt;LLM: instructions + metadata</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    LLM-&gt;&gt;User: follow instructions</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    LLM-&gt;&gt;Files: update plan file</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    Note over User,Files: Cycle continues with each user interaction</span></span></code></pre></div><h2 id="data-flow-architecture" tabindex="-1">Data Flow Architecture <a class="header-anchor" href="#data-flow-architecture" aria-label="Permalink to &quot;Data Flow Architecture&quot;">​</a></h2><h3 id="_1-conversation-identification-flow" tabindex="-1">1. <strong>Conversation Identification Flow</strong> <a class="header-anchor" href="#_1-conversation-identification-flow" aria-label="Permalink to &quot;1. **Conversation Identification Flow**&quot;">​</a></h3><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>User Input → Project Detection → Git Branch Detection → Conversation ID Generation → FileStorage Lookup</span></span></code></pre></div><h3 id="_2-state-management-flow" tabindex="-1">2. <strong>State Management Flow</strong> <a class="header-anchor" href="#_2-state-management-flow" aria-label="Permalink to &quot;2. **State Management Flow**&quot;">​</a></h3><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>Conversation ID → State Retrieval → Context Analysis → Phase Determination → State Update → File Persistence</span></span></code></pre></div><h3 id="_3-instruction-generation-flow" tabindex="-1">3. <strong>Instruction Generation Flow</strong> <a class="header-anchor" href="#_3-instruction-generation-flow" aria-label="Permalink to &quot;3. **Instruction Generation Flow**&quot;">​</a></h3><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>Current Phase → Project Context → Conversation History → Instruction Template → Customized Instructions</span></span></code></pre></div><h3 id="_4-plan-file-management-flow" tabindex="-1">4. <strong>Plan File Management Flow</strong> <a class="header-anchor" href="#_4-plan-file-management-flow" aria-label="Permalink to &quot;4. **Plan File Management Flow**&quot;">​</a></h3><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>Project Path → Branch Detection → Plan File Path → Content Generation → File Updates → Progress Tracking</span></span></code></pre></div><h2 id="key-architectural-principles" tabindex="-1">Key Architectural Principles <a class="header-anchor" href="#key-architectural-principles" aria-label="Permalink to &quot;Key Architectural Principles&quot;">​</a></h2><h3 id="_1-project-centric-design" tabindex="-1">1. <strong>Project-Centric Design</strong> <a class="header-anchor" href="#_1-project-centric-design" aria-label="Permalink to &quot;1. **Project-Centric Design**&quot;">​</a></h3><ul><li>Each project maintains independent conversation state</li><li>Git branch awareness enables feature-specific development tracking</li><li>Plan files remain within project directories for easy access</li></ul><h3 id="_2-persistent-state-management" tabindex="-1">2. <strong>Persistent State Management</strong> <a class="header-anchor" href="#_2-persistent-state-management" aria-label="Permalink to &quot;2. **Persistent State Management**&quot;">​</a></h3><ul><li>File-based storage ensures state survives server restarts</li><li>Conversation history enables context-aware decision making</li><li>Storage isolated per conversation in <code>.vibe/conversations/</code> directory</li><li>Automatic migration from legacy SQLite databases</li></ul><h3 id="_3-phase-driven-workflow" tabindex="-1">3. <strong>Phase-Driven Workflow</strong> <a class="header-anchor" href="#_3-phase-driven-workflow" aria-label="Permalink to &quot;3. **Phase-Driven Workflow**&quot;">​</a></h3><ul><li>Clear separation between development phases</li><li>Phase-specific instructions guide LLM behavior</li><li>Transition logic ensures appropriate workflow progression</li></ul><h3 id="_4-conversation-continuity" tabindex="-1">4. <strong>Conversation Continuity</strong> <a class="header-anchor" href="#_4-conversation-continuity" aria-label="Permalink to &quot;4. **Conversation Continuity**&quot;">​</a></h3><ul><li>Long-term memory across multiple LLM interactions</li><li>Context preservation enables complex, multi-session development</li><li>History tracking supports learning and improvement</li></ul><h3 id="_5-git-integration" tabindex="-1">5. <strong>Git Integration</strong> <a class="header-anchor" href="#_5-git-integration" aria-label="Permalink to &quot;5. **Git Integration**&quot;">​</a></h3><ul><li>Branch-aware conversation management</li><li>Separate development contexts for different features</li><li>Integration with existing git workflows</li></ul><h3 id="_6-flexible-documentation-architecture" tabindex="-1">6. <strong>Flexible Documentation Architecture</strong> <a class="header-anchor" href="#_6-flexible-documentation-architecture" aria-label="Permalink to &quot;6. **Flexible Documentation Architecture**&quot;">​</a></h3><ul><li><strong>Optional Documentation</strong>: Workflows can specify whether formal documentation is required</li><li><strong>Conditional References</strong>: Workflows adapt instructions based on document availability</li><li><strong>Workflow-Specific Requirements</strong>: <code>requiresDocumentation</code> metadata flag controls documentation enforcement</li><li><strong>Backward Compatibility</strong>: Existing workflows default to optional documentation</li></ul><h2 id="optional-documentation-architecture" tabindex="-1">Optional Documentation Architecture <a class="header-anchor" href="#optional-documentation-architecture" aria-label="Permalink to &quot;Optional Documentation Architecture&quot;">​</a></h2><p>The system supports flexible documentation requirements to accommodate both comprehensive and lightweight development approaches:</p><h3 id="documentation-requirement-levels" tabindex="-1">Documentation Requirement Levels <a class="header-anchor" href="#documentation-requirement-levels" aria-label="Permalink to &quot;Documentation Requirement Levels&quot;">​</a></h3><table tabindex="0"><thead><tr><th><strong>Workflow Type</strong></th><th><strong>requiresDocumentation</strong></th><th><strong>Behavior</strong></th><th><strong>Examples</strong></th></tr></thead><tbody><tr><td><strong>Comprehensive</strong></td><td><code>true</code></td><td>Documentation setup required before workflow start</td><td>greenfield, waterfall, c4-analysis</td></tr><tr><td><strong>Lightweight</strong></td><td><code>false</code> (default)</td><td>Skip documentation setup, proceed directly</td><td>epcc, minor, bugfix</td></tr></tbody></table><h2 id="scalability-considerations" tabindex="-1">Scalability Considerations <a class="header-anchor" href="#scalability-considerations" aria-label="Permalink to &quot;Scalability Considerations&quot;">​</a></h2><h3 id="_1-multi-project-support" tabindex="-1">1. <strong>Multi-Project Support</strong> <a class="header-anchor" href="#_1-multi-project-support" aria-label="Permalink to &quot;1. **Multi-Project Support**&quot;">​</a></h3><ul><li>Concurrent handling of multiple project conversations</li><li>Isolated state prevents cross-project interference</li><li>Efficient database indexing for fast project lookups</li></ul><h3 id="_2-performance-optimization" tabindex="-1">2. <strong>Performance Optimization</strong> <a class="header-anchor" href="#_2-performance-optimization" aria-label="Permalink to &quot;2. **Performance Optimization**&quot;">​</a></h3><ul><li>SQLite provides fast local storage with minimal overhead</li><li>Conversation state caching reduces database queries</li><li>Efficient git branch detection minimizes system calls</li></ul><h3 id="_3-storage-management" tabindex="-1">3. <strong>Storage Management</strong> <a class="header-anchor" href="#_3-storage-management" aria-label="Permalink to &quot;3. **Storage Management**&quot;">​</a></h3><ul><li>Automatic cleanup of old conversation states</li><li>Plan file management within project boundaries</li><li>Database maintenance and optimization capabilities</li></ul><h2 id="integration-points" tabindex="-1">Integration Points <a class="header-anchor" href="#integration-points" aria-label="Permalink to &quot;Integration Points&quot;">​</a></h2><h3 id="_1-llm-integration" tabindex="-1">1. <strong>LLM Integration</strong> <a class="header-anchor" href="#_1-llm-integration" aria-label="Permalink to &quot;1. **LLM Integration**&quot;">​</a></h3><ul><li>Single <code>whats_next</code> tool interface</li><li>JSON-based instruction delivery</li><li>Context-aware response generation</li></ul><h3 id="_2-file-system-integration" tabindex="-1">2. <strong>File System Integration</strong> <a class="header-anchor" href="#_2-file-system-integration" aria-label="Permalink to &quot;2. **File System Integration**&quot;">​</a></h3><ul><li>Plan file creation and management</li><li>Project directory detection</li><li>Git repository integration</li></ul><h3 id="_3-development-tool-integration" tabindex="-1">3. <strong>Development Tool Integration</strong> <a class="header-anchor" href="#_3-development-tool-integration" aria-label="Permalink to &quot;3. **Development Tool Integration**&quot;">​</a></h3><ul><li>Compatible with existing development workflows</li><li>Non-intrusive plan file placement</li><li>Standard markdown format for universal compatibility</li></ul><h2 id="state-machine" tabindex="-1">State Machine <a class="header-anchor" href="#state-machine" aria-label="Permalink to &quot;State Machine&quot;">​</a></h2><p>The server operates as a state machine that transitions between development phases. While workflows typically follow a linear progression, <strong>users can transition directly to any phase at any time</strong> using the <code>proceed_to_phase</code> tool.</p><p>For a comprehensive reference of all state transitions, including detailed instructions and transition reasons, see <a href="./TRANSITIONS.html">TRANSITIONS.md</a>.</p><h2 id="logging-and-debugging" tabindex="-1">Logging and Debugging <a class="header-anchor" href="#logging-and-debugging" aria-label="Permalink to &quot;Logging and Debugging&quot;">​</a></h2><p>The server includes comprehensive logging with configurable levels for debugging, monitoring, and troubleshooting:</p><h3 id="log-levels" tabindex="-1">Log Levels <a class="header-anchor" href="#log-levels" aria-label="Permalink to &quot;Log Levels&quot;">​</a></h3><ul><li><strong>DEBUG</strong>: Detailed tracing and execution flow</li><li><strong>INFO</strong>: Success operations and important milestones (default)</li><li><strong>WARN</strong>: Expected errors and recoverable issues</li><li><strong>ERROR</strong>: Caught but unexpected errors</li></ul><h3 id="configuration" tabindex="-1">Configuration <a class="header-anchor" href="#configuration" aria-label="Permalink to &quot;Configuration&quot;">​</a></h3><p>Set the log level using the <code>LOG_LEVEL</code> environment variable:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Debug level (most verbose)</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">LOG_LEVEL</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">DEBUG</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> npx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> tsx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> src/index.ts</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Production level</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">LOG_LEVEL</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">INFO</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> node</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dist/index.js</span></span></code></pre></div><h3 id="log-components" tabindex="-1">Log Components <a class="header-anchor" href="#log-components" aria-label="Permalink to &quot;Log Components&quot;">​</a></h3><ul><li><strong>Server</strong>: Main server operations and tool handlers</li><li><strong>FileStorage</strong>: File operations and state persistence</li><li><strong>Migration</strong>: SQLite to file-based migration operations</li><li><strong>ConversationManager</strong>: Conversation context management</li><li><strong>TransitionEngine</strong>: Phase transition analysis</li><li><strong>PlanManager</strong>: Plan file operations</li></ul><p>For detailed logging documentation, see <a href="./LOGGING.html">LOGGING.md</a>.</p><h2 id="interaction-logging" tabindex="-1">Interaction Logging <a class="header-anchor" href="#interaction-logging" aria-label="Permalink to &quot;Interaction Logging&quot;">​</a></h2><p>Responsible Vibe MCP includes a comprehensive interaction logging system that records all tool calls and responses for debugging and analysis purposes:</p><h3 id="logged-information" tabindex="-1">Logged Information <a class="header-anchor" href="#logged-information" aria-label="Permalink to &quot;Logged Information&quot;">​</a></h3><ul><li><strong>Tool Calls</strong>: All calls to <code>whats_next</code> and <code>proceed_to_phase</code> tools</li><li><strong>Input Parameters</strong>: Complete request parameters for each tool call</li><li><strong>Response Data</strong>: Complete response data returned to the LLM</li><li><strong>Current Phase</strong>: Development phase at the time of the interaction</li><li><strong>Timestamp</strong>: When the interaction occurred</li><li><strong>Conversation ID</strong>: Which conversation the interaction belongs to</li></ul><h3 id="data-storage" tabindex="-1">Data Storage <a class="header-anchor" href="#data-storage" aria-label="Permalink to &quot;Data Storage&quot;">​</a></h3><p>All interaction logs are stored in JSONL format (one JSON object per line) in the <code>.vibe/conversations/{conversationId}/interactions.jsonl</code> file within your project. The data is stored without masking or filtering, as it is kept locally on your system.</p><p><strong>File Location</strong>: <code>.vibe/conversations/{conversationId}/interactions.jsonl</code></p><h3 id="querying-logs" tabindex="-1">Querying Logs <a class="header-anchor" href="#querying-logs" aria-label="Permalink to &quot;Querying Logs&quot;">​</a></h3><p>Logs can be accessed directly as JSONL files at <code>.vibe/conversations/{conversationId}/interactions.jsonl</code>. Each line is a valid JSON object representing one interaction. You can use standard text tools (<code>cat</code>, <code>grep</code>, <code>jq</code>) to analyze the logs.</p><p><strong>Example:</strong></p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># View all interactions for a conversation</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">cat</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .vibe/conversations/my-project-main-abc123/interactions.jsonl</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Filter by tool name</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">grep</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;whats_next&quot;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .vibe/conversations/my-project-main-abc123/interactions.jsonl</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Pretty-print with jq</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">cat</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .vibe/conversations/my-project-main-abc123/interactions.jsonl</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> jq</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span></code></pre></div><p><strong>Note</strong>: All interaction data is stored locally on your system and is never transmitted to external services.</p><h2 id="task-backend-architecture" tabindex="-1">Task Backend Architecture <a class="header-anchor" href="#task-backend-architecture" aria-label="Permalink to &quot;Task Backend Architecture&quot;">​</a></h2><p>The system supports multiple task management backends through a factory pattern for component substitution.</p><h3 id="backend-detection" tabindex="-1">Backend Detection <a class="header-anchor" href="#backend-detection" aria-label="Permalink to &quot;Backend Detection&quot;">​</a></h3><p>At startup, the system auto-detects the task backend. If the <code>bd</code> command is available, beads is used; otherwise markdown is used. This can be overridden via the <code>TASK_BACKEND</code> environment variable (<code>markdown</code> or <code>beads</code>).</p><h3 id="component-factory" tabindex="-1">Component Factory <a class="header-anchor" href="#component-factory" aria-label="Permalink to &quot;Component Factory&quot;">​</a></h3><p>The ServerComponentsFactory creates appropriate implementations based on detected task backend configuration.</p><h3 id="component-responsibilities" tabindex="-1">Component Responsibilities <a class="header-anchor" href="#component-responsibilities" aria-label="Permalink to &quot;Component Responsibilities&quot;">​</a></h3><p>Task management functionality varies between backends:</p><ul><li><strong>Plan Management</strong>: Markdown backends use traditional plan files with checkboxes; beads backends reference task hierarchies</li><li><strong>Instruction Generation</strong>: Markdown backends provide generic task guidance; beads backends provide CLI command guidance</li><li><strong>Task Operations</strong>: Markdown backends store tasks in plan files; beads backends integrate with CLI tools for task lifecycle management</li></ul>`,142)])])}const u=a(i,[["render",o]]);export{g as __pageData,u as default};
