Agent Setup Guide

This guide explains how to set up AI coding agents to work with the workflows server.

Core Concepts

Every AI coding agent needs two things to work with the workflows server:

1. System Prompt

Instructions that tell the agent how to use the MCP tools. The system prompt teaches the agent to:

• Call whats_next() after each user interaction
• Follow the workflow phases (explore, plan, code, commit, etc.)
• Update the plan file to maintain project memory
• Request phase transitions when appropriate

2. MCP Server Connection

A connection to the workflows server that provides the actual tools:

{
  "mcpServers": {
    "workflows": {
      "command": "npx",
      "args": ["-y", "@codemcp/workflows-server"]
    }
  }
}

Setup via CLI

The CLI generates both the system prompt and MCP configuration for your agent:

npx @codemcp/workflows setup <mode> <target>

Modes

Mode	Description
config	Embeds system prompt in agent configuration files (traditional approach)
skill	Creates agentskills.io compatible skill files (on-demand loading)

Config mode is best when you always want the workflow guidance active.

Skill mode is best when you want the agent to load workflow instructions only when needed.

Targets

Target	Aliases	Description
kiro	amazonq-cli, amazonq	Kiro / Amazon Q CLI
claude	claude-code, claude-desktop	Claude Code
gemini	gemini-cli	Gemini CLI
opencode	-	OpenCode CLI
copilot	copilot-vscode, vscode, github-copilot	GitHub Copilot

Examples

# Config mode - embeds system prompt
npx @codemcp/workflows setup config claude
npx @codemcp/workflows setup config kiro

# Skill mode - on-demand loading
npx @codemcp/workflows setup skill copilot
npx @codemcp/workflows setup skill gemini

# List all available targets
npx @codemcp/workflows setup

Manual Setup

For unsupported agents or custom configurations:

1. Get the system prompt from any generated config file (e.g., CLAUDE.md, GEMINI.md)

2. Configure MCP server in your agent's settings:

   {
     "mcpServers": {
       "workflows": {
         "command": "npx",
         "args": ["-y", "@codemcp/workflows-server"]
       }
     }
   }

3. Grant tool permissions for these essential tools:

   • whats_next
   • start_development
   • proceed_to_phase
   • conduct_review
   • list_workflows
   • get_tool_info

Verification

After setup, verify the integration works:

1. Start a conversation with your agent
2. Ask: "Help me implement a new feature"
3. The agent should call start_development() or whats_next()
4. Check for .vibe/development-plan-*.md files being created

Troubleshooting

Agent doesn't call MCP tools:

• Verify system prompt is configured correctly
• Check MCP server connection in agent settings
• Restart your agent/IDE

"Tool not found" errors:

• Run npx @codemcp/workflows directly to test the server
• Check server configuration path and permissions

Project path issues:

• Set PROJECT_PATH environment variable in MCP config if needed
• Ensure the path exists and is writable

Next Steps

• How It Works – Understand the development flow
• Tutorial – Hands-on walkthrough
• Workflows – Explore available methodologies