Files

Eyal Toledano 36d559db26 docs: Update documentation for new AI/config architecture and finalize cleanup

This commit updates all relevant documentation (READMEs, docs/*, .cursor/rules) to accurately reflect the finalized unified AI service architecture and the new configuration system (.taskmasterconfig + .env/mcp.json). It also includes the final code cleanup steps related to the refactoring.

Key Changes:

1. **Documentation Updates:**

* Revised `README.md`, `README-task-master.md`, `assets/scripts_README.md`, `docs/configuration.md`, and `docs/tutorial.md` to explain the new configuration split (.taskmasterconfig vs .env/mcp.json).

* Updated MCP configuration examples in READMEs and tutorials to only include API keys in the `env` block.

* Added/updated examples for using the `--research` flag in `docs/command-reference.md`, `docs/examples.md`, and `docs/tutorial.md`.

* Updated `.cursor/rules/ai_services.mdc`, `.cursor/rules/architecture.mdc`, `.cursor/rules/dev_workflow.mdc`, `.cursor/rules/mcp.mdc`, `.cursor/rules/taskmaster.mdc`, `.cursor/rules/utilities.mdc`, and `.cursor/rules/new_features.mdc` to align with the new architecture, removing references to old patterns/files.

* Removed internal rule links from user-facing rules (`taskmaster.mdc`, `dev_workflow.mdc`, `self_improve.mdc`).

* Deleted outdated example file `docs/ai-client-utils-example.md`.

2. **Final Code Refactor & Cleanup:**

* Corrected `update-task-by-id.js` by removing the last import from the old `ai-services.js`.

* Refactored `update-subtask-by-id.js` to correctly use the unified service and logger patterns.

* Removed the obsolete export block from `mcp-server/src/core/task-master-core.js`.

* Corrected logger implementation in `update-tasks.js` for CLI context.

* Updated API key mapping in `config-manager.js` and `ai-services-unified.js`.

3. **Configuration Files:**

* Updated API keys in `.cursor/mcp.json`, replacing `GROK_API_KEY` with `XAI_API_KEY`.

* Updated `.env.example` with current API key names.

* Added `azureOpenaiBaseUrl` to `.taskmasterconfig` example.

4. **Task Management:**

* Marked documentation subtask 61.10 as 'done'.

* Includes various other task content/status updates from the diff summary.

5. **Changeset:**

* Added `.changeset/cuddly-zebras-matter.md` for user-facing `expand`/`expand-all` improvements.

This commit concludes the major architectural refactoring (Task 61) and ensures the documentation accurately reflects the current system.

2025-04-25 14:43:12 -04:00

3.8 KiB

Raw Blame History

Configuration

Taskmaster uses two primary methods for configuration:

.taskmasterconfig File (Project Root - Recommended for most settings)

This JSON file stores most configuration settings, including AI model selections, parameters, logging levels, and project defaults.
Location: Create this file in the root directory of your project.
Management: Use the task-master models --setup command (or models MCP tool) to interactively create and manage this file. Manual editing is possible but not recommended unless you understand the structure.

Example Structure:

{
	"models": {
		"main": {
			"provider": "anthropic",
			"modelId": "claude-3-7-sonnet-20250219",
			"maxTokens": 64000,
			"temperature": 0.2
		},
		"research": {
			"provider": "perplexity",
			"modelId": "sonar-pro",
			"maxTokens": 8700,
			"temperature": 0.1
		},
		"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",
		"azureOpenaiBaseUrl": "https://your-endpoint.openai.azure.com/"
	}
}

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.
  - 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 (in .taskmasterconfig):
  - AZURE_OPENAI_ENDPOINT: Required if using Azure OpenAI key.
  - OLLAMA_BASE_URL: Override the default Ollama API URL (Default: http://localhost:11434/api).

Important: Settings like model ID selections (main, research, fallback), maxTokens, temperature, logLevel, defaultSubtasks, defaultPriority, and projectName are managed in .taskmasterconfig, not environment variables.

Example `.env` File (for API Keys)

# Required API keys for providers configured in .taskmasterconfig
ANTHROPIC_API_KEY=sk-ant-api03-your-key-here
PERPLEXITY_API_KEY=pplx-your-key-here
# OPENAI_API_KEY=sk-your-key-here
# GOOGLE_API_KEY=AIzaSy...
# etc.

# Optional Endpoint Overrides
# AZURE_OPENAI_ENDPOINT=https://your-azure-endpoint.openai.azure.com/
# OLLAMA_BASE_URL=http://custom-ollama-host:11434/api

Troubleshooting

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.

If `task-master init` doesn't respond:

Try running it with Node directly:

node node_modules/claude-task-master/scripts/init.js

Or clone the repository and run:

git clone https://github.com/eyaltoledano/claude-task-master.git
cd claude-task-master
node scripts/init.js

3.8 KiB Raw Blame History