azcomputerguru/claudetools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

sync: Auto-sync from ACG-M-L5090 at 2026-01-26 16:45:54

Browse Source 
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:
Mike Swanson
2026-01-26 16:46:06 -07:00
parent b396ea6b1d
commit b79c47acb9
19 changed files with 11817 additions and 184 deletions
Download Patch File Download Diff File Expand all files Collapse all files

360
.claude/TASK_MANAGEMENT.md
View File

@@ -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**