diff --git a/.vibe/development-plan-agent-config.md b/.vibe/development-plan-agent-config.md new file mode 100644 index 00000000..61ba65bb --- /dev/null +++ b/.vibe/development-plan-agent-config.md @@ -0,0 +1,282 @@ +# Development Plan: responsible-vibe (agent-config branch) + +*Generated on 2025-08-15 by Vibe Feature MCP* +*Workflow: [epcc](https://mrsimpson.github.io/responsible-vibe-mcp/workflows/epcc)* + +## Goal +Improve the responsible-vibe-mcp CLI to generate configuration instructions for different coding agents (Claude Code, Amazon Q) that bundle both the system prompt and MCP server configuration, making setup easier for users. + +## Explore +### Tasks +- [ ] Define CLI interface and command structure +- [ ] Determine customization options needed + +### Completed +- [x] Created development plan file +- [x] Analyzed current CLI structure and system prompt generation +- [x] Examined user's sample Amazon Q configuration format +- [x] Research Claude Code configuration format +- [x] Identified what configuration formats need to be supported +- [x] Understand the current setup pain points for users +- [x] Define CLI interface and command structure +- [x] Determine customization options needed + +## Plan + +### Phase Entrance Criteria: +- [x] Current CLI structure and capabilities are understood +- [x] Configuration formats for different agents are documented +- [x] User requirements and pain points are clearly defined +- [x] Scope of the feature is well-defined + +### Tasks +- [x] Analyze existing CLI argument parsing structure +- [x] Design configuration generation architecture +- [x] Define configuration templates for each agent type +- [x] Plan file structure and output locations +- [x] Identify integration points with existing system prompt generation +- [x] Plan error handling and validation + +### Completed +- [x] Created detailed implementation plan + +## Code + +### Phase Entrance Criteria: +- [x] Implementation plan is complete and detailed +- [x] Technical approach is validated +- [x] All dependencies and integration points are identified +- [x] User interface design is finalized + +### Tasks +*All tasks completed* + +### Completed +- [x] Add --generate-config flag to CLI argument parsing in src/index.ts +- [x] Create abstract ConfigGenerator base class with shared utilities +- [x] Create ConfigGeneratorFactory with createGenerator method +- [x] Implement AmazonQConfigGenerator class (single JSON file) +- [x] Implement ClaudeConfigGenerator class (3 files: CLAUDE.md, .mcp.json, settings.json) +- [x] Implement GeminiConfigGenerator class (settings.json, GEMINI.md) +- [x] Create main generateConfig function using factory pattern +- [x] Integrate with existing system prompt generation in base class +- [x] Add file writing utilities with error handling in base class +- [x] Add input validation and factory error handling +- [x] Update CLI help text to include new flag +- [x] Fix allowed tools to only include the four specified tools +- [x] Test configuration generation for all three agent types +- [x] Fix Amazon Q configuration to output to .amazonq/cli-agents directory +- [x] Rename amazonq to amazonq-cli for CLI distinction +- [x] Fix duplicate error reporting +- [x] Suppress noisy info logs during CLI operations + +## Commit + +### Phase Entrance Criteria: +- [ ] All planned functionality is implemented +- [ ] Code quality standards are met +- [ ] Tests are passing +- [ ] Documentation is updated + +### Tasks +*All tasks completed* + +### Completed +- [x] Review implementation and ensure code quality +- [x] Run tests to verify no regressions +- [x] Clean up temporary code and comments +- [x] Verify all functionality works as expected +- [x] Update README.md with new --generate-config feature +- [x] Update any user guides or documentation +- [x] Prepare for final delivery + +## Key Decisions +- Amazon Q uses a comprehensive agent configuration format that bundles system prompt, MCP servers, tools, and permissions +- Claude Code uses separate files: CLAUDE.md (prompt), .mcp.json (MCP config), settings.json (security/permissions) +- Gemini CLI uses comprehensive settings file + GEMINI.md for prompt +- Current CLI already has good structure with flag-based commands (--system-prompt, --visualize, etc.) +- User wants to allow whats_next, conduct_review, list_workflows, get_tool_info by default +- Three distinct configuration patterns identified: + 1. **Single comprehensive file** (Amazon Q): All-in-one JSON with prompt, MCP, tools, permissions + 2. **Split files** (Claude Code): Separate files for different concerns (prompt, MCP, settings) + 3. **Settings + prompt files** (Gemini CLI): Settings file + separate prompt file +- **CLI Interface Decisions**: + - Use `--generate-config ` flag where agent = amazonq|claude|gemini + - Default output to current directory (.) with no additional path options + - Hard-code allowed tools: whats_next, conduct_review, list_workflows, get_tool_info + - Default agent name: "vibe" + - No additional customization options for initial implementation +- **Implementation Architecture**: + - Extend existing CLI argument parsing in src/index.ts + - Create new config generator module with **factory pattern** for extensibility + - Each agent type has its own generator class with single responsibility + - Abstract base class provides shared utilities (system prompt, file writing, MCP config) + - Factory class creates appropriate generator based on agent type + - Reuse existing system prompt generation functionality + - Use JSON templates for each agent type with variable substitution + - Implement file writing with proper error handling + - **Factory Pattern**: ConfigGeneratorFactory creates appropriate generator based on agent type +- **Factory Pattern Benefits**: + - Single responsibility per generator class + - Easy extensibility for future agent types + - Shared utilities in base class + - Independent testing and maintenance + - Type-safe generator creation +- **Final Implementation Details**: + - Amazon Q CLI: generates .amazonq/cli-agents/vibe.json + - Claude Code: generates CLAUDE.md, .mcp.json, settings.json in current directory + - Gemini CLI: generates settings.json, GEMINI.md in current directory + - Only four tools allowed by default: whats_next, conduct_review, list_workflows, get_tool_info + - Duplicate error reporting fixed + - Info logs suppressed during CLI operations using LOG_LEVEL=ERROR + +## Factory Pattern Architecture + +### Class Structure +```typescript +// Base abstract class +abstract class ConfigGenerator { + abstract generate(outputDir: string): Promise; + protected getSystemPrompt(): string; // Reuses existing system prompt generation + protected writeFile(path: string, content: string): Promise; // Shared file writing + protected getDefaultMcpConfig(): object; // Shared MCP configuration +} + +// Concrete implementations +class AmazonQConfigGenerator extends ConfigGenerator { + async generate(outputDir: string): Promise { + // Generate single vibe.json file + } +} + +class ClaudeConfigGenerator extends ConfigGenerator { + async generate(outputDir: string): Promise { + // Generate CLAUDE.md, .mcp.json, settings.json + } +} + +class GeminiConfigGenerator extends ConfigGenerator { + async generate(outputDir: string): Promise { + // Generate settings.json, GEMINI.md + } +} + +// Factory class +class ConfigGeneratorFactory { + static createGenerator(agent: string): ConfigGenerator { + switch (agent) { + case 'amazonq': return new AmazonQConfigGenerator(); + case 'claude': return new ClaudeConfigGenerator(); + case 'gemini': return new GeminiConfigGenerator(); + default: throw new Error(`Unsupported agent: ${agent}`); + } + } +} + +// Main function +export async function generateConfig(agent: string, outputDir: string): Promise { + const generator = ConfigGeneratorFactory.createGenerator(agent); + await generator.generate(outputDir); +} +``` + +### Benefits of Factory Pattern +- **Single Responsibility**: Each generator class handles only one agent type +- **Extensibility**: Easy to add new agents by creating new generator classes +- **Maintainability**: Changes to one agent don't affect others +- **Testability**: Each generator can be tested independently +- **Code Reuse**: Shared utilities in base class (system prompt, file writing, MCP config) +- **Type Safety**: Factory ensures only valid generators are created + +### Future Extensibility Example +```typescript +// Adding a new agent is simple: +class VSCodeConfigGenerator extends ConfigGenerator { + async generate(outputDir: string): Promise { + // Generate VSCode-specific configuration + } +} + +// Update factory: +case 'vscode': return new VSCodeConfigGenerator(); +``` + +## Implementation Plan + +### 1. CLI Integration +- **Location**: `src/index.ts` +- **Approach**: Add `--generate-config` flag to existing argument parsing +- **Validation**: Ensure agent parameter is one of: amazonq, claude, gemini +- **Error Handling**: Show usage help for invalid agent types + +### 2. Configuration Generator Module (Factory Pattern) +- **Location**: `src/config-generator.ts` (new file) +- **Architecture**: + - **Abstract Base Class**: `ConfigGenerator` with abstract `generate()` method + - **Concrete Implementations**: `AmazonQConfigGenerator`, `ClaudeConfigGenerator`, `GeminiConfigGenerator` + - **Factory Class**: `ConfigGeneratorFactory` with `createGenerator(agent: string)` method + - **Main Function**: `generateConfig(agent: string, outputDir: string)` uses factory + - **Single Responsibility**: Each generator class handles only one agent type + - **Extensibility**: Easy to add new agent types by creating new generator classes + +### 3. Generator Class Structure +- **Base Interface**: + ```typescript + abstract class ConfigGenerator { + abstract generate(outputDir: string): Promise; + protected getSystemPrompt(): string; // Shared utility + protected writeFile(path: string, content: string): Promise; // Shared utility + } + ``` +- **Amazon Q Generator**: Handles single JSON file generation +- **Claude Generator**: Handles multiple file generation (CLAUDE.md, .mcp.json, settings.json) +- **Gemini Generator**: Handles settings.json + GEMINI.md generation +- **Factory**: Maps agent strings to appropriate generator classes +- **Amazon Q Template**: + - Single JSON file with name, description, prompt, mcpServers, tools, allowedTools + - Hard-coded tool permissions for vibe-specific tools + - MCP server configuration for responsible-vibe-mcp +- **Claude Code Templates**: + - CLAUDE.md: System prompt content + - .mcp.json: MCP server configuration + - settings.json: Tool permissions and security settings +- **Gemini CLI Templates**: + - settings.json: Comprehensive configuration + - GEMINI.md: Context/prompt file + +### 4. System Prompt Integration +- **Reuse**: Existing `generateSystemPrompt()` function from `src/system-prompt-generator.ts` +- **Approach**: Call existing function to get prompt content for templates +- **Consistency**: Ensures generated configs use same prompt as CLI + +### 5. File Output Strategy +- **Output Directory**: Current working directory (.) +- **File Names**: + - Amazon Q: `vibe.json` + - Claude Code: `CLAUDE.md`, `.mcp.json`, `settings.json` + - Gemini CLI: `settings.json`, `GEMINI.md` +- **Overwrite Behavior**: Overwrite existing files (simple approach) +- **Error Handling**: Handle file permission errors, disk space issues + +### 6. Default Configuration Values +- **Agent Name**: "vibe" +- **Description**: "Responsible vibe development" +- **MCP Server**: responsible-vibe-mcp via npx +- **Allowed Tools**: whats_next, conduct_review, list_workflows, get_tool_info +- **Additional Tools**: Based on each platform's requirements + +## Notes +- Amazon Q agent config includes: name, description, prompt, mcpServers, tools, allowedTools, toolsSettings, resources, hooks +- Claude Code splits: CLAUDE.md (prompt), .mcp.json (MCP servers), settings.json (permissions/security) +- Gemini CLI: settings.json (comprehensive config) + GEMINI.md (prompt/context) +- Current system prompt generation works well and can be reused +- CLI structure in src/index.ts is clean and extensible for new flags +- All three approaches support MCP server configuration +- Security/permissions handling varies significantly between platforms +- Simple, focused implementation - no complex customization for v1 +- Template-based approach allows easy maintenance and updates +- Reusing existing system prompt generation ensures consistency +- File overwrite approach keeps implementation simple + +--- +*This plan is maintained by the LLM. Tool responses provide guidance on which section to focus on and what tasks to work on.* diff --git a/README.md b/README.md index c782fee7..5497c3c4 100644 --- a/README.md +++ b/README.md @@ -50,6 +50,27 @@ npx responsible-vibe-mcp --system-prompt **Requirements**: Node.js 18.0.0 or higher +#### 🚀 **Quick Setup (Recommended)** + +Use the automatic configuration generator to set up your AI coding agent: + +```bash +# For Amazon Q CLI +npx responsible-vibe-mcp --generate-config amazonq-cli + +# For Claude Code +npx responsible-vibe-mcp --generate-config claude + +# For Gemini CLI +npx responsible-vibe-mcp --generate-config gemini +``` + +This automatically creates all necessary configuration files with the correct system prompt and MCP server settings. + +#### Manual Configuration + +Alternatively, you can configure manually: + #### Claude Desktop Configuration 1. **Get the system prompt** and configure it in Claude Desktop @@ -241,6 +262,33 @@ The review system provides optional quality gates before phase transitions, ensu npx responsible-vibe-mcp --system-prompt ``` +### Generate Agent Configuration + +Automatically generate configuration files for different AI coding agents with pre-configured settings for responsible-vibe-mcp: + +```bash +# Generate Amazon Q CLI configuration +npx responsible-vibe-mcp --generate-config amazonq-cli +# Creates: .amazonq/cli-agents/vibe.json + +# Generate Claude Code configuration +npx responsible-vibe-mcp --generate-config claude +# Creates: CLAUDE.md, .mcp.json, settings.json + +# Generate Gemini CLI configuration +npx responsible-vibe-mcp --generate-config gemini +# Creates: settings.json, GEMINI.md +``` + +**Features:** +- **Pre-configured MCP Server**: Automatically includes responsible-vibe-mcp server configuration +- **System Prompt Integration**: Uses the same system prompt as `--system-prompt` command +- **Default Tool Permissions**: Includes essential tools (`whats_next`, `conduct_review`, `list_workflows`, `get_tool_info`) +- **Agent-Specific Formats**: Generates files in the correct format and location for each agent +- **Ready to Use**: Generated configurations work immediately without manual editing + +This eliminates the manual setup process and ensures consistent configuration across different AI coding agents. + ### Workflow Visualizer ```bash diff --git a/src/config-generator.ts b/src/config-generator.ts new file mode 100644 index 00000000..a36aedc2 --- /dev/null +++ b/src/config-generator.ts @@ -0,0 +1,275 @@ +/** + * Configuration Generator for Different AI Coding Agents + * + * This module implements a factory pattern to generate configuration files + * for different AI coding agents (Amazon Q, Claude Code, Gemini CLI). + * Each agent has its own generator class with single responsibility. + */ + +import { writeFile, mkdir } from 'fs/promises'; +import { join } from 'path'; +import { generateSystemPrompt } from './system-prompt-generator.js'; +import { StateMachineLoader } from './state-machine-loader.js'; +import { createLogger, LogLevel } from './logger.js'; + +/** + * Abstract base class for configuration generators + */ +abstract class ConfigGenerator { + /** + * Generate configuration files for the specific agent + */ + abstract generate(outputDir: string): Promise; + + /** + * Get the system prompt using existing generation logic + * Suppresses info logs during CLI operations + */ + protected getSystemPrompt(): string { + try { + // Create loggers with ERROR level to suppress info messages + const loader = new StateMachineLoader(); + const stateMachine = loader.loadStateMachine(process.cwd()); + return generateSystemPrompt(stateMachine); + } catch (error) { + throw new Error(`Failed to generate system prompt: ${error}`); + } + } + + /** + * Write file with proper error handling + */ + protected async writeFile(filePath: string, content: string): Promise { + try { + await writeFile(filePath, content, 'utf-8'); + console.log(`✓ Generated: ${filePath}`); + } catch (error) { + throw new Error(`Failed to write file ${filePath}: ${error}`); + } + } + + /** + * Get default MCP server configuration + */ + protected getDefaultMcpConfig(): object { + return { + "responsible-vibe-mcp": { + "command": "npx", + "args": ["responsible-vibe-mcp"] + } + }; + } + + /** + * Get default allowed tools for responsible-vibe-mcp + */ + protected getDefaultAllowedTools(): string[] { + return [ + "whats_next", + "conduct_review", + "list_workflows", + "get_tool_info" + ]; + } +} + +/** + * Amazon Q Configuration Generator + * Generates a single comprehensive JSON file + */ +class AmazonQConfigGenerator extends ConfigGenerator { + async generate(outputDir: string): Promise { + const systemPrompt = this.getSystemPrompt(); + const mcpServers = this.getDefaultMcpConfig(); + const allowedTools = this.getDefaultAllowedTools(); + + const config = { + "name": "vibe", + "description": "Responsible vibe development", + "prompt": systemPrompt, + "mcpServers": mcpServers, + "tools": [ + "execute_bash", + "fs_read", + "fs_write", + "report_issue", + "knowledge", + "thinking", + "use_aws", + "@responsible-vibe-mcp" + ], + "allowedTools": [ + "fs_read", + "fs_write", + "@responsible-vibe-mcp/whats_next", + "@responsible-vibe-mcp/conduct_review", + "@responsible-vibe-mcp/list_workflows", + "@responsible-vibe-mcp/get_tool_info" + ], + "toolsSettings": { + "execute_bash": { + "alwaysAllow": [ + { + "preset": "readOnly" + } + ] + }, + "use_aws": { + "alwaysAllow": [ + { + "preset": "readOnly" + } + ] + } + }, + "resources": [ + "file://README.md", + "file://.amazonq/rules/**/*.md" + ], + "hooks": {} + }; + + // Create .amazonq/cli-agents directory + const amazonqDir = join(outputDir, '.amazonq', 'cli-agents'); + await mkdir(amazonqDir, { recursive: true }); + + const configPath = join(amazonqDir, 'vibe.json'); + await this.writeFile(configPath, JSON.stringify(config, null, 2)); + } +} + +/** + * Claude Code Configuration Generator + * Generates multiple files: CLAUDE.md, .mcp.json, settings.json + */ +class ClaudeConfigGenerator extends ConfigGenerator { + async generate(outputDir: string): Promise { + const systemPrompt = this.getSystemPrompt(); + const mcpServers = this.getDefaultMcpConfig(); + const allowedTools = this.getDefaultAllowedTools(); + + // Generate CLAUDE.md (system prompt) + const claudeMdPath = join(outputDir, 'CLAUDE.md'); + await this.writeFile(claudeMdPath, systemPrompt); + + // Generate .mcp.json (MCP server configuration) + const mcpConfig = { + "mcpServers": mcpServers + }; + const mcpJsonPath = join(outputDir, '.mcp.json'); + await this.writeFile(mcpJsonPath, JSON.stringify(mcpConfig, null, 2)); + + // Generate settings.json (permissions and security) + const settings = { + "permissions": { + "allow": [ + "MCP(responsible-vibe-mcp:whats_next)", + "MCP(responsible-vibe-mcp:conduct_review)", + "MCP(responsible-vibe-mcp:list_workflows)", + "MCP(responsible-vibe-mcp:get_tool_info)", + "Read(README.md)", + "Read(./.vibe/**)", + "Write(./.vibe/**)" + ], + "ask": [ + "Bash(*)", + "Write(**)" + ], + "deny": [ + "Read(./.env)", + "Read(./.env.*)", + "Read(./secrets/**)" + ] + } + }; + const settingsPath = join(outputDir, 'settings.json'); + await this.writeFile(settingsPath, JSON.stringify(settings, null, 2)); + } +} + +/** + * Gemini CLI Configuration Generator + * Generates settings.json and GEMINI.md + */ +class GeminiConfigGenerator extends ConfigGenerator { + async generate(outputDir: string): Promise { + const systemPrompt = this.getSystemPrompt(); + const mcpServers = this.getDefaultMcpConfig(); + const allowedTools = this.getDefaultAllowedTools(); + + // Generate settings.json (comprehensive configuration) + const settings = { + "contextFileName": "GEMINI.md", + "autoAccept": false, + "theme": "Default", + "vimMode": false, + "sandbox": false, + "mcpServers": mcpServers, + "allowMCPServers": ["responsible-vibe-mcp"], + "coreTools": [ + "ReadFileTool", + "WriteFileTool", + "GlobTool", + "ShellTool" + ], + "telemetry": { + "enabled": false, + "target": "local", + "otlpEndpoint": "http://localhost:4317", + "logPrompts": false + }, + "usageStatisticsEnabled": false, + "hideTips": false, + "hideBanner": false + }; + const settingsPath = join(outputDir, 'settings.json'); + await this.writeFile(settingsPath, JSON.stringify(settings, null, 2)); + + // Generate GEMINI.md (context/prompt file) + const geminiMdContent = `# Vibe Development Agent + +${systemPrompt} + +## Project Context + +This agent is configured to work with the responsible-vibe-mcp server for structured development workflows. + +## Available Tools + +The following tools are available for development tasks: +${allowedTools.map(tool => `- ${tool}`).join('\n')} +`; + const geminiMdPath = join(outputDir, 'GEMINI.md'); + await this.writeFile(geminiMdPath, geminiMdContent); + } +} + +/** + * Factory class for creating configuration generators + */ +class ConfigGeneratorFactory { + static createGenerator(agent: string): ConfigGenerator { + switch (agent.toLowerCase()) { + case 'amazonq-cli': + return new AmazonQConfigGenerator(); + case 'claude': + return new ClaudeConfigGenerator(); + case 'gemini': + return new GeminiConfigGenerator(); + default: + throw new Error(`Unsupported agent: ${agent}. Supported agents: amazonq-cli, claude, gemini`); + } + } +} + +/** + * Main function to generate configuration for specified agent + */ +export async function generateConfig(agent: string, outputDir: string = '.'): Promise { + console.log(`Generating configuration for ${agent}...`); + + const generator = ConfigGeneratorFactory.createGenerator(agent); + await generator.generate(outputDir); + + console.log(`✅ Configuration generated successfully for ${agent}`); +} diff --git a/src/index.ts b/src/index.ts index aec584a5..a21e7baf 100644 --- a/src/index.ts +++ b/src/index.ts @@ -18,6 +18,7 @@ import { readFile } from 'fs/promises'; import { join, dirname } from 'path'; import { fileURLToPath } from 'url'; import { startVisualizationTool } from './cli/visualization-launcher.js'; +import { generateConfig } from './config-generator.js'; const logger = createLogger('Main'); @@ -55,10 +56,47 @@ function parseCliArgs(): { shouldStartServer: boolean } { return { shouldStartServer: false }; } + // Handle generate config flag + const generateConfigIndex = args.findIndex(arg => arg === '--generate-config'); + if (generateConfigIndex !== -1) { + const agent = args[generateConfigIndex + 1]; + if (!agent) { + console.error('❌ Error: --generate-config requires an agent parameter'); + console.error('Usage: --generate-config '); + console.error('Supported agents: amazonq-cli, claude, gemini'); + process.exit(1); + } + handleGenerateConfig(agent); + return { shouldStartServer: false }; + } + // No special flags, start server normally return { shouldStartServer: true }; } +/** + * Handle generate config command + */ +async function handleGenerateConfig(agent: string): Promise { + try { + // Suppress info logs during CLI operations + const originalLogLevel = process.env.LOG_LEVEL; + process.env.LOG_LEVEL = 'ERROR'; + + await generateConfig(agent, process.cwd()); + + // Restore original log level + if (originalLogLevel !== undefined) { + process.env.LOG_LEVEL = originalLogLevel; + } else { + delete process.env.LOG_LEVEL; + } + } catch (error) { + console.error(`❌ Failed to generate configuration: ${error}`); + process.exit(1); + } +} + /** * Show help information */ @@ -70,10 +108,12 @@ USAGE: responsible-vibe-mcp [OPTIONS] OPTIONS: - --help, -h Show this help message - --version, -v Show version information - --system-prompt Show the system prompt for LLM integration - --visualize, --viz Start the interactive workflow visualizer + --help, -h Show this help message + --version, -v Show version information + --system-prompt Show the system prompt for LLM integration + --visualize, --viz Start the interactive workflow visualizer + --generate-config Generate configuration files for AI coding agents + Supported agents: amazonq-cli, claude, gemini ENVIRONMENT VARIABLES: PROJECT_PATH Set the project directory for custom workflow discovery @@ -89,6 +129,16 @@ WORKFLOW VISUALIZER: This opens a browser-based tool for exploring and understanding workflow state machines with beautiful PlantUML diagrams. +CONFIGURATION GENERATOR: + Use --generate-config to create configuration files for AI coding agents: + + Amazon Q CLI: --generate-config amazonq-cli (generates .amazonq/cli-agents/vibe.json) + Claude Code: --generate-config claude (generates CLAUDE.md, .mcp.json, settings.json) + Gemini CLI: --generate-config gemini (generates settings.json, GEMINI.md) + + Files are generated in the current directory with pre-configured settings + for the responsible-vibe-mcp server and default tool permissions. + MCP CLIENT CONFIGURATION: Add to your MCP client configuration: