Skip to content

An AI-powered task-management system you can drop into Cursor, Lovable, Windsurf, Roo, and others.

chore: formatting

Eyal Toledano43ad75c7fa31
diff --git a/assets/AGENTS.md b/assets/AGENTS.md
index 517cccca..d7cfbfa1 100644
--- a/assets/AGENTS.md
+++ b/assets/AGENTS.md
@@ -3,13 +3,14 @@
## Essential Commands
### Core Workflow Commands
+
```bash
# Project Setup
task-master init # Initialize Task Master in current project
task-master parse-prd scripts/prd.txt # Generate tasks from PRD document
task-master models --setup # Configure AI models interactively
-# Daily Development Workflow
+# Daily Development Workflow
task-master list # Show all tasks with status
task-master next # Get next available task to work on
task-master show <id> # View detailed task information (e.g., task-master show 1.2)
@@ -23,7 +24,7 @@ task-master update --from=<id> --prompt="changes" # Update multiple t
task-master update-subtask --id=<id> --prompt="notes" # Add implementation notes to subtask
# Analysis & Planning
-task-master analyze-complexity --research # Analyze task complexity
+task-master analyze-complexity --research # Analyze task complexity
task-master complexity-report # View complexity analysis
task-master expand --all --research # Expand all eligible tasks
@@ -37,6 +38,7 @@ task-master generate # Update task markd
## Key Files & Project Structure
### Core Files
+
- `tasks/tasks.json` - Main task data file (auto-managed)
- `.taskmasterconfig` - AI model configuration (use `task-master models` to modify)
- `scripts/prd.txt` - Product Requirements Document for parsing
@@ -44,12 +46,14 @@ task-master generate # Update task markd
- `.env` - API keys for CLI usage
### Claude Code Integration Files
+
- `CLAUDE.md` - Auto-loaded context for Claude Code (this file)
- `.claude/settings.json` - Claude Code tool allowlist and preferences
- `.claude/commands/` - Custom slash commands for repeated workflows
- `.mcp.json` - MCP server configuration (project-specific)
### Directory Structure
+
```
project/
├── tasks/
@@ -74,49 +78,50 @@ Task Master provides an MCP server that Claude Code can connect to. Configure in
```json
{
- "mcpServers": {
- "task-master-ai": {
- "command": "npx",
- "args": ["-y", "--package=task-master-ai", "task-master-ai"],
- "env": {
- "ANTHROPIC_API_KEY": "your_key_here",
- "PERPLEXITY_API_KEY": "your_key_here",
- "OPENAI_API_KEY": "OPENAI_API_KEY_HERE",
- "GOOGLE_API_KEY": "GOOGLE_API_KEY_HERE",
- "XAI_API_KEY": "XAI_API_KEY_HERE",
- "OPENROUTER_API_KEY": "OPENROUTER_API_KEY_HERE",
- "MISTRAL_API_KEY": "MISTRAL_API_KEY_HERE",
- "AZURE_OPENAI_API_KEY": "AZURE_OPENAI_API_KEY_HERE",
- "OLLAMA_API_KEY": "OLLAMA_API_KEY_HERE"
- }
- }
- }
+ "mcpServers": {
+ "task-master-ai": {
+ "command": "npx",
+ "args": ["-y", "--package=task-master-ai", "task-master-ai"],
+ "env": {
+ "ANTHROPIC_API_KEY": "your_key_here",
+ "PERPLEXITY_API_KEY": "your_key_here",
+ "OPENAI_API_KEY": "OPENAI_API_KEY_HERE",
+ "GOOGLE_API_KEY": "GOOGLE_API_KEY_HERE",
+ "XAI_API_KEY": "XAI_API_KEY_HERE",
+ "OPENROUTER_API_KEY": "OPENROUTER_API_KEY_HERE",
+ "MISTRAL_API_KEY": "MISTRAL_API_KEY_HERE",
+ "AZURE_OPENAI_API_KEY": "AZURE_OPENAI_API_KEY_HERE",
+ "OLLAMA_API_KEY": "OLLAMA_API_KEY_HERE"
+ }
+ }
+ }
}
```
### Essential MCP Tools
+
```javascript
-help // = shows available taskmaster commands
+help; // = shows available taskmaster commands
// Project setup
-initialize_project // = task-master init
-parse_prd // = task-master parse-prd
+initialize_project; // = task-master init
+parse_prd; // = task-master parse-prd
// Daily workflow
-get_tasks // = task-master list
-next_task // = task-master next
-get_task // = task-master show <id>
-set_task_status // = task-master set-status
+get_tasks; // = task-master list
+next_task; // = task-master next
+get_task; // = task-master show <id>
+set_task_status; // = task-master set-status
// Task management
-add_task // = task-master add-task
-expand_task // = task-master expand
-update_task // = task-master update-task
-update_subtask // = task-master update-subtask
-update // = task-master update
+add_task; // = task-master add-task
+expand_task; // = task-master expand
+update_task; // = task-master update-task
+update_subtask; // = task-master update-subtask
+update; // = task-master update
// Analysis
-analyze_project_complexity // = task-master analyze-complexity
-complexity_report // = task-master complexity-report
+analyze_project_complexity; // = task-master analyze-complexity
+complexity_report; // = task-master complexity-report
```
## Claude Code Workflow Integration
@@ -124,6 +129,7 @@ complexity_report // = task-master complexity-report
### Standard Development Workflow
#### 1. Project Initialization
+
```bash
# Initialize Task Master
task-master init
@@ -139,6 +145,7 @@ task-master expand --all --research
If tasks already exist, another PRD can be parsed (with new information only!) using parse-prd with --append flag. This will add the generated tasks to the existing list of tasks..
#### 2. Daily Development Loop
+
```bash
# Start each session
task-master next # Find next available task
@@ -152,13 +159,14 @@ task-master set-status --id=<id> --status=done
```
#### 3. Multi-Claude Workflows
+
For complex projects, use multiple Claude Code sessions:
```bash
# Terminal 1: Main implementation
cd project && claude
-# Terminal 2: Testing and validation
+# Terminal 2: Testing and validation
cd project-test-worktree && claude
# Terminal 3: Documentation updates
@@ -168,10 +176,12 @@ cd project-docs-worktree && claude
### Custom Slash Commands
Create `.claude/commands/taskmaster-next.md`:
+
```markdown
Find the next available Task Master task and show its details.
Steps:
+
1. Run `task-master next` to get the next task
2. If a task is available, run `task-master show <id>` for full details
3. Provide a summary of what needs to be implemented
@@ -179,10 +189,12 @@ Steps:
```
Create `.claude/commands/taskmaster-complete.md`:
+
```markdown
Complete a Task Master task: $ARGUMENTS
Steps:
+
1. Review the current task with `task-master show $ARGUMENTS`
2. Verify all implementation is complete
3. Run any tests related to this task
@@ -193,25 +205,28 @@ Steps:
## Tool Allowlist Recommendations
Add to `.claude/settings.json`:
+
```json
{
- "allowedTools": [
- "Edit",
- "Bash(task-master *)",
- "Bash(git commit:*)",
- "Bash(git add:*)",
- "Bash(npm run *)",
- "mcp__task_master_ai__*"
- ]
+ "allowedTools": [
+ "Edit",
+ "Bash(task-master *)",
+ "Bash(git commit:*)",
+ "Bash(git add:*)",
+ "Bash(npm run *)",
+ "mcp__task_master_ai__*"
+ ]
}
```
## Configuration & Setup
### API Keys Required
+
At least **one** of these API keys must be configured:
+
- `ANTHROPIC_API_KEY` (Claude models) - **Recommended**
-- `PERPLEXITY_API_KEY` (Research features) - **Highly recommended**
+- `PERPLEXITY_API_KEY` (Research features) - **Highly recommended**
- `OPENAI_API_KEY` (GPT models)
- `GOOGLE_API_KEY` (Gemini models)
- `MISTRAL_API_KEY` (Mistral models)
@@ -221,6 +236,7 @@ At least **one** of these API keys must be configured:
An API key is required for any provider used across any of the 3 roles defined in the `models` command.
### Model Configuration
+
```bash
# Interactive setup (recommended)
task-master models --setup
@@ -234,43 +250,48 @@ task-master models --set-fallback gpt-4o-mini
## Task Structure & IDs
### Task ID Format
+
- Main tasks: `1`, `2`, `3`, etc.
- Subtasks: `1.1`, `1.2`, `2.1`, etc.
- Sub-subtasks: `1.1.1`, `1.1.2`, etc.
### Task Status Values
+
- `pending` - Ready to work on
-- `in-progress` - Currently being worked on
+- `in-progress` - Currently being worked on
- `done` - Completed and verified
- `deferred` - Postponed
- `cancelled` - No longer needed
- `blocked` - Waiting on external factors
### Task Fields
+
```json
{
- "id": "1.2",
- "title": "Implement user authentication",
- "description": "Set up JWT-based auth system",
- "status": "pending",
- "priority": "high",
- "dependencies": ["1.1"],
- "details": "Use bcrypt for hashing, JWT for tokens...",
- "testStrategy": "Unit tests for auth functions, integration tests for login flow",
- "subtasks": []
+ "id": "1.2",
+ "title": "Implement user authentication",
+ "description": "Set up JWT-based auth system",
+ "status": "pending",
+ "priority": "high",
+ "dependencies": ["1.1"],
+ "details": "Use bcrypt for hashing, JWT for tokens...",
+ "testStrategy": "Unit tests for auth functions, integration tests for login flow",
+ "subtasks": []
}
```
## Claude Code Best Practices with Task Master
### Context Management
+
- Use `/clear` between different tasks to maintain focus
- This CLAUDE.md file is automatically loaded for context
- Use `task-master show <id>` to pull specific task context when needed
### Iterative Implementation
+
1. `task-master show <subtask-id>` - Understand requirements
-2. Explore codebase and plan implementation
+2. Explore codebase and plan implementation
3. `task-master update-subtask --id=<id> --prompt="detailed plan"` - Log plan
4. `task-master set-status --id=<id> --status=in-progress` - Start work
5. Implement code following logged plan
@@ -278,16 +299,19 @@ task-master models --set-fallback gpt-4o-mini
7. `task-master set-status --id=<id> --status=done` - Complete task
### Complex Workflows with Checklists
+
For large migrations or multi-step processes:
1. Create a markdown PRD file describing the new changes: `touch task-migration-checklist.md` (prds can be .txt or .md)
2. Use Taskmaster to parse the new prd with `task-master parse-prd --append` (also available in MCP)
-3. Use Taskmaster to expand the newly generated tasks into subtasks. Consdier using `analyze-complexity` with the correct --to and --from IDs (the new ids) to identify the ideal subtask amounts for each task. Then expand them.
-4. Work through items systematically, checking them off as completed
+3. Use Taskmaster to expand the newly generated tasks into subtasks. Consdier using `analyze-complexity` with the correct --to and --from IDs (the new ids) to identify the ideal subtask amounts for each task. Then expand them.
+4. Work through items systematically, checking them off as completed
5. Use `task-master update-subtask` to log progress on each task/subtask and/or updating/researching them before/during implementation if getting stuck
### Git Integration
+
Task Master works well with `gh` CLI:
+
```bash
# Create PR for completed task
gh pr create --title "Complete task 1.2: User authentication" --body "Implements JWT auth system as specified in task 1.2"
@@ -297,6 +321,7 @@ git commit -m "feat: implement JWT auth (task 1.2)"
```
### Parallel Development with Git Worktrees
+
```bash
# Create worktrees for parallel task development
git worktree add ../project-auth feature/auth-system
@@ -310,11 +335,12 @@ cd ../project-api && claude # Terminal 2: API work
## Troubleshooting
### AI Commands Failing
+
```bash
# Check API keys are configured
cat .env # For CLI usage
-# Verify model configuration
+# Verify model configuration
task-master models
# Test with different model
@@ -322,12 +348,14 @@ task-master models --set-fallback gpt-4o-mini
```
### MCP Connection Issues
+
- Check `.mcp.json` configuration
- Verify Node.js installation
- Use `--mcp-debug` flag when starting Claude Code
- Use CLI as fallback if MCP unavailable
### Task File Sync Issues
+
```bash
# Regenerate task files from tasks.json
task-master generate
@@ -341,9 +369,11 @@ DO NOT RE-INITIALIZE. That will not do anything beyond re-adding the same Taskma
## Important Notes
### AI-Powered Operations
+
These commands make AI calls and may take up to a minute:
+
- `parse_prd` / `task-master parse-prd`
-- `analyze_project_complexity` / `task-master analyze-complexity`
+- `analyze_project_complexity` / `task-master analyze-complexity`
- `expand_task` / `task-master expand`
- `expand_all` / `task-master expand --all`
- `add_task` / `task-master add-task`
@@ -352,23 +382,27 @@ These commands make AI calls and may take up to a minute:
- `update_subtask` / `task-master update-subtask`
### File Management
+
- Never manually edit `tasks.json` - use commands instead
-- Never manually edit `.taskmasterconfig` - use `task-master models`
+- Never manually edit `.taskmasterconfig` - use `task-master models`
- Task markdown files in `tasks/` are auto-generated
- Run `task-master generate` after manual changes to tasks.json
### Claude Code Session Management
+
- Use `/clear` frequently to maintain focused context
- Create custom slash commands for repeated Task Master workflows
- Configure tool allowlist to streamline permissions
- Use headless mode for automation: `claude -p "task-master next"`
### Multi-Task Updates
+
- Use `update --from=<id>` to update multiple future tasks
- Use `update-task --id=<id>` for single task updates
- Use `update-subtask --id=<id>` for implementation logging
### Research Mode
+
- Add `--research` flag for research-based AI enhancement
- Requires a research model API key like Perplexity (`PERPLEXITY_API_KEY`) in environment
- Provides more informed task creation and updates
@@ -376,4 +410,4 @@ These commands make AI calls and may take up to a minute:
---
-*This guide ensures Claude Code has immediate access to Task Master's essential functionality for agentic development workflows.*
+_This guide ensures Claude Code has immediate access to Task Master's essential functionality for agentic development workflows._
diff --git a/llms-install.md b/llms-install.md
index 3952989e..8b2a4bbb 100644
--- a/llms-install.md
+++ b/llms-install.md
@@ -14,27 +14,28 @@ Add the following configuration to the user's MCP settings file (`.cursor/mcp.js
```json
{
- "mcpServers": {
- "taskmaster-ai": {
- "command": "npx",
- "args": ["-y", "--package=task-master-ai", "task-master-ai"],
- "env": {
- "ANTHROPIC_API_KEY": "user_will_add_their_key_here",
- "PERPLEXITY_API_KEY": "user_will_add_their_key_here",
- "OPENAI_API_KEY": "user_will_add_their_key_here",
- "GOOGLE_API_KEY": "user_will_add_their_key_here",
- "MISTRAL_API_KEY": "user_will_add_their_key_here",
- "OPENROUTER_API_KEY": "user_will_add_their_key_here",
- "XAI_API_KEY": "user_will_add_their_key_here"
- }
- }
- }
+ "mcpServers": {
+ "taskmaster-ai": {
+ "command": "npx",
+ "args": ["-y", "--package=task-master-ai", "task-master-ai"],
+ "env": {
+ "ANTHROPIC_API_KEY": "user_will_add_their_key_here",
+ "PERPLEXITY_API_KEY": "user_will_add_their_key_here",
+ "OPENAI_API_KEY": "user_will_add_their_key_here",
+ "GOOGLE_API_KEY": "user_will_add_their_key_here",
+ "MISTRAL_API_KEY": "user_will_add_their_key_here",
+ "OPENROUTER_API_KEY": "user_will_add_their_key_here",
+ "XAI_API_KEY": "user_will_add_their_key_here"
+ }
+ }
+ }
}
```
### Step 2: API Key Requirements
Inform the user they need **at least one** API key from the following providers:
+
- **Anthropic** (for Claude models) - Recommended
- **OpenAI** (for GPT models)
- **Google** (for Gemini models)
@@ -88,7 +89,6 @@ If the user does not have a PRD, the AI agent can help them create one and store
> Can you move task [ID] to become a subtask of [parent ID]?
> Can you update task [ID] with this new information: [details]
-
## Verification Steps
After installation, verify everything is working:
@@ -104,25 +104,28 @@ When adding keys to `.env` only, the `models` tool will explain that the keys ar
## Troubleshooting
**If MCP server doesn't start:**
+
- Verify the JSON configuration is valid
- Check that Node.js is installed
- Ensure API keys are properly formatted
**If AI commands fail:**
+
- Verify at least one API key is configured
- Check API key permissions and quotas
- Try using a different model via the `models` tool
## CLI Fallback
-Taskmaster is also available via CLI commands, by installing with `npm install task-master-ai@latest` in a terminal. Running `task-master help` will show all available commands, which offer a 1:1 experience with the MCP server. As the AI agent, you should refer to the system prompts and rules provided to you to identify Taskmaster-specific rules that help you understand how and when to use it.
+Taskmaster is also available via CLI commands, by installing with `npm install task-master-ai@latest` in a terminal. Running `task-master help` will show all available commands, which offer a 1:1 experience with the MCP server. As the AI agent, you should refer to the system prompts and rules provided to you to identify Taskmaster-specific rules that help you understand how and when to use it.
## Next Steps
Once installed, users can:
+
- Create new tasks with `add-task` or parse a PRD (scripts/prd.txt) into tasks with `parse-prd`
- Set up model preferences with `models` tool
- Expand tasks into subtasks with `expand-all` and `expand-task`
- Explore advanced features like research mode and complexity analysis
-For detailed documentation, refer to the Task Master docs directory.``
\ No newline at end of file
+For detailed documentation, refer to the Task Master docs directory.``