description: guide the Cursor Agent in using the meta-development script (scripts/dev.js). It also defines the overall workflow for reading, updating, and generating tasks during AI-driven development.
- name: "Meta Development Workflow for Cursor Agent"
description: >
Provides comprehensive guidelines on how the agent (Cursor) should coordinate
with the meta task script in scripts/dev.js. The agent will call
these commands at various points in the coding process to keep
tasks.json up to date and maintain a single source of truth for development tasks.
triggers:
# Potential triggers or states in Cursor where these rules apply.
# You may list relevant event names, e.g., "onTaskCompletion" or "onUserCommand"
- always
steps:
- "**Initial Setup**: If starting a new project with a PRD document, run `node scripts/dev.js parse-prd --input=<prd-file.txt>` to generate the initial tasks.json file. This will create a structured task list with IDs, titles, descriptions, dependencies, priorities, and test strategies."
- "**Task Discovery**: When a coding session begins, call `node scripts/dev.js list` to see the current tasks, their status, and IDs. This provides a quick overview of all tasks and their current states (pending, done, deferred)."
- "**Task Selection**: Select the next pending task based on these criteria:
1. Dependencies: Only select tasks whose dependencies are marked as 'done'
3. ID order: When priorities are equal, select the task with the lowest ID
If multiple tasks are eligible, present options to the user for selection."
- "**Task Clarification**: If a task description is unclear or lacks detail:
1. Check if a corresponding task file exists in the tasks/ directory (e.g., task_001.txt)
2. If more information is needed, ask the user for clarification
3. If architectural changes have occurred, run `node scripts/dev.js update --from=<id> --prompt=\"<new architectural context>\"` to update the task and all subsequent tasks"
- "**Task Breakdown**: For complex tasks that need to be broken down into smaller steps:
1. Use `node scripts/dev.js expand --id=<id> --subtasks=<number>` to generate detailed subtasks
2. Optionally provide additional context with `--prompt=\"<context>\"` to guide subtask generation
3. Review the generated subtasks and adjust if necessary
4. For multiple tasks, use `--all` flag to expand all pending tasks that don't have subtasks"
- "**Task Implementation**: Implement the code necessary for the chosen task. Follow these guidelines:
1. Reference the task's 'details' section for implementation specifics
2. Consider dependencies on previous tasks when implementing
3. Follow the project's coding standards and patterns
4. Create appropriate tests based on the task's 'testStrategy' field"
- "**Task Verification**: Before marking a task as done, verify it according to:
- "**Task Completion**: When a task is completed and verified, run `node scripts/dev.js set-status --id=<id> --status=done` to mark it as done in tasks.json. This ensures the task tracking remains accurate."
- "**Implementation Drift Handling**: If during implementation, you discover that:
1. The current approach differs significantly from what was planned
2. Future tasks need to be modified due to current implementation choices
3. New dependencies or requirements have emerged
Then call `node scripts/dev.js update --from=<futureTaskId> --prompt=\"Detailed explanation of architectural or implementation changes...\"` to rewrite or re-scope subsequent tasks in tasks.json."
- "**Task File Generation**: After any updates to tasks.json (status changes, task updates), run `node scripts/dev.js generate` to regenerate the individual task_XXX.txt files in the tasks/ folder. This ensures that task files are always in sync with tasks.json."
- "**Task Status Management**: Use appropriate status values when updating tasks:
1. 'pending': Tasks that are ready to be worked on
2. 'done': Tasks that have been completed and verified
3. 'deferred': Tasks that have been postponed to a later time
4. Any other custom status that might be relevant to the project"
- "**Dependency Management**: When selecting tasks, always respect the dependency chain:
1. Never start a task whose dependencies are not marked as 'done'
2. If a dependency task is deferred, consider whether dependent tasks should also be deferred
3. If dependency relationships change during development, update tasks.json accordingly"
- "**Progress Reporting**: Periodically (at the beginning of sessions or after completing significant tasks), run `node scripts/dev.js list` to provide the user with an updated view of project progress."
- "**Task File Format**: When reading task files, understand they follow this structure:
```
# Task ID: <id>
# Title: <title>
# Status: <status>
# Dependencies: <comma-separated list of dependency IDs>
# Priority: <priority>
# Description: <brief description>
# Details:
<detailed implementation notes>
# Test Strategy:
<verification approach>
```"
- "**Continuous Workflow**: Repeat this process until all tasks relevant to the current development phase are completed. Always maintain tasks.json as the single source of truth for development progress."
description: "Updates tasks with ID >= the specified ID based on the provided prompt. Useful for handling implementation drift or architectural changes."
parameters:
- "--from=<id>: The task ID from which to start updating (required)"
- "--prompt=\"<text>\": The prompt explaining the changes or new context (required)"
example: "node scripts/dev.js update --from=4 --prompt=\"Now we are using Express instead of Fastify.\""
notes: "Only updates tasks that aren't marked as 'done'. Completed tasks remain unchanged."
- name: "generate"
syntax: "node scripts/dev.js generate"
description: "Generates individual task files in the tasks/ directory based on the current state of tasks.json."
parameters: "None"
example: "node scripts/dev.js generate"
notes: "Overwrites existing task files. Creates the tasks/ directory if it doesn't exist."
