@cognitiv/taskblaster

Master your tasks with Taskblaster™️ to make all your tasks faster! Automated pull request creation with AI-generated descriptions and JIRA integration.

🚀 Quick Start

Installation

npm install -g @cognitiv/taskblaster

Setup

From any git repository:

taskblaster-setup

This will:

• Check for required dependencies
• Create global configuration at ~/.config/taskblaster/config
• Guide you through the interactive setup process

Usage

Create a PR from your current branch:

taskblaster

📋 Prerequisites

Required Tools

• bash - Shell script execution
• jq - JSON processing (brew install jq or sudo apt install jq)
• gh - GitHub CLI (brew install gh then gh auth login)
• curl - HTTP requests
• git - Version control

API Keys Required

• Claude Code - For AI-generated descriptions (npm install -g @anthropic-ai/claude-code then claude)
• JIRA API Token - For ticket creation/management (Get yours here)
• GitHub Authentication - Via gh auth login

⚙️ Configuration

After running taskblaster-setup, your configuration is saved globally at:

Location: ~/.config/taskblaster/config

Includes:

• JIRA_URL, JIRA_EMAIL, JIRA_API_TOKEN
• JIRA_PROJECT_KEY, JIRA_IN_REVIEW_STATUS

🎯 Features

🤖 AI-Generated Descriptions

• Smart commit analysis - Only analyzes new commits when updating existing PRs
• Professional PR titles - Generates concise, descriptive titles
• Intelligent descriptions - Uses Claude AI for comprehensive summaries
• Context-aware - Focuses on what changed and why

🎫 Flexible JIRA Integration

• Auto-detects JIRA tickets from branch names
• Creates new tickets if none found
• NO-JIRA option - Skip JIRA entirely by typing 'n'
• Moves tickets to "In Review" status automatically
• Smart linking - Links PRs to JIRA tickets with proper formatting

🔗 Advanced GitHub Integration

• Smart base branch detection - Auto-detects fork source branch
• Existing PR updates - Adds comments and updates titles for existing PRs
• Title concatenation - Appends new titles to existing PRs (e.g., "TICKET-1: Fix, TICKET-2: Enhancement")
• Intelligent filtering - Only processes new commits when PR already exists
• Proper formatting - Consistent title format: TICKET: Description or NO-JIRA: Description

🔄 Existing PR Management

When a PR already exists for your branch, Taskblaster will:

1. Filter commits - Only analyze commits not already in the PR
2. Update PR title - Append new ticket/title to existing title
3. Add comment - Post new description as a comment
4. Smart detection - Show exactly how many new vs total commits

📝 Branch Naming & JIRA Options

Branch Naming

Works with any branch naming convention but can auto-detect JIRA tickets from:

• PROJ-123-feature-name
• feature/PROJ-456-description
• bugfix/PROJ-789-fix-login
• feature/user-auth (will create new ticket or use NO-JIRA)

JIRA Options

When prompted for JIRA ticket ID, you can:

• Press Enter - Create new ticket automatically
• Type ticket ID - Use existing ticket (e.g., PROJ-123)
• Type 'n' - Skip JIRA entirely (creates NO-JIRA PR)

🔒 Security

• Global config files are properly secured
• API keys never logged or committed
• JIRA tokens have limited scope
• GitHub auth uses standard OAuth

🛠️ Troubleshooting

Common Issues

"Command not found"

Make sure you installed globally:

npm install -g @cognitiv/taskblaster

"Not in a git repository"

Run the commands from within a git repository.

"No global configuration found"

Run taskblaster-setup first to create the configuration.

JIRA API errors

• Verify your JIRA_URL format: https://company.atlassian.net
• Check that JIRA_EMAIL and JIRA_API_TOKEN are correct
• Ensure JIRA_PROJECT_KEY exists and you have access

"Could not find transition to 'In Review'"

• Check your JIRA_IN_REVIEW_STATUS setting in the config
• Verify the status name matches exactly (case-sensitive)
• Ensure your JIRA project has the configured status

📊 Example Output

Creating New PR

============================================================
Taskblaster™️
============================================================

🎯 Target Branch Selection (Fork source: main)
Enter target branch [main]:
📌 ev-main => main

🎫 JIRA Ticket Configuration
Enter JIRA ticket ID [Generate new ticket/n]:
📌 JIRA ticket: Generate new ticket

🔍 Checking for existing PR...
🔍 Scanning commits...
  - Found 3 commit(s)
  - Modified 8 file(s)
🤖 Generating title and description...

📝 Title Configuration
Enter custom title [Add user authentication system]:
📌 Title: Add user authentication system

============================================================
📋 Confirmation
============================================================
📌 ev-main => main
📌 JIRA ticket: Generate new ticket
📌 Title: Add user authentication system

Proceed with creating JIRA ticket and GitHub PR? [Y/n]:

📌 Creating new JIRA ticket...
📌 Creating GitHub PR...

============================================================
✨ Success!
============================================================
✅ JIRA ticket created: https://company.atlassian.net/browse/PROJ-124
✅ Ticket moved to 'In Review' status
✅ GitHub PR created: https://github.com/company/repo/pull/114

Updating Existing PR

🔍 Checking for existing PR...
  - Found existing PR: https://github.com/company/repo/pull/114
🔍 Scanning commits...
  - Found 2 new commit(s) (out of 5 total)

... (JIRA and title configuration) ...

============================================================
✨ Success!
============================================================
✅ JIRA ticket created: https://company.atlassian.net/browse/PROJ-125
✅ Ticket moved to 'In Review' status
⚠️  Pull request already exists: https://github.com/company/repo/pull/114
✅ Updated PR: https://github.com/company/repo/pull/114#issuecomment-123

NO-JIRA Option

🎫 JIRA Ticket Configuration
Enter JIRA ticket ID [Generate new ticket/n]: n
📌 JIRA ticket: NO-JIRA

... (continues with NO-JIRA: title format) ...

============================================================
✨ Success!
============================================================
⚠️  NO-JIRA: No JIRA ticket created
✅ GitHub PR created: https://github.com/company/repo/pull/115

🤝 Contributing

Issues and improvements welcome! Please visit our GitHub repository.

📚 License

MIT License - see LICENSE file for details.

Happy automating! 🚀