339 lines
8.9 KiB
Markdown
339 lines
8.9 KiB
Markdown
# 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`
|