claudetools/.claude/TASK_MANAGEMENT.md

Task Management System

Overview

All tasks and subtasks across all modes (MSP, Development, Normal) are tracked using Claude Code's native task management tools (TaskCreate, TaskUpdate, TaskList, TaskGet). The orchestrator (main Claude session) manages tasks, updating status as work progresses. Task data is persisted to .claude/active-tasks.json for cross-session continuity.

Native Task Integration (NEW - 2026-01-23):

• Session Layer: TaskCreate/Update/List for real-time coordination
• Persistence Layer: .claude/active-tasks.json file for cross-session recovery
• Agent Pattern: Agents report status → Main Claude updates tasks
• See: .claude/NATIVE_TASK_INTEGRATION.md for complete guide

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 .claude/active-tasks.json:

• What was requested (subject, description)
• Task status (pending, in_progress, completed)
• Which agent is working (owner field)
• Task dependencies (blocks, blockedBy)
• Timestamps (created_at, started_at, completed_at)
• Metadata (client, project, complexity)
• Cross-session persistence for recovery

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 using native tools:

// Orchestrator thinks:
// This is a complex task - break it down

// Create parent task
TaskCreate({
  subject: "Implement API authentication",
  description: "Complete JWT-based authentication system with Argon2 hashing",
  activeForm: "Implementing API authentication"
})
// Returns: Task #7

// Create subtasks with dependencies
design = TaskCreate({
  subject: "Design authentication schema",
  description: "Define users, tokens, and refresh_tokens tables",
  activeForm: "Designing auth schema"
})
// Returns: Task #8

generate = TaskCreate({
  subject: "Generate JWT authentication code",
  description: "Implement FastAPI endpoints with JWT token generation",
  activeForm: "Generating auth code",
  addBlockedBy: ["8"]  // Depends on design
})
// Returns: Task #9

review = TaskCreate({
  subject: "Review authentication code",
  description: "Code review for security and standards compliance",
  activeForm: "Reviewing auth code",
  addBlockedBy: ["9"]  // Depends on code generation
})
// Returns: Task #10

tests = TaskCreate({
  subject: "Write authentication tests",
  description: "Create pytest tests for auth flow",
  activeForm: "Writing auth tests",
  addBlockedBy: ["10"]  // Depends on review
})
// Returns: Task #11

// Persist all tasks to file
Write(".claude/active-tasks.json", tasks_data)

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 to in_progress
TaskUpdate({
  taskId: "8",  // Design task
  status: "in_progress",
  owner: "Coding Agent"
})

// Update file
Update active-tasks.json with new status

// Launch agent
Coding Agent: analyze_and_design_auth_schema(...)

Step 5: Agent Completes, Orchestrator Updates

// Agent returns design
agent_result = {
  status: "completed",
  outcome: "Schema designed with users, tokens, refresh_tokens tables",
  files_created: ["docs/auth_schema.md"]
}

// Orchestrator updates task
TaskUpdate({
  taskId: "8",
  status: "completed"
})

// Update file
Update active-tasks.json with completion

// Next task (dependency cleared automatically)
TaskUpdate({
  taskId: "9",  // Generate code task
  status: "in_progress"
})

// Update checklist shown to user via TaskList()

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

File-Based Storage

Tasks are persisted to .claude/active-tasks.json for cross-session continuity.

File Structure:

{
  "last_updated": "2026-01-23T10:30:00Z",
  "tasks": [
    {
      "id": "7",
      "subject": "Implement API authentication",
      "description": "Complete JWT-based authentication...",
      "activeForm": "Implementing API authentication",
      "status": "in_progress",
      "owner": "Coding Agent",
      "created_at": "2026-01-23T10:00:00Z",
      "started_at": "2026-01-23T10:05:00Z",
      "completed_at": null,
      "blocks": [],
      "blockedBy": [],
      "metadata": {
        "client": "Dataforth",
        "project": "ClaudeTools",
        "complexity": "moderate"
      }
    }
  ]
}

Key Fields:

• id - Task number from TaskCreate
• subject - Brief task title
• description - Detailed description
• status - pending, in_progress, completed
• owner - Which agent is working (from TaskUpdate)
• blocks/blockedBy - Task dependencies
• metadata - Client, project, complexity

Agent Interaction Pattern

Agents Don't Manage Tasks Directly

// [ERROR] WRONG - Agent uses TaskUpdate directly
// Inside Coding Agent:
TaskUpdate({ taskId: "7", 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
TaskUpdate({
  taskId: "7",
  status: "completed"
})

// Update file
Update active-tasks.json with completion data

Orchestrator Sequence

// 1. Create task
task_id = TaskCreate({
  subject: "Generate auth code",
  description: "Create JWT authentication endpoints",
  activeForm: "Generating auth code"
})
// Returns: "7"

// 2. Update status before launching agent
TaskUpdate({
  taskId: "7",
  status: "in_progress",
  owner: "Coding Agent"
})
Update active-tasks.json

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

// 4. Update task with result
TaskUpdate({
  taskId: "7",
  status: "completed"
})
Update active-tasks.json with outcome

// 5. Show updated checklist to user
TaskList()  // Shows current state

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 [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 File:

// Parent task marked complete in active-tasks.json
// Task removed from active list (or status updated to completed)
// Context preserved for session logs
// Can be archived to tasks/archive/ directory

---

Cross-Session Recovery

When a new session starts:

1. Check for active tasks file

   if (file_exists(".claude/active-tasks.json")) {
     tasks_data = read_json(".claude/active-tasks.json")
   }
   

2. Filter incomplete tasks

   incomplete_tasks = tasks_data.tasks.filter(t => t.status !== "completed")
   

3. Recreate native tasks

   for (task of incomplete_tasks) {
     new_id = TaskCreate({
       subject: task.subject,
       description: task.description,
       activeForm: task.activeForm
     })
     // Map old task.id → new_id for dependencies
   }
   

4. Restore dependencies

   for (task of incomplete_tasks) {
     if (task.blockedBy.length > 0) {
       TaskUpdate({
         taskId: mapped_id(task.id),
         addBlockedBy: task.blockedBy.map(mapped_id)
       })
     }
   }
   

5. Show recovered state

   TaskList()
   // User sees: "Continuing from previous session: 3 tasks in progress"
   

---

Summary

Orchestrator (main Claude) manages tasks

• Creates tasks using TaskCreate for complex work
• Updates status as agents report using TaskUpdate
• Provides progress visibility via TaskList
• Persists to .claude/active-tasks.json file

Agents report progress

• Don't manage tasks directly
• Return results to orchestrator
• Orchestrator updates tasks and file

File-based persistence

• All active task data stored in JSON
• Cross-session recovery on startup
• Human-readable and editable

Result: Complete visibility and context preservation