DevOps AI Toolkit

# PRD: Unified Deployment Tool (recommend) **Status**: Complete **Created**: 2025-01-20 **Last Updated**: 2025-10-01 **GitHub Issue**: [#114](https://github.com/vfarcic/dot-ai/issues/114) ## Problem Statement The current Kubernetes deployment workflow requires users and AI agents to manually orchestrate **5 separate MCP tools** in sequence: 1. `recommend` - Get deployment recommendations 2. `chooseSolution` - Select a specific solution 3. `answerQuestion` - Configure solution parameters 4. `generateManifests` - Create Kubernetes manifests 5. `deployManifests` - Deploy to cluster This creates unnecessary complexity for: - **AI Agents**: Must manage complex state and error handling across 5 tools - **Developers**: Need to understand and coordinate multiple tool interactions - **Integration**: Each tool integration point is a potential failure point ## Solution Overview Extend the **`recommend` tool** with stage-based routing to consolidate the entire deployment workflow into a single MCP tool, following the same pattern as `remediate` and `manageOrgData`. ### Key Principles - **Same User Experience**: Zero changes to user interaction patterns - **Internal Routing**: Use `stage` parameter to route to existing tool handlers - **Universal Scope**: Support deployment of anything accessible through Kubernetes API (including CRDs) - **Function Reuse**: All existing tool functions remain unchanged ## Technical Approach ### Stage-Based Routing Single tool with `stage` parameter routes to existing handlers: - `stage: 'recommend'` → `handleRecommendTool()` - `stage: 'chooseSolution'` → `handleChooseSolutionTool()` - `stage: 'answerQuestion'` → `handleAnswerQuestionTool()` - `stage: 'generateManifests'` → `handleGenerateManifestsTool()` - `stage: 'deployManifests'` → `handleDeployManifestsTool()` ### Parameter Consolidation Unified parameter schema accepts all parameters from existing tools plus routing: ```typescript { stage?: 'recommend' | 'chooseSolution' | 'answerQuestion' | 'generateManifests' | 'deployManifests', // Default: 'recommend' if stage is undefined/empty // All existing parameters from 5 tools intent?: string, final?: boolean, solutionId?: string, answers?: object, timeout?: number, // etc... } ``` **Stage Parameter Behavior**: When `stage` is undefined or omitted, it defaults to `'recommend'`. This simplifies initial deployment requests where users can call `recommend({ intent: "deploy database" })` without explicitly specifying the stage. ## Success Criteria ### Must Have - [x] Single `recommend` tool with stage routing replaces 5-tool orchestration - [x] Identical user experience to current workflow - [x] All existing tool functions work unchanged - [x] Complete workflow from intent to deployment - [x] Clean cutover with immediate removal of 4 separate tools (chooseSolution, answerQuestion, generateManifests, deployManifests) ### Should Have - [x] Improved error handling through unified workflow - [x] Enhanced debugging through consolidated logging - [x] Simplified agent integration patterns ## Implementation Milestones ### Milestone 1: Core Tool Structure ✅ - [x] Extend `recommend` tool with stage-based routing - [x] Implement stage routing system in recommend handler - [x] Route to existing tool handlers based on stage - [x] Validate basic parameter passing with stage ### Milestone 2: MCP Integration ✅ - [x] Update `recommend` tool MCP registration - [x] Remove 4 separate tool registrations (chooseSolution, answerQuestion, generateManifests, deployManifests) - [x] Update `recommend` registration with unified schema supporting stage parameter - [x] Test MCP tool discovery shows single `recommend` tool ### Milestone 3: Complete Workflow Testing ✅ - [x] Test each stage routing correctly - [x] Validate parameter passing between stages - [x] Test complete deployment workflows - [x] Ensure session continuity ### Milestone 4: Test Suite Updates ✅ - [x] Update `tests/integration/tools/recommend.test.ts` to test stage-based routing - [x] Refactor test to include `stage` parameter in all calls - [x] Ensure all 5 workflow stages validated (recommend, chooseSolution, answerQuestion, generateManifests, deployManifests) - [x] Validate default stage behavior (undefined → 'recommend') - [ ] Performance testing ### Milestone 5: Documentation & Migration ✅ - [x] Update shared prompts to reference stage parameter - [x] Update MCP documentation for `recommend` tool with stages - [x] Create migration guide showing stage parameter usage - [x] Update user guides and examples ### Milestone 6: Backwards Compatibility ✅ ~~This milestone has been removed based on design decision to perform immediate cutover without backwards compatibility period.~~ ## Risk Assessment ### Low Risks - **Function Changes**: All existing tool functions remain unchanged - **User Experience**: Exact same interaction patterns maintained - **Testing**: Existing tests can be adapted with minimal changes ### Medium Risks - **MCP Registration**: Changes to tool registration require careful validation - **Parameter Handling**: Must ensure all parameters reach correct handlers ## Dependencies ### Internal Dependencies - Existing deployment tools and handlers - MCP server infrastructure - Current parameter schemas - Session management systems ### External Dependencies - MCP protocol compliance - Kubernetes API access - Vector database services - AI service integrations ## Design Decisions ### Decision 1: Immediate Tool Removal (2025-10-01) **Decision**: Remove all 5 separate MCP tools immediately without backwards compatibility period **Rationale**: - Simplifies implementation and testing - Eliminates maintenance burden of parallel tool sets - Cleaner architecture with single tool interface - No existing external integrations to migrate **Impact**: - Milestone 6 (Backwards Compatibility) removed from scope - Success criteria updated to reflect clean cutover approach - MCP registration will only include unified `deploy` tool - No deprecation warnings or migration timeline needed **Code Impact**: `src/interfaces/mcp.ts` will remove 4 tool registrations (chooseSolution, answerQuestion, generateManifests, deployManifests) and update `recommend` registration with unified schema --- ### Decision 2: Default Stage Behavior (2025-10-01) **Decision**: Empty/undefined `stage` parameter defaults to `'recommend'` **Rationale**: - Simplifies initial deployment requests - Users can start workflow with just `deploy({ intent: "..." })` - Reduces cognitive load for most common use case - Follows principle of least surprise **Impact**: - Parameter schema documentation updated - Router implementation includes default logic - Integration tests validate default behavior **Code Impact**: ```typescript const stage = args.stage || 'recommend'; // Default routing ``` --- ### Decision 4: Integration Test Update Strategy (2025-10-01) **Decision**: Update existing `recommend.test.ts` integration tests to test stage-based routing instead of creating new test files **Rationale**: - Existing `tests/integration/tools/recommend.test.ts` already covers complete 5-stage deployment workflow - Follows integration testing principle: "Eliminate Redundancy - always check if functionality is already covered" - Maintains "One Comprehensive Test" pattern from integration testing standards - Reduces maintenance burden by updating rather than duplicating test coverage **Impact**: - Milestone 4 scope changed from "create integration tests" to "update existing integration tests" - Test file will be renamed/refactored to test `deploy` tool instead of separate `recommend` tool - All existing workflow coverage preserved while validating unified tool interface **Code Impact**: `tests/integration/tools/recommend.test.ts` will be updated to include `stage` parameter in calls instead of using separate tool endpoints --- ### Decision 3: Test-Driven Development Approach (2025-10-01) **Decision**: Implement using strict TDD methodology (tests before code) **Rationale**: - Ensures comprehensive test coverage from start - Validates design before implementation - Catches integration issues early - Provides living documentation of expected behavior **Impact**: - Implementation order changed: tests → code → validation - Integration tests created before tool implementation - Each milestone requires passing tests before proceeding **Code Impact**: `tests/integration/tools/recommend.test.ts` updated with stage parameters first, then `src/tools/recommend.ts` and `src/interfaces/mcp.ts` updated to implement routing and pass tests --- ### Decision 5: Use `recommend` Tool Name Instead of `deploy` (2025-10-01) **Decision**: Keep tool name as `recommend` with stage-based routing instead of creating new `deploy` tool **Rationale**: - `recommend` is already the natural entry point for the deployment workflow - More intuitive for users - "recommend" encompasses the full deployment journey from intent to deployment - Avoids confusion with kubectl deploy/deployManifests commands - Maintains existing tool naming conventions while consolidating functionality - Users already understand `recommend` as the starting point **Impact**: - Tool naming: Use `recommend` (not `deploy`) for unified tool - API endpoint remains: `/api/v1/tools/recommend` - Test file naming: `recommend.test.ts` already correct, no rename needed - Success criteria updated to reference `recommend` tool - Documentation clarity: "recommend with stages" is more descriptive than "deploy" **Code Impact**: ```typescript // MCP registration uses 'recommend' as tool name export const RECOMMEND_TOOL_NAME = 'recommend'; // Routing logic within recommend tool handler const stage = args.stage || 'recommend'; // Default to initial stage switch (stage) { case 'recommend': return handleRecommendLogic(...); case 'chooseSolution': return handleChooseSolutionTool(...); // etc... } ``` --- ## Definition of Done - [x] `recommend` tool extended with stage-based routing - [x] MCP registration updated (4 separate tools removed: chooseSolution, answerQuestion, generateManifests, deployManifests) - [x] All existing workflows function identically - [x] Tests passing (integration tests updated in `recommend.test.ts` to validate stage routing) - [x] Documentation updated - [x] Integration tests validate all stages including default behavior ## Progress Log ### 2025-01-20 - **Created**: Initial PRD and implementation planning - **Status**: Beginning implementation with core tool structure ### 2025-10-01 (Morning) - **Design Decisions**: Captured 3 key decisions from implementation planning - Immediate tool removal (no backwards compatibility) - Default stage behavior (undefined → 'recommend') - Test-Driven Development approach - **PRD Updates**: Updated success criteria, parameter schema, and removed Milestone 6 - **Status**: Ready to begin TDD implementation starting with integration tests ### 2025-10-01 (Afternoon): TDD Preparation - Integration Tests Written **Duration**: ~2 hours **Focus**: Test-driven development preparation and design decisions **Completed PRD Items**: - [x] Decision 5: Use `recommend` tool name instead of `deploy` - Evidence: PRD updated with rationale and code examples - [x] Update integration tests for stage-based routing - Evidence: tests/integration/tools/recommend.test.ts refactored with stage parameters - [x] Define stage routing format - Evidence: `answerQuestion:required` pattern documented - [x] Define agent instruction format - Evidence: `'Call recommend tool with stage: X'` pattern in tests **Key Decisions Made**: - **Tool naming**: Keep `recommend` (not `deploy`) for intuitive user experience and avoid confusion with kubectl deploy - **Stage format**: Use colon notation (`answerQuestion:required`) to combine routing with sub-parameters, eliminating parameter naming conflicts - **Agent instructions**: Explicit format `'Call recommend tool with stage: X'` for maximum clarity to AI agents **Test Updates**: - Updated all API calls from separate tool endpoints to unified `/api/v1/tools/recommend` with stage parameter - Updated all response expectations to use `tool: 'recommend'` - Updated all `nextAction` instructions to reference stage-based routing - Added test coverage for default stage behavior (omitted stage defaults to 'recommend') **Next Session Priorities**: 1. Implement stage routing in `src/tools/recommend.ts` handler 2. Update MCP registration in `src/interfaces/mcp.ts` to remove 4 separate tools 3. Run integration tests to validate implementation (tests currently written but will fail until implementation complete) --- ### 2025-10-01 (Evening): Stage Routing Implementation Complete **Duration**: ~3 hours **Commits**: 3 commits (test infrastructure fixes, TDD tests, stage routing implementation) **Completed PRD Items** (Milestone 1 & Milestone 3): - [x] Implement stage routing system - Evidence: src/tools/recommend.ts lines 122-150 - [x] Route to existing tool handlers - Evidence: Dispatches to all 4 handlers correctly - [x] Validate basic parameter passing - Evidence: Parameters pass through routing correctly - [x] Test each stage routing correctly - Evidence: Integration test validates all stages - [x] Validate parameter passing between stages - Evidence: solutionId and answers pass correctly - [x] Test complete deployment workflows - Evidence: Full workflow from clarification to deployment - [x] Ensure session continuity - Evidence: Session data maintained across stage transitions **Completed PRD Items** (Definition of Done): - [x] `recommend` tool extended with stage-based routing - [x] All existing workflows function identically - [x] Tests passing (integration tests) - [x] Integration tests validate all stages including default behavior **Implementation Highlights**: - **Stage routing dispatcher**: Added at entry point of recommend handler to route based on `stage` parameter - **Test data configuration**: Solved test failure by adding `QDRANT_CAPABILITIES_COLLECTION=capabilities-policies` env var - **Agent instruction updates**: Updated `nextAction` responses to use unified stage-based format across all tools - **Colon notation**: Successfully implemented `answerQuestion:required` pattern to combine routing with sub-parameters **Technical Discoveries**: - Test Qdrant database uses `capabilities-policies` collection for pre-populated data, not default `capabilities` collection - Environment variable approach allows flexibility for test vs production collection names - Stage routing cleanly separates concerns while maintaining backward-compatible interfaces --- ### 2025-10-02 (Late Evening): Documentation Complete - PRD 114 DONE ✅ **Duration**: ~1 hour **Commits**: Pending (documentation updates) **Completed PRD Items** (Milestone 5 & Definition of Done): - [x] Update shared prompts - Evidence: deploy.md already correct, no changes needed - [x] Update MCP documentation - Evidence: mcp-recommendation-guide.md updated with stage-based routing - [x] Update user guides - Evidence: quick-start.md updated with unified tool reference - [x] Documentation updated (Definition of Done) - Evidence: All user-facing docs reflect unified tool design **Documentation Updates**: - **mcp-recommendation-guide.md**: Updated all tool references to use stage-based routing pattern - Changed all `chooseSolution` → `recommend with stage: 'chooseSolution'` - Changed all `answerQuestion` → `recommend with stage: 'answerQuestion:required/basic/advanced/open'` - Changed all `generateManifests` → `recommend with stage: 'generateManifests'` - Changed all `deployManifests` → `recommend with stage: 'deployManifests'` - Updated "What happened behind the scenes" explanations throughout both examples - **quick-start.md**: Updated deployment example to show unified tool with stage routing - **shared-prompts/deploy.md**: Verified already correct (calls `recommend` tool without old tool references) **Key Insight**: Stage parameter is internal implementation detail - users don't need to know about stages. They interact conversationally while AI agent handles stage routing automatically. **PRD 114 Status**: ✅ **COMPLETE** - All milestones done, all Definition of Done criteria met --- ### 2025-10-02 (Evening): MCP Registration Update Complete **Duration**: ~1 hour **Commits**: 1 commit pending (MCP registration consolidation) **Completed PRD Items** (Milestone 2 & Definition of Done): - [x] Update `recommend` tool MCP registration - Evidence: src/interfaces/mcp.ts updated - [x] Remove 4 separate tool registrations - Evidence: chooseSolution, answerQuestion, generateManifests, deployManifests removed from mcp.ts - [x] Update `recommend` registration with unified schema - Evidence: Schema already included all parameters, just registration updated - [x] Test MCP tool discovery shows single recommend tool - Evidence: Manual verification shows "totalTools: 5" (not 9) - [x] MCP registration updated (Definition of Done) - Evidence: All 4 separate tools removed successfully **Implementation Highlights**: - **Clean consolidation**: Removed imports and registrations for 4 separate tools - **Unified interface**: Single `recommend` tool now handles all 5 workflow stages - **No breaking changes**: All handler functions remain unchanged, only MCP registration affected - **Build validation**: TypeScript compilation successful with no errors - **Manual verification**: Server logs confirm 5 tools registered (recommend, version, testDocs, manageOrgData, remediate) **Technical Details**: - Removed lines 25-48 in mcp.ts (unused imports for 4 separate tools) - Removed lines 192-278 in mcp.ts (4 tool registration blocks) - Updated logging to show 5 tools instead of 9 - Maintained all handler imports in recommend.ts for internal routing **Next Session Priorities**: 1. **Milestone 5**: Update shared prompts and documentation for stage-based approach 2. **Complete PRD**: Only documentation remains for full completion --- *This PRD represents a consolidation effort to simplify tool orchestration while maintaining identical functionality and user experience.*