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 # View detailed task information (e.g., task-master show 1.2) @@ -23,7 +24,7 @@ task-master update --from= --prompt="changes" # Update multiple t task-master update-subtask --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 -set_task_status // = task-master set-status +get_tasks; // = task-master list +next_task; // = task-master next +get_task; // = task-master show +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= --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 ` 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 ` to pull specific task context when needed ### Iterative Implementation + 1. `task-master show ` - Understand requirements -2. Explore codebase and plan implementation +2. Explore codebase and plan implementation 3. `task-master update-subtask --id= --prompt="detailed plan"` - Log plan 4. `task-master set-status --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= --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=` to update multiple future tasks - Use `update-task --id=` for single task updates - Use `update-subtask --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.``