Cline rules

1---
2description: Workflow for starting new task when context window reaches 50%
3author: https://github.com/cline
4version: 1.0
5category: "Cline Core"
6tags: ["context-management", "new-task"]
7globs: ["*"]
8---
9# You MUST use the `new_task` tool: Task Handoff Strategy Guide
10 
11**⚠️ CRITICAL INSTRUCTIONS - YOU MUST FOLLOW THESE GUIDELINES ⚠️**
12 
13This guide provides **MANDATORY** instructions for effectively breaking down complex tasks and implementing a smooth handoff process between tasks. You **MUST** follow these guidelines to ensure continuity, context preservation, and efficient task completion.
14 
15## ⚠️ CONTEXT WINDOW MONITORING - MANDATORY ACTION REQUIRED ⚠️
16 
17You **MUST** monitor the context window usage displayed in the environment details. When usage exceeds 50% of the available context window, you **MUST** initiate a task handoff using the `new_task` tool.
18 
19Example of context window usage over 50% with a 200K context window:
20 
21\`\`\`text
22# Context Window Usage
23105,000 / 200,000 tokens (53%)
24Model: anthropic/claude-3.7-sonnet (200K context window)
25\`\`\`
26 
27**IMPORTANT**: When you see context window usage at or above 50%, you MUST:
281. Complete your current logical step
292. Use the `ask_followup_question` tool to offer creating a new task
303. If approved, use the `new_task` tool with comprehensive handoff instructions
31 
32## Task Breakdown in Plan Mode - REQUIRED PROCESS
33 
34Plan Mode is specifically designed for analyzing complex tasks and breaking them into manageable subtasks. When in Plan Mode, you **MUST**:
35 
36### 1. Initial Task Analysis - REQUIRED
37 
38- **MUST** begin by thoroughly understanding the full scope of the user's request
39- **MUST** identify all major components and dependencies of the task
40- **MUST** consider potential challenges, edge cases, and prerequisites
41 
42### 2. Strategic Task Decomposition - REQUIRED
43 
44- **MUST** break the overall task into logical, discrete subtasks
45- **MUST** prioritize subtasks based on dependencies (what must be completed first)
46- **MUST** aim for subtasks that can be completed within a single session (15-30 minutes of work)
47- **MUST** consider natural breaking points where context switching makes sense
48 
49### 3. Creating a Task Roadmap - REQUIRED
50 
51- **MUST** present a clear, numbered list of subtasks to the user
52- **MUST** explain dependencies between subtasks
53- **MUST** provide time estimates for each subtask when possible
54- **MUST** use Mermaid diagrams to visualize task flow and dependencies when helpful
55 
56\`\`\`mermaid
57graph TD
58    A[Main Task] --> B[Subtask 1: Setup]
59    A --> C[Subtask 2: Core Implementation]
60    A --> D[Subtask 3: Testing]
61    A --> E[Subtask 4: Documentation]
62    B --> C
63    C --> D
64\`\`\`
65 
66### 4. Getting User Approval - REQUIRED
67 
68- **MUST** ask for user feedback on the proposed task breakdown
69- **MUST** adjust the plan based on user priorities or additional requirements
70- **MUST** confirm which subtask to begin with
71- **MUST** request the user to toggle to Act Mode when ready to implement
72 
73## Task Implementation and Handoff Process - MANDATORY PROCEDURES
74 
75When implementing tasks in Act Mode, you **MUST** follow these guidelines for effective task handoff:
76 
77### 1. Focused Implementation - REQUIRED
78 
79- **MUST** focus on completing the current subtask fully
80- **MUST** document progress clearly through comments and commit messages
81- **MUST** create checkpoints at logical completion points
82 
83### 2. Recognizing Completion Points - CRITICAL
84 
85You **MUST** identify natural handoff points when:
86- The current subtask is fully completed
87- You've reached a logical stopping point in a larger subtask
88- The implementation is taking longer than expected and can be continued later
89- The task scope has expanded beyond the original plan
90- **CRITICAL**: The context window usage exceeds 50% (e.g., 100,000+ tokens for a 200K context window)
91 
92### 3. Initiating the Handoff Process - MANDATORY ACTION
93 
94When you've reached a completion point, you **MUST**:
95 
961. Summarize what has been accomplished so far
972. Clearly state what remains to be done
983. **MANDATORY**: Use the `ask_followup_question` tool to offer creating a new task:
99 
100\`\`\`xml
101<ask_followup_question>
102<question>I've completed [specific accomplishment]. Would you like me to create a new task to continue with [remaining work]?</question>
103<options>["Yes, create a new task", "No, continue in this session", "Let me think about it"]</options>
104</ask_followup_question>
105\`\`\`
106 
107### 4. Creating a New Task with Context - REQUIRED ACTION
108 
109If the user agrees to create a new task, you **MUST** use the `new_task` tool with comprehensive handoff instructions:
110 
111\`\`\`xml
112<new_task>
113<context>
114# Task Continuation: [Brief Task Title]
115 
116## Completed Work
117- [Detailed list of completed items]
118- [Include specific files modified/created]
119- [Note any important decisions made]
120 
121## Current State
122- [Description of the current state of the project]
123- [Any running processes or environment setup]
124- [Key files and their current state]
125 
126## Next Steps
127- [Detailed list of remaining tasks]
128- [Specific implementation details to address]
129- [Any known challenges to be aware of]
130 
131## Reference Information
132- [Links to relevant documentation]
133- [Important code snippets or patterns to follow]
134- [Any user preferences noted during the current session]
135 
136Please continue the implementation by [specific next action].
137</context>
138</new_task>
139\`\`\`
140 
141### 5. Detailed Context Transfer - MANDATORY COMPONENTS
142 
143When creating a new task, you **MUST** always include:
144 
145#### Project Context - REQUIRED
146- **MUST** include the overall goal and purpose of the project
147- **MUST** include key architectural decisions and patterns
148- **MUST** include technology stack and dependencies
149 
150#### Implementation Details - REQUIRED
151- **MUST** list files created or modified in the current session
152- **MUST** describe specific functions, classes, or components implemented
153- **MUST** explain design patterns being followed
154- **MUST** outline testing approach
155 
156#### Progress Tracking - REQUIRED
157- **MUST** provide checklist of completed items
158- **MUST** provide checklist of remaining items
159- **MUST** note any blockers or challenges encountered
160 
161#### User Preferences - REQUIRED
162- **MUST** note coding style preferences mentioned by the user
163- **MUST** document specific approaches requested by the user
164- **MUST** highlight priority areas identified by the user
165 
166## Best Practices for Effective Handoffs - MANDATORY GUIDELINES
167 
168### 1. Maintain Continuity - REQUIRED
169 
170- **MUST** use consistent terminology between tasks
171- **MUST** reference previous decisions and their rationale
172- **MUST** maintain the same architectural approach unless explicitly changing direction
173 
174### 2. Preserve Context - REQUIRED
175 
176- **MUST** include relevant code snippets in the handoff
177- **MUST** summarize key discussions from the previous session
178- **MUST** reference specific files and line numbers when applicable
179 
180### 3. Set Clear Next Actions - REQUIRED
181 
182- **MUST** begin the handoff with a clear, actionable next step
183- **MUST** prioritize remaining tasks
184- **MUST** highlight any decisions that need to be made
185 
186### 4. Document Assumptions - REQUIRED
187 
188- **MUST** clearly state any assumptions made during implementation
189- **MUST** note areas where user input might be needed
190- **MUST** identify potential alternative approaches
191 
192### 5. Optimize for Resumability - REQUIRED
193 
194- **MUST** structure the handoff so the next session can begin working immediately
195- **MUST** include setup instructions if environment configuration is needed
196- **MUST** provide a quick summary at the top for rapid context restoration
197 
198## Example Task Handoff
199 
200### Example #1 of an effective task handoff:
201 
202\`\`\`xml
203<new_task>
204<context>
205# Task Continuation: Implement User Authentication System
206 
207## Completed Work
208- Created basic Express.js server structure
209- Implemented MongoDB connection and user schema
210- Completed user registration endpoint with password hashing
211- Added input validation using Joi
212- Created initial test suite for registration endpoint
213 
214## Current State
215- Server runs successfully on port 3000
216- MongoDB connection is established
217- Registration endpoint (/api/users/register) is fully functional
218- Test suite passes for all registration scenarios
219 
220## Next Steps
2211. Implement login endpoint (/api/users/login)
222   - Use bcrypt to compare passwords
223   - Generate JWT token upon successful login
224   - Add proper error handling for invalid credentials
2252. Create authentication middleware
226   - Verify JWT tokens
227   - Extract user information
228   - Handle expired tokens
2293. Add protected routes that require authentication
2304. Implement password reset functionality
231 
232## Reference Information
233- JWT secret should be stored in .env file
234- Follow the existing error handling pattern in routes/users.js
235- User schema is defined in models/User.js
236- Test patterns are established in tests/auth.test.js
237 
238Please continue by implementing the login endpoint following the same patterns established in the registration endpoint.
239</context>
240</new_task>
241\`\`\`
242 
243### Example #2 of an ineffective task handoff:
244 
245*(Note: The example provided in the original rules showing "YOLO MODE Implementation" seems less like a direct handoff context block and more like a general status update with future considerations. A true ineffective handoff might lack detail in 'Current State' or 'Next Steps').*
246 
247## When to Use Task Handoffs - MANDATORY TRIGGERS
248 
249You **MUST** initiate task handoffs in these scenarios:
250 
2511. **CRITICAL**: When context window usage exceeds 50% (e.g., 100,000+ tokens for a 200K context window)
2522. **Long-running projects** that exceed a single session
2533. **Complex implementations** with multiple distinct phases
2544. **When context window limitations** are approaching
2555. **When switching focus areas** within a larger project
2566. **When different expertise** might be beneficial for different parts of the task
257 
258**⚠️ FINAL REMINDER - CRITICAL INSTRUCTION ⚠️**
259 
260You **MUST** monitor the context window usage in the environment details section. When it exceeds 50% (e.g., "105,000 / 200,000 tokens (53%)"), you **MUST** proactively initiate the task handoff process using the `ask_followup_question` tool followed by the `new_task` tool. You MUST use the `new_task` tool.
261 
262By strictly following these guidelines, you'll ensure smooth transitions between tasks, maintain project momentum, and provide the best possible experience for users working on complex, multi-session projects.
263```markdown
264 
265## User Interaction & Workflow Considerations
266 
267*   **Linear Flow:** Currently, using `new_task` creates a linear sequence. The old task ends, and the new one begins. The old task history remains accessible for backtracking.
268*   **User Approval:** You always have control, approving the handoff and having the chance to modify the context Cline proposes to carry forward.
269*   **Flexibility:** The core `new_task` tool is a flexible building block. Experiment with `.clinerules` to create workflows that best suit your needs, whether for strict context management, task decomposition, or other creative uses.
270 
271```