import{_ as a,c as e,o as i,a0 as n}from"./chunks/framework.FdfEk_gD.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};
