Merge branch 'next' of github.com:eyaltoledano/claude-task-master into v017-adds

- Fix clear-subtasks test by implementing deep copy of mock data to prevent mutation issues between tests
- Fix add-task test by uncommenting and properly configuring generateTaskFiles call with correct parameters
- Fix analyze-task-complexity tests by properly mocking fs.writeFileSync with shared mock function
- Update test expectations to match actual function signatures and data structures
- Improve mock setup consistency across all test suites
- Ensure all tests now pass (329 total: 318 passed, 11 skipped, 0 failed)

.cursor/rules/taskmaster.mdc

@@ -49,11 +49,13 @@ This document provides a detailed reference for interacting with Taskmaster, cov
 *   **Key Parameters/Options:**
     *   `input`: `Path to your PRD or requirements text file that Taskmaster should parse for tasks.` (CLI: `[file]` positional or `-i, --input <file>`)
     *   `output`: `Specify where Taskmaster should save the generated 'tasks.json' file. Defaults to '.taskmaster/tasks/tasks.json'.` (CLI: `-o, --output <file>`)
+    *   `output`: `Specify where Taskmaster should save the generated 'tasks.json' file. Defaults to '.taskmaster/tasks/tasks.json'.` (CLI: `-o, --output <file>`)
     *   `numTasks`: `Approximate number of top-level tasks Taskmaster should aim to generate from the document.` (CLI: `-n, --num-tasks <number>`)
     *   `force`: `Use this to allow Taskmaster to overwrite an existing 'tasks.json' without asking for confirmation.` (CLI: `-f, --force`)
 *   **Usage:** Useful for bootstrapping a project from an existing requirements document.
 *   **Notes:** Task Master will strictly adhere to any specific requirements mentioned in the PRD, such as libraries, database schemas, frameworks, tech stacks, etc., while filling in any gaps where the PRD isn't fully specified. Tasks are designed to provide the most direct implementation path while avoiding over-engineering.
 *   **Important:** This MCP tool makes AI calls and can take up to a minute to complete. Please inform users to hang tight while the operation is in progress. If the user does not have a PRD, suggest discussing their idea and then use the example PRD in `.taskmaster/templates/example_prd.txt` as a template for creating the PRD based on their idea, for use with `parse-prd`.
+*   **Important:** This MCP tool makes AI calls and can take up to a minute to complete. Please inform users to hang tight while the operation is in progress. If the user does not have a PRD, suggest discussing their idea and then use the example PRD in `.taskmaster/templates/example_prd.txt` as a template for creating the PRD based on their idea, for use with `parse-prd`.
 
 ---
 
@@ -81,9 +83,11 @@ This document provides a detailed reference for interacting with Taskmaster, cov
 *   **Usage (MCP):** Call without set flags to get current config. Use `setMain`, `setResearch`, or `setFallback` with a valid model ID to update the configuration. Use `listAvailableModels: true` to get a list of unassigned models. To set a custom model, provide the model ID and set `ollama: true` or `openrouter: true`.
 *   **Usage (CLI):** Run without flags to view current configuration and available models. Use set flags to update specific roles. Use `--setup` for guided configuration, including custom models. To set a custom model via flags, use `--set-<role>=<model_id>` along with either `--ollama` or `--openrouter`.
 *   **Notes:** Configuration is stored in `.taskmaster/config.json` in the project root. This command/tool modifies that file. Use `listAvailableModels` or `task-master models` to see internally supported models. OpenRouter custom models are validated against their live API. Ollama custom models are not validated live.
+*   **Notes:** Configuration is stored in `.taskmaster/config.json` in the project root. This command/tool modifies that file. Use `listAvailableModels` or `task-master models` to see internally supported models. OpenRouter custom models are validated against their live API. Ollama custom models are not validated live.
 *   **API note:** API keys for selected AI providers (based on their model) need to exist in the mcp.json file to be accessible in MCP context. The API keys must be present in the local .env file for the CLI to be able to read them.
 *   **Model costs:** The costs in supported models are expressed in dollars. An input/output value of 3 is $3.00. A value of 0.8 is $0.80. 
 *   **Warning:** DO NOT MANUALLY EDIT THE .taskmaster/config.json FILE. Use the included commands either in the MCP or CLI format as needed. Always prioritize MCP tools when available and use the CLI as a fallback.
+*   **Warning:** DO NOT MANUALLY EDIT THE .taskmaster/config.json FILE. Use the included commands either in the MCP or CLI format as needed. Always prioritize MCP tools when available and use the CLI as a fallback.
 
 ---
 
@@ -374,6 +378,7 @@ This document provides a detailed reference for interacting with Taskmaster, cov
 *   **Description:** `Display the task complexity analysis report in a readable format.`
 *   **Key Parameters/Options:**
     *   `file`: `Path to the complexity report (default: '.taskmaster/reports/task-complexity-report.json').` (CLI: `-f, --file <file>`)
+    *   `file`: `Path to the complexity report (default: '.taskmaster/reports/task-complexity-report.json').` (CLI: `-f, --file <file>`)
 *   **Usage:** Review and understand the complexity analysis results after running analyze-complexity.
 
 ---
@@ -512,6 +517,7 @@ This new suite of commands allows you to manage different task contexts (tags).
 
 ## Environment Variables Configuration (Updated)
 
+Taskmaster primarily uses the **`.taskmaster/config.json`** file (in project root) for configuration (models, parameters, logging level, etc.), managed via `task-master models --setup`.
 Taskmaster primarily uses the **`.taskmaster/config.json`** file (in project root) for configuration (models, parameters, logging level, etc.), managed via `task-master models --setup`.
 
 Environment variables are used **only** for sensitive API keys related to AI providers and specific overrides like the Ollama base URL:
@@ -526,11 +532,14 @@ Environment variables are used **only** for sensitive API keys related to AI pro
     *   `OPENROUTER_API_KEY`
     *   `XAI_API_KEY`
     *   `OLLAMA_API_KEY` (Requires `OLLAMA_BASE_URL` too)
+*   **Endpoints (Optional/Provider Specific inside .taskmaster/config.json):**
+    *   `OLLAMA_API_KEY` (Requires `OLLAMA_BASE_URL` too)
 *   **Endpoints (Optional/Provider Specific inside .taskmaster/config.json):**
     *   `AZURE_OPENAI_ENDPOINT`
     *   `OLLAMA_BASE_URL` (Default: `http://localhost:11434/api`)
 
 **Set API keys** in your **`.env`** file in the project root (for CLI use) or within the `env` section of your **`.cursor/mcp.json`** file (for MCP/Cursor integration). All other settings (model choice, max tokens, temperature, log level, custom endpoints) are managed in `.taskmaster/config.json` via `task-master models` command or `models` MCP tool.
+**Set API keys** in your **`.env`** file in the project root (for CLI use) or within the `env` section of your **`.cursor/mcp.json`** file (for MCP/Cursor integration). All other settings (model choice, max tokens, temperature, log level, custom endpoints) are managed in `.taskmaster/config.json` via `task-master models` command or `models` MCP tool.
 
 ---
 

.taskmaster/reports/task-complexity-report.json

@@ -1,9 +1,9 @@
 {
 	"meta": {
-		"generatedAt": "2025-05-27T16:34:53.088Z",
-		"tasksAnalyzed": 1,
-		"totalTasks": 84,
-		"analysisCount": 45,
+		"generatedAt": "2025-05-22T05:48:33.026Z",
+		"tasksAnalyzed": 6,
+		"totalTasks": 88,
+		"analysisCount": 43,
 		"thresholdScore": 5,
 		"projectName": "Taskmaster",
 		"usedResearch": true
@@ -313,6 +313,14 @@
 			"expansionPrompt": "Break down the update of ai-services-unified.js for dynamic token limits into subtasks such as: (1) Import and integrate the token counting utility, (2) Refactor _unifiedServiceRunner to calculate and enforce dynamic token limits, (3) Update error handling for token limit violations, (4) Add and verify logging for token usage, (5) Write and execute tests for various prompt and model scenarios.",
 			"reasoning": "This task involves significant code changes to a core function, integration of a new utility, dynamic logic for multiple models, and robust error handling. It also requires comprehensive testing for edge cases and integration, making it moderately complex and best managed by splitting into focused subtasks."
 		},
+		{
+			"taskId": 86,
+			"taskTitle": "Update .taskmasterconfig schema and user guide",
+			"complexityScore": 6,
+			"recommendedSubtasks": 4,
+			"expansionPrompt": "Expand this task into subtasks: (1) Draft a migration guide for users, (2) Update user documentation to explain new config fields, (3) Modify schema validation logic in config-manager.js, (4) Test and validate backward compatibility and error messaging.",
+			"reasoning": "The task spans documentation, schema changes, migration guidance, and validation logic. While not algorithmically complex, it requires careful coordination and thorough testing to ensure a smooth user transition and robust validation."
+		},
 		{
 			"taskId": 87,
 			"taskTitle": "Implement validation and error handling",
@@ -344,30 +352,6 @@
 			"recommendedSubtasks": 5,
 			"expansionPrompt": "Expand this task into: (1) Implement move logic for tasks and subtasks, (2) Handle edge cases (invalid ids, non-existent parents, circular dependencies), (3) Update CLI to support move command with flags, (4) Ensure data integrity and update relationships, (5) Write and execute tests for various move scenarios.",
 			"reasoning": "Moving tasks and subtasks requires careful handling of hierarchical data, edge cases, and data integrity. The command must be robust and user-friendly, necessitating multiple focused subtasks for safe implementation."
-		},
-		{
-			"taskId": 92,
-			"taskTitle": "Add Global Joke Flag to All CLI Commands",
-			"complexityScore": 8,
-			"recommendedSubtasks": 7,
-			"expansionPrompt": "Break down the implementation of the global --joke flag into the following subtasks: (1) Update CLI foundation to support global flags, (2) Develop the joke-service module with joke management and category support, (3) Integrate joke output into existing output utilities, (4) Update all CLI commands for joke flag compatibility, (5) Add configuration options for joke categories and custom jokes, (6) Implement comprehensive testing (flag recognition, output, content, integration, performance, regression), (7) Update documentation and usage examples.",
-			"reasoning": "This task requires changes across the CLI foundation, output utilities, all command modules, and configuration management. It introduces a new service module, global flag handling, and output logic that must not interfere with existing features (including JSON output). The need for robust testing and backward compatibility further increases complexity. The scope spans multiple code areas and requires careful integration, justifying a high complexity score and a detailed subtask breakdown to manage risk and ensure maintainability.[2][3][5]"
-		},
-		{
-			"taskId": 94,
-			"taskTitle": "Implement Standalone 'research' CLI Command for AI-Powered Queries",
-			"complexityScore": 7,
-			"recommendedSubtasks": 6,
-			"expansionPrompt": "Break down the implementation of the 'research' CLI command into logical subtasks covering command registration, parameter handling, context gathering, AI service integration, output formatting, and documentation.",
-			"reasoning": "This task has moderate to high complexity (7/10) due to multiple interconnected components: CLI argument parsing, integration with AI services, context gathering from various sources, and output formatting with different modes. The cyclomatic complexity would be significant with multiple decision paths for handling different flags and options. The task requires understanding existing patterns and extending the codebase in a consistent manner, suggesting the need for careful decomposition into manageable subtasks."
-		},
-		{
-			"taskId": 86,
-			"taskTitle": "Implement GitHub Issue Export Feature",
-			"complexityScore": 9,
-			"recommendedSubtasks": 10,
-			"expansionPrompt": "Break down the implementation of the GitHub Issue Export Feature into detailed subtasks covering: command structure and CLI integration, GitHub API client development, authentication and error handling, task-to-issue mapping logic, content formatting and markdown conversion, bidirectional linking and metadata management, extensible architecture and adapter interfaces, configuration and settings management, documentation, and comprehensive testing (unit, integration, edge cases, performance).",
-			"reasoning": "This task involves designing and implementing a robust, extensible export system with deep integration into GitHub, including bidirectional workflows, complex data mapping, error handling, and support for future platforms. The requirements span CLI design, API integration, content transformation, metadata management, extensibility, configuration, and extensive testing. The breadth and depth of these requirements, along with the need for maintainability and future extensibility, place this task at a high complexity level. Breaking it into at least 10 subtasks will ensure each major component and concern is addressed systematically, reducing risk and improving quality."
 		}
 	]
 }

assets/env.example

@@ -6,5 +6,4 @@ GOOGLE_API_KEY="your_google_api_key_here"             # Optional, for Google Gem
 MISTRAL_API_KEY="your_mistral_key_here"               # Optional, for Mistral AI models.
 XAI_API_KEY="YOUR_XAI_KEY_HERE"                       # Optional, for xAI AI models.
 AZURE_OPENAI_API_KEY="your_azure_key_here"            # Optional, for Azure OpenAI models (requires endpoint in .taskmaster/config.json).
-OLLAMA_API_KEY="your_ollama_api_key_here"             # Optional: For remote Ollama servers that require authentication.
-GITHUB_API_KEY="your_github_api_key_here"             # Optional: For GitHub import/export features. Format: ghp_... or github_pat_...
+OLLAMA_API_KEY="your_ollama_api_key_here"             # Optional: For remote Ollama servers that require authentication.

docs/configuration.md

@@ -8,6 +8,8 @@ Taskmaster uses two primary methods for configuration:
     - This JSON file stores most configuration settings, including AI model selections, parameters, logging levels, and project defaults.
     - **Location:** This file is created in the `.taskmaster/` directory when you run the `task-master models --setup` interactive setup or initialize a new project with `task-master init`.
     - **Migration:** Existing projects with `.taskmasterconfig` in the root will continue to work, but should be migrated to the new structure using `task-master migrate`.
+    - **Location:** This file is created in the `.taskmaster/` directory when you run the `task-master models --setup` interactive setup or initialize a new project with `task-master init`.
+    - **Migration:** Existing projects with `.taskmasterconfig` in the root will continue to work, but should be migrated to the new structure using `task-master migrate`.
     - **Management:** Use the `task-master models --setup` command (or `models` MCP tool) to interactively create and manage this file. You can also set specific models directly using `task-master models --set-<role>=<model_id>`, adding `--ollama` or `--openrouter` flags for custom models. Manual editing is possible but not recommended unless you understand the structure.
     - **Example Structure:**
       ```json
@@ -58,6 +60,35 @@ Taskmaster uses two primary methods for configuration:
 
 ## Environment Variables (`.env` file or MCP `env` block - For API Keys Only)
 
+- Used **exclusively** for sensitive API keys and specific endpoint URLs.
+- **Location:**
+  - For CLI usage: Create a `.env` file in your project root.
+  - For MCP/Cursor usage: Configure keys in the `env` section of your `.cursor/mcp.json` file.
+- **Required API Keys (Depending on configured providers):**
+  - `ANTHROPIC_API_KEY`: Your Anthropic API key.
+  - `PERPLEXITY_API_KEY`: Your Perplexity API key.
+  - `OPENAI_API_KEY`: Your OpenAI API key.
+  - `GOOGLE_API_KEY`: Your Google API key (also used for Vertex AI provider).
+  - `MISTRAL_API_KEY`: Your Mistral API key.
+  - `AZURE_OPENAI_API_KEY`: Your Azure OpenAI API key (also requires `AZURE_OPENAI_ENDPOINT`).
+  - `OPENROUTER_API_KEY`: Your OpenRouter API key.
+  - `XAI_API_KEY`: Your X-AI API key.
+- **Optional Endpoint Overrides:**
+  - **Per-role `baseURL` in `.taskmasterconfig`:** You can add a `baseURL` property to any model role (`main`, `research`, `fallback`) to override the default API endpoint for that provider. If omitted, the provider's standard endpoint is used.
+  - `AZURE_OPENAI_ENDPOINT`: Required if using Azure OpenAI key (can also be set as `baseURL` for the Azure model role).
+  - `OLLAMA_BASE_URL`: Override the default Ollama API URL (Default: `http://localhost:11434/api`).
+  - `VERTEX_PROJECT_ID`: Your Google Cloud project ID for Vertex AI. Required when using the 'vertex' provider.
+  - `VERTEX_LOCATION`: Google Cloud region for Vertex AI (e.g., 'us-central1'). Default is 'us-central1'.
+  - `GOOGLE_APPLICATION_CREDENTIALS`: Path to service account credentials JSON file for Google Cloud auth (alternative to API key for Vertex AI).
+2.  **Legacy `.taskmasterconfig` File (Backward Compatibility)**
+
+    - For projects that haven't migrated to the new structure yet.
+    - **Location:** Project root directory.
+    - **Migration:** Use `task-master migrate` to move this to `.taskmaster/config.json`.
+    - **Deprecation:** While still supported, you'll see warnings encouraging migration to the new structure.
+
+## Environment Variables (`.env` file or MCP `env` block - For API Keys Only)
+
 - Used **exclusively** for sensitive API keys and specific endpoint URLs.
 - **Location:**
   - For CLI usage: Create a `.env` file in your project root.
@@ -145,6 +176,9 @@ PERPLEXITY_API_KEY=pplx-your-key-here
 
 ### Configuration Errors
 
+- If Task Master reports errors about missing configuration or cannot find the config file, run `task-master models --setup` in your project root to create or repair the file.
+- For new projects, config will be created at `.taskmaster/config.json`. For legacy projects, you may want to use `task-master migrate` to move to the new structure.
+- Ensure API keys are correctly placed in your `.env` file (for CLI) or `.cursor/mcp.json` (for MCP) and are valid for the providers selected in your config file.
 - If Task Master reports errors about missing configuration or cannot find the config file, run `task-master models --setup` in your project root to create or repair the file.
 - For new projects, config will be created at `.taskmaster/config.json`. For legacy projects, you may want to use `task-master migrate` to move to the new structure.
 - Ensure API keys are correctly placed in your `.env` file (for CLI) or `.cursor/mcp.json` (for MCP) and are valid for the providers selected in your config file.

mcp-server/src/core/direct-functions/update-subtask-by-id.js

@@ -43,6 +43,7 @@ export async function updateSubtaskByIdDirect(args, log, context = {}) {
 			return {
 				success: false,
 				error: { code: 'MISSING_ARGUMENT', message: errorMessage }
+				error: { code: 'MISSING_ARGUMENT', message: errorMessage }
 			};
 		}
 
@@ -54,6 +55,7 @@ export async function updateSubtaskByIdDirect(args, log, context = {}) {
 			return {
 				success: false,
 				error: { code: 'INVALID_SUBTASK_ID', message: errorMessage }
+				error: { code: 'INVALID_SUBTASK_ID', message: errorMessage }
 			};
 		}
 
@@ -64,6 +66,7 @@ export async function updateSubtaskByIdDirect(args, log, context = {}) {
 			return {
 				success: false,
 				error: { code: 'MISSING_PROMPT', message: errorMessage }
+				error: { code: 'MISSING_PROMPT', message: errorMessage }
 			};
 		}
 
@@ -75,6 +78,7 @@ export async function updateSubtaskByIdDirect(args, log, context = {}) {
 			return {
 				success: false,
 				error: { code: 'INVALID_SUBTASK_ID_TYPE', message: errorMessage }
+				error: { code: 'INVALID_SUBTASK_ID_TYPE', message: errorMessage }
 			};
 		}
 
@@ -85,6 +89,7 @@ export async function updateSubtaskByIdDirect(args, log, context = {}) {
 			return {
 				success: false,
 				error: { code: 'INVALID_SUBTASK_ID_FORMAT', message: errorMessage }
+				error: { code: 'INVALID_SUBTASK_ID_FORMAT', message: errorMessage }
 			};
 		}
 
@@ -124,6 +129,7 @@ export async function updateSubtaskByIdDirect(args, log, context = {}) {
 				return {
 					success: false,
 					error: { code: 'SUBTASK_NOT_FOUND', message: message }
+					error: { code: 'SUBTASK_NOT_FOUND', message: message }
 				};
 			}
 
@@ -151,6 +157,7 @@ export async function updateSubtaskByIdDirect(args, log, context = {}) {
 					code: 'UPDATE_SUBTASK_CORE_ERROR',
 					message: error.message || 'Unknown error updating subtask'
 				}
+				}
 			};
 		} finally {
 			if (!wasSilent && isSilentMode()) {
@@ -168,6 +175,7 @@ export async function updateSubtaskByIdDirect(args, log, context = {}) {
 				code: 'DIRECT_FUNCTION_SETUP_ERROR',
 				message: error.message || 'Unknown setup error'
 			}
+			}
 		};
 	}
 }

mcp-server/src/tools/next-task.js

@@ -1,21 +1,24 @@
 /**
  * tools/next-task.js
  * Tool to find the next task to work on based on dependencies and status
+ * Tool to find the next task to work on based on dependencies and status
  */
 
 import { z } from 'zod';
 import {
 	createErrorResponse,
 	handleApiResult,
+	handleApiResult,
 	withNormalizedProjectRoot
 } from './utils.js';
 import { nextTaskDirect } from '../core/task-master-core.js';
 import {
-	resolveTasksPath,
-	resolveComplexityReportPath
+	findTasksPath,
+	findComplexityReportPath
 } from '../core/utils/path-utils.js';
 
 /**
+ * Register the nextTask tool with the MCP server
  * Register the nextTask tool with the MCP server
  * @param {Object} server - FastMCP server instance
  */
@@ -40,10 +43,13 @@ export function registerNextTaskTool(server) {
 			try {
 				log.info(`Finding next task with args: ${JSON.stringify(args)}`);
 
-				// Resolve the path to tasks.json using new path utilities
+				// Resolve the path to tasks.json
 				let tasksJsonPath;
 				try {
-					tasksJsonPath = resolveTasksPath(args, session);
+					tasksJsonPath = findTasksPath(
+						{ projectRoot: args.projectRoot, file: args.file },
+						log
+					);
 				} catch (error) {
 					log.error(`Error finding tasks.json: ${error.message}`);
 					return createErrorResponse(
@@ -51,16 +57,26 @@ export function registerNextTaskTool(server) {
 					);
 				}
 
+				// Resolve the path to complexity report (optional)
 				// Resolve the path to complexity report (optional)
 				let complexityReportPath;
 				try {
-					complexityReportPath = resolveComplexityReportPath(args, session);
+					complexityReportPath = findComplexityReportPath(
+						{
+							projectRoot: args.projectRoot,
+							complexityReport: args.complexityReport
+						},
+						log
+					);
 				} catch (error) {
 					log.error(`Error finding complexity report: ${error.message}`);
 					// This is optional, so we don't fail the operation
 					complexityReportPath = null;
+					// This is optional, so we don't fail the operation
+					complexityReportPath = null;
 				}
 
+
 				const result = await nextTaskDirect(
 					{
 						tasksJsonPath: tasksJsonPath,
@@ -80,6 +96,7 @@ export function registerNextTaskTool(server) {
 					args.projectRoot
 				);
 			} catch (error) {
+				log.error(`Error finding next task: ${error.message}`);
 				log.error(`Error finding next task: ${error.message}`);
 				return createErrorResponse(error.message);
 			}

mcp-server/src/tools/parse-prd.js

@@ -8,6 +8,8 @@ import {
 	handleApiResult,
 	withNormalizedProjectRoot,
 	createErrorResponse
+	withNormalizedProjectRoot,
+	createErrorResponse
 } from './utils.js';
 import { parsePRDDirect } from '../core/task-master-core.js';
 import {
@@ -15,6 +17,11 @@ import {
 	TASKMASTER_DOCS_DIR,
 	TASKMASTER_TASKS_FILE
 } from '../../../src/constants/paths.js';
+import {
+	PRD_FILE,
+	TASKMASTER_DOCS_DIR,
+	TASKMASTER_TASKS_FILE
+} from '../../../src/constants/paths.js';
 
 /**
  * Register the parse_prd tool
@@ -24,11 +31,13 @@ export function registerParsePRDTool(server) {
 	server.addTool({
 		name: 'parse_prd',
 		description: `Parse a Product Requirements Document (PRD) text file to automatically generate initial tasks. Reinitializing the project is not necessary to run this tool. It is recommended to run parse-prd after initializing the project and creating/importing a prd.txt file in the project root's ${TASKMASTER_DOCS_DIR} directory.`,
+		description: `Parse a Product Requirements Document (PRD) text file to automatically generate initial tasks. Reinitializing the project is not necessary to run this tool. It is recommended to run parse-prd after initializing the project and creating/importing a prd.txt file in the project root's ${TASKMASTER_DOCS_DIR} directory.`,
 		parameters: z.object({
 			input: z
 				.string()
 				.optional()
 				.default(PRD_FILE)
+				.default(PRD_FILE)
 				.describe('Absolute path to the PRD document file (.txt, .md, etc.)'),
 			projectRoot: z
 				.string()
@@ -39,6 +48,15 @@ export function registerParsePRDTool(server) {
 				.describe(
 					`Output path for tasks.json file (default: ${TASKMASTER_TASKS_FILE})`
 				),
+			projectRoot: z
+				.string()
+				.describe('The directory of the project. Must be an absolute path.'),
+			output: z
+				.string()
+				.optional()
+				.describe(
+					`Output path for tasks.json file (default: ${TASKMASTER_TASKS_FILE})`
+				),
 			numTasks: z
 				.string()
 				.optional()
@@ -55,11 +73,16 @@ export function registerParsePRDTool(server) {
 				.optional()
 				.describe(
 					'Enable Taskmaster to use the research role for potentially more informed task generation. Requires appropriate API key.'
+					'Enable Taskmaster to use the research role for potentially more informed task generation. Requires appropriate API key.'
 				),
 			append: z
 				.boolean()
 				.optional()
 				.describe('Append generated tasks to existing file.')
+			append: z
+				.boolean()
+				.optional()
+				.describe('Append generated tasks to existing file.')
 		}),
 		execute: withNormalizedProjectRoot(async (args, { log, session }) => {
 			try {
@@ -74,6 +97,8 @@ export function registerParsePRDTool(server) {
 			} catch (error) {
 				log.error(`Error in parse_prd: ${error.message}`);
 				return createErrorResponse(`Failed to parse PRD: ${error.message}`);
+				log.error(`Error in parse_prd: ${error.message}`);
+				return createErrorResponse(`Failed to parse PRD: ${error.message}`);
 			}
 		})
 	});

mcp-server/src/tools/utils.js

@@ -304,6 +304,7 @@ function getProjectRootFromSession(session, log) {
  * @param {string} [projectRoot] - Optional project root for tag information
  * @returns {Object} - Standardized MCP response object
  */
+async function handleApiResult(
 async function handleApiResult(
 	result,
 	log,
@@ -329,11 +330,14 @@ async function handleApiResult(
 		: result.data;
 
 	log.info('Successfully completed operation');
+	log.info('Successfully completed operation');
 
 	// Create the response payload including version info and tag info
 	const responsePayload = {
 		data: processedData,
 		version: versionInfo
+		data: processedData,
+		version: versionInfo
 	};
 
 	// Add tag information if available
@@ -436,6 +440,8 @@ function executeTaskMasterCommand(
  * @param {Object} options.log - The logger instance.
  * @returns {Promise<Object>} - An object containing the result.
  *                              Format: { success: boolean, data?: any, error?: { code: string, message: string } }
+ * @returns {Promise<Object>} - An object containing the result.
+ *                              Format: { success: boolean, data?: any, error?: { code: string, message: string } }
  */
 async function getCachedOrExecute({ cacheKey, actionFn, log }) {
 	// Check cache first
@@ -444,6 +450,7 @@ async function getCachedOrExecute({ cacheKey, actionFn, log }) {
 	if (cachedResult !== undefined) {
 		log.info(`Cache hit for key: ${cacheKey}`);
 		return cachedResult;
+		return cachedResult;
 	}
 
 	log.info(`Cache miss for key: ${cacheKey}. Executing action function.`);
@@ -451,10 +458,12 @@ async function getCachedOrExecute({ cacheKey, actionFn, log }) {
 	// Execute the action function if cache missed
 	const result = await actionFn();
 
+	// If the action was successful, cache the result
 	// If the action was successful, cache the result
 	if (result.success && result.data !== undefined) {
 		log.info(`Action successful. Caching result for key: ${cacheKey}`);
 		contextManager.setCachedData(cacheKey, result);
+		contextManager.setCachedData(cacheKey, result);
 	} else if (!result.success) {
 		log.warn(
 			`Action failed for cache key ${cacheKey}. Result not cached. Error: ${result.error?.message}`
@@ -466,6 +475,7 @@ async function getCachedOrExecute({ cacheKey, actionFn, log }) {
 	}
 
 	return result;
+	return result;
 }
 
 /**

scripts/modules/commands.js

@@ -42,6 +42,8 @@ import {
 	taskExists,
 	moveTask,
 	migrateProject
+	moveTask,
+	migrateProject
 } from './task-manager.js';
 
 import {
@@ -111,6 +113,8 @@ import {
 import { getTaskMasterVersion } from '../../src/utils/getVersion.js';
 import { syncTasksToReadme } from './sync-readme.js';
 
+import { syncTasksToReadme } from './sync-readme.js';
+
 /**
  * Runs the interactive setup process for model configuration.
  * @param {string|null} projectRoot - The resolved project root directory.
@@ -327,6 +331,7 @@ async function runInteractiveSetup(projectRoot) {
 		commonPrefix.push(customOllamaOption);
 		commonPrefix.push(customBedrockOption);
 
+		const prefixLength = commonPrefix.length; // Initial prefix length
 		const prefixLength = commonPrefix.length; // Initial prefix length
 
 		if (allowNone) {
@@ -521,6 +526,7 @@ async function runInteractiveSetup(projectRoot) {
 				console.error(
 					chalk.red(
 						'Error: AWS_ACCESS_KEY_ID and/or AWS_SECRET_ACCESS_KEY environment variables are missing. Please set them before using custom Bedrock models.'
+						'Error: AWS_ACCESS_KEY_ID and/or AWS_SECRET_ACCESS_KEY environment variables are missing. Please set them before using custom Bedrock models.'
 					)
 				);
 				setupSuccess = false;
@@ -679,6 +685,7 @@ function registerCommands(programInstance) {
 			'Path to the PRD file (alternative to positional argument)'
 		)
 		.option('-o, --output <file>', 'Output file path', TASKMASTER_TASKS_FILE)
+		.option('-o, --output <file>', 'Output file path', TASKMASTER_TASKS_FILE)
 		.option('-n, --num-tasks <number>', 'Number of tasks to generate', '10')
 		.option('-f, --force', 'Skip confirmation when overwriting existing tasks')
 		.option(
@@ -694,6 +701,7 @@ function registerCommands(programInstance) {
 			// Use input option if file argument not provided
 			const inputFile = file || options.input;
 			const defaultPrdPath = PRD_FILE;
+			const defaultPrdPath = PRD_FILE;
 			const numTasks = parseInt(options.numTasks, 10);
 			const outputPath = options.output;
 			const force = options.force || false;
@@ -778,10 +786,12 @@ function registerCommands(programInstance) {
 					console.log(
 						chalk.yellow(
 							`No PRD file specified and default PRD file not found at ${PRD_FILE}.`
+							`No PRD file specified and default PRD file not found at ${PRD_FILE}.`
 						)
 					);
 					console.log(
 						boxen(
+							`${chalk.white.bold('Parse PRD Help')}\n\n${chalk.cyan('Usage:')}\n  task-master parse-prd <prd-file.txt> [options]\n\n${chalk.cyan('Options:')}\n  -i, --input <file>       Path to the PRD file (alternative to positional argument)\n  -o, --output <file>      Output file path (default: "${TASKMASTER_TASKS_FILE}")\n  -n, --num-tasks <number> Number of tasks to generate (default: 10)\n  -f, --force              Skip confirmation when overwriting existing tasks\n  --append                 Append new tasks to existing tasks.json instead of overwriting\n  -r, --research           Use Perplexity AI for research-backed task generation\n\n${chalk.cyan('Example:')}\n  task-master parse-prd requirements.txt --num-tasks 15\n  task-master parse-prd --input=requirements.txt\n  task-master parse-prd --force\n  task-master parse-prd requirements_v2.txt --append\n  task-master parse-prd requirements.txt --research\n\n${chalk.yellow('Note: This command will:')}\n  1. Look for a PRD file at ${PRD_FILE} by default\n  2. Use the file specified by --input or positional argument if provided\n  3. Generate tasks from the PRD and either:\n     - Overwrite any existing tasks.json file (default)\n     - Append to existing tasks.json if --append is used`,
 							`${chalk.white.bold('Parse PRD Help')}\n\n${chalk.cyan('Usage:')}\n  task-master parse-prd <prd-file.txt> [options]\n\n${chalk.cyan('Options:')}\n  -i, --input <file>       Path to the PRD file (alternative to positional argument)\n  -o, --output <file>      Output file path (default: "${TASKMASTER_TASKS_FILE}")\n  -n, --num-tasks <number> Number of tasks to generate (default: 10)\n  -f, --force              Skip confirmation when overwriting existing tasks\n  --append                 Append new tasks to existing tasks.json instead of overwriting\n  -r, --research           Use Perplexity AI for research-backed task generation\n\n${chalk.cyan('Example:')}\n  task-master parse-prd requirements.txt --num-tasks 15\n  task-master parse-prd --input=requirements.txt\n  task-master parse-prd --force\n  task-master parse-prd requirements_v2.txt --append\n  task-master parse-prd requirements.txt --research\n\n${chalk.yellow('Note: This command will:')}\n  1. Look for a PRD file at ${PRD_FILE} by default\n  2. Use the file specified by --input or positional argument if provided\n  3. Generate tasks from the PRD and either:\n     - Overwrite any existing tasks.json file (default)\n     - Append to existing tasks.json if --append is used`,
 							{ padding: 1, borderColor: 'blue', borderStyle: 'round' }
 						)
@@ -841,6 +851,11 @@ function registerCommands(programInstance) {
 			'Path to the tasks file',
 			TASKMASTER_TASKS_FILE
 		)
+		.option(
+			'-f, --file <file>',
+			'Path to the tasks file',
+			TASKMASTER_TASKS_FILE
+		)
 		.option(
 			'--from <id>',
 			'Task ID to start updating from (tasks with ID >= this value will be updated)',
@@ -856,6 +871,7 @@ function registerCommands(programInstance) {
 		)
 		.option('--tag <tag>', 'Specify tag context for task operations')
 		.action(async (options) => {
+			const tasksPath = options.file || TASKMASTER_TASKS_FILE;
 			const tasksPath = options.file || TASKMASTER_TASKS_FILE;
 			const fromId = parseInt(options.from, 10); // Validation happens here
 			const prompt = options.prompt;
@@ -939,6 +955,11 @@ function registerCommands(programInstance) {
 			'Path to the tasks file',
 			TASKMASTER_TASKS_FILE
 		)
+		.option(
+			'-f, --file <file>',
+			'Path to the tasks file',
+			TASKMASTER_TASKS_FILE
+		)
 		.option('-i, --id <id>', 'Task ID to update (required)')
 		.option(
 			'-p, --prompt <text>',
@@ -982,6 +1003,7 @@ function registerCommands(programInstance) {
 
 				// Parse the task ID and validate it's a number
 				const taskId = parseInt(options.id, 10);
+				if (Number.isNaN(taskId) || taskId <= 0) {
 				if (Number.isNaN(taskId) || taskId <= 0) {
 					console.error(
 						chalk.red(
@@ -1018,6 +1040,7 @@ function registerCommands(programInstance) {
 					console.error(
 						chalk.red(`Error: Tasks file not found at path: ${tasksPath}`)
 					);
+					if (tasksPath === TASKMASTER_TASKS_FILE) {
 					if (tasksPath === TASKMASTER_TASKS_FILE) {
 						console.log(
 							chalk.yellow(
@@ -1116,6 +1139,11 @@ function registerCommands(programInstance) {
 			'Path to the tasks file',
 			TASKMASTER_TASKS_FILE
 		)
+		.option(
+			'-f, --file <file>',
+			'Path to the tasks file',
+			TASKMASTER_TASKS_FILE
+		)
 		.option(
 			'-i, --id <id>',
 			'Subtask ID to update in format "parentId.subtaskId" (required)'
@@ -1191,6 +1219,7 @@ function registerCommands(programInstance) {
 					console.error(
 						chalk.red(`Error: Tasks file not found at path: ${tasksPath}`)
 					);
+					if (tasksPath === TASKMASTER_TASKS_FILE) {
 					if (tasksPath === TASKMASTER_TASKS_FILE) {
 						console.log(
 							chalk.yellow(
@@ -1295,6 +1324,7 @@ function registerCommands(programInstance) {
 		)
 		.option('--tag <tag>', 'Specify tag context for task operations')
 		.action(async (options) => {
+			const tasksPath = options.file || TASKMASTER_TASKS_FILE;
 			const tasksPath = options.file || TASKMASTER_TASKS_FILE;
 			const outputDir = options.output;
 			const tag = options.tag;
@@ -1332,6 +1362,7 @@ function registerCommands(programInstance) {
 		)
 		.option('--tag <tag>', 'Specify tag context for task operations')
 		.action(async (options) => {
+			const tasksPath = options.file || TASKMASTER_TASKS_FILE;
 			const tasksPath = options.file || TASKMASTER_TASKS_FILE;
 			const taskId = options.id;
 			const status = options.status;
@@ -1379,10 +1410,16 @@ function registerCommands(programInstance) {
 			'Path to the tasks file',
 			TASKMASTER_TASKS_FILE
 		)
+		.option(
+			'-f, --file <file>',
+			'Path to the tasks file',
+			TASKMASTER_TASKS_FILE
+		)
 		.option(
 			'-r, --report <report>',
 			'Path to the complexity report file',
 			COMPLEXITY_REPORT_FILE
+			COMPLEXITY_REPORT_FILE
 		)
 		.option('-s, --status <status>', 'Filter by status')
 		.option('--with-subtasks', 'Show subtasks for each task')
@@ -1446,6 +1483,7 @@ function registerCommands(programInstance) {
 			'--file <file>',
 			'Path to the tasks file (relative to project root)',
 			TASKMASTER_TASKS_FILE // Allow file override
+			TASKMASTER_TASKS_FILE // Allow file override
 		) // Allow file override
 		.option('--tag <tag>', 'Specify tag context for task operations')
 		.action(async (options) => {
@@ -1526,6 +1564,7 @@ function registerCommands(programInstance) {
 			'-o, --output <file>',
 			'Output file path for the report',
 			COMPLEXITY_REPORT_FILE
+			COMPLEXITY_REPORT_FILE
 		)
 		.option(
 			'-m, --model <model>',
@@ -1541,6 +1580,11 @@ function registerCommands(programInstance) {
 			'Path to the tasks file',
 			TASKMASTER_TASKS_FILE
 		)
+		.option(
+			'-f, --file <file>',
+			'Path to the tasks file',
+			TASKMASTER_TASKS_FILE
+		)
 		.option(
 			'-r, --research',
 			'Use Perplexity AI for research-backed complexity analysis'
@@ -1969,6 +2013,11 @@ ${result.result}
 			'Path to the tasks file',
 			TASKMASTER_TASKS_FILE
 		)
+		.option(
+			'-f, --file <file>',
+			'Path to the tasks file',
+			TASKMASTER_TASKS_FILE
+		)
 		.option(
 			'-i, --id <ids>',
 			'Task IDs (comma-separated) to clear subtasks from'
@@ -1976,6 +2025,7 @@ ${result.result}
 		.option('--all', 'Clear subtasks from all tasks')
 		.option('--tag <tag>', 'Specify tag context for task operations')
 		.action(async (options) => {
+			const tasksPath = options.file || TASKMASTER_TASKS_FILE;
 			const tasksPath = options.file || TASKMASTER_TASKS_FILE;
 			const taskIds = options.id;
 			const all = options.all;
@@ -2022,6 +2072,11 @@ ${result.result}
 			'Path to the tasks file',
 			TASKMASTER_TASKS_FILE
 		)
+		.option(
+			'-f, --file <file>',
+			'Path to the tasks file',
+			TASKMASTER_TASKS_FILE
+		)
 		.option(
 			'-p, --prompt <prompt>',
 			'Description of the task to add (required if not using manual fields)'
@@ -2064,6 +2119,14 @@ ${result.result}
 
 			const tasksPath = options.file || TASKMASTER_TASKS_FILE;
 
+			if (!fs.existsSync(tasksPath)) {
+				console.error(
+					`❌ No tasks.json file found. Please run "task-master init" or create a tasks.json file at ${TASKMASTER_TASKS_FILE}`
+				);
+				process.exit(1);
+			}
+			const tasksPath = options.file || TASKMASTER_TASKS_FILE;
+
 			if (!fs.existsSync(tasksPath)) {
 				console.error(
 					`❌ No tasks.json file found. Please run "task-master init" or create a tasks.json file at ${TASKMASTER_TASKS_FILE}`
@@ -2156,13 +2219,20 @@ ${result.result}
 			'Path to the tasks file',
 			TASKMASTER_TASKS_FILE
 		)
+		.option(
+			'-f, --file <file>',
+			'Path to the tasks file',
+			TASKMASTER_TASKS_FILE
+		)
 		.option(
 			'-r, --report <report>',
 			'Path to the complexity report file',
 			COMPLEXITY_REPORT_FILE
+			COMPLEXITY_REPORT_FILE
 		)
 		.option('--tag <tag>', 'Specify tag context for task operations')
 		.action(async (options) => {
+			const tasksPath = options.file || TASKMASTER_TASKS_FILE;
 			const tasksPath = options.file || TASKMASTER_TASKS_FILE;
 			const reportPath = options.report;
 			const tag = options.tag;
@@ -2200,6 +2270,7 @@ ${result.result}
 			'-r, --report <report>',
 			'Path to the complexity report file',
 			COMPLEXITY_REPORT_FILE
+			COMPLEXITY_REPORT_FILE
 		)
 		.option('--tag <tag>', 'Specify tag context for task operations')
 		.action(async (taskId, options) => {
@@ -2221,6 +2292,7 @@ ${result.result}
 				process.exit(1);
 			}
 
+			const tasksPath = options.file || TASKMASTER_TASKS_FILE;
 			const tasksPath = options.file || TASKMASTER_TASKS_FILE;
 			const reportPath = options.report;
 
@@ -2265,6 +2337,7 @@ ${result.result}
 		)
 		.option('--tag <tag>', 'Specify tag context for task operations')
 		.action(async (options) => {
+			const tasksPath = options.file || TASKMASTER_TASKS_FILE;
 			const tasksPath = options.file || TASKMASTER_TASKS_FILE;
 			const taskId = options.id;
 			const dependencyId = options.dependsOn;
@@ -2316,6 +2389,7 @@ ${result.result}
 		)
 		.option('--tag <tag>', 'Specify tag context for task operations')
 		.action(async (options) => {
+			const tasksPath = options.file || TASKMASTER_TASKS_FILE;
 			const tasksPath = options.file || TASKMASTER_TASKS_FILE;
 			const taskId = options.id;
 			const dependencyId = options.dependsOn;
@@ -2425,6 +2499,7 @@ ${result.result}
 			'-f, --file <file>',
 			'Path to the report file',
 			COMPLEXITY_REPORT_FILE
+			COMPLEXITY_REPORT_FILE
 		)
 		.option('--tag <tag>', 'Specify tag context for task operations')
 		.action(async (options) => {
@@ -2458,6 +2533,11 @@ ${result.result}
 			'Path to the tasks file',
 			TASKMASTER_TASKS_FILE
 		)
+		.option(
+			'-f, --file <file>',
+			'Path to the tasks file',
+			TASKMASTER_TASKS_FILE
+		)
 		.option('-p, --parent <id>', 'Parent task ID (required)')
 		.option('-i, --task-id <id>', 'Existing task ID to convert to subtask')
 		.option(
@@ -2633,6 +2713,7 @@ ${result.result}
 	function showAddSubtaskHelp() {
 		console.log(
 			boxen(
+				`${chalk.white.bold('Add Subtask Command Help')}\n\n${chalk.cyan('Usage:')}\n  task-master add-subtask --parent=<id> [options]\n\n${chalk.cyan('Options:')}\n  -p, --parent <id>         Parent task ID (required)\n  -i, --task-id <id>        Existing task ID to convert to subtask\n  -t, --title <title>       Title for the new subtask\n  -d, --description <text>  Description for the new subtask\n  --details <text>          Implementation details for the new subtask\n  --dependencies <ids>      Comma-separated list of dependency IDs\n  -s, --status <status>     Status for the new subtask (default: "pending")\n  -f, --file <file>         Path to the tasks file (default: "${TASKMASTER_TASKS_FILE}")\n  --skip-generate           Skip regenerating task files\n\n${chalk.cyan('Examples:')}\n  task-master add-subtask --parent=5 --task-id=8\n  task-master add-subtask -p 5 -t "Implement login UI" -d "Create the login form"`,
 				`${chalk.white.bold('Add Subtask Command Help')}\n\n${chalk.cyan('Usage:')}\n  task-master add-subtask --parent=<id> [options]\n\n${chalk.cyan('Options:')}\n  -p, --parent <id>         Parent task ID (required)\n  -i, --task-id <id>        Existing task ID to convert to subtask\n  -t, --title <title>       Title for the new subtask\n  -d, --description <text>  Description for the new subtask\n  --details <text>          Implementation details for the new subtask\n  --dependencies <ids>      Comma-separated list of dependency IDs\n  -s, --status <status>     Status for the new subtask (default: "pending")\n  -f, --file <file>         Path to the tasks file (default: "${TASKMASTER_TASKS_FILE}")\n  --skip-generate           Skip regenerating task files\n\n${chalk.cyan('Examples:')}\n  task-master add-subtask --parent=5 --task-id=8\n  task-master add-subtask -p 5 -t "Implement login UI" -d "Create the login form"`,
 				{ padding: 1, borderColor: 'blue', borderStyle: 'round' }
 			)
@@ -2648,6 +2729,11 @@ ${result.result}
 			'Path to the tasks file',
 			TASKMASTER_TASKS_FILE
 		)
+		.option(
+			'-f, --file <file>',
+			'Path to the tasks file',
+			TASKMASTER_TASKS_FILE
+		)
 		.option(
 			'-i, --id <id>',
 			'Subtask ID(s) to remove in format "parentId.subtaskId" (can be comma-separated for multiple subtasks)'
@@ -2659,6 +2745,7 @@ ${result.result}
 		.option('--skip-generate', 'Skip regenerating task files')
 		.option('--tag <tag>', 'Specify tag context for task operations')
 		.action(async (options) => {
+			const tasksPath = options.file || TASKMASTER_TASKS_FILE;
 			const tasksPath = options.file || TASKMASTER_TASKS_FILE;
 			const subtaskIds = options.id;
 			const convertToTask = options.convert || false;
@@ -2790,6 +2877,9 @@ ${result.result}
 					'  -f, --file <file>   Path to the tasks file (default: "' +
 					TASKMASTER_TASKS_FILE +
 					'")\n' +
+					'  -f, --file <file>   Path to the tasks file (default: "' +
+					TASKMASTER_TASKS_FILE +
+					'")\n' +
 					'  --skip-generate     Skip regenerating task files\n\n' +
 					chalk.cyan('Examples:') +
 					'\n' +
@@ -2959,9 +3049,15 @@ ${result.result}
 			'Path to the tasks file',
 			TASKMASTER_TASKS_FILE
 		)
+		.option(
+			'-f, --file <file>',
+			'Path to the tasks file',
+			TASKMASTER_TASKS_FILE
+		)
 		.option('-y, --yes', 'Skip confirmation prompt', false)
 		.option('--tag <tag>', 'Specify tag context for task operations')
 		.action(async (options) => {
+			const tasksPath = options.file || TASKMASTER_TASKS_FILE;
 			const tasksPath = options.file || TASKMASTER_TASKS_FILE;
 			const taskIdsString = options.id;
 
@@ -3479,6 +3575,11 @@ Examples:
 			'Path to the tasks file',
 			TASKMASTER_TASKS_FILE
 		)
+		.option(
+			'-f, --file <file>',
+			'Path to the tasks file',
+			TASKMASTER_TASKS_FILE
+		)
 		.option(
 			'--from <id>',
 			'ID of the task/subtask to move (e.g., "5" or "5.2"). Can be comma-separated to move multiple tasks (e.g., "5,6,7")'
@@ -3489,6 +3590,7 @@ Examples:
 		)
 		.option('--tag <tag>', 'Specify tag context for task operations')
 		.action(async (options) => {
+			const tasksPath = options.file || TASKMASTER_TASKS_FILE;
 			const tasksPath = options.file || TASKMASTER_TASKS_FILE;
 			const sourceId = options.from;
 			const destinationId = options.to;
@@ -4289,6 +4391,7 @@ async function runCLI(argv = process.argv) {
 		// Setup and parse
 		// NOTE: getConfig() might be called during setupCLI->registerCommands if commands need config
 		// This means the ConfigurationError might be thrown here if configuration file is missing.
+		// This means the ConfigurationError might be thrown here if configuration file is missing.
 		const programInstance = setupCLI();
 		await programInstance.parseAsync(argv);
 
@@ -4348,7 +4451,10 @@ async function runCLI(argv = process.argv) {
 						'\n\n' +
 						chalk.white('Taskmaster now uses a ') +
 						chalk.yellow.bold('configuration file') +
+						chalk.white('Taskmaster now uses a ') +
+						chalk.yellow.bold('configuration file') +
 						chalk.white(
+							' in your project for AI model choices and settings.\n\n' +
 							' in your project for AI model choices and settings.\n\n' +
 								'This file appears to be '
 						) +
@@ -4362,6 +4468,7 @@ async function runCLI(argv = process.argv) {
 						'\n' +
 						chalk.white('*   ') +
 						chalk.yellow.bold('Configuration file') +
+						chalk.yellow.bold('Configuration file') +
 						chalk.white(
 							': Stores your AI model settings (do not manually edit)\n'
 						) +

scripts/modules/task-manager/expand-task.js

@@ -421,7 +421,10 @@ async function expandTask(
 	const outputFormat = mcpLog ? 'json' : 'text';
 
 	// Determine projectRoot: Use from context if available, otherwise derive from tasksPath
-	const projectRoot = contextProjectRoot || findProjectRoot(tasksPath);
+	const projectRoot =
+		contextProjectRoot ||
+		findProjectRoot() ||
+		path.dirname(path.dirname(tasksPath));
 
 	// Use mcpLog if available, otherwise use the default console log wrapper
 	const logger = mcpLog || {

scripts/modules/task-manager/list-tasks.js

@@ -213,6 +213,78 @@ function listTasks(
 		// Find next task to work on, passing the complexity report
 		const nextItem = findNextTask(data.tasks, complexityReport);
 
+		// Calculate dependency statistics (moved up to be available for all output formats)
+		const completedTaskIds = new Set(
+			data.tasks
+				.filter((t) => t.status === 'done' || t.status === 'completed')
+				.map((t) => t.id)
+		);
+
+		const tasksWithNoDeps = data.tasks.filter(
+			(t) =>
+				t.status !== 'done' &&
+				t.status !== 'completed' &&
+				(!t.dependencies || t.dependencies.length === 0)
+		).length;
+
+		const tasksWithAllDepsSatisfied = data.tasks.filter(
+			(t) =>
+				t.status !== 'done' &&
+				t.status !== 'completed' &&
+				t.dependencies &&
+				t.dependencies.length > 0 &&
+				t.dependencies.every((depId) => completedTaskIds.has(depId))
+		).length;
+
+		const tasksWithUnsatisfiedDeps = data.tasks.filter(
+			(t) =>
+				t.status !== 'done' &&
+				t.status !== 'completed' &&
+				t.dependencies &&
+				t.dependencies.length > 0 &&
+				!t.dependencies.every((depId) => completedTaskIds.has(depId))
+		).length;
+
+		// Calculate total tasks ready to work on (no deps + satisfied deps)
+		const tasksReadyToWork = tasksWithNoDeps + tasksWithAllDepsSatisfied;
+
+		// Calculate most depended-on tasks
+		const dependencyCount = {};
+		data.tasks.forEach((task) => {
+			if (task.dependencies && task.dependencies.length > 0) {
+				task.dependencies.forEach((depId) => {
+					dependencyCount[depId] = (dependencyCount[depId] || 0) + 1;
+				});
+			}
+		});
+
+		// Find the most depended-on task
+		let mostDependedOnTaskId = null;
+		let maxDependents = 0;
+
+		for (const [taskId, count] of Object.entries(dependencyCount)) {
+			if (count > maxDependents) {
+				maxDependents = count;
+				mostDependedOnTaskId = parseInt(taskId);
+			}
+		}
+
+		// Get the most depended-on task
+		const mostDependedOnTask =
+			mostDependedOnTaskId !== null
+				? data.tasks.find((t) => t.id === mostDependedOnTaskId)
+				: null;
+
+		// Calculate average dependencies per task
+		const totalDependencies = data.tasks.reduce(
+			(sum, task) => sum + (task.dependencies ? task.dependencies.length : 0),
+			0
+		);
+		const avgDependenciesPerTask = totalDependencies / data.tasks.length;
+
+		// Find next task to work on, passing the complexity report
+		const nextItem = findNextTask(data.tasks, complexityReport);
+
 		// For JSON output, return structured data
 		if (outputFormat === 'json') {
 			// *** Modification: Remove 'details' field for JSON output ***
@@ -1045,4 +1117,232 @@ function generateMarkdownOutput(data, filteredTasks, stats) {
 	return markdown;
 }
 
+/**
+ * Generate markdown-formatted output for README files
+ * @param {Object} data - Full tasks data
+ * @param {Array} filteredTasks - Filtered tasks array
+ * @param {Object} stats - Statistics object
+ * @returns {string} - Formatted markdown string
+ */
+function generateMarkdownOutput(data, filteredTasks, stats) {
+	const {
+		totalTasks,
+		completedTasks,
+		completionPercentage,
+		doneCount,
+		inProgressCount,
+		pendingCount,
+		blockedCount,
+		deferredCount,
+		cancelledCount,
+		totalSubtasks,
+		completedSubtasks,
+		subtaskCompletionPercentage,
+		inProgressSubtasks,
+		pendingSubtasks,
+		blockedSubtasks,
+		deferredSubtasks,
+		cancelledSubtasks,
+		tasksWithNoDeps,
+		tasksReadyToWork,
+		tasksWithUnsatisfiedDeps,
+		mostDependedOnTask,
+		mostDependedOnTaskId,
+		maxDependents,
+		avgDependenciesPerTask,
+		complexityReport,
+		withSubtasks,
+		nextItem
+	} = stats;
+
+	let markdown = '';
+
+	// Create progress bars for markdown (using Unicode block characters)
+	const createMarkdownProgressBar = (percentage, width = 20) => {
+		const filled = Math.round((percentage / 100) * width);
+		const empty = width - filled;
+		return '█'.repeat(filled) + '░'.repeat(empty);
+	};
+
+	// Dashboard section
+	markdown += '```\n';
+	markdown +=
+		'╭─────────────────────────────────────────────────────────╮╭─────────────────────────────────────────────────────────╮\n';
+	markdown +=
+		'│                                                         ││                                                         │\n';
+	markdown +=
+		'│   Project Dashboard                                     ││   Dependency Status & Next Task                         │\n';
+	markdown += `│   Tasks Progress: ${createMarkdownProgressBar(completionPercentage, 20)} ${Math.round(completionPercentage)}%    ││   Dependency Metrics:                                   │\n`;
+	markdown += `│   ${Math.round(completionPercentage)}%                                                   ││   • Tasks with no dependencies: ${tasksWithNoDeps}                      │\n`;
+	markdown += `│   Done: ${doneCount}  In Progress: ${inProgressCount}  Pending: ${pendingCount}  Blocked: ${blockedCount}     ││   • Tasks ready to work on: ${tasksReadyToWork}                          │\n`;
+	markdown += `│   Deferred: ${deferredCount}  Cancelled: ${cancelledCount}                             ││   • Tasks blocked by dependencies: ${tasksWithUnsatisfiedDeps}                    │\n`;
+	markdown += `│                                                         ││   • Most depended-on task: #${mostDependedOnTaskId} (${maxDependents} dependents)           │\n`;
+	markdown += `│   Subtasks Progress: ${createMarkdownProgressBar(subtaskCompletionPercentage, 20)}     ││   • Avg dependencies per task: ${avgDependenciesPerTask.toFixed(1)}                      │\n`;
+	markdown += `│   ${Math.round(subtaskCompletionPercentage)}% ${Math.round(subtaskCompletionPercentage)}%                                               ││                                                         │\n`;
+	markdown += `│   Completed: ${completedSubtasks}/${totalSubtasks}  In Progress: ${inProgressSubtasks}  Pending: ${pendingSubtasks}      ││   Next Task to Work On:                                 │\n`;
+
+	const nextTaskTitle = nextItem
+		? nextItem.title.length > 40
+			? nextItem.title.substring(0, 37) + '...'
+			: nextItem.title
+		: 'No task available';
+
+	markdown += `│   Blocked: ${blockedSubtasks}  Deferred: ${deferredSubtasks}  Cancelled: ${cancelledSubtasks}                 ││   ID: ${nextItem ? nextItem.id : 'N/A'} - ${nextTaskTitle}     │\n`;
+	markdown += `│                                                         ││   Priority: ${nextItem ? nextItem.priority || 'medium' : ''}  Dependencies: ${nextItem && nextItem.dependencies && nextItem.dependencies.length > 0 ? 'Some' : 'None'}                    │\n`;
+	markdown += `│   Priority Breakdown:                                   ││   Complexity: ${nextItem && nextItem.complexityScore ? '● ' + nextItem.complexityScore : 'N/A'}                                       │\n`;
+	markdown += `│   • High priority: ${data.tasks.filter((t) => t.priority === 'high').length}                                   │╰─────────────────────────────────────────────────────────╯\n`;
+	markdown += `│   • Medium priority: ${data.tasks.filter((t) => t.priority === 'medium').length}                                 │\n`;
+	markdown += `│   • Low priority: ${data.tasks.filter((t) => t.priority === 'low').length}                                     │\n`;
+	markdown += '│                                                         │\n';
+	markdown += '╰─────────────────────────────────────────────────────────╯\n';
+
+	// Tasks table
+	markdown +=
+		'┌───────────┬──────────────────────────────────────┬─────────────────┬──────────────┬───────────────────────┬───────────┐\n';
+	markdown +=
+		'│ ID        │ Title                                │ Status          │ Priority     │ Dependencies          │ Complexi… │\n';
+	markdown +=
+		'├───────────┼──────────────────────────────────────┼─────────────────┼──────────────┼───────────────────────┼───────────┤\n';
+
+	// Helper function to format status with symbols
+	const getStatusSymbol = (status) => {
+		switch (status) {
+			case 'done':
+			case 'completed':
+				return '✓ done';
+			case 'in-progress':
+				return '► in-progress';
+			case 'pending':
+				return '○ pending';
+			case 'blocked':
+				return '⭕ blocked';
+			case 'deferred':
+				return 'x deferred';
+			case 'cancelled':
+				return 'x cancelled';
+			case 'review':
+				return '? review';
+			default:
+				return status || 'pending';
+		}
+	};
+
+	// Helper function to format dependencies without color codes
+	const formatDependenciesForMarkdown = (deps, allTasks) => {
+		if (!deps || deps.length === 0) return 'None';
+		return deps
+			.map((depId) => {
+				const depTask = allTasks.find((t) => t.id === depId);
+				return depTask ? depId.toString() : depId.toString();
+			})
+			.join(', ');
+	};
+
+	// Process all tasks
+	filteredTasks.forEach((task) => {
+		const taskTitle = task.title; // No truncation for README
+		const statusSymbol = getStatusSymbol(task.status);
+		const priority = task.priority || 'medium';
+		const deps = formatDependenciesForMarkdown(task.dependencies, data.tasks);
+		const complexity = task.complexityScore
+			? `● ${task.complexityScore}`
+			: 'N/A';
+
+		markdown += `│ ${task.id.toString().padEnd(9)} │ ${taskTitle.substring(0, 36).padEnd(36)} │ ${statusSymbol.padEnd(15)} │ ${priority.padEnd(12)} │ ${deps.substring(0, 21).padEnd(21)} │ ${complexity.padEnd(9)} │\n`;
+
+		// Add subtasks if requested
+		if (withSubtasks && task.subtasks && task.subtasks.length > 0) {
+			task.subtasks.forEach((subtask) => {
+				const subtaskTitle = `└─ ${subtask.title}`; // No truncation
+				const subtaskStatus = getStatusSymbol(subtask.status);
+				const subtaskDeps = formatDependenciesForMarkdown(
+					subtask.dependencies,
+					data.tasks
+				);
+				const subtaskComplexity = subtask.complexityScore
+					? subtask.complexityScore.toString()
+					: 'N/A';
+
+				markdown +=
+					'├───────────┼──────────────────────────────────────┼─────────────────┼──────────────┼───────────────────────┼───────────┤\n';
+				markdown += `│ ${task.id}.${subtask.id}${' '.padEnd(6)} │ ${subtaskTitle.substring(0, 36).padEnd(36)} │ ${subtaskStatus.padEnd(15)} │ -            │ ${subtaskDeps.substring(0, 21).padEnd(21)} │ ${subtaskComplexity.padEnd(9)} │\n`;
+			});
+		}
+
+		markdown +=
+			'├───────────┼──────────────────────────────────────┼─────────────────┼──────────────┼───────────────────────┼───────────┤\n';
+	});
+
+	// Close the table
+	markdown = markdown.slice(
+		0,
+		-1 *
+			'├───────────┼──────────────────────────────────────┼─────────────────┼──────────────┼───────────────────────┼───────────┤\n'
+				.length
+	);
+	markdown +=
+		'└───────────┴──────────────────────────────────────┴─────────────────┴──────────────┴───────────────────────┴───────────┘\n';
+	markdown += '```\n\n';
+
+	// Next task recommendation
+	if (nextItem) {
+		markdown +=
+			'╭────────────────────────────────────────────── ⚡ RECOMMENDED NEXT TASK ⚡ ──────────────────────────────────────────────╮\n';
+		markdown +=
+			'│                                                                                                                         │\n';
+		markdown += `│  🔥 Next Task to Work On: #${nextItem.id} - ${nextItem.title}                                  │\n`;
+		markdown +=
+			'│                                                                                                                         │\n';
+		markdown += `│  Priority: ${nextItem.priority || 'medium'}   Status: ${getStatusSymbol(nextItem.status)}                                                                                     │\n`;
+		markdown += `│  Dependencies: ${nextItem.dependencies && nextItem.dependencies.length > 0 ? formatDependenciesForMarkdown(nextItem.dependencies, data.tasks) : 'None'}                                                                                                     │\n`;
+		markdown +=
+			'│                                                                                                                         │\n';
+		markdown += `│  Description: ${getWorkItemDescription(nextItem, data.tasks)}     │\n`;
+		markdown +=
+			'│                                                                                                                         │\n';
+
+		// Add subtasks if they exist
+		const parentTask = data.tasks.find((t) => t.id === nextItem.id);
+		if (parentTask && parentTask.subtasks && parentTask.subtasks.length > 0) {
+			markdown +=
+				'│  Subtasks:                                                                                              │\n';
+			parentTask.subtasks.forEach((subtask) => {
+				markdown += `│  ${nextItem.id}.${subtask.id} [${subtask.status || 'pending'}] ${subtask.title}                                         │\n`;
+			});
+			markdown +=
+				'│                                                                                                                         │\n';
+		}
+
+		markdown += `│  Start working: task-master set-status --id=${nextItem.id} --status=in-progress                                                     │\n`;
+		markdown += `│  View details: task-master show ${nextItem.id}                                                                      │\n`;
+		markdown +=
+			'│                                                                                                                         │\n';
+		markdown +=
+			'╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\n\n';
+	}
+
+	// Suggested next steps
+	markdown += '\n';
+	markdown +=
+		'╭──────────────────────────────────────────────────────────────────────────────────────╮\n';
+	markdown +=
+		'│                                                                                      │\n';
+	markdown +=
+		'│   Suggested Next Steps:                                                              │\n';
+	markdown +=
+		'│                                                                                      │\n';
+	markdown +=
+		'│   1. Run task-master next to see what to work on next                                │\n';
+	markdown +=
+		'│   2. Run task-master expand --id=<id> to break down a task into subtasks             │\n';
+	markdown +=
+		'│   3. Run task-master set-status --id=<id> --status=done to mark a task as complete   │\n';
+	markdown +=
+		'│                                                                                      │\n';
+	markdown +=
+		'╰──────────────────────────────────────────────────────────────────────────────────────╯\n';
+
+	return markdown;
+}
+
 export default listTasks;

scripts/modules/ui.js

@@ -28,6 +28,10 @@ import {
 	TASKMASTER_CONFIG_FILE,
 	TASKMASTER_TASKS_FILE
 } from '../../src/constants/paths.js';
+import {
+	TASKMASTER_CONFIG_FILE,
+	TASKMASTER_TASKS_FILE
+} from '../../src/constants/paths.js';
 import { getTaskMasterVersion } from '../../src/utils/getVersion.js';
 
 // Create a color gradient for the banner