@codemcp/workflows 5.3.0 → 6.0.1

package/packages/docs/.vitepress/dist/assets/dev_ARCHITECTURE.md.da_vFDwM.js

@@ -0,0 +1,130 @@
+import{_ as a,c as n,o as s,a0 as t}from"./chunks/framework.DZS7lpav.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};

package/packages/docs/.vitepress/dist/assets/dev_ARCHITECTURE.md.da_vFDwM.lean.js

@@ -0,0 +1 @@
+import{_ as a,c as n,o as s,a0 as t}from"./chunks/framework.DZS7lpav.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("",142)])])}const u=a(i,[["render",o]]);export{g as __pageData,u as default};

package/packages/docs/.vitepress/dist/assets/dev_DEVELOPMENT.md.DWl9cccE.js

@@ -0,0 +1,72 @@
+import{_ as a,c as e,o as i,a0 as n}from"./chunks/framework.DZS7lpav.js";const g=JSON.parse('{"title":"Development","description":"","frontmatter":{},"headers":[],"relativePath":"dev/DEVELOPMENT.md","filePath":"dev/DEVELOPMENT.md"}'),t={name:"dev/DEVELOPMENT.md"};function l(o,s,r,p,h,d){return i(),e("div",null,[...s[0]||(s[0]=[n(`<h1 id="development" tabindex="-1">Development <a class="header-anchor" href="#development" aria-label="Permalink to &quot;Development&quot;">​</a></h1><p>This document provides information for developers working on the Responsible Vibe MCP Server, including testing, logging, debugging, and architectural decisions.</p><h2 id="optional-documentation-feature" tabindex="-1">Optional Documentation Feature <a class="header-anchor" href="#optional-documentation-feature" aria-label="Permalink to &quot;Optional Documentation Feature&quot;">​</a></h2><p>The system includes a flexible documentation architecture that allows workflows to specify their documentation requirements:</p><h3 id="key-implementation-components" tabindex="-1">Key Implementation Components <a class="header-anchor" href="#key-implementation-components" aria-label="Permalink to &quot;Key Implementation Components&quot;">​</a></h3><h4 id="_1-workflow-metadata-schema" tabindex="-1">1. Workflow Metadata Schema <a class="header-anchor" href="#_1-workflow-metadata-schema" aria-label="Permalink to &quot;1. Workflow Metadata Schema&quot;">​</a></h4><div class="language-typescript vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">typescript</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">interface</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> YamlStateMachine</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">  metadata</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">    requiresDocumentation</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> boolean</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">; </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// defaults to false</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    // ... other metadata</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  };</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h4 id="_2-start-development-handler-logic" tabindex="-1">2. Start Development Handler Logic <a class="header-anchor" href="#_2-start-development-handler-logic" aria-label="Permalink to &quot;2. Start Development Handler Logic&quot;">​</a></h4><p>The <code>StartDevelopmentHandler</code> implements conditional documentation checking:</p><ul><li><strong>Required workflows</strong>: Block on missing documents, provide setup guidance</li><li><strong>Optional workflows</strong>: Skip artifact checks entirely, proceed to initial phase</li><li><strong>Backward compatibility</strong>: Existing workflows without metadata default to optional</li></ul><h4 id="_3-workflow-updates" tabindex="-1">3. Workflow Updates <a class="header-anchor" href="#_3-workflow-updates" aria-label="Permalink to &quot;3. Workflow Updates&quot;">​</a></h4><ul><li><strong>Comprehensive workflows</strong> (greenfield, waterfall, c4-analysis): Set <code>requiresDocumentation: true</code></li><li><strong>Lightweight workflows</strong> (epcc, minor, bugfix): Default to optional documentation</li><li><strong>Conditional instructions</strong>: Use &quot;If $DOC exists...&quot; patterns for flexible workflows</li></ul><h3 id="testing-coverage" tabindex="-1">Testing Coverage <a class="header-anchor" href="#testing-coverage" aria-label="Permalink to &quot;Testing Coverage&quot;">​</a></h3><p>The implementation includes comprehensive test coverage:</p><ul><li><strong>Unit tests</strong>: Verify requiresDocumentation flag behavior</li><li><strong>Integration tests</strong>: Test both required and optional workflow paths</li><li><strong>Edge case tests</strong>: Handle partial document availability and malformed workflows</li><li><strong>Regression tests</strong>: Ensure backward compatibility</li></ul><h2 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to &quot;Testing&quot;">​</a></h2><p>The project includes comprehensive test coverage with different test execution options to balance thoroughness with development speed:</p><h3 id="test-commands" tabindex="-1">Test Commands <a class="header-anchor" href="#test-commands" aria-label="Permalink to &quot;Test Commands&quot;">​</a></h3><h4 id="default-test-run-quiet" tabindex="-1">Default Test Run (Quiet) <a class="header-anchor" href="#default-test-run-quiet" aria-label="Permalink to &quot;Default Test Run (Quiet)&quot;">​</a></h4><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:#6F42C1;--shiki-dark:#B392F0;">npm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> test</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">          # Interactive test runner</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> test:run</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # Single test run (quiet, no noisy tests)</span></span></code></pre></div><ul><li>Excludes the MCP contract test (which shows INFO logs due to SDK limitations)</li><li>Clean output with ERROR-level logging only</li><li><strong>Recommended for development</strong> - fast and quiet</li></ul><h4 id="all-tests-including-noisy" tabindex="-1">All Tests (Including Noisy) <a class="header-anchor" href="#all-tests-including-noisy" aria-label="Permalink to &quot;All Tests (Including Noisy)&quot;">​</a></h4><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:#6F42C1;--shiki-dark:#B392F0;">npm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> test:all</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # Run all tests including noisy ones</span></span></code></pre></div><ul><li><strong>10 test files</strong>, <strong>96+ tests</strong></li><li>Includes the MCP contract test with spawned processes</li><li>Shows INFO-level logs from MCP SDK (unavoidable)</li><li><strong>Use for comprehensive testing</strong> before commits/releases</li></ul><h4 id="specific-test-categories" tabindex="-1">Specific Test Categories <a class="header-anchor" href="#specific-test-categories" aria-label="Permalink to &quot;Specific Test Categories&quot;">​</a></h4><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:#6F42C1;--shiki-dark:#B392F0;">npm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> test:noisy</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">        # Run only the noisy MCP contract test</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> test:mcp-contract</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Run MCP contract test (with custom state machine check)</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> test:ui</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">           # Interactive test UI</span></span></code></pre></div><h3 id="test-configuration" tabindex="-1">Test Configuration <a class="header-anchor" href="#test-configuration" aria-label="Permalink to &quot;Test Configuration&quot;">​</a></h3><p>The test setup automatically:</p><ul><li>Sets <code>LOG_LEVEL=ERROR</code> for clean output during testing</li><li>Configures test environment variables (<code>NODE_ENV=test</code>, <code>VITEST=true</code>)</li><li>Excludes noisy tests by default unless <code>INCLUDE_NOISY_TESTS=true</code></li><li>Uses TypeScript source files and compiled JavaScript as needed</li></ul><h2 id="testing-architecture" tabindex="-1">Testing Architecture <a class="header-anchor" href="#testing-architecture" aria-label="Permalink to &quot;Testing Architecture&quot;">​</a></h2><p>The project uses an innovative E2E testing approach without process spawning, providing consumer perspective testing with real file system integration.</p><h3 id="testing-pattern" tabindex="-1">Testing Pattern <a class="header-anchor" href="#testing-pattern" aria-label="Permalink to &quot;Testing Pattern&quot;">​</a></h3><ul><li><strong>Production</strong>: Client → Transport → Server → Components</li><li><strong>Testing</strong>: Test → DirectInterface → Server → Components</li></ul><h3 id="test-structure" tabindex="-1">Test Structure <a class="header-anchor" href="#test-structure" aria-label="Permalink to &quot;Test Structure&quot;">​</a></h3><div class="language-typescript vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">typescript</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">it</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;should work end-to-end&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">async</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> () </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> tempProject</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> createTempProjectWithDefaultStateMachine</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  const</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">client</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">cleanup</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> createE2EScenario</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ tempProject });</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> result</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> client.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">callTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;whats_next&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    user_input: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;implement auth&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  });</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  expect</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(result.phase).</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">toBeDefined</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><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>Database</strong>: SQLite operations and state persistence</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>Vibe Feature 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 the local SQLite database in the <code>.vibe</code> directory of your project. The data is stored without masking or filtering, as it is kept locally on your system.</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 queried by conversation ID for analysis and debugging purposes. No UI is provided in the current implementation, but the database can be accessed directly using SQLite tools.</p><p><strong>Note</strong>: All interaction data is stored locally on your system and is never transmitted to external services.</p><h2 id="development-setup" tabindex="-1">Development Setup <a class="header-anchor" href="#development-setup" aria-label="Permalink to &quot;Development Setup&quot;">​</a></h2><h3 id="prerequisites" tabindex="-1">Prerequisites <a class="header-anchor" href="#prerequisites" aria-label="Permalink to &quot;Prerequisites&quot;">​</a></h3><ul><li>Node.js 18.0.0 or higher</li><li>npm or yarn</li></ul><h3 id="installation" tabindex="-1">Installation <a class="header-anchor" href="#installation" aria-label="Permalink to &quot;Installation&quot;">​</a></h3><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;"># Clone the repository</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> clone</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">repository-ur</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">l</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">cd</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">the</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> folder</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> you</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> cloned</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> t</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">o</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Install dependencies</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> install</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Build the project</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build</span></span></code></pre></div><h2 id="project-file-organization" tabindex="-1">Project File Organization <a class="header-anchor" href="#project-file-organization" aria-label="Permalink to &quot;Project File Organization&quot;">​</a></h2><p>The server creates a <code>.vibe</code> subdirectory in your project to store all workflow related files:</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>your-project/</span></span>
+<span class="line"><span>├── .vibe/</span></span>
+<span class="line"><span>│   ├── conversation-state.sqlite      # SQLite database for conversation state</span></span>
+<span class="line"><span>│   ├── development-plan.md        # Main development plan (main/master branch)</span></span>
+<span class="line"><span>│   └── development-plan-{branch}.md  # Branch-specific development plans</span></span>
+<span class="line"><span>├── src/</span></span>
+<span class="line"><span>├── package.json</span></span>
+<span class="line"><span>└── ... (your project files)</span></span></code></pre></div><h3 id="plan-file-management" tabindex="-1">Plan File Management <a class="header-anchor" href="#plan-file-management" aria-label="Permalink to &quot;Plan File Management&quot;">​</a></h3><p>The server automatically creates and manages development plan files:</p><ul><li><strong>Main branch</strong>: <code>.vibe/development-plan.md</code></li><li><strong>Feature branches</strong>: <code>.vibe/development-plan-{branch-name}.md</code></li></ul><p>The LLM is instructed to continuously update these files with:</p><ul><li>Task progress and completion status</li><li>Technical decisions and design choices</li><li>Implementation notes and progress</li><li>Testing results and validation</li></ul><h3 id="database-storage" tabindex="-1">Database Storage <a class="header-anchor" href="#database-storage" aria-label="Permalink to &quot;Database Storage&quot;">​</a></h3><p>Conversation state is persisted in a project-local SQLite database: <code>.vibe/conversation-state.sqlite</code></p><p>This ensures:</p><ul><li><strong>Project isolation</strong>: Each project has its own conversation state</li><li><strong>Branch awareness</strong>: Different branches can have separate development contexts</li><li><strong>Persistence</strong>: State survives server restarts and provides conversation continuity</li><li><strong>Portability</strong>: Database travels with your project</li></ul><h2 id="project-identification" tabindex="-1">Project Identification <a class="header-anchor" href="#project-identification" aria-label="Permalink to &quot;Project Identification&quot;">​</a></h2><p>Each conversation is uniquely identified by:</p><ul><li><strong>Project path</strong>: Absolute path to current working directory</li><li><strong>Git branch</strong>: Current git branch (or &#39;no-git&#39; if not in a git repo)</li></ul><p>This allows multiple projects and branches to have independent conversation states.</p><h3 id="development-commands" tabindex="-1">Development Commands <a class="header-anchor" href="#development-commands" aria-label="Permalink to &quot;Development Commands&quot;">​</a></h3><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;"># Start development server</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dev</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Build for production</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Run tests</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> test:run</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Run all tests (including noisy ones)</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> test:all</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Start workflow visualizer</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> visualize</span></span></code></pre></div><h3 id="project-structure" tabindex="-1">Project Structure <a class="header-anchor" href="#project-structure" aria-label="Permalink to &quot;Project 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>src/</span></span>
+<span class="line"><span>├── index.ts              # Main server entry point</span></span>
+<span class="line"><span>├── server.ts             # MCP server implementation</span></span>
+<span class="line"><span>├── conversation/         # Conversation management</span></span>
+<span class="line"><span>├── database/            # Database operations</span></span>
+<span class="line"><span>├── plan/               # Plan file management</span></span>
+<span class="line"><span>├── transitions/        # Phase transition logic</span></span>
+<span class="line"><span>├── workflows/          # Workflow definitions</span></span>
+<span class="line"><span>└── utils/              # Utility functions</span></span>
+<span class="line"><span></span></span>
+<span class="line"><span>tests/</span></span>
+<span class="line"><span>├── unit/               # Unit tests</span></span>
+<span class="line"><span>├── integration/        # Integration tests</span></span>
+<span class="line"><span>└── fixtures/           # Test fixtures</span></span>
+<span class="line"><span></span></span>
+<span class="line"><span>docs/</span></span>
+<span class="line"><span>├── ARCHITECTURE.md     # Architecture documentation</span></span>
+<span class="line"><span>├── EXAMPLES.md         # Usage examples</span></span>
+<span class="line"><span>├── DEVELOPMENT.md      # This file</span></span>
+<span class="line"><span>└── *.md               # Other documentation</span></span></code></pre></div><h2 id="debugging-tips" tabindex="-1">Debugging Tips <a class="header-anchor" href="#debugging-tips" aria-label="Permalink to &quot;Debugging Tips&quot;">​</a></h2><h3 id="common-issues" tabindex="-1">Common Issues <a class="header-anchor" href="#common-issues" aria-label="Permalink to &quot;Common Issues&quot;">​</a></h3><ol><li><strong>Server not responding</strong>: Check if the server process is running and listening on the correct port</li><li><strong>Database errors</strong>: Ensure the SQLite database file has proper permissions</li><li><strong>Git integration issues</strong>: Verify git is installed and the project is in a git repository</li><li><strong>Plan file not updating</strong>: Check file permissions and project path configuration</li></ol><h3 id="debug-mode" tabindex="-1">Debug Mode <a class="header-anchor" href="#debug-mode" aria-label="Permalink to &quot;Debug Mode&quot;">​</a></h3><p>Enable debug logging to see detailed execution flow:</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:#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;"> @codemcp/workflows-server</span></span></code></pre></div><h3 id="testing-with-mcp-inspector" tabindex="-1">Testing with MCP Inspector <a class="header-anchor" href="#testing-with-mcp-inspector" aria-label="Permalink to &quot;Testing with MCP Inspector&quot;">​</a></h3><p>Use the MCP Inspector for interactive testing:</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:#6F42C1;--shiki-dark:#B392F0;">npx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @modelcontextprotocol/inspector</span></span></code></pre></div><p>Configure it to connect to your local server instance.</p><h2 id="contributing" tabindex="-1">Contributing <a class="header-anchor" href="#contributing" aria-label="Permalink to &quot;Contributing&quot;">​</a></h2><h3 id="code-style" tabindex="-1">Code Style <a class="header-anchor" href="#code-style" aria-label="Permalink to &quot;Code Style&quot;">​</a></h3><ul><li>Use TypeScript for all new code</li><li>Follow existing code formatting conventions</li><li>Add tests for new functionality</li><li>Update documentation for API changes</li></ul><h3 id="commit-messages" tabindex="-1">Commit Messages <a class="header-anchor" href="#commit-messages" aria-label="Permalink to &quot;Commit Messages&quot;">​</a></h3><p>Use conventional commits for version management:</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>feat: add new workflow support</span></span>
+<span class="line"><span>fix: resolve database connection issue</span></span>
+<span class="line"><span>docs: update API documentation</span></span>
+<span class="line"><span>test: add integration tests for phase transitions</span></span></code></pre></div><h3 id="pull-request-process" tabindex="-1">Pull Request Process <a class="header-anchor" href="#pull-request-process" aria-label="Permalink to &quot;Pull Request Process&quot;">​</a></h3><ol><li>Fork the repository</li><li>Create a feature branch</li><li>Make your changes with tests</li><li>Ensure all tests pass (<code>npm run test:all</code>)</li><li>Update documentation as needed</li><li>Submit a pull request</li></ol><h3 id="automated-checks" tabindex="-1">Automated Checks <a class="header-anchor" href="#automated-checks" aria-label="Permalink to &quot;Automated Checks&quot;">​</a></h3><p>The project includes several automated checks that run on every PR:</p><ul><li><strong>Tests</strong>: Comprehensive test suite including MCP contract tests</li><li><strong>Linting</strong>: Code style and quality checks</li><li><strong>Type Checking</strong>: TypeScript compilation verification</li><li><strong>Build Verification</strong>: Ensures the project builds successfully</li></ul><h3 id="dependency-management" tabindex="-1">Dependency Management <a class="header-anchor" href="#dependency-management" aria-label="Permalink to &quot;Dependency Management&quot;">​</a></h3><p>This project uses <strong>Renovate</strong> for automated dependency management:</p><ul><li>Automatically creates PRs for dependency updates</li><li>Follows semantic versioning for update scheduling</li><li>Includes security updates with higher priority</li><li>Configuration in <code>.github/renovate.json</code></li><li>Helps keep dependencies current and secure</li></ul><h3 id="release-process" tabindex="-1">Release Process <a class="header-anchor" href="#release-process" aria-label="Permalink to &quot;Release Process&quot;">​</a></h3><p>The project uses automated releases based on conventional commits:</p><ul><li><code>feat:</code> commits trigger minor version bumps</li><li><code>fix:</code> commits trigger patch version bumps</li><li><code>BREAKING CHANGE:</code> in commit body triggers major version bumps</li></ul>`,106)])])}const k=a(t,[["render",l]]);export{g as __pageData,k as default};

package/packages/docs/.vitepress/dist/assets/dev_DEVELOPMENT.md.DWl9cccE.lean.js

@@ -0,0 +1 @@
+import{_ as a,c as e,o as i,a0 as n}from"./chunks/framework.DZS7lpav.js";const g=JSON.parse('{"title":"Development","description":"","frontmatter":{},"headers":[],"relativePath":"dev/DEVELOPMENT.md","filePath":"dev/DEVELOPMENT.md"}'),t={name:"dev/DEVELOPMENT.md"};function l(o,s,r,p,h,d){return i(),e("div",null,[...s[0]||(s[0]=[n("",106)])])}const k=a(t,[["render",l]]);export{g as __pageData,k as default};

package/packages/docs/.vitepress/dist/assets/dev_LOGGING.md.BebvbW7z.js

@@ -0,0 +1,34 @@
+import{_ as s,c as a,o as e,a0 as n}from"./chunks/framework.DZS7lpav.js";const d=JSON.parse('{"title":"Logging Documentation","description":"","frontmatter":{},"headers":[],"relativePath":"dev/LOGGING.md","filePath":"dev/LOGGING.md"}'),t={name:"dev/LOGGING.md"};function l(o,i,r,h,p,g){return e(),a("div",null,[...i[0]||(i[0]=[n(`<h1 id="logging-documentation" tabindex="-1">Logging Documentation <a class="header-anchor" href="#logging-documentation" aria-label="Permalink to &quot;Logging Documentation&quot;">​</a></h1><p>The Vibe Feature MCP Server includes a comprehensive logging system that follows MCP best practices and provides both local debugging capabilities and client notifications.</p><h2 id="mcp-compliance" tabindex="-1">MCP Compliance <a class="header-anchor" href="#mcp-compliance" aria-label="Permalink to &quot;MCP Compliance&quot;">​</a></h2><p>The logging system is fully compliant with MCP requirements:</p><ul><li><strong>stderr only</strong>: All local logging uses <code>stderr</code> (not <code>stdout</code>) to avoid interfering with MCP protocol operation</li><li><strong>Client notifications</strong>: Important events are sent to the MCP client via log message notifications</li><li><strong>Structured logging</strong>: All log messages include structured context data</li><li><strong>Centralized logging</strong>: All logging logic is centralized in <code>logger.ts</code> to avoid duplication</li></ul><h2 id="log-levels" tabindex="-1">Log Levels <a class="header-anchor" href="#log-levels" aria-label="Permalink to &quot;Log Levels&quot;">​</a></h2><p>The server supports four log levels with configurable output:</p><ul><li><strong>DEBUG</strong>: Detailed tracing and execution flow information</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><h2 id="configuration" tabindex="-1">Configuration <a class="header-anchor" href="#configuration" aria-label="Permalink to &quot;Configuration&quot;">​</a></h2><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 (default)</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>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Error level only</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;">ERROR</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><h2 id="logging-components" tabindex="-1">Logging Components <a class="header-anchor" href="#logging-components" aria-label="Permalink to &quot;Logging Components&quot;">​</a></h2><h3 id="local-logging-stderr" tabindex="-1">Local Logging (stderr) <a class="header-anchor" href="#local-logging-stderr" aria-label="Permalink to &quot;Local Logging (stderr)&quot;">​</a></h3><p>All log messages are written to <code>stderr</code> with structured formatting:</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>[2025-06-23T06:33:37.372Z] INFO [Server] Phase transition completed {&quot;from&quot;:&quot;idle&quot;,&quot;to&quot;:&quot;requirements&quot;,&quot;reason&quot;:&quot;Starting development&quot;}</span></span></code></pre></div><p>Format: <code>[timestamp] LEVEL [component] message {context}</code></p><h3 id="mcp-client-notifications" tabindex="-1">MCP Client Notifications <a class="header-anchor" href="#mcp-client-notifications" aria-label="Permalink to &quot;MCP Client Notifications&quot;">​</a></h3><p>Important events are automatically sent to the MCP client as enhanced log message notifications:</p><ul><li><strong>Phase transitions</strong>: Formatted as &quot;Phase Transition: Idle → Requirements&quot;</li><li><strong>Server initialization</strong>: Enhanced as &quot;🚀 Vibe Feature MCP Server Ready&quot;</li><li><strong>Error conditions</strong>: When tools fail or encounter issues</li><li><strong>Debug information</strong>: Only sent at DEBUG level</li></ul><p>Client notifications use the MCP <code>notifications/message</code> method with enhanced formatting for better user experience.</p><h2 id="component-loggers" tabindex="-1">Component Loggers <a class="header-anchor" href="#component-loggers" aria-label="Permalink to &quot;Component Loggers&quot;">​</a></h2><p>The system uses component-specific loggers for better organization:</p><ul><li><strong>Server</strong>: Main server operations and tool handlers</li><li><strong>Database</strong>: SQLite operations and state persistence</li><li><strong>ConversationManager</strong>: Conversation context management</li><li><strong>TransitionEngine</strong>: Phase transition analysis and state machine operations</li><li><strong>PlanManager</strong>: Plan file operations and management</li><li><strong>StateMachineLoader</strong>: State machine loading and validation</li><li><strong>InteractionLogger</strong>: Tool interaction logging</li></ul><h2 id="usage-examples" tabindex="-1">Usage Examples <a class="header-anchor" href="#usage-examples" aria-label="Permalink to &quot;Usage Examples&quot;">​</a></h2><h3 id="creating-a-logger" tabindex="-1">Creating a Logger <a class="header-anchor" href="#creating-a-logger" aria-label="Permalink to &quot;Creating a Logger&quot;">​</a></h3><div class="language-typescript vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">typescript</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { createLogger } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;./logger.js&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> logger</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> createLogger</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;MyComponent&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span></code></pre></div><h3 id="logging-with-context" tabindex="-1">Logging with Context <a class="header-anchor" href="#logging-with-context" aria-label="Permalink to &quot;Logging with Context&quot;">​</a></h3><div class="language-typescript vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">typescript</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;">logger.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">info</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;Operation completed&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  conversationId: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;abc123&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  phase: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;requirements&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  operation: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;phase_transition&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h3 id="error-logging" tabindex="-1">Error Logging <a class="header-anchor" href="#error-logging" aria-label="Permalink to &quot;Error Logging&quot;">​</a></h3><div class="language-typescript vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">typescript</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">try</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // some operation</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">} </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">catch</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (error) {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  logger.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">error</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;Operation failed&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, error </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">as</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Error</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    operation: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;database_query&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    conversationId: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;abc123&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  });</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h3 id="child-loggers" tabindex="-1">Child Loggers <a class="header-anchor" href="#child-loggers" aria-label="Permalink to &quot;Child Loggers&quot;">​</a></h3><div class="language-typescript vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">typescript</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> childLogger</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> logger.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">child</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;SubComponent&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">childLogger.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">debug</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;Sub-operation started&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Output: [timestamp] DEBUG [MyComponent:SubComponent] Sub-operation started</span></span></code></pre></div><h2 id="client-integration" tabindex="-1">Client Integration <a class="header-anchor" href="#client-integration" aria-label="Permalink to &quot;Client Integration&quot;">​</a></h2><p>When using the MCP server, clients will receive enhanced log notifications for:</p><ol><li><strong>Server initialization</strong>: &quot;🚀 Vibe Feature MCP Server Ready&quot;</li><li><strong>Phase transitions</strong>: &quot;Phase Transition: Requirements → Design&quot;</li><li><strong>Error conditions</strong>: Immediate notification of tool failures or issues</li><li><strong>Debug information</strong>: Detailed tracing (only at DEBUG level)</li></ol><p>Example client notification:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</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;">{</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;method&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;notifications/message&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;params&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">    &quot;level&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;info&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">    &quot;logger&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Server&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">    &quot;data&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Phase Transition: Idle → Requirements {</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\&quot;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">from</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\&quot;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\&quot;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">idle</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\&quot;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">,</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\&quot;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">to</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\&quot;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\&quot;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">requirements</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\&quot;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">,</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\&quot;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">reason</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\&quot;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\&quot;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">Starting development</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\&quot;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}&quot;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  }</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h2 id="architecture-benefits" tabindex="-1">Architecture Benefits <a class="header-anchor" href="#architecture-benefits" aria-label="Permalink to &quot;Architecture Benefits&quot;">​</a></h2><h3 id="centralized-logging" tabindex="-1">Centralized Logging <a class="header-anchor" href="#centralized-logging" aria-label="Permalink to &quot;Centralized Logging&quot;">​</a></h3><ul><li>All logging logic is contained in <code>logger.ts</code></li><li>No duplication between server components</li><li>Single point of configuration and enhancement</li></ul><h3 id="enhanced-user-experience" tabindex="-1">Enhanced User Experience <a class="header-anchor" href="#enhanced-user-experience" aria-label="Permalink to &quot;Enhanced User Experience&quot;">​</a></h3><ul><li>Phase transitions are formatted for readability</li><li>Important events get visual indicators (🚀)</li><li>Context information is preserved but formatted appropriately</li></ul><h3 id="mcp-compliance-1" tabindex="-1">MCP Compliance <a class="header-anchor" href="#mcp-compliance-1" aria-label="Permalink to &quot;MCP Compliance&quot;">​</a></h3><ul><li>All local logs go to stderr as required</li><li>Client notifications use proper MCP protocol</li><li>Graceful fallback when MCP transport is unavailable</li></ul><h2 id="debugging" tabindex="-1">Debugging <a class="header-anchor" href="#debugging" aria-label="Permalink to &quot;Debugging&quot;">​</a></h2><h3 id="enable-debug-logging" tabindex="-1">Enable Debug Logging <a class="header-anchor" href="#enable-debug-logging" aria-label="Permalink to &quot;Enable Debug Logging&quot;">​</a></h3><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:#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></code></pre></div><p>Debug logging includes:</p><ul><li>Detailed execution flow</li><li>State machine operations</li><li>Database queries</li><li>Plan file operations</li><li>Tool parameter validation</li></ul><h3 id="log-file-analysis" tabindex="-1">Log File Analysis <a class="header-anchor" href="#log-file-analysis" aria-label="Permalink to &quot;Log File Analysis&quot;">​</a></h3><p>Since all logs go to <code>stderr</code>, you can capture them for analysis:</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;"># Capture logs to file</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 style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> 2&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> server.log</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Monitor logs in real-time</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 style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> 2&gt;&amp;1</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> tee</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> server.log</span></span></code></pre></div><h2 id="best-practices" tabindex="-1">Best Practices <a class="header-anchor" href="#best-practices" aria-label="Permalink to &quot;Best Practices&quot;">​</a></h2><ol><li><strong>Use appropriate log levels</strong>: Debug for tracing, Info for milestones, Warn for recoverable issues, Error for failures</li><li><strong>Include context</strong>: Always provide relevant context data with log messages</li><li><strong>Avoid sensitive data</strong>: Don&#39;t log passwords, tokens, or other sensitive information</li><li><strong>Use structured logging</strong>: Provide context as objects rather than string interpolation</li><li><strong>Component-specific loggers</strong>: Use dedicated loggers for different components</li><li><strong>Centralized logging</strong>: Use the logger module for all logging needs</li></ol><h2 id="performance-considerations" tabindex="-1">Performance Considerations <a class="header-anchor" href="#performance-considerations" aria-label="Permalink to &quot;Performance Considerations&quot;">​</a></h2><ul><li>Log level filtering happens before message formatting for efficiency</li><li>MCP client notifications are sent asynchronously to avoid blocking operations</li><li>Failed MCP notifications fall back to stderr logging</li><li>Context objects are JSON-serialized only when the log level permits output</li><li>Enhanced notifications only process important events to reduce overhead</li></ul><h2 id="troubleshooting" tabindex="-1">Troubleshooting <a class="header-anchor" href="#troubleshooting" aria-label="Permalink to &quot;Troubleshooting&quot;">​</a></h2><h3 id="no-log-output" tabindex="-1">No Log Output <a class="header-anchor" href="#no-log-output" aria-label="Permalink to &quot;No Log Output&quot;">​</a></h3><p>Check the <code>LOG_LEVEL</code> environment variable. Default is <code>INFO</code>.</p><h3 id="mcp-client-not-receiving-notifications" tabindex="-1">MCP Client Not Receiving Notifications <a class="header-anchor" href="#mcp-client-not-receiving-notifications" aria-label="Permalink to &quot;MCP Client Not Receiving Notifications&quot;">​</a></h3><p>Ensure the server is properly initialized and connected to the MCP transport. Client notifications are only sent after successful server initialization. In test environments, &quot;Not connected&quot; errors are expected and harmless.</p><h3 id="performance-issues" tabindex="-1">Performance Issues <a class="header-anchor" href="#performance-issues" aria-label="Permalink to &quot;Performance Issues&quot;">​</a></h3><p>Consider raising the log level to <code>WARN</code> or <code>ERROR</code> in production environments to reduce log volume.</p><h2 id="integration-with-mcp-inspector" tabindex="-1">Integration with MCP Inspector <a class="header-anchor" href="#integration-with-mcp-inspector" aria-label="Permalink to &quot;Integration with MCP Inspector&quot;">​</a></h2><p>When using the MCP Inspector for debugging, set debug logging to see detailed protocol interactions:</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:#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;"> @modelcontextprotocol/inspector</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> 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></code></pre></div><p>The enhanced logging system provides comprehensive visibility into the server&#39;s operation while maintaining MCP compliance and optimal performance through centralized, structured logging.</p>`,67)])])}const c=s(t,[["render",l]]);export{d as __pageData,c as default};

package/packages/docs/.vitepress/dist/assets/dev_LOGGING.md.BebvbW7z.lean.js

@@ -0,0 +1 @@
+import{_ as s,c as a,o as e,a0 as n}from"./chunks/framework.DZS7lpav.js";const d=JSON.parse('{"title":"Logging Documentation","description":"","frontmatter":{},"headers":[],"relativePath":"dev/LOGGING.md","filePath":"dev/LOGGING.md"}'),t={name:"dev/LOGGING.md"};function l(o,i,r,h,p,g){return e(),a("div",null,[...i[0]||(i[0]=[n("",67)])])}const c=s(t,[["render",l]]);export{d as __pageData,c as default};

package/packages/docs/.vitepress/dist/assets/dev_PUBLISHING.md.CQqbiIOF.js

@@ -0,0 +1 @@
+import{_ as i,c as s,o as t,a0 as a}from"./chunks/framework.DZS7lpav.js";const m=JSON.parse('{"title":"Publishing Guide","description":"","frontmatter":{},"headers":[],"relativePath":"dev/PUBLISHING.md","filePath":"dev/PUBLISHING.md"}'),o={name:"dev/PUBLISHING.md"};function l(r,e,n,h,u,c){return t(),s("div",null,[...e[0]||(e[0]=[a('<h1 id="publishing-guide" tabindex="-1">Publishing Guide <a class="header-anchor" href="#publishing-guide" aria-label="Permalink to &quot;Publishing Guide&quot;">​</a></h1><p>This document describes the automated publishing setup for the responsible-vibe MCP server.</p><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to &quot;Overview&quot;">​</a></h2><p>The project uses GitHub Actions to automatically:</p><ul><li>Run tests on pull requests</li><li>Version bump using conventional commits</li><li>Publish to npm registry</li><li>Create git tags and GitHub releases</li><li>Generate changelogs</li></ul><h2 id="setup-instructions" tabindex="-1">Setup Instructions <a class="header-anchor" href="#setup-instructions" aria-label="Permalink to &quot;Setup Instructions&quot;">​</a></h2><h3 id="_1-npm-token-setup" tabindex="-1">1. npm Token Setup <a class="header-anchor" href="#_1-npm-token-setup" aria-label="Permalink to &quot;1. npm Token Setup&quot;">​</a></h3><ol><li><p><strong>Generate npm Access Token:</strong></p><ul><li>Go to <a href="https://www.npmjs.com/settings/tokens" target="_blank" rel="noreferrer">https://www.npmjs.com/settings/tokens</a></li><li>Click &quot;Generate New Token&quot; → &quot;Automation&quot; (for CI/CD)</li><li>Copy the token (starts with <code>npm_</code>)</li></ul></li><li><p><strong>Add GitHub Secret:</strong></p><ul><li>Go to your repo: <a href="https://github.com/mrsimpson/vibe-feature-mcp/settings/secrets/actions" target="_blank" rel="noreferrer">https://github.com/mrsimpson/vibe-feature-mcp/settings/secrets/actions</a></li><li>Click &quot;New repository secret&quot;</li><li>Name: <code>NPM_TOKEN</code></li><li>Value: Your npm token</li></ul></li></ol><h3 id="_2-package-information" tabindex="-1">2. Package Information <a class="header-anchor" href="#_2-package-information" aria-label="Permalink to &quot;2. Package Information&quot;">​</a></h3><ul><li><strong>Package Name</strong>: <code>@codemcp/workflows</code></li><li><strong>Registry</strong>: npm (<a href="https://registry.npmjs.org" target="_blank" rel="noreferrer">https://registry.npmjs.org</a>)</li><li><strong>Access</strong>: Public (scoped package)</li></ul><h2 id="workflows" tabindex="-1">Workflows <a class="header-anchor" href="#workflows" aria-label="Permalink to &quot;Workflows&quot;">​</a></h2><h3 id="pr-workflow-github-workflows-pr-yml" tabindex="-1">PR Workflow (<code>.github/workflows/pr.yml</code>) <a class="header-anchor" href="#pr-workflow-github-workflows-pr-yml" aria-label="Permalink to &quot;PR Workflow (`.github/workflows/pr.yml`)&quot;">​</a></h3><p><strong>Triggers</strong>: Pull requests to main branch <strong>Actions</strong>:</p><ul><li>Tests on Node.js 18, 20, and latest</li><li>Build verification</li><li>Full test suite including MCP contract tests</li></ul><h3 id="release-workflow-github-workflows-release-yml" tabindex="-1">Release Workflow (<code>.github/workflows/release.yml</code>) <a class="header-anchor" href="#release-workflow-github-workflows-release-yml" aria-label="Permalink to &quot;Release Workflow (`.github/workflows/release.yml`)&quot;">​</a></h3><p><strong>Triggers</strong>: Push to main branch <strong>Actions</strong>:</p><ol><li>Run full test suite</li><li>Analyze conventional commits for version bump</li><li>Update package.json version</li><li>Create git tag (v1.2.3 format)</li><li>Generate changelog</li><li>Publish to npm</li><li>Create GitHub release</li></ol><h2 id="conventional-commits" tabindex="-1">Conventional Commits <a class="header-anchor" href="#conventional-commits" aria-label="Permalink to &quot;Conventional Commits&quot;">​</a></h2><p>The versioning follows conventional commit standards:</p><ul><li><code>feat:</code> → Minor version bump (1.0.0 → 1.1.0)</li><li><code>fix:</code> → Patch version bump (1.0.0 → 1.0.1)</li><li><code>BREAKING CHANGE:</code> → Major version bump (1.0.0 → 2.0.0)</li></ul><h3 id="examples" tabindex="-1">Examples: <a class="header-anchor" href="#examples" aria-label="Permalink to &quot;Examples:&quot;">​</a></h3><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:#6F42C1;--shiki-dark:#B392F0;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> commit</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -m</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;feat: add new authentication method&quot;</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> commit</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -m</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;fix: resolve memory leak in state management&quot;</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> commit</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -m</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;feat!: redesign API structure</span></span>\n<span class="line"></span>\n<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">BREAKING CHANGE: API endpoints have changed&quot;</span></span></code></pre></div><h2 id="publishing-process" tabindex="-1">Publishing Process <a class="header-anchor" href="#publishing-process" aria-label="Permalink to &quot;Publishing Process&quot;">​</a></h2><ol><li><strong>Development</strong>: Work on feature branches</li><li><strong>Pull Request</strong>: Create PR to main branch (triggers tests)</li><li><strong>Review &amp; Merge</strong>: After approval, merge to main</li><li><strong>Automatic Release</strong>: GitHub Actions handles the rest: <ul><li>Tests pass → Version bump → npm publish → Git tag → Release notes</li></ul></li></ol><h2 id="manual-override" tabindex="-1">Manual Override <a class="header-anchor" href="#manual-override" aria-label="Permalink to &quot;Manual Override&quot;">​</a></h2><p>If needed, you can manually trigger releases:</p><ol><li>Go to Actions tab in GitHub</li><li>Select &quot;Release and Publish&quot; workflow</li><li>Click &quot;Run workflow&quot; on main branch</li></ol><h2 id="troubleshooting" tabindex="-1">Troubleshooting <a class="header-anchor" href="#troubleshooting" aria-label="Permalink to &quot;Troubleshooting&quot;">​</a></h2><h3 id="common-issues" tabindex="-1">Common Issues: <a class="header-anchor" href="#common-issues" aria-label="Permalink to &quot;Common Issues:&quot;">​</a></h3><ol><li><strong>npm publish fails</strong>: Check NPM_TOKEN secret is set correctly</li><li><strong>No version bump</strong>: Ensure commits follow conventional format</li><li><strong>Tests fail</strong>: Fix tests before merging to main</li><li><strong>Permission denied</strong>: Verify GitHub Actions permissions</li></ol><h3 id="checking-status" tabindex="-1">Checking Status: <a class="header-anchor" href="#checking-status" aria-label="Permalink to &quot;Checking Status:&quot;">​</a></h3><ul><li><strong>npm package</strong>: <a href="https://www.npmjs.com/package/@codemcp/workflows" target="_blank" rel="noreferrer">https://www.npmjs.com/package/@codemcp/workflows</a></li><li><strong>GitHub releases</strong>: <a href="https://github.com/mrsimpson/vibe-feature-mcp/releases" target="_blank" rel="noreferrer">https://github.com/mrsimpson/vibe-feature-mcp/releases</a></li><li><strong>Actions logs</strong>: <a href="https://github.com/mrsimpson/vibe-feature-mcp/actions" target="_blank" rel="noreferrer">https://github.com/mrsimpson/vibe-feature-mcp/actions</a></li></ul><h2 id="version-history" tabindex="-1">Version History <a class="header-anchor" href="#version-history" aria-label="Permalink to &quot;Version History&quot;">​</a></h2><p>Versions and changelogs are automatically maintained in:</p><ul><li>GitHub Releases</li><li>CHANGELOG.md (auto-generated)</li><li>Git tags (v1.2.3 format)</li></ul>',35)])])}const g=i(o,[["render",l]]);export{m as __pageData,g as default};