@programinglive/dev-workflow-mcp-server 1.3.7 → 1.3.9

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [1.3.9](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.3.8...v1.3.9) (2025-11-22)
+
+
+### ✨ Features
+
+* **web:** improve documentation modal layout and readability ([ca033bd](https://github.com/programinglive/dev-workflow-mcp-server/commit/ca033bd1208283c46a6262b6f447f57246c19dc7))
+
+
+### 🧹 Chores
+
+* rebuild Tailwind CSS ([b8a552e](https://github.com/programinglive/dev-workflow-mcp-server/commit/b8a552ebec854b4a50265fc9979c350a46a594ca))
+
+### [1.3.8](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.3.7...v1.3.8) (2025-11-22)
+
+
+### 🐛 Bug Fixes
+
+* **web:** track dist/docs in git for production deployment ([95a9e87](https://github.com/programinglive/dev-workflow-mcp-server/commit/95a9e8792e7045a86435b6df0d44f31d6b9952f1))
+
 ### [1.3.7](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.3.6...v1.3.7) (2025-11-22)
 
 

package/dist/docs/EXAMPLES.html

@@ -0,0 +1,411 @@
+<h1>Practical Examples for Dev-Workflow MCP Server</h1>
+<p>This document provides real-world examples of using the dev-workflow MCP server in Antigravity.</p>
+<h2>Table of Contents</h2>
+<ul>
+<li><a href="#simple-feature-development">Simple Feature Development</a></li>
+<li><a href="#bug-fix-with-test-discovery">Bug Fix with Test Discovery</a></li>
+<li><a href="#refactoring-workflow">Refactoring Workflow</a></li>
+<li><a href="#using-run_full_workflow">Using run_full_workflow</a></li>
+<li><a href="#multi-project-workflow">Multi-Project Workflow</a></li>
+<li><a href="#per-user-workflow-isolation">Per-User Workflow Isolation</a></li>
+<li><a href="#handling-test-failures">Handling Test Failures</a></li>
+</ul>
+<hr>
+<h2>Simple Feature Development</h2>
+<p><strong>Scenario:</strong> Adding a user profile avatar feature</p>
+<h3>Step-by-Step</h3>
+<p><strong>1. Start the task:</strong></p>
+<pre><code>start_task:
+  description: &quot;Add user avatar upload and display&quot;
+  type: &quot;feature&quot;
+</code></pre>
+<p><strong>Response:</strong></p>
+<pre><code>✅ Task started: Add user avatar upload and display
+📝 Task ID: task-20231122-001
+🔄 Phase: implementation
+Next: Implement the feature, then mark as fixed
+</code></pre>
+<p><strong>2. Implement the feature:</strong></p>
+<ul>
+<li>Create <code>components/Avatar.jsx</code></li>
+<li>Add upload functionality</li>
+<li>Integrate with user profile page</li>
+</ul>
+<p><strong>3. Mark as fixed:</strong></p>
+<pre><code>mark_bug_fixed:
+  summary: &quot;Avatar component with upload, preview, and persistence&quot;
+</code></pre>
+<p><strong>4. Create tests:</strong></p>
+<ul>
+<li>Write <code>Avatar.test.jsx</code> with upload tests</li>
+<li>Add integration tests for profile page</li>
+</ul>
+<pre><code>create_tests
+</code></pre>
+<p><strong>5. Run tests:</strong></p>
+<pre><code class="language-bash">npm test
+</code></pre>
+<pre><code>run_tests:
+  passed: true
+  testCommand: &quot;npm test&quot;
+  details: &quot;31 tests passed (27 existing + 4 new avatar tests)&quot;
+</code></pre>
+<p><strong>6. Document:</strong>
+Update <code>README.md</code> with avatar component usage:</p>
+<pre><code>create_documentation:
+  documentationType: &quot;README&quot;
+  summary: &quot;Added Avatar component documentation with API reference and examples&quot;
+</code></pre>
+<p><strong>7. Commit and push:</strong></p>
+<pre><code>commit_and_push:
+  commitMessage: &quot;feat(profile): add user avatar upload and display&quot;
+</code></pre>
+<p><strong>8. Release:</strong></p>
+<pre><code>perform_release:
+  command: &quot;npm run release:minor&quot;
+  notes: &quot;v1.3.0 - User avatar feature&quot;
+</code></pre>
+<p><strong>9. Complete:</strong></p>
+<pre><code>complete_task:
+  commitMessage: &quot;feat(profile): add user avatar upload and display&quot;
+</code></pre>
+<hr>
+<h2>Bug Fix with Test Discovery</h2>
+<p><strong>Scenario:</strong> Fixing a date formatting bug discovered in production</p>
+<h3>Workflow</h3>
+<p><strong>1. Start:</strong></p>
+<pre><code>start_task:
+  description: &quot;Fix incorrect date format in transaction history&quot;
+  type: &quot;bugfix&quot;
+</code></pre>
+<p><strong>2. Reproduce and fix:</strong></p>
+<ul>
+<li>Find the bug in <code>utils/formatDate.js</code></li>
+<li>Fix the formatting logic</li>
+<li>Verify the fix</li>
+</ul>
+<p><strong>3. Mark as fixed:</strong></p>
+<pre><code>mark_bug_fixed:
+  summary: &quot;Corrected date formatting to use ISO 8601 format&quot;
+</code></pre>
+<p><strong>4. Create regression test:</strong>
+Create <code>utils/formatDate.test.js</code>:</p>
+<pre><code class="language-javascript">describe(&#39;formatDate&#39;, () =&gt; {
+  it(&#39;formats dates in ISO 8601 format&#39;, () =&gt; {
+    const date = new Date(&#39;2023-11-22T10:30:00Z&#39;);
+    expect(formatDate(date)).toBe(&#39;2023-11-22&#39;);
+  });
+  
+  it(&#39;handles timezone correctly&#39;, () =&gt; {
+    // Regression test for the bug
+    const date = new Date(&#39;2023-11-22T23:00:00-05:00&#39;);
+    expect(formatDate(date)).toBe(&#39;2023-11-22&#39;);
+  });
+});
+</code></pre>
+<pre><code>create_tests
+</code></pre>
+<p><strong>5. Run tests:</strong></p>
+<pre><code>run_tests:
+  passed: true
+  testCommand: &quot;npm test -- utils/formatDate.test.js&quot;
+  details: &quot;2 new tests pass, including regression test&quot;
+</code></pre>
+<p><strong>6. Document:</strong>
+Update <code>CHANGELOG.md</code>:</p>
+<pre><code>create_documentation:
+  documentationType: &quot;changelog&quot;
+  summary: &quot;Added bug fix entry for date formatting issue&quot;
+</code></pre>
+<p><strong>7. Commit:</strong></p>
+<pre><code>commit_and_push:
+  commitMessage: &quot;fix(utils): correct date formatting to use ISO 8601&quot;
+</code></pre>
+<p><strong>8. Release:</strong></p>
+<pre><code>perform_release:
+  command: &quot;npm run release:patch&quot;
+  notes: &quot;v1.2.1 - Hotfix for date formatting&quot;
+</code></pre>
+<p><strong>9. Complete:</strong></p>
+<pre><code>complete_task:
+  commitMessage: &quot;fix(utils): correct date formatting to use ISO 8601&quot;
+</code></pre>
+<hr>
+<h2>Refactoring Workflow</h2>
+<p><strong>Scenario:</strong> Refactoring API service layer for better maintainability</p>
+<h3>Workflow</h3>
+<p><strong>1. Start:</strong></p>
+<pre><code>start_task:
+  description: &quot;Refactor API service layer to use interceptors pattern&quot;
+  type: &quot;refactor&quot;
+</code></pre>
+<p><strong>2. Refactor code:</strong></p>
+<ul>
+<li>Extract common logic to interceptors</li>
+<li>Update all API calls to use new pattern</li>
+<li>Ensure backward compatibility</li>
+</ul>
+<p><strong>3. Mark as fixed:</strong></p>
+<pre><code>mark_bug_fixed:
+  summary: &quot;Refactored API service to use axios interceptors for auth and error handling&quot;
+</code></pre>
+<p><strong>4. Update existing tests:</strong>
+Since this is a refactor, update existing tests to work with new structure:</p>
+<pre><code>create_tests
+</code></pre>
+<p><strong>5. Run comprehensive test suite:</strong></p>
+<pre><code>run_tests:
+  passed: true
+  testCommand: &quot;npm test -- --coverage&quot;
+  details: &quot;All 127 tests pass. Coverage: 94% → 96%&quot;
+</code></pre>
+<p><strong>6. Document changes:</strong>
+Update inline comments and architecture docs:</p>
+<pre><code>create_documentation:
+  documentationType: &quot;inline-comments&quot;
+  summary: &quot;Added JSDoc comments for interceptors and updated architecture diagram&quot;
+</code></pre>
+<p><strong>7. Commit:</strong></p>
+<pre><code>commit_and_push:
+  commitMessage: &quot;refactor(api): use interceptors pattern for auth and error handling&quot;
+</code></pre>
+<p><strong>8. Release:</strong></p>
+<pre><code>perform_release:
+  command: &quot;npm run release:minor&quot;
+  notes: &quot;v1.4.0 - API service refactoring (internal improvement)&quot;
+</code></pre>
+<p><strong>9. Complete:</strong></p>
+<pre><code>complete_task:
+  commitMessage: &quot;refactor(api): use interceptors pattern for auth and error handling&quot;
+</code></pre>
+<hr>
+<h2>Using run_full_workflow</h2>
+<p><strong>Scenario:</strong> Quick feature when you know all the details upfront</p>
+<p>The <code>run_full_workflow</code> tool executes all workflow steps in one call:</p>
+<pre><code>run_full_workflow:
+  summary: &quot;Add dark mode toggle to settings&quot;
+  testCommand: &quot;npm test&quot;
+  testsPassed: true
+  testDetails: &quot;3 new tests for dark mode: all pass&quot;
+  documentationType: &quot;README&quot;
+  documentationSummary: &quot;Added dark mode section to README with usage&quot;
+  commitMessage: &quot;feat(ui): add dark mode toggle to settings&quot;
+  releaseCommand: &quot;npm run release:minor&quot;
+  releaseNotes: &quot;v1.5.0 - Dark mode support&quot;
+</code></pre>
+<p>This single call:</p>
+<ol>
+<li>✅ Marks the feature as fixed</li>
+<li>✅ Records test creation</li>
+<li>✅ Records test execution</li>
+<li>✅ Records documentation</li>
+<li>✅ Checks ready to commit</li>
+<li>✅ Commits and pushes</li>
+<li>✅ Performs release</li>
+<li>✅ Completes the task</li>
+</ol>
+<p><strong>When to use:</strong></p>
+<ul>
+<li>Simple, well-defined features</li>
+<li>You&#39;ve already done the work and just need to record it</li>
+<li>Batch processing multiple small changes</li>
+</ul>
+<p><strong>When not to use:</strong></p>
+<ul>
+<li>Complex features requiring step-by-step verification</li>
+<li>When tests might fail (you need to fix them first)</li>
+<li>Learning the workflow for the first time</li>
+</ul>
+<hr>
+<h2>Multi-Project Workflow</h2>
+<p><strong>Scenario:</strong> Working on multiple projects with separate workflow histories</p>
+<h3>Setup</h3>
+<p>Each project gets its own <code>.state/workflow-state.json</code>:</p>
+<pre><code class="language-bash"># Project A
+cd ~/projects/frontend-app
+npm install @programinglive/dev-workflow-mcp-server
+
+# Project B  
+cd ~/projects/backend-api
+npm install @programinglive/dev-workflow-mcp-server
+</code></pre>
+<h3>Usage</h3>
+<p>Workflows are automatically isolated by project:</p>
+<p><strong>In frontend-app:</strong></p>
+<pre><code>start_task:
+  description: &quot;Add checkout flow&quot;
+  type: &quot;feature&quot;
+
+# Work on frontend...
+# Complete workflow...
+</code></pre>
+<p><strong>In backend-api:</strong></p>
+<pre><code>start_task:
+  description: &quot;Add payment webhook endpoint&quot;
+  type: &quot;feature&quot;
+
+# Work on backend...
+# Complete workflow...
+</code></pre>
+<p>Each project tracks its own:</p>
+<ul>
+<li>Current task</li>
+<li>Workflow phase</li>
+<li>History</li>
+</ul>
+<p>View history for current project:</p>
+<pre><code>view_history:
+  limit: 5
+</code></pre>
+<p>This shows only the history for the current project!</p>
+<hr>
+<h2>Per-User Workflow Isolation</h2>
+<p><strong>Scenario:</strong> Multiple developers on the same machine or shared repository</p>
+<h3>Configuration</h3>
+<p>Set unique user IDs for each developer:</p>
+<p><strong>Developer 1 (Alice):</strong></p>
+<pre><code class="language-json">{
+  &quot;mcpServers&quot;: {
+    &quot;dev-workflow&quot;: {
+      &quot;command&quot;: &quot;node&quot;,
+      &quot;args&quot;: [&quot;d:\\code\\dev-workflow-mcp-server\\index.js&quot;],
+      &quot;env&quot;: {
+        &quot;DEV_WORKFLOW_USER_ID&quot;: &quot;alice&quot;
+      }
+    }
+  }
+}
+</code></pre>
+<p><strong>Developer 2 (Bob):</strong></p>
+<pre><code class="language-json">{
+  &quot;mcpServers&quot;: {
+    &quot;dev-workflow&quot;: {
+      &quot;command&quot;: &quot;node&quot;,
+      &quot;args&quot;: [&quot;d:\\code\\dev-workflow-mcp-server\\index.js&quot;],
+      &quot;env&quot;: {
+        &quot;DEV_WORKFLOW_USER_ID&quot;: &quot;bob&quot;
+      }
+    }
+  }
+}
+</code></pre>
+<h3>Result</h3>
+<p>Workflow states are isolated:</p>
+<ul>
+<li><code>.state/users/alice/workflow-state.db</code> - Alice&#39;s history</li>
+<li><code>.state/users/bob/workflow-state.db</code> - Bob&#39;s history</li>
+</ul>
+<p>Each developer can:</p>
+<ul>
+<li>Work on different tasks simultaneously</li>
+<li>Have independent workflow phases</li>
+<li>View their own history without seeing others</li>
+</ul>
+<h3>Web Dashboard</h3>
+<p>View specific user&#39;s history:</p>
+<pre><code class="language-bash">npm run web
+# Opens http://localhost:3111
+
+# Filter by user:
+# http://localhost:3111?user=alice
+# http://localhost:3111?user=bob
+</code></pre>
+<hr>
+<h2>Handling Test Failures</h2>
+<p><strong>Scenario:</strong> Tests fail during workflow</p>
+<h3>Workflow with Failure</h3>
+<p><strong>1. Start and implement:</strong></p>
+<pre><code>start_task:
+  description: &quot;Add email validation to signup form&quot;
+  type: &quot;feature&quot;
+
+mark_bug_fixed:
+  summary: &quot;Email validation with regex and domain verification&quot;
+
+create_tests
+</code></pre>
+<p><strong>2. Run tests (they fail!):</strong></p>
+<pre><code>run_tests:
+  passed: false
+  testCommand: &quot;npm test&quot;
+  details: &quot;2 of 4 tests failed: Invalid email format not caught&quot;
+</code></pre>
+<p><strong>Response:</strong></p>
+<pre><code>❌ Tests FAILED!
+🚫 Cannot proceed to commit with failing tests
+📝 Current phase: testing (blocked)
+
+You must:
+1. Fix the failing tests
+2. Re-run tests with passed: true
+</code></pre>
+<p><strong>3. Fix the bugs:</strong></p>
+<ul>
+<li>Update validation regex</li>
+<li>Fix edge case handling</li>
+</ul>
+<p><strong>4. Run tests again:</strong></p>
+<pre><code>run_tests:
+  passed: true
+  testCommand: &quot;npm test&quot;
+  details: &quot;All 4 tests now pass&quot;
+</code></pre>
+<p><strong>Response:</strong></p>
+<pre><code>✅ Tests passed!
+✅ Testing phase complete
+Next: Create documentation
+</code></pre>
+<p><strong>5. Continue workflow:</strong></p>
+<pre><code>create_documentation:
+  documentationType: &quot;inline-comments&quot;
+  summary: &quot;Added validation rules documentation&quot;
+
+commit_and_push:
+  commitMessage: &quot;feat(auth): add email validation to signup&quot;
+
+perform_release:
+  command: &quot;npm run release:minor&quot;
+
+complete_task:
+  commitMessage: &quot;feat(auth): add email validation to signup&quot;
+</code></pre>
+<h3>Key Takeaway</h3>
+<p><strong>The workflow blocks commits when tests fail!</strong> This enforces quality and prevents broken code from reaching your repository.</p>
+<hr>
+<h2>Advanced: Skipping Tests</h2>
+<p><strong>Scenario:</strong> Manual testing required (mobile app, hardware integration, etc.)</p>
+<pre><code>start_task:
+  description: &quot;Add iOS biometric authentication&quot;
+  type: &quot;feature&quot;
+
+mark_bug_fixed:
+  summary: &quot;Face ID and Touch ID integration complete&quot;
+
+skip_tests:
+  reason: &quot;Biometric auth requires physical iOS device testing; automated tests not feasible. Manual QA completed on iPhone 14 Pro and iPhone 12.&quot;
+</code></pre>
+<p><strong>Response:</strong></p>
+<pre><code>⚠️  Tests skipped with justification
+✅ Testing phase marked as satisfied
+📝 Task flagged for manual verification
+
+Reason: Biometric auth requires physical iOS device testing; automated tests not feasible. Manual QA completed on iPhone 14 Pro and iPhone 12.
+
+Next: Create documentation
+</code></pre>
+<p><strong>When to skip tests:</strong></p>
+<ul>
+<li>Hardware-dependent features</li>
+<li>Manual UI testing on specific devices</li>
+<li>Third-party service integration (with mocking limitations)</li>
+</ul>
+<p><strong>Best practice:</strong> Always provide detailed justification for audit trail.</p>
+<hr>
+<h2>Next Steps</h2>
+<ul>
+<li>Check <a href="./WORKFLOW-TEMPLATES.md">WORKFLOW-TEMPLATES.md</a> for ready-to-use templates</li>
+<li>See <a href="./TROUBLESHOOTING.md">TROUBLESHOOTING.md</a> for common issues</li>
+<li>Return to <a href="./GETTING-STARTED.md">GETTING-STARTED.md</a> for setup instructions</li>
+</ul>
+<hr>
+<p><strong>Happy coding with disciplined workflows!</strong> 🎯</p>

package/dist/docs/GETTING-STARTED.html

@@ -0,0 +1,233 @@
+<h1>Getting Started with Dev-Workflow MCP Server in Antigravity</h1>
+<p>This guide will help you set up and use the dev-workflow MCP server in the Antigravity text editor.</p>
+<h2>What is Dev-Workflow MCP Server?</h2>
+<p>The dev-workflow MCP server is a development discipline enforcer that guides you through proper software development workflows. It ensures you:</p>
+<ul>
+<li>✅ Start with a clear task description</li>
+<li>✅ Write tests for your changes</li>
+<li>✅ Run tests (and block commits if they fail)</li>
+<li>✅ Document your work</li>
+<li>✅ Follow a structured commit and release process</li>
+<li>✅ Track your development history</li>
+</ul>
+<h2>Prerequisites</h2>
+<ul>
+<li><strong>Node.js</strong> (v18 or later)</li>
+<li><strong>Antigravity</strong> text editor</li>
+<li><strong>Git</strong> installed and configured</li>
+<li>Basic understanding of terminal commands</li>
+</ul>
+<h2>Installation</h2>
+<h3>Option 1: Install in Your Project (Recommended)</h3>
+<p>This creates a project-specific workflow state:</p>
+<pre><code class="language-bash">cd your-project
+npm install @programinglive/dev-workflow-mcp-server
+</code></pre>
+<p>This automatically creates <code>.state/workflow-state.json</code> in your project root.</p>
+<h3>Option 2: Install from Source</h3>
+<pre><code class="language-bash">git clone https://github.com/programinglive/dev-workflow-mcp-server.git
+cd dev-workflow-mcp-server
+npm install
+</code></pre>
+<h2>Configuration in Antigravity</h2>
+<p>Antigravity uses an MCP configuration file located at:</p>
+<p><strong>Windows:</strong> <code>%APPDATA%\Antigravity\mcp_config.json</code> or <code>C:\Users\&lt;USERNAME&gt;\.gemini\antigravity\mcp_config.json</code></p>
+<p><strong>macOS:</strong> <code>~/Library/Application Support/Antigravity/mcp_config.json</code></p>
+<p><strong>Linux:</strong> <code>~/.config/antigravity/mcp_config.json</code></p>
+<h3>Configuration File</h3>
+<p>Create or edit the <code>mcp_config.json</code> file:</p>
+<pre><code class="language-json">{
+  &quot;mcpServers&quot;: {
+    &quot;dev-workflow&quot;: {
+      &quot;command&quot;: &quot;node&quot;,
+      &quot;args&quot;: [
+        &quot;d:\\code\\dev-workflow-mcp-server\\index.js&quot;
+      ]
+    }
+  }
+}
+</code></pre>
+<p><strong>Important Notes:</strong></p>
+<ul>
+<li>Use <strong>absolute paths</strong> to <code>index.js</code></li>
+<li>On Windows, use <strong>escaped backslashes</strong> (<code>\\</code>) in JSON</li>
+<li>Restart Antigravity after editing the configuration</li>
+</ul>
+<h3>Verify Installation</h3>
+<p>After restarting Antigravity, you should see dev-workflow tools available. You can verify by:</p>
+<ol>
+<li>Opening Antigravity</li>
+<li>Checking if MCP tools like <code>start_task</code>, <code>get_workflow_status</code> are available</li>
+<li>Running <code>get_workflow_status</code> to see the initial state</li>
+</ol>
+<h2>Your First Workflow</h2>
+<p>Let&#39;s walk through a complete development workflow:</p>
+<h3>1. Start a New Task</h3>
+<pre><code>Use start_task to begin:
+- description: &quot;Add header component to landing page&quot;
+- type: &quot;feature&quot;
+</code></pre>
+<p>The MCP server responds with your task ID and current phase.</p>
+<h3>2. Write Your Code</h3>
+<p>Implement your feature as you normally would. The workflow doesn&#39;t interfere with your coding.</p>
+<h3>3. Mark as Fixed</h3>
+<p>Once you&#39;ve completed the implementation:</p>
+<pre><code>Use mark_bug_fixed:
+- summary: &quot;Header component with logo and navigation menu&quot;
+</code></pre>
+<h3>4. Create Tests</h3>
+<p>The server will remind you to create tests. Write your tests, then:</p>
+<pre><code>Use create_tests (no parameters needed)
+</code></pre>
+<h3>5. Run Tests</h3>
+<p>Execute your test suite and record the results:</p>
+<pre><code>Use run_tests:
+- passed: true
+- testCommand: &quot;npm test&quot;
+- details: &quot;All 25 tests passed&quot;
+</code></pre>
+<blockquote>
+<p><strong>Important:</strong> If tests fail, the workflow will block you from proceeding!</p>
+</blockquote>
+<h3>6. Create Documentation</h3>
+<p>Update your documentation (README, inline comments, etc.):</p>
+<pre><code>Use create_documentation:
+- documentationType: &quot;README&quot;
+- summary: &quot;Added header component documentation and usage examples&quot;
+</code></pre>
+<h3>7. Commit and Push</h3>
+<p>The server will automatically stage, commit, and push your changes:</p>
+<pre><code>Use commit_and_push:
+- commitMessage: &quot;feat: add header component with navigation&quot;
+</code></pre>
+<p>The branch is auto-detected (main or master).</p>
+<h3>8. Perform Release</h3>
+<p>Record your release:</p>
+<pre><code>Use perform_release:
+- command: &quot;npm run release:patch&quot;
+- notes: &quot;Released header component&quot;
+</code></pre>
+<h3>9. Complete Task</h3>
+<p>Finally, mark the task as complete:</p>
+<pre><code>Use complete_task:
+- commitMessage: &quot;feat: add header component with navigation&quot;
+</code></pre>
+<h2>Antigravity vs. Windsurf</h2>
+<h3>Key Differences</h3>
+<table>
+<thead>
+<tr>
+<th>Feature</th>
+<th>Antigravity</th>
+<th>Windsurf</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><strong>Configuration</strong></td>
+<td><code>mcp_config.json</code> in <code>.gemini</code></td>
+<td><code>config.json</code> in app data</td>
+</tr>
+<tr>
+<td><strong>Tool Invocation</strong></td>
+<td>Direct MCP tool calls</td>
+<td>May use different interfaces</td>
+</tr>
+<tr>
+<td><strong>Workflow State</strong></td>
+<td>Per-user isolation with <code>DEV_WORKFLOW_USER_ID</code></td>
+<td>Shared state</td>
+</tr>
+<tr>
+<td><strong>Path Format</strong></td>
+<td>Windows requires <code>\\</code> escaping</td>
+<td>Same</td>
+</tr>
+</tbody></table>
+<h3>Avoiding Conflicts</h3>
+<p>If you use both Antigravity and Windsurf:</p>
+<ol>
+<li><p><strong>Use separate user IDs</strong> to isolate workflow states:</p>
+<pre><code class="language-bash"># In Antigravity MCP config, add environment variable
+export DEV_WORKFLOW_USER_ID=antigravity-user
+
+# In Windsurf, use different ID
+export DEV_WORKFLOW_USER_ID=windsurf-user
+</code></pre>
+</li>
+<li><p><strong>Don&#39;t run both simultaneously</strong> on the same project to avoid state conflicts</p>
+</li>
+<li><p><strong>Use project-specific installations</strong> to keep states isolated per project</p>
+</li>
+</ol>
+<h2>Common Workflows</h2>
+<h3>Quick Feature Development</h3>
+<p>For simple features, use <code>run_full_workflow</code>:</p>
+<pre><code>Use run_full_workflow with:
+- summary: &quot;Add contact form&quot;
+- testCommand: &quot;npm test&quot;
+- documentationType: &quot;README&quot;
+- documentationSummary: &quot;Added contact form docs&quot;
+- commitMessage: &quot;feat: add contact form&quot;
+- releaseCommand: &quot;npm run release:minor&quot;
+- testsPassed: true
+</code></pre>
+<p>This executes all workflow steps in one go!</p>
+<h3>Bug Fix Workflow</h3>
+<ol>
+<li><code>start_task</code> with type &quot;bugfix&quot;</li>
+<li>Fix the bug</li>
+<li><code>mark_bug_fixed</code></li>
+<li>Create regression tests</li>
+<li><code>create_tests</code></li>
+<li><code>run_tests</code></li>
+<li><code>create_documentation</code> (changelog)</li>
+<li><code>commit_and_push</code></li>
+<li><code>perform_release</code></li>
+<li><code>complete_task</code></li>
+</ol>
+<h3>When Tests Can&#39;t Be Automated</h3>
+<p>Sometimes automated tests aren&#39;t feasible (e.g., manual UI testing):</p>
+<pre><code>Use skip_tests:
+- reason: &quot;Mobile device testing requires manual QA on physical devices&quot;
+</code></pre>
+<p>This flags the task for manual verification but allows the workflow to continue.</p>
+<h2>Checking Your Status</h2>
+<p>At any time, check where you are:</p>
+<pre><code>Use get_workflow_status
+</code></pre>
+<p>This shows:</p>
+<ul>
+<li>Current task description</li>
+<li>Active phase (implementation, testing, documentation, etc.)</li>
+<li>Completed steps</li>
+<li>Next required step</li>
+</ul>
+<h2>Viewing History</h2>
+<p>See your completed tasks:</p>
+<pre><code>Use view_history:
+- limit: 10
+</code></pre>
+<p>This displays your recent workflow completions.</p>
+<h2>Next Steps</h2>
+<ul>
+<li>Read <a href="./EXAMPLES.md">EXAMPLES.md</a> for detailed real-world examples</li>
+<li>Check <a href="./WORKFLOW-TEMPLATES.md">WORKFLOW-TEMPLATES.md</a> for ready-to-use templates</li>
+<li>See <a href="./TROUBLESHOOTING.md">TROUBLESHOOTING.md</a> if you encounter issues</li>
+</ul>
+<h2>Tips for Success</h2>
+<ol>
+<li><strong>Always start with <code>start_task</code></strong> - This clarifies your intention</li>
+<li><strong>Never skip tests</strong> - They&#39;re mandatory for production code</li>
+<li><strong>Use conventional commit messages</strong> - e.g., <code>feat:</code>, <code>fix:</code>, <code>docs:</code></li>
+<li><strong>Keep tasks focused</strong> - One feature/bugfix per workflow</li>
+<li><strong>Check status frequently</strong> - Use <code>get_workflow_status</code> to stay on track</li>
+<li><strong>Review history</strong> - Learn from your past workflows</li>
+</ol>
+<h2>Getting Help</h2>
+<ul>
+<li><strong>Documentation:</strong> <a href="../../README.md">Main README</a></li>
+<li><strong>GitHub Issues:</strong> <a href="https://github.com/programinglive/dev-workflow-mcp-server/issues">Report bugs or request features</a></li>
+<li><strong>Troubleshooting:</strong> <a href="./TROUBLESHOOTING.md">Common issues and solutions</a></li>
+</ul>
+<hr>
+<p><strong>Ready to enforce development discipline with Antigravity? Start your first workflow now!</strong> 🚀</p>