Initial commit: ClaudeTools system foundation
Complete architecture for multi-mode Claude operation: - MSP Mode (client work tracking) - Development Mode (project management) - Normal Mode (general research) Agents created: - Coding Agent (perfectionist programmer) - Code Review Agent (quality gatekeeper) - Database Agent (data custodian) - Gitea Agent (version control) - Backup Agent (data protection) Workflows documented: - CODE_WORKFLOW.md (mandatory review process) - TASK_MANAGEMENT.md (checklist system) - FILE_ORGANIZATION.md (hybrid storage) - MSP-MODE-SPEC.md (complete architecture, 36 tables) Commands: - /sync (pull latest from Gitea) Database schema: 36 tables for comprehensive context storage File organization: clients/, projects/, normal/, backups/ Backup strategy: Daily/weekly/monthly with retention Status: Architecture complete, ready for implementation Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
562
.claude/TASK_MANAGEMENT.md
Normal file
562
.claude/TASK_MANAGEMENT.md
Normal file
@@ -0,0 +1,562 @@
|
||||
# Task Management System
|
||||
|
||||
## 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.
|
||||
|
||||
## 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 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
|
||||
|
||||
## 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:
|
||||
|
||||
```python
|
||||
# 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"
|
||||
}
|
||||
}
|
||||
|
||||
# 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"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: Orchestrator Shows Checklist to User
|
||||
```markdown
|
||||
## 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
|
||||
```python
|
||||
# Update task status
|
||||
Database Agent: update_task(
|
||||
task_id="design-subtask-uuid",
|
||||
status="in_progress",
|
||||
assigned_agent="Coding Agent",
|
||||
started_at=now()
|
||||
)
|
||||
|
||||
# Launch agent
|
||||
Coding Agent: analyze_and_design_auth_schema(...)
|
||||
```
|
||||
|
||||
### Step 5: Agent Completes, Orchestrator Updates
|
||||
```python
|
||||
# Agent returns design
|
||||
# Orchestrator updates task
|
||||
|
||||
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"]
|
||||
}
|
||||
)
|
||||
|
||||
# Update checklist shown to user
|
||||
```
|
||||
|
||||
### Step 6: Progress Visibility
|
||||
```markdown
|
||||
## Task Progress
|
||||
|
||||
- [✓] Design authentication schema (completed)
|
||||
- [→] Generate code for JWT authentication (in progress)
|
||||
- [ ] Review authentication code
|
||||
- [ ] Write authentication tests
|
||||
```
|
||||
|
||||
### Step 7: All Tasks Complete
|
||||
```python
|
||||
# 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:
|
||||
|
||||
```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:
|
||||
```python
|
||||
{
|
||||
"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:
|
||||
```python
|
||||
{
|
||||
"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:
|
||||
```python
|
||||
{
|
||||
"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:
|
||||
```python
|
||||
{
|
||||
"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)
|
||||
```markdown
|
||||
## Progress
|
||||
|
||||
- [✓] Analyze requirements (completed)
|
||||
- [→] Generate code (in progress - Coding Agent)
|
||||
- [ ] Review code
|
||||
- [ ] Deploy to staging
|
||||
```
|
||||
|
||||
### Detailed (On Request)
|
||||
```markdown
|
||||
## 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
|
||||
```
|
||||
|
||||
## Database Schema
|
||||
|
||||
See Database Agent documentation for full `tasks` table schema.
|
||||
|
||||
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)
|
||||
|
||||
## Agent Interaction Pattern
|
||||
|
||||
### Agents Don't Manage Tasks Directly
|
||||
```python
|
||||
# ❌ WRONG - Agent updates database directly
|
||||
# Inside Coding Agent:
|
||||
Database.update_task(task_id, 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
|
||||
Database Agent.update_task(
|
||||
task_id=task_id,
|
||||
status="completed",
|
||||
task_context=agent_result
|
||||
)
|
||||
```
|
||||
|
||||
### Orchestrator Sequence
|
||||
```python
|
||||
# 1. Create task
|
||||
task = Database_Agent.create_task(title="Generate auth code", ...)
|
||||
|
||||
# 2. Update status before launching agent
|
||||
Database_Agent.update_task(task.id, status="in_progress", assigned_agent="Coding 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
|
||||
)
|
||||
|
||||
# 5. Show updated checklist to user
|
||||
display_checklist_update(task)
|
||||
```
|
||||
|
||||
## 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:**
|
||||
```markdown
|
||||
## 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:**
|
||||
```python
|
||||
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:**
|
||||
```markdown
|
||||
## 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:**
|
||||
```markdown
|
||||
## Implementation Complete ✅
|
||||
|
||||
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 Database:**
|
||||
```python
|
||||
# Parent task marked complete
|
||||
# work_item created with billable time
|
||||
# Context preserved for future reference
|
||||
# Environmental insights updated if issues encountered
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**Orchestrator (main Claude) manages checklist**
|
||||
- Creates tasks from user requests
|
||||
- Updates status as agents report
|
||||
- Provides progress visibility
|
||||
- Stores context via Database Agent
|
||||
|
||||
**Agents report progress**
|
||||
- Don't manage tasks directly
|
||||
- Return results to orchestrator
|
||||
- Orchestrator updates database
|
||||
|
||||
**Database Agent persists everything**
|
||||
- All task data and context
|
||||
- Links to clients/projects
|
||||
- Enables cross-session continuity
|
||||
|
||||
**Result: Complete visibility and context preservation**
|
||||
Reference in New Issue
Block a user