docs: Update documentation and rules for tagged task lists system
- Updated task-structure.md with comprehensive tagged format explanation - Updated all .cursor/rules/*.mdc files to reflect tagged system - Completed subtask 103.16: Update Documentation for Tagged Task Lists System
This commit is contained in:
Eyal Toledano
@@ -232,4 +232,4 @@ If you encounter issues during migration:
|
||||
|
||||
---
|
||||
|
||||
_This migration guide applies to Task Master v3.x and later. For older versions, please upgrade to the latest version first._
|
||||
_This migration guide applies to Task Master v0.15.x and later. For older versions, please upgrade to the latest version first._
|
||||
|
||||
@@ -137,3 +137,290 @@ The `show` command:
|
||||
8. **Communicate context to the agent**: When asking the Cursor agent to help with a task, provide context about what you're trying to achieve.
|
||||
|
||||
9. **Validate dependencies**: Periodically run the validate-dependencies command to check for invalid or circular dependencies.
|
||||
|
||||
# Task Structure Documentation
|
||||
|
||||
Task Master uses a structured JSON format to organize and manage tasks. As of version 0.16.2, Task Master introduces **Tagged Task Lists** for multi-context task management while maintaining full backward compatibility.
|
||||
|
||||
## Tagged Task Lists System
|
||||
|
||||
Task Master now organizes tasks into separate contexts called **tags**. This enables working across multiple contexts such as different branches, environments, or project phases without conflicts.
|
||||
|
||||
### Data Structure Overview
|
||||
|
||||
**Tagged Format (Current)**:
|
||||
|
||||
```json
|
||||
{
|
||||
"master": {
|
||||
"tasks": [
|
||||
{ "id": 1, "title": "Setup API", "status": "pending", ... }
|
||||
]
|
||||
},
|
||||
"feature-branch": {
|
||||
"tasks": [
|
||||
{ "id": 1, "title": "New Feature", "status": "pending", ... }
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Legacy Format (Automatically Migrated)**:
|
||||
|
||||
```json
|
||||
{
|
||||
"tasks": [
|
||||
{ "id": 1, "title": "Setup API", "status": "pending", ... }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Tag-based Task Lists (v0.17+) and Compatibility
|
||||
|
||||
- **Seamless Migration**: Existing `tasks.json` files are automatically migrated to use a "master" tag
|
||||
- **Zero Disruption**: All existing commands continue to work exactly as before
|
||||
- **Backward Compatibility**: Existing workflows remain unchanged
|
||||
- **Silent Process**: Migration happens transparently on first use with a friendly notification
|
||||
|
||||
## Core Task Properties
|
||||
|
||||
Each task within a tag context contains the following properties:
|
||||
|
||||
### Required Properties
|
||||
|
||||
- **`id`** (number): Unique identifier within the tag context
|
||||
|
||||
```json
|
||||
"id": 1
|
||||
```
|
||||
|
||||
- **`title`** (string): Brief, descriptive title
|
||||
|
||||
```json
|
||||
"title": "Implement user authentication"
|
||||
```
|
||||
|
||||
- **`description`** (string): Concise summary of what the task involves
|
||||
|
||||
```json
|
||||
"description": "Create a secure authentication system using JWT tokens"
|
||||
```
|
||||
|
||||
- **`status`** (string): Current state of the task
|
||||
- Valid values: `"pending"`, `"in-progress"`, `"done"`, `"review"`, `"deferred"`, `"cancelled"`
|
||||
```json
|
||||
"status": "pending"
|
||||
```
|
||||
|
||||
### Optional Properties
|
||||
|
||||
- **`dependencies`** (array): IDs of prerequisite tasks that must be completed first
|
||||
|
||||
```json
|
||||
"dependencies": [2, 3]
|
||||
```
|
||||
|
||||
- **`priority`** (string): Importance level
|
||||
|
||||
- Valid values: `"high"`, `"medium"`, `"low"`
|
||||
- Default: `"medium"`
|
||||
|
||||
```json
|
||||
"priority": "high"
|
||||
```
|
||||
|
||||
- **`details`** (string): In-depth implementation instructions
|
||||
|
||||
```json
|
||||
"details": "Use GitHub OAuth client ID/secret, handle callback, set session token"
|
||||
```
|
||||
|
||||
- **`testStrategy`** (string): Verification approach
|
||||
|
||||
```json
|
||||
"testStrategy": "Deploy and call endpoint to confirm authentication flow"
|
||||
```
|
||||
|
||||
- **`subtasks`** (array): List of smaller, more specific tasks
|
||||
```json
|
||||
"subtasks": [
|
||||
{
|
||||
"id": 1,
|
||||
"title": "Configure OAuth",
|
||||
"description": "Set up OAuth configuration",
|
||||
"status": "pending",
|
||||
"dependencies": [],
|
||||
"details": "Configure GitHub OAuth app and store credentials"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Subtask Structure
|
||||
|
||||
Subtasks follow a similar structure to main tasks but with some differences:
|
||||
|
||||
### Subtask Properties
|
||||
|
||||
- **`id`** (number): Unique identifier within the parent task
|
||||
- **`title`** (string): Brief, descriptive title
|
||||
- **`description`** (string): Concise summary of the subtask
|
||||
- **`status`** (string): Current state (same values as main tasks)
|
||||
- **`dependencies`** (array): Can reference other subtasks or main task IDs
|
||||
- **`details`** (string): Implementation instructions and notes
|
||||
|
||||
### Subtask Example
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 2,
|
||||
"title": "Handle OAuth callback",
|
||||
"description": "Process the OAuth callback and extract user data",
|
||||
"status": "pending",
|
||||
"dependencies": [1],
|
||||
"details": "Parse callback parameters, exchange code for token, fetch user profile"
|
||||
}
|
||||
```
|
||||
|
||||
## Complete Example
|
||||
|
||||
Here's a complete example showing the tagged task structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"master": {
|
||||
"tasks": [
|
||||
{
|
||||
"id": 1,
|
||||
"title": "Setup Express Server",
|
||||
"description": "Initialize and configure Express.js server with middleware",
|
||||
"status": "done",
|
||||
"dependencies": [],
|
||||
"priority": "high",
|
||||
"details": "Create Express app with CORS, body parser, and error handling",
|
||||
"testStrategy": "Start server and verify health check endpoint responds",
|
||||
"subtasks": [
|
||||
{
|
||||
"id": 1,
|
||||
"title": "Initialize npm project",
|
||||
"description": "Set up package.json and install dependencies",
|
||||
"status": "done",
|
||||
"dependencies": [],
|
||||
"details": "Run npm init, install express, cors, body-parser"
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"title": "Configure middleware",
|
||||
"description": "Set up CORS and body parsing middleware",
|
||||
"status": "done",
|
||||
"dependencies": [1],
|
||||
"details": "Add app.use() calls for cors() and express.json()"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"title": "Implement user authentication",
|
||||
"description": "Create secure authentication system",
|
||||
"status": "pending",
|
||||
"dependencies": [1],
|
||||
"priority": "high",
|
||||
"details": "Use JWT tokens for session management",
|
||||
"testStrategy": "Test login/logout flow with valid and invalid credentials",
|
||||
"subtasks": []
|
||||
}
|
||||
]
|
||||
},
|
||||
"feature-auth": {
|
||||
"tasks": [
|
||||
{
|
||||
"id": 1,
|
||||
"title": "OAuth Integration",
|
||||
"description": "Add OAuth authentication support",
|
||||
"status": "pending",
|
||||
"dependencies": [],
|
||||
"priority": "medium",
|
||||
"details": "Integrate with GitHub OAuth for user authentication",
|
||||
"testStrategy": "Test OAuth flow with GitHub account",
|
||||
"subtasks": []
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Tag Context Management
|
||||
|
||||
### Current Tag Resolution
|
||||
|
||||
Task Master automatically determines the current tag context based on:
|
||||
|
||||
1. **State Configuration**: Current tag stored in `.taskmaster/state.json`
|
||||
2. **Default Fallback**: "master" tag when no context is specified
|
||||
3. **Future Enhancement**: Git branch-based tag switching (Part 2)
|
||||
|
||||
### Tag Isolation
|
||||
|
||||
- **Context Separation**: Tasks in different tags are completely isolated
|
||||
- **Independent Numbering**: Each tag has its own task ID sequence starting from 1
|
||||
- **Parallel Development**: Multiple team members can work on separate tags without conflicts
|
||||
|
||||
## Data Validation
|
||||
|
||||
Task Master validates the following aspects of task data:
|
||||
|
||||
### Required Validations
|
||||
|
||||
- **Unique IDs**: Task IDs must be unique within each tag context
|
||||
- **Valid Status**: Status values must be from the allowed set
|
||||
- **Dependency References**: Dependencies must reference existing task IDs within the same tag
|
||||
- **Subtask IDs**: Subtask IDs must be unique within their parent task
|
||||
|
||||
### Optional Validations
|
||||
|
||||
- **Circular Dependencies**: System detects and prevents circular dependency chains
|
||||
- **Priority Values**: Priority must be one of the allowed values if specified
|
||||
- **Data Types**: All properties must match their expected data types
|
||||
|
||||
## File Generation
|
||||
|
||||
Task Master can generate individual markdown files for each task based on the JSON structure. These files include:
|
||||
|
||||
- **Task Overview**: ID, title, status, dependencies
|
||||
- **Tag Context**: Which tag the task belongs to
|
||||
- **Implementation Details**: Full task details and test strategy
|
||||
- **Subtask Breakdown**: All subtasks with their current status
|
||||
- **Dependency Status**: Visual indicators showing which dependencies are complete
|
||||
|
||||
## Migration Process
|
||||
|
||||
When Task Master encounters a legacy format `tasks.json` file:
|
||||
|
||||
1. **Detection**: Automatically detects `{"tasks": [...]}` format
|
||||
2. **Transformation**: Converts to `{"master": {"tasks": [...]}}` format
|
||||
3. **Configuration**: Updates `.taskmaster/config.json` with tagged system settings
|
||||
4. **State Creation**: Creates `.taskmaster/state.json` for tag management
|
||||
5. **Notification**: Shows one-time friendly notice about the new system
|
||||
6. **Preservation**: All existing task data is preserved exactly as-is
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Task Organization
|
||||
|
||||
- **Logical Grouping**: Use tags to group related tasks (e.g., by feature, branch, or milestone)
|
||||
- **Clear Titles**: Use descriptive titles that explain the task's purpose
|
||||
- **Proper Dependencies**: Define dependencies to ensure correct execution order
|
||||
- **Detailed Instructions**: Include sufficient detail in the `details` field for implementation
|
||||
|
||||
### Tag Management
|
||||
|
||||
- **Meaningful Names**: Use descriptive tag names that reflect their purpose
|
||||
- **Consistent Naming**: Establish naming conventions for tags (e.g., branch names, feature names)
|
||||
- **Context Switching**: Be aware of which tag context you're working in
|
||||
- **Isolation Benefits**: Leverage tag isolation to prevent merge conflicts
|
||||
|
||||
### Subtask Design
|
||||
|
||||
- **Granular Tasks**: Break down complex tasks into manageable subtasks
|
||||
- **Clear Dependencies**: Define subtask dependencies to show implementation order
|
||||
- **Implementation Notes**: Use subtask details to track progress and decisions
|
||||
- **Status Tracking**: Keep subtask status updated as work progresses
|
||||
|
||||
Reference in New Issue
Block a user