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

feat: Add .taskmaster directory (#619)

Browse Source
This commit is contained in:
Ralph Khreish
2025-05-31 16:21:03 +02:00
committed by Eyal Toledano
parent 78397fe0be
commit 518f73eefa
148 changed files with 3523 additions and 7642 deletions
Download Patch File Download Diff File Expand all files Collapse all files

128
docs/configuration.md
View File

@@ -2,73 +2,82 @@
Taskmaster uses two primary methods for configuration:
1. **`.taskmasterconfig` File (Project Root - Recommended for most settings)**
1. **`.taskmaster/config.json` File (Recommended - New Structure)**
- This JSON file stores most configuration settings, including AI model selections, parameters, logging levels, and project defaults.
- **Location:** This file is created in the root directory of your project when you run the `task-master models --setup` interactive setup. You typically do this during the initialization sequence. Do not manually edit this file beyond adjusting Temperature and Max Tokens depending on your model.
- **Location:** This file is created in the `.taskmaster/` directory when you run the `task-master models --setup` interactive setup or initialize a new project with `task-master init`.
- **Migration:** Existing projects with `.taskmasterconfig` in the root will continue to work, but should be migrated to the new structure using `task-master migrate`.
- **Management:** Use the `task-master models --setup` command (or `models` MCP tool) to interactively create and manage this file. You can also set specific models directly using `task-master models --set-<role>=<model_id>`, adding `--ollama` or `--openrouter` flags for custom models. Manual editing is possible but not recommended unless you understand the structure.
- **Example Structure:**
```json
{
"models": {
"main": {
"provider": "anthropic",
"modelId": "claude-3-7-sonnet-20250219",
"maxTokens": 64000,
"temperature": 0.2,
"baseURL": "https://api.anthropic.com/v1"
},
"research": {
"provider": "perplexity",
"modelId": "sonar-pro",
"maxTokens": 8700,
"temperature": 0.1,
"baseURL": "https://api.perplexity.ai/v1"
},
"fallback": {
"provider": "anthropic",
"modelId": "claude-3-5-sonnet",
"maxTokens": 64000,
"temperature": 0.2
}
},
"global": {
"logLevel": "info",
"debug": false,
"defaultSubtasks": 5,
"defaultPriority": "medium",
"projectName": "Your Project Name",
"ollamaBaseURL": "http://localhost:11434/api",
"azureBaseURL": "https://your-endpoint.azure.com/",
"vertexProjectId": "your-gcp-project-id",
"vertexLocation": "us-central1"
}
"models": {
"main": {
"provider": "anthropic",
"modelId": "claude-3-7-sonnet-20250219",
"maxTokens": 64000,
"temperature": 0.2,
"baseURL": "https://api.anthropic.com/v1"
},
"research": {
"provider": "perplexity",
"modelId": "sonar-pro",
"maxTokens": 8700,
"temperature": 0.1,
"baseURL": "https://api.perplexity.ai/v1"
},
"fallback": {
"provider": "anthropic",
"modelId": "claude-3-5-sonnet",
"maxTokens": 64000,
"temperature": 0.2
}
},
"global": {
"logLevel": "info",
"debug": false,
"defaultSubtasks": 5,
"defaultPriority": "medium",
"projectName": "Your Project Name",
"ollamaBaseURL": "http://localhost:11434/api",
"azureBaseURL": "https://your-endpoint.azure.com/",
"vertexProjectId": "your-gcp-project-id",
"vertexLocation": "us-central1"
}
}
```
2. **Environment Variables (`.env` file or MCP `env` block - For API Keys Only)**
- Used **exclusively** for sensitive API keys and specific endpoint URLs.
- **Location:**
- For CLI usage: Create a `.env` file in your project root.
- For MCP/Cursor usage: Configure keys in the `env` section of your `.cursor/mcp.json` file.
- **Required API Keys (Depending on configured providers):**
- `ANTHROPIC_API_KEY`: Your Anthropic API key.
- `PERPLEXITY_API_KEY`: Your Perplexity API key.
- `OPENAI_API_KEY`: Your OpenAI API key.
- `GOOGLE_API_KEY`: Your Google API key (also used for Vertex AI provider).
- `MISTRAL_API_KEY`: Your Mistral API key.
- `AZURE_OPENAI_API_KEY`: Your Azure OpenAI API key (also requires `AZURE_OPENAI_ENDPOINT`).
- `OPENROUTER_API_KEY`: Your OpenRouter API key.
- `XAI_API_KEY`: Your X-AI API key.
- **Optional Endpoint Overrides:**
- **Per-role `baseURL` in `.taskmasterconfig`:** You can add a `baseURL` property to any model role (`main`, `research`, `fallback`) to override the default API endpoint for that provider. If omitted, the provider's standard endpoint is used.
- `AZURE_OPENAI_ENDPOINT`: Required if using Azure OpenAI key (can also be set as `baseURL` for the Azure model role).
- `OLLAMA_BASE_URL`: Override the default Ollama API URL (Default: `http://localhost:11434/api`).
- `VERTEX_PROJECT_ID`: Your Google Cloud project ID for Vertex AI. Required when using the 'vertex' provider.
- `VERTEX_LOCATION`: Google Cloud region for Vertex AI (e.g., 'us-central1'). Default is 'us-central1'.
- `GOOGLE_APPLICATION_CREDENTIALS`: Path to service account credentials JSON file for Google Cloud auth (alternative to API key for Vertex AI).
2. **Legacy `.taskmasterconfig` File (Backward Compatibility)**
**Important:** Settings like model ID selections (`main`, `research`, `fallback`), `maxTokens`, `temperature`, `logLevel`, `defaultSubtasks`, `defaultPriority`, and `projectName` are **managed in `.taskmasterconfig`**, not environment variables.
- For projects that haven't migrated to the new structure yet.
- **Location:** Project root directory.
- **Migration:** Use `task-master migrate` to move this to `.taskmaster/config.json`.
- **Deprecation:** While still supported, you'll see warnings encouraging migration to the new structure.
## Environment Variables (`.env` file or MCP `env` block - For API Keys Only)
- Used **exclusively** for sensitive API keys and specific endpoint URLs.
- **Location:**
- For CLI usage: Create a `.env` file in your project root.
- For MCP/Cursor usage: Configure keys in the `env` section of your `.cursor/mcp.json` file.
- **Required API Keys (Depending on configured providers):**
- `ANTHROPIC_API_KEY`: Your Anthropic API key.
- `PERPLEXITY_API_KEY`: Your Perplexity API key.
- `OPENAI_API_KEY`: Your OpenAI API key.
- `GOOGLE_API_KEY`: Your Google API key (also used for Vertex AI provider).
- `MISTRAL_API_KEY`: Your Mistral API key.
- `AZURE_OPENAI_API_KEY`: Your Azure OpenAI API key (also requires `AZURE_OPENAI_ENDPOINT`).
- `OPENROUTER_API_KEY`: Your OpenRouter API key.
- `XAI_API_KEY`: Your X-AI API key.
- **Optional Endpoint Overrides:**
- **Per-role `baseURL` in `.taskmasterconfig`:** You can add a `baseURL` property to any model role (`main`, `research`, `fallback`) to override the default API endpoint for that provider. If omitted, the provider's standard endpoint is used.
- `AZURE_OPENAI_ENDPOINT`: Required if using Azure OpenAI key (can also be set as `baseURL` for the Azure model role).
- `OLLAMA_BASE_URL`: Override the default Ollama API URL (Default: `http://localhost:11434/api`).
- `VERTEX_PROJECT_ID`: Your Google Cloud project ID for Vertex AI. Required when using the 'vertex' provider.
- `VERTEX_LOCATION`: Google Cloud region for Vertex AI (e.g., 'us-central1'). Default is 'us-central1'.
- `GOOGLE_APPLICATION_CREDENTIALS`: Path to service account credentials JSON file for Google Cloud auth (alternative to API key for Vertex AI).
**Important:** Settings like model ID selections (`main`, `research`, `fallback`), `maxTokens`, `temperature`, `logLevel`, `defaultSubtasks`, `defaultPriority`, and `projectName` are **managed in `.taskmaster/config.json`** (or `.taskmasterconfig` for unmigrated projects), not environment variables.
## Example `.env` File (for API Keys)
@@ -94,8 +103,9 @@ PERPLEXITY_API_KEY=pplx-your-key-here
### Configuration Errors
- If Task Master reports errors about missing configuration or cannot find `.taskmasterconfig`, run `task-master models --setup` in your project root to create or repair the file.
- Ensure API keys are correctly placed in your `.env` file (for CLI) or `.cursor/mcp.json` (for MCP) and are valid for the providers selected in `.taskmasterconfig`.
- If Task Master reports errors about missing configuration or cannot find the config file, run `task-master models --setup` in your project root to create or repair the file.
- For new projects, config will be created at `.taskmaster/config.json`. For legacy projects, you may want to use `task-master migrate` to move to the new structure.
- Ensure API keys are correctly placed in your `.env` file (for CLI) or `.cursor/mcp.json` (for MCP) and are valid for the providers selected in your config file.
### If `task-master init` doesn't respond:

2
docs/examples.md
View File

@@ -5,7 +5,7 @@ Here are some common interactions with Cursor AI when using Task Master:
## Starting a new project
```
I've just initialized a new project with Claude Task Master. I have a PRD at scripts/prd.txt.
I've just initialized a new project with Claude Task Master. I have a PRD at .taskmaster/docs/prd.txt.
Can you help me parse it and set up the initial tasks?
```

235
docs/migration-guide.md Normal file
View File

@@ -0,0 +1,235 @@
# Migration Guide: New .taskmaster Directory Structure
## Overview
Task Master v3.x introduces a new `.taskmaster/` directory structure to keep your project directories clean and organized. This guide explains the benefits of the new structure and how to migrate existing projects.
## What's New
### Before (Legacy Structure)
```
your-project/
├── tasks/ # Task files
│ ├── tasks.json
│ ├── task-1.md
│ └── task-2.md
├── scripts/ # PRD and reports
│ ├── prd.txt
│ ├── example_prd.txt
│ └── task-complexity-report.json
├── .taskmasterconfig # Configuration
└── ... (your project files)
```
### After (New Structure)
```
your-project/
├── .taskmaster/ # Consolidated Task Master files
│ ├── config.json # Configuration (was .taskmasterconfig)
│ ├── tasks/ # Task files
│ │ ├── tasks.json
│ │ ├── task-1.md
│ │ └── task-2.md
│ ├── docs/ # Project documentation
│ │ └── prd.txt
│ ├── reports/ # Generated reports
│ │ └── task-complexity-report.json
│ └── templates/ # Example/template files
│ └── example_prd.txt
└── ... (your project files)
```
## Benefits of the New Structure
✅ **Cleaner Project Root**: No more scattered Task Master files
✅ **Better Organization**: Logical separation of tasks, docs, reports, and templates
✅ **Hidden by Default**: `.taskmaster/` directory is hidden from most file browsers
✅ **Future-Proof**: Centralized location for Task Master extensions
✅ **Backward Compatible**: Existing projects continue to work until migrated
## Migration Options
### Option 1: Automatic Migration (Recommended)
Task Master provides a built-in migration command that handles everything automatically:
#### CLI Migration
```bash
# Dry run to see what would be migrated
task-master migrate --dry-run
# Perform the migration with backup
task-master migrate --backup
# Force migration (overwrites existing files)
task-master migrate --force
# Clean up legacy files after migration
task-master migrate --cleanup
```
#### MCP Migration (Cursor/AI Editors)
Ask your AI assistant:
```
Please migrate my Task Master project to the new .taskmaster directory structure
```
### Option 2: Manual Migration
If you prefer to migrate manually:
1. **Create the new directory structure:**
```bash
mkdir -p .taskmaster/{tasks,docs,reports,templates}
```
2. **Move your files:**
```bash
# Move tasks
mv tasks/* .taskmaster/tasks/
# Move configuration
mv .taskmasterconfig .taskmaster/config.json
# Move PRD and documentation
mv scripts/prd.txt .taskmaster/docs/
mv scripts/example_prd.txt .taskmaster/templates/
# Move reports (if they exist)
mv scripts/task-complexity-report.json .taskmaster/reports/ 2>/dev/null || true
```
3. **Clean up empty directories:**
```bash
rmdir tasks scripts 2>/dev/null || true
```
## What Gets Migrated
The migration process handles these file types:
### Tasks Directory → `.taskmaster/tasks/`
- `tasks.json`
- Individual task Markdown files (`.md`)
### Scripts Directory → Multiple Destinations
- **PRD files** → `.taskmaster/docs/`
- `prd.txt`, `requirements.txt`, etc.
- **Example/Template files** → `.taskmaster/templates/`
- `example_prd.txt`, template files
- **Reports** → `.taskmaster/reports/`
- `task-complexity-report.json`
### Configuration
- `.taskmasterconfig` → `.taskmaster/config.json`
## After Migration
Once migrated, Task Master will:
✅ **Automatically use** the new directory structure
✅ **Show deprecation warnings** when legacy files are detected
✅ **Create new files** in the proper locations
✅ **Fall back gracefully** to legacy locations if new ones don't exist
### Verification
After migration, verify everything works:
1. **List your tasks:**
```bash
task-master list
```
2. **Check your configuration:**
```bash
task-master models
```
3. **Generate new task files:**
```bash
task-master generate
```
## Troubleshooting
### Migration Issues
**Q: Migration says "no files to migrate"**
A: Your project may already be using the new structure or have no Task Master files to migrate.
**Q: Migration fails with permission errors**
A: Ensure you have write permissions in your project directory.
**Q: Some files weren't migrated**
A: Check the migration output - some files may not match the expected patterns. You can migrate these manually.
### Working with Legacy Projects
If you're working with an older project that hasn't been migrated:
- Task Master will continue to work with the old structure
- You'll see deprecation warnings in the output
- New files will still be created in legacy locations
- Use the migration command when ready to upgrade
### New Project Initialization
New projects automatically use the new structure:
```bash
task-master init # Creates .taskmaster/ structure
```
## Path Changes for Developers
If you're developing tools or scripts that interact with Task Master files:
### Configuration File
- **Old:** `.taskmasterconfig`
- **New:** `.taskmaster/config.json`
- **Fallback:** Task Master checks both locations
### Tasks File
- **Old:** `tasks/tasks.json`
- **New:** `.taskmaster/tasks/tasks.json`
- **Fallback:** Task Master checks both locations
### Reports
- **Old:** `scripts/task-complexity-report.json`
- **New:** `.taskmaster/reports/task-complexity-report.json`
- **Fallback:** Task Master checks both locations
### PRD Files
- **Old:** `scripts/prd.txt`
- **New:** `.taskmaster/docs/prd.txt`
- **Fallback:** Task Master checks both locations
## Need Help?
If you encounter issues during migration:
1. **Check the logs:** Add `--debug` flag for detailed output
2. **Backup first:** Always use `--backup` option for safety
3. **Test with dry-run:** Use `--dry-run` to preview changes
4. **Ask for help:** Use our Discord community or GitHub issues
---
_This migration guide applies to Task Master v3.x and later. For older versions, please upgrade to the latest version first._

44
docs/tutorial.md
View File

@@ -20,22 +20,22 @@ npm i -g task-master-ai
```json
{
"mcpServers": {
"taskmaster-ai": {
"command": "npx",
"args": ["-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"
}
}
}
"mcpServers": {
"taskmaster-ai": {
"command": "npx",
"args": ["-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"
}
}
}
}
```
@@ -60,12 +60,12 @@ The AI will:
- Set up initial configuration files
- Guide you through the rest of the process
5. Place your PRD document in the `scripts/` directory (e.g., `scripts/prd.txt`)
5. Place your PRD document in the `.taskmaster/docs/` directory (e.g., `.taskmaster/docs/prd.txt`)
6. **Use natural language commands** to interact with Task Master:
```
Can you parse my PRD at scripts/prd.txt?
Can you parse my PRD at .taskmaster/docs/prd.txt?
What's the next task I should work on?
Can you help me implement task 3?
```
@@ -132,7 +132,7 @@ If you're not using MCP, you can still set up Cursor integration:
1. After initializing your project, open it in Cursor
2. The `.cursor/rules/dev_workflow.mdc` file is automatically loaded by Cursor, providing the AI with knowledge about the task management system
3. Place your PRD document in the `scripts/` directory (e.g., `scripts/prd.txt`)
3. Place your PRD document in the `.taskmaster/docs/` directory (e.g., `.taskmaster/docs/prd.txt`)
4. Open Cursor's AI chat and switch to Agent mode
### Alternative MCP Setup in Cursor
@@ -155,13 +155,13 @@ Once configured, you can interact with Task Master's task management commands di
In Cursor's AI chat, instruct the agent to generate tasks from your PRD:
```
Please use the task-master parse-prd command to generate tasks from my PRD. The PRD is located at scripts/prd.txt.
Please use the task-master parse-prd command to generate tasks from my PRD. The PRD is located at .taskmaster/docs/prd.txt.
```
The agent will execute:
```bash
task-master parse-prd scripts/prd.txt
task-master parse-prd .taskmaster/docs/prd.txt
```
This will:
@@ -397,7 +397,7 @@ task-master expand --id=5 --research
### Starting a new project
```
I've just initialized a new project with Claude Task Master. I have a PRD at scripts/prd.txt.
I've just initialized a new project with Claude Task Master. I have a PRD at .taskmaster/docs/prd.txt.
Can you help me parse it and set up the initial tasks?
```