├── .ai ├── plans │ ├── PLAN.md │ └── features │ │ └── .gitkeep ├── TASKS.md └── memory │ ├── plans │ └── .gitkeep │ ├── tasks │ └── .gitkeep │ ├── PLANS_LOG.md │ └── TASKS_LOG.md ├── .cursor └── rules │ └── .task-magic │ ├── workflow.md │ ├── _index.mdc │ ├── expand.mdc │ ├── memory.mdc │ ├── plans.mdc │ └── tasks.mdc ├── .windsurf └── rules │ └── .task-magic │ ├── workflow.md │ ├── _index.md │ ├── expand.md │ ├── memory.md │ ├── plans.md │ └── tasks.md └── README.md /.ai/plans/PLAN.md: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /.ai/TASKS.md: -------------------------------------------------------------------------------- 1 | # Project Tasks -------------------------------------------------------------------------------- /.ai/memory/plans/.gitkeep: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /.ai/memory/tasks/.gitkeep: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /.ai/plans/features/.gitkeep: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /.ai/memory/PLANS_LOG.md: -------------------------------------------------------------------------------- 1 | # Plans Log -------------------------------------------------------------------------------- /.ai/memory/TASKS_LOG.md: -------------------------------------------------------------------------------- 1 | # Task Archive Log -------------------------------------------------------------------------------- /.cursor/rules/.task-magic/workflow.md: -------------------------------------------------------------------------------- 1 | # Task Magic Workflow Diagram 2 | 3 | Below is the workflow diagram for the Task Magic system, illustrating the process of task creation, execution, and archival. 4 | 5 | ```mermaid 6 | graph TD 7 | A[User Request: Create Tasks from Plan/PRD] --> B["Plan All Tasks (Identify complex tasks for expansion)"]; 8 | B --> B1{Expansion Needed for Any Task?}; 9 | B1 -- Yes --> B2["Define Sub-tasks & Update Parent Task Definitions to Parent Tasks (listing sub-tasks in parent\'s details)"]; 10 | B1 -- No --> C; 11 | B2 --> C["Update .ai/TASKS.md with ALL Planned Tasks (Parent Tasks & Sub-tasks)"]; 12 | C --> D["For Each Task (Parent Task or Sub-task) in .ai/TASKS.md"]; 13 | D -- Loop --> E[Create/Update Individual task file in .ai/tasks/]; 14 | E --> F["Populate YAML & Markdown Body in task file (Parent task file updated to reflect parent status & list sub-tasks)"]; 15 | F -- End Loop --> G[All Task Files Created/Updated]; 16 | G --> H{User asks agent to work?}; 17 | H -- Yes --> I[Agent reads TASKS.md, finds first pending task]; 18 | I --> J{Check Dependencies for selected task}; 19 | J -- Met --> K[Update Task File YAML status: inprogress]; 20 | K --> L[Update TASKS.md entry: progress marker]; 21 | L --> M[Execute Task]; 22 | M -- Success --> N[Update YAML status: completed]; 23 | N --> O[Update TASKS.md entry: completed marker]; 24 | M -- Failure --> P["Update YAML status: failed, add error_log"]; 25 | P --> Q[Update TASKS.md entry: failed marker]; 26 | J -- Not Met --> R[Inform User: Dependencies Missing]; 27 | S{User asks to archive?} --> T[Agent finds completed/failed tasks in .ai/tasks/]; 28 | T --> U[Move task files to .ai/memory/tasks/]; 29 | U --> V[Append summary to .ai/memory/TASKS_LOG.md]; 30 | V --> W[Remove corresponding entries from .ai/TASKS.md]; 31 | ``` 32 | -------------------------------------------------------------------------------- /.windsurf/rules/.task-magic/workflow.md: -------------------------------------------------------------------------------- 1 | # Task Magic Workflow Diagram 2 | 3 | Below is the workflow diagram for the Task Magic system, illustrating the process of task creation, execution, and archival. 4 | 5 | ```mermaid 6 | graph TD 7 | A[User Request: Create Tasks from Plan/PRD] --> B["Plan All Tasks (Identify complex tasks for expansion)"]; 8 | B --> B1{Expansion Needed for Any Task?}; 9 | B1 -- Yes --> B2["Define Sub-tasks & Update Parent Task Definitions to Parent Tasks (listing sub-tasks in parent\'s details)"]; 10 | B1 -- No --> C; 11 | B2 --> C["Update .ai/TASKS.md with ALL Planned Tasks (Parent Tasks & Sub-tasks)"]; 12 | C --> D["For Each Task (Parent Task or Sub-task) in .ai/TASKS.md"]; 13 | D -- Loop --> E[Create/Update Individual task file in .ai/tasks/]; 14 | E --> F["Populate YAML & Markdown Body in task file (Parent task file updated to reflect parent status & list sub-tasks)"]; 15 | F -- End Loop --> G[All Task Files Created/Updated]; 16 | G --> H{User asks agent to work?}; 17 | H -- Yes --> I[Agent reads TASKS.md, finds first pending task]; 18 | I --> J{Check Dependencies for selected task}; 19 | J -- Met --> K[Update Task File YAML status: inprogress]; 20 | K --> L[Update TASKS.md entry: progress marker]; 21 | L --> M[Execute Task]; 22 | M -- Success --> N[Update YAML status: completed]; 23 | N --> O[Update TASKS.md entry: completed marker]; 24 | M -- Failure --> P["Update YAML status: failed, add error_log"]; 25 | P --> Q[Update TASKS.md entry: failed marker]; 26 | J -- Not Met --> R[Inform User: Dependencies Missing]; 27 | S{User asks to archive?} --> T[Agent finds completed/failed tasks in .ai/tasks/]; 28 | T --> U[Move task files to .ai/memory/tasks/]; 29 | U --> V[Append summary to .ai/memory/TASKS_LOG.md]; 30 | V --> W[Remove corresponding entries from .ai/TASKS.md]; 31 | ``` 32 | -------------------------------------------------------------------------------- /.cursor/rules/.task-magic/_index.mdc: -------------------------------------------------------------------------------- 1 | --- 2 | description: 3 | globs: 4 | alwaysApply: true 5 | --- 6 | # Task Magic System Overview 7 | 8 | Whenever you use this rule, start your message with the following: 9 | 10 | "Accessing Task Magic system overview..." 11 | 12 | The Task Magic system is a file-based project management and AI agent operational framework designed to plan features, manage development tasks, and maintain a memory of past work. It consists of three main components, each governed by its own detailed rule file: 13 | 14 | 1. **Plans (`@plans.mdc`)**: 15 | * **Purpose**: Defines how Product Requirements Documents (PRDs) are created and structured for the overall project and specific features. 16 | * **Location**: PRDs are stored in `.ai/plans/`, with feature-specific plans in `.ai/plans/features/`. 17 | * **Key File**: A global `PLAN.md` is mandatory in `.ai/plans/`. 18 | * **Details**: For plan creation, fully review [task-magic/plans.mdc](mdc:.cursor/rules/task-magic/plans.mdc) 19 | 20 | 2. **Tasks (`@tasks.mdc`)**: 21 | * **Purpose**: Governs the creation, management, and lifecycle of individual development tasks. 22 | * **Active Tasks**: All active tasks reside in `.ai/tasks/` as `task{id}_name.md` files. 23 | * **Master View**: A master checklist, `.ai/TASKS.md`, mirrors the status of tasks in the `.ai/tasks/` directory and must be kept synchronized. 24 | * **Details**: For task creation, fully review [task-magic/tasks.mdc](mdc:.cursor/rules/task-magic/tasks.mdc) 25 | 26 | 3. **Memory (`@memory.mdc`)**: 27 | * **Purpose**: Archives completed and failed tasks to provide historical context. 28 | * **Location**: Archived task files are stored in `.ai/memory/tasks/`. 29 | * **Log File**: A chronological log of archived tasks is maintained in `.ai/memory/TASKS_LOG.md`. 30 | * **Details**: For storing to memory, full review [task-magic/memory.mdc](mdc:.cursor/rules/task-magic/memory.mdc) 31 | 32 | This interconnected system allows for structured project development, from high-level planning to task execution and historical review, primarily managed through Markdown files and defined agent responsibilities. 33 | -------------------------------------------------------------------------------- /.windsurf/rules/.task-magic/_index.md: -------------------------------------------------------------------------------- 1 | --- 2 | trigger: always_on 3 | description: This rule provides an overview of the Task Magic system. 4 | --- 5 | # Task Magic System Overview 6 | 7 | Whenever you use this rule, start your message with the following: 8 | 9 | "Accessing Task Magic system overview..." 10 | 11 | The Task Magic system is a file-based project management and AI agent operational framework designed to plan features, manage development tasks, and maintain a memory of past work. It consists of three main components, each governed by its own detailed rule file: 12 | 13 | 1. **Plans (`@plans.md`)**: 14 | * **Purpose**: Defines how Product Requirements Documents (PRDs) are created and structured for the overall project and specific features. 15 | * **Location**: PRDs are stored in `.ai/plans/`, with feature-specific plans in `.ai/plans/features/`. 16 | * **Key File**: A global `PLAN.md` is mandatory in `.ai/plans/`. 17 | * **Details**: For plan creation, fully review [task-magic/plans.md](mdc:.cursor/rules/task-magic/plans.md) 18 | 19 | 2. **Tasks (`@tasks.md`)**: 20 | * **Purpose**: Governs the creation, management, and lifecycle of individual development tasks. 21 | * **Active Tasks**: All active tasks reside in `.ai/tasks/` as `task{id}_name.md` files. 22 | * **Master View**: A master checklist, `.ai/TASKS.md`, mirrors the status of tasks in the `.ai/tasks/` directory and must be kept synchronized. 23 | * **Details**: For task creation, fully review [task-magic/tasks.md](mdc:.cursor/rules/task-magic/tasks.md) 24 | 25 | 3. **Memory (`@memory.md`)**: 26 | * **Purpose**: Archives completed and failed tasks to provide historical context. 27 | * **Location**: Archived task files are stored in `.ai/memory/tasks/`. 28 | * **Log File**: A chronological log of archived tasks is maintained in `.ai/memory/TASKS_LOG.md`. 29 | * **Details**: For storing to memory, full review [task-magic/memory.md](mdc:.cursor/rules/task-magic/memory.md) 30 | 31 | This interconnected system allows for structured project development, from high-level planning to task execution and historical review, primarily managed through Markdown files and defined agent responsibilities. 32 | -------------------------------------------------------------------------------- /.windsurf/rules/.task-magic/expand.md: -------------------------------------------------------------------------------- 1 | --- 2 | trigger: model_decision 3 | description: This rule explains how the agent should check if a given task needs to be expanded into sub-tasks. 4 | --- 5 | # Expanding Large Tasks 6 | 7 | Whenever you use this rule, start your message with the following: 8 | 9 | "Checking if task needs to be expanded..." 10 | 11 | This rule provides guidelines for an AI agent to assess if a task defined in the Task Magic system is too complex or large and should be recommended for expansion into smaller, more manageable sub-tasks. 12 | 13 | You are a senior software architect and product manager and an expert in analyzing task complexity to decide whether or not a given task or tasks should be recommended for expansion into smaller subtasks. 14 | 15 | ## 1. When to Assess Task Complexity for Expansion 16 | 17 | Task complexity should be assessed: 18 | 19 | * **During Task Creation:** When a new task is being defined based on a PRD or user request. 20 | * **Before Starting a Task:** When an agent is about to pick up a `pending` task. 21 | * **If a Task Stagnates:** If an `inprogress` task shows little progress over a significant period. 22 | 23 | ## 2. Criteria for Identifying Tasks Needing Expansion 24 | 25 | A task might be a candidate for expansion if it meets several of the following criteria: 26 | 27 | * **Estimated Effort:** The task seems likely to take more than a predefined threshold (e.g., 2-3 ideal developer days) to complete. 28 | * **Multiple Distinct Components:** The task involves changes across multiple unrelated modules, services, or UI areas. 29 | * **High Uncertainty/Ambiguity:** The requirements are not fully clear, or there are many unknown technical challenges. 30 | * **Multiple Logical Outcomes:** The task has several distinct, independently verifiable outcomes. 31 | * **Numerous Acceptance Criteria:** The "Details" or "Test Strategy" sections are exceptionally long and cover many different aspects. 32 | * **Blocks Multiple Other Tasks:** It's a large prerequisite for a significant number of subsequent tasks. 33 | 34 | ## 3. Recommendation for Expansion 35 | 36 | If a task is deemed too complex for direct execution based on the criteria above, the agent should: 37 | 38 | 1. **Identify Sub-Goals:** Mentally break the original task's objective into smaller, logical, and sequential (or parallelizable) sub-goals. 39 | 2. **Recommend Sub-Tasks:** Propose a list of sub-tasks to the user or the calling process. For each proposed sub-task, suggest: 40 | * A descriptive title. 41 | * A brief description of its objective. 42 | * Potential dependencies on other proposed sub-tasks or the original parent task. 43 | * A suggested priority. 44 | 3. **State the Recommendation Clearly:** The agent's output should be a clear recommendation that the original task be expanded, followed by the list of suggested sub-tasks. For example: 45 | "Based on the complexity, I recommend expanding Task {original_task_id} '{Original Task Title}' into the following sub-tasks: 46 | 1. **Title:** Setup Database Schema for User Profiles 47 | * **Description:** Create and migrate the necessary database tables for storing user profile information. 48 | * **Priority:** critical 49 | * **Dependencies:** None 50 | 2. **Title:** Implement User Profile API Endpoints 51 | * **Description:** Develop the CRUD API endpoints for managing user profiles. 52 | * **Priority:** high 53 | * **Dependencies:** Sub-task 1 54 | 3. **Title:** Build User Profile Frontend View 55 | * **Description:** Create the UI components to display and edit user profiles. 56 | * **Priority:** high 57 | * **Dependencies:** Sub-task 2" 58 | 59 | **The actual creation of sub-task files, numbering, and updates to `TASKS.md` will be handled by the process that receives this recommendation, typically guided by the `task-magic/tasks.md` rule.** 60 | 61 | By focusing on analysis and recommendation, this rule provides a clear decision point before proceeding with the mechanics of task splitting. 62 | -------------------------------------------------------------------------------- /.cursor/rules/.task-magic/expand.mdc: -------------------------------------------------------------------------------- 1 | --- 2 | description: This rule explains how the agent should check if a given task needs to be expanded into sub-tasks. 3 | globs: 4 | alwaysApply: false 5 | --- 6 | # Expanding Large Tasks 7 | 8 | Whenever you use this rule, start your message with the following: 9 | 10 | "Checking if task needs to be expanded..." 11 | 12 | This rule provides guidelines for an AI agent to assess if a task defined in the Task Magic system is too complex or large and should be recommended for expansion into smaller, more manageable sub-tasks. 13 | 14 | You are a senior software architect and product manager and an expert in analyzing task complexity to decide whether or not a given task or tasks should be recommended for expansion into smaller subtasks. 15 | 16 | ## 1. When to Assess Task Complexity for Expansion 17 | 18 | Task complexity should be assessed: 19 | 20 | * **During Task Creation:** When a new task is being defined based on a PRD or user request. 21 | * **Before Starting a Task:** When an agent is about to pick up a `pending` task. 22 | * **If a Task Stagnates:** If an `inprogress` task shows little progress over a significant period. 23 | 24 | ## 2. Criteria for Identifying Tasks Needing Expansion 25 | 26 | A task might be a candidate for expansion if it meets several of the following criteria: 27 | 28 | * **Estimated Effort:** The task seems likely to take more than a predefined threshold (e.g., 2-3 ideal developer days) to complete. 29 | * **Multiple Distinct Components:** The task involves changes across multiple unrelated modules, services, or UI areas. 30 | * **High Uncertainty/Ambiguity:** The requirements are not fully clear, or there are many unknown technical challenges. 31 | * **Multiple Logical Outcomes:** The task has several distinct, independently verifiable outcomes. 32 | * **Numerous Acceptance Criteria:** The "Details" or "Test Strategy" sections are exceptionally long and cover many different aspects. 33 | * **Blocks Multiple Other Tasks:** It's a large prerequisite for a significant number of subsequent tasks. 34 | 35 | ## 3. Recommendation for Expansion 36 | 37 | If a task is deemed too complex for direct execution based on the criteria above, the agent should: 38 | 39 | 1. **Identify Sub-Goals:** Mentally break the original task's objective into smaller, logical, and sequential (or parallelizable) sub-goals. 40 | 2. **Recommend Sub-Tasks:** Propose a list of sub-tasks to the user or the calling process. For each proposed sub-task, suggest: 41 | * A descriptive title. 42 | * A brief description of its objective. 43 | * Potential dependencies on other proposed sub-tasks or the original parent task. 44 | * A suggested priority. 45 | 3. **State the Recommendation Clearly:** The agent's output should be a clear recommendation that the original task be expanded, followed by the list of suggested sub-tasks. For example: 46 | "Based on the complexity, I recommend expanding Task {original_task_id} '{Original Task Title}' into the following sub-tasks: 47 | 1. **Title:** Setup Database Schema for User Profiles 48 | * **Description:** Create and migrate the necessary database tables for storing user profile information. 49 | * **Priority:** critical 50 | * **Dependencies:** None 51 | 2. **Title:** Implement User Profile API Endpoints 52 | * **Description:** Develop the CRUD API endpoints for managing user profiles. 53 | * **Priority:** high 54 | * **Dependencies:** Sub-task 1 55 | 3. **Title:** Build User Profile Frontend View 56 | * **Description:** Create the UI components to display and edit user profiles. 57 | * **Priority:** high 58 | * **Dependencies:** Sub-task 2" 59 | 60 | **The actual creation of sub-task files, numbering, and updates to `TASKS.md` will be handled by the process that receives this recommendation, typically guided by the `task-magic/tasks.mdc` rule.** 61 | 62 | By focusing on analysis and recommendation, this rule provides a clear decision point before proceeding with the mechanics of task splitting. 63 | -------------------------------------------------------------------------------- /.windsurf/rules/.task-magic/memory.md: -------------------------------------------------------------------------------- 1 | --- 2 | trigger: model_decision 3 | description: This rule explains how the agent should use the memory system to find context of the project 4 | --- 5 | # AI Memory System 6 | 7 | Whenever you use this rule, start your message with the following: 8 | 9 | "Checking Task Magic memory..." 10 | 11 | This project utilizes a memory system located in the `.ai/memory/` directory to store a history of completed, failed, or superseded work, providing valuable context for ongoing development. It archives both tasks and plans. 12 | 13 | ## Structure 14 | 15 | The memory system consists of: 16 | 17 | ### Task Archive 18 | 19 | * **`.ai/memory/tasks/`**: This directory contains the full Markdown files (`task{id}_name.md`) of tasks that have been archived (status: `completed` or `failed`). These files retain the original details, descriptions, and test strategies defined when the task was active. 20 | * **`.ai/memory/TASKS_LOG.md`**: This is an append-only Markdown file that serves as a chronological log of when tasks were archived. Each entry summarizes the archived task, including its ID, Title, final Status, Dependencies, and the Description extracted from the task file at the time of archival. 21 | 22 | ### Plan Archive 23 | 24 | * **`.ai/memory/plans/`**: This directory contains the full Markdown files of PRDs (both global `PLAN.md` versions and feature plans like `{feature}-plan.md`) that have been archived. Plans might be archived when they are completed (all associated features are implemented and stable), deprecated (the feature or project direction is abandoned), or superseded by a newer version of the plan. 25 | * **`.ai/memory/PLANS_LOG.md`**: This is an append-only Markdown file that serves as a chronological log of when plans were archived. Each entry should summarize the archived plan, including its **full path within the `.ai/memory/plans/` directory** (e.g., `.ai/memory/plans/old-feature-plan.md`), a version or date stamp, the reason for archival (e.g., Completed, Deprecated, Superseded), and a brief description or title of the plan. 26 | * **Log Entry Format Example for PLANS_LOG.md:** 27 | ```markdown 28 | - **Archived Plan:** `.ai/memory/plans/old-feature-plan.md` 29 | - **Archived On:** YYYY-MM-DD HH:MM:SS 30 | - **Reason:** Deprecated 31 | - **Title:** PRD: Old Feature 32 | - **Original File (Optional):** {.ai/plans/features/old-feature-plan.md} 33 | ``` 34 | 35 | ## Directory and File Management 36 | 37 | When working with the memory system, the agent should always verify that required directories and files exist before attempting operations: 38 | 39 | 1. **Check Directories Before Creation:** Before performing operations, check if directories like `.ai/memory/tasks/` or `.ai/memory/plans/` exist by using the `list_dir` tool on its parent (`.ai/memory/`) or by using `file_search` for the specific directory path. If a directory does not appear in the results, it can be implicitly created when using `edit_file` to write a file within that path, as `edit_file` creates necessary parent directories. 40 | 41 | 2. **Check Files Before Operations:** Before operating on files like `.ai/memory/TASKS_LOG.md` or `.ai/memory/PLANS_LOG.md`, the agent should use the `file_search` tool with the full file path to check for its existence. 42 | 43 | 3. **Safe File Creation/Modification:** If a file like `.ai/memory/TASKS_LOG.md` or `.ai/memory/PLANS_LOG.md` doesn't exist (as determined by `file_search`), and it needs to be created with initial content (e.g., `"\# Task Archive Log\\n\\n"` or `"\# Plan Archive Log\\n\\n"`), use the `edit_file` tool. To append to an existing file, first use `read_file` to get its current content, then append the new data to this content, and finally use `edit_file` to write the combined content back. 44 | 45 | 4. **Archiving Plan Files:** When moving a plan file (e.g., from `.ai/plans/features/` to `.ai/memory/plans/`), always use the `run_terminal_cmd` tool with the `mv` command. Do not use `edit_file` to create a new file in the destination and `delete_file` to remove the original. This ensures the file is moved atomically and preserves its history if version control is used. Example: `mv .ai/plans/features/my-feature-plan.md .ai/memory/plans/my-feature-plan.md`. 46 | 47 | ## Purpose and Usage 48 | 49 | The memory system serves as the project's historical record of development activity and planning managed by the AI task system. 50 | 51 | **When to Consult Memory:** 52 | 53 | * **Understanding Past Implementations & Plans:** Before starting a new task or planning a new feature, consult the memory (`TASKS_LOG.md`, `PLANS_LOG.md`, and relevant archived files) to understand how similar or dependent features were built and planned. 54 | * **Avoiding Redundancy:** Check if a similar task, requirement, or plan has been addressed previously. 55 | * **Planning Related Features:** Review past tasks and plans for a feature to inform the planning and task breakdown of new, related features. 56 | * **Investigating Failed Tasks:** If a task failed previously, reviewing its archived file (including the `error_log` in the YAML) can provide context. 57 | * **Historical Context of Decisions:** Archived plans provide a snapshot of the project's goals, requirements, and intended direction at a particular point in time. 58 | 59 | **How to Consult Memory:** 60 | 61 | 1. **Start with the Logs:** Read `.ai/memory/TASKS_LOG.md` and `.ai/memory/PLANS_LOG.md` to get a chronological overview of archived items. Identify potentially relevant tasks or plans based on their titles, descriptions, and reasons for archival. 62 | 2. **Dive into Archived Files:** If a log entry suggests an item is highly relevant, read the full archived file from its respective directory (`.ai/memory/tasks/` or `.ai/memory/plans/`) to get the complete details. 63 | 64 | By leveraging this historical context, the AI can make more informed decisions, maintain consistency, and work more efficiently on the project. 65 | -------------------------------------------------------------------------------- /.cursor/rules/.task-magic/memory.mdc: -------------------------------------------------------------------------------- 1 | --- 2 | description: This rule explains how the agent should use the memory system to find context of the project 3 | globs: 4 | alwaysApply: false 5 | --- 6 | # AI Memory System 7 | 8 | Whenever you use this rule, start your message with the following: 9 | 10 | "Checking Task Magic memory..." 11 | 12 | This project utilizes a memory system located in the `.ai/memory/` directory to store a history of completed, failed, or superseded work, providing valuable context for ongoing development. It archives both tasks and plans. 13 | 14 | ## Structure 15 | 16 | The memory system consists of: 17 | 18 | ### Task Archive 19 | 20 | * **`.ai/memory/tasks/`**: This directory contains the full Markdown files (`task{id}_name.md`) of tasks that have been archived (status: `completed` or `failed`). These files retain the original details, descriptions, and test strategies defined when the task was active. 21 | * **`.ai/memory/TASKS_LOG.md`**: This is an append-only Markdown file that serves as a chronological log of when tasks were archived. Each entry summarizes the archived task, including its ID, Title, final Status, Dependencies, and the Description extracted from the task file at the time of archival. 22 | 23 | ### Plan Archive 24 | 25 | * **`.ai/memory/plans/`**: This directory contains the full Markdown files of PRDs (both global `PLAN.md` versions and feature plans like `{feature}-plan.md`) that have been archived. Plans might be archived when they are completed (all associated features are implemented and stable), deprecated (the feature or project direction is abandoned), or superseded by a newer version of the plan. 26 | * **`.ai/memory/PLANS_LOG.md`**: This is an append-only Markdown file that serves as a chronological log of when plans were archived. Each entry should summarize the archived plan, including its **full path within the `.ai/memory/plans/` directory** (e.g., `.ai/memory/plans/old-feature-plan.md`), a version or date stamp, the reason for archival (e.g., Completed, Deprecated, Superseded), and a brief description or title of the plan. 27 | * **Log Entry Format Example for PLANS_LOG.md:** 28 | ```markdown 29 | - **Archived Plan:** `.ai/memory/plans/old-feature-plan.md` 30 | - **Archived On:** YYYY-MM-DD HH:MM:SS 31 | - **Reason:** Deprecated 32 | - **Title:** PRD: Old Feature 33 | - **Original File (Optional):** {.ai/plans/features/old-feature-plan.md} 34 | ``` 35 | 36 | ## Directory and File Management 37 | 38 | When working with the memory system, the agent should always verify that required directories and files exist before attempting operations: 39 | 40 | 1. **Check Directories Before Creation:** Before performing operations, check if directories like `.ai/memory/tasks/` or `.ai/memory/plans/` exist by using the `list_dir` tool on its parent (`.ai/memory/`) or by using `file_search` for the specific directory path. If a directory does not appear in the results, it can be implicitly created when using `edit_file` to write a file within that path, as `edit_file` creates necessary parent directories. 41 | 42 | 2. **Check Files Before Operations:** Before operating on files like `.ai/memory/TASKS_LOG.md` or `.ai/memory/PLANS_LOG.md`, the agent should use the `file_search` tool with the full file path to check for its existence. 43 | 44 | 3. **Safe File Creation/Modification:** If a file like `.ai/memory/TASKS_LOG.md` or `.ai/memory/PLANS_LOG.md` doesn't exist (as determined by `file_search`), and it needs to be created with initial content (e.g., `"\# Task Archive Log\\n\\n"` or `"\# Plan Archive Log\\n\\n"`), use the `edit_file` tool. To append to an existing file, first use `read_file` to get its current content, then append the new data to this content, and finally use `edit_file` to write the combined content back. 45 | 46 | 4. **Archiving Plan Files:** When moving a plan file (e.g., from `.ai/plans/features/` to `.ai/memory/plans/`), always use the `run_terminal_cmd` tool with the `mv` command. Do not use `edit_file` to create a new file in the destination and `delete_file` to remove the original. This ensures the file is moved atomically and preserves its history if version control is used. Example: `mv .ai/plans/features/my-feature-plan.md .ai/memory/plans/my-feature-plan.md`. 47 | 48 | ## Purpose and Usage 49 | 50 | The memory system serves as the project's historical record of development activity and planning managed by the AI task system. 51 | 52 | **When to Consult Memory:** 53 | 54 | * **Understanding Past Implementations & Plans:** Before starting a new task or planning a new feature, consult the memory (`TASKS_LOG.md`, `PLANS_LOG.md`, and relevant archived files) to understand how similar or dependent features were built and planned. 55 | * **Avoiding Redundancy:** Check if a similar task, requirement, or plan has been addressed previously. 56 | * **Planning Related Features:** Review past tasks and plans for a feature to inform the planning and task breakdown of new, related features. 57 | * **Investigating Failed Tasks:** If a task failed previously, reviewing its archived file (including the `error_log` in the YAML) can provide context. 58 | * **Historical Context of Decisions:** Archived plans provide a snapshot of the project's goals, requirements, and intended direction at a particular point in time. 59 | 60 | **How to Consult Memory:** 61 | 62 | 1. **Start with the Logs:** Read `.ai/memory/TASKS_LOG.md` and `.ai/memory/PLANS_LOG.md` to get a chronological overview of archived items. Identify potentially relevant tasks or plans based on their titles, descriptions, and reasons for archival. 63 | 2. **Dive into Archived Files:** If a log entry suggests an item is highly relevant, read the full archived file from its respective directory (`.ai/memory/tasks/` or `.ai/memory/plans/`) to get the complete details. 64 | 65 | By leveraging this historical context, the AI can make more informed decisions, maintain consistency, and work more efficiently on the project. 66 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Task Magic: Automagically create tasks for vibe coding projects 2 | 3 | This system helps you manage your software projects by defining plans, breaking them down into actionable tasks, and keeping a memory of what's been done, all while working seamlessly with AI agents like Cursor and Windsurf. 4 | 5 | One of the key goals is to avoid the "AI loop of death." ☠️ 6 | 7 | By breaking down work into smaller, focused tasks (each with a clear start, end, and test strategy), AI agents can tackle them effectively without losing context and making dumb mistakes. 8 | 9 | (Note: they will still sometimes make dumb mistakes but it is 10x less likely using a task-based approach.) 10 | 11 | The system provides permanent context through the `.ai/memory/` folder. This allows AI coding agents to see what has been built before and understand the how and why, helping them to ship new tasks more effectively. 12 | 13 | ## Video walkthrough 14 | 15 | To get an idea of how to use Task Magic in your own projects, check out the video walkthrough below (and also subscribe to the channel, obvs). 16 | 17 | [![I built a task manager that makes Cursor "JUST WORK"](https://img.youtube.com/vi/XBu8KeWuQbM/0.jpg)](https://www.youtube.com/watch?v=XBu8KeWuQbM) 18 | 19 | ## How it works 20 | 21 | Task Magic is a file-based system. This means all your project plans, tasks, and history are stored in plain text files (mostly Markdown) right in your project's `.ai/` directory. This makes it easy to version control, track changes, and for AI agents to read and understand your project. 22 | 23 | There are three main parts to Task Magic: 24 | 25 | 1. **Plans (`.ai/plans/`)**: 26 | * **Purpose**: This is where you define the "what" and "why" of your project or specific features. Think of these as your Product Requirements Documents (PRDs). 27 | * **Key files**: 28 | * `.ai/plans/PLAN.md`: A global overview of your entire project. It should be a concise summary and index, linking to more detailed feature plans. 29 | * `.ai/plans/features/{your-feature}-plan.md`: Detailed PRDs for each specific feature you're building. This is where the AI will look for specifics when generating tasks. 30 | * **AI interaction**: AI agents use these plans to understand the scope and requirements, helping to generate tasks. 31 | 32 | 2. **Tasks (`.ai/tasks/` & `.ai/TASKS.md`)**: 33 | * **Purpose**: This is where the actual work items live. AI agents (or you) can break down plans into individual, manageable tasks. 34 | * **Key files & structure**: 35 | * `.ai/tasks/task{id}_description.md`: Each task gets its own Markdown file. It includes details like status (pending, inprogress, completed), priority, dependencies, a description, and how to test it. 36 | * `.ai/TASKS.md`: This is your master checklist. It's a human-friendly overview of all tasks in the `.ai/tasks/` directory, showing their status at a glance. **This file and the individual task files are kept in sync by the AI.** 37 | * **AI interaction**: AI agents can create tasks from plans, update their status as they work on them, and help you manage dependencies. 38 | 39 | 3. **Memory (`.ai/memory/`)**: 40 | * **Purpose**: Completed and failed tasks, as well as old plans, are archived here. This provides a valuable history for the AI to learn from and for you to reference. 41 | * **Key files**: 42 | * `.ai/memory/tasks/`: Archived task files. 43 | * `.ai/memory/TASKS_LOG.md`: A log of when tasks were archived. 44 | * `.ai/memory/plans/`: Archived plan files. 45 | * `.ai/memory/PLANS_LOG.md`: A log for archived plans. 46 | * **AI interaction**: The AI can consult the memory to understand how similar things were done in the past, or why a certain approach was taken. 47 | 48 | ## Working with AI agents (Cursor & Windsurf) 49 | 50 | Task Magic is designed to work closely with AI agents. Here's how rules and context are handled: 51 | 52 | * **Automatic context (`_index.md` files)**: 53 | * Files named `_index.md` (like the one in `.windsurf/rules/.task-magic/_index.md` or `.cursor/rules/.task-magic/_index.mdc`) provide a high-level overview of a system or a set of rules. 54 | * These `_index.md` files are **automatically included in the AI's context** when you're working within a project that uses them. This gives the AI a foundational understanding without you needing to do anything extra. 55 | 56 | * **On-demand rules (other `.md` or `.mdc` rule files)**: 57 | * Other rule files (e.g., `tasks.mdc`, `plans.mdc` located in `.cursor/rules/.task-magic/` or `.windsurf/rules/.task-magic/`) define specific behaviors or knowledge for the AI. 58 | * Each of these rule files has a `description` in its header. The AI agent (Cursor/Windsurf) can read these descriptions and **decide dynamically whether a specific rule is relevant** to your current request or the task it's performing. 59 | * If the AI deems a rule relevant, it will "fetch" and use that rule. 60 | 61 | * **Your role: Guiding the AI with @-tags**: 62 | * While the agent is usually pretty good at figuring out which rules to use, you can manually tag the rules you want to use. 63 | * **For best results, @-tag specific rule files or directories in your prompts.** For example: 64 | * `@.cursor/rules/.task-magic/tasks.mdc create tasks for this feature` 65 | * `@.windsurf/rules/.task-magic/plans.md generate a plan for X` 66 | * `@TASKS.md what is the status of my project?` (to refer to the main task checklist) 67 | * `@.ai/plans/features/my-cool-feature-plan.md can you review this plan?` 68 | * This helps ensure the AI looks at the exact information you want it to. 69 | 70 | ## Getting started 71 | 72 | 1. **Initialize `.ai/` structure**: If these directories don't exist, the AI will typically create them as needed when you ask it to create a plan or task. You can also create them manually. 73 | * `.ai/plans/PLAN.md` (start with a simple project title and overview) 74 | * `.ai/TASKS.md` (can start with just `# Project Tasks`) 75 | * `.ai/memory/TASKS_LOG.md` (can start with `# Task Archive Log`) 76 | 2. **Create a plan**: Ask your AI assistant to create a new feature plan using the planning rule (e.g., `@.cursor/rules/.task-magic/plans.mdc create a plan for user authentication`). 77 | 3. **Generate tasks**: Once a plan is ready, ask the AI to generate tasks from it (e.g., `@.cursor/rules/.task-magic/tasks.mdc generate tasks for the user-authentication-plan.md`). 78 | 4. **Work on tasks**: Tell the AI to start working on tasks. It will update `.ai/TASKS.md` and the individual task files as it progresses. 79 | 5. **Archive**: Periodically, ask the AI to archive completed or failed tasks to keep your active task list clean. 80 | 81 | By using Task Magic, you get a structured, AI-friendly way to manage your projects, ensuring both you and your AI assistants are always on the same page. 82 | 83 | ## Customizing Task Magic 84 | 85 | I built this for myself to fit into my workflow. It might not work as well for you. 86 | 87 | But since this is file based rules and we're all vibe coding in Cursor/Windsurf, you can easily customize it to fit your workflow. 88 | 89 | If something doesn't work for you, tag the rule(s) you want to change, explain what doesn't work (and what you think might) and **have the agent update them for you.** 90 | 91 | For example: 92 | 93 | ``` 94 | @plans.mdc I want my plans to be more concise and simple. Update the rule and make the PRD template shorter and to the point. 95 | ``` 96 | 97 | ## Contributing & feedback 98 | 99 | This system is designed to evolve. If you have ideas for improvements, find a bug, or want to make Task Magic even better: 100 | 101 | * **Open an issue**: If you encounter problems or have suggestions, please open an issue. 102 | * **Submit Pull Requests**: If you've made enhancements to the rules or the system structure that you think would benefit others, feel free to submit a pull request. -------------------------------------------------------------------------------- /.windsurf/rules/.task-magic/plans.md: -------------------------------------------------------------------------------- 1 | --- 2 | trigger: model_decision 3 | description: This rule specifies the technical details for creating Product Requirements Documents (PRDs), also known as plans, in the project's file-based planning system. 4 | --- 5 | # PRD Generation Rule 6 | 7 | Whenever you use this rule, start your message with the following: 8 | 9 | "Checking Task Magic planner..." 10 | 11 | This rule specifies the technical details for creating Product Requirements Documents (PRDs) in the project's file-based planning system. 12 | 13 | You are a senior product manager and an expert in creating product requirements documents (PRDs) for software development teams. 14 | 15 | Your task is to create a comprehensive product requirements document (PRD) for the project or feature requested by the user. 16 | 17 | ## Core Concepts 18 | 19 | 1. **Planning Folder:** The `.ai/plans/` directory holds all PRD files. 20 | 2. **Global Plan (`PLAN.MD`):** A single, mandatory `PLAN.MD` file must exist directly within `.ai/plans/`. Its primary role is to serve as a **concise high-level overview of the overall project and an index to detailed feature-specific PRDs**. It should define the project's vision and core goals but **must not become a lengthy PRD itself**. It provides essential context by linking to comprehensive feature plans. 21 | 3. **Feature Plans:** Specific features **must** have their detailed PRDs located within the `.ai/plans/features/` subdirectory (e.g., `features/{feature}-plan.md`). These documents contain the comprehensive planning, requirements, user stories, and technical considerations for individual features. 22 | 4. **Purpose:** PRDs serve as the detailed specification for specific features (`features/{feature}-plan.md`). The global `PLAN.MD` supports this by providing the overarching project summary and acting as a central hub that **links to these detailed feature PRDs**. Task breakdown (using the `ai-tasks` system) is based on the detailed content within feature plans. 23 | 5. **Plan Lifecycle:** Active plans reside in `.ai/plans/`. Completed, deprecated, or superseded plans can be archived to `.ai/memory/plans/` for historical reference, as detailed in the `task-magic/memory` rule. 24 | 25 | ## Directory Structure 26 | 27 | ``` 28 | .ai/ 29 | plans/ # Parent directory for all PRDs 30 | PLAN.md # Mandatory: Global project PRD 31 | features/ # Directory for feature-specific PRDs 32 | {feature}-plan.md # Example feature PRD 33 | tasks/ # (For reference - Tasks are generated based on PRDs) 34 | memory/ # (For reference - Task archive) 35 | TASKS.md # (For reference - Master task checklist) 36 | ``` 37 | 38 | **Note:** Before creating directories like `.ai/plans/` or `.ai/plans/features/`, the agent should first check if they exist using `list_dir` on the parent directory or `file_search` for the specific directory path. If a directory does not exist, it can be implicitly created when using `edit_file` to place a file within that path, as `edit_file` will create necessary parent directories. The agent should also ensure `PLAN.md` exists (checking with `file_search` and creating with `edit_file` if necessary with a basic structure) before generating feature plans. 39 | 40 | ## PRD File Format 41 | 42 | PRDs are Markdown files (`.md`) following a structured template. 43 | 44 | **Filename Convention:** 45 | 46 | - **Global:** `PLAN.md` (Mandatory). 47 | - **Feature:** `{feature}-plan.md`, where `{feature}` is a short, descriptive kebab-case name for the feature (e.g., `user-authentication-plan.md`). 48 | 49 | **PRD Template (Markdown):** 50 | 51 | Agents should generate PRDs following this structure, filling in details based on user requests and context. Use sentence case for headings unless otherwise specified. 52 | 53 | ```markdown 54 | # PRD: {Project/Feature Title} 55 | 56 | ## 1. Product overview 57 | 58 | ### 1.1 Document title and version 59 | 60 | - PRD: {Project/Feature Title} 61 | - Version: 1.0 62 | 63 | ### 1.2 Product summary 64 | 65 | (2-3 short paragraphs providing an overview of the project or feature.) 66 | 67 | ## 2. Goals 68 | 69 | ### 2.1 Business goals 70 | 71 | - (Bullet list of business objectives) 72 | 73 | ### 2.2 User goals 74 | 75 | - (Bullet list of what users aim to achieve) 76 | 77 | ### 2.3 Non-goals 78 | 79 | - (Bullet list of explicitly out-of-scope items) 80 | 81 | ## 3. User personas 82 | 83 | ### 3.1 Key user types 84 | 85 | - (Bullet list of primary user categories) 86 | 87 | ### 3.2 Basic persona details 88 | 89 | - **{Persona Name 1}**: {Brief description} 90 | - **{Persona Name 2}**: {Brief description} 91 | 92 | ### 3.3 Role-based access 93 | 94 | - **{Role Name 1}**: {Description of permissions/access} 95 | - **{Role Name 2}**: {Description of permissions/access} 96 | 97 | ## 4. Functional requirements 98 | 99 | - **{Feature Name 1}** (Priority: {High/Medium/Low}) 100 | - {Requirement 1.1} 101 | - {Requirement 1.2} 102 | - **{Feature Name 2}** (Priority: {High/Medium/Low}) 103 | - {Requirement 2.1} 104 | 105 | ## 5. User experience 106 | 107 | ### 5.1 Entry points & first-time user flow 108 | 109 | - (How users access this feature/product initially) 110 | 111 | ### 5.2 Core experience 112 | 113 | - **{Step 1}**: {Explanation of the step} 114 | - {Detail on making it a good experience} 115 | - **{Step 2}**: {Explanation of the step} 116 | - {Detail on making it a good experience} 117 | 118 | ### 5.3 Advanced features & edge cases 119 | 120 | - (Bullet list of less common scenarios or advanced capabilities) 121 | 122 | ### 5.4 UI/UX highlights 123 | 124 | - (Key design principles or user interface elements) 125 | 126 | ## 6. Narrative 127 | 128 | (A single paragraph describing the user's journey and the benefit they receive.) 129 | 130 | ## 7. Success metrics 131 | 132 | ### 7.1 User-centric metrics 133 | 134 | - (e.g., Task completion rate, user satisfaction) 135 | 136 | ### 7.2 Business metrics 137 | 138 | - (e.g., Conversion rate, revenue impact) 139 | 140 | ### 7.3 Technical metrics 141 | 142 | - (e.g., Page load time, error rate) 143 | 144 | ## 8. Technical considerations 145 | 146 | ### 8.1 Integration points 147 | 148 | - (Interaction with other systems/services) 149 | 150 | ### 8.2 Data storage & privacy 151 | 152 | - (How data is handled, GDPR/CCPA compliance etc.) 153 | 154 | ### 8.3 Scalability & performance 155 | 156 | - (Anticipated load, performance targets) 157 | 158 | ### 8.4 Potential challenges 159 | 160 | - (Risks or technical hurdles) 161 | 162 | ## 9. Milestones & sequencing 163 | 164 | ### 9.1 Project estimate 165 | 166 | - {Small/Medium/Large}: {Rough time estimate, e.g., 2-4 weeks} 167 | 168 | ### 9.2 Team size & composition 169 | 170 | - {e.g., Small Team: 1-2 people (1 PM, 1 Eng)} 171 | 172 | ### 9.3 Suggested phases 173 | 174 | - **{Phase 1}**: {Description} ({Time estimate}) 175 | - Key deliverables: {List} 176 | - **{Phase 2}**: {Description} ({Time estimate}) 177 | - Key deliverables: {List} 178 | 179 | ## 10. User stories 180 | 181 | (Generate a subsection for each user story) 182 | 183 | ### 10.1 {User Story Title 1} 184 | 185 | - **ID**: US-001 186 | - **Description**: As a {persona}, I want to {action} so that {benefit}. 187 | - **Acceptance Criteria**: 188 | - {Criterion 1.1} 189 | - {Criterion 1.2} 190 | 191 | ### 10.2 {User Story Title 2} 192 | 193 | - **ID**: US-002 194 | - **Description**: As a {persona}, I want to {action} so that {benefit}. 195 | - **Acceptance Criteria**: 196 | - {Criterion 2.1} 197 | - {Criterion 2.2} 198 | 199 | ``` 200 | 201 | ## Agent Responsibilities 202 | 203 | 1. **Ensure Global Plan Exists:** Before creating feature plans, verify `.ai/plans/PLAN.MD` exists. If not, inform the user and offer to create a basic structure for it, emphasizing its role as a **concise project summary and an index to detailed feature plans**, not a comprehensive PRD itself. 204 | 2. **Determine Scope:** Clarify if the request is to update the global `PLAN.MD` (which should generally involve refining the overall project vision, updating core goals, or adding/modifying links to feature PRDs) or to create/update a **detailed feature-specific plan** in `.ai/plans/features/{feature}-plan.md`. Avoid adding extensive feature details directly into `PLAN.MD`. 205 | 3. **Filename:** Use the correct filename convention. Create directories if they don't exist. 206 | 4. **Use Template:** Generate the PRD content strictly following the Markdown template structure provided above. 207 | 5. **Fill Content:** Populate the sections based on the user's request, project context (especially `PLAN.md`), and best practices for PRD writing. 208 | 6. **Completeness:** Ensure all necessary user stories (primary, alternative, edge cases, security) are included with clear acceptance criteria. 209 | 7. **Focus:** The agent's role is *only* to generate or update PRD Markdown files in the active planning directory (`.ai/plans/`). This means creating/editing the high-level `PLAN.MD` or detailed `features/{feature}-plan.md` files. Task creation is a separate process handled by interpreting the detailed feature PRDs using the `ai-tasks` rule. Archiving plans is handled by the `task-magic/memory` rule. 210 | -------------------------------------------------------------------------------- /.cursor/rules/.task-magic/plans.mdc: -------------------------------------------------------------------------------- 1 | --- 2 | description: This rule specifies the technical details for creating Product Requirements Documents (PRDs), also known as plans, in the project's file-based planning system. 3 | globs: 4 | alwaysApply: false 5 | --- 6 | # PRD Generation Rule 7 | 8 | Whenever you use this rule, start your message with the following: 9 | 10 | "Checking Task Magic planner..." 11 | 12 | This rule specifies the technical details for creating Product Requirements Documents (PRDs) in the project's file-based planning system. 13 | 14 | You are a senior product manager and an expert in creating product requirements documents (PRDs) for software development teams. 15 | 16 | Your task is to create a comprehensive product requirements document (PRD) for the project or feature requested by the user. 17 | 18 | ## Core Concepts 19 | 20 | 1. **Planning Folder:** The `.ai/plans/` directory holds all PRD files. 21 | 2. **Global Plan (`PLAN.MD`):** A single, mandatory `PLAN.MD` file must exist directly within `.ai/plans/`. Its primary role is to serve as a **concise high-level overview of the overall project and an index to detailed feature-specific PRDs**. It should define the project's vision and core goals but **must not become a lengthy PRD itself**. It provides essential context by linking to comprehensive feature plans. 22 | 3. **Feature Plans:** Specific features **must** have their detailed PRDs located within the `.ai/plans/features/` subdirectory (e.g., `features/{feature}-plan.md`). These documents contain the comprehensive planning, requirements, user stories, and technical considerations for individual features. 23 | 4. **Purpose:** PRDs serve as the detailed specification for specific features (`features/{feature}-plan.md`). The global `PLAN.MD` supports this by providing the overarching project summary and acting as a central hub that **links to these detailed feature PRDs**. Task breakdown (using the `ai-tasks` system) is based on the detailed content within feature plans. 24 | 5. **Plan Lifecycle:** Active plans reside in `.ai/plans/`. Completed, deprecated, or superseded plans can be archived to `.ai/memory/plans/` for historical reference, as detailed in the `task-magic/memory` rule. 25 | 26 | ## Directory Structure 27 | 28 | ``` 29 | .ai/ 30 | plans/ # Parent directory for all PRDs 31 | PLAN.md # Mandatory: Global project PRD 32 | features/ # Directory for feature-specific PRDs 33 | {feature}-plan.md # Example feature PRD 34 | tasks/ # (For reference - Tasks are generated based on PRDs) 35 | memory/ # (For reference - Task archive) 36 | TASKS.md # (For reference - Master task checklist) 37 | ``` 38 | 39 | **Note:** Before creating directories like `.ai/plans/` or `.ai/plans/features/`, the agent should first check if they exist using `list_dir` on the parent directory or `file_search` for the specific directory path. If a directory does not exist, it can be implicitly created when using `edit_file` to place a file within that path, as `edit_file` will create necessary parent directories. The agent should also ensure `PLAN.md` exists (checking with `file_search` and creating with `edit_file` if necessary with a basic structure) before generating feature plans. 40 | 41 | ## PRD File Format 42 | 43 | PRDs are Markdown files (`.md`) following a structured template. 44 | 45 | **Filename Convention:** 46 | 47 | - **Global:** `PLAN.md` (Mandatory). 48 | - **Feature:** `{feature}-plan.md`, where `{feature}` is a short, descriptive kebab-case name for the feature (e.g., `user-authentication-plan.md`). 49 | 50 | **PRD Template (Markdown):** 51 | 52 | Agents should generate PRDs following this structure, filling in details based on user requests and context. Use sentence case for headings unless otherwise specified. 53 | 54 | ```markdown 55 | # PRD: {Project/Feature Title} 56 | 57 | ## 1. Product overview 58 | 59 | ### 1.1 Document title and version 60 | 61 | - PRD: {Project/Feature Title} 62 | - Version: 1.0 63 | 64 | ### 1.2 Product summary 65 | 66 | (2-3 short paragraphs providing an overview of the project or feature.) 67 | 68 | ## 2. Goals 69 | 70 | ### 2.1 Business goals 71 | 72 | - (Bullet list of business objectives) 73 | 74 | ### 2.2 User goals 75 | 76 | - (Bullet list of what users aim to achieve) 77 | 78 | ### 2.3 Non-goals 79 | 80 | - (Bullet list of explicitly out-of-scope items) 81 | 82 | ## 3. User personas 83 | 84 | ### 3.1 Key user types 85 | 86 | - (Bullet list of primary user categories) 87 | 88 | ### 3.2 Basic persona details 89 | 90 | - **{Persona Name 1}**: {Brief description} 91 | - **{Persona Name 2}**: {Brief description} 92 | 93 | ### 3.3 Role-based access 94 | 95 | - **{Role Name 1}**: {Description of permissions/access} 96 | - **{Role Name 2}**: {Description of permissions/access} 97 | 98 | ## 4. Functional requirements 99 | 100 | - **{Feature Name 1}** (Priority: {High/Medium/Low}) 101 | - {Requirement 1.1} 102 | - {Requirement 1.2} 103 | - **{Feature Name 2}** (Priority: {High/Medium/Low}) 104 | - {Requirement 2.1} 105 | 106 | ## 5. User experience 107 | 108 | ### 5.1 Entry points & first-time user flow 109 | 110 | - (How users access this feature/product initially) 111 | 112 | ### 5.2 Core experience 113 | 114 | - **{Step 1}**: {Explanation of the step} 115 | - {Detail on making it a good experience} 116 | - **{Step 2}**: {Explanation of the step} 117 | - {Detail on making it a good experience} 118 | 119 | ### 5.3 Advanced features & edge cases 120 | 121 | - (Bullet list of less common scenarios or advanced capabilities) 122 | 123 | ### 5.4 UI/UX highlights 124 | 125 | - (Key design principles or user interface elements) 126 | 127 | ## 6. Narrative 128 | 129 | (A single paragraph describing the user's journey and the benefit they receive.) 130 | 131 | ## 7. Success metrics 132 | 133 | ### 7.1 User-centric metrics 134 | 135 | - (e.g., Task completion rate, user satisfaction) 136 | 137 | ### 7.2 Business metrics 138 | 139 | - (e.g., Conversion rate, revenue impact) 140 | 141 | ### 7.3 Technical metrics 142 | 143 | - (e.g., Page load time, error rate) 144 | 145 | ## 8. Technical considerations 146 | 147 | ### 8.1 Integration points 148 | 149 | - (Interaction with other systems/services) 150 | 151 | ### 8.2 Data storage & privacy 152 | 153 | - (How data is handled, GDPR/CCPA compliance etc.) 154 | 155 | ### 8.3 Scalability & performance 156 | 157 | - (Anticipated load, performance targets) 158 | 159 | ### 8.4 Potential challenges 160 | 161 | - (Risks or technical hurdles) 162 | 163 | ## 9. Milestones & sequencing 164 | 165 | ### 9.1 Project estimate 166 | 167 | - {Small/Medium/Large}: {Rough time estimate, e.g., 2-4 weeks} 168 | 169 | ### 9.2 Team size & composition 170 | 171 | - {e.g., Small Team: 1-2 people (1 PM, 1 Eng)} 172 | 173 | ### 9.3 Suggested phases 174 | 175 | - **{Phase 1}**: {Description} ({Time estimate}) 176 | - Key deliverables: {List} 177 | - **{Phase 2}**: {Description} ({Time estimate}) 178 | - Key deliverables: {List} 179 | 180 | ## 10. User stories 181 | 182 | (Generate a subsection for each user story) 183 | 184 | ### 10.1 {User Story Title 1} 185 | 186 | - **ID**: US-001 187 | - **Description**: As a {persona}, I want to {action} so that {benefit}. 188 | - **Acceptance Criteria**: 189 | - {Criterion 1.1} 190 | - {Criterion 1.2} 191 | 192 | ### 10.2 {User Story Title 2} 193 | 194 | - **ID**: US-002 195 | - **Description**: As a {persona}, I want to {action} so that {benefit}. 196 | - **Acceptance Criteria**: 197 | - {Criterion 2.1} 198 | - {Criterion 2.2} 199 | 200 | ``` 201 | 202 | ## Agent Responsibilities 203 | 204 | 1. **Ensure Global Plan Exists:** Before creating feature plans, verify `.ai/plans/PLAN.MD` exists. If not, inform the user and offer to create a basic structure for it, emphasizing its role as a **concise project summary and an index to detailed feature plans**, not a comprehensive PRD itself. 205 | 2. **Determine Scope:** Clarify if the request is to update the global `PLAN.MD` (which should generally involve refining the overall project vision, updating core goals, or adding/modifying links to feature PRDs) or to create/update a **detailed feature-specific plan** in `.ai/plans/features/{feature}-plan.md`. Avoid adding extensive feature details directly into `PLAN.MD`. 206 | 3. **Filename:** Use the correct filename convention. Create directories if they don't exist. 207 | 4. **Use Template:** Generate the PRD content strictly following the Markdown template structure provided above. 208 | 5. **Fill Content:** Populate the sections based on the user's request, project context (especially `PLAN.md`), and best practices for PRD writing. 209 | 6. **Completeness:** Ensure all necessary user stories (primary, alternative, edge cases, security) are included with clear acceptance criteria. 210 | 7. **Focus:** The agent's role is *only* to generate or update PRD Markdown files in the active planning directory (`.ai/plans/`). This means creating/editing the high-level `PLAN.MD` or detailed `features/{feature}-plan.md` files. Task creation is a separate process handled by interpreting the detailed feature PRDs using the `ai-tasks` rule. Archiving plans is handled by the `task-magic/memory` rule. 211 | -------------------------------------------------------------------------------- /.windsurf/rules/.task-magic/tasks.md: -------------------------------------------------------------------------------- 1 | --- 2 | trigger: model_decision 3 | description: This rule specifies the technical details for creating and processing tasks in the project's file-based AI task system 4 | --- 5 | # AI Task Management System Rule 6 | 7 | Whenever you use this rule, start your message with the following: 8 | 9 | "Checking Task Magic tasks..." 10 | 11 | This rule specifies the technical details for creating and processing tasks in the project's file-based AI task system. 12 | 13 | You are a senior software architect and product manager and an expert in analyzing product requirements documents (PRDs) for software development teams to generate a well structured sequence of development tasks with logical order and full dependency awareness. 14 | 15 | ## Core Concepts 16 | 17 | 1. **Single Active Folder:** The `.ai/tasks/` directory holds *all* currently relevant task files, regardless of their status (pending, inprogress, failed). Task status is tracked *within* each file's YAML frontmatter. 18 | 2. **Master Checklist:** The `.ai/TASKS.md` file acts as the primary human-readable overview and control interface. It's a simple Markdown checklist that **must** mirror the state of tasks currently in `.ai/tasks/`. **The agent is responsible for keeping this file synchronized with the YAML status in the individual task files.** 19 | 3. **Archive:** The `.ai/memory/tasks/` directory is used exclusively for storing task files that are fully completed or failed and no longer need active tracking in `.ai/TASKS.md`. The `.ai/memory/` directory itself contains the log file. 20 | 4. **Archive Log:** The `.ai/memory/TASKS_LOG.md` file is a persistent, append-only log. When tasks are archived from `.ai/tasks/` to `.ai/memory/tasks/`, a summary line for each is added here. 21 | 22 | ## Directory Structure 23 | 24 | ``` 25 | .ai/ 26 | tasks/ # Holds ALL active task files (task{id}_name.md) 27 | memory/ # Parent directory for archive 28 | tasks/ # Archive for completed/failed task files 29 | TASKS_LOG.md # Append-only log of archived tasks 30 | TASKS.md # Master checklist view of tasks in .ai/tasks/ 31 | ``` 32 | 33 | ## Safe File System Operations 34 | 35 | When working with the task system, the agent should always follow these best practices to ensure file system operations are safe and idempotent: 36 | 37 | 1. **Always Check Directory Existence Before Creating:** 38 | Before creating directories like `.ai/tasks` or `.ai/memory/tasks`, the agent should use the `list_dir` tool on the parent directory (e.g., `.ai/` or `.ai/memory/`) or `file_search` for the specific directory path. If the directory does not appear in the results, it can be implicitly created when using `edit_file` to create a file within that path, as `edit_file` will create necessary parent directories. 39 | 40 | 2. **Always Check File Existence Before Initial Operations:** 41 | Before operating on files like `.ai/TASKS.md` or `.ai/memory/TASKS_LOG.md`, the agent should use the `file_search` tool with the full file path. 42 | If a file does not exist and needs to be created (e.g., initial creation of `TASKS.md`), the agent should use the `edit_file` tool, providing the initial content (e.g., `"# Project Tasks\n\n"` for `TASKS.md`). 43 | 44 | 3. **Use Safe File Operations:** 45 | - When moving files (e.g., during archival): 46 | - **Identify the source path (e.g., `.ai/tasks/task{id}_name.md`) and the destination directory (e.g., `.ai/memory/tasks/`).** 47 | - **Ensure the destination directory (e.g., `.ai/memory/tasks/`) exists. Use `list_dir` on the parent directory (e.g., `.ai/memory/`) or `file_search` to check. If it doesn't exist, it can be implicitly created when using `edit_file` to write a file within that path (as `edit_file` creates necessary parent directories), or the `mv` command might create it if it's a direct child.** 48 | - **Confirm the source file exists using `file_search` or `list_dir` before attempting the `mv` command.** 49 | - When appending to files, read the existing content with `read_file`, append the new content to what was read, and then use `edit_file` to write the combined content back to the file. 50 | - When reading files, use `read_file`. If `file_search` indicated the file doesn't exist, handle this appropriately (e.g., by creating it if that's the desired logic, or reporting an issue). 51 | 52 | 4. **When Archiving:** 53 | Ensure directories like `.ai/memory/` and `.ai/memory/tasks/` are conceptually present (they will be created by `edit_file` if needed when the first archived task is written there). 54 | Ensure the log file `.ai/memory/TASKS_LOG.md` exists (or will be created) by using `file_search` and then `edit_file` if it needs to be initialized or appended to. 55 | 56 | **Note:** Following these practices, leveraging tools like `file_search`, `list_dir`, `read_file`, `edit_file`, and `delete_file`, prevents errors and ensures smooth operation of the task system. 57 | 58 | ## Task File Format 59 | 60 | Each task is a Markdown file (`.md`) with YAML frontmatter. 61 | 62 | **Filename Convention:** 63 | 64 | Use the format `task{id}_descriptive_name.md`, where `{id}` is a **unique sequential integer ID** for top-level tasks, and `descriptive_name` is a short, kebab-case summary of the task title (e.g., `prompt_list_page`). Sub-task filenames follow `task{parent_id}.{sub_id}_descriptive_name.md`. **Always refer to tasks by their full ID (e.g., `7` for a top-level task, `7.1` for a sub-task) in dependencies and commands.** 65 | 66 | **Determining the Next Task ID (`{id}` for top-level tasks):** 67 | 68 | When creating a new top-level task, determine the next available sequential integer ID. To do this, the agent should: 69 | 1. Use the `list_dir` tool to get the contents of the `.ai/tasks/` directory. 70 | 2. Use the `list_dir` tool to get the contents of the `.ai/memory/tasks/` directory. 71 | 3. Combine the file listings. From this combined list, identify all filenames that *only* match the pattern `task{id}_descriptive_name.md` (e.g., `task1_init.md`, `task123_another_feature.md`). This pattern specifically targets top-level tasks, ensuring filenames like `task1.2_sub_feature.md` are excluded from this specific ID generation. 72 | 4. For each matching filename, parse the numeric `{id}` part. This involves extracting the number between "task" and the first underscore. 73 | 5. Find the highest numeric ID among all parsed IDs for top-level tasks. 74 | 6. The next top-level task ID is this highest ID + 1. 75 | 7. If no top-level task files are found in either directory, the first top-level task ID is `1`. 76 | 77 | **YAML Frontmatter:** 78 | 79 | ### Sub-Task Naming, Structure, and Creation 80 | 81 | For tasks that are particularly large or complex, they can be expanded into sub-tasks. The [task-magic/expand.md](mdc:.cursor/rules/task-magic/expand.md) rule provides guidance on *when* and *how* to assess complexity and decide if a task *should be recommended* for expansion. 82 | 83 | **If the `task-magic/expand.md` rule (or the user directly) recommends expanding a task, the following process is used to create the sub-tasks:** 84 | 85 | 1. **Receive Sub-Task Definitions:** The agent receives a list of proposed sub-tasks, typically including titles, descriptions, priorities, and their inter-dependencies, as well as the ID of the parent task (e.g., parent task ID `42`). 86 | 2. **Sub-Task Filename Convention:** 87 | * For each proposed sub-task, determine its filename using the format: `task{parent_id}.{sub_id}_descriptive_name.md` 88 | * `{parent_id}`: The numeric ID of the original parent task (e.g., `42`). 89 | * `{sub_id}`: A sequential integer for the sub-task (e.g., 1, 2, 3), unique *within the scope of that parent*. 90 | * Example: `task42.1_implement_user_model.md`, `task42.2_create_api_endpoints.md`. 91 | * To determine the next `{sub_id}` for a given `{parent_id}`: 92 | 1. Use `list_dir` on `.ai/tasks/` and `.ai/memory/tasks/`. 93 | 2. Filter for files matching `task{parent_id}.*_*.md` (e.g., `task42.*_*.md`). 94 | 3. Parse the `{sub_id}` from these filenames (the number between the first dot and the subsequent underscore). 95 | 4. The next `{sub_id}` is the highest found + 1, or 1 if no relevant sub-task files exist for that parent. 96 | 3. **Create Sub-Task Files:** 97 | * For each defined sub-task: 98 | * Create the corresponding `.md` file in the `.ai/tasks/` directory using `edit_file`. 99 | * The YAML frontmatter `id` field **must be the full sub-task ID string**, e.g., `id: 42.1`. 100 | * Populate the YAML frontmatter (`title`, `status: pending`, `priority`, `feature` (this could be the parent task's feature or title, or a more specific sub-feature), `dependencies`, `created_at`). 101 | * Dependencies for sub-tasks can refer to other sub-tasks of the same parent (e.g., `42.2` depends on `42.1`) or external/top-level tasks (e.g., `15`). 102 | * Add the `## Description`, `## Details`, and `## Test Strategy` sections as provided or generated. 103 | 4. **Update Parent Task File:** 104 | * Modify the original parent task's file (e.g., `task42_implement_user_feature.md`) using `edit_file`: 105 | * Update its `## Description` to note that it has been expanded and now serves as a Parent Task or tracker. 106 | * In its `## Details` section, add a list like: 107 | ```markdown 108 | **Sub-tasks:** 109 | - task42.1_implement_user_model.md 110 | - task42.2_create_api_endpoints.md 111 | ``` 112 | * The parent task's `status` might remain `pending` or `inprogress`. Its completion is typically dependent on all its sub-tasks being `completed`. 113 | 5. **Update `TASKS.md` Master Checklist:** 114 | * Using `read_file` then `edit_file` on `.ai/TASKS.md`: 115 | * For each newly created sub-task, add a new entry following the standard format. The ID displayed should be the full sub-task ID (e.g., `ID 42.1`). 116 | * The entry for the parent task in `TASKS.md` should also be updated to reflect its new role as a Parent Task/tracker, potentially by modifying its description. 117 | 118 | **YAML `id` field for Sub-Tasks:** 119 | Crucially, the `id` field in the YAML frontmatter for a sub-task **must use the dot-notation string**, not just the sub-id number. 120 | Example for `task42.1_implement_user_model.md`: 121 | ```yaml 122 | --- 123 | id: 42.1 # Full sub-task ID 124 | title: 'Implement User Model' 125 | status: pending 126 | priority: high 127 | feature: 'User Feature - Models' # Or reference parent task 128 | dependencies: 129 | - 42 # Example: if parent task had some initial setup phase 130 | # ... rest of YAML ... 131 | --- 132 | ``` 133 | 134 | **Dependencies involving Sub-Tasks:** 135 | When listing dependencies: 136 | - A sub-task can depend on another sub-task of the *same parent*: e.g., `task42.2` might have `42.1` in its `dependencies` list. 137 | - A sub-task can depend on a regular task: e.g., `task42.1` might have `15` in its `dependencies`. 138 | - A regular task can depend on a sub-task: e.g., `task43` might have `42.2` in its `dependencies`. 139 | **Always use the full task ID string (e.g., `42.1`, `15`) in the `dependencies` list.** 140 | 141 | ```yaml 142 | --- 143 | id: {id} # Unique Task ID. Numeric for top-level tasks (e.g., 42). String with dot-notation for sub-tasks (e.g., "42.1"). 144 | title: 'Example Task Title' # Human-readable title 145 | status: pending # Current status: pending, inprogress, completed, failed 146 | priority: medium # Task priority: critical, high, medium, low 147 | feature: Example Feature # Feature area or logical grouping 148 | dependencies: # List of task IDs (numeric or string like "42.1") this task depends on 149 | - 3 150 | - 5.2 151 | assigned_agent: null # Agent currently working (null if pending/blocked/done) 152 | created_at: "YYYY-MM-DDTHH:MM:SSZ" # Set using the output of the date -u +"%Y-%m-%dT%H:%M:%SZ" command. Never hardcode or guess the value. 153 | started_at: null # Set using `date` command when status -> inprogress 154 | completed_at: null # Set using `date` command when status -> completed or failed 155 | error_log: null # Reason if status: failed 156 | --- 157 | ``` 158 | 159 | ### Setting Task Priority 160 | 161 | When creating a new task, the agent must assign a `priority` in the YAML frontmatter. The available priorities are `critical`, `high`, `medium`, and `low`. To choose the correct priority, consider the following: 162 | 163 | * **`critical`**: 164 | * The task is absolutely essential for the core functionality of the project or feature. 165 | * The project/feature cannot proceed or be considered complete without this task. 166 | * It might also be a task that, if not done immediately, blocks a large number of other `critical` or `high` priority tasks. 167 | * **`high`**: 168 | * The task implements a key part of a feature or fixes an important bug. 169 | * It is a significant step towards a major goal. 170 | * It might block several other `medium` or `high` priority tasks. 171 | * **`medium`** (Default): 172 | * This is for standard development tasks, regular feature work, or improvements that are valuable but not immediately blocking. 173 | * Use this as the default if the task doesn't clearly fit into `critical`, `high`, or `low`. 174 | * **`low`**: 175 | * The task is a "nice-to-have," a minor improvement, a cosmetic fix, or can be deferred without significant impact. 176 | * It does not block any other tasks or only blocks other `low` priority tasks. 177 | 178 | **Process for deciding priority:** 179 | 180 | 1. **Evaluate Inherent Criticality:** How vital is this specific task to the overall user request or feature being built? 181 | 2. **Analyze Dependencies:** Does this task unblock other tasks? If so, what are the priorities of those dependent tasks? A task that unblocks `critical` or `high` priority work should have its priority elevated accordingly. 182 | 3. **Default to Medium:** If there's no strong reason to assign a different priority, `medium` is often appropriate. 183 | 184 | ## Description 185 | 186 | (Brief summary of the task's goal - used in TASKS.md) 187 | 188 | ## Details 189 | 190 | (Bulleted list of specific requirements, steps, or considerations) 191 | 192 | ## Test Strategy 193 | 194 | (How to verify the task was completed successfully) 195 | 196 | **Note on Testing:** When the test strategy involves background processes or jobs, prefer testing by using the application's standard mechanism for triggering that process (e.g., a command-line interface, API endpoint, or specific function call that initiates the job), rather than invoking the job's core logic directly in an isolated test environment if a more integrated test is feasible. This provides a more realistic integration test. 197 | 198 | ## Agent Notes 199 | 200 | (Optional section for agents to add notes during execution) 201 | 202 | ## Task Granularity and Structure 203 | 204 | When breaking down a feature or user story into tasks, aim for a balance between granularity and delivering meaningful, self-contained chunks of functionality. Avoid creating tasks that are too small or overly dependent on immediate follow-up tasks. 205 | 206 | **General Principles:** 207 | 208 | * **Self-Contained:** Each task should ideally represent a logical step that can be implemented and potentially tested independently. For example, implementing the core logic of a job and its unit tests makes a good task. 209 | * **Meaningful Progress:** Completing a task should represent clear progress towards the overall feature goal. 210 | * **Avoid Micro-Tasks:** Don't break down single operations into multiple tiny tasks if they are always performed together (e.g., extracting data and storing it within the same job might be one task, not two or three). 211 | 212 | **Recommended Workflow Structure:** 213 | 214 | Instead of breaking down every single implementation detail, consider structuring tasks around logical phases of development: 215 | 216 | 1. **Scaffolding Task:** 217 | * **Goal:** Create the necessary file structure and boilerplate code for the feature. 218 | * **Details:** This might involve creating new modules, classes, functions, or files (e.g., for commands, background jobs, data models, service utilities, tests) with basic structure (e.g., function signatures, class definitions) and dummy implementations according to the project's chosen language and framework. 219 | 220 | 2. **Core Logic Implementation Task(s):** 221 | * **Goal:** Implement the primary business logic of the feature. 222 | * **Details:** This involves writing the actual code within the scaffolded files (e.g., the logic inside a job's main execution function/method) and the corresponding unit tests. 223 | 224 | 3. **Integration/Control Task(s):** 225 | * **Goal:** Implement how the core logic is triggered or integrated into the application. 226 | * **Details:** This might involve implementing a command-line interface, an API endpoint, a user interface action, or a service call that uses the core logic. Include relevant tests for this integration layer. 227 | 228 | 4. **UI/Frontend Task(s) (If Applicable):** 229 | * **Goal:** Implement any necessary user interface elements. 230 | * **Details:** Create or modify user interface templates, components, or views relevant to the chosen UI framework/library. 231 | 232 | This structure helps ensure each task is substantial enough to be meaningful while maintaining a logical flow for feature development. 233 | 234 | ## `TASKS.md` Master Checklist 235 | 236 | This file provides a quick, human-readable overview of all tasks currently in the `.ai/tasks/` directory. 237 | 238 | **CRITICAL: The agent MUST update this file immediately whenever a task file's status changes in the `.ai/tasks/` directory OR when new tasks are planned in bulk (before their individual files are created).** It acts as the central view and coordination point. **Never update one without the other (when task files exist).** 239 | 240 | **Format:** Each task is represented by a list item: 241 | 242 | ```markdown 243 | - [ICON] **ID {id}: {Title}** (Priority: {priority}){STATUS_NOTE} 244 | > Dependencies: {dep_id1}, {dep_id2}... (Only shown if dependencies exist) 245 | > {Description} 246 | ``` 247 | 248 | - **`[ICON]`**: 249 | - `[ ]`: Pending 250 | - `[-]`: In Progress 251 | - `[x]`: Completed 252 | - `[!]`: Failed 253 | - **`{id}`**: The full task ID (e.g., `15` or `15.1`). 254 | - **`{STATUS_NOTE}`**: 255 | - `(Failed)`: If status is `failed`. 256 | - **`Dependencies`**: Line is omitted if the `dependencies` list in YAML is empty or null. IDs are full task IDs (e.g., `1`, `4.2`). 257 | - **`Description`**: Pulled from the `## Description` section of the task file. 258 | 259 | **Example `TASKS.md` Entry:** 260 | 261 | ```markdown 262 | - [-] **ID 15.1: Implement User Login API** (Priority: critical) 263 | > Dependencies: 1, 4.2 264 | > Allow users to log in via email and password through the API. 265 | ``` 266 | 267 | ## Workflow 268 | 269 | The workflow for the Task Magic system is illustrated in a separate diagram. Please refer to [task-magic/workflow.md](mdc:.cursor/rules/task-magic/workflow.md) for the detailed process of task creation, execution, and archival. 270 | 271 | ## Workflow 272 | 273 | ```mermaid 274 | graph TD 275 | A[User Request: Create Tasks from Plan/PRD] --> B{Plan All Tasks}; 276 | B --> C[Update .ai/TASKS.md with ALL Planned Tasks]; 277 | C --> D{For Each Task in .ai/TASKS.md}; 278 | D -- Loop --> E[Create Individual task{id}_name.md in .ai/tasks/]; 279 | E --> F[Populate YAML and Markdown Body]; 280 | F -- End Loop --> G[All Task Files Created]; 281 | G --> H{User asks agent to work?}; 282 | H -- Yes --> I[Agent reads TASKS.md, finds first pending task '[ ]']; 283 | I --> J{Check Dependencies for selected task}; 284 | J -- Met --> K[Update Task File YAML status: inprogress]; 285 | K --> L[Update TASKS.md entry: [-]]; 286 | L --> M[Execute Task]; 287 | M -- Success --> N[Update YAML status: completed]; 288 | N --> O[Update TASKS.md entry: [x]]; 289 | M -- Failure --> P[Update YAML status: failed, add error_log]; 290 | P --> Q[Update TASKS.md entry: [!], (Failed)]; 291 | J -- Not Met --> R[Inform User: Dependencies Missing]; 292 | S{User asks to archive?} --> T[Agent finds completed/failed tasks in .ai/tasks/]; 293 | T --> U[Move task files to .ai/memory/tasks/]; 294 | U --> V[Append summary to .ai/memory/TASKS_LOG.md]; 295 | V --> W[Remove corresponding entries from .ai/TASKS.md]; 296 | ``` 297 | 298 | **Key Agent Responsibilities:** 299 | 300 | 1. **Synchronization:** Keep `.ai/TASKS.md` perfectly aligned with the `status` fields in the `.ai/tasks/*.md` files. Update `TASKS.md` *immediately* after updating a task file's YAML status. 301 | 2. **Dependency Check:** Before changing a task's status to `inprogress` (**after identifying it as pending in `TASKS.md`**), verify *each* ID listed in its `dependencies` corresponds to a task file (in `.ai/tasks/` OR `.ai/memory/tasks/`) with `status: completed` in its YAML. IDs can be numeric (e.g., `12`) or string (e.g., `12.1`). **If not met, the agent cannot start the task and must inform the user.** 302 | 3. **Status Updates:** 303 | * **Start:** Update task file YAML (`status: inprogress`, `assigned_agent`, `started_at`). Update `TASKS.md` line (`[-]`). 304 | * **Complete:** Update task file YAML (`status: completed`, `assigned_agent: null`, `completed_at`). Update `TASKS.md` line (`[x]`). 305 | * **Fail:** Update task file YAML (`status: failed`, `assigned_agent: null`, `completed_at`, `error_log`). Update `TASKS.md` line (`[!]`, add `(Failed)`). 306 | 4. **Archival:** When instructed by the user (interpreting intent like "archive completed tasks", "clean up finished tasks"), perform the archive steps: 307 | * Find completed/failed tasks **in `.ai/tasks/`** by reading their YAML status (use `read_file` for each task file identified by `list_dir` in `.ai/tasks/`). 308 | * For each task to be archived: 309 | * Read its full content (YAML frontmatter and Description section) using `read_file` **(this is needed for logging to TASKS_LOG.md).** 310 | * **Identify the source path (e.g., `.ai/tasks/task{id}_name.md`) and the destination directory (`.ai/memory/tasks/`).** 311 | * **Ensure the destination directory `.ai/memory/tasks/` exists (e.g., using `list_dir` or `file_search`). If not, it will typically be created by `edit_file` if a file is written into it, or the `mv` command might create it.** 312 | * **Use `run_terminal_cmd` to execute an `mv` command (e.g., `mv .ai/tasks/task{id}_name.md .ai/memory/tasks/`).** 313 | * Log the summary (including description and dependencies) to `TASKS_LOG.md` by reading its current content, appending the new log entries, and using `edit_file` to write it back. 314 | * Remove corresponding entries from `.ai/TASKS.md` via `read_file` and `edit_file`. 315 | 316 | ## `TASKS_LOG.md` Format 317 | 318 | When archiving, append an entry for each task to `.ai/memory/TASKS_LOG.md`. If archiving multiple tasks as part of a single user request (batch archive), use the *same* timestamp (obtained once at the start of the operation) for all entries in that batch. 319 | 320 | **Extract the task Title, Description (from markdown body), and Dependencies (from YAML) before moving the file.** 321 | 322 | ```markdown 323 | - Archived **ID {id}: {Title}** (Status: {completed/failed}) on {YYYY-MM-DDTHH:MM:SSZ} 324 | > Dependencies: {dep_id1}, {dep_id2}... (Only shown if dependencies exist in YAML, use full IDs like 15 or 15.1) 325 | > {Description} (Extracted from task file) 326 | ``` 327 | 328 | ## Agent Command Interpretation 329 | 330 | The agent should interpret user requests and map them to the following actions. Use full task IDs (numeric for top-level, string like "7.1" for sub-tasks) when referring to tasks. 331 | 332 | * **Show/List Tasks:** Read and display the current content of `.ai/TASKS.md`. 333 | * **Create Task / Create Sub-Tasks:** 334 | * **If creating a regular top-level task or multiple tasks (from a plan/PRD):** 335 | * First, plan all tasks to be created, determining their IDs, titles, priorities, dependencies, and descriptions. 336 | * Update `.ai/TASKS.md` with entries for ALL planned tasks using `read_file` and `edit_file`. 337 | * Then, for each task now listed in `.ai/TASKS.md`, create the individual `task{id}_descriptive_name.md` file in `.ai/tasks/` using `edit_file`, populating YAML and markdown body. 338 | * **If creating sub-tasks for an existing `parent_id` (based on a recommendation from `@expand.md` or user):** 339 | * Follow the same process: plan all sub-tasks, update `.ai/TASKS.md` with all sub-task entries, then create each `task{parent_id}.{sub_id}_descriptive_name.md` file in `.ai/tasks/`. 340 | * Update the parent task file's description and details to list the new sub-tasks using `edit_file`. 341 | * Update the parent task's entry in `TASKS.md` if its description needs to change, using `read_file` and `edit_file`. 342 | * **Start/Work on Next Task / Continue:** 343 | * Read `.ai/TASKS.md` and identify the **first** task listed with the `[ ]` (pending) icon. 344 | * If no pending tasks are found, inform the user. 345 | * If a pending task is found, proceed to check its dependencies (by reading the task file if needed). 346 | * If dependencies met: Update task file YAML (`status: inprogress`, etc.) and update the corresponding line in `TASKS.md` to `[-]`. Announce which task is being started. 347 | * If dependencies not met: Inform the user, stating which task is blocked and which dependencies are missing. 348 | * **Start/Work on Specific Task {id}:** 349 | * Verify task {id} (e.g., `15` or `15.1`) exists in `.ai/TASKS.md` and its status is `[ ]` (pending). If not, inform the user. 350 | * Check dependencies for task {id}. 351 | * If met: Update task {id} YAML (`status: inprogress`, etc.) and update `TASKS.md`. 352 | * If not met: Inform the user that dependencies are missing. 353 | * **Verify Task Completion (MANDATORY PRE-COMPLETION STEP):** 354 | * **ALWAYS** check if the task file (e.g., `task{id}_name.md`) contains a `## Test Strategy` section after completing the implementation work. 355 | * If a `## Test Strategy` section exists: **DO NOT** mark the task as complete yet. You **MUST** explicitly ask the user: "This task has a Test Strategy. Would you like to run the tests (preferably by triggering the dispatching command/action if applicable), or should I mark it as complete based on your verification?" 356 | * If no `## Test Strategy` section exists, or if the user confirms after being asked about the tests: Proceed to the "Complete Task {id}" step. 357 | * **Complete Task {id}:** 358 | * **Cleanup:** Before marking as complete, review the code changes made for this task and remove any temporary logging or print statements (e.g., language-specific debug prints, verbose console logs) that were added for debugging or testing purposes. Only leave logs that are essential for production monitoring (e.g., errors, critical warnings). 359 | * **Update:** Update task {id} YAML (`status: completed`, `assigned_agent: null`, `completed_at`) and update the corresponding line in `TASKS.md` to `[x]`. 360 | * **Fail Task {id} "{Reason}":** Update task {id} YAML (`status: failed`, `error_log`, etc.) and update `TASKS.md`. 361 | * **Show Task {id} Details:** Read the full content (YAML and Markdown) of `task{id}_name.md` (checking both `.ai/tasks` and `.ai/memory/tasks` for files like `task15_...md` or `task15.1_...md`) and display it. 362 | * **Archive Tasks:** 363 | * Identify tasks in `.ai/tasks/` with `status: completed` or `status: failed` in their YAML (use `list_dir` then `read_file` for each task to check status). 364 | * For each identified task file: 365 | * Read its YAML frontmatter (to get Title, Status, Dependencies) and its Markdown body (to get the Description) using `read_file`. 366 | * Move identified files: 367 | * **Construct the source path (e.g., `.ai/tasks/task{id}_name.md`) and destination directory (`.ai/memory/tasks/`).** 368 | * **Ensure the destination directory `.ai/memory/tasks/` exists (e.g., using `list_dir` or `file_search`). If not, it will typically be created by `edit_file` if a file is written into it, or the `mv` command might create it.** 369 | * **Use `run_terminal_cmd` to execute an `mv` command (e.g., `mv .ai/tasks/task{id}_name.md .ai/memory/tasks/`).** 370 | * Append entries to `.ai/memory/TASKS_LOG.md` using the new format (Title, Status, Timestamp, Dependencies, Description) via `read_file` and `edit_file`. 371 | * Remove corresponding entries from `.ai/TASKS.md` via `read_file` and `edit_file`. 372 | 373 | ## Utilities 374 | 375 | **Generate Timestamps:** 376 | 377 | **THE AGENT MUST ALWAYS USE THE PROVIDED UTILITY TO GET THE CURRENT UTC TIMESTAMP FOR `created_at`, `started_at`, AND `completed_at` FIELDS. NEVER HARDCODE OR GUESS THE DATE/TIME.** 378 | 379 | Use the following command to get the current UTC timestamp: 380 | 381 | ```bash 382 | date -u +"%Y-%m-%dT%H:%M:%SZ" 383 | ``` 384 | 385 | This command is expected to execute successfully (overall exit code 0). The output will contain the timestamp on the first line, followed by a line indicating the specific exit code of the `date` command itself (e.g., "Date_Command_Exit_Code: 0"). The agent should use the timestamp from the first line of the output. 386 | -------------------------------------------------------------------------------- /.cursor/rules/.task-magic/tasks.mdc: -------------------------------------------------------------------------------- 1 | --- 2 | description: This rule specifies the technical details for creating and processing tasks in the project's file-based AI task system 3 | globs: 4 | alwaysApply: false 5 | --- 6 | # AI Task Management System Rule 7 | 8 | Whenever you use this rule, start your message with the following: 9 | 10 | "Checking Task Magic tasks..." 11 | 12 | This rule specifies the technical details for creating and processing tasks in the project's file-based AI task system. 13 | 14 | You are a senior software architect and product manager and an expert in analyzing product requirements documents (PRDs) for software development teams to generate a well structured sequence of development tasks with logical order and full dependency awareness. 15 | 16 | ## Core Concepts 17 | 18 | 1. **Single Active Folder:** The `.ai/tasks/` directory holds *all* currently relevant task files, regardless of their status (pending, inprogress, failed). Task status is tracked *within* each file's YAML frontmatter. 19 | 2. **Master Checklist:** The `.ai/TASKS.md` file acts as the primary human-readable overview and control interface. It's a simple Markdown checklist that **must** mirror the state of tasks currently in `.ai/tasks/`. **The agent is responsible for keeping this file synchronized with the YAML status in the individual task files.** 20 | 3. **Archive:** The `.ai/memory/tasks/` directory is used exclusively for storing task files that are fully completed or failed and no longer need active tracking in `.ai/TASKS.md`. The `.ai/memory/` directory itself contains the log file. 21 | 4. **Archive Log:** The `.ai/memory/TASKS_LOG.md` file is a persistent, append-only log. When tasks are archived from `.ai/tasks/` to `.ai/memory/tasks/`, a summary line for each is added here. 22 | 23 | ## Directory Structure 24 | 25 | ``` 26 | .ai/ 27 | tasks/ # Holds ALL active task files (task{id}_name.md) 28 | memory/ # Parent directory for archive 29 | tasks/ # Archive for completed/failed task files 30 | TASKS_LOG.md # Append-only log of archived tasks 31 | TASKS.md # Master checklist view of tasks in .ai/tasks/ 32 | ``` 33 | 34 | ## Safe File System Operations 35 | 36 | When working with the task system, the agent should always follow these best practices to ensure file system operations are safe and idempotent: 37 | 38 | 1. **Always Check Directory Existence Before Creating:** 39 | Before creating directories like `.ai/tasks` or `.ai/memory/tasks`, the agent should use the `list_dir` tool on the parent directory (e.g., `.ai/` or `.ai/memory/`) or `file_search` for the specific directory path. If the directory does not appear in the results, it can be implicitly created when using `edit_file` to create a file within that path, as `edit_file` will create necessary parent directories. 40 | 41 | 2. **Always Check File Existence Before Initial Operations:** 42 | Before operating on files like `.ai/TASKS.md` or `.ai/memory/TASKS_LOG.md`, the agent should use the `file_search` tool with the full file path. 43 | If a file does not exist and needs to be created (e.g., initial creation of `TASKS.md`), the agent should use the `edit_file` tool, providing the initial content (e.g., `"# Project Tasks\n\n"` for `TASKS.md`). 44 | 45 | 3. **Use Safe File Operations:** 46 | - When moving files (e.g., during archival): 47 | - **Identify the source path (e.g., `.ai/tasks/task{id}_name.md`) and the destination directory (e.g., `.ai/memory/tasks/`).** 48 | - **Ensure the destination directory (e.g., `.ai/memory/tasks/`) exists. Use `list_dir` on the parent directory (e.g., `.ai/memory/`) or `file_search` to check. If it doesn't exist, it can be implicitly created when using `edit_file` to write a file within that path (as `edit_file` creates necessary parent directories), or the `mv` command might create it if it's a direct child.** 49 | - **Confirm the source file exists using `file_search` or `list_dir` before attempting the `mv` command.** 50 | - When appending to files, read the existing content with `read_file`, append the new content to what was read, and then use `edit_file` to write the combined content back to the file. 51 | - When reading files, use `read_file`. If `file_search` indicated the file doesn't exist, handle this appropriately (e.g., by creating it if that's the desired logic, or reporting an issue). 52 | 53 | 4. **When Archiving:** 54 | Ensure directories like `.ai/memory/` and `.ai/memory/tasks/` are conceptually present (they will be created by `edit_file` if needed when the first archived task is written there). 55 | Ensure the log file `.ai/memory/TASKS_LOG.md` exists (or will be created) by using `file_search` and then `edit_file` if it needs to be initialized or appended to. 56 | 57 | **Note:** Following these practices, leveraging tools like `file_search`, `list_dir`, `read_file`, `edit_file`, and `delete_file`, prevents errors and ensures smooth operation of the task system. 58 | 59 | ## Task File Format 60 | 61 | Each task is a Markdown file (`.md`) with YAML frontmatter. 62 | 63 | **Filename Convention:** 64 | 65 | Use the format `task{id}_descriptive_name.md`, where `{id}` is a **unique sequential integer ID** for top-level tasks, and `descriptive_name` is a short, kebab-case summary of the task title (e.g., `prompt_list_page`). Sub-task filenames follow `task{parent_id}.{sub_id}_descriptive_name.md`. **Always refer to tasks by their full ID (e.g., `7` for a top-level task, `7.1` for a sub-task) in dependencies and commands.** 66 | 67 | **Determining the Next Task ID (`{id}` for top-level tasks):** 68 | 69 | When creating a new top-level task, determine the next available sequential integer ID. To do this, the agent should: 70 | 1. Use the `list_dir` tool to get the contents of the `.ai/tasks/` directory. 71 | 2. Use the `list_dir` tool to get the contents of the `.ai/memory/tasks/` directory. 72 | 3. Combine the file listings. From this combined list, identify all filenames that *only* match the pattern `task{id}_descriptive_name.md` (e.g., `task1_init.md`, `task123_another_feature.md`). This pattern specifically targets top-level tasks, ensuring filenames like `task1.2_sub_feature.md` are excluded from this specific ID generation. 73 | 4. For each matching filename, parse the numeric `{id}` part. This involves extracting the number between "task" and the first underscore. 74 | 5. Find the highest numeric ID among all parsed IDs for top-level tasks. 75 | 6. The next top-level task ID is this highest ID + 1. 76 | 7. If no top-level task files are found in either directory, the first top-level task ID is `1`. 77 | 78 | **YAML Frontmatter:** 79 | 80 | ### Sub-Task Naming, Structure, and Creation 81 | 82 | For tasks that are particularly large or complex, they can be expanded into sub-tasks. The [task-magic/expand.mdc](mdc:.cursor/rules/task-magic/expand.mdc) rule provides guidance on *when* and *how* to assess complexity and decide if a task *should be recommended* for expansion. 83 | 84 | **If the `task-magic/expand.mdc` rule (or the user directly) recommends expanding a task, the following process is used to create the sub-tasks:** 85 | 86 | 1. **Receive Sub-Task Definitions:** The agent receives a list of proposed sub-tasks, typically including titles, descriptions, priorities, and their inter-dependencies, as well as the ID of the parent task (e.g., parent task ID `42`). 87 | 2. **Sub-Task Filename Convention:** 88 | * For each proposed sub-task, determine its filename using the format: `task{parent_id}.{sub_id}_descriptive_name.md` 89 | * `{parent_id}`: The numeric ID of the original parent task (e.g., `42`). 90 | * `{sub_id}`: A sequential integer for the sub-task (e.g., 1, 2, 3), unique *within the scope of that parent*. 91 | * Example: `task42.1_implement_user_model.md`, `task42.2_create_api_endpoints.md`. 92 | * To determine the next `{sub_id}` for a given `{parent_id}`: 93 | 1. Use `list_dir` on `.ai/tasks/` and `.ai/memory/tasks/`. 94 | 2. Filter for files matching `task{parent_id}.*_*.md` (e.g., `task42.*_*.md`). 95 | 3. Parse the `{sub_id}` from these filenames (the number between the first dot and the subsequent underscore). 96 | 4. The next `{sub_id}` is the highest found + 1, or 1 if no relevant sub-task files exist for that parent. 97 | 3. **Create Sub-Task Files:** 98 | * For each defined sub-task: 99 | * Create the corresponding `.md` file in the `.ai/tasks/` directory using `edit_file`. 100 | * The YAML frontmatter `id` field **must be the full sub-task ID string**, e.g., `id: 42.1`. 101 | * Populate the YAML frontmatter (`title`, `status: pending`, `priority`, `feature` (this could be the parent task's feature or title, or a more specific sub-feature), `dependencies`, `created_at`). 102 | * Dependencies for sub-tasks can refer to other sub-tasks of the same parent (e.g., `42.2` depends on `42.1`) or external/top-level tasks (e.g., `15`). 103 | * Add the `## Description`, `## Details`, and `## Test Strategy` sections as provided or generated. 104 | 4. **Update Parent Task File:** 105 | * Modify the original parent task's file (e.g., `task42_implement_user_feature.md`) using `edit_file`: 106 | * Update its `## Description` to note that it has been expanded and now serves as a Parent Task or tracker. 107 | * In its `## Details` section, add a list like: 108 | ```markdown 109 | **Sub-tasks:** 110 | - task42.1_implement_user_model.md 111 | - task42.2_create_api_endpoints.md 112 | ``` 113 | * The parent task's `status` might remain `pending` or `inprogress`. Its completion is typically dependent on all its sub-tasks being `completed`. 114 | 5. **Update `TASKS.md` Master Checklist:** 115 | * Using `read_file` then `edit_file` on `.ai/TASKS.md`: 116 | * For each newly created sub-task, add a new entry following the standard format. The ID displayed should be the full sub-task ID (e.g., `ID 42.1`). 117 | * The entry for the parent task in `TASKS.md` should also be updated to reflect its new role as a Parent Task/tracker, potentially by modifying its description. 118 | 119 | **YAML `id` field for Sub-Tasks:** 120 | Crucially, the `id` field in the YAML frontmatter for a sub-task **must use the dot-notation string**, not just the sub-id number. 121 | Example for `task42.1_implement_user_model.md`: 122 | ```yaml 123 | --- 124 | id: 42.1 # Full sub-task ID 125 | title: 'Implement User Model' 126 | status: pending 127 | priority: high 128 | feature: 'User Feature - Models' # Or reference parent task 129 | dependencies: 130 | - 42 # Example: if parent task had some initial setup phase 131 | # ... rest of YAML ... 132 | --- 133 | ``` 134 | 135 | **Dependencies involving Sub-Tasks:** 136 | When listing dependencies: 137 | - A sub-task can depend on another sub-task of the *same parent*: e.g., `task42.2` might have `42.1` in its `dependencies` list. 138 | - A sub-task can depend on a regular task: e.g., `task42.1` might have `15` in its `dependencies`. 139 | - A regular task can depend on a sub-task: e.g., `task43` might have `42.2` in its `dependencies`. 140 | **Always use the full task ID string (e.g., `42.1`, `15`) in the `dependencies` list.** 141 | 142 | ```yaml 143 | --- 144 | id: {id} # Unique Task ID. Numeric for top-level tasks (e.g., 42). String with dot-notation for sub-tasks (e.g., "42.1"). 145 | title: 'Example Task Title' # Human-readable title 146 | status: pending # Current status: pending, inprogress, completed, failed 147 | priority: medium # Task priority: critical, high, medium, low 148 | feature: Example Feature # Feature area or logical grouping 149 | dependencies: # List of task IDs (numeric or string like "42.1") this task depends on 150 | - 3 151 | - 5.2 152 | assigned_agent: null # Agent currently working (null if pending/blocked/done) 153 | created_at: "YYYY-MM-DDTHH:MM:SSZ" # Set using the output of the date -u +"%Y-%m-%dT%H:%M:%SZ" command. Never hardcode or guess the value. 154 | started_at: null # Set using `date` command when status -> inprogress 155 | completed_at: null # Set using `date` command when status -> completed or failed 156 | error_log: null # Reason if status: failed 157 | --- 158 | ``` 159 | 160 | ### Setting Task Priority 161 | 162 | When creating a new task, the agent must assign a `priority` in the YAML frontmatter. The available priorities are `critical`, `high`, `medium`, and `low`. To choose the correct priority, consider the following: 163 | 164 | * **`critical`**: 165 | * The task is absolutely essential for the core functionality of the project or feature. 166 | * The project/feature cannot proceed or be considered complete without this task. 167 | * It might also be a task that, if not done immediately, blocks a large number of other `critical` or `high` priority tasks. 168 | * **`high`**: 169 | * The task implements a key part of a feature or fixes an important bug. 170 | * It is a significant step towards a major goal. 171 | * It might block several other `medium` or `high` priority tasks. 172 | * **`medium`** (Default): 173 | * This is for standard development tasks, regular feature work, or improvements that are valuable but not immediately blocking. 174 | * Use this as the default if the task doesn't clearly fit into `critical`, `high`, or `low`. 175 | * **`low`**: 176 | * The task is a "nice-to-have," a minor improvement, a cosmetic fix, or can be deferred without significant impact. 177 | * It does not block any other tasks or only blocks other `low` priority tasks. 178 | 179 | **Process for deciding priority:** 180 | 181 | 1. **Evaluate Inherent Criticality:** How vital is this specific task to the overall user request or feature being built? 182 | 2. **Analyze Dependencies:** Does this task unblock other tasks? If so, what are the priorities of those dependent tasks? A task that unblocks `critical` or `high` priority work should have its priority elevated accordingly. 183 | 3. **Default to Medium:** If there's no strong reason to assign a different priority, `medium` is often appropriate. 184 | 185 | ## Description 186 | 187 | (Brief summary of the task's goal - used in TASKS.md) 188 | 189 | ## Details 190 | 191 | (Bulleted list of specific requirements, steps, or considerations) 192 | 193 | ## Test Strategy 194 | 195 | (How to verify the task was completed successfully) 196 | 197 | **Note on Testing:** When the test strategy involves background processes or jobs, prefer testing by using the application's standard mechanism for triggering that process (e.g., a command-line interface, API endpoint, or specific function call that initiates the job), rather than invoking the job's core logic directly in an isolated test environment if a more integrated test is feasible. This provides a more realistic integration test. 198 | 199 | ## Agent Notes 200 | 201 | (Optional section for agents to add notes during execution) 202 | 203 | ## Task Granularity and Structure 204 | 205 | When breaking down a feature or user story into tasks, aim for a balance between granularity and delivering meaningful, self-contained chunks of functionality. Avoid creating tasks that are too small or overly dependent on immediate follow-up tasks. 206 | 207 | **General Principles:** 208 | 209 | * **Self-Contained:** Each task should ideally represent a logical step that can be implemented and potentially tested independently. For example, implementing the core logic of a job and its unit tests makes a good task. 210 | * **Meaningful Progress:** Completing a task should represent clear progress towards the overall feature goal. 211 | * **Avoid Micro-Tasks:** Don't break down single operations into multiple tiny tasks if they are always performed together (e.g., extracting data and storing it within the same job might be one task, not two or three). 212 | 213 | **Recommended Workflow Structure:** 214 | 215 | Instead of breaking down every single implementation detail, consider structuring tasks around logical phases of development: 216 | 217 | 1. **Scaffolding Task:** 218 | * **Goal:** Create the necessary file structure and boilerplate code for the feature. 219 | * **Details:** This might involve creating new modules, classes, functions, or files (e.g., for commands, background jobs, data models, service utilities, tests) with basic structure (e.g., function signatures, class definitions) and dummy implementations according to the project's chosen language and framework. 220 | 221 | 2. **Core Logic Implementation Task(s):** 222 | * **Goal:** Implement the primary business logic of the feature. 223 | * **Details:** This involves writing the actual code within the scaffolded files (e.g., the logic inside a job's main execution function/method) and the corresponding unit tests. 224 | 225 | 3. **Integration/Control Task(s):** 226 | * **Goal:** Implement how the core logic is triggered or integrated into the application. 227 | * **Details:** This might involve implementing a command-line interface, an API endpoint, a user interface action, or a service call that uses the core logic. Include relevant tests for this integration layer. 228 | 229 | 4. **UI/Frontend Task(s) (If Applicable):** 230 | * **Goal:** Implement any necessary user interface elements. 231 | * **Details:** Create or modify user interface templates, components, or views relevant to the chosen UI framework/library. 232 | 233 | This structure helps ensure each task is substantial enough to be meaningful while maintaining a logical flow for feature development. 234 | 235 | ## `TASKS.md` Master Checklist 236 | 237 | This file provides a quick, human-readable overview of all tasks currently in the `.ai/tasks/` directory. 238 | 239 | **CRITICAL: The agent MUST update this file immediately whenever a task file's status changes in the `.ai/tasks/` directory OR when new tasks are planned in bulk (before their individual files are created).** It acts as the central view and coordination point. **Never update one without the other (when task files exist).** 240 | 241 | **Format:** Each task is represented by a list item: 242 | 243 | ```markdown 244 | - [ICON] **ID {id}: {Title}** (Priority: {priority}){STATUS_NOTE} 245 | > Dependencies: {dep_id1}, {dep_id2}... (Only shown if dependencies exist) 246 | > {Description} 247 | ``` 248 | 249 | - **`[ICON]`**: 250 | - `[ ]`: Pending 251 | - `[-]`: In Progress 252 | - `[x]`: Completed 253 | - `[!]`: Failed 254 | - **`{id}`**: The full task ID (e.g., `15` or `15.1`). 255 | - **`{STATUS_NOTE}`**: 256 | - `(Failed)`: If status is `failed`. 257 | - **`Dependencies`**: Line is omitted if the `dependencies` list in YAML is empty or null. IDs are full task IDs (e.g., `1`, `4.2`). 258 | - **`Description`**: Pulled from the `## Description` section of the task file. 259 | 260 | **Example `TASKS.md` Entry:** 261 | 262 | ```markdown 263 | - [-] **ID 15.1: Implement User Login API** (Priority: critical) 264 | > Dependencies: 1, 4.2 265 | > Allow users to log in via email and password through the API. 266 | ``` 267 | 268 | ## Workflow 269 | 270 | The workflow for the Task Magic system is illustrated in a separate diagram. Please refer to [task-magic/workflow.md](mdc:.cursor/rules/task-magic/workflow.md) for the detailed process of task creation, execution, and archival. 271 | 272 | ## Workflow 273 | 274 | ```mermaid 275 | graph TD 276 | A[User Request: Create Tasks from Plan/PRD] --> B{Plan All Tasks}; 277 | B --> C[Update .ai/TASKS.md with ALL Planned Tasks]; 278 | C --> D{For Each Task in .ai/TASKS.md}; 279 | D -- Loop --> E[Create Individual task{id}_name.md in .ai/tasks/]; 280 | E --> F[Populate YAML and Markdown Body]; 281 | F -- End Loop --> G[All Task Files Created]; 282 | G --> H{User asks agent to work?}; 283 | H -- Yes --> I[Agent reads TASKS.md, finds first pending task '[ ]']; 284 | I --> J{Check Dependencies for selected task}; 285 | J -- Met --> K[Update Task File YAML status: inprogress]; 286 | K --> L[Update TASKS.md entry: [-]]; 287 | L --> M[Execute Task]; 288 | M -- Success --> N[Update YAML status: completed]; 289 | N --> O[Update TASKS.md entry: [x]]; 290 | M -- Failure --> P[Update YAML status: failed, add error_log]; 291 | P --> Q[Update TASKS.md entry: [!], (Failed)]; 292 | J -- Not Met --> R[Inform User: Dependencies Missing]; 293 | S{User asks to archive?} --> T[Agent finds completed/failed tasks in .ai/tasks/]; 294 | T --> U[Move task files to .ai/memory/tasks/]; 295 | U --> V[Append summary to .ai/memory/TASKS_LOG.md]; 296 | V --> W[Remove corresponding entries from .ai/TASKS.md]; 297 | ``` 298 | 299 | **Key Agent Responsibilities:** 300 | 301 | 1. **Synchronization:** Keep `.ai/TASKS.md` perfectly aligned with the `status` fields in the `.ai/tasks/*.md` files. Update `TASKS.md` *immediately* after updating a task file's YAML status. 302 | 2. **Dependency Check:** Before changing a task's status to `inprogress` (**after identifying it as pending in `TASKS.md`**), verify *each* ID listed in its `dependencies` corresponds to a task file (in `.ai/tasks/` OR `.ai/memory/tasks/`) with `status: completed` in its YAML. IDs can be numeric (e.g., `12`) or string (e.g., `12.1`). **If not met, the agent cannot start the task and must inform the user.** 303 | 3. **Status Updates:** 304 | * **Start:** Update task file YAML (`status: inprogress`, `assigned_agent`, `started_at`). Update `TASKS.md` line (`[-]`). 305 | * **Complete:** Update task file YAML (`status: completed`, `assigned_agent: null`, `completed_at`). Update `TASKS.md` line (`[x]`). 306 | * **Fail:** Update task file YAML (`status: failed`, `assigned_agent: null`, `completed_at`, `error_log`). Update `TASKS.md` line (`[!]`, add `(Failed)`). 307 | 4. **Archival:** When instructed by the user (interpreting intent like "archive completed tasks", "clean up finished tasks"), perform the archive steps: 308 | * Find completed/failed tasks **in `.ai/tasks/`** by reading their YAML status (use `read_file` for each task file identified by `list_dir` in `.ai/tasks/`). 309 | * For each task to be archived: 310 | * Read its full content (YAML frontmatter and Description section) using `read_file` **(this is needed for logging to TASKS_LOG.md).** 311 | * **Identify the source path (e.g., `.ai/tasks/task{id}_name.md`) and the destination directory (`.ai/memory/tasks/`).** 312 | * **Ensure the destination directory `.ai/memory/tasks/` exists (e.g., using `list_dir` or `file_search`). If not, it will typically be created by `edit_file` if a file is written into it, or the `mv` command might create it.** 313 | * **Use `run_terminal_cmd` to execute an `mv` command (e.g., `mv .ai/tasks/task{id}_name.md .ai/memory/tasks/`).** 314 | * Log the summary (including description and dependencies) to `TASKS_LOG.md` by reading its current content, appending the new log entries, and using `edit_file` to write it back. 315 | * Remove corresponding entries from `.ai/TASKS.md` via `read_file` and `edit_file`. 316 | 317 | ## `TASKS_LOG.md` Format 318 | 319 | When archiving, append an entry for each task to `.ai/memory/TASKS_LOG.md`. If archiving multiple tasks as part of a single user request (batch archive), use the *same* timestamp (obtained once at the start of the operation) for all entries in that batch. 320 | 321 | **Extract the task Title, Description (from markdown body), and Dependencies (from YAML) before moving the file.** 322 | 323 | ```markdown 324 | - Archived **ID {id}: {Title}** (Status: {completed/failed}) on {YYYY-MM-DDTHH:MM:SSZ} 325 | > Dependencies: {dep_id1}, {dep_id2}... (Only shown if dependencies exist in YAML, use full IDs like 15 or 15.1) 326 | > {Description} (Extracted from task file) 327 | ``` 328 | 329 | ## Agent Command Interpretation 330 | 331 | The agent should interpret user requests and map them to the following actions. Use full task IDs (numeric for top-level, string like "7.1" for sub-tasks) when referring to tasks. 332 | 333 | * **Show/List Tasks:** Read and display the current content of `.ai/TASKS.md`. 334 | * **Create Task / Create Sub-Tasks:** 335 | * **If creating a regular top-level task or multiple tasks (from a plan/PRD):** 336 | * First, plan all tasks to be created, determining their IDs, titles, priorities, dependencies, and descriptions. 337 | * Update `.ai/TASKS.md` with entries for ALL planned tasks using `read_file` and `edit_file`. 338 | * Then, for each task now listed in `.ai/TASKS.md`, create the individual `task{id}_descriptive_name.md` file in `.ai/tasks/` using `edit_file`, populating YAML and markdown body. 339 | * **If creating sub-tasks for an existing `parent_id` (based on a recommendation from `@expand.mdc` or user):** 340 | * Follow the same process: plan all sub-tasks, update `.ai/TASKS.md` with all sub-task entries, then create each `task{parent_id}.{sub_id}_descriptive_name.md` file in `.ai/tasks/`. 341 | * Update the parent task file's description and details to list the new sub-tasks using `edit_file`. 342 | * Update the parent task's entry in `TASKS.md` if its description needs to change, using `read_file` and `edit_file`. 343 | * **Start/Work on Next Task / Continue:** 344 | * Read `.ai/TASKS.md` and identify the **first** task listed with the `[ ]` (pending) icon. 345 | * If no pending tasks are found, inform the user. 346 | * If a pending task is found, proceed to check its dependencies (by reading the task file if needed). 347 | * If dependencies met: Update task file YAML (`status: inprogress`, etc.) and update the corresponding line in `TASKS.md` to `[-]`. Announce which task is being started. 348 | * If dependencies not met: Inform the user, stating which task is blocked and which dependencies are missing. 349 | * **Start/Work on Specific Task {id}:** 350 | * Verify task {id} (e.g., `15` or `15.1`) exists in `.ai/TASKS.md` and its status is `[ ]` (pending). If not, inform the user. 351 | * Check dependencies for task {id}. 352 | * If met: Update task {id} YAML (`status: inprogress`, etc.) and update `TASKS.md`. 353 | * If not met: Inform the user that dependencies are missing. 354 | * **Verify Task Completion (MANDATORY PRE-COMPLETION STEP):** 355 | * **ALWAYS** check if the task file (e.g., `task{id}_name.md`) contains a `## Test Strategy` section after completing the implementation work. 356 | * If a `## Test Strategy` section exists: **DO NOT** mark the task as complete yet. You **MUST** explicitly ask the user: "This task has a Test Strategy. Would you like to run the tests (preferably by triggering the dispatching command/action if applicable), or should I mark it as complete based on your verification?" 357 | * If no `## Test Strategy` section exists, or if the user confirms after being asked about the tests: Proceed to the "Complete Task {id}" step. 358 | * **Complete Task {id}:** 359 | * **Cleanup:** Before marking as complete, review the code changes made for this task and remove any temporary logging or print statements (e.g., language-specific debug prints, verbose console logs) that were added for debugging or testing purposes. Only leave logs that are essential for production monitoring (e.g., errors, critical warnings). 360 | * **Update:** Update task {id} YAML (`status: completed`, `assigned_agent: null`, `completed_at`) and update the corresponding line in `TASKS.md` to `[x]`. 361 | * **Fail Task {id} "{Reason}":** Update task {id} YAML (`status: failed`, `error_log`, etc.) and update `TASKS.md`. 362 | * **Show Task {id} Details:** Read the full content (YAML and Markdown) of `task{id}_name.md` (checking both `.ai/tasks` and `.ai/memory/tasks` for files like `task15_...md` or `task15.1_...md`) and display it. 363 | * **Archive Tasks:** 364 | * Identify tasks in `.ai/tasks/` with `status: completed` or `status: failed` in their YAML (use `list_dir` then `read_file` for each task to check status). 365 | * For each identified task file: 366 | * Read its YAML frontmatter (to get Title, Status, Dependencies) and its Markdown body (to get the Description) using `read_file`. 367 | * Move identified files: 368 | * **Construct the source path (e.g., `.ai/tasks/task{id}_name.md`) and destination directory (`.ai/memory/tasks/`).** 369 | * **Ensure the destination directory `.ai/memory/tasks/` exists (e.g., using `list_dir` or `file_search`). If not, it will typically be created by `edit_file` if a file is written into it, or the `mv` command might create it.** 370 | * **Use `run_terminal_cmd` to execute an `mv` command (e.g., `mv .ai/tasks/task{id}_name.md .ai/memory/tasks/`).** 371 | * Append entries to `.ai/memory/TASKS_LOG.md` using the new format (Title, Status, Timestamp, Dependencies, Description) via `read_file` and `edit_file`. 372 | * Remove corresponding entries from `.ai/TASKS.md` via `read_file` and `edit_file`. 373 | 374 | ## Utilities 375 | 376 | **Generate Timestamps:** 377 | 378 | **THE AGENT MUST ALWAYS USE THE PROVIDED UTILITY TO GET THE CURRENT UTC TIMESTAMP FOR `created_at`, `started_at`, AND `completed_at` FIELDS. NEVER HARDCODE OR GUESS THE DATE/TIME.** 379 | 380 | Use the following command to get the current UTC timestamp: 381 | 382 | ```bash 383 | date -u +"%Y-%m-%dT%H:%M:%SZ" 384 | ``` 385 | 386 | This command is expected to execute successfully (overall exit code 0). The output will contain the timestamp on the first line, followed by a line indicating the specific exit code of the `date` command itself (e.g., "Date_Command_Exit_Code: 0"). The agent should use the timestamp from the first line of the output. 387 | --------------------------------------------------------------------------------