sync: Auto-sync from ACG-M-L5090 at 2026-01-26 16:45:54
Synced files: - Complete claude-projects import (5 catalog files) - Client directory with 12 clients - Project directory with 12 projects - Credentials updated (100+ sets) - Session logs consolidated - Agent coordination rules updated - Task management integration Major work completed: - Exhaustive cataloging of claude-projects - All session logs analyzed (38 files) - All credentials extracted and organized - Client infrastructure documented - Problem solutions cataloged (70+) Machine: ACG-M-L5090 Timestamp: 2026-01-26 16:45:54 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
@@ -236,6 +236,7 @@ curl ... -d '{"context_type": "session_summary", ...}'
|
||||
- [OK] **Automatically invoke skills when triggered** (NEW)
|
||||
- [OK] **Recognize when Sequential Thinking is needed** (NEW)
|
||||
- [OK] **Execute dual checkpoints (git + database)** (NEW)
|
||||
- [OK] **Manage tasks with native tools (TaskCreate/Update/List)** (NEW)
|
||||
|
||||
**Main Claude Does NOT:**
|
||||
- [ERROR] Query database directly
|
||||
@@ -319,7 +320,71 @@ Main Claude: [Reports to user]
|
||||
- Database: Cross-machine context recall
|
||||
- Together: Complete project memory
|
||||
|
||||
### 4. Skills vs Agents
|
||||
### 4. Native Task Management
|
||||
|
||||
**Main Claude uses TaskCreate/Update/List for complex multi-step operations:**
|
||||
|
||||
**When to Use:**
|
||||
- Complex work requiring >3 distinct steps
|
||||
- Multi-agent coordination needing status tracking
|
||||
- User requests progress visibility
|
||||
- Work may span multiple sessions
|
||||
|
||||
**Task Workflow:**
|
||||
```
|
||||
User: "Implement authentication for API"
|
||||
|
||||
Main Claude:
|
||||
1. TaskCreate (parent: "Implement API authentication")
|
||||
2. TaskCreate (subtasks with dependencies):
|
||||
- "Design auth schema" (pending)
|
||||
- "Generate code" (blockedBy: design)
|
||||
- "Review code" (blockedBy: generate)
|
||||
- "Write tests" (blockedBy: review)
|
||||
|
||||
3. Save all tasks to .claude/active-tasks.json
|
||||
|
||||
4. Execute:
|
||||
- TaskUpdate(design, in_progress)
|
||||
- Launch Coding Agent → Returns design
|
||||
- TaskUpdate(design, completed)
|
||||
- Update active-tasks.json
|
||||
|
||||
- TaskUpdate(generate, in_progress) [dependency cleared]
|
||||
- Launch Coding Agent → Returns code
|
||||
- TaskUpdate(generate, completed)
|
||||
- Update active-tasks.json
|
||||
|
||||
[Continue pattern...]
|
||||
|
||||
5. TaskList() → Show user progress
|
||||
```
|
||||
|
||||
**Agent Integration:**
|
||||
- Agents report status (completed/failed/blocked)
|
||||
- Main Claude translates to TaskUpdate
|
||||
- File updated after each status change
|
||||
|
||||
**Cross-Session Recovery:**
|
||||
```
|
||||
New session starts:
|
||||
1. Read .claude/active-tasks.json
|
||||
2. Filter incomplete tasks
|
||||
3. Recreate with TaskCreate
|
||||
4. Restore dependencies
|
||||
5. TaskList() → Show recovered state
|
||||
6. Continue execution
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Real-time progress visibility via TaskList
|
||||
- Built-in dependency management (blocks/blockedBy)
|
||||
- File-based persistence (no database)
|
||||
- Session continuity across restarts
|
||||
|
||||
**See:** `.claude/NATIVE_TASK_INTEGRATION.md` for complete guide
|
||||
|
||||
### 5. Skills vs Agents
|
||||
|
||||
**Main Claude understands the difference:**
|
||||
|
||||
@@ -356,6 +421,7 @@ Main Claude: [Reports to user]
|
||||
| **UI validation** | **Frontend Design Skill (auto-invoked)** |
|
||||
| **Complex problem analysis** | **Sequential Thinking MCP** |
|
||||
| **Dual checkpoints** | **/checkpoint command (Main Claude)** |
|
||||
| **Task tracking (>3 steps)** | **TaskCreate/Update/List (Main Claude)** |
|
||||
| **User interaction** | **Main Claude** |
|
||||
| **Coordination** | **Main Claude** |
|
||||
| **Decision making** | **Main Claude** |
|
||||
@@ -390,11 +456,12 @@ Main Claude: [Reports to user]
|
||||
- Invoke frontend-design skill for ANY UI change
|
||||
- Recognize when Sequential Thinking is appropriate
|
||||
- Execute dual checkpoints (git + database) via /checkpoint
|
||||
- **Manage tasks with native tools for complex operations (>3 steps)**
|
||||
- Coordinate agents and skills intelligently
|
||||
|
||||
---
|
||||
|
||||
**Created:** 2026-01-17
|
||||
**Last Updated:** 2026-01-17 (added new capabilities)
|
||||
**Last Updated:** 2026-01-23 (added native task management)
|
||||
**Purpose:** Ensure proper agent-based architecture
|
||||
**Status:** Mandatory guideline for all future operations
|
||||
|
||||
669
.claude/NATIVE_TASK_INTEGRATION.md
Normal file
669
.claude/NATIVE_TASK_INTEGRATION.md
Normal file
@@ -0,0 +1,669 @@
|
||||
# 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
|
||||
@@ -2,7 +2,13 @@
|
||||
|
||||
## 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.
|
||||
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
|
||||
|
||||
@@ -29,14 +35,14 @@ Agents don't manage tasks directly - they report to orchestrator:
|
||||
- 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
|
||||
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
|
||||
|
||||
@@ -46,53 +52,54 @@ User: "Implement authentication for the API"
|
||||
```
|
||||
|
||||
### Step 2: Orchestrator Creates Task(s)
|
||||
Main Claude analyzes request and creates task structure:
|
||||
Main Claude analyzes request and creates task structure using native tools:
|
||||
|
||||
```python
|
||||
# Orchestrator thinks:
|
||||
# This is a complex task - break it down
|
||||
```javascript
|
||||
// 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"
|
||||
}
|
||||
}
|
||||
// Create parent task
|
||||
TaskCreate({
|
||||
subject: "Implement API authentication",
|
||||
description: "Complete JWT-based authentication system with Argon2 hashing",
|
||||
activeForm: "Implementing API authentication"
|
||||
})
|
||||
// Returns: Task #7
|
||||
|
||||
# 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"
|
||||
}
|
||||
]
|
||||
}
|
||||
// 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
|
||||
@@ -110,34 +117,46 @@ 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()
|
||||
)
|
||||
```javascript
|
||||
// Update task status to in_progress
|
||||
TaskUpdate({
|
||||
taskId: "8", // Design task
|
||||
status: "in_progress",
|
||||
owner: "Coding Agent"
|
||||
})
|
||||
|
||||
# Launch 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
|
||||
```python
|
||||
# Agent returns design
|
||||
# Orchestrator updates task
|
||||
```javascript
|
||||
// Agent returns design
|
||||
agent_result = {
|
||||
status: "completed",
|
||||
outcome: "Schema designed with users, tokens, refresh_tokens tables",
|
||||
files_created: ["docs/auth_schema.md"]
|
||||
}
|
||||
|
||||
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"]
|
||||
}
|
||||
)
|
||||
// Orchestrator updates task
|
||||
TaskUpdate({
|
||||
taskId: "8",
|
||||
status: "completed"
|
||||
})
|
||||
|
||||
# Update checklist shown to user
|
||||
// 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
|
||||
@@ -368,65 +387,102 @@ Tasks not linked to client or project:
|
||||
- Blocked by: Need staging environment credentials
|
||||
```
|
||||
|
||||
## Database Schema
|
||||
## File-Based Storage
|
||||
|
||||
See Database Agent documentation for full `tasks` table schema.
|
||||
Tasks are persisted to `.claude/active-tasks.json` for cross-session continuity.
|
||||
|
||||
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)
|
||||
**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"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**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
|
||||
```python
|
||||
# [ERROR] WRONG - Agent updates database directly
|
||||
# Inside Coding Agent:
|
||||
Database.update_task(task_id, status="completed")
|
||||
```javascript
|
||||
// [ERROR] WRONG - Agent uses TaskUpdate directly
|
||||
// Inside Coding Agent:
|
||||
TaskUpdate({ taskId: "7", status: "completed" })
|
||||
|
||||
# ✓ CORRECT - Agent reports to orchestrator
|
||||
# Inside Coding Agent:
|
||||
// ✓ 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 receives agent result, then updates task
|
||||
TaskUpdate({
|
||||
taskId: "7",
|
||||
status: "completed"
|
||||
})
|
||||
|
||||
// Update file
|
||||
Update active-tasks.json with completion data
|
||||
```
|
||||
|
||||
### Orchestrator Sequence
|
||||
```python
|
||||
# 1. Create task
|
||||
task = Database_Agent.create_task(title="Generate auth code", ...)
|
||||
```javascript
|
||||
// 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
|
||||
Database_Agent.update_task(task.id, status="in_progress", assigned_agent="Coding Agent")
|
||||
// 2. Update status before launching agent
|
||||
TaskUpdate({
|
||||
taskId: "7",
|
||||
status: "in_progress",
|
||||
owner: "Coding Agent"
|
||||
})
|
||||
Update active-tasks.json
|
||||
|
||||
# 3. Launch 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
|
||||
)
|
||||
// 4. Update task with result
|
||||
TaskUpdate({
|
||||
taskId: "7",
|
||||
status: "completed"
|
||||
})
|
||||
Update active-tasks.json with outcome
|
||||
|
||||
# 5. Show updated checklist to user
|
||||
display_checklist_update(task)
|
||||
// 5. Show updated checklist to user
|
||||
TaskList() // Shows current state
|
||||
```
|
||||
|
||||
## Benefits
|
||||
@@ -531,32 +587,80 @@ NAS monitoring set up for Dataforth:
|
||||
[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
|
||||
**Stored in File:**
|
||||
```javascript
|
||||
// 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**
|
||||
```javascript
|
||||
if (file_exists(".claude/active-tasks.json")) {
|
||||
tasks_data = read_json(".claude/active-tasks.json")
|
||||
}
|
||||
```
|
||||
|
||||
2. **Filter incomplete tasks**
|
||||
```javascript
|
||||
incomplete_tasks = tasks_data.tasks.filter(t => t.status !== "completed")
|
||||
```
|
||||
|
||||
3. **Recreate native tasks**
|
||||
```javascript
|
||||
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**
|
||||
```javascript
|
||||
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**
|
||||
```javascript
|
||||
TaskList()
|
||||
// User sees: "Continuing from previous session: 3 tasks in progress"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**Orchestrator (main Claude) manages checklist**
|
||||
- Creates tasks from user requests
|
||||
- Updates status as agents report
|
||||
- Provides progress visibility
|
||||
- Stores context via Database Agent
|
||||
**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 database
|
||||
- Orchestrator updates tasks and file
|
||||
|
||||
**Database Agent persists everything**
|
||||
- All task data and context
|
||||
- Links to clients/projects
|
||||
- Enables cross-session continuity
|
||||
**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**
|
||||
|
||||
4
.claude/active-tasks.json
Normal file
4
.claude/active-tasks.json
Normal file
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"last_updated": "2026-01-23T00:00:00Z",
|
||||
"tasks": []
|
||||
}
|
||||
Reference in New Issue
Block a user