roger/myorg-assistant
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
Roger Oriol
2026-02-03 23:50:19 +01:00
commit 87fb32b559
80 changed files with 8884 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

745
implementation-plan.md Normal file
View File

@@ -0,0 +1,745 @@
# MyOrg Personal Assistant - Implementation Plan
**Project**: `+myorg-assistant`
**Document**: Implementation Plan
**Created**: 2026-01-31
**Status**: Planning
## Overview
This document outlines the step-by-step implementation plan for building the MyOrg Personal Assistant. The project is broken down into phases, with each phase delivering functional value that can be tested and used.
## Implementation Strategy
**Approach**: Incremental delivery with vertical slices
- Each phase delivers a working feature end-to-end
- Early phases establish core infrastructure
- Later phases add intelligence and automation
- Can deploy and use the system after Phase 2
**Development Environment**:
- Local development: Python virtual environment, local git clone of myorg
- Testing: Unit tests + integration tests with test myorg repository
- Deployment: Docker container → k3s cluster
## Phases
### Phase 0: Project Setup & Foundation (Week 1)
**Goal**: Set up development environment and project structure
**Tasks**:
1. Create project repository structure
```
myorg-assistant/
├── src/
│ ├── agent/ # Claude Agent SDK integration
│ ├── tools/ # Agent tools (file ops, git, parsers)
│ ├── parsers/ # Todo.txt, calendar.txt parsers
│ ├── api/ # FastAPI endpoints
│ ├── bot/ # Discord bot
│ ├── web/ # Web UI (templates, static files)
│ └── scheduler/ # Scheduled jobs
├── tests/
├── k8s/ # Kubernetes manifests
├── Dockerfile
├── requirements.txt
└── README.md
```
2. Set up Python environment
- Create virtual environment
- Install core dependencies: FastAPI, Claude Agent SDK, GitPython, Discord.py
- Set up pre-commit hooks (black, ruff, mypy)
3. Create parsers for myorg formats
- `TodoParser`: Parse todo.txt format
- `CalendarParser`: Parse calendar.txt format
- `ProjectParser`: Parse projects.txt
- Unit tests for each parser
4. Create test myorg repository
- Minimal working example with sample data
- Use for testing without affecting real data
**Deliverable**: Working parsers that can read myorg files
**Estimated Time**: 3-4 days
---
### Phase 1: Core Agent with File Tools (Week 1-2)
**Goal**: Build Claude Agent SDK integration with basic file operations
**Tasks**:
1. Set up Claude Agent SDK
- Configure connection to LiteLLM endpoint
- Set up Claude Sonnet 4.5 model
- Create base agent class
2. Implement file operation tools
- `read_file(path)`: Read any myorg file
- `write_file(path, content)`: Write/update files
- `append_to_file(path, content)`: Append content
- `list_files(directory)`: Browse structure
- Add safety checks (validate paths, backup before write)
3. Implement task management tools
- `add_task(description, project, context, priority, due_date)`
- `complete_task(task_line_number)`: Mark complete with timestamp
- `search_tasks(filters)`: Query by project/context/priority
- Use TodoParser for proper formatting
4. Implement git tools
- `git_status()`: Check repo status
- `git_commit(message)`: Commit changes
- `git_pull()`: Sync from remote
- `git_push()`: Push to remote
5. Create agent system prompt
- Define agent role and responsibilities
- Document myorg structure and formats
- Set guidelines for autonomous actions
6. Build simple CLI for testing
- Interactive chat with agent
- Test file operations and task management
- Verify git integration
**Deliverable**: Working agent that can read/write myorg files and manage tasks via CLI
**Estimated Time**: 4-5 days
---
### Phase 2: Discord Bot Integration (Week 2-3)
**Goal**: Deploy agent as Discord bot for daily use
**Tasks**:
1. Set up Discord bot
- Create Discord application and bot
- Implement discord.py integration
- Connect bot to agent backend
2. Implement core bot commands
- Natural conversation → agent processes
- `/briefing`: Manual trigger for daily summary
- `/add [task]`: Quick task addition
- `/tasks [filter]`: Show filtered tasks
- `/today`: Today's calendar and priority tasks
- `/context [context]`: Set current context
3. Format agent responses for Discord
- Use Discord markdown formatting
- Add emojis for readability
- Handle long responses (pagination/truncation)
4. Create Docker container
- Dockerfile with Python app
- Include git for repository operations
- Environment variables for config
5. Deploy to k3s cluster
- Create Kubernetes Deployment manifest
- Create ConfigMap for configuration
- Create Secret for Discord token and git credentials
- Create PersistentVolumeClaim for myorg repository
- Deploy and test
6. Set up repository sync
- Clone myorg repo on container startup
- Periodic git pull (every 15 minutes)
- Auto-push after agent commits
**Deliverable**: Discord bot that can chat, add tasks, and show daily summary
**Estimated Time**: 5-6 days
---
### Phase 3: Scheduled Briefings & Reminders (Week 3-4)
**Goal**: Add proactive scheduled features
**Tasks**:
1. Implement briefing generators
- `generate_morning_briefing()`: Calendar + priority tasks + waiting items
- `generate_evening_summary()`: Accomplishments + tomorrow prep
- Format as Discord messages
2. Implement reminder logic
- `check_deadlines()`: Find tasks due soon (7d, 3d, 1d)
- `check_waiting_items()`: Find stale waiting list items
- `check_upcoming_events()`: Calendar prep (30 min before)
3. Set up scheduling system
- Option A: APScheduler in-process
- Option B: Kubernetes CronJobs (preferred for k8s)
- Configure timezone handling
4. Create Kubernetes CronJobs
- `morning-briefing`: Daily at 8:00 AM
- `evening-summary`: Daily at 8:00 PM
- `deadline-checker`: Hourly
- `waiting-followup`: Weekly (Monday 9:00 AM)
- `git-sync`: Every 15 minutes
- All jobs send messages via Discord bot
5. Implement context inference
- `infer_context(time, calendar_events)`: Guess user context
- Time-based rules (work hours, evenings, weekends)
- Calendar-based (meeting → @telefon, travel → location)
**Deliverable**: Automated briefings and reminders sent via Discord
**Estimated Time**: 5-6 days
---
### Phase 4: Web Interface (Week 4-5)
**Goal**: Build web dashboard for richer visualization
**Tasks**:
1. Set up FastAPI web server
- Create FastAPI app
- Add Jinja2 template engine
- Serve static files (CSS, JS)
2. Build core pages
- **Dashboard** (`/`):
- Today's calendar events
- Priority tasks list
- Quick stats (active projects, waiting items)
- Context selector
- **Chat** (`/chat`):
- Chat interface with agent
- Server-Sent Events for real-time updates
- HTMX for message sending/loading
- **Tasks** (`/tasks`):
- Filterable task list
- Add/complete tasks
- HTMX for dynamic updates
- **Calendar** (`/calendar`):
- Monthly/weekly calendar view
- Today's events highlighted
- Simple CSS Grid layout
- **Projects** (`/projects`):
- Active projects list
- Progress indicators
- Link to related tasks
3. Style with vanilla CSS
- Clean, semantic HTML
- Responsive layout (mobile-friendly)
- Dark mode support
- Minimal, fast-loading
4. Add HTMX interactivity
- Task completion without page reload
- Live task filtering
- Quick-add forms
- Auto-refresh sections
5. Implement SSE for chat
- Real-time agent responses
- Streaming message updates
- Connection handling
6. Add authentication (basic)
- Simple password or API key
- Protect web interface
- Optional: OAuth if needed
7. Update Kubernetes manifests
- Add Service for web interface
- Add Ingress (optional, for external access)
- Configure internal DNS
**Deliverable**: Web interface for viewing tasks, calendar, and chatting with agent
**Estimated Time**: 6-7 days
---
### Phase 5: Advanced Intelligence (Week 5-6)
**Goal**: Add smart suggestions and goal tracking
**Tasks**:
1. Implement calendar tools
- `parse_calendar()`: Read and structure calendar.txt
- `add_event()`: Add formatted events
- `get_events(date_range)`: Query events
- `get_todays_events()`: Quick today access
2. Implement project & goal tools
- `get_active_projects()`: Parse projects.txt
- `get_quarterly_goals()`: Read current quarter goals
- `get_telos()`: Read telos.md
- `analyze_project_progress(project)`: Count tasks completed
- `analyze_goal_progress(goal)`: Track goal completion
3. Implement intelligent suggestions
- `suggest_tasks(context, time_available, energy_level)`:
- Filter by context
- Consider time of day
- Prioritize goal-aligned work
- Respect due dates
- Add to morning briefing and `/suggest` command
4. Implement goal alignment features
- Show project → goal → mission mappings
- Highlight projects not progressing
- Suggest tasks that move goals forward
- Weekly goal progress report
5. Add working memory integration
- Automatically update working-memory.txt after significant actions
- Include working memory in agent context
- Show recent activities in dashboard
6. Enhance weekly review assistant
- Follow skills/weekly-review.md guide
- Interactive walkthrough via Discord
- Automatic archival suggestions
- Project progress analysis
- Goal alignment check
**Deliverable**: Intelligent task suggestions and goal tracking
**Estimated Time**: 6-7 days
---
### Phase 6: Polish & Optimization (Week 6-7)
**Goal**: Improve performance, reliability, and user experience
**Tasks**:
1. Performance optimization
- Cache frequently accessed files (telos, goals)
- Optimize parser performance
- Reduce LLM API calls where possible
- Add request/response caching
2. Error handling improvements
- Graceful degradation if LiteLLM unavailable
- Better error messages for users
- Automatic retry logic for transient failures
- Rollback on git commit failures
3. Add monitoring and logging
- Structured logging (JSON format)
- Log agent actions (file writes, git commits)
- Track API usage and costs
- Optional: Prometheus metrics
4. Improve Discord UX
- Better formatting and layout
- Interactive buttons for confirmations
- Typing indicators while agent thinks
- Help command with examples
5. Improve web UI
- Loading states for HTMX requests
- Error notifications
- Keyboard shortcuts
- Accessibility improvements
6. Add configuration options
- User preferences (briefing time, reminder settings)
- Configurable contexts
- Custom scheduling
- Store in SQLite database
7. Testing and QA
- Integration tests for key workflows
- Test with real myorg data
- Performance testing under load
- Security audit (file access, git operations)
8. Documentation
- User guide (how to use bot and web UI)
- Deployment guide (k8s setup)
- Development guide (how to add tools)
- Troubleshooting guide
**Deliverable**: Production-ready assistant with monitoring and docs
**Estimated Time**: 5-6 days
---
## Phase 7: Optional Enhancements (Future)
**Goal**: Additional features based on usage and feedback
**Potential features**:
- Mobile PWA (progressive web app)
- Voice interface (speech-to-text for task entry)
- Email integration (send briefings via email)
- Calendar sync (import/export to Google Calendar)
- Habits tracking (daily check-ins, streaks)
- Advanced analytics (productivity reports, time tracking)
- Multi-user support (family/team organization)
- Backup and restore functionality
- API webhooks for external integrations
---
## Technical Details
### Repository Structure
```
myorg-assistant/
├── src/
│ ├── __init__.py
│ ├── main.py # Application entry point
│ ├── config.py # Configuration management
│ │
│ ├── agent/
│ │ ├── __init__.py
│ │ ├── core.py # Claude Agent SDK setup
│ │ ├── prompts.py # System prompts
│ │ └── tools.py # Tool registry
│ │
│ ├── tools/
│ │ ├── __init__.py
│ │ ├── file_ops.py # File operation tools
│ │ ├── task_ops.py # Task management tools
│ │ ├── calendar_ops.py # Calendar tools
│ │ ├── git_ops.py # Git tools
│ │ ├── project_ops.py # Project/goal tools
│ │ └── intelligence.py # Smart suggestions
│ │
│ ├── parsers/
│ │ ├── __init__.py
│ │ ├── todo_parser.py # Todo.txt format
│ │ ├── calendar_parser.py # Calendar.txt format
│ │ └── project_parser.py # Projects.txt format
│ │
│ ├── api/
│ │ ├── __init__.py
│ │ ├── app.py # FastAPI application
│ │ ├── routes/
│ │ │ ├── chat.py # Chat endpoints
│ │ │ ├── tasks.py # Task CRUD endpoints
│ │ │ ├── calendar.py # Calendar endpoints
│ │ │ └── dashboard.py # Dashboard data
│ │ └── middleware.py # Auth, CORS, etc.
│ │
│ ├── bot/
│ │ ├── __init__.py
│ │ ├── discord_bot.py # Discord bot setup
│ │ ├── commands.py # Bot commands
│ │ └── formatters.py # Discord message formatting
│ │
│ ├── scheduler/
│ │ ├── __init__.py
│ │ ├── jobs.py # Scheduled job definitions
│ │ └── briefings.py # Briefing generators
│ │
│ ├── web/
│ │ ├── templates/ # Jinja2 templates
│ │ │ ├── base.html
│ │ │ ├── dashboard.html
│ │ │ ├── chat.html
│ │ │ ├── tasks.html
│ │ │ ├── calendar.html
│ │ │ └── projects.html
│ │ └── static/
│ │ ├── css/
│ │ │ └── style.css
│ │ └── js/
│ │ └── app.js # Minimal vanilla JS
│ │
│ └── utils/
│ ├── __init__.py
│ ├── git.py # Git helper functions
│ └── context.py # Context inference
│
├── tests/
│ ├── __init__.py
│ ├── test_parsers.py
│ ├── test_tools.py
│ ├── test_agent.py
│ └── fixtures/
│ └── test_myorg/ # Test myorg repository
│
├── k8s/
│ ├── deployment.yaml # Main app deployment
│ ├── service.yaml # ClusterIP service
│ ├── ingress.yaml # Optional ingress
│ ├── configmap.yaml # Configuration
│ ├── secret.yaml.example # Secret template
│ ├── pvc.yaml # Persistent volume claim
│ └── cronjobs/
│ ├── morning-briefing.yaml
│ ├── evening-summary.yaml
│ ├── deadline-checker.yaml
│ ├── waiting-followup.yaml
│ └── git-sync.yaml
│
├── Dockerfile
├── requirements.txt
├── requirements-dev.txt
├── .env.example
├── .gitignore
├── pytest.ini
├── mypy.ini
└── README.md
```
### Key Dependencies
```
# requirements.txt
fastapi==0.109.0
uvicorn[standard]==0.27.0
discord.py==2.3.2
gitpython==3.1.41
anthropic==0.18.0 # Claude Agent SDK
jinja2==3.1.3
python-multipart==0.0.6
httpx==0.26.0
apscheduler==3.10.4
python-dotenv==1.0.0
pydantic==2.5.3
pydantic-settings==2.1.0
# requirements-dev.txt
pytest==7.4.4
pytest-asyncio==0.23.3
black==24.1.1
ruff==0.1.14
mypy==1.8.0
```
### Environment Variables
```bash
# .env.example
# LiteLLM Configuration
LITELLM_ENDPOINT=http://litellm-service.default.svc.cluster.local:4000
LITELLM_API_KEY=your-api-key
LITELLM_MODEL=claude-sonnet-4-5
# Discord Configuration
DISCORD_BOT_TOKEN=your-discord-bot-token
DISCORD_CHANNEL_ID=your-channel-id
# Git Configuration
GIT_REPO_URL=https://github.com/yourusername/myorg.git
GIT_BRANCH=main
GIT_USERNAME=your-username
GIT_TOKEN=your-git-token
# Myorg Repository Path
MYORG_REPO_PATH=/data/myorg
# Scheduling (timezone)
TIMEZONE=Europe/Madrid
# Web Interface
WEB_HOST=0.0.0.0
WEB_PORT=8000
WEB_SECRET_KEY=your-secret-key
# Optional: Authentication
WEB_PASSWORD=your-password # Basic auth for web UI
```
### Docker Configuration
```dockerfile
# Dockerfile
FROM python:3.11-slim
# Install git
RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
# Set working directory
WORKDIR /app
# Copy requirements
COPY requirements.txt .
# Install dependencies
RUN pip install --no-cache-dir -r requirements.txt
# Copy application code
COPY src/ ./src/
# Create data directory for myorg repo
RUN mkdir -p /data/myorg
# Expose web interface port
EXPOSE 8000
# Run application
CMD ["python", "-m", "src.main"]
```
### Kubernetes Deployment Example
```yaml
# k8s/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: myorg-assistant
labels:
app: myorg-assistant
spec:
replicas: 1
selector:
matchLabels:
app: myorg-assistant
template:
metadata:
labels:
app: myorg-assistant
spec:
containers:
- name: myorg-assistant
image: myorg-assistant:latest
imagePullPolicy: IfNotPresent
ports:
- containerPort: 8000
name: web
env:
- name: LITELLM_ENDPOINT
valueFrom:
configMapKeyRef:
name: myorg-assistant-config
key: litellm_endpoint
- name: DISCORD_BOT_TOKEN
valueFrom:
secretKeyRef:
name: myorg-assistant-secret
key: discord_token
- name: GIT_TOKEN
valueFrom:
secretKeyRef:
name: myorg-assistant-secret
key: git_token
envFrom:
- configMapRef:
name: myorg-assistant-config
volumeMounts:
- name: myorg-data
mountPath: /data/myorg
resources:
requests:
memory: "256Mi"
cpu: "250m"
limits:
memory: "512Mi"
cpu: "500m"
volumes:
- name: myorg-data
persistentVolumeClaim:
claimName: myorg-assistant-pvc
```
---
## Timeline Summary
| Phase | Duration | Deliverable |
|-------|----------|-------------|
| Phase 0: Setup | 3-4 days | Parsers working |
| Phase 1: Core Agent | 4-5 days | CLI agent with file tools |
| Phase 2: Discord Bot | 5-6 days | Discord bot deployed to k8s |
| Phase 3: Scheduling | 5-6 days | Automated briefings |
| Phase 4: Web Interface | 6-7 days | Web dashboard |
| Phase 5: Intelligence | 6-7 days | Smart suggestions & goal tracking |
| Phase 6: Polish | 5-6 days | Production-ready system |
| **Total** | **~6 weeks** | Full personal assistant |
---
## Development Workflow
### Local Development
1. Clone myorg-assistant repository
2. Create Python virtual environment: `python -m venv venv`
3. Install dependencies: `pip install -r requirements.txt -r requirements-dev.txt`
4. Copy `.env.example` to `.env` and configure
5. Clone test myorg repository to `/tmp/test-myorg`
6. Run tests: `pytest`
7. Run locally: `python -m src.main`
### Testing
- Unit tests for parsers and tools
- Integration tests for agent workflows
- Test against test myorg repository
- Manual testing via CLI and Discord
### Deployment
1. Build Docker image: `docker build -t myorg-assistant:latest .`
2. Push to registry (or load into k3s)
3. Apply Kubernetes manifests: `kubectl apply -f k8s/`
4. Check logs: `kubectl logs -f deployment/myorg-assistant`
5. Test Discord bot
6. Test web interface
### Monitoring
- Application logs: `kubectl logs -f deployment/myorg-assistant`
- CronJob status: `kubectl get cronjobs`
- Git sync status: Check commits in myorg repository
- Discord bot health: Send test message
---
## Success Criteria
**Phase 2 (MVP)**:
- ✅ Can chat with agent via Discord
- ✅ Can add tasks through natural language
- ✅ Can view today's tasks and calendar
- ✅ Agent commits changes to git
**Phase 3 (Automation)**:
- ✅ Receives morning briefing daily
- ✅ Receives evening summary daily
- ✅ Gets deadline warnings automatically
**Phase 4 (Complete)**:
- ✅ Can use web interface as alternative
- ✅ Dashboard shows relevant information
- ✅ HTMX provides smooth interactions
**Phase 5 (Intelligence)**:
- ✅ Agent suggests context-aware tasks
- ✅ Goal progress is tracked and reported
- ✅ Weekly review is assisted and automated
**Phase 6 (Production)**:
- ✅ System is stable and reliable
- ✅ Error handling is robust
- ✅ Documentation is complete
---
## Risk Mitigation
| Risk | Impact | Mitigation |
|------|--------|------------|
| LiteLLM endpoint unavailable | High | Add connection retry logic, graceful degradation |
| Claude API rate limits | Medium | Cache responses, limit proactive messages |
| Git conflicts on sync | Medium | Always pull before push, handle merge conflicts |
| Discord bot rate limits | Low | Throttle messages, batch notifications |
| File corruption | High | Backup before write, validate format, git history |
| Kubernetes pod crashes | Medium | Set restart policy, health checks, persistent storage |
---
## Next Steps
1. **Now**: Review and approve this implementation plan
2. **Next**: Set up project repository (Phase 0)
3. **Week 1**: Build parsers and core agent (Phases 0-1)
4. **Week 2**: Deploy Discord bot (Phase 2)
5. **Ongoing**: Continue through phases, testing at each step
---
**Last Updated**: 2026-01-31