## 1. Project Overview & Quickstart (eyaltoledano/claude-task-master) ## File: README.md ## By [@eyaltoledano](https://x.com/eyaltoledano) & [@RalphEcom](https://x.com/RalphEcom) [](https://x.com/eyaltoledano) [](https://x.com/RalphEcom) A task management system for AI-driven development with Claude, designed to work seamlessly with Cursor AI. ## Documentation πŸ“š **[View Full Documentation](https://tryhamster.com/docs/taskmaster)** ### Quick Links - [Quick Start Guide](https://tryhamster.com/docs/taskmaster/getting-started/quick-start/quick-start) - [Installation](https://tryhamster.com/docs/taskmaster/getting-started/quick-start/installation) - [API Keys & Providers](https://tryhamster.com/docs/taskmaster/getting-started/api-keys) - [Supported Editors](https://tryhamster.com/docs/taskmaster/ide-setup/supported-editors) - [MCP Tools Reference](https://tryhamster.com/docs/taskmaster/capabilities/mcp) - [CLI Commands Reference](https://tryhamster.com/docs/taskmaster/capabilities/cli-root-commands) - [Task Structure](https://tryhamster.com/docs/taskmaster/capabilities/task-structure) - [Task Dependencies](https://tryhamster.com/docs/taskmaster/task-workflow/dependencies) - [Tags & Workstreams](https://tryhamster.com/docs/taskmaster/task-workflow/tags) - [Research Command](https://tryhamster.com/docs/taskmaster/task-workflow/research) - [Loop Command](https://tryhamster.com/docs/taskmaster/automation/loop) - [AI Providers Overview](https://tryhamster.com/docs/taskmaster/ai-providers/overview) - [Team Collaboration](https://tryhamster.com/docs/taskmaster/team/overview) - [Best Practices](https://tryhamster.com/docs/taskmaster/best-practices/index) - [FAQ](https://tryhamster.com/docs/taskmaster/getting-started/faq) - [Changelog](CHANGELOG.md) ### More from Hamster - [Hamster Studio](https://tryhamster.com/product/studio) - [Product & Engineering Methods](https://tryhamster.com/methods) - [Product & Engineering Skills](https://tryhamster.com/skills) - [Hamster Pricing](https://tryhamster.com/pricing) #### Quick Install for Cursor 1.0+ (One-Click) [](https://cursor.com/en/install-mcp?name=task-master-ai&config=eyJjb21tYW5kIjoibnB4IC15IC0tcGFja2FnZT10YXNrLW1hc3Rlci1haSB0YXNrLW1hc3Rlci1haSIsImVudiI6eyJBTlRIUk9QSUNfQVBJX0tFWSI6IllPVVJfQU5USFJPUElDX0FQSV9LRVlfSEVSRSIsIlBFUlBMRVhJVFlfQVBJX0tFWSI6IllPVVJfUEVSUExFWElUWV9BUElfS0VZX0hFUkUiLCJPUEVOQUlfQVBJX0tFWSI6IllPVVJfT1BFTkFJX0tFWV9IRVJFIiwiR09PR0xFX0FQSV9LRVkiOiJZT1VSX0dPT0dMRV9LRVlfSEVSRSIsIk1JU1RSQUxfQVBJX0tFWSI6IllPVVJfTUlTVFJBTF9LRVlfSEVSRSIsIkdST1FfQVBJX0tFWSI6IllPVVJfR1JPUV9LRVlfSEVSRSIsIk9QRU5ST1VURVJfQVBJX0tFWSI6IllPVVJfT1BFTlJPVVRFUl9LRVlfSEVSRSIsIlhBSV9BUElfS0VZIjoiWU9VUl9YQUlfS0VZX0hFUkUiLCJBWlVSRV9PUEVOQUlfQVBJX0tFWSI6IllPVVJfQVpVUkVfS0VZX0hFUkUiLCJPTExBTUFfQVBJX0tFWSI6IllPVVJfT0xMQU1BX0FQSV9LRVlfSEVSRSJ9fQ%3D%3D) > **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. You can define 3 types of models to be used: the main model, the research model, and the fallback model (in case either the main or research fail). Whatever model you use, its provider API key must be present in either mcp.json or .env. At least one (1) of the following is required: - Anthropic API key (Claude API) - OpenAI API key - Google Gemini API key - Perplexity API key (for research model) - xAI API Key (for research or main model) - OpenRouter API Key (for research or main model) - Claude Code (no API key required - requires Claude Code CLI) - Codex CLI (OAuth via ChatGPT subscription - requires Codex CLI) Using the research model is optional but highly recommended. You will need at least ONE API key (unless using Claude Code or Codex CLI with OAuth). Adding all API keys enables you to seamlessly switch between model providers at will. ## Quick Start ### Option 1: MCP (Recommended) MCP (Model Control Protocol) lets you run Task Master directly from your editor. #### 1. Add your MCP config at the following path depending on your editor | Editor | Scope | Linux/macOS Path | Windows Path | Key | | ------------ | ------- | ------------------------------------- | ------------------------------------------------- | ------------ | | **Cursor** | Global | `~/.cursor/mcp.json` | `%USERPROFILE%\.cursor\mcp.json` | `mcpServers` | | | Project | `/.cursor/mcp.json` | `\.cursor\mcp.json` | `mcpServers` | | **Windsurf** | Global | `~/.codeium/windsurf/mcp_config.json` | `%USERPROFILE%\.codeium\windsurf\mcp_config.json` | `mcpServers` | | **VS Code** | Project | `/.vscode/mcp.json` | `\.vscode\mcp.json` | `servers` | | **Q CLI** | Global | `~/.aws/amazonq/mcp.json` | | `mcpServers` | ##### Manual Configuration ###### Cursor & Windsurf & Q Developer CLI (`mcpServers`) ```json { "mcpServers": { "task-master-ai": { "command": "npx", "args": ["-y", "task-master-ai"], "env": { // "TASK_MASTER_TOOLS": "all", // Options: "all", "standard", "core", or comma-separated list of tools "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", "GROQ_API_KEY": "YOUR_GROQ_KEY_HERE", "OPENROUTER_API_KEY": "YOUR_OPENROUTER_KEY_HERE", "XAI_API_KEY": "YOUR_XAI_KEY_HERE", "AZURE_OPENAI_API_KEY": "YOUR_AZURE_KEY_HERE", "OLLAMA_API_KEY": "YOUR_OLLAMA_API_KEY_HERE" } } } } ``` > πŸ”‘ Replace `YOUR_…_KEY_HERE` with your real API keys. You can remove keys you don't use. > **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 { "servers": { "task-master-ai": { "command": "npx", "args": ["-y", "task-master-ai"], "env": { // "TASK_MASTER_TOOLS": "all", // Options: "all", "standard", "core", or comma-separated list of tools "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", "GROQ_API_KEY": "YOUR_GROQ_KEY_HERE", "OPENROUTER_API_KEY": "YOUR_OPENROUTER_KEY_HERE", "XAI_API_KEY": "YOUR_XAI_KEY_HERE", "AZURE_OPENAI_API_KEY": "YOUR_AZURE_KEY_HERE", "OLLAMA_API_KEY": "YOUR_OLLAMA_API_KEY_HERE" }, "type": "stdio" } } } ``` > πŸ”‘ Replace `YOUR_…_KEY_HERE` with your real API keys. You can remove keys you don't use. #### 2. (Cursor-only) Enable Taskmaster MCP Open Cursor Settings (Ctrl+Shift+J) ➑ Click on MCP tab on the left ➑ Enable task-master-ai with the toggle #### 3. (Optional) Configure the models you want to use In your editor's AI chat pane, say: ```txt Change the main, research and fallback models to , and respectively. ``` For example, to use Claude Code (no API key required): ```txt Change the main model to claude-code/sonnet ``` [Table of available models](docs/models.md) | [Claude Code setup](docs/examples/claude-code-usage.md) #### 4. Initialize Task Master In your editor's AI chat pane, say: ```txt Initialize taskmaster-ai in my project ``` #### 5. Make sure you have a PRD (Recommended) For **new projects**: Create your PRD at `.taskmaster/docs/prd.txt`. For **existing projects**: You can use `scripts/prd.txt` or migrate with `task-master migrate` An example PRD template is available after initialization in `.taskmaster/templates/example_prd.txt`. > [!NOTE] > While a PRD is recommended for complex projects, you can always create individual tasks by asking "Can you help me implement [description of what you want to do]?" in chat. **Always start with a detailed PRD.** The more detailed your PRD, the better the generated tasks will be. #### 6. Common Commands Use your AI assistant to: - Parse requirements: `Can you parse my PRD at scripts/prd.txt?` - Plan next step: `What's the next task I should work on?` - Implement a task: `Can you help me implement task 3?` - View multiple tasks: `Can you show me tasks 1, 3, and 5?` - Expand a task: `Can you help me expand task 4?` - **Research fresh information**: `Research the latest best practices for implementing JWT authentication with Node.js` - **Research with context**: `Research React Query v5 migration strategies for our current API implementation in src/api.js` [More examples on how to use Task Master in chat](docs/examples.md) ### Option 2: Using Command Line #### Installation ```bash # Install globally npm install task-master-ai # OR install locally within your project npm install task-master-ai ``` #### Initialize a new project ```bash # If installed globally task-master init # If installed locally npx task-master init # Initialize project with specific rules task-master init --rules cursor,windsurf,vscode ``` This will prompt you for project details and set up a new project with the necessary files and structure. #### Common Commands ```bash # Initialize a new project task-master init # Parse a PRD and generate tasks task-master parse-prd your-prd.txt # List all tasks task-master list # Show the next task to work on task-master next # Show specific task(s) - supports comma-separated IDs task-master show 1,3,5 # Research fresh information with project context task-master research "What are the latest best practices for JWT authentication?" # Move tasks between tags (cross-tag movement) task-master move --from=5 --from-tag=backlog --to-tag=in-progress task-master move --from=5,6,7 --from-tag=backlog --to-tag=done --with-dependencies task-master move --from=5 --from-tag=backlog --to-tag=in-progress --ignore-dependencies # Add rules after initialization task-master rules add windsurf,roo,vscode ``` ## Tool Loading Configuration ### Optimizing MCP Tool Loading Task Master's MCP server supports selective tool loading to reduce context window usage. By default, all 36 tools are loaded (~21,000 tokens) to maintain backward compatibility with existing installations. You can optimize performance by configuring the `TASK_MASTER_TOOLS` environment variable: ### Available Modes | Mode | Tools | Context Usage | Use Case | |------|-------|--------------|----------| | `all` (default) | 36 | ~21,000 tokens | Complete feature set - all tools available | | `standard` | 15 | ~10,000 tokens | Common task management operations | | `core` (or `lean`) | 7 | ~5,000 tokens | Essential daily development workflow | | `custom` | Variable | Variable | Comma-separated list of specific tools | ### Configuration Methods #### Method 1: Environment Variable in MCP Configuration Add `TASK_MASTER_TOOLS` to your MCP configuration file's `env` section: ```jsonc { "mcpServers": { // or "servers" for VS Code "task-master-ai": { "command": "npx", "args": ["-y", "task-master-ai"], "env": { "TASK_MASTER_TOOLS": "standard", // Options: "all", "standard", "core", "lean", or comma-separated list "ANTHROPIC_API_KEY": "your-key-here", // ... other API keys } } } } ``` #### Method 2: Claude Code CLI (One-Time Setup) For Claude Code users, you can set the mode during installation: ```bash # Core mode example (~70% token reduction) claude mcp add task-master-ai --scope user \ --env TASK_MASTER_TOOLS="core" \ -- npx -y task-master-ai@latest # Custom tools example claude mcp add task-master-ai --scope user \ --env TASK_MASTER_TOOLS="get_tasks,next_task,set_task_status" \ -- npx -y task-master-ai@latest ``` ### Tool Sets Details **Core Tools (7):** `get_tasks`, `next_task`, `get_task`, `set_task_status`, `update_subtask`, `parse_prd`, `expand_task` **Standard Tools (15):** All core tools plus `initialize_project`, `analyze_project_complexity`, `expand_all`, `add_subtask`, `remove_task`, `generate`, `add_task`, `complexity_report` **All Tools (36):** Complete set including project setup, task management, analysis, dependencies, tags, research, and more ### Recommendations - **New users**: Start with `"standard"` mode for a good balance - **Large projects**: Use `"core"` mode to minimize token usage - **Complex workflows**: Use `"all"` mode or custom selection - **Backward compatibility**: If not specified, defaults to `"all"` mode ## Claude Code Support Task Master now supports Claude models through the Claude Code CLI, which requires no API key: - **Models**: `claude-code/opus` and `claude-code/sonnet` - **Requirements**: Claude Code CLI installed - **Benefits**: No API key needed, uses your local Claude instance [Learn more about Claude Code setup](docs/examples/claude-code-usage.md) ## Troubleshooting ### If `task-master init` doesn't respond Try running it with Node directly: ```bash node node_modules/claude-task-master/scripts/init.js ``` Or clone the repository and run: ```bash git clone https://github.com/eyaltoledano/claude-task-master.git cd claude-task-master node scripts/init.js ``` ## Join Our Team ## Contributors ## Star History [](https://www.star-history.com/#eyaltoledano/claude-task-master&Timeline) ## Licensing Task Master is licensed under the MIT License with Commons Clause. This means you can: βœ… **Allowed**: - Use Task Master for any purpose (personal, commercial, academic) - Modify the code - Distribute copies - Create and sell products built using Task Master ❌ **Not Allowed**: - Sell Task Master itself - Offer Task Master as a hosted service - Create competing products based on Task Master See the [LICENSE](LICENSE) file for the complete license text and [licensing details](docs/licensing.md) for more information. --- ## File: apps/mcp/src/tools/README-ZOD-V3.md # Why MCP Tools Use Zod v3 ## Problem - **FastMCP** uses `xsschema` to convert schemas β†’ outputs JSON Schema **Draft 2020-12** - **MCP clients** (Augment IDE, gemini-cli, etc.) only support **Draft-07** - Using Zod v4 in tools causes "vendor undefined" errors and tool discovery failures ## Temporary Solution All MCP tool files import from `zod/v3` instead of `zod`: ```typescript import { z } from 'zod/v3'; // βœ… Draft-07 compatible // NOT: import { z } from 'zod'; // ❌ Would use Draft 2020-12 ``` ### Why This Works - Zod v4 ships with v3 compatibility at `zod/v3` - FastMCP + zod-to-json-schema converts Zod v3 schemas β†’ **Draft-07** - This ensures MCP clients can discover and use our tools ### What This Means - βœ… **MCP tools** β†’ use `zod/v3` (apps/mcp & mcp-server/src/tools) - βœ… **Rest of codebase** β†’ uses `zod` (Zod v4) - βœ… **No conflicts** β†’ they're from the same package, just different versions ## When Can We Remove This? This workaround can be removed when **either**: 1. **FastMCP adds JSON Schema version configuration** - e.g., `new FastMCP({ jsonSchema: { target: 'draft-07' } })` - Tracking: https://github.com/punkpeye/fastmcp/issues/189 2. **MCP spec adds Draft 2020-12 support** - Unlikely in the short term 3. **xsschema adds version targeting** - Would allow FastMCP to use Draft-07 ## How to Maintain When adding new MCP tools: ```typescript // βœ… CORRECT import { z } from 'zod/v3'; export function registerMyTool(server: FastMCP) { server.addTool({ name: 'my_tool', parameters: z.object({ ... }), // Will use Draft-07 execute: async (args, context) => { ... } }); } ``` ```typescript // ❌ WRONG - Will break MCP client compatibility import { z } from 'zod'; // Don't do this in apps/mcp/src/tools/ ``` --- **Last Updated:** 2025-10-18 **Affects:** All files in `apps/mcp/src/tools/` **See Also:** `mcp-server/src/tools/README-ZOD-V3.md` (same workaround) --- ## File: apps/extension/docs/extension-CI-setup.md # VS Code Extension CI/CD Setup This document explains the CI/CD setup for the Task Master VS Code extension using automated changesets. ## πŸ”„ Workflows Overview ### 1. Extension CI (`extension-ci.yml`) #### Triggers - Push to `main` or `next` branches (only when extension files change) - Pull requests to `main` or `next` (only when extension files change) #### What it does - βœ… Lints and type-checks the extension code - πŸ”¨ Builds the extension (`npm run build`) - πŸ“¦ Creates a clean package (`npm run package`) - πŸ§ͺ Runs tests with VS Code test framework - πŸ“‹ Creates a test VSIX package to verify packaging works - πŸ’Ύ Uploads build artifacts for inspection ### 2. Version & Publish (`version.yml`) **Triggers:** - Push to `main` branch **What it does:** - πŸ” Detects changeset files for pending releases - πŸ“ Creates "Version Packages" PR with updated versions and CHANGELOG - πŸ€– When Version PR is merged, automatically: - πŸ”¨ Builds and packages the extension - 🏷️ Creates git tags with changeset automation - πŸ“€ Publishes to VS Code Marketplace - 🌍 Publishes to Open VSX Registry - πŸ“Š Updates package versions and CHANGELOG ## πŸš€ Changeset Workflow ### Creating Changes When making changes to the extension: 1. **Make your code changes** 2. **Create a changeset**: ```bash # From project root npx changeset add ``` 3. **Select the extension package**: Choose `taskr-kanban` when prompted 4. **Select version bump type**: - `patch`: Bug fixes, minor updates - `minor`: New features, backwards compatible - `major`: Breaking changes 5. **Write a summary**: Describe what changed for users 6. **Commit changeset file** along with your code changes 7. **Push to feature branch** and create PR ### Automated Publishing Process 1. **PR with changeset** gets merged to `main` 2. **Version workflow** detects changesets and creates "Version Packages" PR 3. **Review and merge** the Version PR 4. **Automated publishing** happens immediately: - Extension is built using 3-file packaging system - VSIX package is created and tested - Published to VS Code Marketplace (if `VSCE_PAT` is set) - Published to Open VSX Registry (if `OVSX_PAT` is set) - Git tags are created: `taskr-kanban@1.0.1` - CHANGELOG is updated automatically ## πŸ”‘ Required Secrets To use the automated publishing, you need to set up these GitHub repository secrets: ### `VSCE_PAT` (VS Code Marketplace Personal Access Token) 1. Go to [Azure DevOps](https://dev.azure.com/) 2. Sign in with your Microsoft account 3. Create a Personal Access Token: - **Name**: VS Code Extension Publishing - **Organization**: All accessible organizations - **Expiration**: Custom (recommend 1 year) - **Scopes**: Custom defined β†’ **Marketplace** β†’ **Manage** 4. Copy the token and add it to GitHub Secrets as `VSCE_PAT` ### `OVSX_PAT` (Open VSX Registry Personal Access Token) 1. Go to [Open VSX Registry](https://open-vsx.org/) 2. Sign in with your GitHub account 3. Go to your [User Settings](https://open-vsx.org/user-settings/tokens) 4. Create a new Access Token: - **Description**: VS Code Extension Publishing - **Scopes**: Leave default (full access) 5. Copy the token and add it to GitHub Secrets as `OVSX_PAT` ### `GITHUB_TOKEN` (automatically provided) This is automatically available in GitHub Actions - no setup required. ## πŸ“‹ Version Management ### Changeset-Based Versioning Versions are automatically managed by changesets: - **No manual version updates needed** - changesets handle this automatically - **Semantic versioning** is enforced based on changeset types - **Changelog generation** happens automatically - **Git tagging** is handled by the automation ### Critical Fields Sync The automation ensures these fields stay in sync between `package.json` and `package.publish.json`: ```json { "version": "1.0.2", // βœ… AUTO-SYNCED "publisher": "Hamster", // ⚠️ MUST MATCH MANUALLY "displayName": "taskr: Task Master Kanban", // ⚠️ MUST MATCH MANUALLY "description": "...", // ⚠️ MUST MATCH MANUALLY "engines": { "vscode": "^1.93.0" }, // ⚠️ MUST MATCH MANUALLY "categories": [...], // ⚠️ MUST MATCH MANUALLY "contributes": { ... } // ⚠️ MUST MATCH MANUALLY } ``` **Note**: Only `version` is automatically synced. Other fields must be manually kept in sync. ## πŸ” Monitoring Builds ### CI Status - **Green βœ…**: Extension builds and tests successfully - **Red ❌**: Build/test failures - check logs for details - **Yellow 🟑**: Partial success - some jobs may have warnings ### Version PR Status - **Version PR Created**: Changesets detected, review and merge to publish - **No Version PR**: No changesets found, no releases pending - **Version PR Merged**: Automated publishing triggered ### Release Status - **Published πŸŽ‰**: Extension live on VS Code Marketplace and Open VSX - **Skipped ℹ️**: No changesets found, no release needed - **Failed ❌**: Check logs - often missing secrets or build issues ### Artifacts Workflows upload artifacts that you can download: - **CI**: Test results, built files, and VSIX package - **Version**: Final VSIX package and published extension ## πŸ› οΈ Troubleshooting ### Common Issues #### No Version PR Created - **Check**: Changeset files exist in `.changeset/` directory - **Check**: Changeset refers to `taskr-kanban` package name - **Check**: Changes were pushed to `main` branch - **Solution**: Create changeset with `npx changeset add` #### Version PR Not Publishing - **Check**: Version PR was actually merged (not just closed) - **Check**: Required secrets (`VSCE_PAT`, `OVSX_PAT`) are set - **Check**: No build failures in workflow logs - **Solution**: Re-run workflow or check secret configuration #### `VSCE_PAT` is not set Error - Ensure `VSCE_PAT` secret is added to repository - Check token hasn't expired - Verify token has Marketplace β†’ Manage permissions #### `OVSX_PAT` is not set Error - Ensure `OVSX_PAT` secret is added to repository - Check token hasn't expired - Verify you're signed in to Open VSX Registry with GitHub #### Build Failures - Check extension code compiles locally: `cd apps/extension && npm run build` - Verify tests pass locally: `npm run test` - Check for TypeScript errors: `npm run typecheck` #### Packaging Failures - Ensure clean package builds: `npm run package` - Check vsix-build structure is correct - Verify `package.publish.json` has correct `repository` field #### Changeset Issues - **Wrong package name**: Ensure changeset refers to `taskr-kanban` - **Invalid format**: Check changeset markdown format is correct - **Merge conflicts**: Resolve any conflicts in changeset files ## πŸ“ File Structure Impact The CI workflows respect the 3-file packaging system: - **Development**: Uses `package.json` for dependencies and scripts - **Release**: Uses `package.publish.json` for clean marketplace package - **Build**: Uses `package.mjs` to create `vsix-build/` for final packaging - **Changesets**: Automatically manage versions across the system ## 🌍 Dual Registry Publishing Your extension will be automatically published to both: - **VS Code Marketplace** - For official VS Code users - **Open VSX Registry** - For Cursor, Windsurf, VSCodium, Gitpod, Eclipse Theia, and other compatible editors ## 🎯 Benefits of Changeset Automation - βœ… **Automated versioning**: No manual version bumps needed - βœ… **Generated changelogs**: Automatic, accurate release notes - βœ… **Semantic versioning**: Enforced through changeset types - βœ… **Git tagging**: Proper tags for extension releases - βœ… **Conflict prevention**: Clear separation of extension vs. main package versions - βœ… **Review process**: Version changes are reviewable via PR - βœ… **Rollback capability**: Easy to revert if issues arise This ensures clean, predictable, and fully automated publishing to both registries! πŸš€ --- ## File: apps/extension/docs/extension-development-guide.md # VS Code Extension Development Guide ## πŸ“ File Structure Overview This VS Code extension uses a **3-file packaging system** to avoid dependency conflicts during publishing: ``` apps/extension/ β”œβ”€β”€ package.json # Development configuration β”œβ”€β”€ package.publish.json # Clean publishing configuration β”œβ”€β”€ package.mjs # Build script for packaging β”œβ”€β”€ .vscodeignore # Files to exclude from extension package └── vsix-build/ # Generated clean package directory ``` ## πŸ“‹ File Purposes ### `package.json` (Development) - **Purpose**: Development environment with all build tools - **Contains**: - All `devDependencies` needed for building - Development scripts (`build`, `watch`, `lint`, etc.) - Development package name: `"taskr"` - **Used for**: Local development, building, testing ### `package.publish.json` (Publishing) - **Purpose**: Clean distribution version for VS Code Marketplace - **Contains**: - **No devDependencies** (avoids dependency conflicts) - Publishing metadata (`keywords`, `repository`, `categories`) - Marketplace package name: `"taskr-kanban"` - VS Code extension configuration - **Used for**: Final extension packaging ### `package.mjs` (Build Script) - **Purpose**: Creates clean package for distribution - **Process**: 1. Builds the extension (`build:js` + `build:css`) 2. Creates clean `vsix-build/` directory 3. Copies only essential files (no source code) 4. Renames `package.publish.json` β†’ `package.json` 5. Ready for `vsce package` ## πŸš€ Development Workflow ### Local Development ```bash # Install dependencies npm install # Start development with hot reload npm run watch # Run just JavaScript build npm run build:js # Run just CSS build npm run build:css # Full production build npm run build # Type checking npm run typecheck # Linting npm run lint ``` ### Testing in VS Code 1. Press `F5` in VS Code to launch Extension Development Host 2. Test your extension functionality in the new window 3. Use `Developer: Reload Window` to reload after changes ## πŸ“¦ Production Packaging ### Step 1: Build Clean Package ```bash npm run package ``` This creates `vsix-build/` with clean distribution files. ### Step 2: Create VSIX ```bash cd vsix-build npx vsce package --no-dependencies ``` Creates: `taskr-kanban-1.0.1.vsix` ### Alternative: One Command ```bash npm run package && cd vsix-build && npx vsce package --no-dependencies ``` ## πŸ”„ Keeping Files in Sync ### Critical Fields to Sync Between Files When updating extension metadata, ensure these fields match between `package.json` and `package.publish.json`: #### Version & Identity ```json { "version": "1.0.1", // ⚠️ MUST MATCH "publisher": "Hamster", // ⚠️ MUST MATCH "displayName": "taskr: Task Master Kanban", // ⚠️ MUST MATCH "description": "A visual Kanban board...", // ⚠️ MUST MATCH } ``` #### VS Code Configuration ```json { "engines": { "vscode": "^1.101.0" }, // ⚠️ MUST MATCH "categories": [...], // ⚠️ MUST MATCH "activationEvents": [...], // ⚠️ MUST MATCH "main": "./dist/extension.js", // ⚠️ MUST MATCH "contributes": { ... } // ⚠️ MUST MATCH EXACTLY } ``` ### Key Differences (Should NOT Match) ```json // package.json (dev) { "name": "taskr", // βœ… Short dev name "devDependencies": { ... }, // βœ… Only in dev file "scripts": { ... } // βœ… Build scripts } // package.publish.json (publishing) { "name": "taskr-kanban", // βœ… Marketplace name "keywords": [...], // βœ… Only in publish file "repository": "https://github.com/...", // βœ… Only in publish file // NO devDependencies // βœ… Clean for publishing // NO build scripts // βœ… Not needed in package } ``` ## πŸ€– Automated Release Process ### Changesets Workflow This extension uses [Changesets](https://github.com/changesets/changesets) for automated version management and publishing. #### Adding Changes When making changes to the extension: 1. **Make your code changes** 2. **Create a changeset**: ```bash # From project root npx changeset add ``` 3. **Select the extension package**: Choose `taskr-kanban` when prompted 4. **Select version bump type**: - `patch`: Bug fixes, minor updates - `minor`: New features, backwards compatible - `major`: Breaking changes 5. **Write a summary**: Describe what changed for users #### Automated Publishing The automation workflow runs on pushes to `main`: 1. **Version Workflow** (`.github/workflows/version.yml`): - Detects when changesets exist - Creates a "Version Packages" PR with updated versions and CHANGELOG - When the PR is merged, automatically publishes the extension 2. **Release Process** (`scripts/release.sh`): - Builds the extension using the 3-file packaging system - Creates VSIX package - Publishes to VS Code Marketplace (if `VSCE_PAT` is set) - Publishes to Open VSX Registry (if `OVSX_PAT` is set) - Creates git tags for the extension version #### Required Secrets For automated publishing, these secrets must be set in the repository: - `VSCE_PAT`: Personal Access Token for VS Code Marketplace - `OVSX_PAT`: Personal Access Token for Open VSX Registry - `GITHUB_TOKEN`: Automatically provided by GitHub Actions #### Manual Release If needed, you can manually trigger a release: ```bash # From project root ./scripts/release.sh ``` ### Extension Tagging The extension uses a separate tagging strategy from the main package: - **Extension tags**: `taskr-kanban@1.0.1` - **Main package tags**: `task-master-ai@2.1.0` This allows independent versioning and prevents conflicts in the monorepo. ## πŸ” Troubleshooting ### Dependency Conflicts **Problem**: `vsce package` fails with missing dependencies **Solution**: Use the 3-file system - never run `vsce package` from root ### Build Failures **Problem**: Extension not working after build **Check**: 1. All files copied to `vsix-build/dist/` 2. `package.publish.json` has correct `main` field 3. VS Code engine version compatibility ### Sync Issues **Problem**: Extension works locally but fails when packaged **Check**: Ensure critical fields are synced between package files ### Changeset Issues **Problem**: Version workflow not triggering **Check**: 1. Changeset files exist in `.changeset/` 2. Package name in changeset matches `package.publish.json` 3. Changes are pushed to `main` branch **Problem**: Publishing fails **Check**: 1. Required secrets are set in repository settings 2. `package.publish.json` has correct repository URL 3. Build process completes successfully ## πŸ“ Version Release Checklist ### Manual Releases 1. **Create changeset**: `npx changeset add` 2. **Update critical fields** in both `package.json` and `package.publish.json` 3. **Test locally** with `F5` in VS Code 4. **Commit and push** to trigger automated workflow ### Automated Releases (Recommended) 1. **Create changeset**: `npx changeset add` 2. **Push to feature branch** and create PR 3. **Merge PR** - this triggers version PR creation 4. **Review and merge version PR** - this triggers automated publishing ## 🎯 Why This System? - **Avoids dependency conflicts**: VS Code doesn't see dev dependencies - **Clean distribution**: Only essential files in final package - **Faster packaging**: No dependency resolution during `vsce package` - **Maintainable**: Clear separation of dev vs. production configs - **Reliable**: Consistent, conflict-free packaging process - **Automated**: Changesets handle versioning and publishing automatically - **Traceable**: Clear changelog and git tags for every release --- **Remember**: Always use `npx changeset add` for changes, then push to trigger automated releases! πŸš€ --- ## File: apps/extension/README.md # Official Taskmaster AI Extension Transform your AI-driven development workflow with a beautiful, interactive Kanban board directly in VS Code. Seamlessly manage tasks from [Taskmaster AI](https://github.com/eyaltoledano/claude-task-master) projects with real-time synchronization and intelligent task management. ## 🎯 What is Taskmaster AI? Taskmaster AI is an intelligent task management system designed for AI-assisted development. It helps you break down complex projects into manageable tasks, track progress, and leverage AI to enhance your development workflow. ## ✨ Key Features ### πŸ“Š **Interactive Kanban Board** - **Drag & Drop Interface** - Effortlessly move tasks between status columns - **Real-time Sync** - Changes instantly reflect in your Taskmaster project files - **Multiple Views** - Board view and detailed task sidebar - **Smart Columns** - Pending, In Progress, Review, Done, Deferred, and Cancelled ### πŸ€– **AI-Powered Features** - **Task Content Generation** - Regenerate task descriptions using AI - **Smart Task Updates** - Append findings and progress notes automatically - **MCP Integration** - Seamless connection to Taskmaster AI via Model Context Protocol - **Intelligent Caching** - Smart performance optimization with background refresh ### πŸš€ **Performance & Usability** - **Offline Support** - Continue working even when disconnected - **Auto-refresh** - Automatic polling for task changes with smart frequency - **VS Code Native** - Perfectly integrated with VS Code themes and UI - **Modern Interface** - Built with ShadCN UI components and Tailwind CSS ## πŸ› οΈ Installation ### Prerequisites 1. **VS Code** 1.90.0 or higher 2. **Node.js** 20.0 or higher (for Taskmaster MCP server) ### Install the Extension 1. **From VS Code Marketplace:** - Click the **Install** button above - The extension will be automatically added to your VS Code instance ## πŸš€ Quick Start ### 1. **Initialize Taskmaster Project** If you don't have a Taskmaster project yet: ```bash cd your-project npm i task-master-ai task-master init ``` ### 2. **Open Kanban Board** - **Command Palette** (Ctrl+Shift+P): `Taskmaster Kanban: Show Board` - **Or** the extension automatically activates when you have a `.taskmaster` folder in your workspace ### 3. **MCP Server Setup** The extension automatically handles the Taskmaster MCP server connection: - **No manual installation required** - The extension spawns the MCP server automatically - **Uses npx by default** - Automatically downloads Taskmaster AI when needed - **Configurable** - You can customize the MCP server command in settings if needed ### 4. **Start Managing Tasks** - **Drag tasks** between columns to change status - **Click tasks** to view detailed information - **Use AI features** to enhance task content - **Add subtasks** with the + button on parent tasks ## πŸ“‹ Usage Guide ### Task Management | Action | How to Do It | |--------|--------------| | **View Kanban Board** | `Ctrl/Cmd + Shift + P` β†’ "Taskmaster: Show Board" | | **Change Task Status** | Drag task card to different column | | **View Task Details** | Click on any task card | | **Edit Task Content** | Click task β†’ Use edit buttons in details panel | | **Add Subtasks** | Click the + button on parent task cards | | **Use AI Features** | Open task details β†’ Click AI action buttons | ### Understanding Task Statuses - πŸ“‹ **Pending** - Tasks ready to be started - πŸš€ **In Progress** - Currently being worked on - πŸ‘€ **Review** - Awaiting review or feedback - βœ… **Done** - Completed tasks - ⏸️ **Deferred** - Postponed for later ### **AI-Powered Task Management** The extension integrates seamlessly with Taskmaster AI via MCP to provide: - **Smart Task Generation** - AI creates detailed implementation plans - **Progress Tracking** - Append timestamped notes and findings - **Content Enhancement** - Regenerate task descriptions for clarity - **Research Integration** - Get up-to-date information for your tasks ## βš™οΈ Configuration Access settings via **File β†’ Preferences β†’ Settings** and search for "Taskmaster": ### **MCP Connection Settings** - **MCP Server Command** - Path to task-master-ai executable (default: `npx`) - **MCP Server Args** - Arguments for the server command (default: `-y`, `task-master-ai`) - **Connection Timeout** - Server response timeout (default: 30s) - **Auto Refresh** - Enable automatic task updates (default: enabled) ### **UI Preferences** - **Theme** - Auto, Light, or Dark mode - **Show Completed Tasks** - Display done tasks in board (default: enabled) - **Task Display Limit** - Maximum tasks to show (default: 100) ### **Performance Options** - **Cache Duration** - How long to cache task data (default: 5s) - **Concurrent Requests** - Max simultaneous API calls (default: 5) ## πŸ”§ Troubleshooting ### **Extension Not Loading** 1. Ensure Node.js 20+ is installed 2. Check workspace contains `.taskmaster` folder 3. Restart VS Code 4. Check Output panel (View β†’ Output β†’ Taskmaster Kanban) ### **MCP Connection Issues** 1. **Command not found**: Ensure Node.js and npx are in your PATH 2. **Timeout errors**: Increase timeout in settings 3. **Permission errors**: Check Node.js permissions 4. **Network issues**: Verify internet connection for npx downloads ### **Tasks Not Updating** 1. Check MCP connection status in status bar 2. Verify `.taskmaster/tasks/tasks.json` exists 3. Try manual refresh: `Taskmaster Kanban: Check Connection` 4. Review error logs in Output panel ### **Performance Issues** 1. Reduce task display limit in settings 2. Increase cache duration 3. Disable auto-refresh if needed 4. Close other VS Code extensions temporarily ## πŸ†˜ Support & Resources ### **Getting Help** - πŸ“– **Documentation**: [Taskmaster AI Docs](https://github.com/eyaltoledano/claude-task-master) - πŸ› **Report Issues**: [GitHub Issues](https://github.com/eyaltoledano/claude-task-master/issues) - πŸ’¬ **Discussions**: [GitHub Discussions](https://github.com/eyaltoledano/claude-task-master/discussions) - πŸ› **Report Issues**: [GitHub Issues](https://github.com/eyaltoledano/claude-task-master/issues) ## 🎯 Tips for Best Results ### **Project Organization** - Use descriptive task titles - Add detailed implementation notes - Set appropriate task dependencies - Leverage AI features for complex tasks ### **Workflow Optimization** - Review task details before starting work - Use subtasks for complex features - Update task status as you progress - Add findings and learnings to task notes ### **Collaboration** - Keep task descriptions updated - Use consistent status conventions - Document decisions in task details - Share knowledge through task notes --- ## πŸ† Why Taskmaster Kanban? βœ… **Visual workflow management** for your Taskmaster projects βœ… **AI-powered task enhancement** built right in βœ… **Real-time synchronization** keeps everything in sync βœ… **Native VS Code integration** feels like part of the editor βœ… **Free and open source** with active development **Transform your development workflow today!** πŸš€ --- *Originally Made with ❀️ by [David Maliglowka](https://x.com/DavidMaliglowka)* ## Support This is an open-source project maintained in my spare time. While I strive to fix bugs and improve the extension, support is provided on a best-effort basis. Feel free to: - Report issues on [GitHub](https://github.com/eyaltoledano/claude-task-master/issues) - Submit pull requests with improvements - Fork the project if you need specific modifications ## Disclaimer This extension is provided "as is" without any warranties. Use at your own risk. The author is not responsible for any issues, data loss, or damages that may occur from using this extension. Please backup your work regularly and test thoroughly before using in important projects. --- ## File: apps/docs/capabilities/cli-root-commands.mdx --- title: CLI Commands sidebarTitle: "CLI Commands" --- ```bash # Parse a PRD file and generate tasks task-master parse-prd # Limit the number of tasks generated task-master parse-prd --num-tasks=10 ``` ```bash # List all tasks task-master list # List tasks with a specific status task-master list --status= # List tasks with subtasks task-master list --with-subtasks # List tasks with a specific status and include subtasks task-master list --status= --with-subtasks # Watch for changes and auto-refresh the list task-master list --watch task-master list -w # Combine watch with other options task-master list all -w # Watch all tasks with subtasks task-master list -w --compact # Watch in compact format task-master list --status=pending -w # Watch pending tasks only ``` ```bash # Show the next task to work on based on dependencies and status task-master next ``` ```bash # Show details of a specific task task-master show # or task-master show --id= # View a specific subtask (e.g., subtask 2 of task 1) task-master show 1.2 ``` ```bash # Update tasks from a specific ID and provide context task-master update --from= --prompt="" ``` ```bash # Update a single task by ID with new information task-master update-task --id= --prompt="" # Use research-backed updates with Perplexity AI task-master update-task --id= --prompt="" --research ``` ```bash # Append additional information to a specific subtask task-master update-subtask --id= --prompt="" # Example: Add details about API rate limiting to subtask 2 of task 5 task-master update-subtask --id=5.2 --prompt="Add rate limiting of 100 requests per minute" # Use research-backed updates with Perplexity AI task-master update-subtask --id= --prompt="" --research ``` Unlike the `update-task` command which replaces task information, the `update-subtask` command _appends_ new information to the existing subtask details, marking it with a timestamp. This is useful for iteratively enhancing subtasks while preserving the original content. ```bash # Generate individual task files from tasks.json task-master generate ``` ```bash # Set status of a single task task-master set-status --id= --status= # Set status for multiple tasks task-master set-status --id=1,2,3 --status= # Set status for subtasks task-master set-status --id=1.1,1.2 --status= ``` When marking a task as "done", all of its subtasks will automatically be marked as "done" as well. ```bash # Expand a specific task with subtasks task-master expand --id= --num= # Expand with additional context task-master expand --id= --prompt="" # Expand all pending tasks task-master expand --all # Force regeneration of subtasks for tasks that already have them task-master expand --all --force # Research-backed subtask generation for a specific task task-master expand --id= --research # Research-backed generation for all tasks task-master expand --all --research ``` ```bash # Clear subtasks from a specific task task-master clear-subtasks --id= # Clear subtasks from multiple tasks task-master clear-subtasks --id=1,2,3 # Clear subtasks from all tasks task-master clear-subtasks --all ``` ```bash # Analyze complexity of all tasks task-master analyze-complexity # Save report to a custom location task-master analyze-complexity --output=my-report.json # Use a specific LLM model task-master analyze-complexity --model=claude-3-opus-20240229 # Set a custom complexity threshold (1-10) task-master analyze-complexity --threshold=6 # Use an alternative tasks file task-master analyze-complexity --file=custom-tasks.json # Use your configured research model for research-backed complexity analysis task-master analyze-complexity --research ``` ```bash # Display the task complexity analysis report task-master complexity-report # View a report at a custom location task-master complexity-report --file=my-report.json ``` ```bash # Add a dependency to a task task-master add-dependency --id= --depends-on= # Remove a dependency from a task task-master remove-dependency --id= --depends-on= # Validate dependencies without fixing them task-master validate-dependencies # Find and fix invalid dependencies automatically task-master fix-dependencies ``` ```bash # Add a new task using AI task-master add-task --prompt="Description of the new task" # Add a task with dependencies task-master add-task --prompt="Description" --dependencies=1,2,3 # Add a task with priority task-master add-task --prompt="Description" --priority=high ``` ```bash # Initialize a new project with Task Master structure task-master init ``` --- ## File: apps/docs/capabilities/index.mdx --- title: Technical Capabilities sidebarTitle: "Technical Capabilities" --- # Capabilities (Technical) Discover the technical capabilities of Task Master, including supported models, integrations, and more. # CLI Interface Synopsis This document outlines the command-line interface (CLI) for the Task Master application, as defined in `bin/task-master.js` and the `scripts/modules/commands.js` file (which I will assume exists based on the context). This guide is intended for those writing user-facing documentation to understand how users interact with the application from the command line. ## Entry Point The main entry point for the CLI is the `task-master` command, which is an executable script that spawns the main application logic in `scripts/dev.js`. ## Global Options The following options are available for all commands: - `-h, --help`: Display help information. - `--version`: Display the application's version. ## Commands The CLI is organized into a series of commands, each with its own set of options. The following is a summary of the available commands, categorized by their functionality. ### 1. Task and Subtask Management - **`add`**: Creates a new task using an AI-powered prompt. - `--prompt `: The prompt to use for generating the task. - `--dependencies `: A comma-separated list of task IDs that this task depends on. - `--priority `: The priority of the task (e.g., `high`, `medium`, `low`). - **`add-subtask`**: Adds a subtask to a parent task. - `--parent-id `: The ID of the parent task. - `--task-id `: The ID of an existing task to convert to a subtask. - `--title `: The title of the new subtask. - **`remove`**: Removes one or more tasks or subtasks. - `--ids `: A comma-separated list of task or subtask IDs to remove. - **`remove-subtask`**: Removes a subtask from its parent. - `--id <subtaskId>`: The ID of the subtask to remove (in the format `parentId.subtaskId`). - `--convert-to-task`: Converts the subtask to a standalone task. - **`update`**: Updates multiple tasks starting from a specific ID. - `--from <fromId>`: The ID of the task to start updating from. - `--prompt `: The new context to apply to the tasks. - **`update-task`**: Updates a single task. - `--id <taskId>`: The ID of the task to update. - `--prompt `: The new context to apply to the task. - **`update-subtask`**: Appends information to a subtask. - `--id <subtaskId>`: The ID of the subtask to update (in the format `parentId.subtaskId`). - `--prompt `: The information to append to the subtask. - **`move`**: Moves a task or subtask. - `--from `: The ID of the task or subtask to move. - `--to <destinationId>`: The destination ID. - **`clear-subtasks`**: Clears all subtasks from one or more tasks. - `--ids `: A comma-separated list of task IDs. ### 2. Task Information and Status - **`list`**: Lists all tasks. - `--status <status>`: Filters tasks by status. - `--with-subtasks`: Includes subtasks in the list. - **`show`**: Shows the details of a specific task. - `--id <taskId>`: The ID of the task to show. - **`next`**: Shows the next task to work on. - **`set-status`**: Sets the status of a task or subtask. - `--id `: The ID of the task or subtask. - `--status <status>`: The new status. ### 3. Task Analysis and Expansion - **`parse-prd`**: Parses a PRD to generate tasks. - `--file <file>`: The path to the PRD file. - `--num-tasks <numTasks>`: The number of tasks to generate. - **`expand`**: Expands a task into subtasks. - `--id <taskId>`: The ID of the task to expand. - `--num-subtasks <numSubtasks>`: The number of subtasks to generate. - **`expand-all`**: Expands all eligible tasks. - `--num-subtasks <numSubtasks>`: The number of subtasks to generate for each task. - **`analyze-complexity`**: Analyzes task complexity. - `--file <file>`: The path to the tasks file. - **`complexity-report`**: Displays the complexity analysis report. ### 4. Project and Configuration - **`init`**: Initializes a new project. - **`generate`**: Generates individual task files. - **`migrate`**: Migrates a project to the new directory structure. - **`research`**: Performs AI-powered research. - `--query <query>`: The research query. This synopsis provides a comprehensive overview of the CLI commands and their options, which should be helpful for creating user-facing documentation. # Core Implementation Synopsis This document provides a high-level overview of the core implementation of the Task Master application, focusing on the functionalities exposed through `scripts/modules/task-manager.js`. This serves as a guide for understanding the application's capabilities when writing user-facing documentation. ## Core Concepts The application revolves around the management of tasks and subtasks, which are stored in a `tasks.json` file. The core logic provides functionalities to create, read, update, and delete tasks and subtasks, as well as manage their dependencies and statuses. ### Task Structure A task is a JSON object with the following key properties: - `id`: A unique number identifying the task. - `title`: A string representing the task's title. - `description`: A string providing a brief description of the task. - `details`: A string containing detailed information about the task. - `testStrategy`: A string describing how to test the task. - `status`: A string representing the task's current status (e.g., `pending`, `in-progress`, `done`). - `dependencies`: An array of task IDs that this task depends on. - `priority`: A string representing the task's priority (e.g., `high`, `medium`, `low`). - `subtasks`: An array of subtask objects. A subtask has a similar structure to a task but is nested within a parent task. ## Feature Categories The core functionalities can be categorized as follows: ### 1. Task and Subtask Management These functions are the bread and butter of the application, allowing for the creation, modification, and deletion of tasks and subtasks. - **`addTask(prompt, dependencies, priority)`**: Creates a new task using an AI-powered prompt to generate the title, description, details, and test strategy. It can also be used to create a task manually by providing the task data directly. - **`addSubtask(parentId, existingTaskId, newSubtaskData)`**: Adds a subtask to a parent task. It can either convert an existing task into a subtask or create a new subtask from scratch. - **`removeTask(taskIds)`**: Removes one or more tasks or subtasks. - **`removeSubtask(subtaskId, convertToTask)`**: Removes a subtask from its parent. It can optionally convert the subtask into a standalone task. - **`updateTaskById(taskId, prompt)`**: Updates a task's information based on a prompt. - **`updateSubtaskById(subtaskId, prompt)`**: Appends additional information to a subtask's details. - **`updateTasks(fromId, prompt)`**: Updates multiple tasks starting from a specific ID based on a new context. - **`moveTask(sourceId, destinationId)`**: Moves a task or subtask to a new position. - **`clearSubtasks(taskIds)`**: Clears all subtasks from one or more tasks. ### 2. Task Information and Status These functions are used to retrieve information about tasks and manage their status. - **`listTasks(statusFilter, withSubtasks)`**: Lists all tasks, with options to filter by status and include subtasks. - **`findTaskById(taskId)`**: Finds a task by its ID. - **`taskExists(taskId)`**: Checks if a task with a given ID exists. - **`setTaskStatus(taskIdInput, newStatus)`**: Sets the status of a task or subtask. -al - **`updateSingleTaskStatus(taskIdInput, newStatus)`**: A helper function to update the status of a single task or subtask. - **`findNextTask()`**: Determines the next task to work on based on dependencies and status. ### 3. Task Analysis and Expansion These functions leverage AI to analyze and break down tasks. - **`parsePRD(prdPath, numTasks)`**: Parses a Product Requirements Document (PRD) to generate an initial set of tasks. - **`expandTask(taskId, numSubtasks)`**: Expands a task into a specified number of subtasks using AI. - **`expandAllTasks(numSubtasks)`**: Expands all eligible pending or in-progress tasks. - **`analyzeTaskComplexity(options)`**: Analyzes the complexity of tasks and generates recommendations for expansion. - **`readComplexityReport()`**: Reads the complexity analysis report. ### 4. Dependency Management These functions are crucial for managing the relationships between tasks. - **`isTaskDependentOn(task, targetTaskId)`**: Checks if a task has a direct or indirect dependency on another task. ### 5. Project and Configuration These functions are for managing the project and its configuration. - **`generateTaskFiles()`**: Generates individual task files from `tasks.json`. - **`migrateProject()`**: Migrates the project to the new `.taskmaster` directory structure. - **`performResearch(query, options)`**: Performs AI-powered research with project context. This overview should provide a solid foundation for creating user-facing documentation. For more detailed information on each function, refer to the source code in `scripts/modules/task-manager/`. # MCP Interface Synopsis This document provides an overview of the MCP (Machine-to-Machine Communication Protocol) interface for the Task Master application. The MCP interface is defined in the `mcp-server/` directory and exposes the application's core functionalities as a set of tools that can be called remotely. ## Core Concepts The MCP interface is built on top of the `fastmcp` library and registers a set of tools that correspond to the core functionalities of the Task Master application. These tools are defined in the `mcp-server/src/tools/` directory and are registered with the MCP server in `mcp-server/src/tools/index.js`. Each tool is defined with a name, a description, and a set of parameters that are validated using the `zod` library. The `execute` function of each tool calls the corresponding core logic function from `scripts/modules/task-manager.js`. ## Tool Categories The MCP tools can be categorized in the same way as the core functionalities: ### 1. Task and Subtask Management - **`add_task`**: Creates a new task. - **`add_subtask`**: Adds a subtask to a parent task. - **`remove_task`**: Removes one or more tasks or subtasks. - **`remove_subtask`**: Removes a subtask from its parent. - **`update_task`**: Updates a single task. - **`update_subtask`**: Appends information to a subtask. - **`update`**: Updates multiple tasks. - **`move_task`**: Moves a task or subtask. - **`clear_subtasks`**: Clears all subtasks from one or more tasks. ### 2. Task Information and Status - **`get_tasks`**: Lists all tasks. - **`get_task`**: Shows the details of a specific task. - **`next_task`**: Shows the next task to work on. - **`set_task_status`**: Sets the status of a task or subtask. ### 3. Task Analysis and Expansion - **`parse_prd`**: Parses a PRD to generate tasks. - **`expand_task`**: Expands a task into subtasks. - **`expand_all`**: Expands all eligible tasks. - **`analyze_project_complexity`**: Analyzes task complexity. - **`complexity_report`**: Displays the complexity analysis report. ### 4. Dependency Management - **`add_dependency`**: Adds a dependency to a task. - **`remove_dependency`**: Removes a dependency from a task. - **`validate_dependencies`**: Validates the dependencies of all tasks. - **`fix_dependencies`**: Fixes any invalid dependencies. ### 5. Project and Configuration - **`initialize_project`**: Initializes a new project. - **`generate`**: Generates individual task files. - **`models`**: Manages AI model configurations. - **`research`**: Performs AI-powered research. ### 6. Tag Management - **`add_tag`**: Creates a new tag. - **`delete_tag`**: Deletes a tag. - **`list_tags`**: Lists all tags. - **`use_tag`**: Switches to a different tag. - **`rename_tag`**: Renames a tag. - **`copy_tag`**: Copies a tag. This synopsis provides a clear overview of the MCP interface and its available tools, which will be valuable for anyone writing documentation for developers who need to interact with the Task Master application programmatically. --- ## File: apps/docs/capabilities/loop.mdx --- title: Loop Command sidebarTitle: "Loop Command" --- # Loop Command The `loop` command runs Claude Code in autonomous loops, spawning fresh agent sessions for each iteration. This approach, known as the "Ralph Wiggum pattern" (credited to Jeffrey Huntley, popularized by Matt Pocock), maintains context quality by avoiding long-running sessions that accumulate context fatigue. ## Overview Instead of a single long-running agent session that degrades over time, the loop command: 1. **Spawns fresh sessions** - Each iteration starts with a clean context 2. **Uses preset prompts** - Built-in or custom prompts guide each iteration 3. **Tracks progress** - A progress file persists notes across sessions 4. **Detects completion** - Special markers signal when work is done or blocked This pattern is ideal for batch operations like clearing task backlogs, improving test coverage, or fixing lint errors across a codebase. ## Basic Usage Run 10 iterations with the default task-completion preset: ```bash task-master loop -n 10 ``` Run 5 iterations with the test-coverage preset: ```bash task-master loop -n 5 --prompt test-coverage ``` Run iterations with a custom prompt file: ```bash task-master loop -n 10 --prompt ./my-custom-prompt.md ``` Filter to specific task tag: ```bash task-master loop -n 10 --tag backend ``` ## How It Works Each loop iteration: 1. Generates a prompt combining context header + preset content 2. Spawns `claude -p ` as a fresh subprocess 3. Captures output and checks for completion markers 4. Appends progress notes to the progress file 5. Sleeps before the next iteration (configurable) The loop exits early when: - An agent outputs `<loop-complete>REASON</loop-complete>` - all work done - An agent outputs `<loop-blocked>REASON</loop-blocked>` - cannot proceed - Maximum iterations reached ## Progress File Each iteration's agent has access to a shared progress file (default: `.taskmaster/loop-progress.txt`) via the `@` file reference syntax. Agents append notes about what they completed, allowing subsequent iterations to build on previous work. Example progress file content: ``` # Loop Progress - Started 2025-01-09 10:30:00 # Preset: test-coverage | Iterations: 10 [10:30:45] Iteration 1 (Task 5.2): Added unit tests for UserService [10:35:22] Iteration 2 (Task 5.3): Added integration tests for auth flow [10:40:18] Iteration 3: All pending test tasks complete ``` ## CLI Options | Option | Type | Default | Description | | ------------------------ | ------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `-n, --iterations` | number | `10` | Maximum number of iterations to run. | | `-p, --prompt` | string | `default` | Preset name or path to a custom prompt file. Accepts: `default`, `test-coverage`, `linting`, `duplication`, `entropy`, or a file path like `./my-prompt.md`. | | `--progress-file` | string | `.taskmaster/loop-progress.txt` | Path to the progress log file where iteration notes are appended. | | `--sleep` | number | `5` | Seconds to wait between iterations. Gives the system time to settle before spawning the next agent. | | `--on-complete` | string | - | Shell command to run when all tasks complete (status becomes `all_complete`). Example: `--on-complete 'notify-send "Done!"'` | | `-t, --tag` | string | - | Filter to only work on tasks with this tag. | | `--status` | string | `pending` | Filter to only work on tasks with this status. | | `--project` | string | - | Project root directory. Auto-detected if not provided. | | `--json` | flag | - | Output results as JSON instead of formatted text. | ### Option Details **`--prompt` accepts two types of values:** - **Preset names**: Use built-in presets like `default`, `test-coverage`, `linting`, `duplication`, or `entropy` - **File paths**: Provide a path to a custom prompt file (e.g., `./my-custom-loop.md`) **`--on-complete` runs only on success:** The shell command only executes when `finalStatus` is `all_complete`, meaning an agent output the `<loop-complete>` marker. It does not run on `max_iterations`, `blocked`, or `error` outcomes. ## Built-in Presets The loop command includes five built-in presets for common development workflows. Each preset guides agents to complete ONE focused task per iteration. | Preset | Purpose | Completion Marker | | ------ | ------- | ----------------- | | `default` | Complete tasks from Task Master backlog | `ALL_TASKS_DONE` | | `test-coverage` | Write meaningful tests for uncovered code | `COVERAGE_TARGET` | | `linting` | Fix lint and type errors one by one | `ZERO_ERRORS` | | `duplication` | Refactor duplicated code into shared utilities | `LOW_DUPLICATION` | | `entropy` | Clean up code smells (long functions, deep nesting) | `LOW_ENTROPY` | ### default The standard task completion workflow. Agents work through your Task Master backlog, completing one task per iteration. ```bash task-master loop -n 10 --prompt default ``` **What it does:** 1. Runs `task-master next` to get the highest priority available task 2. Reads task details with `task-master show ` 3. Implements the task with the smallest possible change 4. Runs tests and type checks to verify quality 5. Marks the task complete with `task-master set-status --id= --status=done` 6. Commits work with a descriptive message **Completion criteria:** All pending tasks are complete. ### test-coverage Improves test coverage by writing meaningful tests for user-facing behavior - not just chasing coverage numbers. ```bash task-master loop -n 10 --prompt test-coverage ``` **What it does:** 1. Runs the coverage command (`npm run coverage`, etc.) 2. Identifies the most important user-facing feature lacking tests 3. Writes ONE meaningful test validating real behavior 4. Verifies coverage increased as a side effect 5. Commits with message: `test(<file>): <describe user behavior tested>` **Philosophy:** Don't write tests just to increase coverage. Use coverage as a guide to find untested user-facing behavior. Prioritize error handling, CLI commands, API endpoints, and file parsing over internal utilities. **Completion criteria:** Coverage reaches target or 100%. ### linting Cleans up lint errors and type errors systematically, one fix per iteration. ```bash task-master loop -n 20 --prompt linting ``` **What it does:** 1. Runs lint command (`npm run lint`, `eslint .`, etc.) 2. Runs type check (`tsc --noEmit`, etc.) 3. Picks ONE error to fix, prioritizing: - Type errors (breaks builds) - Security-related lint errors - Errors in frequently-changed files 4. Fixes with minimal changes - no surrounding refactoring 5. Commits with message: `fix(<file>): <describe error fixed>` **Completion criteria:** Zero lint errors and zero type errors. ### duplication Finds duplicated code using detection tools and refactors into shared utilities. ```bash task-master loop -n 10 --prompt duplication ``` **What it does:** 1. Runs duplication detection (`npx jscpd .` or similar) 2. Reviews the report and picks ONE clone to refactor, prioritizing: - Larger clones (more lines = more maintenance burden) - Clones in frequently-changed files - Clones with slight variations 3. Extracts duplicated code into a shared utility 4. Updates all clone locations to use the shared utility 5. Runs tests to verify behavior is preserved **Completion criteria:** Duplication below threshold (e.g., <3%). ### entropy Targets code smells that increase cognitive load and maintenance burden. ```bash task-master loop -n 10 --prompt entropy ``` **Code smells targeted:** - Long functions (>60 lines) β†’ extract into smaller functions - Deep nesting (>3 levels) β†’ use early returns, extract conditions - Large files (>500 lines) β†’ split into focused modules - Magic numbers β†’ extract into named constants - Complex conditionals β†’ extract into well-named functions - God classes β†’ split responsibilities **What it does:** 1. Scans codebase for code smells (uses judgment or tools like `complexity-report`) 2. Picks ONE smell to fix, prioritizing smells in critical paths 3. Refactors with minimal changes - no over-engineering 4. Runs tests to verify behavior is preserved **Completion criteria:** No significant code smells remain. ## Custom Prompts You can create custom prompt files for specialized workflows that aren't covered by the built-in presets. ### Specifying a Custom Prompt Pass the file path to the `--prompt` option: ```bash task-master loop -n 10 --prompt ./my-custom-loop.md ``` The path can be absolute or relative to the current directory. ### Required Structure Custom prompts should follow this structure to work effectively with the loop system: ```markdown # Your Loop Title Brief description of what this loop does. ## Files Available - @.taskmaster/tasks/tasks.json - Your task backlog - @.taskmaster/loop-progress.txt - Progress log from previous iterations - @path/to/other/file.ts - Any other files the agent needs ## Process 1. Step one of the workflow 2. Step two of the workflow 3. ... more steps ## Important - Complete ONLY ONE task per session - Keep changes small and focused - Do NOT start another task after completing one - If work is complete, output: <loop-complete>REASON</loop-complete> - If blocked, output: <loop-blocked>REASON</loop-blocked> ``` ### File References with @ Syntax The `@` prefix makes files available to the agent. Claude Code will read these files when processing the prompt: ```markdown ## Files Available - @src/index.ts - Main entry point - @package.json - Dependencies and scripts - @.taskmaster/loop-progress.txt - Progress from previous iterations ``` Without the `@` prefix, file paths are just text. With `@`, the agent can actually read and reference the file contents. ### Completion Markers The loop watches for two special markers in agent output: | Marker | Purpose | Example | | ------ | ------- | ------- | | `<loop-complete>REASON</loop-complete>` | Signal that all work is done | `<loop-complete>ALL_TESTS_PASSING</loop-complete>` | | `<loop-blocked>REASON</loop-blocked>` | Signal that work cannot proceed | `<loop-blocked>MISSING_API_KEY</loop-blocked>` | When either marker is detected, the loop exits early. The reason text is captured in the final result. **Example usage in a custom prompt:** ```markdown ## Important - If all migrations are complete, output: <loop-complete>MIGRATIONS_DONE</loop-complete> - If a migration fails with an unrecoverable error, output: <loop-blocked>MIGRATION_FAILED: describe error</loop-blocked> ``` ### Best Practices 1. **Be specific**: Clearly define what "done" means for your workflow 2. **One task per iteration**: Instruct agents to complete exactly one unit of work 3. **Use the progress file**: Reference `@.taskmaster/loop-progress.txt` so agents can see what previous iterations accomplished 4. **Include quality checks**: Add steps for running tests or type checks before completing 5. **Define completion criteria**: Tell agents exactly when to output `<loop-complete>` 6. **Handle edge cases**: Define when to output `<loop-blocked>` to avoid infinite loops ## Progress File The progress file is a shared log that persists notes across loop iterations. Since each iteration spawns a fresh agent session, this file provides continuity. ### Default Location ``` .taskmaster/loop-progress.txt ``` Override with the `--progress-file` option: ```bash task-master loop -n 10 --progress-file ./my-progress.txt ``` ### How It Works 1. **Initialization**: The loop creates the progress file at the start with a header 2. **Each iteration**: Agents read the file via `@` reference and append notes about their work 3. **Context continuity**: Subsequent agents see what previous iterations accomplished ### File Format The progress file uses a simple timestamped format: ``` # Loop Progress - Started 2025-01-09 10:30:00 # Preset: default | Iterations: 10 | Tag: backend [10:30:45] Iteration 1 (Task 5.2): Implemented user authentication endpoint [10:35:22] Iteration 2 (Task 5.3): Added input validation for login form [10:40:18] Iteration 3 (Task 5.4): Fixed edge case in token refresh logic [10:45:01] Iteration 4: All pending backend tasks complete ``` **Format breakdown:** - **Header**: Timestamp, preset name, max iterations, optional tag filter - **Entries**: `[HH:MM:SS] Iteration N (Task ID): Description` - **Task ID**: Optional - included when agent worked on a specific task ### Using Progress in Custom Prompts Always include the progress file in your `## Files Available` section: ```markdown ## Files Available - @.taskmaster/loop-progress.txt - Progress log from previous iterations ``` And instruct agents to append notes: ```markdown ## Process ... 7. Append a brief note to the progress file about what was done ``` This creates a chain of context that helps each iteration build on previous work. ## Real-World Examples Here are practical scenarios for using the loop command in your development workflow. ### Weekend Automation Run a loop overnight or over the weekend to clear your task backlog while you're away: ```bash task-master loop -n 50 --prompt default --on-complete 'notify-send "Loop complete!"' ``` This runs up to 50 iterations, completing tasks one by one. When all tasks are done, you'll get a desktop notification. ### Test Coverage Sprint Push your test coverage from 60% to 80% systematically: ```bash task-master loop -n 20 --prompt test-coverage --on-complete 'echo "Coverage target reached!"' ``` Each iteration identifies the most important untested user-facing behavior and writes a meaningful test. The agent prioritizes error handling, API endpoints, and CLI commands over internal utilities. ### Tech Debt Day Dedicate a day to cleaning up lint errors across your codebase: ```bash task-master loop -n 30 --prompt linting --sleep 3 ``` With `--sleep 3`, iterations run faster for quick fixes. The agent systematically addresses type errors first (they break builds), then security-related lint errors, then others. ### Code Review Prep Reduce code duplication before opening a PR: ```bash task-master loop -n 10 --prompt duplication --tag backend ``` The `--tag backend` flag focuses the loop on backend code only. Each iteration finds and refactors one instance of duplicated code into a shared utility. ### Multi-Tag Workflow Process different parts of your codebase in sequence: ```bash # First, handle critical backend tasks task-master loop -n 10 --tag backend --status pending # Then, address frontend tasks task-master loop -n 10 --tag frontend --status pending ``` ### Custom Migration Script For complex migrations, create a custom prompt and run it: ```bash # Create custom-migration.md with your specific steps task-master loop -n 20 --prompt ./custom-migration.md --progress-file ./migration-progress.txt ``` Use a separate progress file to track migration-specific notes. --- <Note> **Related documentation:** - [CLI Root Commands](/capabilities/cli-root-commands) - Full command reference - [TDD Workflow](/tdd-workflow/quickstart) - Structured test-driven development - [Task Structure](/capabilities/task-structure) - Understanding task organization </Note> <Tip> The loop command is perfect for "overnight automation" - start a loop before leaving and return to a cleaned-up codebase. </Tip> --- ## File: apps/docs/capabilities/mcp.mdx --- title: MCP Tools sidebarTitle: "MCP Tools" --- # MCP Tools This document provides an overview of the MCP (Machine-to-Machine Communication Protocol) interface for the Task Master application. The MCP interface is defined in the `mcp-server/` directory and exposes the application's core functionalities as a set of tools that can be called remotely. ## Core Concepts The MCP interface is built on top of the `fastmcp` library and registers a set of tools that correspond to the core functionalities of the Task Master application. These tools are defined in the `mcp-server/src/tools/` directory and are registered with the MCP server in `mcp-server/src/tools/index.js`. Each tool is defined with a name, a description, and a set of parameters that are validated using the `zod` library. The `execute` function of each tool calls the corresponding core logic function from `scripts/modules/task-manager.js`. ## Configurable Tool Loading To optimize LLM context usage, you can control which Task Master MCP tools are loaded using the `TASK_MASTER_TOOLS` environment variable. This is particularly useful when working with LLMs that have context limits or when you only need a subset of tools. ### Configuration Modes #### Core Tools (Default, Lean Mode) Loads only 7 essential tools for daily development. Ideal for minimal context usage. **Core tools included:** - `get_tasks` - List all tasks - `next_task` - Find the next task to work on - `get_task` - Get detailed task information - `set_task_status` - Update task status - `update_subtask` - Add implementation notes - `parse_prd` - Generate tasks from PRD - `expand_task` - Break down tasks into subtasks ```json { "mcpServers": { "task-master-ai": { "command": "npx", "args": ["-y", "task-master-ai"], "env": { "TASK_MASTER_TOOLS": "core", "ANTHROPIC_API_KEY": "your_key_here" } } } } ``` You can also use `"lean"` as an alias for `"core"`. If `TASK_MASTER_TOOLS` is not set, core tools are loaded by default. #### Standard Tools Loads 15 commonly used tools. Balances functionality with context efficiency. **Standard tools include all core tools plus:** - `initialize_project` - Set up new projects - `analyze_project_complexity` - Analyze task complexity - `expand_all` - Expand all eligible tasks - `add_subtask` - Add subtasks manually - `remove_task` - Remove tasks - `generate` - Generate task markdown files - `add_task` - Create new tasks - `complexity_report` - View complexity analysis ```json { "mcpServers": { "task-master-ai": { "command": "npx", "args": ["-y", "task-master-ai"], "env": { "TASK_MASTER_TOOLS": "standard", "ANTHROPIC_API_KEY": "your_key_here" } } } } ``` #### Custom Tool Selection Specify exactly which tools to load using a comma-separated list. Tool names are case-insensitive and support both underscores and hyphens. ```json { "mcpServers": { "task-master-ai": { "command": "npx", "args": ["-y", "task-master-ai"], "env": { "TASK_MASTER_TOOLS": "get_tasks,next_task,set_task_status,update_subtask", "ANTHROPIC_API_KEY": "your_key_here" } } } } ``` #### All Tools Loads all 36 available tools. Use when you need full Task Master functionality. ```json { "mcpServers": { "task-master-ai": { "command": "npx", "args": ["-y", "task-master-ai"], "env": { "TASK_MASTER_TOOLS": "all", "ANTHROPIC_API_KEY": "your_key_here" } } } } ``` ### Choosing the Right Configuration - **Use `core`/`lean`**: Default setting, ideal for basic task management workflows or when context limits are strict - **Use `standard`**: For most development workflows that include task creation and analysis - **Use `all`**: When you need full functionality including tag management, dependencies, and advanced features - **Use custom list**: When you have specific tool requirements or want to experiment with minimal sets ### Verification When the MCP server starts, it logs which tools were loaded: ``` Task Master MCP Server starting... Tool mode configuration: standard Loading standard tools Registering 15 MCP tools (mode: standard) Successfully registered 15/15 tools ``` ## Tool Categories The MCP tools can be categorized in the same way as the core functionalities: ### 1. Task and Subtask Management - **`add_task`**: Creates a new task. - **`add_subtask`**: Adds a subtask to a parent task. - **`remove_task`**: Removes one or more tasks or subtasks. - **`remove_subtask`**: Removes a subtask from its parent. - **`update_task`**: Updates a single task. - **`update_subtask`**: Appends information to a subtask. - **`update`**: Updates multiple tasks. - **`move_task`**: Moves a task or subtask. - **`clear_subtasks`**: Clears all subtasks from one or more tasks. ### 2. Task Information and Status - **`get_tasks`**: Lists all tasks. - **`get_task`**: Shows the details of a specific task. - **`next_task`**: Shows the next task to work on. - **`set_task_status`**: Sets the status of a task or subtask. ### 3. Task Analysis and Expansion - **`parse_prd`**: Parses a PRD to generate tasks. - **`expand_task`**: Expands a task into subtasks. - **`expand_all`**: Expands all eligible tasks. - **`analyze_project_complexity`**: Analyzes task complexity. - **`complexity_report`**: Displays the complexity analysis report. ### 4. Dependency Management - **`add_dependency`**: Adds a dependency to a task. - **`remove_dependency`**: Removes a dependency from a task. - **`validate_dependencies`**: Validates the dependencies of all tasks. - **`fix_dependencies`**: Fixes any invalid dependencies. ### 5. Project and Configuration - **`initialize_project`**: Initializes a new project. - **`generate`**: Generates individual task files. - **`models`**: Manages AI model configurations. - **`research`**: Performs AI-powered research. ### 6. Tag Management - **`add_tag`**: Creates a new tag. - **`delete_tag`**: Deletes a tag. - **`list_tags`**: Lists all tags. - **`use_tag`**: Switches to a different tag. - **`rename_tag`**: Renames a tag. - **`copy_tag`**: Copies a tag. --- ## File: apps/docs/capabilities/rpg-method.mdx --- title: RPG Method for PRD Creation sidebarTitle: "RPG Method" --- # Repository Planning Graph (RPG) Method The RPG (Repository Planning Graph) method is an advanced approach to creating Product Requirements Documents that generate highly-structured, dependency-aware task graphs. It's based on Microsoft Research's methodology for scalable codebase generation. ## When to Use RPG Use the RPG template (`example_prd_rpg.md`) for: - **Complex multi-module systems** with intricate dependencies - **Large-scale codebases** being built from scratch - **Projects requiring explicit architecture** and clear module boundaries - **Teams needing dependency visibility** for parallel development For simpler features or smaller projects, the standard `example_prd.md` template may be more appropriate. --- ## Core Principles ### 1. Dual-Semantics Separate **functional** thinking (WHAT) from **structural** thinking (HOW): ``` Functional: "Data Validation capability with schema checking and rule enforcement" ↓ Structural: "src/validation/ with schema-validator.js and rule-validator.js" ``` This separation prevents mixing concerns and creates clearer module boundaries. ### 2. Explicit Dependencies Never assume dependencies - always state them explicitly: ``` Good: Module: data-ingestion Depends on: [schema-validator, config-manager] Bad: Module: data-ingestion (Assumes schema-validator exists somewhere) ``` Explicit dependencies enable: - Topological ordering of implementation - Parallel development of independent modules - Clear build/test order - Early detection of circular dependencies ### 3. Topological Order Build foundation layers before higher layers: ``` Phase 0 (Foundation): error-handling, base-types, config ↓ Phase 1 (Data): validation, ingestion (depend on Phase 0) ↓ Phase 2 (Core): algorithms, pipelines (depend on Phase 1) ↓ Phase 3 (API): routes, handlers (depend on Phase 2) ``` Task Master automatically orders tasks based on this dependency chain. ### 4. Progressive Refinement Start broad, refine iteratively: 1. High-level capabilities β†’ Main tasks 2. Features per capability β†’ Subtasks 3. Implementation details β†’ Expanded subtasks --- ## Template Structure The RPG template guides you through 7 key sections: ### 1. Overview - Problem statement - Target users - Success metrics ### 2. Functional Decomposition (WHAT) - High-level capability domains - Features per capability - Inputs/outputs/behavior for each feature **Example:** ``` Capability: Data Management Feature: Schema validation Inputs: JSON object, schema definition Outputs: Validation result + error details Behavior: Iterate fields, check types, enforce constraints ``` ### 3. Structural Decomposition (HOW) - Repository folder structure - Module-to-capability mapping - File organization - Public interfaces/exports **Example:** ``` Capability: Data Management β†’ Maps to: src/data/ β”œβ”€β”€ schema-validator.js (Schema validation feature) β”œβ”€β”€ rule-validator.js (Rule validation feature) └── index.js (Exports) ``` ### 4. Dependency Graph (CRITICAL) - Foundation layer (no dependencies) - Each subsequent layer's dependencies - Explicit "depends on" declarations **Example:** ``` Foundation Layer (Phase 0): - error-handling: No dependencies - base-types: No dependencies Data Layer (Phase 1): - schema-validator: Depends on [base-types, error-handling] - data-ingestion: Depends on [schema-validator] ``` ### 5. Implementation Roadmap - Phases with entry/exit criteria - Tasks grouped by phase - Clear deliverables per phase ### 6. Test Strategy - Test pyramid ratios - Coverage requirements - Critical test scenarios per module - Guidelines for test generation ### 7. Architecture & Risks - Technical architecture - Data models - Technology decisions - Risk mitigation strategies --- ## Using RPG with Task Master ### Step 1: Create PRD with RPG Template Use a code-context-aware tool to fill out the template: ```bash # In Claude Code, Cursor, or similar "Create a PRD using @.taskmaster/templates/example_prd_rpg.txt for [your project]" ``` **Why code context matters:** The AI needs to understand your existing codebase to make informed decisions about: - Module boundaries - Dependency relationships - Integration points - Naming conventions **Recommended tools:** - Claude Code (claude-code CLI) - Cursor/Windsurf - Gemini CLI (large contexts) - Codex/Grok CLI ### Step 2: Parse PRD into Tasks ```bash task-master parse-prd .taskmaster/docs/your-prd.md --research ``` Task Master will: 1. Extract capabilities β†’ Main tasks 2. Extract features β†’ Subtasks 3. Parse dependencies β†’ Task dependencies 4. Order by phases β†’ Task priorities **Result:** A dependency-aware task graph ready for topological execution. ### Step 3: Analyze Complexity ```bash task-master analyze-complexity --research ``` Review the complexity report to identify tasks that need expansion. ### Step 4: Expand Tasks ```bash task-master expand --all --research ``` Break down complex tasks into manageable subtasks while preserving dependency chains. --- ## RPG Benefits ### For Solo Developers - Clear roadmap for implementing complex features - Prevents architectural mistakes early - Explicit dependency tracking avoids integration issues - Enables resuming work after interruptions ### For Teams - Parallel development of independent modules - Clear contracts between modules (explicit dependencies) - Reduced merge conflicts (proper module boundaries) - Onboarding aid (architectural overview in PRD) ### For AI Agents - Structured context for code generation - Clear scope boundaries per task - Dependency awareness prevents incomplete implementations - Test strategy guidance for TDD workflows --- ## RPG vs Standard Template | Aspect | Standard Template | RPG Template | |--------|------------------|--------------| | **Best for** | Simple features | Complex systems | | **Dependency handling** | Implicit | Explicit graph | | **Structure guidance** | Minimal | Step-by-step | | **Examples** | Few | Inline good/bad examples | | **Module boundaries** | Vague | Precise mapping | | **Task ordering** | Manual | Automatic (topological) | | **Learning curve** | Low | Medium | | **Resulting task quality** | Good | Excellent | --- ## Tips for Best Results ### 1. Spend Time on Dependencies The dependency graph section is the most valuable. List all dependencies explicitly, even if they seem obvious. ### 2. Keep Features Atomic Each feature should be independently testable. If a feature description is vague ("handle data"), break it into specific features. ### 3. Progressive Refinement Don't try to get everything perfect on the first pass: 1. Fill out high-level sections 2. Review and refine 3. Add detail where needed 4. Let `task-master expand` break down complex tasks further ### 4. Use Research Mode ```bash task-master parse-prd --research ``` The `--research` flag leverages AI to enhance task generation with domain knowledge. ### 5. Validate Early ```bash task-master validate-dependencies ``` Check for circular dependencies or orphaned modules before starting implementation. --- ## Common Pitfalls ### ❌ Mixing Functional and Structural ``` Bad: "Capability: validation.js" Good: "Capability: Data Validation" β†’ maps to "src/validation/" ``` ### ❌ Vague Module Boundaries ``` Bad: "Module: utils" Good: "Module: string-utilities" with clear exports ``` ### ❌ Implicit Dependencies ``` Bad: "Module: API handlers (needs validation)" Good: "Module: API handlers, Depends on: [validation, error-handling]" ``` ### ❌ Skipping Test Strategy Without test strategy, the AI won't know what to test during implementation. --- ## Example Workflow 1. **Discuss idea with AI**: Explain your project concept 2. **Reference RPG template**: Show AI the `example_prd_rpg.md` 3. **Co-create PRD**: Work through each section with AI guidance 4. **Save to docs**: Place in `.taskmaster/docs/your-project.md` (use `.md` for better editor support) 5. **Parse PRD**: `task-master parse-prd .taskmaster/docs/your-project.md --research` 6. **Analyze**: `task-master analyze-complexity --research` 7. **Expand**: `task-master expand --all --research` 8. **Start work**: `task-master next` --- ## Further Reading - [PRD Creation and Parsing Guide](/getting-started/quick-start/prd-quick) - [Task Structure Documentation](/capabilities/task-structure) - [Microsoft Research RPG Paper](https://arxiv.org/html/2509.16198) (Original methodology) --- <Tip> The RPG template includes inline `` and `<example>` blocks that teach the method as you use it. Read these sections carefully - they provide valuable guidance at each decision point. </Tip> ## 2. Official Technical Reference & Guides (eyaltoledano/docs) # Task Master Documentation Welcome to the Task Master documentation. Use the links below to navigate to the information you need: ## Getting Started - [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 ## Reference - [Command Reference](archive/ccommand-reference.md) - Complete list of all available commands - [Task Structure](archive/ctask-structure.md) - Understanding the task format and features ## Examples & Licensing - [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 [main README](../README.md) or visit our [GitHub repository](https://github.com/eyaltoledano/claude-task-master).