153 lines
4.6 KiB
Markdown
153 lines
4.6 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```python
|
|
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
|