trax/scripts/README_taskmaster_tracker.md

Taskmaster Task Tracker

Automatically updates Taskmaster tasks with datetime stamps whenever they're created or status changed. This tool monitors the tasks.json file and adds timestamps to track task lifecycle events.

Features

• Automatic Timestamping: Adds timestamps for task creation and status changes
• File Monitoring: Watches for changes in the tasks.json file
• Backup System: Creates backups before making changes
• Logging: Comprehensive logging to track all activities
• Safe Operation: Only adds timestamps, never modifies existing data

Timestamp Fields Added

The tracker adds the following timestamp fields to tasks:

• created_at: ISO 8601 timestamp when the task was first detected
• updated_at: ISO 8601 timestamp when the task was last modified
• status_changed_to_X: ISO 8601 timestamp when status changed to X (e.g., status_changed_to_done)

Usage

Quick Start

# Run once to process current tasks
./scripts/tm_tracker.sh --once

# Watch for changes continuously (5-second interval)
./scripts/tm_tracker.sh --watch

# Watch with custom interval (10 seconds)
./scripts/tm_tracker.sh --watch --interval 10

Python Script Direct Usage

# Run once
python scripts/taskmaster_tracker.py

# Watch continuously
python scripts/taskmaster_tracker.py --watch

# Watch with custom interval
python scripts/taskmaster_tracker.py --watch --interval 10

Files and Directories

• scripts/taskmaster_tracker.py: Main Python script
• scripts/tm_tracker.sh: Shell wrapper script
• .taskmaster/backups/: Directory containing task backups
• logs/taskmaster_tracker.log: Log file with all tracker activities

How It Works

1. File Monitoring: Uses MD5 hashing to detect changes in tasks.json
2. Task Detection: Compares current tasks with previously known tasks
3. Timestamp Addition: Adds appropriate timestamps for new tasks and status changes
4. Backup Creation: Creates timestamped backups before making changes
5. Logging: Logs all activities for debugging and audit purposes

Example Output

When a new task is created:

{
  "id": 11,
  "title": "New Task",
  "status": "pending",
  "created_at": "2024-01-15T10:30:00.123456+00:00",
  "updated_at": "2024-01-15T10:30:00.123456+00:00"
}

When a task status changes:

{
  "id": 11,
  "title": "New Task",
  "status": "done",
  "created_at": "2024-01-15T10:30:00.123456+00:00",
  "updated_at": "2024-01-15T14:45:00.789012+00:00",
  "status_changed_to_done": "2024-01-15T14:45:00.789012+00:00"
}

Logging

The tracker logs all activities to logs/taskmaster_tracker.log with timestamps:

2024-01-15 10:30:00,123 - INFO - New task detected: 11 - New Task
2024-01-15 10:30:00,124 - INFO - Added created_at to task 11: 2024-01-15T10:30:00.123456+00:00
2024-01-15 14:45:00,789 - INFO - Status change detected for task 11: pending -> done
2024-01-15 14:45:00,790 - INFO - Added status_changed_to_done to task 11: 2024-01-15T14:45:00.789012+00:00

Safety Features

• Backup System: Always creates backups before modifying tasks
• Non-Destructive: Only adds new fields, never modifies existing data
• Error Handling: Graceful handling of file errors and JSON parsing issues
• Cleanup: Automatically removes old backups (keeps last 10)

Integration with Taskmaster

The tracker works seamlessly with Taskmaster:

1. No Conflicts: Only adds timestamp fields, doesn't interfere with Taskmaster operations
2. Automatic Detection: Detects changes made by Taskmaster CLI or MCP tools
3. Backup Safety: Creates backups before any modifications
4. Logging: Provides audit trail for all task changes

Troubleshooting

Common Issues

1. Permission Errors: Ensure the script has read/write permissions
2. File Not Found: Check that .taskmaster/tasks/tasks.json exists
3. JSON Errors: The tracker will log JSON parsing errors and continue
4. Backup Directory: Automatically creates backup directory if it doesn't exist

Debug Mode

To see more detailed logging, modify the logging level in the Python script:

logging.basicConfig(level=logging.DEBUG, ...)

Development

The tracker is designed to be:

• Lightweight: Minimal resource usage
• Reliable: Comprehensive error handling
• Safe: Non-destructive operations only
• Extensible: Easy to add new timestamp types

Future Enhancements

Potential improvements:

• Webhook notifications for task changes
• Integration with external time tracking tools
• Custom timestamp field configurations
• Database storage for change history
• Email notifications for status changes