@vfarcic/dot-ai 0.4.9 → 0.5.1

package/docs/NEXT_STEPS.md

@@ -0,0 +1,97 @@
+# Next Development Steps
+
+## Immediate Priority: Detailed API Specifications
+
+**Current Status**: Architecture and workflow design complete  
+**Next Task**: Define detailed JSON schemas and examples for all MCP functions
+
+### 1. MCP Function Specifications
+
+Create detailed specs for each function in a new `API_SPECS.md` file:
+
+#### `create_application`
+- **Input schema**: `{}` (no parameters)
+- **Output schema**: Discovery results + initial workflow guidance
+- **Error handling**: Cluster access failures, discovery errors
+- **State management**: How to track session state
+
+#### `continue_workflow` 
+- **Input schema**: User choice + context from previous steps
+- **Output schema**: Next question + workflow guidance
+- **Error handling**: Invalid choices, context missing
+- **State management**: Progressive workflow state
+
+#### `deploy_application`
+- **Input schema**: Complete configuration object
+- **Output schema**: Deployment status + monitoring guidance  
+- **Error handling**: Manifest validation, deployment failures
+- **State management**: Deployment tracking
+
+#### `get_deployment_status`
+- **Input schema**: Deployment identifier
+- **Output schema**: Status + resource details + lessons learned
+- **Error handling**: Deployment not found, cluster access issues
+- **State management**: Status polling patterns
+
+### 2. Supporting Schemas
+
+Define schemas for:
+- **Discovery Results**: CRDs, capabilities, cluster info
+- **Workflow Context**: Session state, user choices, progress
+- **Memory Lessons**: Success patterns, failure modes, troubleshooting
+- **Governance Policies**: Plain English rule interpretation
+- **Error Responses**: Consistent error structure across all functions
+
+### 3. Implementation Patterns
+
+Document:
+- **Claude Code SDK Integration**: How to structure the agent core
+- **Kubernetes API Patterns**: Standard kubectl operations and error handling
+- **Memory System**: JSON file structure and retrieval patterns
+- **Policy Interpretation**: How to parse plain English governance rules
+
+## File Structure to Create
+
+```
+mcp-app-management/
+├── docs/
+│   ├── API_SPECS.md         # ← CREATE THIS (detailed JSON schemas)
+│   ├── IMPLEMENTATION.md    # ← CREATE THIS (Claude Code SDK integration)
+│   ├── MEMORY_SYSTEM.md     # ← CREATE THIS (lesson storage design)
+│   └── TESTING_STRATEGY.md  # ← CREATE THIS (how to test the system)
+├── examples/
+│   ├── governance/          # ← CREATE THIS (example policy files)
+│   └── workflows/           # ← CREATE THIS (example interaction flows)
+└── schemas/
+    ├── mcp-functions.json   # ← CREATE THIS (JSON Schema definitions)
+    └── memory-lessons.json  # ← CREATE THIS (Memory structure schema)
+```
+
+## Success Criteria
+
+After completing API specifications, you should have:
+
+✅ **Complete JSON schemas** for all 4 MCP functions  
+✅ **Error handling patterns** documented  
+✅ **State management** approach defined  
+✅ **Memory system** structure specified  
+✅ **Governance integration** details  
+✅ **Implementation roadmap** for Claude Code SDK  
+
+## Ready to Start?
+
+1. Read `design.md` for complete architecture understanding
+2. Review `CONTEXT.md` for key decisions
+3. Start with `API_SPECS.md` - define the JSON schemas
+4. Use the examples in `design.md` as starting points
+5. Focus on making the schemas precise and implementable
+
+## Key Principles to Remember
+
+- **Discovery-driven**: Everything adapts to what's found in the cluster
+- **Resource-agnostic**: No hardcoded platform assumptions
+- **Plain English governance**: Policies in natural language
+- **Memory-enhanced**: Learn from every deployment
+- **Dual-mode**: Same intelligence, different interfaces
+
+The foundation is solid - now we need the detailed specifications to make it implementable! 🚀 

package/docs/STAGE_BASED_API.md

@@ -0,0 +1,97 @@
+# Stage-Based Question Flow API Design
+
+## Overview
+Replace the current `done` parameter and multi-group responses with explicit stage-based workflow validation.
+
+## API Contract
+
+### Request Format
+```typescript
+{
+  "solutionId": "sol_2025-07-02T134102_b665a82ca41d",
+  "stage": "required" | "basic" | "advanced" | "open",
+  "answers": {
+    "questionId": "value",
+    // ... more answers for this stage only
+  }
+}
+```
+
+### Response Format
+```typescript
+{
+  "status": "stage_questions" | "ready_for_manifest_generation" | "stage_error",
+  "solutionId": "sol_xxx",
+  "currentStage": "required" | "basic" | "advanced" | "open",
+  "questions": [...], // Only questions for current stage
+  "nextStage": "basic" | "advanced" | "open" | null,
+  "message": "Stage-specific message",
+  "timestamp": "..."
+}
+```
+
+## Stage Progression Rules
+
+### Valid Transitions
+- `required` → `basic`, `open`
+- `basic` → `advanced`, `open`  
+- `advanced` → `open`
+- `open` → (triggers manifest generation)
+
+### Stage Skip Logic
+- **Required**: Cannot skip (must have at least one answer)
+- **Basic**: Can skip (send `{"stage": "basic", "answers": {}}`)
+- **Advanced**: Can skip (send `{"stage": "advanced", "answers": {}}`)
+- **Open**: Complete with "N/A" (send `{"stage": "open", "answers": {"open": "N/A"}}`)
+
+### Completion Logic
+- Completing the `open` stage triggers manifest generation
+- No more `done` parameter or separate `complete` stage needed
+
+## Error Handling
+
+### Stage Mismatch
+```typescript
+{
+  "status": "stage_error",
+  "error": "stage_mismatch",
+  "expected": "basic",
+  "received": "advanced", 
+  "message": "You're in 'basic' stage but provided 'advanced'. Complete basic questions first or skip them explicitly."
+}
+```
+
+### Invalid Transition
+```typescript
+{
+  "status": "stage_error", 
+  "error": "invalid_transition",
+  "from": "required",
+  "to": "advanced",
+  "message": "Cannot jump from 'required' to 'advanced'. Must complete 'basic' stage first or skip to 'open'."
+}
+```
+
+## Implementation Benefits
+
+1. **Code-Only Validation**: No AI needed for workflow logic
+2. **Explicit Intent**: Clear distinction between skip vs incomplete
+3. **Single Question Group**: Always return one stage at a time
+4. **Predictable Flow**: State machine with clear transitions
+5. **Better Error Messages**: Specific stage-related feedback
+
+## Breaking Changes
+
+- Remove `done` parameter from answerQuestion
+- Add required `stage` parameter (enum: required, basic, advanced, open)
+- Remove `complete` stage - completion handled by `open` stage
+- Single-group question responses only
+- New error response formats
+
+## Migration Path
+
+1. Update answerQuestion tool input schema
+2. Implement stage validation logic
+3. Replace multi-group responses with single-stage
+4. Update all tests
+5. Test end-to-end workflow