myorg-assistant/project-plan.md

# MyOrg Personal Assistant

**Project**: `+myorg-assistant`  
**Area**: `+CreixementPersonal` `+Carrera`  
**Status**: Planning  
**Created**: 2026-01-31  
**Goal**: Build an AI-powered personal assistant that helps manage daily life using the myorg GTD system

## Overview

The MyOrg Personal Assistant is an intelligent agent that helps you manage your personal organization system (myorg). It acts as a trusted assistant that can read, understand, and modify your GTD-based task management system, providing proactive help throughout your day.

## Vision

A personal AI assistant that:
- Understands your goals, projects, and daily priorities from your myorg repository
- Proactively helps you stay on track with briefings, reminders, and suggestions
- Makes it easy to capture tasks and manage your system through natural conversation
- Works autonomously as a trusted agent, handling routine operations without constant supervision
- Integrates seamlessly into your daily workflow through Discord and web interface

## Key Features

### 1. Intelligent Task Management
- **Natural Language Task Entry**: Add tasks by chatting naturally - assistant parses and formats properly
- **Context-Aware Suggestions**: Recommends tasks based on current context, time, and energy level
- **Smart Prioritization**: Analyzes your goals, due dates, and project status to suggest what to work on next
- **Automatic Archival**: Handles routine archival of completed tasks and projects

### 2. Proactive Scheduling & Reminders
- **Morning Briefing (8 AM)**: 
  - Today's calendar events
  - Priority tasks filtered by likely context
  - Items in waiting.txt that may need follow-up
  - Weather/commute info if relevant
  
- **Evening Summary (8 PM)**:
  - What was accomplished today
  - Tomorrow's calendar preview
  - Tasks to prepare for tomorrow
  - Reflection prompts for working-memory.txt

- **Weekly Review Assistant (Sunday)**:
  - Guides through weekly review process (following skills/weekly-review.md)
  - Suggests completed items to archive
  - Highlights stale waiting items
  - Reviews project progress against quarterly goals

- **Deadline Warnings**: Proactive alerts 7 days, 3 days, 1 day before due dates

- **Waiting List Follow-ups**: Weekly check-ins on items waiting on others

- **Calendar Prep**: 30-minute reminders before events with context and prep suggestions

### 3. Conversational Interface
- **Discord Integration**:
  - Natural conversation with the assistant bot
  - Scheduled messages sent automatically
  - Quick commands for common operations
  - Rich formatting with task lists and calendar views

- **Web Interface**:
  - Dashboard showing today's priorities
  - Chat interface for deeper conversations
  - Visual calendar and project boards
  - Quick-add forms for tasks/events

### 4. Context Intelligence
- **Manual Context Setting**: "I'm @bcn with @computer-deep focus for the next 2 hours"
- **Time-Based Inference**: Understands work hours, evenings, weekends from patterns
- **Calendar Integration**: Infers context from current/upcoming calendar events
- **Smart Filtering**: Shows only relevant tasks for current context

### 5. Goal Alignment
- Understands your telos.md, annual goals, and quarterly OKRs
- Connects tasks to projects to goals to missions
- Suggests tasks that move key goals forward
- Highlights projects that aren't progressing
- Provides goal progress reports

## Technical Architecture

### System Components

```
┌─────────────────────────────────────────────────────────────┐
│                        User Interfaces                       │
├──────────────────────────┬──────────────────────────────────┤
│   Discord Bot            │      Web Interface               │
│   - Natural chat         │      - Dashboard                 │
│   - Scheduled messages   │      - Chat UI                   │
│   - Rich formatting      │      - Visual views              │
└──────────────────────────┴──────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Assistant Service                         │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              Core Agent (LLM-Powered)                │   │
│  │  - Intent understanding                              │   │
│  │  - Context management                                │   │
│  │  - Response generation                               │   │
│  └──────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              Task Engine                             │   │
│  │  - Parse/format todo.txt, calendar.txt, etc.        │   │
│  │  - CRUD operations on all myorg files                │   │
│  │  - Query and filter tasks/projects/events           │   │
│  │  - Git operations (commit, pull, push)              │   │
│  └──────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              Scheduler                               │   │
│  │  - Cron jobs for briefings and reminders            │   │
│  │  - Deadline monitoring                               │   │
│  │  - Event-based triggers                              │   │
│  └──────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              Context Manager                         │   │
│  │  - Track user's current context                     │   │
│  │  - Infer context from time/calendar                  │   │
│  │  - Filter tasks by context                           │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    External Services                         │
├──────────────────────────┬──────────────────────────────────┤
│   LiteLLM Service        │      Git Repository              │
│   (Claude/OpenAI)        │      (myorg)                     │
│   - Running in k3s       │      - Cloned in container       │
│   - Natural language     │      - Periodic sync             │
│   - Reasoning            │      - Auto-commit updates       │
└──────────────────────────┴──────────────────────────────────┘
```

### Deployment Architecture

**Kubernetes Resources:**
- **Deployment**: `myorg-assistant` (1 replica)
- **Service**: Internal ClusterIP for web interface
- **CronJobs**: 
  - `morning-briefing`: Runs daily at 8:00 AM
  - `evening-summary`: Runs daily at 8:00 PM
  - `weekly-review`: Runs Sunday at 6:00 PM
  - `deadline-checker`: Runs hourly
  - `waiting-followup`: Runs weekly
  - `git-sync`: Runs every 15 minutes
- **ConfigMap**: Discord bot token, LiteLLM endpoint, schedule configs
- **Secret**: Git credentials, Discord bot token
- **PersistentVolumeClaim**: Store cloned myorg repository

### Technology Stack

**Backend:**
- **Language**: Python 3.11+
- **Framework**: FastAPI (for web API) + Discord.py (for bot)
- **LLM Integration**: 
  - **Agent Framework**: Claude Agent SDK for building AI agents with tool use capabilities
  - **LLM Provider**: LiteLLM proxy (running in k3s) providing access to Claude Sonnet 4.5
  - **Model**: claude-sonnet-4-5 via LiteLLM endpoint
  - **Agent Tools**: File read/write, task parsing, git operations, calendar queries
- **Task Parsing**: Custom parsers for todo.txt format + calendar format
- **Git Operations**: GitPython
- **Scheduling**: APScheduler or built-in CronJobs
- **Data Storage**: File-based (myorg git repo) + SQLite for assistant state

**Frontend (Web Interface):**
- **Framework**: Vanilla JavaScript (no framework needed)
- **Styling**: Vanilla CSS (semantic HTML with progressive enhancement)
- **Interactivity**: HTMX for dynamic updates without full page reloads
- **Real-time**: Server-Sent Events (SSE) for chat updates
- **Calendar View**: Minimal custom CSS Grid calendar or simple list views
- **Approach**: Server-rendered HTML templates (Jinja2) with HTMX for dynamic parts

**Infrastructure:**
- **Container**: Docker
- **Orchestration**: Kubernetes (k3s)
- **Ingress**: Traefik or nginx-ingress (if exposing web UI)
- **Monitoring**: Prometheus + Grafana (optional)

## AI Agent Architecture with Claude Agent SDK

The assistant uses the **Claude Agent SDK** to build intelligent agents that can autonomously perform complex tasks by reading files, modifying data, and using custom tools.

### Why Claude Agent SDK?

- **Native Tool Use**: Built-in support for function calling and tool execution
- **File Operations**: Read/write myorg files (todo.txt, calendar.txt, etc.) directly
- **Complex Reasoning**: Multi-step task planning and execution
- **Context Management**: Maintains conversation history and system state
- **Error Handling**: Graceful handling of tool failures and retries

### Agent Tool Suite

The assistant agent has access to the following tools:

**1. File System Tools:**
- `read_file(path)`: Read any myorg file (todo.txt, telos.md, goals, etc.)
- `write_file(path, content)`: Write/update myorg files
- `append_to_file(path, content)`: Append to files (e.g., working-memory.txt)
- `list_files(directory)`: Browse myorg structure

**2. Task Management Tools:**
- `parse_todo(file_content)`: Parse todo.txt format into structured data
- `add_task(description, project, context, priority, due_date)`: Add formatted task
- `complete_task(task_id)`: Mark task as complete with timestamp
- `search_tasks(query, filters)`: Query tasks by project, context, priority
- `archive_completed_tasks()`: Move completed tasks to archive

**3. Calendar Tools:**
- `parse_calendar(file_content)`: Parse calendar.txt into structured events
- `add_event(date, time, description, tags)`: Add formatted calendar entry
- `get_events(date_range)`: Get events for specific dates
- `get_todays_events()`: Quick access to today's schedule

**4. Project & Goal Tools:**
- `get_active_projects()`: List all active projects from projects.txt
- `get_quarterly_goals()`: Read current quarter's OKR goals
- `get_telos()`: Read telos.md for mission alignment
- `project_progress(project_tag)`: Analyze tasks completed for a project

**5. Git Tools:**
- `git_status()`: Check repository status
- `git_commit(message)`: Commit changes to myorg
- `git_pull()`: Sync latest changes
- `git_push()`: Push updates to remote

**6. Context & Intelligence Tools:**
- `infer_context(time, calendar_events)`: Determine likely user context
- `suggest_tasks(context, time_available, energy_level)`: Recommend tasks
- `analyze_goal_progress(goal_id)`: Track progress toward goals
- `check_waiting_items()`: Review waiting.txt for follow-ups
- `find_overdue_tasks()`: Identify tasks past due date

### Agent Workflows

**Example 1: Morning Briefing Agent**
```python
# Agent receives scheduled trigger at 8:00 AM
agent = ClaudeAgent(tools=[
    read_file, parse_calendar, parse_todo, 
    get_todays_events, infer_context, suggest_tasks
])

response = agent.run("""
Generate morning briefing for today:
1. Read calendar.txt and find today's events
2. Read todo.txt and identify priority tasks
3. Read waiting.txt for items needing follow-up
4. Infer likely context based on calendar
5. Suggest top 5 tasks for the day
6. Format as Discord message
""")
```

**Example 2: Natural Language Task Entry**
```python
# User says: "Recordatori para comprar llet demà al matí"
agent = ClaudeAgent(tools=[
    read_file, write_file, add_task, git_commit
])

response = agent.run("""
User said: "Recordatori para comprar llet demà al matí"

Parse this natural language input and:
1. Extract task: "Comprar llet"
2. Determine due date: tomorrow (2026-02-01)
3. Infer context: @recados (shopping)
4. Add to todo.txt with proper format
5. Commit change to git
6. Confirm to user
""")
```

**Example 3: Weekly Review Assistant**
```python
# Scheduled Sunday 6 PM
agent = ClaudeAgent(tools=[
    read_file, parse_todo, archive_completed_tasks,
    get_quarterly_goals, project_progress, git_commit
])

response = agent.run("""
Conduct weekly review:
1. Read todo.txt and identify completed tasks
2. Suggest archival of completed items
3. Check waiting.txt for stale items (>7 days)
4. Read quarterly goals and assess progress
5. Analyze project progress (tasks completed per project)
6. Generate summary report
7. Ask user for confirmation before archiving
""")
```

### Agent Configuration

**System Prompt:**
```
You are a personal assistant managing a GTD-based organization system.

Repository structure:
- todo.txt: Active tasks in todo.txt format
- calendar.txt: Calendar events
- projects.txt: Active projects
- waiting.txt: Items waiting on others
- telos.md: User's vision and missions
- goals/: Quarterly and yearly goals

Your role:
- Help user capture, organize, and prioritize tasks
- Provide context-aware suggestions
- Handle routine operations autonomously
- Maintain system integrity (proper formats, git commits)
- Be proactive but respect user's decisions

When modifying files:
- Always preserve todo.txt format
- Include proper metadata (dates, projects, contexts)
- Commit changes with descriptive messages
- Keep working-memory.txt updated with significant actions
```

**Agent Settings:**
- Model: `claude-sonnet-4-5` (via LiteLLM endpoint in k3s cluster)
- Temperature: 0.7 (balanced between creativity and consistency)
- Max tokens: 4096
- Tool choice: Auto (agent decides when to use tools)
- LiteLLM endpoint: `http://litellm-service.default.svc.cluster.local:4000`

**How it works:**
The Claude Agent SDK orchestrates agent behavior (tool calling, conversation flow, task planning) while using the LiteLLM proxy as the model provider. LiteLLM handles the actual API calls to Anthropic's Claude Sonnet 4.5 model, providing unified API access and load balancing.

### Error Handling & Safety

**File Operation Safety:**
- Always read before write to verify file exists
- Validate todo.txt format before writing
- Backup files before major changes
- Rollback git commits if operations fail

**LLM Reliability:**
- LiteLLM proxy provides retry logic and error handling
- Cache frequently used data (telos, goals) to reduce API calls
- Graceful degradation if LiteLLM endpoint is temporarily unavailable

**Rate Limiting:**
- Scheduled jobs: 1 per scheduled time (no retries unless failed)
- User interactions: Standard API limits via LiteLLM
- Background sync: Max 1 git operation per 15 minutes

## User Interactions

### Discord Chat Examples

**Adding a task:**
```
You: "Recordatori para comprar llet demà al matí"
Assistant: ✅ Afegit a todo.txt:
(B) 2026-02-01 Comprar llet @recados due:2026-02-01
```

**Asking what to work on:**
```
You: "Què hauria de fer ara? Estic @bcn amb 2 hores @computer-deep"
Assistant: 📋 Basant-me en els teus projectes actius i el context @computer-deep, et recomano:

1. *(A)* Continuar amb l'article observability-blog +observability-blog
2. Definir arquitectura myorg-assistant +myorg-assistant
3. Review PRs pendents +k3s

Els teus top goals per Q1 són: observability content i k3s setup. Les primeres dues tasques t'ajuden amb això.
```

**Morning briefing:**
```
Assistant: 🌅 **Bon dia! Resum del dissabte 1 febrer 2026**

📅 **Esdeveniments d'avui:**
- Cap esdeveniment programat

✅ **Tasques prioritàries:**
- *(A)* Escriure draft observability blog +observability-blog @computer-deep
- Arreglar ingress k3s +k3s @bcn
- Comprar llet @recados

⏳ **Waiting list (items que pots revisar):**
- Himanshu firmar documents +Llar
- Pagament final Corte Inglés Viatges +egipte (due: 2026-02-21)

🎯 **Projectes actius:** 6 projectes, 3 necessiten atenció aquesta setmana
```

### Weekly Review Flow

```
Assistant (Sunday 6 PM): 
📝 **Hora de la revisió setmanal!**

He trobat:
- 12 tasques completades aquesta setmana
- 3 projectes amb progrés
- 2 items a waiting.txt sense updates en >7 dies

Vols que et guiï per la revisió? [Sí] [Més tard]

User: Sí