Windsurf rules

1Below you will find a variety of important rules spanning:
2- the dev_workflow
3- the .windsurfrules document self-improvement workflow
4- the template to follow when modifying or adding new sections/rules to this document.
5 
6---
7DEV_WORKFLOW
8---
9description: Guide for using meta-development script (scripts/dev.js) to manage task-driven development workflows
10globs: **/*
11filesToApplyRule: **/*
12alwaysApply: true
13---
14 
15- **Global CLI Commands**
16  - Task Master now provides a global CLI through the `task-manager` command
17  - All functionality from `scripts/dev.js` is available through this interface
18  - Install globally with `npm install -g claude-task-manager` or use locally via `npx`
19  - Use `task-manager <command>` instead of `node scripts/dev.js <command>`
20  - Examples:
21    - `task-manager list` instead of `node scripts/dev.js list`
22    - `task-manager next` instead of `node scripts/dev.js next`
23    - `task-manager expand --id=3` instead of `node scripts/dev.js expand --id=3`
24  - All commands accept the same options as their script equivalents
25  - The CLI provides additional commands like `task-manager init` for project setup
26 
27- **Development Workflow Process**
28  - Start new projects by running `task-manager init` or `node scripts/dev.js parse-prd --input=<prd-file.txt>` to generate initial tasks.json
29  - Begin coding sessions with `task-manager list` to see current tasks, status, and IDs
30  - Analyze task complexity with `task-manager analyze-complexity --research` before breaking down tasks
31  - Select tasks based on dependencies (all marked 'done'), priority level, and ID order
32  - Clarify tasks by checking task files in tasks/ directory or asking for user input
33  - View specific task details using `task-manager show <id>` to understand implementation requirements
34  - Break down complex tasks using `task-manager expand --id=<id>` with appropriate flags
35  - Clear existing subtasks if needed using `task-manager clear-subtasks --id=<id>` before regenerating
36  - Implement code following task details, dependencies, and project standards
37  - Verify tasks according to test strategies before marking as complete
38  - Mark completed tasks with `task-manager set-status --id=<id> --status=done`
39  - Update dependent tasks when implementation differs from original plan
40  - Generate task files with `task-manager generate` after updating tasks.json
41  - Maintain valid dependency structure with `task-manager fix-dependencies` when needed
42  - Respect dependency chains and task priorities when selecting work
43  - Report progress regularly using the list command
44 
45- **Task Complexity Analysis**
46  - Run `node scripts/dev.js analyze-complexity --research` for comprehensive analysis
47  - Review complexity report in scripts/task-complexity-report.json
48  - Or use `node scripts/dev.js complexity-report` for a formatted, readable version of the report
49  - Focus on tasks with highest complexity scores (8-10) for detailed breakdown
50  - Use analysis results to determine appropriate subtask allocation
51  - Note that reports are automatically used by the expand command
52 
53- **Task Breakdown Process**
54  - For tasks with complexity analysis, use `node scripts/dev.js expand --id=<id>`
55  - Otherwise use `node scripts/dev.js expand --id=<id> --subtasks=<number>`
56  - Add `--research` flag to leverage Perplexity AI for research-backed expansion
57  - Use `--prompt="<context>"` to provide additional context when needed
58  - Review and adjust generated subtasks as necessary
59  - Use `--all` flag to expand multiple pending tasks at once
60  - If subtasks need regeneration, clear them first with `clear-subtasks` command
61 
62- **Implementation Drift Handling**
63  - When implementation differs significantly from planned approach
64  - When future tasks need modification due to current implementation choices
65  - When new dependencies or requirements emerge
66  - Call `node scripts/dev.js update --from=<futureTaskId> --prompt="<explanation>"` to update tasks.json
67 
68- **Task Status Management**
69  - Use 'pending' for tasks ready to be worked on
70  - Use 'done' for completed and verified tasks
71  - Use 'deferred' for postponed tasks
72  - Add custom status values as needed for project-specific workflows
73 
74- **Task File Format Reference**
75```
76  # Task ID: <id>
77  # Title: <title>
78  # Status: <status>
79  # Dependencies: <comma-separated list of dependency IDs>
80  # Priority: <priority>
81  # Description: <brief description>
82  # Details:
83  <detailed implementation notes>
84 
85  # Test Strategy:
86  <verification approach>
87```
88 
89- **Command Reference: parse-prd**
90  - Legacy Syntax: `node scripts/dev.js parse-prd --input=<prd-file.txt>`
91  - CLI Syntax: `task-manager parse-prd --input=<prd-file.txt>`
92  - Description: Parses a PRD document and generates a tasks.json file with structured tasks
93  - Parameters:
94    - `--input=<file>`: Path to the PRD text file (default: sample-prd.txt)
95  - Example: `task-manager parse-prd --input=requirements.txt`
96  - Notes: Will overwrite existing tasks.json file. Use with caution.
97 
98- **Command Reference: update**
99  - Legacy Syntax: `node scripts/dev.js update --from=<id> --prompt="<prompt>"`
100  - CLI Syntax: `task-manager update --from=<id> --prompt="<prompt>"`
101  - Description: Updates tasks with ID >= specified ID based on the provided prompt
102  - Parameters:
103    - `--from=<id>`: Task ID from which to start updating (required)
104    - `--prompt="<text>"`: Explanation of changes or new context (required)
105  - Example: `task-manager update --from=4 --prompt="Now we are using Express instead of Fastify."`
106  - Notes: Only updates tasks not marked as 'done'. Completed tasks remain unchanged.
107 
108- **Command Reference: generate**
109  - Legacy Syntax: `node scripts/dev.js generate`
110  - CLI Syntax: `task-manager generate`
111  - Description: Generates individual task files in tasks/ directory based on tasks.json
112  - Parameters:
113    - `--file=<path>, -f`: Use alternative tasks.json file (default: 'tasks/tasks.json')
114    - `--output=<dir>, -o`: Output directory (default: 'tasks')
115  - Example: `task-manager generate`
116  - Notes: Overwrites existing task files. Creates tasks/ directory if needed.
117 
118- **Command Reference: set-status**
119  - Legacy Syntax: `node scripts/dev.js set-status --id=<id> --status=<status>`
120  - CLI Syntax: `task-manager set-status --id=<id> --status=<status>`
121  - Description: Updates the status of a specific task in tasks.json
122  - Parameters:
123    - `--id=<id>`: ID of the task to update (required)
124    - `--status=<status>`: New status value (required)
125  - Example: `task-manager set-status --id=3 --status=done`
126  - Notes: Common values are 'done', 'pending', and 'deferred', but any string is accepted.
127 
128- **Command Reference: list**
129  - Legacy Syntax: `node scripts/dev.js list`
130  - CLI Syntax: `task-manager list`
131  - Description: Lists all tasks in tasks.json with IDs, titles, and status
132  - Parameters:
133    - `--status=<status>, -s`: Filter by status
134    - `--with-subtasks`: Show subtasks for each task
135    - `--file=<path>, -f`: Use alternative tasks.json file (default: 'tasks/tasks.json')
136  - Example: `task-manager list`
137  - Notes: Provides quick overview of project progress. Use at start of sessions.
138 
139- **Command Reference: expand**
140  - Legacy Syntax: `node scripts/dev.js expand --id=<id> [--num=<number>] [--research] [--prompt="<context>"]`
141  - CLI Syntax: `task-manager expand --id=<id> [--num=<number>] [--research] [--prompt="<context>"]`
142  - Description: Expands a task with subtasks for detailed implementation
143  - Parameters:
144    - `--id=<id>`: ID of task to expand (required unless using --all)
145    - `--all`: Expand all pending tasks, prioritized by complexity
146    - `--num=<number>`: Number of subtasks to generate (default: from complexity report)
147    - `--research`: Use Perplexity AI for research-backed generation
148    - `--prompt="<text>"`: Additional context for subtask generation
149    - `--force`: Regenerate subtasks even for tasks that already have them
150  - Example: `task-manager expand --id=3 --num=5 --research --prompt="Focus on security aspects"`
151  - Notes: Uses complexity report recommendations if available.
152 
153- **Command Reference: analyze-complexity**
154  - Legacy Syntax: `node scripts/dev.js analyze-complexity [options]`
155  - CLI Syntax: `task-manager analyze-complexity [options]`
156  - Description: Analyzes task complexity and generates expansion recommendations
157  - Parameters:
158    - `--output=<file>, -o`: Output file path (default: scripts/task-complexity-report.json)
159    - `--model=<model>, -m`: Override LLM model to use
160    - `--threshold=<number>, -t`: Minimum score for expansion recommendation (default: 5)
161    - `--file=<path>, -f`: Use alternative tasks.json file
162    - `--research, -r`: Use Perplexity AI for research-backed analysis
163  - Example: `task-manager analyze-complexity --research`
164  - Notes: Report includes complexity scores, recommended subtasks, and tailored prompts.
165 
166- **Command Reference: clear-subtasks**
167  - Legacy Syntax: `node scripts/dev.js clear-subtasks --id=<id>`
168  - CLI Syntax: `task-manager clear-subtasks --id=<id>`
169  - Description: Removes subtasks from specified tasks to allow regeneration
170  - Parameters:
171    - `--id=<id>`: ID or comma-separated IDs of tasks to clear subtasks from
172    - `--all`: Clear subtasks from all tasks
173  - Examples:
174    - `task-manager clear-subtasks --id=3`
175    - `task-manager clear-subtasks --id=1,2,3`
176    - `task-manager clear-subtasks --all`
177  - Notes:
178    - Task files are automatically regenerated after clearing subtasks
179    - Can be combined with expand command to immediately generate new subtasks
180    - Works with both parent tasks and individual subtasks
181 
182- **Task Structure Fields**
183  - **id**: Unique identifier for the task (Example: `1`)
184  - **title**: Brief, descriptive title (Example: `"Initialize Repo"`)
185  - **description**: Concise summary of what the task involves (Example: `"Create a new repository, set up initial structure."`)
186  - **status**: Current state of the task (Example: `"pending"`, `"done"`, `"deferred"`)
187  - **dependencies**: IDs of prerequisite tasks (Example: `[1, 2]`)
188    - Dependencies are displayed with status indicators (✅ for completed, ⏱️ for pending)
189    - This helps quickly identify which prerequisite tasks are blocking work
190  - **priority**: Importance level (Example: `"high"`, `"medium"`, `"low"`)
191  - **details**: In-depth implementation instructions (Example: `"Use GitHub client ID/secret, handle callback, set session token."`)
192  - **testStrategy**: Verification approach (Example: `"Deploy and call endpoint to confirm 'Hello World' response."`)
193  - **subtasks**: List of smaller, more specific tasks (Example: `[{"id": 1, "title": "Configure OAuth", ...}]`)
194 
195- **Environment Variables Configuration**
196  - **ANTHROPIC_API_KEY** (Required): Your Anthropic API key for Claude (Example: `ANTHROPIC_API_KEY=sk-ant-api03-...`)
197  - **MODEL** (Default: `"claude-3-7-sonnet-20250219"`): Claude model to use (Example: `MODEL=claude-3-opus-20240229`)
198  - **MAX_TOKENS** (Default: `"4000"`): Maximum tokens for responses (Example: `MAX_TOKENS=8000`)
199  - **TEMPERATURE** (Default: `"0.7"`): Temperature for model responses (Example: `TEMPERATURE=0.5`)
200  - **DEBUG** (Default: `"false"`): Enable debug logging (Example: `DEBUG=true`)
201  - **LOG_LEVEL** (Default: `"info"`): Console output level (Example: `LOG_LEVEL=debug`)
202  - **DEFAULT_SUBTASKS** (Default: `"3"`): Default subtask count (Example: `DEFAULT_SUBTASKS=5`)
203  - **DEFAULT_PRIORITY** (Default: `"medium"`): Default priority (Example: `DEFAULT_PRIORITY=high`)
204  - **PROJECT_NAME** (Default: `"MCP SaaS MVP"`): Project name in metadata (Example: `PROJECT_NAME=My Awesome Project`)
205  - **PROJECT_VERSION** (Default: `"1.0.0"`): Version in metadata (Example: `PROJECT_VERSION=2.1.0`)
206  - **PERPLEXITY_API_KEY**: For research-backed features (Example: `PERPLEXITY_API_KEY=pplx-...`)
207  - **PERPLEXITY_MODEL** (Default: `"sonar-medium-online"`): Perplexity model (Example: `PERPLEXITY_MODEL=sonar-large-online`)
208 
209- **Determining the Next Task**
210  - Run `task-manager next` to show the next task to work on
211  - The next command identifies tasks with all dependencies satisfied
212  - Tasks are prioritized by priority level, dependency count, and ID
213  - The command shows comprehensive task information including:
214    - Basic task details and description
215    - Implementation details
216    - Subtasks (if they exist)
217    - Contextual suggested actions
218  - Recommended before starting any new development work
219  - Respects your project's dependency structure
220  - Ensures tasks are completed in the appropriate sequence
221  - Provides ready-to-use commands for common task actions
222 
223- **Viewing Specific Task Details**
224  - Run `task-manager show <id>` or `task-manager show --id=<id>` to view a specific task
225  - Use dot notation for subtasks: `task-manager show 1.2` (shows subtask 2 of task 1)
226  - Displays comprehensive information similar to the next command, but for a specific task
227  - For parent tasks, shows all subtasks and their current status
228  - For subtasks, shows parent task information and relationship
229  - Provides contextual suggested actions appropriate for the specific task
230  - Useful for examining task details before implementation or checking status
231 
232- **Managing Task Dependencies**
233  - Use `task-manager add-dependency --id=<id> --depends-on=<id>` to add a dependency
234  - Use `task-manager remove-dependency --id=<id> --depends-on=<id>` to remove a dependency
235  - The system prevents circular dependencies and duplicate dependency entries
236  - Dependencies are checked for existence before being added or removed
237  - Task files are automatically regenerated after dependency changes
238  - Dependencies are visualized with status indicators in task listings and files
239 
240- **Command Reference: add-dependency**
241  - Legacy Syntax: `node scripts/dev.js add-dependency --id=<id> --depends-on=<id>`
242  - CLI Syntax: `task-manager add-dependency --id=<id> --depends-on=<id>`
243  - Description: Adds a dependency relationship between two tasks
244  - Parameters:
245    - `--id=<id>`: ID of task that will depend on another task (required)
246    - `--depends-on=<id>`: ID of task that will become a dependency (required)
247  - Example: `task-manager add-dependency --id=22 --depends-on=21`
248  - Notes: Prevents circular dependencies and duplicates; updates task files automatically
249 
250- **Command Reference: remove-dependency**
251  - Legacy Syntax: `node scripts/dev.js remove-dependency --id=<id> --depends-on=<id>`
252  - CLI Syntax: `task-manager remove-dependency --id=<id> --depends-on=<id>`
253  - Description: Removes a dependency relationship between two tasks
254  - Parameters:
255    - `--id=<id>`: ID of task to remove dependency from (required)
256    - `--depends-on=<id>`: ID of task to remove as a dependency (required)
257  - Example: `task-manager remove-dependency --id=22 --depends-on=21`
258  - Notes: Checks if dependency actually exists; updates task files automatically
259 
260- **Command Reference: validate-dependencies**
261  - Legacy Syntax: `node scripts/dev.js validate-dependencies [options]`
262  - CLI Syntax: `task-manager validate-dependencies [options]`
263  - Description: Checks for and identifies invalid dependencies in tasks.json and task files
264  - Parameters:
265    - `--file=<path>, -f`: Use alternative tasks.json file (default: 'tasks/tasks.json')
266  - Example: `task-manager validate-dependencies`
267  - Notes:
268    - Reports all non-existent dependencies and self-dependencies without modifying files
269    - Provides detailed statistics on task dependency state
270    - Use before fix-dependencies to audit your task structure
271 
272- **Command Reference: fix-dependencies**
273  - Legacy Syntax: `node scripts/dev.js fix-dependencies [options]`
274  - CLI Syntax: `task-manager fix-dependencies [options]`
275  - Description: Finds and fixes all invalid dependencies in tasks.json and task files
276  - Parameters:
277    - `--file=<path>, -f`: Use alternative tasks.json file (default: 'tasks/tasks.json')
278  - Example: `task-manager fix-dependencies`
279  - Notes:
280    - Removes references to non-existent tasks and subtasks
281    - Eliminates self-dependencies (tasks depending on themselves)
282    - Regenerates task files with corrected dependencies
283    - Provides detailed report of all fixes made
284 
285- **Command Reference: complexity-report**
286  - Legacy Syntax: `node scripts/dev.js complexity-report [options]`
287  - CLI Syntax: `task-manager complexity-report [options]`
288  - Description: Displays the task complexity analysis report in a formatted, easy-to-read way
289  - Parameters:
290    - `--file=<path>, -f`: Path to the complexity report file (default: 'scripts/task-complexity-report.json')
291  - Example: `task-manager complexity-report`
292  - Notes:
293    - Shows tasks organized by complexity score with recommended actions
294    - Provides complexity distribution statistics
295    - Displays ready-to-use expansion commands for complex tasks
296    - If no report exists, offers to generate one interactively
297 
298- **Command Reference: add-task**
299  - CLI Syntax: `task-manager add-task [options]`
300  - Description: Add a new task to tasks.json using AI
301  - Parameters:
302    - `--file=<path>, -f`: Path to the tasks file (default: 'tasks/tasks.json')
303    - `--prompt=<text>, -p`: Description of the task to add (required)
304    - `--dependencies=<ids>, -d`: Comma-separated list of task IDs this task depends on
305    - `--priority=<priority>`: Task priority (high, medium, low) (default: 'medium')
306  - Example: `task-manager add-task --prompt="Create user authentication using Auth0"`
307  - Notes: Uses AI to convert description into structured task with appropriate details
308 
309- **Command Reference: init**
310  - CLI Syntax: `task-manager init`
311  - Description: Initialize a new project with Task Master structure
312  - Parameters: None
313  - Example: `task-manager init`
314  - Notes:
315    - Creates initial project structure with required files
316    - Prompts for project settings if not provided
317    - Merges with existing files when appropriate
318    - Can be used to bootstrap a new Task Master project quickly
319 
320- **Code Analysis & Refactoring Techniques**
321  - **Top-Level Function Search**
322    - Use grep pattern matching to find all exported functions across the codebase
323    - Command: `grep -E "export (function|const) \w+|function \w+\(|const \w+ = \(|module\.exports" --include="*.js" -r ./`
324    - Benefits:
325      - Quickly identify all public API functions without reading implementation details
326      - Compare functions between files during refactoring (e.g., monolithic to modular structure)
327      - Verify all expected functions exist in refactored modules
328      - Identify duplicate functionality or naming conflicts
329    - Usage examples:
330      - When migrating from `scripts/dev.js` to modular structure: `grep -E "function \w+\(" scripts/dev.js`
331      - Check function exports in a directory: `grep -E "export (function|const)" scripts/modules/`
332      - Find potential naming conflicts: `grep -E "function (get|set|create|update)\w+\(" -r ./`
333    - Variations:
334      - Add `-n` flag to include line numbers
335      - Add `--include="*.ts"` to filter by file extension
336      - Use with `| sort` to alphabetize results
337    - Integration with refactoring workflow:
338      - Start by mapping all functions in the source file
339      - Create target module files based on function grouping
340      - Verify all functions were properly migrated
341      - Check for any unintentional duplications or omissions
342 
343---
344WINDSURF_RULES
345---
346description: Guidelines for creating and maintaining Windsurf rules to ensure consistency and effectiveness.
347globs: .windsurfrules
348filesToApplyRule: .windsurfrules
349alwaysApply: true
350---
351The below describes how you should be structuring new rule sections in this document.
352- **Required Rule Structure:**
353```markdown
354  ---
355  description: Clear, one-line description of what the rule enforces
356  globs: path/to/files/*.ext, other/path/**/*
357  alwaysApply: boolean
358  ---
359 
360  - **Main Points in Bold**
361    - Sub-points with details
362    - Examples and explanations
363```
364 
365- **Section References:**
366  - Use `ALL_CAPS_SECTION` to reference files
367  - Example: `WINDSURF_RULES`
368 
369- **Code Examples:**
370  - Use language-specific code blocks
371```typescript
372  // ✅ DO: Show good examples
373  const goodExample = true;
374 
375  // ❌ DON'T: Show anti-patterns
376  const badExample = false;
377```
378 
379- **Rule Content Guidelines:**
380  - Start with high-level overview
381  - Include specific, actionable requirements
382  - Show examples of correct implementation
383  - Reference existing code when possible
384  - Keep rules DRY by referencing other rules
385 
386- **Rule Maintenance:**
387  - Update rules when new patterns emerge
388  - Add examples from actual codebase
389  - Remove outdated patterns
390  - Cross-reference related rules
391 
392- **Best Practices:**
393  - Use bullet points for clarity
394  - Keep descriptions concise
395  - Include both DO and DON'T examples
396  - Reference actual code over theoretical examples
397  - Use consistent formatting across rules
398 
399---
400SELF_IMPROVE
401---
402description: Guidelines for continuously improving this rules document based on emerging code patterns and best practices.
403globs: **/*
404filesToApplyRule: **/*
405alwaysApply: true
406---
407 
408- **Rule Improvement Triggers:**
409  - New code patterns not covered by existing rules
410  - Repeated similar implementations across files
411  - Common error patterns that could be prevented
412  - New libraries or tools being used consistently
413  - Emerging best practices in the codebase
414 
415- **Analysis Process:**
416  - Compare new code with existing rules
417  - Identify patterns that should be standardized
418  - Look for references to external documentation
419  - Check for consistent error handling patterns
420  - Monitor test patterns and coverage
421 
422- **Rule Updates:**
423  - **Add New Rules When:**
424    - A new technology/pattern is used in 3+ files
425    - Common bugs could be prevented by a rule
426    - Code reviews repeatedly mention the same feedback
427    - New security or performance patterns emerge
428 
429  - **Modify Existing Rules When:**
430    - Better examples exist in the codebase
431    - Additional edge cases are discovered
432    - Related rules have been updated
433    - Implementation details have changed
434 
435- **Example Pattern Recognition:**
436```typescript
437  // If you see repeated patterns like:
438  const data = await prisma.user.findMany({
439    select: { id: true, email: true },
440    where: { status: 'ACTIVE' }
441  });
442 
443  // Consider adding a PRISMA section in the .windsurfrules:
444  // - Standard select fields
445  // - Common where conditions
446  // - Performance optimization patterns
447```
448 
449- **Rule Quality Checks:**
450  - Rules should be actionable and specific
451  - Examples should come from actual code
452  - References should be up to date
453  - Patterns should be consistently enforced
454 
455- **Continuous Improvement:**
456  - Monitor code review comments
457  - Track common development questions
458  - Update rules after major refactors
459  - Add links to relevant documentation
460  - Cross-reference related rules
461 
462- **Rule Deprecation:**
463  - Mark outdated patterns as deprecated
464  - Remove rules that no longer apply
465  - Update references to deprecated rules
466  - Document migration paths for old patterns
467 
468- **Documentation Updates:**
469  - Keep examples synchronized with code
470  - Update references to external docs
471  - Maintain links between related rules
472  - Document breaking changes
473 
474Follow WINDSURF_RULES for proper rule formatting and structure of windsurf rule sections.