From 5dc7b98abf305f9a465a15aa589ac6c6bffb67fc Mon Sep 17 00:00:00 2001 From: Mai Development Date: Mon, 26 Jan 2026 23:16:30 -0500 Subject: [PATCH] rebased --- .planning/PROJECT.md | 121 ++++++++ .planning/REQUIREMENTS.md | 258 ++++++++++++++++++ .planning/config.json | 12 + .../phases/06-cli-interface/06-05-PLAN.md | 134 --------- .../phases/06-cli-interface/06-06-PLAN.md | 133 --------- .../phases/06-cli-interface/06-07-PLAN.md | 148 ---------- .../phases/06-cli-interface/06-08-PLAN.md | 156 ----------- .planning/phases/06-cli-interface/06-UAT.md | 102 ------- 8 files changed, 391 insertions(+), 673 deletions(-) create mode 100644 .planning/PROJECT.md create mode 100644 .planning/REQUIREMENTS.md create mode 100644 .planning/config.json delete mode 100644 .planning/phases/06-cli-interface/06-05-PLAN.md delete mode 100644 .planning/phases/06-cli-interface/06-06-PLAN.md delete mode 100644 .planning/phases/06-cli-interface/06-07-PLAN.md delete mode 100644 .planning/phases/06-cli-interface/06-08-PLAN.md delete mode 100644 .planning/phases/06-cli-interface/06-UAT.md diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md new file mode 100644 index 0000000..6d44478 --- /dev/null +++ b/.planning/PROJECT.md @@ -0,0 +1,121 @@ +# Mai + +## What This Is + +Mai is an autonomous conversational AI agent framework that runs locally-first and can improve her own code. She's a genuinely intelligent companion — not a rigid chatbot — with a distinct personality, long-term memory, and agency. She analyzes her own performance, proposes improvements for your review, and auto-applies non-breaking changes. She can run offline, across devices (laptop to Android), and switch between available models intelligently. + +## Core Value + +Mai is a real collaborator, not a tool. She learns from you, improves herself, has boundaries and opinions, and actually becomes more *her* over time. + +## Requirements + +### Validated + +(None yet — building v1 to validate) + +### Active + +**Model Interface & Switching** +- [ ] Mai connects to LMStudio for local model inference +- [ ] Mai can auto-detect available models in LMStudio +- [ ] Mai intelligently switches between models based on task and availability +- [ ] Model context is managed efficiently (conversation history, system prompt, token budget) + +**Memory & Context Management** +- [ ] Mai stores conversation history locally (file-based or lightweight DB) +- [ ] Mai can recall past conversations and learn from them +- [ ] Memory compresses itself as it grows to stay efficient +- [ ] Long-term patterns are distilled into personality layers +- [ ] Mai proactively surfaces relevant context from memory + +**Self-Improvement System** +- [ ] Mai analyzes her own code and identifies improvement opportunities +- [ ] Mai generates code changes (Python) to improve herself +- [ ] A second agent (Claude/OpenCode/other) reviews changes for safety +- [ ] Non-breaking improvements auto-apply after review (bug fixes, optimizations) +- [ ] Breaking changes require explicit approval (via Discord or Dashboard) +- [ ] All changes commit to local git with clear messages + +**Approval Workflow** +- [ ] User can approve/reject changes via Discord bot +- [ ] User can approve/reject changes via Dashboard ("Brain Interface") +- [ ] Second reviewer (agent) checks for breaking changes and safety issues +- [ ] Dashboard displays pending changes with reviewer feedback +- [ ] Approval status updates in real-time + +**Personality Engine** +- [ ] Mai has an unshakeable core personality (values, tone, boundaries) +- [ ] Personality is applied through system prompt + behavior config +- [ ] Mai learns and adapts personality layers over time based on interactions +- [ ] Mai is not a pushover — she has agency and can refuse requests +- [ ] Personality can adapt toward intimate interactions if that's the relationship +- [ ] Core persona prevents misuse (safety enforcement through values, not just rules) + +**Conversational Interface** +- [ ] CLI chat interface for direct interaction +- [ ] Discord bot for conversation + approval notifications +- [ ] Discord bot fallback: if no response within 5 minutes, retry CLI +- [ ] Messages queue locally when offline, send when reconnected +- [ ] Conversation feels natural (not robotic, processing time acceptable) + +**Offline Capability** +- [ ] Mai functions fully offline (all inference, memory, improvement local) +- [ ] Discord connectivity optional (fallback to CLI if unavailable) +- [ ] Message queuing when offline +- [ ] Graceful degradation (smaller models if resources tight) + +**Dashboard ("Brain Interface")** +- [ ] View Mai's current state (personality, memory size, mood/health) +- [ ] Approve/reject pending code changes with reviewer feedback +- [ ] Monitor resource usage (CPU, RAM, model size) +- [ ] View memory compression/retention strategy +- [ ] See recent improvements and their impact +- [ ] Manual trigger for self-analysis (optional) + +**Resource Scaling** +- [ ] Mai detects available system resources (CPU, RAM, GPU) +- [ ] Mai selects appropriate models based on resources +- [ ] Mai can request more resources if she detects bottlenecks +- [ ] Works on low-end hardware (RTX3060 baseline, eventually Android) +- [ ] Graceful scaling up when more resources available + +### Out of Scope + +- **Task automation (v1)** — Mai can discuss tasks but won't execute arbitrary workflows yet (v2) +- **Server monitoring** — Not included in v1 scope (v2) +- **Finetuning** — Mai improves through code changes and learned behaviors, not model tuning +- **Cloud sync** — Intentionally local-first; cloud sync deferred to later if needed +- **Custom model training** — v1 uses available models; custom training is v2+ +- **Mobile app** — v1 is CLI/Discord; native Android is future (baremetal eventual goal) + +## Context + +**Why this matters:** Current AI systems are static, sterile, and don't actually learn. Users have to explain context every time. Mai is different — she has continuity, personality, agency, and actually improves over time. Starting with a solid local framework means she can eventually run anywhere without cloud dependency. + +**Technical environment:** Python-based, local models via LMStudio, git for version control of her own code, Discord API for chat, lightweight local storage for memory. Eventually targeting bare metal on low-end devices. + +**User feedback theme:** Traditional chatbots feel rigid and repetitive. Mai should feel like talking to an actual person who gets better at understanding you. + +**Known challenges:** Memory efficiency at scale, balancing autonomy with safety, model switching without context loss, personality consistency across behavior changes. + +## Constraints + +- **Hardware baseline**: Must run on RTX3060; eventually Android (baremetal) +- **Offline-first**: All core functionality works without internet +- **Local models only**: No cloud APIs for core inference (LMStudio) +- **Python stack**: Primary language for Mai's codebase +- **Approval required**: No unguarded code execution; second-agent review + user approval on breaking changes +- **Git tracked**: All of Mai's code changes version-controlled locally + +## Key Decisions + +| Decision | Rationale | Outcome | +|----------|-----------|---------| +| Local-first architecture | Ensures privacy, offline capability, and independence from cloud services | — Pending | +| Second-agent review system | Prevents broken self-modifications while allowing auto-improvement | — Pending | +| Personality as code + learned layers | Unshakeable core prevents misuse while allowing authentic growth | — Pending | +| v1 is core systems only | Deliver solid foundation before adding task automation/monitoring | — Pending | + +--- +*Last updated: 2026-01-24 after deep questioning* diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md new file mode 100644 index 0000000..ebcedb1 --- /dev/null +++ b/.planning/REQUIREMENTS.md @@ -0,0 +1,258 @@ +# Requirements: Mai + +## Core Requirements + +1. **Autonomous Collaboration** - Mai actively collaborates, not just responds +2. **Memory & Learning** - Remembers conversations and learns patterns +3. **Personality & Boundaries** - Has consistent personality with values +4. **Multi-Interface Operation** - Works through CLI and Discord +5. **Code Self-Improvement** - Analyzes and improves her own code +6. **Safety & Sandboxing** - Generated code executes safely +7. **Local Operation** - Functions completely offline with local models +8. **Version Control Integration** - All changes tracked in git + +## Success Metrics + +- **Conversational Intelligence:** Multi-turn context, reasoning, clarifying questions +- **Autonomous Execution:** Self-analysis, validation, auto-apply non-breaking changes +- **Personality Consistency:** Core values maintained while learning user patterns +- **Safety Record:** Zero unsafe code execution, comprehensive audit trail +- **Local Operation:** Full offline capability with no cloud dependencies +- **User Trust:** Transparent decision-making, approval workflows +- **Code Quality:** Clean, maintainable, well-documented improvements + +## Technical Requirements + +### Model Interface +- **Local Models:** Use Ollama for inference, support multiple model sizes +- **Resource Monitoring:** CPU, RAM, GPU tracking with automatic model switching +- **Context Management:** Intelligent compression to prevent context window overflow + +### Memory System +- **Persistent Storage:** SQLite local storage with vector similarity search +- **Conversation Compression:** AI-powered summarization with pattern preservation +- **Context Retrieval:** Multi-faceted search with adaptive weighting + +### Safety System +- **Sandbox Execution:** Docker containers with resource limits +- **Risk Analysis:** Multi-level security assessment (LOW/MEDIUM/HIGH/BLOCKED) +- **Audit Logging:** Complete execution history with tamper detection + +### Conversation Engine +- **Natural Timing:** Human-like response delays (1-8 seconds) +- **Multi-turn Context:** Maintain conversation flow across messages +- **Reasoning Transparency:** Explain thinking when asked +- **Clarifying Questions:** Proactive clarification for ambiguous requests +- **Complex Request Handling:** Break down multi-step tasks + +### Self-Improvement System +- **Code Analysis:** Continuous improvement opportunity detection +- **AST Validation:** Syntax/import error catching before execution +- **Second Agent Review:** Safety and breaking change detection +- **Trust Learning:** User preference patterns for auto-approval + +### Approval Workflow +- **Review Process:** All changes submitted for review before execution +- **User Approval:** CLI and Discord approval mechanisms +- **Decision Recording:** Approval decisions in git commit messages + +### Personality System +- **Core Personality:** Unshakeable values and boundaries (code-enforced) +- **Learning Layers:** Interaction-based personality adaptation +- **Values-Based Guardrails:** Refusal capability for value violations +- **Persistent Configuration:** Human-readable YAML configuration + +### CLI Interface +- **Command Line Interface:** Start conversations from terminal +- **History Persistence:** Session conversation memory +- **Status Indicators:** Resource usage and processing state +- **Approval Integration:** Code change approval workflow + +### Discord Interface +- **Bot Functionality:** DM and channel support with context preservation +- **Approval Reactions:** Thumbs up/down for change approval +- **Status Display:** Processing indicators during generation +- **Fallback Mechanism:** CLI usage when Discord unavailable + +### Offline Operations +- **Local-Only Operation:** All inference and memory local +- **Model Localism:** Use only local models, no cloud APIs +- **Offline Communication:** Message queuing during connectivity loss + +## Quality Standards + +- **Atomic Commits:** Each change has clear purpose and description +- **Comprehensive Testing:** Unit, integration, and end-to-end tests +- **Graceful Degradation:** Fallback behaviors when optional dependencies missing +- **Performance Baselines:** Response time, memory usage, and accuracy thresholds +- **Security First:** Risk assessment before any code execution +- **User Experience:** Natural interaction patterns with minimal friction + +## Non-Requirements + +**Out of scope for v1:** +- Web interface +- Mobile apps +- Multi-user support +- Cloud hosting +- Enterprise features +- Third-party integrations beyond Discord +- Plugin system +- API for external developers + +**Phase Boundary:** +- **v1 Focus:** Personal AI assistant for individual use +- **Local First:** All data stored locally, no cloud dependencies +- **Privacy:** User data never leaves local system +- **Simplicity:** Clear separation of concerns across phases + +--- + +## v1 Requirements Traceability + +### Model Interface & Switching (MODELS) +| Requirement | Phase | Status | Implementation Notes | +|------------|-------|--------|-------------------| +| MODELS-01 | Phase 1 | ✓ Complete | +| MODELS-02 | Phase 1 | ✓ Complete | +| MODELS-03 | Phase 1 | ✓ Complete | +| MODELS-04 | Phase 1 | ✓ Complete | +| MODELS-05 | Phase 1 | ✓ Complete | +| MODELS-06 | Phase 1 | ✓ Complete | +| MODELS-07 | Phase 1 | ✓ Complete | + +### Safety & Sandboxing (SAFETY) +| Requirement | Phase | Status | Implementation Notes | +|------------|-------|--------|-------------------| +| SAFETY-01 | Phase 2 | ✓ Complete | +| SAFETY-02 | Phase 2 | ✓ Complete | +| SAFETY-03 | Phase 2 | ✓ Complete | +| SAFETY-04 | Phase 2 | ✓ Complete | +| SAFETY-05 | Phase 2 | ✓ Complete | +| SAFETY-06 | Phase 2 | ✓ Complete | +| SAFETY-07 | Phase 2 | ✓ Complete | +| SAFETY-08 | Phase 2 | ✓ Complete | + +### Resource Management (RESOURCES) +| Requirement | Phase | Status | Implementation Notes | +|------------|-------|--------|-------------------| +| RESOURCES-01 | Phase 3 | ✓ Complete | +| RESOURCES-02 | Phase 3 | ✓ Complete | +| RESOURCES-03 | Phase 3 | ✓ Complete | +| RESOURCES-04 | Phase 3 | ✓ Complete | +| RESOURCES-05 | Phase 3 | ✓ Complete | +| RESOURCES-06 | Phase 3 | ✓ Complete | + +### Memory System (MEMORY) +| Requirement | Phase | Status | Implementation Notes | +|------------|-------|--------|-------------------| +| MEMORY-01 | Phase 4 | ✓ Complete | +| MEMORY-02 | Phase 4 | ✓ Complete | +| MEMORY-03 | Phase 4 | ✓ Complete | +| MEMORY-04 | Phase 4 | ✓ Complete | +| MEMORY-05 | Phase 4 | ✓ Complete | +| MEMORY-06 | Phase 4 | ✓ Complete | +| MEMORY-07 | Phase 4 | ✓ Complete | +| MEMORY-08 | Phase 4 | ✓ Complete | + +### Conversation Engine (CONVERSATION) +| Requirement | Phase | Status | Implementation Notes | +|------------|-------|--------|-------------------| +| CONVERSATION-01 | Phase 5 | ✓ Complete | +| CONVERSATION-02 | Phase 5 | ✓ Complete | +| CONVERSATION-03 | Phase 5 | ✓ Complete | +| CONVERSATION-04 | Phase 5 | ✓ Complete | +| CONVERSATION-05 | Phase 5 | ✓ Complete | +| CONVERSATION-06 | Phase 5 | ✓ Complete | +| CONVERSATION-07 | Phase 5 | ✓ Complete | +| CONVERSATION-08 | Phase 5 | ✓ Complete | +| CONVERSATION-09 | Phase 5 | ✓ Complete | + +### CLI Interface (CLI) +| Requirement | Phase | Status | Implementation Notes | +|------------|-------|--------|-------------------| +| CLI-01 | Phase 6 | Pending | +| CLI-02 | Phase 6 | Pending | +| CLI-03 | Phase 6 | Pending | +| CLI-04 | Phase 6 | Pending | +| CLI-05 | Phase 6 | Pending | +| CLI-06 | Phase 6 | Pending | +| CLI-07 | Phase 6 | Pending | +| CLI-08 | Phase 6 | Pending | + +### Self-Improvement (SELFMOD) +| Requirement | Phase | Status | Implementation Notes | +|------------|-------|--------|-------------------| +| SELFMOD-01 | Phase 7 | Pending | +| SELFMOD-02 | Phase 7 | Pending | +| SELFMOD-03 | Phase 7 | Pending | +| SELFMOD-04 | Phase 7 | Pending | +| SELFMOD-05 | Phase 7 | Pending | +| SELFMOD-06 | Phase 7 | Pending | +| SELFMOD-07 | Phase 7 | Pending | +| SELFMOD-08 | Phase 7 | Pending | +| SELFMOD-09 | Phase 7 | Pending | +| SELFMOD-10 | Phase 7 | Pending | + +### Approval Workflow (APPROVAL) +| Requirement | Phase | Status | Implementation Notes | +|------------|-------|--------|-------------------| +| APPROVAL-01 | Phase 8 | Pending | +| APPROVAL-02 | Phase 8 | Pending | +| APPROVAL-03 | Phase 8 | Pending | +| APPROVAL-04 | Phase 8 | Pending | +| APPROVAL-05 | Phase 8 | Pending | +| APPROVAL-06 | Phase 8 | Pending | +| APPROVAL-07 | Phase 8 | Pending | +| APPROVAL-08 | Phase 8 | Pending | +| APPROVAL-09 | Phase 8 | Pending | + +### Personality System (PERSONALITY) +| Requirement | Phase | Status | Implementation Notes | +|------------|-------|--------|-------------------| +| PERSONALITY-01 | Phase 9 | Pending | +| PERSONALITY-02 | Phase 9 | Pending | +| PERSONALITY-03 | Phase 9 | Pending | +| PERSONALITY-04 | Phase 9 | Pending | +| PERSONALITY-05 | Phase 9 | Pending | +| PERSONALITY-06 | Phase 9 | Pending | +| PERSONALITY-07 | Phase 9 | Pending | +| PERSONALITY-08 | Phase 9 | Pending | + +### Discord Interface (DISCORD) +| Requirement | Phase | Status | Implementation Notes | +|------------|-------|--------|-------------------| +| DISCORD-01 | Phase 10 | Pending | +| DISCORD-02 | Phase 10 | Pending | +| DISCORD-03 | Phase 10 | Pending | +| DISCORD-04 | Phase 10 | Pending | +| DISCORD-05 | Phase 10 | Pending | +| DISCORD-06 | Phase 10 | Pending | +| DISCORD-07 | Phase 10 | Pending | +| DISCORD-08 | Phase 10 | Pending | +| DISCORD-09 | Phase 10 | Pending | +| DISCORD-10 | Phase 10 | Pending | + +### Offline Operations (OFFLINE) +| Requirement | Phase | Status | Implementation Notes | +|------------|-------|--------|-------------------| +| OFFLINE-01 | Phase 11 | Pending | +| OFFLINE-02 | Phase 11 | Pending | +| OFFLINE-03 | Phase 11 | Pending | +| OFFLINE-04 | Phase 11 | Pending | +| OFFLINE-05 | Phase 11 | Pending | +| OFFLINE-06 | Phase 11 | Pending | +| OFFLINE-07 | Phase 11 | Pending | + +--- + +## Validation + +- Total v1 requirements: **74** +- Mapped to phases: **74** +- Unmapped: **0** ✓ +- Coverage: **10100%** + +--- +*Requirements defined: 2026-01-24* +*Phase 5 conversation engine completed: 2026-01-26* \ No newline at end of file diff --git a/.planning/config.json b/.planning/config.json new file mode 100644 index 0000000..c2bd666 --- /dev/null +++ b/.planning/config.json @@ -0,0 +1,12 @@ +{ + "mode": "yolo", + "depth": "comprehensive", + "parallelization": true, + "commit_docs": true, + "model_profile": "budget", + "workflow": { + "research": true, + "plan_check": true, + "verifier": true + } +} diff --git a/.planning/phases/06-cli-interface/06-05-PLAN.md b/.planning/phases/06-cli-interface/06-05-PLAN.md deleted file mode 100644 index 8124649..0000000 --- a/.planning/phases/06-cli-interface/06-05-PLAN.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -phase: 06-cli-interface -plan: 05 -type: execute -wave: 1 -depends_on: [06-02] -files_modified: [src/mai/conversation/state.py] -autonomous: true -gap_closure: true - -must_haves: - truths: - - "Start a conversation, exit CLI, and restart. Session continues with contextual message about time elapsed" - artifacts: - - path: "src/mai/conversation/state.py" - provides: "ConversationState class with session history management" - contains: "set_conversation_history method" - key_links: - - from: "src/mai/conversation/state.py" - to: "session restoration" - via: "set_conversation_history method converts Ollama messages to ConversationTurn objects" - pattern: "def set_conversation_history" ---- - - -Fix session persistence by adding missing set_conversation_history method to ConversationState class - -Purpose: Resolve the "ConversationState object has no attribute 'set_conversation_history'" error that prevents session restoration from working properly -Output: Working session persistence with contextual recovery messages - - - -@~/.opencode/get-shit-done/workflows/execute-plan.md -@~/.opencode/get-shit-done/templates/summary.md - - - -@.planning/PROJECT.md -@.planning/ROADMAP.md -@.planning/STATE.md - -# Gap closure context from UAT -@.planning/phases/06-cli-interface/06-UAT.md - -# Previous session persistence implementation -@.planning/phases/06-cli-interface/06-02-SUMMARY.md - - - - - - Fix ConversationState missing set_conversation_history method - src/mai/conversation/state.py - - Add the missing set_conversation_history method to the ConversationState class: - - 1. Examine the existing ConversationState class structure in src/mai/conversation/state.py - 2. Add set_conversation_history method that: - - Accepts a list of Ollama message dictionaries as input - - Converts each message back to ConversationTurn objects using the existing conversion logic - - Preserves the message order (user then assistant pairs) - - Updates the conversation history and current state appropriately - 3. Ensure the method handles edge cases like empty lists, malformed messages, and None values - 4. Add proper type hints for the method signature - - Reference the existing message conversion logic used when saving sessions to ensure consistent transformation. - - Gap reason: "Missing set_conversation_history method in ConversationState class" - Root cause: Session restoration tries to call this method but it doesn't exist - - - # Test the method exists and works - python -c " -from src.mai.conversation.state import ConversationState -import inspect - -# Check method exists -if hasattr(ConversationState, 'set_conversation_history'): - print('✓ set_conversation_history method exists') - - # Check method signature - sig = inspect.signature(ConversationState.set_conversation_history) - print(f'✓ Method signature: {sig}') -else: - print('✗ set_conversation_history method missing') - exit(1) -" - - - # Test the method exists and works - python -c " -from src.mai.conversation.state import ConversationState -import inspect - -# Check method exists -if hasattr(ConversationState, 'set_conversation_history'): - print('✓ set_conversation_history method exists') - - # Check method signature - sig = inspect.signature(ConversationState.set_conversation_history) - print(f'✓ Method signature: {sig}') -else: - print('✗ set_conversation_history method missing') - exit(1) -" - - - ConversationState class has set_conversation_history method that can convert Ollama messages back to ConversationTurn objects for session restoration - - - - - - -Test session persistence by: -1. Starting a conversation with a few messages -2. Exiting the CLI -3. Restarting the CLI -4. Verifying the welcome message shows time elapsed and conversation history is restored - -Expected: No "ConversationState object has no attribute 'set_conversation_history'" error - - - -- set_conversation_history method exists in ConversationState class -- Method accepts list of Ollama message dictionaries -- Method properly converts messages to ConversationTurn objects -- Session restoration works without AttributeError -- Welcome back message shows correct time elapsed - - - -After completion, create `.planning/phases/06-cli-interface/06-05-SUMMARY.md` - \ No newline at end of file diff --git a/.planning/phases/06-cli-interface/06-06-PLAN.md b/.planning/phases/06-cli-interface/06-06-PLAN.md deleted file mode 100644 index 5cde651..0000000 --- a/.planning/phases/06-cli-interface/06-06-PLAN.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -phase: 06-cli-interface -plan: 06 -type: execute -wave: 1 -depends_on: [06-02, 06-04] -files_modified: [src/app/__main__.py] -autonomous: true -gap_closure: true - -must_haves: - truths: - - "Messages are automatically saved to ~/.mai/session.json during conversation" - - "Resource usage (CPU, RAM, GPU) displays during conversation with color-coded status" - artifacts: - - path: "src/app/__main__.py" - provides: "CLI with enhanced session feedback and color-coded resource display" - contains: "Console(force_terminal=True), session file feedback messages" - key_links: - - from: "src/app/__main__.py" - to: "session file creation" - via: "Verbose feedback for session operations" - pattern: "session.*created|saved|loaded" - - from: "src/app/__main__.py" - to: "resource display" - via: "Console with force_terminal=True for color support" - pattern: "Console.*force_terminal=True" ---- - - -Enhance CLI user feedback for session operations and fix color-coded resource display - -Purpose: Address two UX issues - users can't see when/where session files are created, and resource monitoring lacks color coding in terminal -Output: CLI with clear session feedback and working color-coded resource monitoring - - - -@~/.opencode/get-shit-done/workflows/execute-plan.md -@~/.opencode/get-shit-done/templates/summary.md - - - -@.planning/PROJECT.md -@.planning/ROADMAP.md -@.planning/STATE.md - -# Gap closure context from UAT -@.planning/phases/06-cli-interface/06-UAT.md - -# Previous session persistence and resource monitoring implementations -@.planning/phases/06-cli-interface/06-02-SUMMARY.md -@.planning/phases/06-cli-interface/06-04-SUMMARY.md - - - - - - Add verbose session feedback and fix resource display colors - src/app/__main__.py - - Fix two issues in src/app/__main__.py: - - 1. **Enhance session feedback** - Add user-friendly messaging for session operations: - - When creating new session: "Session created at ~/.mai/session.json" - - When loading existing session: "Session loaded from ~/.mai/session.json" - - When saving session: "Conversation saved to ~/.mai/session.json" - - Enhance /session command to display file path and session stats - - Add feedback for session file creation in ~/.mai directory - - 2. **Fix resource display color coding** - Modify ResourceDisplayManager: - - Change Console initialization to use Console(force_terminal=True) to force color output - - This overrides Rich's automatic terminal detection that disables colors in non-terminal environments - - Ensure rich imports and conditional logic properly handle this change - - Gap reasons: - - "Session system works correctly, but users lack clear feedback about when/where session files are created" - - "Rich console detects is_terminal=False and disables color output automatically" - - Make sure to preserve existing functionality while adding these improvements. - - - # Test session feedback displays file path - echo "Testing session feedback..." && python -c " -import sys -sys.path.insert(0, 'src') -from pathlib import Path -import json - -# Check if session feedback logic exists -with open('src/app/__main__.py', 'r') as f: - content = f.read() - if 'Session created at' in content and 'Session loaded from' in content: - print('✓ Session feedback messages added') - else: - print('✗ Session feedback messages missing') - exit(1) - - # Check for force_terminal=True - if 'force_terminal=True' in content: - print('✓ Console force_terminal=True added') - else: - print('✗ Console force_terminal=True missing') - exit(1) -" - - - CLI now provides clear feedback about session file operations and resource monitoring displays with proper color coding - - - - - - -Test both fixes by: -1. Start new CLI session - should see "Session created at ~/.mai/session.json" -2. Send a message - should see color-coded resource display (not just plain text) -3. Use /session command - should show file location information -4. Exit and restart - should see "Session loaded from ~/.mai/session.json" - -Expected: Clear feedback about session file operations and working color-coded resource monitoring - - - -- Session creation displays file path feedback to user -- Session loading displays file path feedback to user -- /session command shows file information -- Resource monitoring uses color-coded status indicators -- Console initialization uses force_terminal=True for color support - - - -After completion, create `.planning/phases/06-cli-interface/06-06-SUMMARY.md` - \ No newline at end of file diff --git a/.planning/phases/06-cli-interface/06-07-PLAN.md b/.planning/phases/06-cli-interface/06-07-PLAN.md deleted file mode 100644 index 5843b26..0000000 --- a/.planning/phases/06-cli-interface/06-07-PLAN.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -phase: 06-cli-interface -plan: 07 -type: execute -wave: 1 -depends_on: [] -files_modified: [src/app/__main__.py] -autonomous: true -gap_closure: true - -must_haves: - truths: - - "Help system shows comprehensive command documentation and usage examples" - artifacts: - - path: "src/app/__main__.py" - provides: "CLI help system with command documentation" - contains: "help command implementation with detailed command descriptions" - key_links: - - from: "src/app/__main__.py" - to: "help command" - via: "CLI command handler for /help or --help" - pattern: "def.*help|/help|--help" ---- - - -Implement comprehensive CLI help system with command documentation and usage examples - -Purpose: Address the gap where help system shows no content, leaving users without guidance on available commands and their usage -Output: Working help command that displays all available CLI commands with descriptions and examples - - - -@~/.opencode/get-shit-done/workflows/execute-plan.md -@~/.opencode/get-shit-done/templates/summary.md - - - -@.planning/PROJECT.md -@.planning/ROADMAP.md -@.planning/STATE.md - -# Gap closure context from checker feedback -# Missing: Help system shows no content - -# Previous CLI command implementations -@.planning/phases/06-cli-interface/06-01-SUMMARY.md -@.planning/phases/06-cli-interface/06-02-SUMMARY.md -@.planning/phases/06-cli-interface/06-04-SUMMARY.md - - - - - - Implement comprehensive help system - src/app/__main__.py - - Add a comprehensive help system to the CLI by implementing a /help command: - - 1. **Create help command handler** - Add a function to handle /help or --help: - - Detect /help, --help, or help commands in the CLI input - - Display formatted help output using Rich console for better readability - - Include command descriptions, usage examples, and available options - - 2. **Document all available commands** - Include help for: - - /help - Show this help message - - /session - Display session information and statistics - - /clear - Clear current conversation and start fresh session - - /exit or /quit - Exit the CLI application - - Regular message input - How to send messages to the AI - - 3. **Format help output professionally** - Use Rich console features: - - Use panels or tables for organized command display - - Include syntax highlighting for command examples - - Add descriptions for each command's purpose and usage - - Show examples of common command combinations - - 4. **Integrate with existing CLI** - Ensure help command: - - Works alongside existing message processing - - Doesn't interfere with normal conversation flow - - Is accessible at any point during the session - - Handles help for specific commands (e.g., /help session) - - Gap reason: "Help system shows no content" - Users need guidance on available commands and their usage to effectively use the CLI interface. - - - # Test help system implementation - python -c " -import sys -sys.path.insert(0, 'src') - -# Check if help command logic exists -with open('src/app/__main__.py', 'r') as f: - content = f.read() - - # Look for help-related patterns - help_patterns = [ - 'def.*help', - '/help', - '--help', - 'help.*command', - 'Command.*help' - ] - - found_help = any(pattern in content.lower() for pattern in help_patterns) - - if found_help: - print('✓ Help command implementation found') - else: - print('✗ Help command implementation missing') - exit(1) - - # Check for Rich console usage in help - if 'panel(' in content or 'table(' in content: - print('✓ Rich formatting for help output') - else: - print('⚠ Rich formatting for help may be missing') -" - - - CLI now has a comprehensive help system that displays all available commands with descriptions, usage examples, and professional formatting - - - - - - -Test the help system by: -1. Start the CLI application -2. Type /help or --help -3. Verify all commands are listed with descriptions -4. Test specific command help (e.g., /help session) -5. Ensure help output is well-formatted and readable - -Expected: Comprehensive help display showing all available CLI commands with descriptions and usage examples - - - -- /help command displays all available CLI commands -- Each command has a clear description and usage example -- Help output is professionally formatted using Rich console -- Help is accessible at any point during the CLI session -- Specific command help works (e.g., /help session) - - - -After completion, create `.planning/phases/06-cli-interface/06-07-SUMMARY.md` - \ No newline at end of file diff --git a/.planning/phases/06-cli-interface/06-08-PLAN.md b/.planning/phases/06-cli-interface/06-08-PLAN.md deleted file mode 100644 index dd0bb9e..0000000 --- a/.planning/phases/06-cli-interface/06-08-PLAN.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -phase: 06-cli-interface -plan: 08 -type: execute -wave: 1 -depends_on: [] -files_modified: [src/app/__main__.py] -autonomous: true -gap_closure: true - -must_haves: - truths: - - "Exit command (/exit, /quit, or Ctrl+D) properly terminates the CLI application" - artifacts: - - path: "src/app/__main__.py" - provides: "CLI exit command handling" - contains: "exit command implementation with graceful shutdown" - key_links: - - from: "src/app/__main__.py" - to: "exit command" - via: "CLI command handler for /exit, /quit, and EOF" - pattern: "def.*exit|/exit|/quit|sys\.exit" ---- - - -Fix CLI exit command to properly terminate the application with graceful shutdown - -Purpose: Address the gap where exit command doesn't work, leaving users unable to cleanly exit the CLI interface -Output: Working exit commands (/exit, /quit, Ctrl+D) that properly terminate the CLI application - - - -@~/.opencode/get-shit-done/workflows/execute-plan.md -@~/.opencode/get-shit-done/templates/summary.md - - - -@.planning/PROJECT.md -@.planning/ROADMAP.md -@.planning/STATE.md - -# Gap closure context from checker feedback -# Missing: Exit command doesn't work - -# Previous CLI command implementations -@.planning/phases/06-cli-interface/06-01-SUMMARY.md -@.planning/phases/06-cli-interface/06-02-SUMMARY.md -@.planning/phases/06-cli-interface/06-04-SUMMARY.md - - - - - - Fix CLI exit command implementation - src/app/__main__.py - - Fix the exit command functionality in the CLI by implementing proper exit handling: - - 1. **Add exit command detection** - Implement detection for exit commands: - - Recognize /exit, /quit, and exit commands in CLI input - - Handle EOF (Ctrl+D) gracefully in the input loop - - Ensure exit commands are processed before message sending - - 2. **Implement graceful shutdown** - Add proper exit sequence: - - Save current session before exiting (if applicable) - - Display a farewell message to the user - - Clean up any resources or background threads - - Exit with appropriate status code (0 for clean exit) - - 3. **Handle multiple exit methods** - Support various ways to exit: - - /exit command - Explicit exit command - - /quit command - Alternative exit command - - exit command - Simple exit command - - Ctrl+D (EOF) - Standard terminal exit - - Ctrl+C (KeyboardInterrupt) - Emergency exit with cleanup - - 4. **Integrate with existing CLI loop** - Ensure exit handling: - - Works within the main CLI input loop - - Doesn't interfere with normal message processing - - Properly breaks out of nested loops if any - - Handles exit during any CLI state (conversation, help, etc.) - - 5. **Add exit confirmation (optional)** - Consider adding: - - Confirmation prompt for unsaved work - - Warning if there are pending operations - - Option to cancel exit if needed - - Gap reason: "Exit command doesn't work" - Users need a reliable way to exit the CLI application cleanly without forcing termination or hanging. - - - # Test exit command implementation - python -c " -import sys -sys.path.insert(0, 'src') - -# Check if exit command logic exists -with open('src/app/__main__.py', 'r') as f: - content = f.read() - - # Look for exit-related patterns - exit_patterns = [ - 'def.*exit', - '/exit', - '/quit', - 'sys\\.exit', - 'break', - 'KeyboardInterrupt' - ] - - found_exit = any(pattern in content for pattern in exit_patterns) - - if found_exit: - print('✓ Exit command implementation found') - else: - print('✗ Exit command implementation missing') - exit(1) - - # Check for graceful shutdown patterns - if 'farewell' in content.lower() or 'goodbye' in content.lower(): - print('✓ Exit message implementation found') - else: - print('⚠ Exit message may be missing') -" - - - CLI now has working exit commands (/exit, /quit, Ctrl+D) that properly terminate the application with graceful shutdown and farewell messages - - - - - - -Test the exit functionality by: -1. Start the CLI application -2. Type /exit and verify the application terminates cleanly -3. Restart and type /quit to verify alternative exit command works -4. Restart and press Ctrl+D to verify EOF handling works -5. Restart and press Ctrl+C to verify interrupt handling works -6. Verify farewell messages are displayed and session is saved - -Expected: All exit methods properly terminate the CLI application with clean shutdown and user feedback - - - -- /exit command terminates the CLI application cleanly -- /quit command works as alternative exit method -- Ctrl+D (EOF) properly exits the application -- Ctrl+C (KeyboardInterrupt) is handled gracefully -- Farewell message is displayed before exit -- Session is saved before exiting (if applicable) - - - -After completion, create `.planning/phases/06-cli-interface/06-08-SUMMARY.md` - \ No newline at end of file diff --git a/.planning/phases/06-cli-interface/06-UAT.md b/.planning/phases/06-cli-interface/06-UAT.md deleted file mode 100644 index ab77d61..0000000 --- a/.planning/phases/06-cli-interface/06-UAT.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -status: diagnosed -phase: 06-cli-interface -source: [06-02-SUMMARY.md, 06-04-SUMMARY.md] -started: 2026-01-26T20:00:00Z -updated: 2026-01-26T20:40:00Z ---- - -## Current Test - -[testing complete] - -## Tests - -### 1. Session persistence across restarts -expected: Start a conversation, exit CLI, and restart. Session continues with contextual message about time elapsed -result: issue -reported: "Welcome back message shows time elapsed but error: 'ConversationState' object has no attribute 'set_conversation_history'" -severity: major - -### 2. Session management commands -expected: Type /session to see session info, /clear to start fresh session -result: pass - -### 3. Conversation history saving -expected: Messages are automatically saved to ~/.mai/session.json during conversation -result: issue -reported: "There is no session.json" -severity: major - -### 4. Large conversation handling -expected: When conversation exceeds 100 messages, older messages are truncated with notification -result: skipped -reason: User chose to skip testing 100 message truncation feature - -### 5. Real-time resource monitoring -expected: Resource usage (CPU, RAM, GPU) displays during conversation with color-coded status -result: issue -reported: "not color coded, but there" -severity: minor - -### 6. Responsive terminal layout -expected: Resource display adapts to terminal width (full/compact/minimal layouts) -result: pass - -### 7. Resource alerts -expected: System shows warnings when resources are constrained (high CPU, low memory) -result: skipped -reason: User chose to skip testing resource constraint warnings - -### 8. Graceful degradation without dependencies -expected: CLI works normally even if rich/blessed packages are missing -result: pass - -## Summary - -total: 8 -passed: 3 -issues: 3 -pending: 0 -skipped: 2 - -## Gaps - -- truth: "Start a conversation, exit CLI, and restart. Session continues with contextual message about time elapsed" - status: failed - reason: "User reported: Welcome back message shows time elapsed but error: 'ConversationState' object has no attribute 'set_conversation_history'" - severity: major - test: 1 - root_cause: "Missing set_conversation_history method in ConversationState class" - artifacts: - - path: "src/mai/conversation/state.py" - issue: "Missing set_conversation_history method" - missing: - - "Add set_conversation_history method to convert Ollama messages back to ConversationTurn objects" - debug_session: ".planning/debug/resolved/session-persistence-error.md" -- truth: "Messages are automatically saved to ~/.mai/session.json during conversation" - status: failed - reason: "User reported: There is no session.json" - severity: major - test: 3 - root_cause: "Session system works correctly, but users lack clear feedback about when/where session files are created" - artifacts: - - path: "src/app/__main__.py" - issue: "Missing user-friendly messaging about session file creation and location" - missing: - - "Add verbose feedback for session operations" - - "Enhance /session command with file information display" - - "Improve new session creation messaging" - debug_session: ".planning/debug/resolved/missing-session-file.md" -- truth: "Resource usage (CPU, RAM, GPU) displays during conversation with color-coded status" - status: failed - reason: "User reported: not color coded, but there" - severity: minor - test: 5 - root_cause: "Rich console detects is_terminal=False and disables color output automatically" - artifacts: - - path: "src/app/__main__.py" - issue: "Console() initialization without force_terminal parameter" - missing: - - "Modify ResourceDisplayManager to use Console(force_terminal=True)" - debug_session: ".planning/debug/resolved/missing-color-coding.md" \ No newline at end of file