myorg-assistant/implementation-plan.md

# 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