claudetools/.claude/NATIVE_TASK_INTEGRATION.md

Native Task Integration Guide

Last Updated: 2026-01-23 Purpose: Guide for using Claude Code native task management tools in ClaudeTools workflow Status: Active

---

Overview

ClaudeTools integrates Claude Code's native task management tools (TaskCreate, TaskUpdate, TaskList, TaskGet) to provide structured task tracking during complex multi-step operations. Tasks are persisted to .claude/active-tasks.json for cross-session continuity.

Key Principles:

• Native tools for session-level coordination and real-time visibility
• File-based persistence for cross-session recovery
• Main Claude (coordinator) manages tasks
• Agents report status, don't manage tasks directly
• ASCII markers only (no emojis)

---

When to Use Native Tasks

Use TaskCreate For:

• Complex multi-step operations (>3 steps)
• Agent coordination requiring status tracking
• User-requested progress visibility
• Dependency management between tasks
• Cross-session work that may span multiple days

Continue Using TodoWrite For:

• Session summaries (Documentation Squire)
• Simple checklists (<3 items, trivial tasks)
• Documentation in session logs
• Backward compatibility with existing workflows

Quick Decision Rule:

If work involves >3 steps OR multiple agents → Use TaskCreate
If work is simple/quick OR for documentation → Use TodoWrite

---

Core Tools

TaskCreate

Creates a new task with structured metadata.

Parameters:

TaskCreate({
  subject: "Brief task title (imperative form)",
  description: "Detailed description of what needs to be done",
  activeForm: "Present continuous form (e.g., 'Implementing feature')"
})

Returns: Task ID for use in TaskUpdate/TaskGet

Example:

TaskCreate({
  subject: "Implement API authentication",
  description: "Complete JWT-based authentication with Argon2 password hashing, refresh tokens, and role-based access control",
  activeForm: "Implementing API authentication"
})
// Returns: Task #7

TaskUpdate

Updates task status, ownership, or dependencies.

Parameters:

TaskUpdate({
  taskId: "7",  // Task number from TaskCreate
  status: "in_progress",  // pending, in_progress, completed
  owner: "Coding Agent",  // Optional: which agent is working
  addBlockedBy: ["5", "6"],  // Optional: dependency task IDs
  addBlocks: ["8"]  // Optional: tasks that depend on this
})

Status Workflow:

pending → in_progress → completed

Example:

// Mark task as started
TaskUpdate({
  taskId: "7",
  status: "in_progress",
  owner: "Coding Agent"
})

// Mark task as complete
TaskUpdate({
  taskId: "7",
  status: "completed"
})

TaskList

Retrieves all active tasks with status.

Parameters: None

Returns: Summary of all tasks with ID, status, subject, owner, blockers

Example:

TaskList()

// Returns:
// #7 [in_progress] Implement API authentication (owner: Coding Agent)
// #8 [pending] Review authentication code (blockedBy: #7)
// #9 [pending] Write authentication tests (blockedBy: #8)

TaskGet

Retrieves full details of a specific task.

Parameters:

TaskGet({
  taskId: "7"
})

Returns: Complete task object with all metadata

---

Workflow Patterns

Pattern 1: Simple Multi-Step Task

// User request
User: "Add dark mode toggle to dashboard"

// Main Claude creates tasks
TaskCreate({
  subject: "Add dark mode toggle",
  description: "Implement toggle button with CSS variables and state persistence",
  activeForm: "Adding dark mode toggle"
})
// Returns: #10

TaskCreate({
  subject: "Design dark mode colors",
  description: "Define color scheme and CSS variables",
  activeForm: "Designing dark mode colors"
})
// Returns: #11

TaskCreate({
  subject: "Implement toggle component",
  description: "Create React component with state management",
  activeForm: "Implementing toggle component",
  addBlockedBy: ["11"]  // Depends on design
})
// Returns: #12

// Execute
TaskUpdate({ taskId: "11", status: "in_progress" })
// ... work happens ...
TaskUpdate({ taskId: "11", status: "completed" })

TaskUpdate({ taskId: "12", status: "in_progress" })  // Dependency cleared
// ... work happens ...
TaskUpdate({ taskId: "12", status: "completed" })

// User sees progress via TaskList

Pattern 2: Multi-Agent Coordination

// User request
User: "Implement user profile endpoint"

// Main Claude creates task hierarchy
parent_task = TaskCreate({
  subject: "Implement user profile endpoint",
  description: "Complete FastAPI endpoint with schema, code, review, tests",
  activeForm: "Implementing profile endpoint"
})
// Returns: #13

// Subtasks with dependencies
design = TaskCreate({
  subject: "Design endpoint schema",
  description: "Define Pydantic models and validation rules",
  activeForm: "Designing endpoint schema"
})
// Returns: #14

code = TaskCreate({
  subject: "Generate endpoint code",
  description: "Write FastAPI route handler",
  activeForm: "Generating endpoint code",
  addBlockedBy: ["14"]
})
// Returns: #15

review = TaskCreate({
  subject: "Review code quality",
  description: "Code review with security and standards check",
  activeForm: "Reviewing code",
  addBlockedBy: ["15"]
})
// Returns: #16

tests = TaskCreate({
  subject: "Write endpoint tests",
  description: "Create pytest tests for all scenarios",
  activeForm: "Writing tests",
  addBlockedBy: ["16"]
})
// Returns: #17

// Execute with agent coordination
TaskUpdate({ taskId: "14", status: "in_progress", owner: "Coding Agent" })
// Launch Coding Agent → Returns schema design
TaskUpdate({ taskId: "14", status: "completed" })

TaskUpdate({ taskId: "15", status: "in_progress", owner: "Coding Agent" })
// Launch Coding Agent → Returns code
TaskUpdate({ taskId: "15", status: "completed" })

TaskUpdate({ taskId: "16", status: "in_progress", owner: "Code Review Agent" })
// Launch Code Review Agent → Returns approval
TaskUpdate({ taskId: "16", status: "completed" })

TaskUpdate({ taskId: "17", status: "in_progress", owner: "Coding Agent" })
// Launch Coding Agent → Returns tests
TaskUpdate({ taskId: "17", status: "completed" })

// All subtasks done, mark parent complete
TaskUpdate({ taskId: "13", status: "completed" })

Pattern 3: Blocked Task

// Task encounters blocker
TaskUpdate({
  taskId: "20",
  status: "blocked"
})

// Report to user
"[ERROR] Task blocked: Need staging environment credentials
 Would you like to provide credentials or skip deployment?"

// When blocker resolved
TaskUpdate({
  taskId: "20",
  status: "in_progress"
})

---

File-Based Persistence

Storage Location

.claude/active-tasks.json

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"
      }
    }
  ]
}

File Update Triggers

TaskCreate:

• Append new task object to tasks array
• Update last_updated timestamp
• Save file

TaskUpdate:

• Find task by ID
• Update status, owner, timestamps
• Update dependencies (blocks/blockedBy)
• Update last_updated timestamp
• Save file

Task Completion:

• Option 1: Update status to "completed" (keep in file)
• Option 2: Remove from active-tasks.json (archive elsewhere)

Cross-Session Recovery

Session Start Workflow:

1. Check if .claude/active-tasks.json exists
2. If exists: Read file content
3. Parse JSON and filter incomplete tasks (status != "completed")
4. For each incomplete task:
   • Call TaskCreate with original subject/description/activeForm
   • Map old ID to new native ID
   • Restore dependencies using mapped IDs
5. Call TaskList to show recovered state
6. Continue execution

Example Recovery:

// Session ended yesterday with 2 incomplete tasks

// New session starts
if (file_exists(".claude/active-tasks.json")) {
  tasks = read_json(".claude/active-tasks.json")
  incomplete = tasks.filter(t => t.status !== "completed")

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

  // Restore dependencies after all tasks recreated
  for (task of incomplete) {
    if (task.blockedBy.length > 0) {
      TaskUpdate({
        taskId: mapped_id(task.id),
        addBlockedBy: task.blockedBy.map(mapped_id)
      })
    }
  }
}

// Show user recovered state
TaskList()
"Continuing from previous session:
 [IN PROGRESS] Design endpoint schema
 [PENDING] Generate endpoint code (blocked by design)
 [PENDING] Review code (blocked by generate)"

---

Agent Integration

Agents DO NOT Use Task Tools Directly

Agents report status to Main Claude, who updates tasks.

Agent Workflow:

// Agent receives task context
function execute_work(context) {
  // 1. Perform specialized work
  result = do_specialized_work(context)

  // 2. Return structured status to Main Claude
  return {
    status: "completed",  // or "failed", "blocked"
    outcome: "What was accomplished",
    files_modified: ["file1.py", "file2.py"],
    blockers: null,  // or array of blocker descriptions
    next_steps: ["Code review required"]
  }
}

// Main Claude receives result
agent_result = Coding_Agent.execute_work(context)

// Main Claude updates task
if (agent_result.status === "completed") {
  TaskUpdate({ taskId: "7", status: "completed" })
} else if (agent_result.status === "blocked") {
  TaskUpdate({ taskId: "7", status: "blocked" })
  // Report blocker to user
}

Agent Status Translation

Agent Returns:

• "completed" → TaskUpdate(status: "completed")
• "failed" → TaskUpdate(status: "blocked") + report error
• "blocked" → TaskUpdate(status: "blocked") + report blocker
• "in_progress" → TaskUpdate(status: "in_progress")

---

User-Facing Output Format

Progress Display (ASCII Markers Only)

## Progress

- [SUCCESS] Design endpoint schema - completed
- [IN PROGRESS] Generate endpoint code - Coding Agent working
- [PENDING] Review code - blocked by code generation
- [PENDING] Write tests - blocked by code review

ASCII Marker Reference:

• [OK] - General success/confirmation
• [SUCCESS] - Task completed successfully
• [IN PROGRESS] - Task currently being worked on
• [PENDING] - Task waiting to start
• [ERROR] - Task failed or blocked
• [WARNING] - Caution/potential issue

Never use emojis - causes encoding issues, violates coding guidelines

---

Main Claude Responsibilities

When Creating Tasks:

1. Analyze user request for complexity (>3 steps?)
2. Break down into logical subtasks
3. Use TaskCreate for each task
4. Set up dependencies (blockedBy) where appropriate
5. Write all tasks to .claude/active-tasks.json
6. Show task plan to user

When Executing Tasks:

1. TaskUpdate(status: in_progress) BEFORE launching agent
2. Update active-tasks.json file
3. Launch specialized agent with context
4. Receive agent status report
5. TaskUpdate(status: completed/blocked) based on result
6. Update active-tasks.json file
7. Continue to next unblocked task

When Reporting Progress:

1. TaskList() to get current state
2. Translate to user-friendly format with ASCII markers
3. Show: completed, in-progress, pending, blocked
4. Provide context (which agent, what blockers)

---

Quick Reference

Create Task

TaskCreate({
  subject: "Task title",
  description: "Details",
  activeForm: "Doing task"
})

Start Task

TaskUpdate({
  taskId: "7",
  status: "in_progress",
  owner: "Agent Name"
})

Complete Task

TaskUpdate({
  taskId: "7",
  status: "completed"
})

Add Dependency

TaskUpdate({
  taskId: "8",
  addBlockedBy: ["7"]  // Task 8 blocked by task 7
})

View All Tasks

TaskList()

Get Task Details

TaskGet({ taskId: "7" })

---

Edge Cases

Corrupted JSON File

try {
  tasks = read_json(".claude/active-tasks.json")
} catch (error) {
  // File corrupted, start fresh
  tasks = {
    last_updated: now(),
    tasks: []
  }
  write_json(".claude/active-tasks.json", tasks)
}

Missing File

if (!file_exists(".claude/active-tasks.json")) {
  // Create new file on first TaskCreate
  write_json(".claude/active-tasks.json", {
    last_updated: now(),
    tasks: []
  })
}

Task ID Mapping Issues

• Old session task IDs don't match new native IDs
• Solution: Maintain mapping table during recovery
• Map old_id → new_id when recreating tasks
• Use mapping when restoring dependencies

---

Examples

Example 1: Add New Feature

User: "Add password reset functionality"

// Create task structure
main = TaskCreate({
  subject: "Add password reset functionality",
  description: "Email-based password reset with token expiration",
  activeForm: "Adding password reset"
})

design = TaskCreate({
  subject: "Design reset token system",
  description: "Define token generation, storage, and validation",
  activeForm: "Designing reset tokens"
})

backend = TaskCreate({
  subject: "Implement backend endpoints",
  description: "Create /forgot-password and /reset-password endpoints",
  activeForm: "Implementing backend",
  addBlockedBy: [design.id]
})

email = TaskCreate({
  subject: "Create password reset email template",
  description: "Design HTML email with reset link",
  activeForm: "Creating email template",
  addBlockedBy: [design.id]
})

tests = TaskCreate({
  subject: "Write password reset tests",
  description: "Test token generation, expiration, and reset flow",
  activeForm: "Writing tests",
  addBlockedBy: [backend.id, email.id]
})

// Execute
TaskUpdate({ taskId: design.id, status: "in_progress" })
// ... Coding Agent designs system ...
TaskUpdate({ taskId: design.id, status: "completed" })

TaskUpdate({ taskId: backend.id, status: "in_progress" })
TaskUpdate({ taskId: email.id, status: "in_progress" })
// ... Both agents work in parallel ...
TaskUpdate({ taskId: backend.id, status: "completed" })
TaskUpdate({ taskId: email.id, status: "completed" })

TaskUpdate({ taskId: tests.id, status: "in_progress" })
// ... Testing Agent writes tests ...
TaskUpdate({ taskId: tests.id, status: "completed" })

TaskUpdate({ taskId: main.id, status: "completed" })

// User sees: "[SUCCESS] Password reset functionality added"

Example 2: Cross-Session Work

// Monday 4pm - Session ends mid-work
TaskList()
// #50 [completed] Design user dashboard
// #51 [in_progress] Implement dashboard components
// #52 [pending] Review dashboard code (blockedBy: #51)
// #53 [pending] Write dashboard tests (blockedBy: #52)

// Tuesday 9am - New session
// Main Claude auto-recovers tasks from file
tasks_recovered = load_and_recreate_tasks()

TaskList()
// #1 [in_progress] Implement dashboard components (recovered)
// #2 [pending] Review dashboard code (recovered, blocked by #1)
// #3 [pending] Write dashboard tests (recovered, blocked by #2)

User sees: "Continuing from yesterday: Dashboard implementation in progress"

// Continue work
TaskUpdate({ taskId: "1", status: "completed" })
TaskUpdate({ taskId: "2", status: "in_progress" })
// ... etc

---

Troubleshooting

Problem: Tasks not persisting between sessions

Solution: Check that .claude/active-tasks.json is being written after each TaskCreate/TaskUpdate

Problem: Dependency chains broken after recovery

Solution: Ensure ID mapping is maintained during recovery and dependencies are restored correctly

Problem: File getting too large

Solution: Archive completed tasks periodically, keep only active/pending tasks in file

Problem: Circular dependencies

Solution: Validate dependency chains before creating, ensure no task blocks itself directly or indirectly

---

Related Documentation

• .claude/directives.md - Main Claude identity and task management rules
• .claude/AGENT_COORDINATION_RULES.md - Agent delegation patterns
• .claude/TASK_MANAGEMENT.md - Task management system overview
• .claude/agents/documentation-squire.md - TodoWrite usage for documentation

---

Version: 1.0 Created: 2026-01-23 Purpose: Enable structured task tracking in ClaudeTools workflow Status: Active