demo
/
trax
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
trax/scripts/README_taskmaster_helpers.md

8.9 KiB
Raw Permalink Blame History

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

# 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:

./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:

./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:

./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:

./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

# 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

# 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

# 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

# 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

    npm install -g task-master-ai

  2. Project Setup: Ensure Taskmaster is initialized in your project

    task-master init

  3. Script Permissions: Make scripts executable (already done)

    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:

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

npm install -g task-master-ai

Script Permission Denied

chmod +x scripts/tm_*.sh

No Tasks Found

Ensure Taskmaster is initialized and tasks are created:

task-master init
task-master parse-prd your-prd.txt

Analysis Fails

Some analysis features require research API keys. Check your Taskmaster configuration:

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