task-master-sync

Task-Master-Sync

A command-line synchronization tool for TaskMaster AI and Monday.com, designed for DevOps workflows.

Overview

This CLI tool bridges the gap between AI-driven task management (TaskMaster AI) and collaborative project tracking on Monday.com. It's particularly useful for DevOps workflows, CI/CD pipelines, and automating task synchronization between developers and project managers.

Features

• Command-line driven synchronization (push/pull)
• Bidirectional synchronization with automatic item recreation
• Easy integration with CI/CD pipelines (GitHub Actions, GitLab CI, Jenkins)
• Task-to-Item data mapping between TaskMaster and Monday.com
• Local configuration through sync-config.json
• Detailed synchronization logs
• Support for standard TaskMaster task properties
• Conflict detection and resolution strategies
• Selective synchronization options

Cursor Integration Setup

For developers using Cursor IDE, an MCP configuration file is required to enable TaskMaster AI integration. Follow these steps:

• Create a .cursor directory in your project root (if it doesn't already exist):

mkdir -p .cursor

• Create an mcp.json file inside the .cursor directory with your API keys:

touch .cursor/mcp.json

• Add the configuration to your mcp.json file. You can use the provided example file as a reference:

# Option 1: Copy the example file
cp .cursor/example-mcp.json .cursor/mcp.json

# Option 2: Create your own based on the template below

Basic configuration template:

{
    "mcpServers": {
        "task-master-ai": {
            "command": "npx",
            "args": [
                "-y",
                "--package=task-master-ai",
                "task-master-ai"
            ],
            "env": {
                "ANTHROPIC_API_KEY": "your-anthropic-api-key-here",
                "PERPLEXITY_API_KEY": "your-perplexity-api-key-here",
                "MODEL": "claude-3-7-sonnet-20250219",
                "PERPLEXITY_MODEL": "sonar",
                "MAX_TOKENS": 64000,
                "TEMPERATURE": 0.2,
                "DEFAULT_SUBTASKS": 5,
                "DEFAULT_PRIORITY": "medium"
            }
        }
    }
}

• Replace the placeholder API keys with your actual keys:

Required API Keys

You need at least one of these API keys depending on which AI provider you prefer:

• ANTHROPIC_API_KEY: Required for using Claude models (recommended)
• PERPLEXITY_API_KEY: Required for research-backed operations

Optional API Keys

You can also add these optional API keys for alternative providers:

• OPENAI_API_KEY: For using OpenAI models
• GOOGLE_API_KEY: For using Google AI models
• MISTRAL_API_KEY: For using Mistral AI models
• OPENROUTER_API_KEY: For using OpenRouter's model router

Configuration Options

• MODEL: Primary model for task generation (default: "claude-3-7-sonnet-20250219")
• PERPLEXITY_MODEL: Model for research operations (default: "sonar")
• MAX_TOKENS: Maximum tokens for model responses (default: 64000)
• TEMPERATURE: Controls randomness in responses (lower values = more deterministic, default: 0.2)
• DEFAULT_SUBTASKS: Default number of subtasks when expanding tasks (default: 5)
• DEFAULT_PRIORITY: Default priority for new tasks (default: "medium")

Important: The mcp.json file contains sensitive API keys and should not be committed to your repository. It is already added to .gitignore.

Bidirectional Synchronization

TaskMaster-Monday Sync v0.2.0+ features robust bidirectional synchronization with automatic item recreation:

Push Sync (TaskMaster → Monday)

When pushing tasks from TaskMaster to Monday.com:

• If a Monday.com item has been deleted but still exists in TaskMaster, it will be automatically recreated
• The system tracks recreated items and updates tasks.json with the new Monday item IDs
• Detailed reporting shows both recreated and standard created/updated items

Pull Sync (Monday → TaskMaster)

When pulling items from Monday.com to TaskMaster:

• If a task has been deleted locally but still exists in Monday.com, it will be automatically recreated
• The recreateMissingTasks option (default: true) controls this behavior
• Conflicts between recreated and existing tasks are detected and reported

Configuration Options

Additional configuration options for bidirectional sync:

# Push sync with deletion of orphaned Monday items (default)
taskmaster-sync push

# Push sync without deletion of orphaned Monday items
taskmaster-sync push --no-delete-orphaned

# Pull sync with automatic recreation of missing tasks (default)
taskmaster-sync pull

# Pull sync without recreation of missing tasks
taskmaster-sync pull --no-recreate-missing-tasks

For more details on the bidirectional sync implementation, see README-BidirectionalSync.md.

Getting Started

Installation

# Install globally
npm install -g task-master-sync

# Or use directly with npx
npx task-master-sync ...

Setup

• Find your Monday.com column IDs - Use the included utility to discover your board's column IDs:

# Option 1: Using environment variables
export MONDAY_API_KEY="your_api_key_here"
export MONDAY_BOARD_ID="your_board_id_here"
npm run get-columns

# Option 2: Using command-line arguments
npm run get-columns -- --api-key="your_api_key_here" --board-id="your_board_id_here"

# Option 3: Using the global command
taskmaster-sync-get-columns --api-key="your_api_key_here" --board-id="your_board_id_here"

• Create your configuration file - Copy the example and add your Monday.com details:

cp sync-config.example.json sync-config.json

Configuration

Create a sync-config.json file in your project root:

{
  "monday_board_id": "your_board_id",
  "monday_group_ids": ["your_group_id"],
  "monday_api_key": "your_api_key",
  "developer_id": "your_unique_id",
  "column_mappings": {
    "taskId": "text_column_id",
    "status": "status_column_id",
    "priority": "priority_column_id",
    "dependencies": "text_column_id",
    "complexity": "color_column_id",
    "description": "long_text_column_id",
    "details": "long_text_column_id",
    "testStrategy": "long_text_column_id"
  },
  "status_mappings": {
    "pending": "pending",
    "in-progress": "in-progress",
    "done": "done"
  },
  "priority_mappings": {
    "high": "high",
    "medium": "medium",
    "low": "low"
  }
}

Alternatively, you can set your Monday.com API key as an environment variable:

export MONDAY_API_KEY=your_api_key

Column Mappings

The column_mappings object in your configuration maps TaskMaster task fields to Monday.com column IDs. These column IDs are specific to your Monday.com board and can be found in the board settings or using the Monday.com API.

For each field, provide the corresponding Monday.com column ID:

Field	Description	Monday.com Column Type
taskId	The TaskMaster task ID	Text column
status	Task status (pending, in-progress, done, etc.)	Status column
priority	Task priority (high, medium, low)	Status column
dependencies	Comma-separated list of dependent task IDs	Text column
complexity	Task complexity (1-10)	Status column
description	Task description	Long text column
details	Implementation details	Long text column
testStrategy	Testing strategy	Long text column

Finding Your Column IDs

To help you find the column IDs for your Monday.com board, we've included a utility command:

# If installed globally
taskmaster-sync-get-columns

# If installed locally in your project
npx taskmaster-sync-get-columns

# Or using npm script
npm run get-columns

This command will:

• Connect to your Monday.com board using your configured API key
• Fetch all column definitions
• Display their IDs, titles, and types
• Provide a template for your column_mappings configuration

Make sure you have a valid sync-config.json with your monday_board_id and monday_api_key before running this command.

CLI Commands

Basic Usage

# If installed globally
taskmaster-sync --help

# If installed locally in your project
npx taskmaster-sync --help

# View command-specific help
taskmaster-sync push --help
taskmaster-sync pull --help

# Display current configuration
taskmaster-sync config

Push Command

Push your local TaskMaster tasks to Monday.com.

taskmaster-sync push [options]

Options

Option	Description	Default
-d, --dry-run	Show what would be synced without making changes	false
-v, --verbose	Increase logging detail	false
-c, --config <path>	Path to sync config file	sync-config.json
-t, --tasks <path>	Path to tasks.json file	tasks/tasks.json
-s, --state <path>	Path to sync state file	.taskmaster_sync_state.json

Examples

# Basic push with default options
taskmaster-sync push

# Dry run to preview changes
taskmaster-sync push --dry-run

# Use a custom tasks file
taskmaster-sync push --tasks custom-tasks/tasks.json

# Enable verbose logging
taskmaster-sync push --verbose

Pull Command

Pull Monday.com items to your local TaskMaster tasks.

taskmaster-sync pull [options]

Options

Option	Description	Default
-d, --dry-run	Show what would be synced without making changes	false
-v, --verbose	Increase logging detail	false
-c, --config <path>	Path to sync config file	sync-config.json
-t, --tasks <path>	Path to tasks.json file	tasks/tasks.json
-s, --state <path>	Path to sync state file	.taskmaster_sync_state.json
-a, --assign-task-ids	Automatically assign Task IDs to new Monday.com items	false
-f, --force	Overwrite local changes with Monday.com data	false
--skip-conflicts	Skip tasks with local changes	false
--task-id <id>	Pull only a specific task by ID
--group <group_id>	Pull from a specific Monday.com group
--regenerate	Regenerate task files after pull	true
--remove-orphaned	Remove orphaned local tasks	true
--no-remove-orphaned	Keep orphaned local tasks
--recreate-missing-tasks	Recreate tasks that exist in Monday but not locally	true
--no-recreate-missing-tasks	Don't recreate missing tasks

License

MIT

Development & Publishing

Development Setup

# Clone the repository
git clone https://github.com/yourusername/task-master-sync.git
cd task-master-sync

# Install dependencies
npm install

# Run tests
npm test

# Try the CLI locally
node src/cli/index.js --help

Building for Publication

The package doesn't require a build step as it uses plain JavaScript. However, before publishing:

• Update the version in package.json
• Ensure all tests are passing
• Check that the files field in package.json includes all necessary files
• Verify the README is up-to-date

Publishing to npm

For Integrity Internal use - check the password manager for the npm username/password and publish token.

# Login to npm (only needed once)
npm login

# Test the package contents that would be published
npm pack

# Review the generated .tgz file to ensure it contains the correct files
tar -tf task-master-sync-*.tgz

# Run the prepublish checks (linting and tests)
npm run prepublishOnly

# Publish to npm
npm publish

# For testing with a specific version before publishing publicly
npm publish --tag beta

CI/CD Publishing (GitHub Actions)

You can automate publishing using GitHub Actions by adding a workflow file:

# .github/workflows/publish.yml
name: Publish to npm

on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20.x'
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm test
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Remember to add an NPM_TOKEN secret in your GitHub repository settings.

Using the Package Locally During Development

# Create a global symlink
npm link

# In another project, use the linked package
npm link task-master-sync

# Run the commands from your development version
taskmaster-sync --help