task-master-agent

An npm CLI tool that supports Task Master-like functionality. Automatically sets up workflows, rules, and prompts for Antigravity/Cursor so AI agents can parse PRDs, create, manage, execute, and verify tasks.

Installation

npx task-master-agent init

Use the --force option to overwrite existing files.

Installed Files

| Path | Purpose | |------|---------| | .agent/rules/task-master.md | Task Master role definition (auto context injection, acceptance criteria management) | | .agent/workflows/task-next.md | Next task execution workflow (Branch-based) | | .agent/workflows/task-worktree.md | Task execution in isolated environment (Worktree-based) | | .agent/workflows/verify-task.md | Task verification (auto-detects Biome, ESLint, etc.) | | .agent/workflows/deploy.md | Production deployment workflow (optional) | | .agent/workflows/code-review.md | Pre-PR self-review checklist (optional) | | .agent/prompts/task-master-prompt.md | Prompt examples | | .cursor/rules/task-master.mdc | Cursor Task Master rule | | prd/PRODUCT_REQUIREMENTS_TEMPLATE.md | PRD template (optional) | | .task-master.json | Project-specific configuration file |

Project Detection and Tool Support

When running init, the tool analyzes your project structure and provides optimized settings:

• Git Strategy Selection: Choose between branch-based or worktree-based workflow.
• Lint Tool Auto-Detection: Automatically detects Biome, ESLint, Prettier, etc., and reflects them in verify-task.md.
• pnpm + turbo: Detects Monorepo environments and generates workflows with // turbo annotations.
• Feature Selection: Choose which features to use: auto status management, file change detection, failure recovery guide, progress reports, etc.

Main Commands

Initialize (Init)

npx task-master-agent init

Interactive CLI to configure tools, Git workflow, additional workflows, and features to use.

Upgrade

npx task-master-agent upgrade [--backup]

Safely upgrade existing installation. User data files are protected and only templates are updated.

Protected Files:

• .agent/TASK_BREAKDOWN.md (tasks in progress)
• .agent/PROJECT_CONTEXT.md (project context)
• .agent/CURRENT_TASK.md (current task details)
• .agent/history/ (work history)

Options:

• --backup: Create full backup before upgrade

Parse PRD

npx task-master-agent parse-prd [prd-file]

Analyzes PRD documents and automatically generates .agent/TASK_BREAKDOWN.md.

Status

npx task-master-agent status

Analyzes .agent/TASK_BREAKDOWN.md and visualizes overall progress and current task in progress.

Sync Context

npx task-master-agent sync

Extracts current task in progress to .agent/CURRENT_TASK.md and updates project context.

Auto Status Management (Update Status)

npx task-master-agent update-status [--task=TASK-001] [--status=completed]

Updates task status programmatically. Can be automatically called by AI agents when work is completed.

Options:

• --task=TASK-001: Task ID to update (defaults to current task in progress if omitted)
• --status=completed|in-progress|pending: Status (default: completed)

Examples:

# Mark current task as completed
npx task-master-agent update-status --status=completed

# Change specific task to in-progress
npx task-master-agent update-status --task=TASK-001 --status=in-progress

File Change Detection and Auto Sync (Watch)

npx task-master-agent watch

Detects changes to TASK_BREAKDOWN.md and automatically syncs context. Runs in background for real-time synchronization.

Use Cases:

• When AI agents manually change task status
• When working across multiple sessions
• When you want to keep context up-to-date in real-time

Failure Recovery Guide (Recover)

npx task-master-agent recover [--task=TASK-001]

Automatically detects issues when task verification fails and generates a recovery guide.

Features:

• Detects build failures and suggests solutions
• Detects lint errors and provides auto-fix commands
• Detects test failures
• Checks incomplete acceptance criteria

Output: Creates .agent/RECOVERY_GUIDE.md file

Progress Report

npx task-master-agent report [--period=daily|weekly|monthly]

Analyzes task progress and generates a report.

Features:

• Overall statistics (completion rate, progress)
• Statistics by priority
• List of completed tasks
• List of tasks in progress
• Blocker identification
• Recommendations

Output: Creates .agent/REPORT_{PERIOD}_{DATE}.md file

Using with Antigravity

When you run init, files are created in .agent/rules/ and .agent/workflows/, which Antigravity automatically recognizes. No manual registration in Customizations needed.

Note: Antigravity only auto-recognizes .agent/rules/ and .agent/workflows/. For .agent/prompts/ prompt examples, reference them in chat as @task-master-prompt.md or copy the content.

| Slash Command | Purpose | |---------------|---------| | /task-next | Find and implement next task + verify | | /verify-task | Verify current work |

Task Master rules are automatically applied via Model Decision when related requests like "task", "PRD", "next work" are made.

Using with Cursor

.cursor/rules/task-master.mdc is applied when opening files related to prd/, TASK_BREAKDOWN.md, PRODUCT_REQUIREMENTS.md.

Required Project Structure

• PRODUCT_REQUIREMENTS.md or prd/ folder: PRD documents
• .agent/TASK_BREAKDOWN.md: Task definitions and status management (auto-parses progress)
• .task-master.json: Project configuration profile (local)

Usage Workflow

1. Initial Project Setup

# 1. Initialize Task Master
npx task-master-agent init

# Interactive prompts:
# - Git strategy: branch or worktree
# - Additional workflows: deploy, code-review (optional)
# - Include PRD template
# - Features to use: auto-status, watch, recover, report

2. Write PRD and Generate Tasks

# If PRD template was selected, it's created in prd/ folder
# Copy template and write actual PRD
cp prd/PRODUCT_REQUIREMENTS_TEMPLATE.md prd/my-feature.md

# After writing PRD, convert to tasks automatically
npx task-master-agent parse-prd prd/my-feature.md

# Or omit filename to auto-search for PRD files
npx task-master-agent parse-prd

parse-prd behavior:

• Analyzes "Functional Requirements" section of PRD
• ### 3.1 [Feature Category] → Main task
• #### 3.1.1 [Feature Name] → Subtask
• Auto-extracts priority and acceptance criteria
• Creates .agent/TASK_BREAKDOWN.md

3. Task Progress Management

# Check overall progress
npx task-master-agent status

# Example output:
# 📊 Task Master Progress
# [████████░░░░░░░░░░░░] 40% (2/5)
# 🏃 Currently working on: Login feature implementation

4. Working with AI Agent

# Sync current task context before starting work
npx task-master-agent sync

# This command:
# - Extracts task with [/] marker from TASK_BREAKDOWN.md
# - Creates .agent/CURRENT_TASK.md (current task details)
# - Updates .agent/PROJECT_CONTEXT.md (project-wide context)

Using with Antigravity:

# Task Master rule automatically references CURRENT_TASK.md
/task-next  # Automatically execute next task

# Auto-update status when work is completed
npx task-master-agent update-status --status=completed

# Generate recovery guide when verification fails
npx task-master-agent recover

# Check progress
npx task-master-agent report --period=weekly

5. Updating Task Status

Method 1: Manual Update Directly change markers in .agent/TASK_BREAKDOWN.md:

• [ ] → [/]: Start work
• [/] → [x]: Complete work

Then run sync again:

npx task-master-agent sync

Method 2: Auto Update (Recommended) AI agent automatically updates status when work is completed:

npx task-master-agent update-status --status=completed

Or use watch mode to detect file changes:

npx task-master-agent watch
# Automatically syncs when TASK_BREAKDOWN.md is modified in another terminal

6. Using Additional Workflows

Deploy Workflow (if selected):

/deploy  # Execute deployment workflow in Antigravity

Code Review Workflow (if selected):

/code-review  # Execute pre-PR self-review checklist

License

MIT