roger/myorg-assistant
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
87fb32b559f67a8445d6ba6f9eec2b9a0d2b1558
myorg-assistant/implementation-plan.md
Roger Oriol 87fb32b559 first commit
2026-02-03 23:50:19 +01:00

22 KiB
Raw Blame History

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

# .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
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

# 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