Task Management System - Documentation

Overview

✅ Production Ready

A complete task management system that syncs with iCloud Reminders, built with the CTR (Clarify-Decompose-Refine) framework for AI agent coordination.

🗄️

SQLite Backend

Local database with full CTR framework implementation, audit trails, and dependency tracking.

☁️

iCloud Integration

Seamless sync to iCloud Reminders for cross-device access to your tasks.

🤖

Multi-Agent Support

Built for AI agents with session tracking and complete action audit trails.

🔄

External Sync

Framework supporting multiple external systems: iCloud, Google Tasks, Notion, and more.

Key Achievement

Successfully synced 7 tasks from a sample project to iCloud's "Family Time" reminder list.

⚠️ Critical Lesson: Use direct Python imports to iCloud MCP modules. Qwen's built-in MCP framework (ctx="native-icloud") always fails with "Not connected".

Architecture

System Diagram

Local Database

Projects
Phases
Tasks
Dependencies

↔️

Task Management

TaskAgent
SyncManager
CTR Framework
Conflict Resolution

↔️

iCloud Reminders

Reminder Lists
Reminders
Due Dates
Priorities

CTR Framework

Clarify

Define high-level projects with clear objectives and constraints.

Project name and description
Clear objective statement
Definition of done
Known constraints

Decompose

Break projects into phases and actionable tasks.

Phases: Level 1 work breakdown
Tasks: Specific, actionable items
Max 2 hours per task rule
Verb-object format enforcement

Refine

Validate, sequence, and track task execution.

Task validation rules
Dependency management
Progress tracking
Status management

Core Files

File	Purpose
`schema.sql`	Database schema with CTR framework
`agent_helpers.py`	Task management library for AI agents
`sync_helpers.py`	External sync framework
`enhanced_sync_helpers.py`	Enhanced iCloud integration
`complete_task_system.py`	Complete integration system

Getting Started

Prerequisites

Python 3.x
iCloud MCP Server at /Users/andrew/.mcp/native-icloud-mcp
macOS with Reminders app access

Quick Start

Creating a Project

from agent_helpers import TaskAgent

with TaskAgent(agent_name='claude-code') as agent:
    project_id = agent.create_project(
        name="My Awesome Project",
        objective="Build something amazing",
        definition_of_done="All features working and tested"
    )

Adding Tasks

task_ids = agent.add_tasks(project_id, [
    {
        'sequence': '1.1',
        'title': 'Create database design',
        'estimate_minutes': 90,
        'priority': 'high'
    },
    {
        'sequence': '1.2',
        'title': 'Implement API endpoints',
        'estimate_minutes': 120,
        'priority': 'high'
    }
], validate=True)  # Enforces CTR rules

iCloud Integration

How It Works

The system uses direct Python imports to access iCloud MCP modules, creating a FastMCP context for communication with iCloud.

💡 The Right Way:

sys.path.insert(0, '/Users/andrew/.mcp/native-icloud-mcp/src')
from native_icloud_mcp import reminders
from fastmcp import FastMCP, Context

mcp = FastMCP("unique-name")
ctx = Context(fastmcp=mcp)
result = asyncio.run(reminders.list_reminder_lists(ctx))

❌ The Wrong Way:

# NEVER use this - always fails
list_reminder_lists(ctx="native-icloud")

Syncing to iCloud

Sync Project to iCloud

from complete_task_system import iCloudTaskSyncSystem
import asyncio

async def sync_tasks():
    system = iCloudTaskSyncSystem()

    # List available lists
    lists = await system.list_available_lists()
    print(f"Available lists: {lists}")

    # Sync to a specific list
    success = await system.sync_project_to_icloud(
        project_id=1,
        list_name='Family Time'
    )
    return success

# Run the sync
asyncio.run(sync_tasks())

Task Mapping

Local Task Field	iCloud Reminder Field
`task.title`	`reminder.title`
`task.description`	`reminder.notes`
`task.priority`	`reminder.priority` (1=high, 5=medium, 9=low)
`task.status`	`reminder.completed`

API Reference

TaskAgent

`create_project(name, objective, definition_of_done, ...)`

Creates a new project with CTR validation.

Returns: project_id (int)

`add_tasks(project_id, tasks, validate=True)`

Adds tasks to a project with optional CTR validation.

Returns: List of task IDs

`update_task_status(task_id, status)`

Updates task status: 'pending', 'in_progress', 'completed'.

Returns: None

SyncManager

`register_external_system(system_id, name, system_type)`

Registers an external system for synchronization.

Returns: None

`sync_to_external(project_id, system_id)`

Syncs a project to an external system.

Returns: Sync results dict

Database Queries

Common SQL Queries

-- View all projects
SELECT * FROM projects;

-- View tasks for a project
SELECT * FROM tasks
WHERE project_id = 1
ORDER BY sequence;

-- View project progress
SELECT * FROM project_progress;

-- View ready tasks (no unmet dependencies)
SELECT * FROM ready_tasks;

Future Plans

Owen Memory System 🧠

📋 Planned

18-day implementation plan for a sophisticated memory system:

Neo4j - Graph database for knowledge storage
Graphiti - Memory backend for AI agents
Ollama - Local embeddings (nomic-embed-text)
Schema-based classification - Automatic content categorization
Context pruning - Keep conversations under 50K tokens
Memory retrieval - Smart searching of past conversations

Status: Comprehensive planning complete, ready to start implementation

✓

Phase 1: Core System

SQLite database with CTR framework

Completed

✓

Phase 2: iCloud Integration

Sync to iCloud Reminders

Completed

→

Phase 3: Memory System

Neo4j + Graphiti implementation

Planned

○

Phase 4: Bidirectional Sync

Sync changes from iCloud to local

Future

○

Phase 5: Web Interface

Dashboard for task management

Future

Additional Enhancements

🔄 Real-time Updates

Continuous synchronization between local and cloud

⚡ Conflict Resolution

Handle concurrent modifications intelligently

🔌 More Integrations

Google Tasks, Notion, Linear, Asana

📊 Analytics

Task completion metrics and insights