# Taskmaster Helper Scripts

A comprehensive set of helper scripts for managing Taskmaster tasks via CLI for the Trax project.

## Overview

These scripts provide a unified interface to Taskmaster functionality, making it easy to check task status, search for tasks, manage workflows, and analyze project progress without needing to remember complex CLI commands.

## Quick Start

```bash
# Get a quick overview of your project
./scripts/tm_master.sh overview

# Get the next task to work on
./scripts/tm_master.sh next

# Start working on a task
./scripts/tm_master.sh start 15

# Complete a task
./scripts/tm_master.sh done 15

# Search for tasks
./scripts/tm_master.sh search whisper

# Run analysis
./scripts/tm_master.sh analyze
```

## Scripts Overview

### 1. `tm_master.sh` - Master Interface
**Purpose**: Unified interface to all helper scripts
**Usage**: `./scripts/tm_master.sh [command] [args]`

**Commands**:
- `overview` - Quick project overview
- `next` - Get next available task
- `start <id>` - Start working on a task
- `done <id>` - Complete a task
- `search <term>` - Search for tasks
- `analyze` - Run analysis
- `daily` - Show daily workflow
- `commands` - Show all available commands
- `shortcuts` - Show quick shortcuts

### 2. `tm_status.sh` - Status & Overview
**Purpose**: Check task status and get project overviews
**Usage**: `./scripts/tm_status.sh [command]`

**Commands**:
- `stats` - Quick statistics
- `next` - Show next task
- `pending` - Show pending tasks
- `progress` - Show in-progress tasks
- `activity` - Show recent activity
- `pipeline` - Show pipeline overview
- `cache` - Show cache status
- `details <id>` - Show task details
- `full` - Comprehensive overview

**Examples**:
```bash
./scripts/tm_status.sh stats
./scripts/tm_status.sh next
./scripts/tm_status.sh details 15
./scripts/tm_status.sh full
```

### 3. `tm_search.sh` - Search & Discovery
**Purpose**: Search tasks by various criteria
**Usage**: `./scripts/tm_search.sh [type] [term]`

**Search Types**:
- `text <term>` - Search by text in title/description
- `status <status>` - Search by task status
- `priority <level>` - Search by priority level
- `pipeline <version>` - Search by pipeline version (v1-v4)
- `type <type>` - Search by task type
- `deps <task-id>` - Show dependencies for a task
- `subtasks <task-id>` - Show subtasks for a task

**Valid Values**:
- **Statuses**: pending, in-progress, done, review, cancelled, deferred
- **Priorities**: high, medium, low
- **Pipeline Versions**: v1, v2, v3, v4
- **Task Types**: transcription, audio, enhancement, database, api, cli, test

**Examples**:
```bash
./scripts/tm_search.sh text whisper
./scripts/tm_search.sh status pending
./scripts/tm_search.sh priority high
./scripts/tm_search.sh pipeline v1
./scripts/tm_search.sh deps 15
```

### 4. `tm_workflow.sh` - Workflow Management
**Purpose**: Manage task workflows and progress
**Usage**: `./scripts/tm_workflow.sh [command] [args]`

**Commands**:
- `start <id>` - Start working on a task
- `update <id> <msg>` - Update task progress
- `complete <id>` - Complete a task
- `pause <id> [reason]` - Pause a task
- `review <id>` - Mark task for review
- `expand <id> [num]` - Expand task into subtasks
- `daily` - Show daily workflow overview
- `weekly` - Show weekly review

**Examples**:
```bash
./scripts/tm_workflow.sh start 15
./scripts/tm_workflow.sh update 15 "Implemented core functionality"
./scripts/tm_workflow.sh complete 15
./scripts/tm_workflow.sh pause 15 "Waiting for API key"
./scripts/tm_workflow.sh expand 15 5
./scripts/tm_workflow.sh daily
```

### 5. `tm_analyze.sh` - Analysis & Insights
**Purpose**: Analyze task complexity and generate insights
**Usage**: `./scripts/tm_analyze.sh [command]`

**Commands**:
- `analyze` - Run complexity analysis
- `report` - Show complexity report
- `dependencies` - Analyze task dependencies
- `distribution` - Analyze task distribution
- `pipeline` - Analyze pipeline progress
- `bottlenecks` - Identify potential bottlenecks
- `insights` - Generate project insights
- `full` - Run comprehensive analysis

**Examples**:
```bash
./scripts/tm_analyze.sh analyze
./scripts/tm_analyze.sh report
./scripts/tm_analyze.sh dependencies
./scripts/tm_analyze.sh insights
./scripts/tm_analyze.sh full
```

### 6. `tm_quick.sh` - Quick Operations
**Purpose**: Quick task operations (existing script)
**Usage**: `./scripts/tm_quick.sh [command] [args]`

**Commands**:
- `next, n` - Get next task
- `list, l` - List all tasks
- `show, s <id>` - Show task details
- `done, d <id>` - Mark as done
- `progress, p <id>` - Mark as in-progress
- `search <term>` - Search tasks
- `stats` - Show statistics

## Common Workflows

### Daily Workflow
```bash
# Start your day
./scripts/tm_master.sh daily

# Get next task
./scripts/tm_master.sh next

# Start working on a task
./scripts/tm_master.sh start 15

# Update progress throughout the day
./scripts/tm_workflow.sh update 15 "Made progress on API integration"

# Complete when done
./scripts/tm_master.sh done 15
```

### Weekly Review
```bash
# Run comprehensive analysis
./scripts/tm_analyze.sh full

# Check weekly progress
./scripts/tm_workflow.sh weekly

# Identify bottlenecks
./scripts/tm_analyze.sh bottlenecks
```

### Task Search & Discovery
```bash
# Find all transcription-related tasks
./scripts/tm_search.sh text transcription

# Find high-priority tasks
./scripts/tm_search.sh priority high

# Find v1 pipeline tasks
./scripts/tm_search.sh pipeline v1

# Check dependencies for a task
./scripts/tm_search.sh deps 15
```

### Project Analysis
```bash
# Get quick overview
./scripts/tm_master.sh overview

# Run complexity analysis
./scripts/tm_analyze.sh analyze

# View complexity report
./scripts/tm_analyze.sh report

# Generate insights
./scripts/tm_analyze.sh insights
```

## Prerequisites

1. **Taskmaster CLI**: Install the Taskmaster CLI globally
   ```bash
   npm install -g task-master-ai
   ```

2. **Project Setup**: Ensure Taskmaster is initialized in your project
   ```bash
   task-master init
   ```

3. **Script Permissions**: Make scripts executable (already done)
   ```bash
   chmod +x scripts/tm_*.sh
   ```

## Features

### Color-Coded Output
All scripts use color-coded output for better readability:
- 🟢 Green: Success, completed tasks
- 🟡 Yellow: Warnings, in-progress tasks
- 🔵 Blue: Information, pending tasks
- 🔴 Red: Errors, issues
- 🟣 Magenta: Special statuses
- 🔵 Cyan: Headers and highlights

### Error Handling
- Graceful handling of missing Taskmaster CLI
- Fallback options when advanced features aren't available
- Clear error messages with helpful suggestions

### Integration
- Works with existing `tm_trax.py` Python script for enhanced features
- Integrates with Taskmaster tracker for activity logging
- Compatible with existing project structure

### Caching
- Uses Taskmaster's built-in caching system
- Fast response times for repeated operations
- Automatic cache validation

## Tips & Best Practices

### 1. Use the Master Script
Start with `tm_master.sh` for most operations - it provides a unified interface and delegates to the appropriate specialized script.

### 2. Regular Status Checks
Use `./scripts/tm_master.sh overview` regularly to keep track of project progress.

### 3. Workflow Consistency
Follow the standard workflow: start → update → complete for consistent task management.

### 4. Search Before Creating
Use search functions to find existing tasks before creating new ones to avoid duplication.

### 5. Regular Analysis
Run analysis periodically to identify bottlenecks and optimize your workflow.

### 6. Use Shortcuts
Create shell aliases for common operations:
```bash
alias tm='./scripts/tm_master.sh'
alias tm-next='./scripts/tm_master.sh next'
alias tm-overview='./scripts/tm_master.sh overview'
```

## Troubleshooting

### Taskmaster CLI Not Found
```bash
npm install -g task-master-ai
```

### Script Permission Denied
```bash
chmod +x scripts/tm_*.sh
```

### No Tasks Found
Ensure Taskmaster is initialized and tasks are created:
```bash
task-master init
task-master parse-prd your-prd.txt
```

### Analysis Fails
Some analysis features require research API keys. Check your Taskmaster configuration:
```bash
task-master models
```

## Contributing

When adding new helper scripts:

1. Follow the existing naming convention: `tm_[purpose].sh`
2. Include comprehensive help documentation
3. Use consistent color coding
4. Add error handling and validation
5. Update this README with new functionality
6. Make scripts executable with `chmod +x`

## Related Files

- `tm_trax.py` - Python-based enhanced Taskmaster functionality
- `taskmaster_tracker.py` - Task tracking and logging
- `tm_quick.sh` - Quick operations (existing)
- `tm_trax.py` - Trax-specific pipeline analysis

## Support

For issues with these helper scripts:
1. Check that Taskmaster CLI is installed and working
2. Verify script permissions are correct
3. Check that Taskmaster is properly initialized in the project
4. Review the individual script help: `./scripts/tm_[script].sh help`