rebased
Some checks failed
Discord Webhook / git (push) Has been cancelled

This commit is contained in:
Mai Development
2026-01-26 23:16:30 -05:00
parent f238a958a0
commit 5dc7b98abf
8 changed files with 391 additions and 673 deletions

121
.planning/PROJECT.md Normal file
View File

@@ -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*

258
.planning/REQUIREMENTS.md Normal file
View File

@@ -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*

12
.planning/config.json Normal file
View File

@@ -0,0 +1,12 @@
{
"mode": "yolo",
"depth": "comprehensive",
"parallelization": true,
"commit_docs": true,
"model_profile": "budget",
"workflow": {
"research": true,
"plan_check": true,
"verifier": true
}
}

View File

@@ -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"
---
<objective>
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
</objective>
<execution_context>
@~/.opencode/get-shit-done/workflows/execute-plan.md
@~/.opencode/get-shit-done/templates/summary.md
</execution_context>
<context>
@.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
</context>
<tasks>
<task type="auto">
<name>Fix ConversationState missing set_conversation_history method</name>
<files>src/mai/conversation/state.py</files>
<action>
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
</action>
<verify>
# 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)
"
</verify>
<verify>
# 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)
"
</verify>
<done>
ConversationState class has set_conversation_history method that can convert Ollama messages back to ConversationTurn objects for session restoration
</done>
</task>
</tasks>
<verification>
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
</verification>
<success_criteria>
- 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
</success_criteria>
<output>
After completion, create `.planning/phases/06-cli-interface/06-05-SUMMARY.md`
</output>

View File

@@ -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"
---
<objective>
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
</objective>
<execution_context>
@~/.opencode/get-shit-done/workflows/execute-plan.md
@~/.opencode/get-shit-done/templates/summary.md
</execution_context>
<context>
@.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
</context>
<tasks>
<task type="auto">
<name>Add verbose session feedback and fix resource display colors</name>
<files>src/app/__main__.py</files>
<action>
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.
</action>
<verify>
# 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)
"
</verify>
<done>
CLI now provides clear feedback about session file operations and resource monitoring displays with proper color coding
</done>
</task>
</tasks>
<verification>
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
</verification>
<success_criteria>
- 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
</success_criteria>
<output>
After completion, create `.planning/phases/06-cli-interface/06-06-SUMMARY.md`
</output>

View File

@@ -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"
---
<objective>
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
</objective>
<execution_context>
@~/.opencode/get-shit-done/workflows/execute-plan.md
@~/.opencode/get-shit-done/templates/summary.md
</execution_context>
<context>
@.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
</context>
<tasks>
<task type="auto">
<name>Implement comprehensive help system</name>
<files>src/app/__main__.py</files>
<action>
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.
</action>
<verify>
# 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')
"
</verify>
<done>
CLI now has a comprehensive help system that displays all available commands with descriptions, usage examples, and professional formatting
</done>
</task>
</tasks>
<verification>
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
</verification>
<success_criteria>
- /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)
</success_criteria>
<output>
After completion, create `.planning/phases/06-cli-interface/06-07-SUMMARY.md`
</output>

View File

@@ -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"
---
<objective>
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
</objective>
<execution_context>
@~/.opencode/get-shit-done/workflows/execute-plan.md
@~/.opencode/get-shit-done/templates/summary.md
</execution_context>
<context>
@.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
</context>
<tasks>
<task type="auto">
<name>Fix CLI exit command implementation</name>
<files>src/app/__main__.py</files>
<action>
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.
</action>
<verify>
# 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')
"
</verify>
<done>
CLI now has working exit commands (/exit, /quit, Ctrl+D) that properly terminate the application with graceful shutdown and farewell messages
</done>
</task>
</tasks>
<verification>
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
</verification>
<success_criteria>
- /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)
</success_criteria>
<output>
After completion, create `.planning/phases/06-cli-interface/06-08-SUMMARY.md`
</output>

View File

@@ -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"