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:

# 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

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

# 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

# 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

## Task Progress

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

Step 7: All Tasks Complete

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

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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)

## Progress

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

Detailed (On Request)

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

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

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

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

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:

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

## Implementation Complete ✅

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:

# 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