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

``bash 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-all.md| [NEW] Execute all tasks sequentially (with Context Management) | |.agent/workflows/write-prd.md| [NEW] Write PRD with AI assistance | |.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 | |skills/write-prd.md| [NEW] AI-friendly PRD writing guide | |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 inverify-task.md. - pnpm + turbo: Detects Monorepo environments and generates workflows with// turboannotations. - Feature Selection: Choose which features to use: auto status management, file change detection, failure recovery guide, progress reports, etc.

`Main Commands`

`$3`

bash
npx task-master-agent init


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

bash
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

`$3`

1. Parse PRD`bash npx task-master-agent parse-prd [prd-file]`Precisely analyzes PRD documents and generates.agent/TASK_BREAKDOWN.md. - Recognizes### Main Task / #### Subtaskhierarchy - Auto-extracts priority (🔴/🟡/🟢) and acceptance criteria (- [ ]) - Improved markdown parsing engine supports various formats

2. PRD Writing Guide Useskills/write-prd.md and the workflow to create AI-friendly PRDs.

`$3`

bash
npx task-master-agent status


Analyzes

.agent/TASK_BREAKDOWN.md

 and visualizes overall progress and current task in progress.
$3

bash
npx task-master-agent sync


Extracts current task in progress to

.agent/CURRENT_TASK.md

 and updates project context.
$3

bash
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:`bash

`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

$3

bash
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
$3

bash
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

`$3`

bash
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| Execute next task + verify | |/task-all| [NEW] Execute all tasks sequentially (with Context Management) | |/write-prd| [NEW] Write PRD with AI | |/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`

`$3`

`bash

`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

$3

`bash

`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`

`bash

`Check overall progress`


npx task-master-agent status
Example output:

📊 Task Master Progress

[████████░░░░░░░░░░░░] 40% (2/5)

🏃 Currently working on: Login feature implementation

$3

`bash

`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

$3

Method 1: Manual Update Directly change markers in.agent/TASK_BREAKDOWN.md: -[ ] → [/]: Start work -[/] → [x]: Complete work

Then run syncagain:`bash npx task-master-agent sync`

Method 2: Auto Update (Recommended) AI agent automatically updates status when work is completed:`bash npx task-master-agent update-status --status=completed`

Or use watchmode to detect file changes:`bash npx task-master-agent watch

`Automatically syncs when TASK_BREAKDOWN.md is modified in another terminal`

$3

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

task-master-agent

Installation

``bash npx task-master-agent init`

Use the --force option to overwrite existing files.

`Installed Files`

`Project Detection and Tool Support`

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

`Main Commands`

`$3`

bash
npx task-master-agent init


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

bash
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

`$3`

2. PRD Writing Guide Useskills/write-prd.md and the workflow to create AI-friendly PRDs.

`$3`

bash
npx task-master-agent status


Analyzes

.agent/TASK_BREAKDOWN.md

 and visualizes overall progress and current task in progress.
$3

bash
npx task-master-agent sync


Extracts current task in progress to

.agent/CURRENT_TASK.md

 and updates project context.
$3

bash
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:`bash

`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

$3

bash
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
$3

bash
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

`$3`

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

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`

`Usage Workflow`

`$3`

`bash

`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

$3

`bash

`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

`$3`

`bash

`Check overall progress`


npx task-master-agent status
Example output:

📊 Task Master Progress

[████████░░░░░░░░░░░░] 40% (2/5)

🏃 Currently working on: Login feature implementation

$3

`bash

`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

$3

Method 1: Manual Update Directly change markers in.agent/TASK_BREAKDOWN.md: -[ ] → [/]: Start work -[/] → [x]: Complete work

Then run syncagain:`bash npx task-master-agent sync`

Method 2: Auto Update (Recommended) AI agent automatically updates status when work is completed:`bash npx task-master-agent update-status --status=completed`

Or use watchmode to detect file changes:`bash npx task-master-agent watch

`Automatically syncs when TASK_BREAKDOWN.md is modified in another terminal`

$3

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