ros/claude-task-master
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: add docs to monorepo (#1111)

Browse Source
This commit is contained in:
Ralph Khreish
2025-08-09 13:31:45 +02:00
committed by GitHub
parent a003041cd8
commit 41a8c2406a
41 changed files with 11423 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

209
apps/docs/capabilities/cli-root-commands.mdx Normal file
View File

@@ -0,0 +1,209 @@
---
title: CLI Commands
sidebarTitle: "CLI Commands"
---
<AccordionGroup>
<Accordion title="Parse PRD">
```bash
# Parse a PRD file and generate tasks
task-master parse-prd <prd-file.txt>
# Limit the number of tasks generated
task-master parse-prd <prd-file.txt> --num-tasks=10
```
</Accordion>
<Accordion title="List Tasks">
```bash
# List all tasks
task-master list
# List tasks with a specific status
task-master list --status=<status>
# List tasks with subtasks
task-master list --with-subtasks
# List tasks with a specific status and include subtasks
task-master list --status=<status> --with-subtasks
```
</Accordion>
<Accordion title="Show Next Task">
```bash
# Show the next task to work on based on dependencies and status
task-master next
```
</Accordion>
<Accordion title="Show Specific Task">
```bash
# Show details of a specific task
task-master show <id>
# or
task-master show --id=<id>
# View a specific subtask (e.g., subtask 2 of task 1)
task-master show 1.2
```
</Accordion>
<Accordion title="Update Tasks">
```bash
# Update tasks from a specific ID and provide context
task-master update --from=<id> --prompt="<prompt>"
```
</Accordion>
<Accordion title="Update a Specific Task">
```bash
# Update a single task by ID with new information
task-master update-task --id=<id> --prompt="<prompt>"
# Use research-backed updates with Perplexity AI
task-master update-task --id=<id> --prompt="<prompt>" --research
```
</Accordion>
<Accordion title="Update a Subtask">
```bash
# Append additional information to a specific subtask
task-master update-subtask --id=<parentId.subtaskId> --prompt="<prompt>"
# Example: Add details about API rate limiting to subtask 2 of task 5
task-master update-subtask --id=5.2 --prompt="Add rate limiting of 100 requests per minute"
# Use research-backed updates with Perplexity AI
task-master update-subtask --id=<parentId.subtaskId> --prompt="<prompt>" --research
```
Unlike the `update-task` command which replaces task information, the `update-subtask` command _appends_ new information to the existing subtask details, marking it with a timestamp. This is useful for iteratively enhancing subtasks while preserving the original content.
</Accordion>
<Accordion title="Generate Task Files">
```bash
# Generate individual task files from tasks.json
task-master generate
```
</Accordion>
<Accordion title="Set Task Status">
```bash
# Set status of a single task
task-master set-status --id=<id> --status=<status>
# Set status for multiple tasks
task-master set-status --id=1,2,3 --status=<status>
# Set status for subtasks
task-master set-status --id=1.1,1.2 --status=<status>
```
When marking a task as "done", all of its subtasks will automatically be marked as "done" as well.
</Accordion>
<Accordion title="Expand Tasks">
```bash
# Expand a specific task with subtasks
task-master expand --id=<id> --num=<number>
# Expand with additional context
task-master expand --id=<id> --prompt="<context>"
# Expand all pending tasks
task-master expand --all
# Force regeneration of subtasks for tasks that already have them
task-master expand --all --force
# Research-backed subtask generation for a specific task
task-master expand --id=<id> --research
# Research-backed generation for all tasks
task-master expand --all --research
```
</Accordion>
<Accordion title="Clear Subtasks">
```bash
# Clear subtasks from a specific task
task-master clear-subtasks --id=<id>
# Clear subtasks from multiple tasks
task-master clear-subtasks --id=1,2,3
# Clear subtasks from all tasks
task-master clear-subtasks --all
```
</Accordion>
<Accordion title="Analyze Task Complexity">
```bash
# Analyze complexity of all tasks
task-master analyze-complexity
# Save report to a custom location
task-master analyze-complexity --output=my-report.json
# Use a specific LLM model
task-master analyze-complexity --model=claude-3-opus-20240229
# Set a custom complexity threshold (1-10)
task-master analyze-complexity --threshold=6
# Use an alternative tasks file
task-master analyze-complexity --file=custom-tasks.json
# Use Perplexity AI for research-backed complexity analysis
task-master analyze-complexity --research
```
</Accordion>
<Accordion title="View Complexity Report">
```bash
# Display the task complexity analysis report
task-master complexity-report
# View a report at a custom location
task-master complexity-report --file=my-report.json
```
</Accordion>
<Accordion title="Managing Task Dependencies">
```bash
# Add a dependency to a task
task-master add-dependency --id=<id> --depends-on=<id>
# Remove a dependency from a task
task-master remove-dependency --id=<id> --depends-on=<id>
# Validate dependencies without fixing them
task-master validate-dependencies
# Find and fix invalid dependencies automatically
task-master fix-dependencies
```
</Accordion>
<Accordion title="Add a New Task">
```bash
# Add a new task using AI
task-master add-task --prompt="Description of the new task"
# Add a task with dependencies
task-master add-task --prompt="Description" --dependencies=1,2,3
# Add a task with priority
task-master add-task --prompt="Description" --priority=high
```
</Accordion>
<Accordion title="Initialize a Project">
```bash
# Initialize a new project with Task Master structure
task-master init
```
</Accordion>
</AccordionGroup>

241
apps/docs/capabilities/index.mdx Normal file
View File

@@ -0,0 +1,241 @@
---
title: Technical Capabilities
sidebarTitle: "Technical Capabilities"
---
# Capabilities (Technical)
Discover the technical capabilities of Task Master, including supported models, integrations, and more.
# CLI Interface Synopsis
This document outlines the command-line interface (CLI) for the Task Master application, as defined in `bin/task-master.js` and the `scripts/modules/commands.js` file (which I will assume exists based on the context). This guide is intended for those writing user-facing documentation to understand how users interact with the application from the command line.
## Entry Point
The main entry point for the CLI is the `task-master` command, which is an executable script that spawns the main application logic in `scripts/dev.js`.
## Global Options
The following options are available for all commands:
- `-h, --help`: Display help information.
- `--version`: Display the application's version.
## Commands
The CLI is organized into a series of commands, each with its own set of options. The following is a summary of the available commands, categorized by their functionality.
### 1. Task and Subtask Management
- **`add`**: Creates a new task using an AI-powered prompt.
- `--prompt <prompt>`: The prompt to use for generating the task.
- `--dependencies <dependencies>`: A comma-separated list of task IDs that this task depends on.
- `--priority <priority>`: The priority of the task (e.g., `high`, `medium`, `low`).
- **`add-subtask`**: Adds a subtask to a parent task.
- `--parent-id <parentId>`: The ID of the parent task.
- `--task-id <taskId>`: The ID of an existing task to convert to a subtask.
- `--title <title>`: The title of the new subtask.
- **`remove`**: Removes one or more tasks or subtasks.
- `--ids <ids>`: A comma-separated list of task or subtask IDs to remove.
- **`remove-subtask`**: Removes a subtask from its parent.
- `--id <subtaskId>`: The ID of the subtask to remove (in the format `parentId.subtaskId`).
- `--convert-to-task`: Converts the subtask to a standalone task.
- **`update`**: Updates multiple tasks starting from a specific ID.
- `--from <fromId>`: The ID of the task to start updating from.
- `--prompt <prompt>`: The new context to apply to the tasks.
- **`update-task`**: Updates a single task.
- `--id <taskId>`: The ID of the task to update.
- `--prompt <prompt>`: The new context to apply to the task.
- **`update-subtask`**: Appends information to a subtask.
- `--id <subtaskId>`: The ID of the subtask to update (in the format `parentId.subtaskId`).
- `--prompt <prompt>`: The information to append to the subtask.
- **`move`**: Moves a task or subtask.
- `--from <sourceId>`: The ID of the task or subtask to move.
- `--to <destinationId>`: The destination ID.
- **`clear-subtasks`**: Clears all subtasks from one or more tasks.
- `--ids <ids>`: A comma-separated list of task IDs.
### 2. Task Information and Status
- **`list`**: Lists all tasks.
- `--status <status>`: Filters tasks by status.
- `--with-subtasks`: Includes subtasks in the list.
- **`show`**: Shows the details of a specific task.
- `--id <taskId>`: The ID of the task to show.
- **`next`**: Shows the next task to work on.
- **`set-status`**: Sets the status of a task or subtask.
- `--id <id>`: The ID of the task or subtask.
- `--status <status>`: The new status.
### 3. Task Analysis and Expansion
- **`parse-prd`**: Parses a PRD to generate tasks.
- `--file <file>`: The path to the PRD file.
- `--num-tasks <numTasks>`: The number of tasks to generate.
- **`expand`**: Expands a task into subtasks.
- `--id <taskId>`: The ID of the task to expand.
- `--num-subtasks <numSubtasks>`: The number of subtasks to generate.
- **`expand-all`**: Expands all eligible tasks.
- `--num-subtasks <numSubtasks>`: The number of subtasks to generate for each task.
- **`analyze-complexity`**: Analyzes task complexity.
- `--file <file>`: The path to the tasks file.
- **`complexity-report`**: Displays the complexity analysis report.
### 4. Project and Configuration
- **`init`**: Initializes a new project.
- **`generate`**: Generates individual task files.
- **`migrate`**: Migrates a project to the new directory structure.
- **`research`**: Performs AI-powered research.
- `--query <query>`: The research query.
This synopsis provides a comprehensive overview of the CLI commands and their options, which should be helpful for creating user-facing documentation.
# Core Implementation Synopsis
This document provides a high-level overview of the core implementation of the Task Master application, focusing on the functionalities exposed through `scripts/modules/task-manager.js`. This serves as a guide for understanding the application's capabilities when writing user-facing documentation.
## Core Concepts
The application revolves around the management of tasks and subtasks, which are stored in a `tasks.json` file. The core logic provides functionalities to create, read, update, and delete tasks and subtasks, as well as manage their dependencies and statuses.
### Task Structure
A task is a JSON object with the following key properties:
- `id`: A unique number identifying the task.
- `title`: A string representing the task's title.
- `description`: A string providing a brief description of the task.
- `details`: A string containing detailed information about the task.
- `testStrategy`: A string describing how to test the task.
- `status`: A string representing the task's current status (e.g., `pending`, `in-progress`, `done`).
- `dependencies`: An array of task IDs that this task depends on.
- `priority`: A string representing the task's priority (e.g., `high`, `medium`, `low`).
- `subtasks`: An array of subtask objects.
A subtask has a similar structure to a task but is nested within a parent task.
## Feature Categories
The core functionalities can be categorized as follows:
### 1. Task and Subtask Management
These functions are the bread and butter of the application, allowing for the creation, modification, and deletion of tasks and subtasks.
- **`addTask(prompt, dependencies, priority)`**: Creates a new task using an AI-powered prompt to generate the title, description, details, and test strategy. It can also be used to create a task manually by providing the task data directly.
- **`addSubtask(parentId, existingTaskId, newSubtaskData)`**: Adds a subtask to a parent task. It can either convert an existing task into a subtask or create a new subtask from scratch.
- **`removeTask(taskIds)`**: Removes one or more tasks or subtasks.
- **`removeSubtask(subtaskId, convertToTask)`**: Removes a subtask from its parent. It can optionally convert the subtask into a standalone task.
- **`updateTaskById(taskId, prompt)`**: Updates a task's information based on a prompt.
- **`updateSubtaskById(subtaskId, prompt)`**: Appends additional information to a subtask's details.
- **`updateTasks(fromId, prompt)`**: Updates multiple tasks starting from a specific ID based on a new context.
- **`moveTask(sourceId, destinationId)`**: Moves a task or subtask to a new position.
- **`clearSubtasks(taskIds)`**: Clears all subtasks from one or more tasks.
### 2. Task Information and Status
These functions are used to retrieve information about tasks and manage their status.
- **`listTasks(statusFilter, withSubtasks)`**: Lists all tasks, with options to filter by status and include subtasks.
- **`findTaskById(taskId)`**: Finds a task by its ID.
- **`taskExists(taskId)`**: Checks if a task with a given ID exists.
- **`setTaskStatus(taskIdInput, newStatus)`**: Sets the status of a task or subtask.
-al
- **`updateSingleTaskStatus(taskIdInput, newStatus)`**: A helper function to update the status of a single task or subtask.
- **`findNextTask()`**: Determines the next task to work on based on dependencies and status.
### 3. Task Analysis and Expansion
These functions leverage AI to analyze and break down tasks.
- **`parsePRD(prdPath, numTasks)`**: Parses a Product Requirements Document (PRD) to generate an initial set of tasks.
- **`expandTask(taskId, numSubtasks)`**: Expands a task into a specified number of subtasks using AI.
- **`expandAllTasks(numSubtasks)`**: Expands all eligible pending or in-progress tasks.
- **`analyzeTaskComplexity(options)`**: Analyzes the complexity of tasks and generates recommendations for expansion.
- **`readComplexityReport()`**: Reads the complexity analysis report.
### 4. Dependency Management
These functions are crucial for managing the relationships between tasks.
- **`isTaskDependentOn(task, targetTaskId)`**: Checks if a task has a direct or indirect dependency on another task.
### 5. Project and Configuration
These functions are for managing the project and its configuration.
- **`generateTaskFiles()`**: Generates individual task files from `tasks.json`.
- **`migrateProject()`**: Migrates the project to the new `.taskmaster` directory structure.
- **`performResearch(query, options)`**: Performs AI-powered research with project context.
This overview should provide a solid foundation for creating user-facing documentation. For more detailed information on each function, refer to the source code in `scripts/modules/task-manager/`.
# MCP Interface Synopsis
This document provides an overview of the MCP (Machine-to-Machine Communication Protocol) interface for the Task Master application. The MCP interface is defined in the `mcp-server/` directory and exposes the application's core functionalities as a set of tools that can be called remotely.
## Core Concepts
The MCP interface is built on top of the `fastmcp` library and registers a set of tools that correspond to the core functionalities of the Task Master application. These tools are defined in the `mcp-server/src/tools/` directory and are registered with the MCP server in `mcp-server/src/tools/index.js`.
Each tool is defined with a name, a description, and a set of parameters that are validated using the `zod` library. The `execute` function of each tool calls the corresponding core logic function from `scripts/modules/task-manager.js`.
## Tool Categories
The MCP tools can be categorized in the same way as the core functionalities:
### 1. Task and Subtask Management
- **`add_task`**: Creates a new task.
- **`add_subtask`**: Adds a subtask to a parent task.
- **`remove_task`**: Removes one or more tasks or subtasks.
- **`remove_subtask`**: Removes a subtask from its parent.
- **`update_task`**: Updates a single task.
- **`update_subtask`**: Appends information to a subtask.
- **`update`**: Updates multiple tasks.
- **`move_task`**: Moves a task or subtask.
- **`clear_subtasks`**: Clears all subtasks from one or more tasks.
### 2. Task Information and Status
- **`get_tasks`**: Lists all tasks.
- **`get_task`**: Shows the details of a specific task.
- **`next_task`**: Shows the next task to work on.
- **`set_task_status`**: Sets the status of a task or subtask.
### 3. Task Analysis and Expansion
- **`parse_prd`**: Parses a PRD to generate tasks.
- **`expand_task`**: Expands a task into subtasks.
- **`expand_all`**: Expands all eligible tasks.
- **`analyze_project_complexity`**: Analyzes task complexity.
- **`complexity_report`**: Displays the complexity analysis report.
### 4. Dependency Management
- **`add_dependency`**: Adds a dependency to a task.
- **`remove_dependency`**: Removes a dependency from a task.
- **`validate_dependencies`**: Validates the dependencies of all tasks.
- **`fix_dependencies`**: Fixes any invalid dependencies.
### 5. Project and Configuration
- **`initialize_project`**: Initializes a new project.
- **`generate`**: Generates individual task files.
- **`models`**: Manages AI model configurations.
- **`research`**: Performs AI-powered research.
### 6. Tag Management
- **`add_tag`**: Creates a new tag.
- **`delete_tag`**: Deletes a tag.
- **`list_tags`**: Lists all tags.
- **`use_tag`**: Switches to a different tag.
- **`rename_tag`**: Renames a tag.
- **`copy_tag`**: Copies a tag.
This synopsis provides a clear overview of the MCP interface and its available tools, which will be valuable for anyone writing documentation for developers who need to interact with the Task Master application programmatically.

68
apps/docs/capabilities/mcp.mdx Normal file
View File

@@ -0,0 +1,68 @@
---
title: MCP Tools
sidebarTitle: "MCP Tools"
---
# MCP Tools
This document provides an overview of the MCP (Machine-to-Machine Communication Protocol) interface for the Task Master application. The MCP interface is defined in the `mcp-server/` directory and exposes the application's core functionalities as a set of tools that can be called remotely.
## Core Concepts
The MCP interface is built on top of the `fastmcp` library and registers a set of tools that correspond to the core functionalities of the Task Master application. These tools are defined in the `mcp-server/src/tools/` directory and are registered with the MCP server in `mcp-server/src/tools/index.js`.
Each tool is defined with a name, a description, and a set of parameters that are validated using the `zod` library. The `execute` function of each tool calls the corresponding core logic function from `scripts/modules/task-manager.js`.
## Tool Categories
The MCP tools can be categorized in the same way as the core functionalities:
### 1. Task and Subtask Management
- **`add_task`**: Creates a new task.
- **`add_subtask`**: Adds a subtask to a parent task.
- **`remove_task`**: Removes one or more tasks or subtasks.
- **`remove_subtask`**: Removes a subtask from its parent.
- **`update_task`**: Updates a single task.
- **`update_subtask`**: Appends information to a subtask.
- **`update`**: Updates multiple tasks.
- **`move_task`**: Moves a task or subtask.
- **`clear_subtasks`**: Clears all subtasks from one or more tasks.
### 2. Task Information and Status
- **`get_tasks`**: Lists all tasks.
- **`get_task`**: Shows the details of a specific task.
- **`next_task`**: Shows the next task to work on.
- **`set_task_status`**: Sets the status of a task or subtask.
### 3. Task Analysis and Expansion
- **`parse_prd`**: Parses a PRD to generate tasks.
- **`expand_task`**: Expands a task into subtasks.
- **`expand_all`**: Expands all eligible tasks.
- **`analyze_project_complexity`**: Analyzes task complexity.
- **`complexity_report`**: Displays the complexity analysis report.
### 4. Dependency Management
- **`add_dependency`**: Adds a dependency to a task.
- **`remove_dependency`**: Removes a dependency from a task.
- **`validate_dependencies`**: Validates the dependencies of all tasks.
- **`fix_dependencies`**: Fixes any invalid dependencies.
### 5. Project and Configuration
- **`initialize_project`**: Initializes a new project.
- **`generate`**: Generates individual task files.
- **`models`**: Manages AI model configurations.
- **`research`**: Performs AI-powered research.
### 6. Tag Management
- **`add_tag`**: Creates a new tag.
- **`delete_tag`**: Deletes a tag.
- **`list_tags`**: Lists all tags.
- **`use_tag`**: Switches to a different tag.
- **`rename_tag`**: Renames a tag.
- **`copy_tag`**: Copies a tag.

163
apps/docs/capabilities/task-structure.mdx Normal file
View File

@@ -0,0 +1,163 @@
---
title: "Task Structure"
sidebarTitle: "Task Structure"
description: "Tasks in Task Master follow a specific format designed to provide comprehensive information for both humans and AI assistants."
---
## Task Fields in tasks.json
Tasks in tasks.json have the following structure:
| Field | Description | Example |
| -------------- | ---------------------------------------------- | ------------------------------------------------------ |
| `id` | Unique identifier for the task. | `1` |
| `title` | Brief, descriptive title. | `"Initialize Repo"` |
| `description` | What the task involves. | `"Create a new repository, set up initial structure."` |
| `status` | Current state. | `"pending"`, `"done"`, `"deferred"` |
| `dependencies` | Prerequisite task IDs. ✅ Completed, ⏱️ Pending | `[1, 2]` |
| `priority` | Task importance. | `"high"`, `"medium"`, `"low"` |
| `details` | Implementation instructions. | `"Use GitHub client ID/secret, handle callback..."` |
| `testStrategy` | How to verify success. | `"Deploy and confirm 'Hello World' response."` |
| `subtasks` | Nested subtasks related to the main task. | `[{"id": 1, "title": "Configure OAuth", ...}]` |
## Task File Format
Individual task files follow this format:
```
# Task ID: <id>
# Title: <title>
# Status: <status>
# Dependencies: <comma-separated list of dependency IDs>
# Priority: <priority>
# Description: <brief description>
# Details:
<detailed implementation notes>
# Test Strategy:
<verification approach>
```
## Features in Detail
<AccordionGroup>
<Accordion title="Analyzing Task Complexity">
The `analyze-complexity` command:
- Analyzes each task using AI to assess its complexity on a scale of 1-10
- Recommends optimal number of subtasks based on configured DEFAULT_SUBTASKS
- Generates tailored prompts for expanding each task
- Creates a comprehensive JSON report with ready-to-use commands
- Saves the report to scripts/task-complexity-report.json by default
The generated report contains:
- Complexity analysis for each task (scored 1-10)
- Recommended number of subtasks based on complexity
- AI-generated expansion prompts customized for each task
- Ready-to-run expansion commands directly within each task analysis
</Accordion>
<Accordion title="Viewing Complexity Report">
The `complexity-report` command:
- Displays a formatted, easy-to-read version of the complexity analysis report
- Shows tasks organized by complexity score (highest to lowest)
- Provides complexity distribution statistics (low, medium, high)
- Highlights tasks recommended for expansion based on threshold score
- Includes ready-to-use expansion commands for each complex task
- If no report exists, offers to generate one on the spot
</Accordion>
<Accordion title="Smart Task Expansion">
The `expand` command automatically checks for and uses the complexity report:
When a complexity report exists:
- Tasks are automatically expanded using the recommended subtask count and prompts
- When expanding all tasks, they're processed in order of complexity (highest first)
- Research-backed generation is preserved from the complexity analysis
- You can still override recommendations with explicit command-line options
Example workflow:
```bash
# Generate the complexity analysis report with research capabilities
task-master analyze-complexity --research
# Review the report in a readable format
task-master complexity-report
# Expand tasks using the optimized recommendations
task-master expand --id=8
# or expand all tasks
task-master expand --all
```
</Accordion>
<Accordion title="Finding the Next Task">
The `next` command:
- Identifies tasks that are pending/in-progress and have all dependencies satisfied
- Prioritizes tasks by priority level, dependency count, and task ID
- Displays comprehensive information about the selected task:
- Basic task details (ID, title, priority, dependencies)
- Implementation details
- Subtasks (if they exist)
- Provides contextual suggested actions:
- Command to mark the task as in-progress
- Command to mark the task as done
- Commands for working with subtasks
</Accordion>
<Accordion title="Viewing Specific Task Details">
The `show` command:
- Displays comprehensive details about a specific task or subtask
- Shows task status, priority, dependencies, and detailed implementation notes
- For parent tasks, displays all subtasks and their status
- For subtasks, shows parent task relationship
- Provides contextual action suggestions based on the task's state
- Works with both regular tasks and subtasks (using the format taskId.subtaskId)
</Accordion>
</AccordionGroup>
## Best Practices for AI-Driven Development
<CardGroup cols={2}>
<Card title="📝 Detailed PRD" icon="lightbulb">
The more detailed your PRD, the better the generated tasks will be.
</Card>
<Card title="👀 Review Tasks" icon="magnifying-glass">
After parsing the PRD, review the tasks to ensure they make sense and have appropriate dependencies.
</Card>
<Card title="📊 Analyze Complexity" icon="chart-line">
Use the complexity analysis feature to identify which tasks should be broken down further.
</Card>
<Card title="⛓️ Follow Dependencies" icon="link">
Always respect task dependencies - the Cursor agent will help with this.
</Card>
<Card title="🔄 Update As You Go" icon="arrows-rotate">
If your implementation diverges from the plan, use the update command to keep future tasks aligned.
</Card>
<Card title="📦 Break Down Tasks" icon="boxes-stacked">
Use the expand command to break down complex tasks into manageable subtasks.
</Card>
<Card title="🔄 Regenerate Files" icon="file-arrow-up">
After any updates to tasks.json, regenerate the task files to keep them in sync.
</Card>
<Card title="💬 Provide Context" icon="comment">
When asking the Cursor agent to help with a task, provide context about what you're trying to achieve.
</Card>
<Card title="✅ Validate Dependencies" icon="circle-check">
Periodically run the validate-dependencies command to check for invalid or circular dependencies.
</Card>
</CardGroup>