import{_ as i,c as t,o as e,a0 as a}from"./chunks/framework.FdfEk_gD.js";const c=JSON.parse('{"title":"Agent Setup Guide","description":"","frontmatter":{},"headers":[],"relativePath":"user/agent-setup.md","filePath":"user/agent-setup.md"}'),n={name:"user/agent-setup.md"};function l(o,s,p,h,r,d){return e(),t("div",null,[...s[0]||(s[0]=[a(`<h1 id="agent-setup-guide" tabindex="-1">Agent Setup Guide <a class="header-anchor" href="#agent-setup-guide" aria-label="Permalink to &quot;Agent Setup Guide&quot;">​</a></h1><p>This guide explains how to set up AI coding agents to work with the workflows server.</p><h2 id="core-concepts" tabindex="-1">Core Concepts <a class="header-anchor" href="#core-concepts" aria-label="Permalink to &quot;Core Concepts&quot;">​</a></h2><p>Every AI coding agent needs two things to work with the workflows server:</p><h3 id="_1-system-prompt" tabindex="-1">1. System Prompt <a class="header-anchor" href="#_1-system-prompt" aria-label="Permalink to &quot;1. System Prompt&quot;">​</a></h3><p>Instructions that tell the agent how to use the MCP tools. The system prompt teaches the agent to:</p><ul><li>Call <code>whats_next()</code> after each user interaction</li><li>Follow the workflow phases (explore, plan, code, commit, etc.)</li><li>Update the plan file to maintain project memory</li><li>Request phase transitions when appropriate</li></ul><h3 id="_2-mcp-server-connection" tabindex="-1">2. MCP Server Connection <a class="header-anchor" href="#_2-mcp-server-connection" aria-label="Permalink to &quot;2. MCP Server Connection&quot;">​</a></h3><p>A connection to the workflows server that provides the actual tools:</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;mcpServers&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">    &quot;workflows&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      &quot;command&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;npx&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      &quot;args&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;-y&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;@codemcp/workflows-server&quot;</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>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h2 id="setup-via-cli" tabindex="-1">Setup via CLI <a class="header-anchor" href="#setup-via-cli" aria-label="Permalink to &quot;Setup via CLI&quot;">​</a></h2><p>The CLI generates both the system prompt and MCP configuration for your agent:</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;"> @codemcp/workflows</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> setup</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">targe</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">t</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--mode </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">config</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">|</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">skill]</span></span></code></pre></div><h3 id="modes" tabindex="-1">Modes <a class="header-anchor" href="#modes" aria-label="Permalink to &quot;Modes&quot;">​</a></h3><table tabindex="0"><thead><tr><th>Mode</th><th>Description</th></tr></thead><tbody><tr><td><code>config</code></td><td>Embeds system prompt in agent configuration files (traditional approach)</td></tr><tr><td><code>skill</code></td><td>Creates <a href="https://agentskills.io" target="_blank" rel="noreferrer">agentskills.io</a> compatible skill files (on-demand loading)</td></tr></tbody></table><p><strong>Config mode</strong> is best when you always want the workflow guidance active.</p><p><strong>Skill mode</strong> is best when you want the agent to load workflow instructions only when needed.</p><h3 id="targets" tabindex="-1">Targets <a class="header-anchor" href="#targets" aria-label="Permalink to &quot;Targets&quot;">​</a></h3><table tabindex="0"><thead><tr><th>Target</th><th>Aliases</th><th>Description</th></tr></thead><tbody><tr><td><code>kiro</code></td><td><code>kiro-cli</code>.</td><td>Kiro / Kiro CLI</td></tr><tr><td><code>claude</code></td><td><code>claude-code</code>, <code>claude-desktop</code></td><td>Claude Code</td></tr><tr><td><code>gemini</code></td><td><code>gemini-cli</code></td><td>Gemini CLI</td></tr><tr><td><code>opencode</code></td><td>-</td><td>OpenCode CLI</td></tr><tr><td><code>copilot</code></td><td><code>copilot-vscode</code>, <code>vscode</code>, <code>github-copilot</code></td><td>GitHub Copilot</td></tr></tbody></table><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:#6A737D;--shiki-dark:#6A737D;"># Config mode - embeds system prompt (default)</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @codemcp/workflows</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> setup</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> claude</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @codemcp/workflows</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> setup</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> kiro</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Skill mode - on-demand loading</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @codemcp/workflows</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> setup</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> copilot</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --mode</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> skill</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @codemcp/workflows</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> setup</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> gemini</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --mode</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> skill</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># List all available targets</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @codemcp/workflows</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> setup</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> list</span></span></code></pre></div><h2 id="manual-setup" tabindex="-1">Manual Setup <a class="header-anchor" href="#manual-setup" aria-label="Permalink to &quot;Manual Setup&quot;">​</a></h2><p>For unsupported agents or custom configurations:</p><ol><li><p><strong>Get the system prompt</strong> from any generated config file (e.g., <code>CLAUDE.md</code>, <code>GEMINI.md</code>)</p></li><li><p><strong>Configure MCP server</strong> in your agent&#39;s settings:</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;mcpServers&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">    &quot;workflows&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      &quot;command&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;npx&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      &quot;args&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;-y&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;@codemcp/workflows-server&quot;</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>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div></li><li><p><strong>Grant tool permissions</strong> for these essential tools:</p><ul><li><code>whats_next</code></li><li><code>start_development</code></li><li><code>proceed_to_phase</code></li><li><code>conduct_review</code></li><li><code>list_workflows</code></li><li><code>get_tool_info</code></li></ul></li></ol><h2 id="verification" tabindex="-1">Verification <a class="header-anchor" href="#verification" aria-label="Permalink to &quot;Verification&quot;">​</a></h2><p>After setup, verify the integration works:</p><ol><li>Start a conversation with your agent</li><li>Ask: &quot;Help me implement a new feature&quot;</li><li>The agent should call <code>start_development()</code> or <code>whats_next()</code></li><li>Check for <code>.vibe/development-plan-*.md</code> files being created</li></ol><h2 id="troubleshooting" tabindex="-1">Troubleshooting <a class="header-anchor" href="#troubleshooting" aria-label="Permalink to &quot;Troubleshooting&quot;">​</a></h2><p><strong>Agent doesn&#39;t call MCP tools:</strong></p><ul><li>Verify system prompt is configured correctly</li><li>Check MCP server connection in agent settings</li><li>Restart your agent/IDE</li></ul><p><strong>&quot;Tool not found&quot; errors:</strong></p><ul><li>Run <code>npx @codemcp/workflows</code> directly to test the server</li><li>Check server configuration path and permissions</li></ul><p><strong>Project path issues:</strong></p><ul><li>Set <code>PROJECT_PATH</code> environment variable in MCP config if needed</li><li>Ensure the path exists and is writable</li></ul><h2 id="next-steps" tabindex="-1">Next Steps <a class="header-anchor" href="#next-steps" aria-label="Permalink to &quot;Next Steps&quot;">​</a></h2><ul><li><strong><a href="./how-it-works.html">How It Works</a></strong> – Understand the development flow</li><li><strong><a href="./tutorial.html">Tutorial</a></strong> – Hands-on walkthrough</li><li><strong><a href="./../workflows.html">Workflows</a></strong> – Explore available methodologies</li></ul>`,36)])])}const g=i(n,[["render",l]]);export{c as __pageData,g as default};
