feat: enhance docs with AI agent selection and improved getting started

- Add AI agent selection page with visual cards and logos
- Create dedicated setup guides for Cursor, Claude Code, and CLI
- Move Windows-specific MCP config from README to docs
- Enhance quick-start page with agent selection flow
- Improve user experience with clear visual hierarchy

Co-authored-by: Ralph Khreish <Crunchyman-ralph@users.noreply.github.com>

.taskmaster/CLAUDE.md

@@ -102,6 +102,35 @@ Task Master provides an MCP server that Claude Code can connect to. Configure in
 }
 ```
 
+For Windows users without WSL, use this configuration instead:
+
+```json
+{
+  "mcpServers": {
+    "task-master-ai": {
+      "command": "cmd",
+      "args": ["/c", "npx -y --package=task-master-ai task-master-ai"],
+      "env": {
+        "ANTHROPIC_API_KEY": "your_key_here",
+        "PERPLEXITY_API_KEY": "your_key_here",
+        "OPENAI_API_KEY": "OPENAI_API_KEY_HERE",
+        "GOOGLE_API_KEY": "GOOGLE_API_KEY_HERE",
+        "XAI_API_KEY": "XAI_API_KEY_HERE",
+        "OPENROUTER_API_KEY": "OPENROUTER_API_KEY_HERE",
+        "MISTRAL_API_KEY": "MISTRAL_API_KEY_HERE",
+        "AZURE_OPENAI_API_KEY": "AZURE_OPENAI_API_KEY_HERE",
+        "OLLAMA_API_KEY": "OLLAMA_API_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+Or install at the project level with Claude Code:
+```bash
+claude mcp add task-master-mcp -s project -- cmd /c "npx -y --package=task-master-ai task-master-ai"
+```
+
 ### Essential MCP Tools
 
 ```javascript

CHANGELOG.md

@@ -1,5 +1,20 @@
 # task-master-ai
 
+## 0.27.3
+
+### Patch Changes
+
+- [#1254](https://github.com/eyaltoledano/claude-task-master/pull/1254) [`af53525`](https://github.com/eyaltoledano/claude-task-master/commit/af53525cbc660a595b67d4bb90d906911c71f45d) Thanks [@Crunchyman-ralph](https://github.com/Crunchyman-ralph)! - Fixed issue where `tm show` command could not find subtasks using dotted notation IDs (e.g., '8.1').
+  - The command now properly searches within parent task subtasks and returns the correct subtask information.
+
+## 0.27.2
+
+### Patch Changes
+
+- [#1248](https://github.com/eyaltoledano/claude-task-master/pull/1248) [`044a7bf`](https://github.com/eyaltoledano/claude-task-master/commit/044a7bfc98049298177bc655cf341d7a8b6a0011) Thanks [@Crunchyman-ralph](https://github.com/Crunchyman-ralph)! - Fix set-status for subtasks:
+  - Parent tasks are now set as `done` when subtasks are all `done`
+  - Parent tasks are now set as `in-progress` when at least one subtask is `in-progress` or `done`
+
 ## 0.27.1
 
 ### Patch Changes

README.md

@@ -124,6 +124,7 @@ MCP (Model Control Protocol) lets you run Task Master directly from your editor.
 
 > **Note**: If you see `0 tools enabled` in the MCP settings, restart your editor and check that your API keys are correctly configured.
 
+
 ###### VS Code (`servers` + `type`)
 
 ```json

apps/docs/getting-started/agents/claude-code.mdx

@@ -0,0 +1,275 @@
+---
+title: Claude Code Setup  
+sidebarTitle: "Claude Code"
+---
+
+<div className="flex items-center space-x-4 mb-6">
+  <img src="/logo/claude-logo.svg" className="w-12 h-12" alt="Claude Code" />
+  <div>
+    <h1 className="text-2xl font-bold">Claude Code</h1>
+    <p className="text-gray-600">Anthropic's official CLI for Claude</p>
+  </div>
+</div>
+
+Claude Code offers the smoothest Task Master experience with **zero API key setup** and direct Claude integration.
+
+## 🎯 Why Choose Claude Code?
+
+<div className="grid grid-cols-1 md:grid-cols-2 gap-4 mb-6">
+  <div className="bg-blue-50 dark:bg-blue-900/20 p-4 rounded-lg border border-blue-200 dark:border-blue-800">
+    <h3 className="font-semibold text-blue-800 dark:text-blue-200 mb-2">🔓 No API Keys</h3>
+    <p className="text-sm text-blue-700 dark:text-blue-300">Uses your existing Claude subscription - no separate API setup needed</p>
+  </div>
+  <div className="bg-green-50 dark:bg-green-900/20 p-4 rounded-lg border border-green-200 dark:border-green-800">
+    <h3 className="font-semibold text-green-800 dark:text-green-200 mb-2">⚡ Native Integration</h3>
+    <p className="text-sm text-green-700 dark:text-green-300">Built specifically for Claude - seamless Task Master experience</p>
+  </div>
+</div>
+
+## 📦 Installation
+
+### Step 1: Install Claude Code
+
+Follow the [official Claude Code installation guide](https://docs.anthropic.com/en/docs/claude-code) or use our quick setup:
+
+<Tabs>
+  <Tab title="macOS">
+    ```bash
+    # Install via Homebrew (recommended)
+    brew install claude-code
+    
+    # Or download from GitHub releases
+    curl -L https://github.com/anthropics/claude-code/releases/latest/download/claude-code-macos.tar.gz | tar xz
+    sudo mv claude-code /usr/local/bin/
+    ```
+  </Tab>
+  
+  <Tab title="Windows">
+    ```powershell
+    # Download and install from GitHub releases
+    # Visit: https://github.com/anthropics/claude-code/releases/latest
+    # Download: claude-code-windows.exe
+    
+    # Or use winget (if available)
+    winget install Anthropic.ClaudeCode
+    ```
+  </Tab>
+  
+  <Tab title="Linux">
+    ```bash
+    # Download from GitHub releases
+    curl -L https://github.com/anthropics/claude-code/releases/latest/download/claude-code-linux.tar.gz | tar xz
+    sudo mv claude-code /usr/local/bin/
+    
+    # Or install via package manager (if available)
+    sudo apt install claude-code  # Ubuntu/Debian
+    sudo yum install claude-code  # RHEL/CentOS
+    ```
+  </Tab>
+</Tabs>
+
+### Step 2: Authenticate with Claude
+
+```bash
+# Login to your Claude account
+claude auth login
+```
+
+Follow the prompts to authenticate with your Anthropic account.
+
+## 🔧 Task Master Integration
+
+### Method 1: MCP Integration (Recommended)
+
+Add Task Master to your Claude Code MCP configuration:
+
+<Tabs>
+  <Tab title="Global Setup">
+    ```bash
+    # Add Task Master MCP server globally
+    claude mcp add task-master-ai -s global -- npx -y task-master-ai
+    ```
+  </Tab>
+  
+  <Tab title="Project Setup">
+    ```bash
+    # Add for current project only  
+    claude mcp add task-master-ai -s project -- npx -y task-master-ai
+    ```
+  </Tab>
+  
+  <Tab title="Windows">
+    ```bash
+    # Windows-specific command
+    claude mcp add task-master-mcp -s project -- cmd /c "npx -y --package=task-master-ai task-master-ai"
+    ```
+  </Tab>
+</Tabs>
+
+### Method 2: Direct CLI Usage
+
+You can also use Task Master commands directly alongside Claude Code:
+
+```bash
+# Initialize Task Master in your project
+npx task-master-ai init
+
+# Use Claude Code for AI interactions
+claude "Help me implement the next task"
+
+# Use Task Master for task management  
+npx task-master-ai next
+npx task-master-ai show 1.2
+```
+
+## 🚀 Getting Started
+
+### 1. Initialize Your Project
+
+In your project directory:
+
+```bash
+# Start Claude Code
+claude
+
+# In the Claude Code chat, initialize Task Master
+Initialize taskmaster-ai in my project
+```
+
+### 2. Configure Models (Optional)
+
+Since Claude Code doesn't need API keys, you can use it as your main model:
+
+```
+Change the main model to claude-code/sonnet
+```
+
+Available Claude Code models:
+- `claude-code/sonnet` - Claude 3.5 Sonnet (recommended)
+- `claude-code/opus` - Claude 3 Opus (for complex tasks)
+
+### 3. Create Your First Tasks
+
+```
+Can you parse my PRD and create tasks for building a todo app?
+```
+
+## 💡 Advanced Configuration
+
+### Hybrid Setup
+
+Use Claude Code as your main model with other APIs for research:
+
+Create `.env` in your project:
+```bash
+# Optional: Add research capabilities
+PERPLEXITY_API_KEY=your_perplexity_key_here
+OPENAI_API_KEY=your_openai_key_here
+```
+
+Then configure models:
+```
+Change the main model to claude-code/sonnet and research model to perplexity-llama-3.1-sonar-large-128k-online
+```
+
+### Multi-Session Workflows
+
+Claude Code excels at parallel development:
+
+```bash
+# Terminal 1: Main development
+cd my-project && claude
+
+# Terminal 2: Testing and validation  
+cd my-project && claude
+
+# Terminal 3: Documentation
+cd my-project && claude
+```
+
+Each session maintains Task Master context while allowing focused work streams.
+
+## 🔍 Troubleshooting
+
+<Accordion title="Claude Code not found">
+- **Check installation**: Run `claude --version` to verify installation
+- **Update PATH**: Ensure Claude Code is in your system PATH
+- **Reinstall**: Try reinstalling Claude Code from scratch
+- **Permissions**: Check file permissions for the claude binary
+</Accordion>
+
+<Accordion title="Authentication issues">
+- **Re-login**: Run `claude auth logout` then `claude auth login`
+- **Check account**: Verify your Anthropic account is active
+- **Network issues**: Check if you're behind a proxy or firewall
+- **Clear cache**: Delete `~/.claude` directory and re-authenticate
+</Accordion>
+
+<Accordion title="MCP server connection fails">
+- **Check Node.js**: Ensure Node.js 16+ is installed
+- **Test manually**: Run `npx task-master-ai` to test the server
+- **Clear MCP cache**: Remove and re-add the MCP server
+- **Check permissions**: Ensure npm can install packages
+</Accordion>
+
+<Accordion title="Task Master commands not working">
+- **Verify MCP**: Run `claude mcp list` to see installed servers
+- **Re-add server**: Remove and re-add the task-master-ai MCP server
+- **Check initialization**: Ensure project is initialized with `Initialize taskmaster-ai`
+- **Review logs**: Check Claude Code logs for error messages
+</Accordion>
+
+## 💡 Pro Tips
+
+<Tip>
+**Use headless mode** for automation: `claude -p "What's the next task I should work on?"` gives quick answers without opening the full chat interface.
+</Tip>
+
+<Tip>
+**Create custom commands** using Claude Code's command system for repeated Task Master workflows like "complete task and get next".
+</Tip>
+
+<Tip>
+**Leverage context persistence** - Claude Code maintains conversation history, making it perfect for long-running development sessions.
+</Tip>
+
+## 🎯 Best Practices
+
+### Development Workflow
+
+```bash
+# Morning routine
+claude "Show me today's tasks and priorities"
+
+# During development  
+claude "Help me implement task 2.1"
+claude "Update task 2.1 with implementation notes"
+
+# End of day
+claude "Mark completed tasks as done and show tomorrow's priorities"
+```
+
+### Team Collaboration
+
+```bash
+# Share task status
+claude "Generate a progress report for the team"
+
+# Review dependencies
+claude "Check which tasks are blocked and why"
+
+# Planning sessions
+claude "Analyze complexity of remaining tasks"
+```
+
+---
+
+<div className="bg-purple-50 dark:bg-purple-900/20 p-4 rounded-lg border border-purple-200 dark:border-purple-800">
+  <div className="flex items-center space-x-2 mb-2">
+    <span className="text-purple-600 dark:text-purple-400 text-lg">🎉</span>
+    <h3 className="font-semibold text-purple-800 dark:text-purple-200">You're all set with Claude Code!</h3>
+  </div>
+  <p className="text-purple-700 dark:text-purple-300">
+    Claude Code offers the most seamless Task Master experience. Ready to create your first project? Check out our <a href="/getting-started/quick-start/prd-quick" className="underline">PRD guide</a>.
+  </p>
+</div>

apps/docs/getting-started/agents/cli.mdx

@@ -0,0 +1,373 @@
+---
+title: Command Line Setup
+sidebarTitle: "CLI"
+---
+
+<div className="flex items-center space-x-4 mb-6">
+  <img src="/logo/terminal-logo.svg" className="w-12 h-12" alt="Terminal" />
+  <div>
+    <h1 className="text-2xl font-bold">Command Line Interface</h1>
+    <p className="text-gray-600">Direct CLI usage without IDE integration</p>
+  </div>
+</div>
+
+Use Task Master directly from the command line for maximum flexibility and control.
+
+## 🎯 Why Choose CLI?
+
+<div className="grid grid-cols-1 md:grid-cols-2 gap-4 mb-6">
+  <div className="bg-blue-50 dark:bg-blue-900/20 p-4 rounded-lg border border-blue-200 dark:border-blue-800">
+    <h3 className="font-semibold text-blue-800 dark:text-blue-200 mb-2">🚀 Maximum Performance</h3>
+    <p className="text-sm text-blue-700 dark:text-blue-300">No IDE overhead - pure command line speed</p>
+  </div>
+  <div className="bg-green-50 dark:bg-green-900/20 p-4 rounded-lg border border-green-200 dark:border-green-800">
+    <h3 className="font-semibold text-green-800 dark:text-green-200 mb-2">🔧 Full Control</h3>
+    <p className="text-sm text-green-700 dark:text-green-300">Access to all Task Master features and configurations</p>
+  </div>
+  <div className="bg-purple-50 dark:bg-purple-900/20 p-4 rounded-lg border border-purple-200 dark:border-purple-800">
+    <h3 className="font-semibold text-purple-800 dark:text-purple-200 mb-2">📜 Scriptable</h3>
+    <p className="text-sm text-purple-700 dark:text-purple-300">Perfect for automation and CI/CD integration</p>
+  </div>
+  <div className="bg-orange-50 dark:bg-orange-900/20 p-4 rounded-lg border border-orange-200 dark:border-orange-800">
+    <h3 className="font-semibold text-orange-800 dark:text-orange-200 mb-2">🌐 Universal</h3>
+    <p className="text-sm text-orange-700 dark:text-orange-300">Works on any system with Node.js</p>
+  </div>
+</div>
+
+## 📦 Installation
+
+### Global Installation (Recommended)
+
+```bash
+# Install Task Master globally
+npm install -g task-master-ai
+
+# Verify installation
+task-master --version
+```
+
+### Local Installation
+
+```bash
+# Install in your project
+npm install task-master-ai
+
+# Use with npx
+npx task-master-ai --version
+```
+
+## 🔧 Configuration
+
+### Step 1: Set Up API Keys
+
+Create a `.env` file in your project root:
+
+```bash
+# At least one of these is required
+ANTHROPIC_API_KEY=your_anthropic_key_here
+PERPLEXITY_API_KEY=your_perplexity_key_here  # Recommended for research
+OPENAI_API_KEY=your_openai_key_here
+
+# Optional additional providers
+GOOGLE_API_KEY=your_google_key_here
+MISTRAL_API_KEY=your_mistral_key_here
+OPENROUTER_API_KEY=your_openrouter_key_here
+XAI_API_KEY=your_xai_key_here
+```
+
+### Step 2: Configure Models
+
+```bash
+# Interactive model configuration
+task-master models --setup
+
+# Or set specific models
+task-master models --set-main claude-3-5-sonnet-20241022
+task-master models --set-research perplexity-llama-3.1-sonar-large-128k-online
+task-master models --set-fallback gpt-4o-mini
+```
+
+### Step 3: Initialize Your Project
+
+```bash
+# Initialize Task Master in current directory
+task-master init
+
+# Initialize with specific rules
+task-master init --rules cursor,windsurf,vscode
+```
+
+## 🚀 Quick Start Guide
+
+### 1. Create Your PRD
+
+```bash
+# Create a Product Requirements Document
+touch .taskmaster/docs/prd.txt
+
+# Edit with your favorite editor
+nano .taskmaster/docs/prd.txt
+# or
+code .taskmaster/docs/prd.txt
+```
+
+### 2. Generate Tasks
+
+```bash
+# Parse your PRD and create tasks
+task-master parse-prd .taskmaster/docs/prd.txt
+
+# Analyze task complexity
+task-master analyze-complexity --research
+
+# Expand tasks into subtasks
+task-master expand --all --research
+```
+
+### 3. Start Working
+
+```bash
+# See all tasks
+task-master list
+
+# Get next task to work on
+task-master next
+
+# Show specific task details
+task-master show 1.2
+
+# Mark task as in-progress
+task-master set-status --id=1.2 --status=in-progress
+```
+
+## 📋 Essential Commands
+
+### Task Management
+
+```bash
+# List all tasks
+task-master list
+
+# Show specific tasks (comma-separated)
+task-master show 1,2,3
+
+# Get next available task
+task-master next
+
+# Add a new task
+task-master add-task --prompt="Implement user login" --research
+
+# Update task with notes
+task-master update-task --id=1.2 --prompt="Added JWT authentication"
+
+# Update subtask with implementation notes
+task-master update-subtask --id=1.2.1 --prompt="Used bcrypt for password hashing"
+```
+
+### Task Status Management
+
+```bash
+# Mark task as done
+task-master set-status --id=1.2 --status=done
+
+# Mark as in-progress
+task-master set-status --id=1.2 --status=in-progress
+
+# Mark as blocked
+task-master set-status --id=1.2 --status=blocked
+```
+
+### Analysis and Planning
+
+```bash
+# Research latest information
+task-master research "What are the latest React best practices?"
+
+# Analyze project complexity
+task-master analyze-complexity --research
+
+# View complexity report
+task-master complexity-report
+
+# Expand task into subtasks
+task-master expand --id=1.2 --research --force
+```
+
+### Dependencies and Organization
+
+```bash
+# Add task dependency
+task-master add-dependency --id=2.1 --depends-on=1.2
+
+# Move task to different position
+task-master move --from=3 --to=1
+
+# Validate dependencies
+task-master validate-dependencies
+
+# Generate markdown files
+task-master generate
+```
+
+## 🎯 Advanced Usage
+
+### Scripting and Automation
+
+Create shell scripts for common workflows:
+
+```bash
+#!/bin/bash
+# daily-standup.sh
+
+echo "=== Today's Tasks ==="
+task-master next
+
+echo -e "\n=== In Progress ==="
+task-master list | grep "in-progress"
+
+echo -e "\n=== Blocked Tasks ==="
+task-master list | grep "blocked"
+
+echo -e "\n=== Complexity Report ==="
+task-master complexity-report
+```
+
+### CI/CD Integration
+
+```yaml
+# .github/workflows/task-validation.yml
+name: Task Validation
+
+on: [push, pull_request]
+
+jobs:
+  validate-tasks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: '18'
+      
+      - name: Install Task Master
+        run: npm install -g task-master-ai
+        
+      - name: Validate task dependencies
+        run: task-master validate-dependencies
+        
+      - name: Generate task report
+        run: task-master complexity-report > task-report.json
+```
+
+### Custom Aliases
+
+Add these to your `.bashrc` or `.zshrc`:
+
+```bash
+# Task Master shortcuts
+alias tm="task-master"
+alias tmn="task-master next"
+alias tml="task-master list"  
+alias tmr="task-master research"
+alias tms="task-master show"
+```
+
+## 🔍 Troubleshooting
+
+<Accordion title="Command not found: task-master">
+**Solutions:**
+- Verify Node.js installation: `node --version`
+- Reinstall globally: `npm install -g task-master-ai`
+- Check npm global path: `npm config get prefix`
+- Use npx if global install fails: `npx task-master-ai`
+</Accordion>
+
+<Accordion title="API key errors">
+**Solutions:**
+- Check `.env` file exists and has correct keys
+- Verify API key format and validity
+- Test with a single API key first
+- Check for typos in environment variable names
+</Accordion>
+
+<Accordion title="Tasks not generating">
+**Solutions:**
+- Verify PRD file exists and has content
+- Check API keys are working: `task-master models`
+- Try with different model: `task-master models --set-main gpt-4o-mini`
+- Add `--research` flag for better results
+</Accordion>
+
+<Accordion title="Permission errors">
+**Solutions:**
+- Use `sudo` for global installs (not recommended)
+- Configure npm to use different directory: `npm config set prefix ~/.local`
+- Use local installation: `npm install task-master-ai`
+- Check file permissions in `.taskmaster` directory
+</Accordion>
+
+## 💡 Pro Tips
+
+<Tip>
+**Use `--research` flag** with AI commands for more informed and up-to-date task suggestions based on current best practices.
+</Tip>
+
+<Tip>
+**Create project templates** with pre-configured `.taskmaster` directories for different types of projects (web apps, APIs, mobile apps).
+</Tip>
+
+<Tip>
+**Combine with other tools** like `jq` for parsing JSON outputs: `task-master list --json | jq '.[] | select(.status=="pending")'`
+</Tip>
+
+<Tip>
+**Use environment-specific configs** by creating different `.env` files (.env.development, .env.production) and symlinking as needed.
+</Tip>
+
+## 📚 Integration Examples
+
+### With Git Hooks
+
+```bash
+#!/bin/sh
+# .git/hooks/pre-commit
+
+# Check if any tasks are marked as done
+if task-master list | grep -q "done"; then
+    echo "✅ Tasks completed in this commit:"
+    task-master list | grep "done"
+fi
+```
+
+### With Make
+
+```makefile
+# Makefile
+
+.PHONY: tasks next status
+
+tasks:
+	@task-master list
+
+next:
+	@task-master next
+
+status:
+	@echo "=== Task Status ==="
+	@task-master list | grep -E "(in-progress|blocked)"
+	@echo ""
+	@echo "=== Next Task ==="
+	@task-master next
+```
+
+---
+
+<div className="bg-cyan-50 dark:bg-cyan-900/20 p-4 rounded-lg border border-cyan-200 dark:border-cyan-800">
+  <div className="flex items-center space-x-2 mb-2">
+    <span className="text-cyan-600 dark:text-cyan-400 text-lg">⚡</span>
+    <h3 className="font-semibold text-cyan-800 dark:text-cyan-200">Ready for maximum productivity!</h3>
+  </div>
+  <p className="text-cyan-700 dark:text-cyan-300">
+    You now have the full power of Task Master at your fingertips. Create your first project with our <a href="/getting-started/quick-start/prd-quick" className="underline">PRD guide</a>.
+  </p>
+</div>

apps/docs/getting-started/agents/cursor.mdx

@@ -0,0 +1,247 @@
+---
+title: Cursor Setup
+sidebarTitle: "Cursor"
+---
+
+<div className="flex items-center space-x-4 mb-6">
+  <img src="/logo/cursor-logo.svg" className="w-12 h-12" alt="Cursor" />
+  <div>
+    <h1 className="text-2xl font-bold">Cursor AI Editor</h1>
+    <p className="text-gray-600">AI-powered VS Code fork with built-in MCP support</p>
+  </div>
+</div>
+
+Cursor offers the smoothest Task Master experience with one-click installation and native MCP integration.
+
+## 🚀 One-Click Install (Recommended)
+
+<div className="bg-blue-50 dark:bg-blue-900/20 p-4 rounded-lg border border-blue-200 dark:border-blue-800 mb-6">
+  <div className="flex items-center space-x-2 mb-3">
+    <span className="text-blue-600 dark:text-blue-400 text-lg">⚡</span>
+    <h3 className="font-semibold text-blue-800 dark:text-blue-200">Fastest Setup</h3>
+  </div>
+  
+  <a href="cursor://anysphere.cursor-deeplink/mcp/install?name=task-master-ai&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIi0tcGFja2FnZT10YXNrLW1hc3Rlci1haSIsInRhc2stbWFzdGVyLWFpIl0sImVudiI6eyJBTlRIUk9QSUNfQVBJX0tFWSI6IllPVVJfQU5USFJPUElDX0FQSV9LRVlfSEVSRSIsIlBFUlBMRVhJVFlfQVBJX0tFWSI6IllPVVJfUEVSUExFWElUWV9BUElfS0VZX0hFUkUiLCJPUEVOQUlfQVBJX0tFWSI6IllPVVJfT1BFTkFJX0tFWV9IRVJFIiwiR09PR0xFX0FQSV9LRVkiOiJZT1VSX0dPT0dMRV9LRVlfSEVSRSIsIk1JU1RSQUxfQVBJX0tFWSI6IllPVVJfTUlTVFJBTF9LRVlfSEVSRSIsIk9QRU5ST1VURVJfQVBJX0tFWSI6IllPVVJfT1BFTlJPVVRFUl9LRVlfSEVSRSIsIlhBSV9BUElfS0VZIjoiWU9VUl9YQUlfS0VZX0hFUkUiLCJBWlVSRV9PUEVOQUJFX0FQSV9LRVkiOiJZT1VSX0FaVVJFX0tFWV9IRVJFIiwiT0xMQU1BX0FQSV9LRVkiOiJZT1VSX09MTEFNQV9BUElfS0VZX0hFUkUifX0%3D">
+    <img 
+      className="block dark:hidden hover:opacity-80 transition-opacity cursor-pointer" 
+      src="https://cursor.com/deeplink/mcp-install-light.png" 
+      alt="Add Task Master MCP server to Cursor" 
+      noZoom
+    />
+    <img 
+      className="hidden dark:block hover:opacity-80 transition-opacity cursor-pointer" 
+      src="https://cursor.com/deeplink/mcp-install-dark.png" 
+      alt="Add Task Master MCP server to Cursor" 
+      noZoom
+    />
+  </a>
+</div>
+
+<Warning>
+**After one-click install**: You still need to add your actual API keys! The installer uses placeholder keys that must be replaced.
+</Warning>
+
+## 📋 Manual Setup
+
+If you prefer manual configuration or the one-click install doesn't work:
+
+### Step 1: Create MCP Configuration
+
+Choose your configuration scope:
+
+<Tabs>
+  <Tab title="Global Config">
+    Create or edit `~/.cursor/mcp.json` (macOS/Linux) or `%USERPROFILE%\.cursor\mcp.json` (Windows):
+
+    ```json
+    {
+      "mcpServers": {
+        "task-master-ai": {
+          "command": "npx",
+          "args": ["-y", "task-master-ai"],
+          "env": {
+            "ANTHROPIC_API_KEY": "YOUR_ANTHROPIC_API_KEY_HERE",
+            "PERPLEXITY_API_KEY": "YOUR_PERPLEXITY_API_KEY_HERE",
+            "OPENAI_API_KEY": "YOUR_OPENAI_KEY_HERE",
+            "GOOGLE_API_KEY": "YOUR_GOOGLE_KEY_HERE",
+            "MISTRAL_API_KEY": "YOUR_MISTRAL_KEY_HERE",
+            "OPENROUTER_API_KEY": "YOUR_OPENROUTER_KEY_HERE",
+            "XAI_API_KEY": "YOUR_XAI_KEY_HERE"
+          }
+        }
+      }
+    }
+    ```
+  </Tab>
+  
+  <Tab title="Project Config">
+    Create `.cursor/mcp.json` in your project root:
+
+    ```json
+    {
+      "mcpServers": {
+        "task-master-ai": {
+          "command": "npx",
+          "args": ["-y", "task-master-ai"],
+          "env": {
+            "ANTHROPIC_API_KEY": "YOUR_ANTHROPIC_API_KEY_HERE",
+            "PERPLEXITY_API_KEY": "YOUR_PERPLEXITY_API_KEY_HERE"
+          }
+        }
+      }
+    }
+    ```
+  </Tab>
+  
+  <Tab title="Windows Native">
+    For Windows users without WSL:
+
+    ```json
+    {
+      "mcpServers": {
+        "task-master-ai": {
+          "command": "cmd",
+          "args": ["/c", "npx -y --package=task-master-ai task-master-ai"],
+          "env": {
+            "ANTHROPIC_API_KEY": "YOUR_ANTHROPIC_API_KEY_HERE",
+            "PERPLEXITY_API_KEY": "YOUR_PERPLEXITY_API_KEY_HERE",
+            "OPENAI_API_KEY": "YOUR_OPENAI_KEY_HERE"
+          }
+        }
+      }
+    }
+    ```
+
+    <Note>
+    **Alternative Windows Setup**: Use Claude Code's project-level installation:
+    ```bash
+    claude mcp add task-master-mcp -s project -- cmd /c "npx -y --package=task-master-ai task-master-ai"
+    ```
+    </Note>
+  </Tab>
+</Tabs>
+
+### Step 2: Enable MCP Server
+
+1. Open Cursor Settings (`Ctrl+Shift+J` or `Cmd+Shift+J`)
+2. Click the **MCP** tab in the left sidebar
+3. Find `task-master-ai` and toggle it **ON**
+4. Restart Cursor if needed
+
+### Step 3: Verify Installation
+
+In Cursor's chat panel, type:
+```
+help
+```
+
+You should see Task Master commands available. If you see "0 tools enabled", check your API keys and restart Cursor.
+
+## 🔧 Configuration
+
+### Add Your API Keys
+
+<Tabs>
+  <Tab title="Required Keys">
+    You need **at least one** of these:
+    - `ANTHROPIC_API_KEY` - For Claude models (recommended)
+    - `OPENAI_API_KEY` - For GPT models  
+    - `GOOGLE_API_KEY` - For Gemini models
+  </Tab>
+  
+  <Tab title="Recommended Keys">
+    For the best experience, also add:
+    - `PERPLEXITY_API_KEY` - Enables research features
+    - `OPENAI_API_KEY` - Fallback option
+  </Tab>
+  
+  <Tab title="All Supported Keys">
+    Full list of supported API keys:
+    - `ANTHROPIC_API_KEY`
+    - `PERPLEXITY_API_KEY` 
+    - `OPENAI_API_KEY`
+    - `GOOGLE_API_KEY`
+    - `MISTRAL_API_KEY`
+    - `OPENROUTER_API_KEY`
+    - `XAI_API_KEY`
+    - `AZURE_OPENAI_API_KEY`
+    - `OLLAMA_API_KEY`
+  </Tab>
+</Tabs>
+
+### Configure Models (Optional)
+
+In Cursor's chat, set your preferred models:
+
+```
+Change the main, research and fallback models to claude-3-5-sonnet-20241022, perplexity-llama-3.1-sonar-large-128k-online and gpt-4o-mini respectively.
+```
+
+## 🎯 Getting Started
+
+### 1. Initialize Task Master
+
+In Cursor's chat panel:
+```
+Initialize taskmaster-ai in my project
+```
+
+### 2. Create Your First Task
+
+```
+Can you help me implement user authentication for my web app?
+```
+
+### 3. Start Working
+
+```
+What's the next task I should work on?
+```
+
+## 🔍 Troubleshooting
+
+<Accordion title="0 tools enabled in MCP settings">
+- **Check API keys**: Ensure at least one API key is correctly set
+- **Restart Cursor**: Close and reopen Cursor completely  
+- **Check file paths**: Verify your `mcp.json` is in the correct location
+- **Test manually**: Run `npx task-master-ai` in terminal to test
+</Accordion>
+
+<Accordion title="MCP server fails to start">
+- **Update Node.js**: Ensure you have Node.js 16+ installed
+- **Clear npm cache**: Run `npm cache clean --force`
+- **Try global install**: Run `npm install -g task-master-ai`
+- **Check permissions**: Ensure npm has permission to install packages
+</Accordion>
+
+<Accordion title="Commands not working">
+- **Verify installation**: Type `help` in chat to see available commands
+- **Check project initialization**: Run `Initialize taskmaster-ai in my project`
+- **Review logs**: Check Cursor's developer console for error messages
+</Accordion>
+
+## 💡 Pro Tips
+
+<Tip>
+**Use project-specific configs** for different API keys per project, especially when working with team projects that have shared API limits.
+</Tip>
+
+<Tip>
+**Enable research mode** with a Perplexity API key to get AI-powered task suggestions based on the latest best practices.
+</Tip>
+
+<Tip>
+**Set up keyboard shortcuts** in Cursor for common Task Master commands like "What's next?" or "Show task status".
+</Tip>
+
+---
+
+<div className="bg-green-50 dark:bg-green-900/20 p-4 rounded-lg border border-green-200 dark:border-green-800">
+  <div className="flex items-center space-x-2 mb-2">
+    <span className="text-green-600 dark:text-green-400 text-lg">✅</span>
+    <h3 className="font-semibold text-green-800 dark:text-green-200">Ready to go!</h3>
+  </div>
+  <p className="text-green-700 dark:text-green-300">
+    You're all set with Cursor! Head over to our <a href="/getting-started/quick-start/prd-quick" className="underline">PRD guide</a> to create your first project.
+  </p>
+</div>

apps/docs/getting-started/ai-agents.mdx

@@ -0,0 +1,118 @@
+---
+title: Choose Your AI Agent
+sidebarTitle: "AI Agents"
+---
+
+Task Master works seamlessly with various AI agents. Choose your preferred agent to get customized setup instructions.
+
+<CardGroup cols={2}>
+  <Card 
+    title="Cursor" 
+    icon="cursor" 
+    href="/getting-started/agents/cursor"
+  >
+    <div className="flex items-center space-x-3">
+      <img src="/logo/cursor-logo.svg" className="w-8 h-8" alt="Cursor" />
+      <span>AI-powered VS Code fork with built-in MCP support</span>
+    </div>
+  </Card>
+
+  <Card 
+    title="Claude Code" 
+    icon="claude" 
+    href="/getting-started/agents/claude-code"
+  >
+    <div className="flex items-center space-x-3">
+      <img src="/logo/claude-logo.svg" className="w-8 h-8" alt="Claude Code" />
+      <span>Anthropic's official CLI for Claude</span>
+    </div>
+  </Card>
+
+  <Card 
+    title="Windsurf" 
+    icon="windsurf" 
+    href="/getting-started/agents/windsurf"
+  >
+    <div className="flex items-center space-x-3">
+      <img src="/logo/windsurf-logo.svg" className="w-8 h-8" alt="Windsurf" />
+      <span>Codeium's AI-native IDE</span>
+    </div>
+  </Card>
+
+  <Card 
+    title="VS Code" 
+    icon="vscode" 
+    href="/getting-started/agents/vscode"
+  >
+    <div className="flex items-center space-x-3">
+      <img src="/logo/vscode-logo.svg" className="w-8 h-8" alt="VS Code" />
+      <span>Microsoft's editor with MCP extensions</span>
+    </div>
+  </Card>
+
+  <Card 
+    title="Command Line" 
+    icon="terminal" 
+    href="/getting-started/agents/cli"
+  >
+    <div className="flex items-center space-x-3">
+      <img src="/logo/terminal-logo.svg" className="w-8 h-8" alt="Terminal" />
+      <span>Direct CLI usage without IDE integration</span>
+    </div>
+  </Card>
+
+  <Card 
+    title="Other Agents" 
+    icon="question" 
+    href="/getting-started/agents/other"
+  >
+    <div className="flex items-center space-x-3">
+      <img src="/logo/generic-logo.svg" className="w-8 h-8" alt="Other" />
+      <span>Generic setup for other AI agents</span>
+    </div>
+  </Card>
+</CardGroup>
+
+## Quick Recommendations
+
+<Accordion title="🎯 Which agent should I choose?">
+**For beginners**: Start with **Cursor** - it has the most seamless MCP integration and one-click install.
+
+**For Claude users**: Use **Claude Code** - it's Anthropic's official CLI with no API key required.
+
+**For existing VS Code users**: Stick with **VS Code** if you're already comfortable with your setup.
+
+**For advanced users**: Try **Windsurf** for its AI-native features or use **Command Line** for maximum flexibility.
+</Accordion>
+
+<Accordion title="💡 What's MCP and why does it matter?">
+MCP (Model Control Protocol) allows Task Master to run directly inside your AI agent, giving you:
+- 🔥 **Seamless integration** - No switching between tools
+- ⚡ **Real-time task management** - Tasks update as you work  
+- 🧠 **Context awareness** - Your AI knows about your tasks
+- 🎯 **Smart suggestions** - AI can recommend next tasks
+</Accordion>
+
+## Platform-Specific Notes
+
+<Tabs>
+  <Tab title="Windows">
+    **Important**: Windows users may need special configuration for some agents. We'll provide Windows-specific instructions for each agent.
+    
+    Some agents work better with WSL (Windows Subsystem for Linux), while others have native Windows support.
+  </Tab>
+  
+  <Tab title="macOS">
+    Most agents work seamlessly on macOS. Claude Code and Cursor have the best native macOS integration.
+  </Tab>
+  
+  <Tab title="Linux">
+    All agents have excellent Linux support. Command Line interface works particularly well in Linux environments.
+  </Tab>
+</Tabs>
+
+---
+
+<Note>
+**Need help choosing?** Check our [comparison table](/getting-started/agent-comparison) or join our [Discord community](https://discord.gg/taskmasterai) for personalized recommendations.
+</Note>

apps/docs/getting-started/quick-start/installation.mdx

@@ -77,6 +77,36 @@ MCP (Model Control Protocol) lets you run Task Master directly from your editor.
 
 > **Note**: If you see `0 tools enabled` in the MCP settings, restart your editor and check that your API keys are correctly configured.
 
+### Windows-specific Configuration
+
+For Windows users without WSL, you may need to use `cmd` to run the MCP server:
+
+```json
+{
+  "mcpServers": {
+    "task-master-ai": {
+      "command": "cmd",
+      "args": ["/c", "npx -y --package=task-master-ai task-master-ai"],
+      "env": {
+        "ANTHROPIC_API_KEY": "YOUR_ANTHROPIC_API_KEY_HERE",
+        "PERPLEXITY_API_KEY": "YOUR_PERPLEXITY_API_KEY_HERE",
+        "OPENAI_API_KEY": "YOUR_OPENAI_KEY_HERE",
+        "GOOGLE_API_KEY": "YOUR_GOOGLE_KEY_HERE",
+        "MISTRAL_API_KEY": "YOUR_MISTRAL_KEY_HERE",
+        "OPENROUTER_API_KEY": "YOUR_OPENROUTER_KEY_HERE",
+        "XAI_API_KEY": "YOUR_XAI_KEY_HERE",
+        "AZURE_OPENAI_API_KEY": "YOUR_AZURE_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+Alternatively, you can install at the project level with Claude Code:
+```bash
+claude mcp add task-master-mcp -s project -- cmd /c "npx -y --package=task-master-ai task-master-ai"
+```
+
 ### VS Code (`servers` + `type`)
 
 ```json

apps/docs/getting-started/quick-start/quick-start.mdx

@@ -5,7 +5,27 @@ sidebarTitle: "Quick Start"
 
 This guide is for new users who want to start using Task Master with minimal setup time.
 
-It covers:
+## 🎯 Choose Your AI Agent
+
+First, pick your preferred AI development environment:
+
+<CardGroup cols={3}>
+  <Card title="Cursor" icon="cursor" href="/getting-started/agents/cursor">
+    One-click install with native MCP support
+  </Card>
+  <Card title="Claude Code" icon="claude" href="/getting-started/agents/claude-code">
+    No API keys needed - uses your Claude subscription
+  </Card>
+  <Card title="Command Line" icon="terminal" href="/getting-started/agents/cli">
+    Maximum control and scriptability
+  </Card>
+</CardGroup>
+
+[View all AI agents →](/getting-started/ai-agents)
+
+## 📋 Quick Start Steps
+
+After setting up your AI agent, this guide covers:
 - [Requirements](/docs/getting-started/quick-start/requirements): You will need Node.js and an AI model API Key.
 - [Installation](/docs/getting-started/quick-start/installation): How to Install Task Master.
 - [Configuration](/docs/getting-started/quick-start/configuration-quick): Setting up your API Key, MCP, and more.

apps/extension/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Change Log
 
+## 0.25.4
+
+### Patch Changes
+
+- Updated dependencies [[`af53525`](https://github.com/eyaltoledano/claude-task-master/commit/af53525cbc660a595b67d4bb90d906911c71f45d)]:
+  - task-master-ai@0.27.3
+
+## 0.25.3
+
+### Patch Changes
+
+- Updated dependencies [[`044a7bf`](https://github.com/eyaltoledano/claude-task-master/commit/044a7bfc98049298177bc655cf341d7a8b6a0011)]:
+  - task-master-ai@0.27.2
+
 ## 0.25.2
 
 ### Patch Changes

apps/extension/package.json

@@ -3,7 +3,7 @@
 	"private": true,
 	"displayName": "TaskMaster",
 	"description": "A visual Kanban board interface for TaskMaster projects in VS Code",
-	"version": "0.25.2",
+	"version": "0.25.4",
 	"publisher": "Hamster",
 	"icon": "assets/icon.png",
 	"engines": {
@@ -240,7 +240,7 @@
 		"check-types": "tsc --noEmit"
 	},
 	"dependencies": {
-		"task-master-ai": "0.27.1"
+		"task-master-ai": "0.27.3"
 	},
 	"devDependencies": {
 		"@dnd-kit/core": "^6.3.1",

package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "task-master-ai",
-	"version": "0.27.1",
+	"version": "0.27.3",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "task-master-ai",
-			"version": "0.27.1",
+			"version": "0.27.3",
 			"license": "MIT WITH Commons-Clause",
 			"workspaces": [
 				"apps/*",
@@ -357,9 +357,9 @@
 			}
 		},
 		"apps/extension": {
-			"version": "0.25.2",
+			"version": "0.25.4",
 			"dependencies": {
-				"task-master-ai": "0.27.1"
+				"task-master-ai": "0.27.3"
 			},
 			"devDependencies": {
 				"@dnd-kit/core": "^6.3.1",

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "task-master-ai",
-	"version": "0.27.1",
+	"version": "0.27.3",
 	"description": "A task management system for ambitious AI-driven development that doesn't overwhelm and confuse Cursor.",
 	"main": "index.js",
 	"type": "module",

packages/tm-core/src/interfaces/storage.interface.ts

@@ -3,7 +3,17 @@
  * This file defines the contract for all storage implementations
  */
 
-import type { Task, TaskMetadata } from '../types/index.js';
+import type { Task, TaskMetadata, TaskStatus } from '../types/index.js';
+
+/**
+ * Result type for updateTaskStatus operations
+ */
+export interface UpdateStatusResult {
+	success: boolean;
+	oldStatus: TaskStatus;
+	newStatus: TaskStatus;
+	taskId: string;
+}
 
 /**
  * Interface for storage operations on tasks
@@ -54,6 +64,19 @@ export interface IStorage {
 		tag?: string
 	): Promise<void>;
 
+	/**
+	 * Update task or subtask status by ID
+	 * @param taskId - ID of the task or subtask (e.g., "1" or "1.2")
+	 * @param newStatus - New status to set
+	 * @param tag - Optional tag context for the task
+	 * @returns Promise that resolves to update result with old and new status
+	 */
+	updateTaskStatus(
+		taskId: string,
+		newStatus: TaskStatus,
+		tag?: string
+	): Promise<UpdateStatusResult>;
+
 	/**
 	 * Delete a task by ID
 	 * @param taskId - ID of the task to delete
@@ -191,6 +214,11 @@ export abstract class BaseStorage implements IStorage {
 		updates: Partial<Task>,
 		tag?: string
 	): Promise<void>;
+	abstract updateTaskStatus(
+		taskId: string,
+		newStatus: TaskStatus,
+		tag?: string
+	): Promise<UpdateStatusResult>;
 	abstract deleteTask(taskId: string, tag?: string): Promise<void>;
 	abstract exists(tag?: string): Promise<boolean>;
 	abstract loadMetadata(tag?: string): Promise<TaskMetadata | null>;

packages/tm-core/src/services/task-service.ts

@@ -135,15 +135,28 @@ export class TaskService {
 	}
 
 	/**
-	 * Get a single task by ID
+	 * Get a single task by ID - delegates to storage layer
 	 */
 	async getTask(taskId: string, tag?: string): Promise<Task | null> {
-		const result = await this.getTaskList({
-			tag,
-			includeSubtasks: true
-		});
+		// Use provided tag or get active tag
+		const activeTag = tag || this.getActiveTag();
 
-		return result.tasks.find((t) => t.id === taskId) || null;
+		try {
+			// Delegate to storage layer which handles the specific logic for tasks vs subtasks
+			return await this.storage.loadTask(String(taskId), activeTag);
+		} catch (error) {
+			throw new TaskMasterError(
+				`Failed to get task ${taskId}`,
+				ERROR_CODES.STORAGE_ERROR,
+				{
+					operation: 'getTask',
+					resource: 'task',
+					taskId: String(taskId),
+					tag: activeTag
+				},
+				error as Error
+			);
+		}
 	}
 
 	/**
@@ -446,7 +459,7 @@ export class TaskService {
 	}
 
 	/**
-	 * Update task status
+	 * Update task status - delegates to storage layer which handles storage-specific logic
 	 */
 	async updateTaskStatus(
 		taskId: string | number,
@@ -468,49 +481,28 @@ export class TaskService {
 
 		// Use provided tag or get active tag
 		const activeTag = tag || this.getActiveTag();
-
 		const taskIdStr = String(taskId);
 
-		// TODO: For now, assume it's a regular task and just try to update directly
-		// In the future, we can add subtask support if needed
-		if (taskIdStr.includes('.')) {
-			throw new TaskMasterError(
-				'Subtask status updates not yet supported in API storage',
-				ERROR_CODES.NOT_IMPLEMENTED
-			);
-		}
-
-		// Get the current task to get old status (simple, direct approach)
-		let currentTask: Task | null;
 		try {
-			// Try to get the task directly
-			currentTask = await this.storage.loadTask(taskIdStr, activeTag);
+			// Delegate to storage layer which handles the specific logic for tasks vs subtasks
+			return await this.storage.updateTaskStatus(
+				taskIdStr,
+				newStatus,
+				activeTag
+			);
 		} catch (error) {
 			throw new TaskMasterError(
-				`Failed to load task ${taskIdStr}`,
-				ERROR_CODES.TASK_NOT_FOUND,
-				{ taskId: taskIdStr },
+				`Failed to update task status for ${taskIdStr}`,
+				ERROR_CODES.STORAGE_ERROR,
+				{
+					operation: 'updateTaskStatus',
+					resource: 'task',
+					taskId: taskIdStr,
+					newStatus,
+					tag: activeTag
+				},
 				error as Error
 			);
 		}
-
-		if (!currentTask) {
-			throw new TaskMasterError(
-				`Task ${taskIdStr} not found`,
-				ERROR_CODES.TASK_NOT_FOUND
-			);
-		}
-
-		const oldStatus = currentTask.status;
-
-		// Simple, direct update - just change the status
-		await this.storage.updateTask(taskIdStr, { status: newStatus }, activeTag);
-
-		return {
-			success: true,
-			oldStatus,
-			newStatus,
-			taskId: taskIdStr
-		};
 	}
 }

packages/tm-core/src/storage/api-storage.ts

@@ -5,9 +5,15 @@
 
 import type {
 	IStorage,
-	StorageStats
+	StorageStats,
+	UpdateStatusResult
 } from '../interfaces/storage.interface.js';
-import type { Task, TaskMetadata, TaskTag } from '../types/index.js';
+import type {
+	Task,
+	TaskMetadata,
+	TaskTag,
+	TaskStatus
+} from '../types/index.js';
 import { ERROR_CODES, TaskMasterError } from '../errors/task-master-error.js';
 import { TaskRepository } from '../repositories/task-repository.interface.js';
 import { SupabaseTaskRepository } from '../repositories/supabase-task-repository.js';
@@ -485,6 +491,62 @@ export class ApiStorage implements IStorage {
 		}
 	}
 
+	/**
+	 * Update task or subtask status by ID - for API storage
+	 */
+	async updateTaskStatus(
+		taskId: string,
+		newStatus: TaskStatus,
+		tag?: string
+	): Promise<UpdateStatusResult> {
+		await this.ensureInitialized();
+
+		try {
+			const existingTask = await this.retryOperation(() =>
+				this.repository.getTask(this.projectId, taskId)
+			);
+
+			if (!existingTask) {
+				throw new Error(`Task ${taskId} not found`);
+			}
+
+			const oldStatus = existingTask.status;
+			if (oldStatus === newStatus) {
+				return {
+					success: true,
+					oldStatus,
+					newStatus,
+					taskId
+				};
+			}
+
+			// Update the task/subtask status
+			await this.retryOperation(() =>
+				this.repository.updateTask(this.projectId, taskId, {
+					status: newStatus,
+					updatedAt: new Date().toISOString()
+				})
+			);
+
+			// Note: Parent status auto-adjustment is handled by the backend API service
+			// which has its own business logic for managing task relationships
+
+			return {
+				success: true,
+				oldStatus,
+				newStatus,
+				taskId
+			};
+		} catch (error) {
+			throw new TaskMasterError(
+				'Failed to update task status via API',
+				ERROR_CODES.STORAGE_ERROR,
+				{ operation: 'updateTaskStatus', taskId, newStatus, tag },
+				error as Error
+			);
+		}
+	}
+
 	/**
 	 * Get all available tags
 	 */

packages/tm-core/src/storage/file-storage/file-storage.ts

@@ -2,10 +2,11 @@
  * @fileoverview Refactored file-based storage implementation for Task Master
  */
 
-import type { Task, TaskMetadata } from '../../types/index.js';
+import type { Task, TaskMetadata, TaskStatus } from '../../types/index.js';
 import type {
 	IStorage,
-	StorageStats
+	StorageStats,
+	UpdateStatusResult
 } from '../../interfaces/storage.interface.js';
 import { FormatHandler } from './format-handler.js';
 import { FileOperations } from './file-operations.js';
@@ -104,9 +105,65 @@ export class FileStorage implements IStorage {
 
 	/**
 	 * Load a single task by ID from the tasks.json file
+	 * Handles both regular tasks and subtasks (with dotted notation like "1.2")
 	 */
 	async loadTask(taskId: string, tag?: string): Promise<Task | null> {
 		const tasks = await this.loadTasks(tag);
+
+		// Check if this is a subtask (contains a dot)
+		if (taskId.includes('.')) {
+			const [parentId, subtaskId] = taskId.split('.');
+			const parentTask = tasks.find((t) => String(t.id) === parentId);
+
+			if (!parentTask || !parentTask.subtasks) {
+				return null;
+			}
+
+			const subtask = parentTask.subtasks.find(
+				(st) => String(st.id) === subtaskId
+			);
+			if (!subtask) {
+				return null;
+			}
+
+			const toFullSubId = (maybeDotId: string | number): string => {
+				const depId = String(maybeDotId);
+				return depId.includes('.') ? depId : `${parentTask.id}.${depId}`;
+			};
+			const resolvedDependencies =
+				subtask.dependencies?.map((dep) => toFullSubId(dep)) ?? [];
+
+			// Return a Task-like object for the subtask with the full dotted ID
+			// Following the same pattern as findTaskById in utils.js
+			const subtaskResult = {
+				...subtask,
+				id: taskId, // Use the full dotted ID
+				title: subtask.title || `Subtask ${subtaskId}`,
+				description: subtask.description || '',
+				status: subtask.status || 'pending',
+				priority: subtask.priority || parentTask.priority || 'medium',
+				dependencies: resolvedDependencies,
+				details: subtask.details || '',
+				testStrategy: subtask.testStrategy || '',
+				subtasks: [],
+				tags: parentTask.tags || [],
+				assignee: subtask.assignee || parentTask.assignee,
+				complexity: subtask.complexity || parentTask.complexity,
+				createdAt: subtask.createdAt || parentTask.createdAt,
+				updatedAt: subtask.updatedAt || parentTask.updatedAt,
+				// Add reference to parent task for context (like utils.js does)
+				parentTask: {
+					id: parentTask.id,
+					title: parentTask.title,
+					status: parentTask.status
+				},
+				isSubtask: true
+			};
+
+			return subtaskResult;
+		}
+
+		// Handle regular task lookup
 		return tasks.find((task) => String(task.id) === String(taskId)) || null;
 	}
 
@@ -281,6 +338,156 @@ export class FileStorage implements IStorage {
 		await this.saveTasks(tasks, tag);
 	}
 
+	/**
+	 * Update task or subtask status by ID - handles file storage logic with parent/subtask relationships
+	 */
+	async updateTaskStatus(
+		taskId: string,
+		newStatus: TaskStatus,
+		tag?: string
+	): Promise<UpdateStatusResult> {
+		const tasks = await this.loadTasks(tag);
+
+		// Check if this is a subtask (contains a dot)
+		if (taskId.includes('.')) {
+			return this.updateSubtaskStatusInFile(tasks, taskId, newStatus, tag);
+		}
+
+		// Handle regular task update
+		const taskIndex = tasks.findIndex((t) => String(t.id) === String(taskId));
+
+		if (taskIndex === -1) {
+			throw new Error(`Task ${taskId} not found`);
+		}
+
+		const oldStatus = tasks[taskIndex].status;
+		if (oldStatus === newStatus) {
+			return {
+				success: true,
+				oldStatus,
+				newStatus,
+				taskId: String(taskId)
+			};
+		}
+
+		tasks[taskIndex] = {
+			...tasks[taskIndex],
+			status: newStatus,
+			updatedAt: new Date().toISOString()
+		};
+
+		await this.saveTasks(tasks, tag);
+
+		return {
+			success: true,
+			oldStatus,
+			newStatus,
+			taskId: String(taskId)
+		};
+	}
+
+	/**
+	 * Update subtask status within file storage - handles parent status auto-adjustment
+	 */
+	private async updateSubtaskStatusInFile(
+		tasks: Task[],
+		subtaskId: string,
+		newStatus: TaskStatus,
+		tag?: string
+	): Promise<UpdateStatusResult> {
+		// Parse the subtask ID to get parent ID and subtask ID
+		const parts = subtaskId.split('.');
+		if (parts.length !== 2) {
+			throw new Error(
+				`Invalid subtask ID format: ${subtaskId}. Expected format: parentId.subtaskId`
+			);
+		}
+
+		const [parentId, subIdRaw] = parts;
+		const subId = subIdRaw.trim();
+		if (!/^\d+$/.test(subId)) {
+			throw new Error(
+				`Invalid subtask ID: ${subId}. Subtask ID must be a positive integer.`
+			);
+		}
+		const subtaskNumericId = Number(subId);
+
+		// Find the parent task
+		const parentTaskIndex = tasks.findIndex(
+			(t) => String(t.id) === String(parentId)
+		);
+
+		if (parentTaskIndex === -1) {
+			throw new Error(`Parent task ${parentId} not found`);
+		}
+
+		const parentTask = tasks[parentTaskIndex];
+
+		// Find the subtask within the parent task
+		const subtaskIndex = parentTask.subtasks.findIndex(
+			(st) => st.id === subtaskNumericId || String(st.id) === subId
+		);
+
+		if (subtaskIndex === -1) {
+			throw new Error(
+				`Subtask ${subtaskId} not found in parent task ${parentId}`
+			);
+		}
+
+		const oldStatus = parentTask.subtasks[subtaskIndex].status || 'pending';
+		if (oldStatus === newStatus) {
+			return {
+				success: true,
+				oldStatus,
+				newStatus,
+				taskId: subtaskId
+			};
+		}
+
+		const now = new Date().toISOString();
+
+		// Update the subtask status
+		parentTask.subtasks[subtaskIndex] = {
+			...parentTask.subtasks[subtaskIndex],
+			status: newStatus,
+			updatedAt: now
+		};
+
+		// Auto-adjust parent status based on subtask statuses
+		const subs = parentTask.subtasks;
+		let parentNewStatus = parentTask.status;
+		if (subs.length > 0) {
+			const norm = (s: any) => s.status || 'pending';
+			const isDoneLike = (s: any) => {
+				const st = norm(s);
+				return st === 'done' || st === 'completed';
+			};
+			const allDone = subs.every(isDoneLike);
+			const anyInProgress = subs.some((s) => norm(s) === 'in-progress');
+			const anyDone = subs.some(isDoneLike);
+			if (allDone) parentNewStatus = 'done';
+			else if (anyInProgress || anyDone) parentNewStatus = 'in-progress';
+		}
+
+		// Always bump updatedAt; update status only if changed
+		tasks[parentTaskIndex] = {
+			...parentTask,
+			...(parentNewStatus !== parentTask.status
+				? { status: parentNewStatus }
+				: {}),
+			updatedAt: now
+		};
+
+		await this.saveTasks(tasks, tag);
+
+		return {
+			success: true,
+			oldStatus,
+			newStatus,
+			taskId: subtaskId
+		};
+	}
+
 	/**
 	 * Delete a task
 	 */