claudetools/.claude/TASK_MANAGEMENT.md

# Task Management System

## Overview

All tasks and subtasks across all modes (MSP, Development, Normal) are tracked in a centralized checklist system. The orchestrator (main Claude session) manages this checklist, updating status as work progresses. All task data and context is persisted to the database via the Database Agent.

## Core Principles

### 1. Everything is Tracked
- User requests → Tasks
- Agent operations → Subtasks
- Code implementations → Tasks
- Research activities → Tasks
- Client work → Tasks (linked to client)
- Development features → Tasks (linked to project)

### 2. Orchestrator Maintains Checklist
The main Claude session (not agents) is responsible for:
- Creating tasks from user requests
- Breaking down complex tasks into subtasks
- Updating task status as agents report progress
- Marking tasks complete when work finishes
- Providing visibility to user on progress

### 3. Agents Report Progress
Agents don't manage tasks directly - they report to orchestrator:
- Agent starts work → Orchestrator marks task 'in_progress'
- Agent completes work → Orchestrator marks task 'completed'
- Agent encounters blocker → Orchestrator marks task 'blocked' with reason

### 4. Context is Preserved
Every task stores rich context in the database:
- What was requested
- Why it's needed
- What environment it runs in
- What agents worked on it
- What files were modified
- What blockers were encountered
- What the outcome was

## Workflow

### Step 1: User Makes Request
```
User: "Implement authentication for the API"
```

### Step 2: Orchestrator Creates Task(s)
Main Claude analyzes request and creates task structure:

```python
# Orchestrator thinks:
# This is a complex task - break it down

# Request to Database Agent:
{
  "operation": "create_task",
  "title": "Implement API authentication",
  "description": "Complete JWT-based authentication system",
  "task_type": "implementation",
  "status": "pending",
  "estimated_complexity": "moderate",
  "task_context": {
    "user_request": "Implement authentication for the API",
    "environment": "Python FastAPI project"
  }
}

# Then create subtasks:
{
  "operation": "create_subtasks",
  "parent_task_id": "parent-uuid",
  "subtasks": [
    {
      "title": "Design authentication schema",
      "task_type": "analysis",
      "status": "pending"
    },
    {
      "title": "Generate code for JWT authentication",
      "task_type": "implementation",
      "status": "pending"
    },
    {
      "title": "Review authentication code",
      "task_type": "review",
      "status": "pending"
    },
    {
      "title": "Write authentication tests",
      "task_type": "testing",
      "status": "pending"
    }
  ]
}
```

### Step 3: Orchestrator Shows Checklist to User
```markdown
## Task Breakdown

I'll implement API authentication in these steps:

- [ ] Design authentication schema
- [ ] Generate code for JWT authentication
- [ ] Review authentication code
- [ ] Write authentication tests

Starting with the design phase...
```

### Step 4: Orchestrator Launches Agents
```python
# Update task status
Database Agent: update_task(
  task_id="design-subtask-uuid",
  status="in_progress",
  assigned_agent="Coding Agent",
  started_at=now()
)

# Launch agent
Coding Agent: analyze_and_design_auth_schema(...)
```

### Step 5: Agent Completes, Orchestrator Updates
```python
# Agent returns design
# Orchestrator updates task

Database Agent: complete_task(
  task_id="design-subtask-uuid",
  completed_at=now(),
  task_context={
    "outcome": "Schema designed with users, tokens, refresh_tokens tables",
    "files_created": ["docs/auth_schema.md"]
  }
)

# Update checklist shown to user
```

### Step 6: Progress Visibility
```markdown
## Task Progress

- [✓] Design authentication schema (completed)
- [→] Generate code for JWT authentication (in progress)
- [ ] Review authentication code
- [ ] Write authentication tests
```

### Step 7: All Tasks Complete
```python
# When all subtasks done, mark parent complete
Database Agent: complete_task(
  task_id="parent-task-uuid",
  completed_at=now(),
  task_context={
    "outcome": "Authentication fully implemented and reviewed",
    "subtasks_completed": 4,
    "files_modified": ["auth.py", "user.py", "test_auth.py"],
    "production_ready": true
  }
)
```

## Task Status Flow

```
pending
  ↓ (agent starts work)
in_progress
  ↓
  ├─→ completed (success)
  ├─→ blocked (encountered issue)
  │     ↓ (issue resolved)
  │   in_progress (resume)
  └─→ cancelled (no longer needed)
```

## Task Types

### implementation
Code generation, feature building, system creation
- Assigned to: Coding Agent → Code Review Agent
- Context includes: files modified, dependencies added, review status

### research
Information gathering, codebase exploration, documentation reading
- Assigned to: Explore Agent, general-purpose agent
- Context includes: findings, relevant files, key information

### review
Code review, quality assurance, specification verification
- Assigned to: Code Review Agent
- Context includes: approval status, issues found, fixes applied

### testing
Test creation, test execution, validation
- Assigned to: Coding Agent (creates tests), potentially Test Agent (future)
- Context includes: tests created, pass/fail status, coverage

### deployment
Deploying code, configuring servers, setting up infrastructure
- Assigned to: DevOps Agent (future) or general-purpose agent
- Context includes: deployment steps, environment, verification

### documentation
Writing docs, creating guides, updating README files
- Assigned to: general-purpose agent
- Context includes: docs created, format, location

### bugfix
Fixing defects, resolving issues, patching problems
- Assigned to: Coding Agent → Code Review Agent
- Context includes: bug description, root cause, fix applied

### analysis
Understanding problems, investigating issues, exploring options
- Assigned to: Explore Agent, general-purpose agent
- Context includes: analysis results, options identified, recommendations

## Context Data Structure

Each task stores rich context as JSON:

```json
{
  "user_request": "Original user message",
  "environment": {
    "os": "Windows",
    "runtime": "Python 3.11",
    "project_type": "FastAPI",
    "client": "Dataforth"  // if MSP mode
  },
  "requirements": [
    "Must use JWT tokens",
    "Must integrate with existing users table",
    "Must include refresh token support"
  ],
  "constraints": [
    "Must work on Server 2019",
    "Cannot use PowerShell 7 cmdlets"
  ],
  "assigned_agents": [
    {
      "agent": "Coding Agent",
      "started": "2026-01-15T20:30:00Z",
      "completed": "2026-01-15T20:40:00Z"
    },
    {
      "agent": "Code Review Agent",
      "started": "2026-01-15T20:40:00Z",
      "completed": "2026-01-15T20:42:00Z",
      "status": "approved"
    }
  ],
  "files_modified": [
    "api/auth.py",
    "models/user.py",
    "tests/test_auth.py"
  ],
  "dependencies_added": [
    "python-jose[cryptography]==3.3.0",
    "passlib[bcrypt]==1.7.4"
  ],
  "blockers_encountered": [],
  "outcome": "Authentication system implemented and approved",
  "production_ready": true,
  "billable": true,  // if MSP mode
  "billable_minutes": 30  // if MSP mode
}
```

## Mode-Specific Task Features

### MSP Mode
Tasks automatically linked to client context:
```python
{
  "operation": "create_task",
  "title": "Fix WINS service on D2TESTNAS",
  "client_id": "dataforth-uuid",
  "infrastructure_ids": ["d2testnas-uuid"],
  "billable_minutes": 45,
  "task_context": {
    "problem": "WINS service not responding",
    "impact": "DOS machines can't resolve NetBIOS names"
  }
}
```

When completed, automatically creates work_item:
```python
{
  "operation": "create_work_item",
  "category": "troubleshooting",
  "problem": "WINS service not responding",
  "solution": "Fixed smb.conf.overrides, restarted nmbd",
  "billable_minutes": 45,
  "linked_task_id": "task-uuid"
}
```

### Development Mode
Tasks linked to project:
```python
{
  "operation": "create_task",
  "title": "Add dark mode toggle",
  "project_id": "gururmm-uuid",
  "task_context": {
    "feature_spec": "User-requested dark mode for dashboard",
    "repository": "azcomputerguru/gururmm"
  }
}
```

### Normal Mode
Tasks not linked to client or project:
```python
{
  "operation": "create_task",
  "title": "Research Rust async patterns",
  "task_type": "research",
  "task_context": {
    "reason": "General learning, not for specific client/project"
  }
}
```

## Checklist Display Format

### Compact (During Execution)
```markdown
## Progress

- [✓] Analyze requirements (completed)
- [→] Generate code (in progress - Coding Agent)
- [ ] Review code
- [ ] Deploy to staging
```

### Detailed (On Request)
```markdown
## Task Status: Implement API Authentication

**Overall Status:** In Progress (2 of 4 complete)

### Completed ✓
1. **Design authentication schema** (5 min)
   - Schema designed with JWT approach
   - Files: docs/auth_schema.md

2. **Generate authentication code** (20 min)
   - Code generated by Coding Agent
   - Approved by Code Review Agent
   - Files: api/auth.py, models/user.py

### In Progress →
3. **Write authentication tests** (in progress)
   - Assigned to: Coding Agent
   - Started: 2 minutes ago

### Pending
4. **Deploy to staging**
   - Blocked by: Need staging environment credentials
```

## Database Schema

See Database Agent documentation for full `tasks` table schema.

Key fields:
- `id` - UUID primary key
- `parent_task_id` - For subtasks
- `title` - Task name
- `status` - pending, in_progress, blocked, completed, cancelled
- `task_type` - implementation, research, review, etc.
- `assigned_agent` - Which agent is handling it
- `task_context` - Rich JSON context
- `session_id` - Link to session
- `client_id` - Link to client (MSP mode)
- `project_id` - Link to project (Dev mode)

## Agent Interaction Pattern

### Agents Don't Manage Tasks Directly
```python
# [ERROR] WRONG - Agent updates database directly
# Inside Coding Agent:
Database.update_task(task_id, status="completed")

# ✓ CORRECT - Agent reports to orchestrator
# Inside Coding Agent:
return {
  "status": "completed",
  "outcome": "Authentication code generated",
  "files_created": ["auth.py"]
}

# Orchestrator receives agent result, then updates task
Database Agent.update_task(
  task_id=task_id,
  status="completed",
  task_context=agent_result
)
```

### Orchestrator Sequence
```python
# 1. Create task
task = Database_Agent.create_task(title="Generate auth code", ...)

# 2. Update status before launching agent
Database_Agent.update_task(task.id, status="in_progress", assigned_agent="Coding Agent")

# 3. Launch agent
result = Coding_Agent.generate_auth_code(...)

# 4. Update task with result
Database_Agent.complete_task(
  task_id=task.id,
  task_context=result
)

# 5. Show updated checklist to user
display_checklist_update(task)
```

## Benefits

### For User
- **Visibility** - Always know what's happening
- **Progress tracking** - See how far along work is
- **Context** - Understand what was done and why
- **Billability** - (MSP mode) Clear record of time spent

### For Orchestrator (Main Claude)
- **Organization** - Structured approach to complex requests
- **Memory** - Database stores context between sessions
- **Resumption** - Can pick up where left off
- **Accountability** - Clear record of what agents did

### For System
- **Learning** - Analyze patterns across tasks
- **Estimation** - Build data for complexity estimates
- **Optimization** - Identify bottlenecks
- **Quality** - Track review pass/fail rates

## Example: Complex Request

**User Request:**
> "Set up monitoring for the Dataforth NAS, alert if sync fails"

**Orchestrator Creates Tasks:**
```markdown
## Implementation Plan

I'll set up NAS monitoring in these steps:

- [ ] Research current sync system (Dataforth)
- [ ] Design monitoring approach
- [ ] Implement monitoring script
- [ ] Review monitoring code
- [ ] Test monitoring alerts
- [ ] Deploy to production
- [ ] Document for team

Starting with research...
```

**Task Breakdown in Database:**
```python
parent_task = {
  "title": "Set up NAS monitoring for Dataforth",
  "client_id": "dataforth-uuid",
  "status": "in_progress",
  "subtasks": [
    {
      "title": "Research current sync system",
      "task_type": "research",
      "assigned_agent": "Explore Agent",
      "status": "in_progress"
    },
    # ... 6 more subtasks
  ]
}
```

**As Work Progresses:**
```markdown
## Progress Update

- [✓] Research current sync system (completed - 5 min)
  - Found: PowerShell script on AD2, syncs every 15 min
  - Files: C:\Shares\test\scripts\Sync-FromNAS.ps1

- [✓] Design monitoring approach (completed - 3 min)
  - Approach: Check _SYNC_STATUS.txt age via DattoRMM
  - Alert if >30 min old or status != "OK"

- [→] Implement monitoring script (in progress - Coding Agent)
- [ ] Review monitoring code
- [ ] Test monitoring alerts
- [ ] Deploy to production
- [ ] Document for team
```

**On Completion:**
```markdown
## Implementation Complete [OK]

NAS monitoring set up for Dataforth:

**Work Summary:**
- Total time: 45 minutes (billable)
- Tasks completed: 7
- Files created: monitor-nas-sync.ps1
- Deployed to: DattoRMM component
- Alert threshold: 30 minutes

**What was built:**
[code blocks]

**Testing:**
[test results]

**Documentation:**
[docs created]
```

**Stored in Database:**
```python
# Parent task marked complete
# work_item created with billable time
# Context preserved for future reference
# Environmental insights updated if issues encountered
```

---

## Summary

**Orchestrator (main Claude) manages checklist**
- Creates tasks from user requests
- Updates status as agents report
- Provides progress visibility
- Stores context via Database Agent

**Agents report progress**
- Don't manage tasks directly
- Return results to orchestrator
- Orchestrator updates database

**Database Agent persists everything**
- All task data and context
- Links to clients/projects
- Enables cross-session continuity

**Result: Complete visibility and context preservation**