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:**
```javascript
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:**
```javascript
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:**
```javascript
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:**
```javascript
// 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:**
```javascript
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:**
```javascript
TaskGet({
  taskId: "7"
})
```

**Returns:** Complete task object with all metadata

---

## Workflow Patterns

### Pattern 1: Simple Multi-Step Task

```javascript
// 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

```javascript
// 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

```javascript
// 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
```json
{
  "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:**
```javascript
// 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:**
```javascript
// 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)

```markdown
## 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
```javascript
TaskCreate({
  subject: "Task title",
  description: "Details",
  activeForm: "Doing task"
})
```

### Start Task
```javascript
TaskUpdate({
  taskId: "7",
  status: "in_progress",
  owner: "Agent Name"
})
```

### Complete Task
```javascript
TaskUpdate({
  taskId: "7",
  status: "completed"
})
```

### Add Dependency
```javascript
TaskUpdate({
  taskId: "8",
  addBlockedBy: ["7"]  // Task 8 blocked by task 7
})
```

### View All Tasks
```javascript
TaskList()
```

### Get Task Details
```javascript
TaskGet({ taskId: "7" })
```

---

## Edge Cases

### Corrupted JSON File
```javascript
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
```javascript
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

```javascript
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

```javascript
// 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