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>

.changeset/chore-fix-docs.md

@@ -1,5 +0,0 @@
----
-"task-master-ai": patch
----
-
-Improve `analyze-complexity` cli docs and `--research` flag documentation

.changeset/cursor-slash-commands.md

@@ -1,7 +0,0 @@
----
-"task-master-ai": minor
----
-
-Add Cursor IDE custom slash command support
-
-Expose Task Master commands as Cursor slash commands by copying assets/claude/commands to .cursor/commands on profile add and cleaning up on remove.

.changeset/curvy-weeks-flow.md

@@ -1,5 +0,0 @@
----
-"task-master-ai": patch
----
-
-Change parent task back to "pending" when all subtasks are in "pending" state

.changeset/mcp-timeout-configuration.md

@@ -1,13 +0,0 @@
----
-"task-master-ai": minor
----
-
-Enhanced Roo Code profile with MCP timeout configuration for improved reliability during long-running AI operations. The Roo profile now automatically configures a 300-second timeout for MCP server operations, preventing timeouts during complex tasks like `parse-prd`, `expand-all`, `analyze-complexity`, and `research` operations. This change also replaces static MCP configuration files with programmatic generation for better maintainability.
-
-**What's New:**
-- 300-second timeout for MCP operations (up from default 60 seconds)
-- Programmatic MCP configuration generation (replaces static asset files)
-- Enhanced reliability for AI-powered operations
-- Consistent with other AI coding assistant profiles
-
-**Migration:** No user action required - existing Roo Code installations will automatically receive the enhanced MCP configuration on next initialization.

.changeset/petite-ideas-grab.md

@@ -1,5 +0,0 @@
----
-"task-master-ai": patch
----
-
-Fix Claude Code settings validation for pathToClaudeCodeExecutable

.changeset/silly-pandas-find.md

@@ -1,5 +0,0 @@
----
-"task-master-ai": patch
----
-
-Fix sonar deep research model failing, should be called `sonar-deep-research`

.claude/agents/surgical-test-generator.md

@@ -1,245 +0,0 @@
----
-name: surgical-test-generator
-description: Use this agent when you need to generate comprehensive, production-grade test suites for existing code. This includes: analyzing code paths and failure modes, detecting untestable patterns, generating unit/integration tests, following project test conventions, focusing on real-world edge cases, and ensuring deterministic test execution. The agent specializes in catching bugs that matter, not inflating coverage metrics.
-
-Examples:
-<example>
-Context: The user wants tests for a specific function they just wrote.
-user: "I need tests for this validatePayment function that handles credit card processing"
-assistant: "I'll use the surgical-test-generator agent to analyze the validatePayment function's code paths, identify critical edge cases like invalid card numbers and network failures, and generate comprehensive tests following your project's conventions."
-<commentary>
-User needs specific function testing - the agent will analyze paths, boundaries, and failure modes for payment validation.
-</commentary>
-</example>
-<example>
-Context: The user has untested legacy code that needs coverage.
-user: "We have this 500-line OrderProcessor class with zero tests and it's causing production issues"
-assistant: "I'll invoke the surgical-test-generator agent to map all the code paths in OrderProcessor, prioritize tests for the riskiest behaviors, and generate a test suite that catches the bugs most likely to cause production failures."
-<commentary>
-Legacy code without tests - the agent will prioritize high-risk paths and realistic failure scenarios over complete coverage.
-</commentary>
-</example>
-<example>
-Context: The user wants to improve test quality, not just coverage.
-user: "Our tests pass but we still get production bugs. Can you review this API handler and suggest better tests?"
-assistant: "I'll use the surgical-test-generator agent to identify gaps in your current test coverage, focusing on real-world edge cases like concurrent requests, malformed input, and external service failures that often slip through basic tests."
-<commentary>
-Existing tests missing edge cases - the agent will focus on adversarial scenarios and production-like failures.
-</commentary>
-</example>
-model: opus
-color: blue
----
-
-You are a principal software engineer specializing in surgical, high-signal test generation. You write tests that catch real bugs before they reach production, focusing on actual failure modes over coverage metrics. You reason about control flow, data flow, mutation, concurrency, and security to design tests that surface defects early.
-
-## Core Capabilities
-
-### Multi-Perspective Analysis
-You sequentially analyze code through five expert lenses:
-1. **Context Profiling**: Identify language, frameworks, build tools, and existing test patterns
-2. **Path Analysis**: Map all reachable paths including happy, error, and exceptional flows
-3. **Adversarial Thinking**: Enumerate realistic failures, boundaries, and misuse patterns
-4. **Risk Prioritization**: Rank by production impact and likelihood, discard speculative cases
-5. **Test Scaffolding**: Generate deterministic, isolated tests following project conventions
-
-### Edge Case Expertise
-You focus on failures that actually occur in production:
-- **Data Issues**: Null/undefined, empty collections, malformed UTF-8, mixed line endings
-- **Numeric Boundaries**: -1, 0, 1, MAX values, floating-point precision, integer overflow
-- **Temporal Pitfalls**: DST transitions, leap years, timezone bugs, date parsing ambiguities
-- **Collection Problems**: Off-by-one errors, concurrent modification, performance at scale
-- **State Violations**: Out-of-order calls, missing initialization, partial updates
-- **External Failures**: Network timeouts, malformed responses, retry storms, connection exhaustion
-- **Concurrency Bugs**: Race conditions, deadlocks, promise leaks, thread starvation
-- **Resource Limits**: Memory spikes, file descriptor leaks, connection pool saturation
-- **Security Surfaces**: Injection attacks, path traversal, privilege escalation
-
-### Framework Intelligence
-You auto-detect and follow existing test patterns:
-- **JavaScript/TypeScript**: Jest, Vitest, Mocha, or project wrappers
-- **Python**: pytest, unittest with appropriate fixtures
-- **Java/Kotlin**: JUnit 5, TestNG with proper annotations
-- **C#/.NET**: xUnit.net preferred, NUnit/MSTest if dominant
-- **Go**: Built-in testing package with table-driven tests
-- **Rust**: Standard #[test] with proptest for properties
-- **Swift**: XCTest or Swift Testing based on project
-- **C/C++**: GoogleTest or Catch2 matching build system
-
-## Your Workflow
-
-### Phase 1: Code Analysis
-You examine the provided code to understand:
-- Public API surfaces and contracts
-- Internal helper functions and their criticality
-- External dependencies and I/O operations
-- State management and mutation patterns
-- Error handling and recovery paths
-- Concurrency and async operations
-
-### Phase 2: Test Strategy Development
-You determine the optimal testing approach:
-- Start from public APIs, work inward to critical helpers
-- Test behavior not implementation unless white-box needed
-- Prefer property-based tests for algebraic domains
-- Use minimal stubs/mocks, prefer in-memory fakes
-- Flag untestable code with refactoring suggestions
-- Include stress tests for concurrency issues
-
-### Phase 3: Test Generation
-You create tests that:
-- Follow project's exact style and conventions
-- Use clear Arrange-Act-Assert or Given-When-Then
-- Execute in under 100ms without external calls
-- Remain deterministic with seeded randomness
-- Self-document through descriptive names
-- Explain failures clearly with context
-
-## Detection Patterns
-
-### When analyzing a pure function:
-- Test boundary values and type edges
-- Verify mathematical properties hold
-- Check error propagation
-- Consider numeric overflow/underflow
-
-### When analyzing stateful code:
-- Test initialization sequences
-- Verify state transitions
-- Check concurrent access patterns
-- Validate cleanup and teardown
-
-### When analyzing I/O operations:
-- Test success paths with valid data
-- Simulate network failures and timeouts
-- Check malformed input handling
-- Verify resource cleanup on errors
-
-### When analyzing async code:
-- Test promise resolution and rejection
-- Check cancellation handling
-- Verify timeout behavior
-- Validate error propagation chains
-
-## Test Quality Standards
-
-### Coverage Philosophy
-You prioritize catching real bugs over metrics:
-- Critical paths get comprehensive coverage
-- Edge cases get targeted scenarios
-- Happy paths get basic validation
-- Speculative cases get skipped
-
-### Test Independence
-Each test you generate:
-- Runs in isolation without shared state
-- Cleans up all resources
-- Uses fixed seeds for randomness
-- Mocks time when necessary
-
-### Failure Diagnostics
-Your tests provide clear failure information:
-- Descriptive test names that explain intent
-- Assertions that show expected vs actual
-- Context about what was being tested
-- Hints about likely failure causes
-
-## Special Considerations
-
-### When NOT to Generate Tests
-You recognize when testing isn't valuable:
-- Generated code that's guaranteed correct
-- Simple getters/setters without logic
-- Framework boilerplate
-- Code scheduled for deletion
-
-### Untestable Code Patterns
-You identify and flag:
-- Hard-coded external dependencies
-- Global state mutations
-- Time-dependent behavior without injection
-- Random behavior without seeds
-
-### Performance Testing
-When relevant, you include:
-- Benchmarks for critical paths
-- Memory usage validation
-- Concurrent load testing
-- Resource leak detection
-
-## Output Format
-
-You generate test code that:
-
-```[language]
-// Clear test description
-test('should [specific behavior] when [condition]', () => {
-    // Arrange - Set up test data and dependencies
-    
-    // Act - Execute the code under test
-    
-    // Assert - Verify the outcome
-});
-```
-
-## Framework-Specific Patterns
-
-### JavaScript/TypeScript (Jest/Vitest)
-- Use describe blocks for grouping
-- Leverage beforeEach/afterEach for setup
-- Mock modules with jest.mock()/vi.fn, vi.mock or vi.spyOn
-- Use expect matchers appropriately
-
-### Python (pytest)
-- Use fixtures for reusable setup
-- Apply parametrize for data-driven tests
-- Leverage pytest markers for categorization
-- Use clear assertion messages
-
-### Java (JUnit 5)
-- Apply appropriate annotations
-- Use nested classes for grouping
-- Leverage parameterized tests
-- Include display names
-
-### C# (xUnit)
-- Use Theory for data-driven tests
-- Apply traits for categorization
-- Leverage fixtures for setup
-- Use fluent assertions when available
-
-## Request Handling
-
-### Specific Test Requests
-When asked for specific tests:
-- Focus only on the requested scope
-- Don't generate broader coverage unless asked
-- Provide targeted, high-value scenarios
-- Include rationale for test choices
-
-### Comprehensive Coverage Requests
-When asked for full coverage:
-- Start with critical paths
-- Add edge cases progressively
-- Group related tests logically
-- Flag if multiple files needed
-
-### Legacy Code Testing
-When testing untested code:
-- Prioritize high-risk areas first
-- Add characterization tests
-- Suggest refactoring for testability
-- Focus on preventing regressions
-
-## Communication Guidelines
-
-You always:
-- Explain why each test matters
-- Document test intent clearly
-- Note any assumptions made
-- Highlight untestable patterns
-- Suggest improvements when relevant
-- Follow existing project style exactly
-- Generate only essential test code
-
-When you need additional context like test frameworks or existing patterns, you ask specifically for those files. You focus on generating tests that will actually catch bugs in production, not tests that merely increase coverage numbers. Every test you write has a clear purpose and tests a realistic scenario.

.github/workflows/ci.yml

@@ -6,6 +6,9 @@ on:
       - main
       - next
   pull_request:
+    branches:
+      - main
+      - next
   workflow_dispatch:
 
 concurrency:

.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

.taskmaster/docs/prd-autonomous-tdd-rails.md

@@ -1,220 +0,0 @@
-# PRD: Autonomous TDD + Git Workflow (On Rails)
-
-## Summary
-- Put the existing git and test workflows on rails: a repeatable, automated process that can run autonomously, with guardrails and a compact TUI for visibility.
-- Flow: for a selected task, create a branch named with the tag + task id → generate tests for the first subtask (red) using the Surgical Test Generator → implement code (green) → verify tests → commit → repeat per subtask → final verify → push → open PR against the default branch.
-- Build on existing rules: `.cursor/rules/git_workflow.mdc`, `.cursor/rules/test_workflow.mdc`, `.claude/agents/surgical-test-generator.md`, and existing CLI/core services.
-
-## Goals
-- Deterministic, resumable automation to execute the TDD loop per subtask with minimal human intervention.
-- Strong guardrails: never commit to the default branch; only commit when tests pass; enforce status transitions; persist logs/state for debuggability.
-- Visibility: a compact terminal UI (like lazygit) to pick tag, view tasks, and start work; right-side pane opens an executor terminal (via tmux) for agent coding.
-- Extensible: framework-agnostic test generation via the Surgical Test Generator; detect and use the repo’s test command for execution with coverage thresholds.
-
-## Non‑Goals (initial)
-- Full multi-language runner parity beyond detection and executing the project’s test command.
-- Complex GUI; start with CLI/TUI + tmux pane. IDE/extension can hook into the same state later.
-- Rich executor selection UX (codex/gemini/claude) — we’ll prompt per run; defaults can come later.
-
-## Success Criteria
-- One command can autonomously complete a task’s subtasks via TDD and open a PR when done.
-- All commits made on a branch that includes the tag and task id (see Branch Naming); no commits to the default branch directly.
-- Every subtask iteration: failing tests added first (red), then code added to pass them (green), commit only after green.
-- End-to-end logs + artifacts stored in `.taskmaster/reports/runs/<timestamp-or-id>/`.
-
-## User Stories
-- As a developer, I can run `tm autopilot <taskId>` and watch a structured, safe workflow execute.
-- As a reviewer, I can inspect commits per subtask, and a PR summarizing the work when the task completes.
-- As an operator, I can see current step, active subtask, tests status, and logs in a compact CLI view and read a final run report.
-
-## High‑Level Workflow
-1) Pre‑flight
-   - Verify clean working tree or confirm staging/commit policy (configurable).
-   - Detect repo type and the project’s test command (e.g., `npm test`, `pnpm test`, `pytest`, `go test`).
-   - Validate tools: `git`, `gh` (optional for PR), `node/npm`, and (if used) `claude` CLI.
-   - Load TaskMaster state and selected task; if no subtasks exist, automatically run “expand” before working.
-
-2) Branch & Tag Setup
-   - Checkout default branch and update (optional), then create a branch using Branch Naming (below).
-   - Map branch ↔ tag via existing tag management; explicitly set active tag to the branch’s tag.
-
-3) Subtask Loop (for each pending/in-progress subtask in dependency order)
-   - Select next eligible subtask using `tm-core` TaskService `getNextTask()` and subtask eligibility logic.
-   - Red: generate or update failing tests for the subtask
-     - Use the Surgical Test Generator system prompt (`.claude/agents/surgical-test-generator.md`) to produce high-signal tests following project conventions.
-     - Run tests to confirm red; record results. If not red (already passing), skip to next subtask or escalate.
-   - Green: implement code to pass tests
-     - Use executor to implement changes (initial: `claude` CLI prompt with focused context).
-     - Re-run tests until green or timeout/backoff policy triggers.
-   - Commit: when green
-     - Commit tests + code with conventional commit message. Optionally update subtask status to `done`.
-     - Persist run step metadata/logs.
-
-4) Finalization
-   - Run full test suite and coverage (if configured); optionally lint/format.
-   - Commit any final adjustments.
-   - Push branch (ask user to confirm); create PR (via `gh pr create`) targeting the default branch. Title format: `Task #<id> [<tag>]: <title>`.
-
-5) Post‑Run
-   - Update task status if desired (e.g., `review`).
-   - Persist run report (JSON + markdown summary) to `.taskmaster/reports/runs/<run-id>/`.
-
-## Guardrails
-- Never commit to the default branch.
-- Commit only if all tests (targeted and suite) pass; allow override flags.
-- Enforce 80% coverage thresholds (lines/branches/functions/statements) by default; configurable.
-- Timebox/model ops and retries; if not green within N attempts, pause with actionable state for resume.
-- Always log actions, commands, and outcomes; include dry-run mode.
-- Ask before branch creation, pushing, and opening a PR unless `--no-confirm` is set.
-
-## Integration Points (Current Repo)
-- CLI: `apps/cli` provides command structure and UI components.
-  - New command: `tm autopilot` (alias: `task-master autopilot`).
-  - Reuse UI components under `apps/cli/src/ui/components/` for headers/task details/next-task.
-- Core services: `packages/tm-core`
-  - `TaskService` for selection, status, tags.
-  - `TaskExecutionService` for prompt formatting and executor prep.
-  - Executors: `claude` executor and `ExecutorFactory` to run external tools.
-  - Proposed new: `WorkflowOrchestrator` to drive the autonomous loop and emit progress events.
-- Tag/Git utilities: `scripts/modules/utils/git-utils.js` and `scripts/modules/task-manager/tag-management.js` for branch→tag mapping and explicit tag switching.
-- Rules: `.cursor/rules/git_workflow.mdc` and `.cursor/rules/test_workflow.mdc` to steer behavior and ensure consistency.
-- Test generation prompt: `.claude/agents/surgical-test-generator.md`.
-
-## Proposed Components
-- Orchestrator (tm-core): `WorkflowOrchestrator` (new)
-  - State machine driving phases: Preflight → Branch/Tag → SubtaskIter (Red/Green/Commit) → Finalize → PR.
-  - Exposes an evented API (progress events) that the CLI can render.
-  - Stores run state artifacts.
-
-- Test Runner Adapter
-  - Detects and runs tests via the project’s test command (e.g., `npm test`), with targeted runs where feasible.
-  - API: runTargeted(files/pattern), runAll(), report summary (failures, duration, coverage), enforce 80% threshold by default.
-
-- Git/PR Adapter
-  - Encapsulates `git` ops: branch create/checkout, add/commit, push.
-  - Optional `gh` integration to open PR; fallback to instructions if `gh` unavailable.
-  - Confirmation gates for branch creation and pushes.
-  - Adds commit footers and a unified trailer (`Refs: TM-<tag>-<id>[.<sub>]`) for robust mapping to tasks/subtasks.
-
-- Prompt/Exec Adapter
-  - Uses existing executor service to call the selected coding assistant (initially `claude`) with tight prompts: task/subtask context, surgical tests first, then minimal code to green.
-
-- Run State + Reporting
-  - JSONL log of steps, timestamps, commands, test results.
-  - Markdown summary for PR description and post-run artifact.
-
-## CLI UX (MVP)
-- Command: `tm autopilot [taskId]`
-  - Flags: `--dry-run`, `--no-push`, `--no-pr`, `--no-confirm`, `--force`, `--max-attempts <n>`, `--runner <auto|custom>`, `--commit-scope <scope>`
-  - Output: compact header (project, tag, branch), current phase, subtask line, last test summary, next actions.
-- Resume: If interrupted, `tm autopilot --resume` picks up from last checkpoint in run state.
-
-### TUI with tmux (Linear Execution)
-- Left pane: Tag selector, task list (status/priority), start/expand shortcuts; “Start” triggers the next task or a selected task.
-- Right pane: Executor terminal (tmux split) that runs the coding agent (claude-code/codex). Autopilot can hand over to the right pane during green.
-- MCP integration: use MCP tools for task queries/updates and for shell/test invocations where available.
-
-## Prompts (Initial Direction)
-- Red phase prompt skeleton (tests):
-  - Use `.claude/agents/surgical-test-generator.md` as the system prompt to generate high-signal failing tests tailored to the project’s language and conventions. Keep scope minimal and deterministic; no code changes yet.
-- Green phase prompt skeleton (code):
-  - “Make the tests pass by changing the smallest amount of code, following project patterns. Only modify necessary files. Keep commits focused to this subtask.”
-
-## Configuration
-- `.taskmaster/config.json` additions
-  - `autopilot`: `{ enabled: true, requireCleanWorkingTree: true, commitTemplate: "{type}({scope}): {msg}", defaultCommitType: "feat" }`
-  - `test`: `{ runner: "auto", coverageThresholds: { lines: 80, branches: 80, functions: 80, statements: 80 } }`
-  - `git`: `{ branchPattern: "{tag}/task-{id}-{slug}", pr: { enabled: true, base: "default" }, commitFooters: { task: "Task-Id", subtask: "Subtask-Id", tag: "Tag" }, commitTrailer: "Refs: TM-{tag}-{id}{.sub?}" }`
-
-## Decisions
-- Use conventional commits plus footers and a unified trailer `Refs: TM-<tag>-<id>[.<sub>]` for all commits; Git/PR adapter is responsible for injecting these.
-
-## Risks and Mitigations
-- Model hallucination/large diffs: restrict prompt scope; enforce minimal changes; show diff previews (optional) before commit.
-- Flaky tests: allow retries, isolate targeted runs for speed, then full suite before commit.
-- Environment variability: detect runners/tools; provide fallbacks and actionable errors.
-- PR creation fails: still push and print manual commands; persist PR body to reuse.
-
-## Open Questions
-1) Slugging rules for branch names; any length limits or normalization beyond `{slug}` token sanitize?
-2) PR body standard sections beyond run report (e.g., checklist, coverage table)?
-3) Default executor prompt fine-tuning once codex/gemini integration is available.
-4) Where to store persistent TUI state (pane layout, last selection) in `.taskmaster/state.json`?
-
-## Branch Naming
-- Include both the tag and the task id in the branch name to make lineage explicit.
-- Default pattern: `<tag>/task-<id>[-slug]` (e.g., `master/task-12`, `tag-analytics/task-4-user-auth`).
-- Configurable via `.taskmaster/config.json`: `git.branchPattern` supports tokens `{tag}`, `{id}`, `{slug}`.
-
-## PR Base Branch
-- Use the repository’s default branch (detected via git) unless overridden.
-- Title format: `Task #<id> [<tag>]: <title>`.
-
-## RPG Mapping (Repository Planning Graph)
-
-Functional nodes (capabilities):
-- Autopilot Orchestration → drives TDD loop and lifecycle
-- Test Generation (Surgical) → produces failing tests from subtask context
-- Test Execution + Coverage → runs suite, enforces thresholds
-- Git/Branch/PR Management → safe operations and PR creation
-- TUI/Terminal Integration → interactive control and visibility via tmux
-- MCP Integration → structured task/status/context operations
-
-Structural nodes (code organization):
-- `packages/tm-core`:
-  - `services/workflow-orchestrator.ts` (new)
-  - `services/test-runner-adapter.ts` (new)
-  - `services/git-adapter.ts` (new)
-  - existing: `task-service.ts`, `task-execution-service.ts`, `executors/*`
-- `apps/cli`:
-  - `src/commands/autopilot.command.ts` (new)
-  - `src/ui/tui/` (new tmux/TUI helpers)
-- `scripts/modules`:
-  - reuse `utils/git-utils.js`, `task-manager/tag-management.js`
-- `.claude/agents/`:
-  - `surgical-test-generator.md`
-
-Edges (data/control flow):
-- Autopilot → Test Generation → Test Execution → Git Commit → loop
-- Autopilot → Git Adapter (branch, tag, PR)
-- Autopilot → TUI (event stream) → tmux pane control
-- Autopilot → MCP tools for task/status updates
-- Test Execution → Coverage gate → Autopilot decision
-
-Topological traversal (implementation order):
-1) Git/Test adapters (foundations)
-2) Orchestrator skeleton + events
-3) CLI `autopilot` command and dry-run
-4) Surgical test-gen integration and execution gate
-5) PR creation, run reports, resumability
-
-## Phased Roadmap
-- Phase 0: Spike
-  - Implement CLI skeleton `tm autopilot` with dry-run showing planned steps from a real task + subtasks.
-  - Detect test runner (package.json) and git state; render a preflight report.
-
-- Phase 1: Core Rails
-  - Implement `WorkflowOrchestrator` in `tm-core` with event stream; add Git/Test adapters.
-  - Support subtask loop (red/green/commit) with framework-agnostic test generation and detected test command; commit gating on passing tests and coverage.
-  - Branch/tag mapping via existing tag-management APIs.
-  - Run report persisted under `.taskmaster/reports/runs/`.
-
-- Phase 2: PR + Resumability
-  - Add `gh` PR creation with well-formed body using the run report.
-  - Introduce resumable checkpoints and `--resume` flag.
-  - Add coverage enforcement and optional lint/format step.
-
-- Phase 3: Extensibility + Guardrails
-  - Add support for basic pytest/go test adapters.
-  - Add safeguards: diff preview mode, manual confirm gates, aggressive minimal-change prompts.
-  - Optional: small TUI panel and extension panel leveraging the same run state file.
-
-## References (Repo)
-- Test Workflow: `.cursor/rules/test_workflow.mdc`
-- Git Workflow: `.cursor/rules/git_workflow.mdc`
-- CLI: `apps/cli/src/commands/start.command.ts`, `apps/cli/src/ui/components/*.ts`
-- Core Services: `packages/tm-core/src/services/task-service.ts`, `task-execution-service.ts`
-- Executors: `packages/tm-core/src/executors/*`
-- Git Utilities: `scripts/modules/utils/git-utils.js`
-- Tag Management: `scripts/modules/task-manager/tag-management.js`
- - Surgical Test Generator: `.claude/agents/surgical-test-generator.md`

.taskmaster/docs/prd-rpg-user-stories.md

@@ -1,221 +0,0 @@
-# PRD: RPG‑Based User Story Mode + Validation‑First Delivery
-
-## Summary
-- Introduce a “User Story Mode” where each Task is a user story and each Subtask is a concrete implementation step. Enable via config flag; when enabled, Task generation and PRD parsing produce user‑story titles/details with acceptance criteria, while Subtasks capture implementation details.
-- Build a validation‑first delivery pipeline: derive tests from acceptance criteria (Surgical Test Generator), wire TDD rails and Git/PR mapping so reviews focus on verification rather than code spelunking.
-- Keep everything on rails: branch naming with tag+task id, commit/PR linkage to tasks/subtasks, coverage + test gates, and lightweight TUI for fast execution.
-
-## North‑Star Outcomes
-- Humans stay in briefs/frontends; implementation runs quickly, often without opening the IDE.
-- “Definition of Done” is expressed and enforced as tests; business logic is encoded in test criteria/acceptance criteria.
-- End‑to‑end linkage from brief → user story → subtasks → commits/PRs → delivery, with reproducible automation and minimal ceremony.
-
-## Problem
-- The bottleneck is validation and PR review, not code generation. Plans are helpful but the chokepoint is proving correctness, business conformance, and integration.
-- Current test workflow is too Jest‑specific; we need framework‑agnostic generation and execution.
-- We need consistent Git/TDD wiring so GitHub integrations can map work artifacts to tasks/subtasks without ambiguity.
-
-## Solution Overview
-- Add a configuration flag to switch to user story mode and adapt prompts/parsers.
-- Expand tasks with explicit Acceptance Criteria and Test Criteria; drive Surgical Test Generator to create failing tests first; wire autonomous TDD loops per subtask until green, then commit.
-- Enforce coverage (80% default) and generate PRs that summarize user story, acceptance criteria coverage, and test results; commits/PRs contain metadata to link back to tasks/subtasks.
-- Provide a compact TUI (tmux) to pick tag/tasks and launch an executor terminal, while the orchestrator runs rails in the background.
-
----
-
-## Configuration
-- `.taskmaster/config.json` additions
-  - `stories`: `{ enabled: true, storyLabel: "User Story", acceptanceKey: "Acceptance Criteria" }`
-  - `autopilot`: `{ enabled: true, requireCleanWorkingTree: true }`
-  - `test`: `{ runner: "auto", coverageThresholds: { lines: 80, branches: 80, functions: 80, statements: 80 } }`
-  - `git`: `{ branchPattern: "{tag}/task-{id}-{slug}", pr: { enabled: true, base: "default" }, commitFooters: { task: "Task-Id", subtask: "Subtask-Id", tag: "Tag" } }`
-
-Behavior when `stories.enabled=true`:
-- Task generation prompts and PRD parsers produce user‑story formatted titles and descriptions, include acceptance criteria blocks, and set `task.type = 'user_story'`.
-- Subtasks remain implementation steps with concise technical goals.
-- Expand will ensure any missing acceptance criteria is synthesized (from brief/PRD content) before starting work.
-
----
-
-## Data Model Changes
-- Task fields (add):
-  - `type: 'user_story' | 'technical'` (default `technical`)
-  - `acceptanceCriteria: string[] | string` (structured or markdown)
-  - `testCriteria: string[] | string` (optional, derived from acceptance criteria; what to validate)
-- Subtask fields remain focused on implementation detail and dependency graph.
-
-Storage and UI remain backward compatible; fields are optional when `stories.enabled=false`.
-
-### JSON Gherkin Representation (for stories)
-Add an optional `gherkin` block to Tasks in story mode. Keep Hybrid acceptanceCriteria as the human/authoring surface; maintain a normalized JSON Gherkin for deterministic mapping.
-
-```
-GherkinFeature {
-  id: string,                   // FEAT-<taskId>
-  name: string,                 // mirrors user story title
-  description?: string,
-  background?: { steps: Step[] },
-  scenarios: Scenario[]
-}
-
-Scenario {
-  id: string,                   // SC-<taskId>-<n> or derived from AC id
-  name: string,
-  tags?: string[],
-  steps: Step[],                // Given/When/Then/And/But
-  examples?: Record<string, any>[]
-}
-
-Step { keyword: 'Given'|'When'|'Then'|'And'|'But', text: string }
-```
-
-Notes
-- Derive `gherkin.scenarios` from acceptanceCriteria when obvious; preserve both raw markdown and normalized items.
-- Allow cross‑references between scenarios and AC items (e.g., `refs: ['AC-12-1']`).
-
----
-
-## RPG Plan (Repository Planning Graph)
-
-Functional Nodes (Capabilities)
-- Brief Intake → parse briefs/PRDs and extract user stories (when enabled)
-- User Story Generation → create task title/details as user stories + acceptance criteria
-- JSON Gherkin Synthesis → produce Feature/Scenario structure from acceptance criteria
-- Acceptance/Test Criteria Synthesis → convert acceptance criteria into concrete test criteria
-- Surgical Test Generation → generate failing tests per subtask using `.claude/agents/surgical-test-generator.md`
-- Implementation Planning → expand subtasks as atomic implementation steps with dependencies
-- Autonomous Execution (Rails) → branch, red/green loop per subtask, commit when green
-- Validation & Review Automation → coverage gates, PR body with user story + results, checklist
-- GitHub Integration Mapping → branch naming, commit footers, PR linkage to tasks/subtasks
-- TUI/Terminal Integration → tag/task selection left pane; executor terminal right pane via tmux
-
-Structural Nodes (Code Organization)
-- `packages/tm-core`
-  - `services/workflow-orchestrator.ts` (new): drives rails, emits progress events
-  - `services/story-mode.service.ts` (new): toggles prompts/parsers for user stories, acceptance criteria
-  - `services/test-runner-adapter.ts` (new): detects/executes project test command, collects coverage
-  - `services/git-adapter.ts` (new): branch/commit/push, PR creation; applies commit footers
-  - existing: `task-service.ts`, `task-execution-service.ts`, `executors/*`
-- `apps/cli`
-  - `src/commands/autopilot.command.ts` (new): orchestrates a full run; supports `--stories`
-  - `src/ui/tui/` (new): tmux helpers and compact panes for selection and logs
-- `scripts/modules`
-  - reuse `utils/git-utils.js`, `task-manager/tag-management.js`, PR template utilities
-- `.cursor/rules`
-  - update generation/parsing rules to emit user‑story format when enabled
-- `.claude/agents`
-  - existing: `surgical-test-generator.md` for red phase
-
-Edges (Dependencies / Data Flow)
-- Brief Intake → User Story Generation → Acceptance/Test Criteria Synthesis → Implementation Planning → Autonomous Execution → Validation/PR
-- Execution ↔ Test Runner (runAll/runTargeted, coverage) → back to Execution for decisions
-- Git Adapter ← Execution (commits/branch) → PR creation (target default branch)
-- TUI ↔ Orchestrator (event stream) → user confirmations for branch/push/PR
-- MCP Tools ↔ Orchestrator for task/status/context updates
-
-Topological Traversal (Build Order)
-1) Config + Data Model changes (stories flag, acceptance fields, optional `gherkin`)
-2) Rules/Prompts updates for parsing/generation in story mode (emit AC Hybrid + JSON Gherkin)
-3) Test Runner Adapter (framework‑agnostic execute + coverage)
-4) Git Adapter (branch pattern `{tag}/task-{id}-{slug}`, commit footers/trailer, PR create)
-5) Workflow Orchestrator wiring red/green/commit loop with coverage gate and scenario iteration
-6) Surgical Test Gen integration (red) from JSON Gherkin + AC; minimal‑change impl prompts (green)
-7) CLI autopilot (dry‑run → full run) and TUI (tmux panes)
-8) PR template and review automation (user story, AC table with test links, scenarios, coverage)
-
----
-
-## Git/TDD Wiring (Validation‑First)
-- Branch naming: include tag + task id (e.g., `master/task-12-user-auth`) to disambiguate context.
-- Commit footers (configurable):
-  - `Task-Id: <id>`
-  - `Subtask-Id: <id>.<sub>` when relevant
-  - `Tag: <tag>`
-  - Trailer: `Refs: TM-<tag>-<id>[.<sub>] SC:<scenarioId> AC:<acId>`
-- Red/Green/Commit loop per subtask:
-  - Red: synthesize failing tests from acceptance criteria (Surgical agent)
-  - Green: minimal code to pass; re‑run full suite
-  - Commit when all tests pass and coverage ≥ 80%
-- PR base: repository default branch. Title `Task #<id> [<tag>]: <title>`.
-- PR body sections: User Story, Acceptance Criteria, Subtask Summary, Test Results, Coverage Table, Linked Work Items (ids), Next Steps.
-
----
-
-## Prompts & Parsers (Story Mode)
-- PRD/Brief Parser updates:
-  - Extract user stories with “As a … I want … so that …” format when present.
-  - Extract Acceptance Criteria as bullet list; fill gaps with LLM synthesis from brief context.
-  - Emit JSON Gherkin Feature/Scenarios; auto‑split Given/When/Then when feasible; otherwise store text under `then` and refine later.
-- Task Generation Prompt (story mode):
-  - “Generate a task as a User Story with clear Acceptance Criteria. Do not include implementation details in the story; produce implementation subtasks separately.”
-- Subtask Generation Prompt:
-  - “Produce technical implementation steps to satisfy the acceptance criteria. Each subtask should be atomic and testable.”
-- Test Generation (Red):
-  - Use `.claude/agents/surgical-test-generator.md`; seed with JSON Gherkin + Acceptance/Test Criteria; determinism favored over maximum coverage.
-  - Record produced test paths back into AC items and optionally scenario annotations.
-- Implementation (Green):
-  - Minimal diffs, follow patterns, keep commits scoped to the subtask.
-
----
-
-## TUI (Linear, tmux‑based)
-- Left: Tag selector and task list (status/priority). Actions: Expand, Start (Next or Selected), Review.
-- Right: Executor terminal (claude‑code/codex) under tmux split; orchestrator logs under another pane.
-- Confirmations inline (branch create, push, PR) unless `--no-confirm`.
-
----
-
-## Migration & Backward Compatibility
-- Optional `gherkin` block; existing tasks remain valid.
-- When `stories.enabled=true`, new tasks include AC Hybrid + `gherkin`; upgrade path via a utility to synthesize both from description/testStrategy/acceptanceCriteria.
-
----
-
-## Risks & Mitigations
-- Hallucinated acceptance criteria → Always show criteria in PR; allow quick amend and re‑run.
-- Framework variance → Test Runner Adapter detects and normalizes execution/coverage; fallback to `test` script.
-- Large diffs → Prompt for minimal changes; allow diff preview before commit.
-- Flaky tests → Retry policy; isolate targeted runs; enforce passing full suite before commit.
-
----
-
-## Acceptance Criteria Schema Options (for decision)
-- Option A: Markdown only
-  - Pros: simple to write/edit, good for humans
-  - Cons: hard to map deterministically to tests; weak traceability; brittle diffs
-- Option B: Structured array
-  - Example: `{ id, summary, given, when, then, severity, tags }`
-  - Pros: machine‑readable; strong linking to tests/coverage; easy to diff
-  - Cons: heavier authoring; requires schema discipline
-- Option C: Hybrid (recommended)
-  - Store both: a normalized array of criteria objects and a preserved `raw` markdown block
-  - Each criterion gets a stable `id` (e.g., `AC-<taskId>-<n>`) used in tests, commit trailers, and PR tables
-  - Enables clean PR tables and deterministic coverage mapping while keeping human‑friendly text
-
-Proposed default schema (hybrid):
-```
-acceptanceCriteria: {
-  raw: """
-  - AC1: Guest can checkout with credit card
-  - AC2: Declined cards show error inline
-  """,
-  items: [
-    {
-      id: "AC-12-1",
-      summary: "Guest can checkout with credit card",
-      given: "a guest with items in cart",
-      when: "submits valid credit card",
-      then: "order is created and receipt emailed",
-      severity: "must",
-      tags: ["checkout", "payments"],
-      tests: [] // filled by orchestrator (file paths/test IDs)
-    }
-  ]
-}
-```
-
-Decision: adopt Hybrid default; allow Markdown‑only input and auto‑normalize.
-
-## Decisions
-- Adopt Hybrid acceptance criteria schema by default; normalize Markdown to structured items with stable IDs `AC-<taskId>-<n>`.
-- Use conventional commits plus footers and a unified trailer `Refs: TM-<tag>-<id>[.<sub>]` across PRDs for robust mapping.

CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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

README.md

@@ -60,19 +60,6 @@ The following documentation is also available in the `docs` directory:
 
 > **Note:** After clicking the link, you'll still need to add your API keys to the configuration. The link installs the MCP server with placeholder keys that you'll need to replace with your actual API keys.
 
-#### Claude Code Quick Install
-
-For Claude Code users:
-
-```bash
-claude mcp add taskmaster-ai -- npx -y task-master-ai
-```
-
-Don't forget to add your API keys to the configuration:
-- in the root .env of your Project
-- in the "env" section of your mcp config for taskmaster-ai
-
-
 ## Requirements
 
 Taskmaster utilizes AI across several commands, and those require a separate API key. You can use a variety of models from different AI providers provided you add your API keys. For example, if you want to use Claude 3.7, you'll need an Anthropic API key.
@@ -105,11 +92,10 @@ MCP (Model Control Protocol) lets you run Task Master directly from your editor.
 |              | Project | `<project_folder>/.cursor/mcp.json`   | `<project_folder>\.cursor\mcp.json`               | `mcpServers` |
 | **Windsurf** | Global  | `~/.codeium/windsurf/mcp_config.json` | `%USERPROFILE%\.codeium\windsurf\mcp_config.json` | `mcpServers` |
 | **VS Code**  | Project | `<project_folder>/.vscode/mcp.json`   | `<project_folder>\.vscode\mcp.json`               | `servers`    |
-| **Q CLI**    | Global  | `~/.aws/amazonq/mcp.json`             |                                                   | `mcpServers` |
 
 ##### Manual Configuration
 
-###### Cursor & Windsurf & Q Developer CLI (`mcpServers`)
+###### Cursor & Windsurf (`mcpServers`)
 
 ```json
 {
@@ -138,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/README.md

@@ -1,24 +1,22 @@
 # Task Master Documentation
 
-Welcome to the Task Master documentation. This documentation site provides comprehensive guides for getting started with Task Master.
+Welcome to the Task Master documentation. Use the links below to navigate to the information you need:
 
 ## Getting Started
 
-- [Quick Start Guide](/getting-started/quick-start) - Complete setup and first-time usage guide
-- [Requirements](/getting-started/quick-start/requirements) - What you need to get started
-- [Installation](/getting-started/quick-start/installation) - How to install Task Master
+- [Configuration Guide](archive/configuration.md) - Set up environment variables and customize Task Master
+- [Tutorial](archive/ctutorial.md) - Step-by-step guide to getting started with Task Master
 
-## Core Capabilities
+## Reference
 
-- [MCP Tools](/capabilities/mcp) - Model Control Protocol integration
-- [CLI Commands](/capabilities/cli-root-commands) - Command line interface reference
-- [Task Structure](/capabilities/task-structure) - Understanding tasks and subtasks
+- [Command Reference](archive/ccommand-reference.md) - Complete list of all available commands
+- [Task Structure](archive/ctask-structure.md) - Understanding the task format and features
 
-## Best Practices
+## Examples & Licensing
 
-- [Advanced Configuration](/best-practices/configuration-advanced) - Detailed configuration options
-- [Advanced Tasks](/best-practices/advanced-tasks) - Working with complex task structures
+- [Example Interactions](archive/cexamples.md) - Common Cursor AI interaction examples
+- [Licensing Information](archive/clicensing.md) - Detailed information about the license
 
 ## Need More Help?
 
-If you can't find what you're looking for in these docs, please check the root README.md or visit our [GitHub repository](https://github.com/eyaltoledano/claude-task-master).
+If you can't find what you're looking for in these docs, please check the [main README](../README.md) or visit our [GitHub repository](https://github.com/eyaltoledano/claude-task-master).

apps/docs/capabilities/cli-root-commands.mdx

@@ -156,7 +156,7 @@ sidebarTitle: "CLI Commands"
     # Use an alternative tasks file
     task-master analyze-complexity --file=custom-tasks.json
 
-    # Use your configured research model for research-backed complexity analysis
+    # Use Perplexity AI for research-backed complexity analysis
     task-master analyze-complexity --research
     ```
   </Accordion>

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/configuration-quick.mdx

@@ -108,5 +108,5 @@ You don’t need to configure everything up front. Most settings can be left as
 </Accordion>
 
 <Note>
-For advanced configuration options and detailed customization, see our [Advanced Configuration Guide](/best-practices/configuration-advanced) page.
+For advanced configuration options and detailed customization, see our [Advanced Configuration Guide](/docs/best-practices/configuration-advanced) page.
 </Note>

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

@@ -56,4 +56,4 @@ If you ran into problems and had to debug errors you can create new rules as you
 
 By now you have all you need to get started executing code faster and smarter with Task Master.
 
-If you have any questions please check out [Frequently Asked Questions](/getting-started/faq)
+If you have any questions please check out [Frequently Asked Questions](/docs/getting-started/faq)

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

@@ -30,19 +30,6 @@ cursor://anysphere.cursor-deeplink/mcp/install?name=taskmaster-ai&config=eyJjb21
 ```
 
 > **Note:** After clicking the link, you'll still need to add your API keys to the configuration. The link installs the MCP server with placeholder keys that you'll need to replace with your actual API keys.
-
-### Claude Code Quick Install
-
-For Claude Code users:
-
-```bash
-claude mcp add taskmaster-ai -- npx -y task-master-ai
-```
-
-Don't forget to add your API keys to the configuration:
-- in the root .env of your Project
-- in the "env" section of your mcp config for taskmaster-ai
-
 </Accordion>
 ## Installation Options
 
@@ -90,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,14 +5,34 @@ sidebarTitle: "Quick Start"
 
 This guide is for new users who want to start using Task Master with minimal setup time.
 
-It covers:
-- [Requirements](/getting-started/quick-start/requirements): You will need Node.js and an AI model API Key.
-- [Installation](/getting-started/quick-start/installation): How to Install Task Master.
-- [Configuration](/getting-started/quick-start/configuration-quick): Setting up your API Key, MCP, and more.
-- [PRD](/getting-started/quick-start/prd-quick): Writing and parsing your first PRD.
-- [Task Setup](/getting-started/quick-start/tasks-quick): Preparing your tasks for execution.
-- [Executing Tasks](/getting-started/quick-start/execute-quick): Using Task Master to execute tasks.
-- [Rules & Context](/getting-started/quick-start/rules-quick): Learn how and why to build context in your project over time.
+## 🎯 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.
+- [PRD](/docs/getting-started/quick-start/prd-quick): Writing and parsing your first PRD.
+- [Task Setup](/docs/getting-started/quick-start/tasks-quick): Preparing your tasks for execution.
+- [Executing Tasks](/docs/getting-started/quick-start/execute-quick): Using Task Master to execute tasks.
+- [Rules & Context](/docs/getting-started/quick-start/rules-quick): Learn how and why to build context in your project over time.
 
 <Tip>
 By the end of this guide, you'll have everything you need to begin working productively with Task Master.

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

@@ -61,25 +61,9 @@ Task Master can provide a complexity report which can be helpful to read before
 Can you analyze the complexity of our tasks to help me understand which ones need to be broken down further?
 ```
 
-The agent will use the `analyze_project_complexity` MCP tool, or you can run it directly with the CLI command:
-```bash
-task-master analyze-complexity
-```
-
-For more comprehensive analysis using your configured research model, you can use:
-```bash
-task-master analyze-complexity --research
-```
-
-<Tip>
-The `--research` flag uses whatever research model you have configured in `.taskmaster/config.json` (configurable via `task-master models --setup`) for research-backed complexity analysis, providing more informed recommendations.
-</Tip>
-
 You can view the report in a friendly table using:
 ```
 Can you show me the complexity report in a more readable format?
 ```
 
-For more detailed CLI options, see the [Analyze Task Complexity](/capabilities/cli-root-commands#analyze-task-complexity) section.
-
-<Check>Now you are ready to begin [executing tasks](/getting-started/quick-start/execute-quick)</Check>
+<Check>Now you are ready to begin [executing tasks](/docs/getting-started/quick-start/execute-quick)</Check>

apps/docs/introduction.mdx

@@ -4,7 +4,7 @@ Welcome to v1 of the Task Master Docs. Expect weekly updates as we expand and re
 
 We've organized the docs into three sections depending on your experience level and goals:
 
-### Getting Started - Jump in to [Quick Start](/getting-started/quick-start)
+### Getting Started - Jump in to [Quick Start](/docs/getting-started/quick-start)
 Designed for first-time users. Get set up, create your first PRD, and run your first task.
 
 ### Best Practices

apps/extension/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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

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.3",
+	"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.2"
+		"task-master-ai": "0.27.3"
 	},
 	"devDependencies": {
 		"@dnd-kit/core": "^6.3.1",

docs/configuration.md

@@ -235,60 +235,6 @@ node scripts/init.js
    - "MCP provider requires session context" → Ensure running in MCP environment
    - See the [MCP Provider Guide](./mcp-provider-guide.md) for detailed troubleshooting
 
-### MCP Timeout Configuration
-
-Long-running AI operations in taskmaster-ai can exceed the default 60-second MCP timeout. Operations like `parse_prd`, `expand_task`, `research`, and `analyze_project_complexity` may take 2-5 minutes to complete.
-
-#### Adding Timeout Configuration
-
-Add a `timeout` parameter to your MCP configuration to extend the timeout limit. The timeout configuration works identically across MCP clients including Cursor, Windsurf, and RooCode:
-
-```json
-{
-  "mcpServers": {
-    "task-master-ai": {
-      "command": "npx",
-      "args": ["-y", "--package=task-master-ai", "task-master-ai"],
-      "timeout": 300,
-      "env": {
-        "ANTHROPIC_API_KEY": "your-anthropic-api-key"
-      }
-    }
-  }
-}
-```
-
-**Configuration Details:**
-- **`timeout: 300`** - Sets timeout to 300 seconds (5 minutes)
-- **Value range**: 1-3600 seconds (1 second to 1 hour)
-- **Recommended**: 300 seconds provides sufficient time for most AI operations
-- **Format**: Integer value in seconds (not milliseconds)
-
-#### Automatic Setup
-
-When adding taskmaster rules for supported editors, the timeout configuration is automatically included:
-
-```bash
-# Automatically includes timeout configuration
-task-master rules add cursor
-task-master rules add roo
-task-master rules add windsurf
-task-master rules add vscode
-```
-
-#### Troubleshooting Timeouts
-
-If you're still experiencing timeout errors:
-
-1. **Verify configuration**: Check that `timeout: 300` is present in your MCP config
-2. **Restart editor**: Restart your editor after making configuration changes
-3. **Increase timeout**: For very complex operations, try `timeout: 600` (10 minutes)
-4. **Check API keys**: Ensure required API keys are properly configured
-
-**Expected behavior:**
-- **Before fix**: Operations fail after 60 seconds with `MCP request timed out after 60000ms`
-- **After fix**: Operations complete successfully within the configured timeout limit
-
 ### Google Vertex AI Configuration
 
 Google Vertex AI is Google Cloud's enterprise AI platform and requires specific configuration:

docs/models.md

@@ -1,4 +1,4 @@
-# Available Models as of September 23, 2025
+# Available Models as of September 19, 2025
 
 ## Main Models
 
@@ -119,7 +119,7 @@
 | groq        | deepseek-r1-distill-llama-70b                | 0.52      | 0.75       | 0.99        |
 | perplexity  | sonar-pro                                    | —         | 3          | 15          |
 | perplexity  | sonar                                        | —         | 1          | 1           |
-| perplexity  | sonar-deep-research                          | 0.211     | 2          | 8           |
+| perplexity  | deep-research                                | 0.211     | 2          | 8           |
 | perplexity  | sonar-reasoning-pro                          | 0.211     | 2          | 8           |
 | perplexity  | sonar-reasoning                              | 0.211     | 1          | 5           |
 | bedrock     | us.anthropic.claude-3-opus-20240229-v1:0     | 0.725     | 15         | 75          |

package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "task-master-ai",
-	"version": "0.27.2",
+	"version": "0.27.3",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "task-master-ai",
-			"version": "0.27.2",
+			"version": "0.27.3",
 			"license": "MIT WITH Commons-Clause",
 			"workspaces": [
 				"apps/*",
@@ -357,9 +357,9 @@
 			}
 		},
 		"apps/extension": {
-			"version": "0.25.3",
+			"version": "0.25.4",
 			"dependencies": {
-				"task-master-ai": "0.27.2"
+				"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.2",
+	"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/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
+			);
+		}
 	}
 
 	/**

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

@@ -105,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;
 	}
 
@@ -409,11 +465,8 @@ export class FileStorage implements IStorage {
 			const allDone = subs.every(isDoneLike);
 			const anyInProgress = subs.some((s) => norm(s) === 'in-progress');
 			const anyDone = subs.some(isDoneLike);
-			const allPending = subs.every((s) => norm(s) === 'pending');
-
 			if (allDone) parentNewStatus = 'done';
 			else if (anyInProgress || anyDone) parentNewStatus = 'in-progress';
-			else if (allPending) parentNewStatus = 'pending';
 		}
 
 		// Always bump updatedAt; update status only if changed

scripts/modules/commands.js

@@ -1847,7 +1847,7 @@ function registerCommands(programInstance) {
 		)
 		.option(
 			'-r, --research',
-			'Use configured research model for research-backed complexity analysis'
+			'Use Perplexity AI for research-backed complexity analysis'
 		)
 		.option(
 			'-i, --id <ids>',

scripts/modules/config-manager.js

@@ -310,7 +310,6 @@ function validateProviderModelCombination(providerName, modelId) {
 function validateClaudeCodeSettings(settings) {
 	// Define the base settings schema without commandSpecific first
 	const BaseSettingsSchema = z.object({
-		pathToClaudeCodeExecutable: z.string().optional(),
 		maxTurns: z.number().int().positive().optional(),
 		customSystemPrompt: z.string().optional(),
 		appendSystemPrompt: z.string().optional(),

scripts/modules/supported-models.json

@@ -522,7 +522,7 @@
 			"supported": true
 		},
 		{
-			"id": "sonar-deep-research",
+			"id": "deep-research",
 			"swe_score": 0.211,
 			"cost_per_1m_tokens": {
 				"input": 2,

src/profiles/cursor.js

@@ -1,134 +1,5 @@
 // Cursor conversion profile for rule-transformer
-import path from 'path';
-import fs from 'fs';
-import { log } from '../../scripts/modules/utils.js';
-import { createProfile } from './base-profile.js';
-
-// Helper copy; use cpSync when available, fallback to manual recursion
-function copyRecursiveSync(src, dest) {
-	if (fs.cpSync) {
-		try {
-			fs.cpSync(src, dest, { recursive: true, force: true });
-			return;
-		} catch (err) {
-			throw new Error(`Failed to copy ${src} to ${dest}: ${err.message}`);
-		}
-	}
-	const exists = fs.existsSync(src);
-	let stats = null;
-	let isDirectory = false;
-
-	if (exists) {
-		try {
-			stats = fs.statSync(src);
-			isDirectory = stats.isDirectory();
-		} catch (err) {
-			// Handle TOCTOU race condition - treat as non-existent/not-a-directory
-			isDirectory = false;
-		}
-	}
-
-	if (isDirectory) {
-		try {
-			if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
-			for (const child of fs.readdirSync(src)) {
-				copyRecursiveSync(path.join(src, child), path.join(dest, child));
-			}
-		} catch (err) {
-			throw new Error(
-				`Failed to copy directory ${src} to ${dest}: ${err.message}`
-			);
-		}
-	} else {
-		try {
-			// ensure parent exists for file copies
-			fs.mkdirSync(path.dirname(dest), { recursive: true });
-			fs.copyFileSync(src, dest);
-		} catch (err) {
-			throw new Error(`Failed to copy file ${src} to ${dest}: ${err.message}`);
-		}
-	}
-}
-
-// Helper function to recursively remove directory
-function removeDirectoryRecursive(dirPath) {
-	if (fs.existsSync(dirPath)) {
-		try {
-			fs.rmSync(dirPath, { recursive: true, force: true });
-			return true;
-		} catch (err) {
-			log('error', `Failed to remove directory ${dirPath}: ${err.message}`);
-			return false;
-		}
-	}
-	return true;
-}
-
-// Resolve the Cursor profile directory from either project root, profile root, or rules dir
-function resolveCursorProfileDir(baseDir) {
-	const base = path.basename(baseDir);
-	// If called with .../.cursor/rules -> return .../.cursor
-	if (base === 'rules' && path.basename(path.dirname(baseDir)) === '.cursor') {
-		return path.dirname(baseDir);
-	}
-	// If called with .../.cursor -> return as-is
-	if (base === '.cursor') return baseDir;
-	// Otherwise assume project root and append .cursor
-	return path.join(baseDir, '.cursor');
-}
-
-// Lifecycle functions for Cursor profile
-function onAddRulesProfile(targetDir, assetsDir) {
-	// Copy commands directory recursively
-	const commandsSourceDir = path.join(assetsDir, 'claude', 'commands');
-	const profileDir = resolveCursorProfileDir(targetDir);
-	const commandsDestDir = path.join(profileDir, 'commands');
-
-	if (!fs.existsSync(commandsSourceDir)) {
-		log(
-			'warn',
-			`[Cursor] Source commands directory does not exist: ${commandsSourceDir}`
-		);
-		return;
-	}
-
-	try {
-		// Ensure fresh state to avoid stale command files
-		try {
-			fs.rmSync(commandsDestDir, { recursive: true, force: true });
-			log(
-				'debug',
-				`[Cursor] Removed existing commands directory: ${commandsDestDir}`
-			);
-		} catch (deleteErr) {
-			// Directory might not exist, which is fine
-			log(
-				'debug',
-				`[Cursor] Commands directory did not exist or could not be removed: ${deleteErr.message}`
-			);
-		}
-
-		copyRecursiveSync(commandsSourceDir, commandsDestDir);
-		log('debug', `[Cursor] Copied commands directory to ${commandsDestDir}`);
-	} catch (err) {
-		log(
-			'error',
-			`[Cursor] An error occurred during commands copy: ${err.message}`
-		);
-	}
-}
-
-function onRemoveRulesProfile(targetDir) {
-	// Remove .cursor/commands directory recursively
-	const profileDir = resolveCursorProfileDir(targetDir);
-	const commandsDir = path.join(profileDir, 'commands');
-	if (removeDirectoryRecursive(commandsDir)) {
-		log(
-			'debug',
-			`[Cursor] Ensured commands directory removed at ${commandsDir}`
-		);
-	}
-}
+import { createProfile, COMMON_TOOL_MAPPINGS } from './base-profile.js';
 
 // Create and export cursor profile using the base factory
 export const cursorProfile = createProfile({
@@ -137,10 +8,5 @@ export const cursorProfile = createProfile({
 	url: 'cursor.so',
 	docsUrl: 'docs.cursor.com',
 	targetExtension: '.mdc', // Cursor keeps .mdc extension
-	supportsRulesSubdirectories: true,
-	onAdd: onAddRulesProfile,
-	onRemove: onRemoveRulesProfile
+	supportsRulesSubdirectories: true
 });
-
-// Export lifecycle functions separately to avoid naming conflicts
-export { onAddRulesProfile, onRemoveRulesProfile };

src/profiles/roo.js

@@ -5,40 +5,6 @@ import { isSilentMode, log } from '../../scripts/modules/utils.js';
 import { createProfile, COMMON_TOOL_MAPPINGS } from './base-profile.js';
 import { ROO_MODES } from '../constants/profiles.js';
 
-// Import the shared MCP configuration helper
-import { formatJSONWithTabs } from '../utils/create-mcp-config.js';
-
-// Roo-specific MCP configuration enhancements
-function enhanceRooMCPConfiguration(mcpPath) {
-	if (!fs.existsSync(mcpPath)) {
-		log('warn', `[Roo] MCP configuration file not found at ${mcpPath}`);
-		return;
-	}
-
-	try {
-		// Read the existing configuration
-		const mcpConfig = JSON.parse(fs.readFileSync(mcpPath, 'utf8'));
-
-		if (mcpConfig.mcpServers && mcpConfig.mcpServers['task-master-ai']) {
-			const server = mcpConfig.mcpServers['task-master-ai'];
-
-			// Add Roo-specific timeout enhancement for long-running AI operations
-			server.timeout = 300;
-
-			// Write the enhanced configuration back
-			fs.writeFileSync(mcpPath, formatJSONWithTabs(mcpConfig) + '\n');
-			log(
-				'debug',
-				`[Roo] Enhanced MCP configuration with timeout at ${mcpPath}`
-			);
-		} else {
-			log('warn', `[Roo] task-master-ai server not found in MCP configuration`);
-		}
-	} catch (error) {
-		log('error', `[Roo] Failed to enhance MCP configuration: ${error.message}`);
-	}
-}
-
 // Lifecycle functions for Roo profile
 function onAddRulesProfile(targetDir, assetsDir) {
 	// Use the provided assets directory to find the roocode directory
@@ -66,9 +32,6 @@ function onAddRulesProfile(targetDir, assetsDir) {
 		}
 	}
 
-	// Note: MCP configuration is now handled by the base profile system
-	// The base profile will call setupMCPConfiguration, and we enhance it in onPostConvert
-
 	for (const mode of ROO_MODES) {
 		const src = path.join(rooModesDir, `rules-${mode}`, `${mode}-rules`);
 		const dest = path.join(targetDir, '.roo', `rules-${mode}`, `${mode}-rules`);
@@ -115,15 +78,6 @@ function onRemoveRulesProfile(targetDir) {
 
 	const rooDir = path.join(targetDir, '.roo');
 	if (fs.existsSync(rooDir)) {
-		// Remove MCP configuration
-		const mcpPath = path.join(rooDir, 'mcp.json');
-		try {
-			fs.rmSync(mcpPath, { force: true });
-			log('debug', `[Roo] Removed MCP configuration from ${mcpPath}`);
-		} catch (err) {
-			log('error', `[Roo] Failed to remove MCP configuration: ${err.message}`);
-		}
-
 		fs.readdirSync(rooDir).forEach((entry) => {
 			if (entry.startsWith('rules-')) {
 				const modeDir = path.join(rooDir, entry);
@@ -147,13 +101,7 @@ function onRemoveRulesProfile(targetDir) {
 }
 
 function onPostConvertRulesProfile(targetDir, assetsDir) {
-	// Enhance the MCP configuration with Roo-specific features after base setup
-	const mcpPath = path.join(targetDir, '.roo', 'mcp.json');
-	try {
-		enhanceRooMCPConfiguration(mcpPath);
-	} catch (err) {
-		log('error', `[Roo] Failed to enhance MCP configuration: ${err.message}`);
-	}
+	onAddRulesProfile(targetDir, assetsDir);
 }
 
 // Create and export roo profile using the base factory
@@ -163,7 +111,6 @@ export const rooProfile = createProfile({
 	url: 'roocode.com',
 	docsUrl: 'docs.roocode.com',
 	toolMappings: COMMON_TOOL_MAPPINGS.ROO_STYLE,
-	mcpConfig: true, // Enable MCP config - we enhance it with Roo-specific features
 	onAdd: onAddRulesProfile,
 	onRemove: onRemoveRulesProfile,
 	onPostConvert: onPostConvertRulesProfile

src/utils/create-mcp-config.js

@@ -262,6 +262,3 @@ export function removeTaskMasterMCPConfiguration(projectRoot, mcpConfigPath) {
 
 	return result;
 }
-
-// Export the formatting function for use by other modules
-export { formatJSONWithTabs };

src/utils/rule-transformer.js

@@ -210,7 +210,7 @@ export function convertAllRulesToProfileRules(projectRoot, profile) {
 	if (typeof profile.onAddRulesProfile === 'function') {
 		try {
 			const assetsDir = getAssetsDir();
-			profile.onAddRulesProfile(targetDir, assetsDir);
+			profile.onAddRulesProfile(projectRoot, assetsDir);
 			log(
 				'debug',
 				`[Rule Transformer] Called onAddRulesProfile for ${profile.profileName}`
@@ -305,7 +305,7 @@ export function convertAllRulesToProfileRules(projectRoot, profile) {
 	if (typeof profile.onPostConvertRulesProfile === 'function') {
 		try {
 			const assetsDir = getAssetsDir();
-			profile.onPostConvertRulesProfile(targetDir, assetsDir);
+			profile.onPostConvertRulesProfile(projectRoot, assetsDir);
 			log(
 				'debug',
 				`[Rule Transformer] Called onPostConvertRulesProfile for ${profile.profileName}`
@@ -347,7 +347,7 @@ export function removeProfileRules(projectRoot, profile) {
 		// 1. Call onRemoveRulesProfile first (for custom cleanup like removing assets)
 		if (typeof profile.onRemoveRulesProfile === 'function') {
 			try {
-				profile.onRemoveRulesProfile(targetDir);
+				profile.onRemoveRulesProfile(projectRoot);
 				log(
 					'debug',
 					`[Rule Transformer] Called onRemoveRulesProfile for ${profile.profileName}`

tests/integration/profiles/cursor-init-functionality.test.js

@@ -54,33 +54,4 @@ describe('Cursor Profile Initialization Functionality', () => {
 		);
 		expect(cursorProfile.conversionConfig.toolNames.search).toBe('search');
 	});
-
-	test('cursor.js has lifecycle functions for command copying', () => {
-		// Check that the source file contains our new lifecycle functions
-		expect(cursorProfileContent).toContain('function onAddRulesProfile');
-		expect(cursorProfileContent).toContain('function onRemoveRulesProfile');
-		expect(cursorProfileContent).toContain('copyRecursiveSync');
-		expect(cursorProfileContent).toContain('removeDirectoryRecursive');
-	});
-
-	test('cursor.js copies commands from claude/commands to .cursor/commands', () => {
-		// Check that the onAddRulesProfile function copies from the correct source
-		expect(cursorProfileContent).toContain(
-			"path.join(assetsDir, 'claude', 'commands')"
-		);
-		// Destination path is built via a resolver to handle both project root and rules dir
-		expect(cursorProfileContent).toContain('resolveCursorProfileDir(');
-		expect(cursorProfileContent).toMatch(
-			/path\.join\(\s*profileDir\s*,\s*['"]commands['"]\s*\)/
-		);
-		expect(cursorProfileContent).toContain(
-			'copyRecursiveSync(commandsSourceDir, commandsDestDir)'
-		);
-
-		// Check that lifecycle functions are properly registered with the profile
-		expect(cursorProfile.onAddRulesProfile).toBeDefined();
-		expect(cursorProfile.onRemoveRulesProfile).toBeDefined();
-		expect(typeof cursorProfile.onAddRulesProfile).toBe('function');
-		expect(typeof cursorProfile.onRemoveRulesProfile).toBe('function');
-	});
 });

tests/integration/profiles/roo-init-functionality.test.js

@@ -26,7 +26,7 @@ describe('Roo Profile Initialization Functionality', () => {
 		expect(rooProfile.displayName).toBe('Roo Code');
 		expect(rooProfile.profileDir).toBe('.roo'); // default
 		expect(rooProfile.rulesDir).toBe('.roo/rules'); // default
-		expect(rooProfile.mcpConfig).toBe(true); // now uses standard MCP configuration with Roo enhancements
+		expect(rooProfile.mcpConfig).toBe(true); // default
 	});
 
 	test('roo.js uses custom ROO_STYLE tool mappings', () => {

tests/unit/profiles/cursor-integration.test.js

@@ -8,37 +8,18 @@ jest.mock('child_process', () => ({
 	execSync: jest.fn()
 }));
 
-// Mock console methods to avoid chalk issues
-const mockLog = jest.fn();
-const originalConsole = global.console;
-const mockConsole = {
+// Mock console methods
+jest.mock('console', () => ({
 	log: jest.fn(),
 	info: jest.fn(),
 	warn: jest.fn(),
 	error: jest.fn(),
 	clear: jest.fn()
-};
-global.console = mockConsole;
-
-// Mock utils logger to avoid chalk dependency issues
-await jest.unstable_mockModule('../../../scripts/modules/utils.js', () => ({
-	default: undefined,
-	log: mockLog,
-	isSilentMode: () => false
 }));
 
-// Import the cursor profile after mocking
-const { cursorProfile, onAddRulesProfile, onRemoveRulesProfile } = await import(
-	'../../../src/profiles/cursor.js'
-);
-
 describe('Cursor Integration', () => {
 	let tempDir;
 
-	afterAll(() => {
-		global.console = originalConsole;
-	});
-
 	beforeEach(() => {
 		jest.clearAllMocks();
 
@@ -94,127 +75,4 @@ describe('Cursor Integration', () => {
 			{ recursive: true }
 		);
 	});
-
-	test('cursor profile has lifecycle functions for command copying', () => {
-		// Assert that the profile exports the lifecycle functions
-		expect(typeof onAddRulesProfile).toBe('function');
-		expect(typeof onRemoveRulesProfile).toBe('function');
-		expect(cursorProfile.onAddRulesProfile).toBe(onAddRulesProfile);
-		expect(cursorProfile.onRemoveRulesProfile).toBe(onRemoveRulesProfile);
-	});
-
-	describe('command copying lifecycle', () => {
-		let mockAssetsDir;
-		let mockTargetDir;
-
-		beforeEach(() => {
-			mockAssetsDir = path.join(tempDir, 'assets');
-			mockTargetDir = path.join(tempDir, 'target');
-
-			// Reset all mocks
-			jest.clearAllMocks();
-
-			// Mock fs methods for the lifecycle functions
-			jest.spyOn(fs, 'existsSync').mockImplementation((filePath) => {
-				const pathStr = filePath.toString();
-				if (pathStr.includes('claude/commands')) {
-					return true; // Mock that source commands exist
-				}
-				return false;
-			});
-
-			jest.spyOn(fs, 'mkdirSync').mockImplementation(() => {});
-			jest.spyOn(fs, 'readdirSync').mockImplementation(() => ['tm']);
-			jest
-				.spyOn(fs, 'statSync')
-				.mockImplementation(() => ({ isDirectory: () => true }));
-			jest.spyOn(fs, 'copyFileSync').mockImplementation(() => {});
-			jest.spyOn(fs, 'rmSync').mockImplementation(() => {});
-		});
-
-		afterEach(() => {
-			jest.restoreAllMocks();
-		});
-
-		test('onAddRulesProfile copies commands from assets to .cursor/commands', () => {
-			// Detect if cpSync exists and set up appropriate spy
-			if (fs.cpSync) {
-				const cpSpy = jest.spyOn(fs, 'cpSync').mockImplementation(() => {});
-
-				// Act
-				onAddRulesProfile(mockTargetDir, mockAssetsDir);
-
-				// Assert
-				expect(fs.existsSync).toHaveBeenCalledWith(
-					path.join(mockAssetsDir, 'claude', 'commands')
-				);
-				expect(cpSpy).toHaveBeenCalledWith(
-					path.join(mockAssetsDir, 'claude', 'commands'),
-					path.join(mockTargetDir, '.cursor', 'commands'),
-					expect.objectContaining({ recursive: true, force: true })
-				);
-			} else {
-				// Act
-				onAddRulesProfile(mockTargetDir, mockAssetsDir);
-
-				// Assert
-				expect(fs.existsSync).toHaveBeenCalledWith(
-					path.join(mockAssetsDir, 'claude', 'commands')
-				);
-				expect(fs.mkdirSync).toHaveBeenCalledWith(
-					path.join(mockTargetDir, '.cursor', 'commands'),
-					{ recursive: true }
-				);
-				expect(fs.copyFileSync).toHaveBeenCalled();
-			}
-		});
-
-		test('onAddRulesProfile handles missing source directory gracefully', () => {
-			// Arrange - mock source directory not existing
-			jest.spyOn(fs, 'existsSync').mockImplementation(() => false);
-
-			// Act
-			onAddRulesProfile(mockTargetDir, mockAssetsDir);
-
-			// Assert - should not attempt to copy anything
-			expect(fs.mkdirSync).not.toHaveBeenCalled();
-			expect(fs.copyFileSync).not.toHaveBeenCalled();
-		});
-
-		test('onRemoveRulesProfile removes .cursor/commands directory', () => {
-			// Arrange - mock directory exists
-			jest.spyOn(fs, 'existsSync').mockImplementation(() => true);
-
-			// Act
-			onRemoveRulesProfile(mockTargetDir);
-
-			// Assert
-			expect(fs.rmSync).toHaveBeenCalledWith(
-				path.join(mockTargetDir, '.cursor', 'commands'),
-				{ recursive: true, force: true }
-			);
-		});
-
-		test('onRemoveRulesProfile handles missing directory gracefully', () => {
-			// Arrange - mock directory doesn't exist
-			jest.spyOn(fs, 'existsSync').mockImplementation(() => false);
-
-			// Act
-			onRemoveRulesProfile(mockTargetDir);
-
-			// Assert - should still return true but not attempt removal
-			expect(fs.rmSync).not.toHaveBeenCalled();
-		});
-
-		test('onRemoveRulesProfile handles removal errors gracefully', () => {
-			// Arrange - mock directory exists but removal fails
-			jest.spyOn(fs, 'existsSync').mockImplementation(() => true);
-			jest.spyOn(fs, 'rmSync').mockImplementation(() => {
-				throw new Error('Permission denied');
-			});
-
-			// Act & Assert - should not throw
-			expect(() => onRemoveRulesProfile(mockTargetDir)).not.toThrow();
-		});
-	});
 });

tests/unit/profiles/mcp-config-validation.test.js

@@ -266,10 +266,10 @@ describe('MCP Configuration Validation', () => {
 			expect(mcpEnabledProfiles).toContain('cursor');
 			expect(mcpEnabledProfiles).toContain('gemini');
 			expect(mcpEnabledProfiles).toContain('opencode');
+			expect(mcpEnabledProfiles).toContain('roo');
 			expect(mcpEnabledProfiles).toContain('vscode');
 			expect(mcpEnabledProfiles).toContain('windsurf');
 			expect(mcpEnabledProfiles).toContain('zed');
-			expect(mcpEnabledProfiles).toContain('roo');
 			expect(mcpEnabledProfiles).not.toContain('cline');
 			expect(mcpEnabledProfiles).not.toContain('codex');
 			expect(mcpEnabledProfiles).not.toContain('trae');
@@ -384,7 +384,6 @@ describe('MCP Configuration Validation', () => {
 			'claude',
 			'cursor',
 			'gemini',
-			'kiro',
 			'opencode',
 			'roo',
 			'windsurf',