New Task Tool

The `new_task` Tool & Context Management Approaches

Introduction

Sypha incorporates a robust internal tool, new_task, created to facilitate workflow continuity and context preservation, particularly for complex or extended tasks. This tool, paired with Sypha's monitoring of its context window utilization and the adaptability of .sypharules, facilitates advanced strategies for work decomposition and guarantees smooth transitions across task sessions.

Comprehending the fundamental capabilities and their interaction with custom rules proves essential for effective utilization of this feature.

Fundamental Capabilities

Two core capabilities facilitate advanced context management:

The new_task Tool:
- Purpose: Permits Sypha, with user authorization, to terminate the current task session and immediately initiate a new one.
- Context Preloading: Significantly, Sypha can preload this new task session with particular context supplied within the tool's <context> block. This context encompasses anything Sypha or a .sypharules file specifies – summaries, code snippets, subsequent steps, project state, etc.
Context Window Monitoring:
- Tracking: Sypha internally monitors the percentage of its available context window currently utilized during a task.
- Visibility: This data appears in the environment_details supplied to Sypha in its prompt.

Utilizing the `/newtask` Slash Command

As a rapid alternative to waiting for Sypha to suggest the newtask tool or establishing complex rules, you can directly trigger the process through a Slash Command.

Method: Simply enter /newtask in the chat input field.
Outcome: Sypha will suggest creating a new task, usually proposing context derived from the current session (comparable to its standard behavior when utilizing the tool). You will still receive the ask_followup_question prompt to approve and potentially adjust the context prior to new task creation.
Advantage: Delivers a quick, user-driven method to exploit the new_task functionality for diverging explorations or handling extended sessions without awaiting Sypha's suggestion.

For more details on using the /newtask slash command, see the New Task Command documentation.

Standard Behavior (Without `.sypharules`)

By default, absent specific .sypharules governing its behavior:

Tool Availability: The new_task tool exists, and Sypha can opt to utilize it.
Context Awareness: Sypha is cognizant of its context usage percentage.
No Automatic Trigger: Sypha will not automatically trigger a task handoff exclusively based on context usage attaining a particular percentage (like 50%). The choice to propose using new_task derives from the AI model's reasoning founded on overall task progress and prompt directives.
Basic Context Preloading: If new_task is utilized without specific rules defining the <context> block structure, Sypha will endeavor to preload pertinent information founded on its current comprehension (e.g., a fundamental summary of progress and subsequent steps), though this may prove less thorough than a rule-driven methodology.

The Capability of `.sypharules`: Facilitating Custom Workflows

While the core capabilities exist by default, genuine power, automation, and customization materialize when you integrate new_task and context monitoring with custom workflows specified in .sypharules. This permits precise control over when and how Sypha manages context and task continuity.

Primary advantages of employing .sypharules with new_task:

Automated Context Management: Establish rules to automatically initiate handoffs at designated context percentages (e.g., >50%, >70%) or token counts, guaranteeing optimal performance and averting context loss.
Model-Specific Optimization: Customize handoff triggers according to recognized thresholds for various LLMs (e.g., trigger sooner for models recognized to deteriorate beyond a certain token count).
Intelligent Breakpoints: Direct Sypha through rules to locate logical stopping points (e.g., following completion of a function or test) after a context threshold passes, guaranteeing cleaner handoffs.
Structured Task Decomposition: Employ Plan Mode to specify subtasks, then utilize .sypharules to have Sypha automatically generate a new task via new_task upon finishing each subtask, preloading the context for the subsequent subtask.
Custom Context Packaging: Specify the precise structure and content of the <context> block in .sypharules for extensively detailed and consistent handoffs (see example below).
Improved Memory Persistence: Employ new_task context blocks as a primary, integrated approach to persist information across sessions, potentially superseding or supplementing file-based memory systems.
Workflow Automation: Establish rules for particular scenarios, such as consistently preloading certain setup instructions or project boilerplate when initiating tasks of a specific type.

Example Rule-Driven Workflow: Task Handoff Process

A typical workflow, governed by specific .sypharules like the example below, encompasses these stages:

Trigger Identification (Rule-Based): Sypha watches for handoff points specified in the rules (e.g., context usage > 50%, task completion).

User Confirmation: Sypha employs ask_followup_question to suggest creating a new task, frequently displaying the intended context specified by the rules.

<ask_followup_question>
<question>I've completed [specific accomplishment] and context usage is high (XX%). Would you like me to create a new task to continue with [remaining work], preloading the following context?</question>
<options>["Yes, create new task", "Modify context first", "No, continue this session"]</options>
</ask_followup_question>

User Control: You can authorize, reject, or request Sypha to adjust the context prior to new task creation.
Context Packaging (new_task Tool): Upon approval, Sypha utilizes new_task, organizing the context according to the structure required by the .sypharules.
New Task Creation: The current task concludes, and a new session commences immediately, preloaded with the designated context.

The Handoff Context Block (Rule-Defined Structure)

The efficacy of rule-driven handoffs relies significantly on how .sypharules specify the <context> block. A thorough structure typically incorporates:

## Completed Work: Comprehensive list of achievements, files altered/generated, crucial decisions.
## Current State: Project status, active processes, essential file states.
## Next Steps: Clear, prioritized list of outstanding tasks, implementation specifics, recognized challenges.
## Reference Information: Links, code snippets, patterns, user preferences.
Actionable Start: A precise instruction for the immediate subsequent action.

Potential Applications & Workflows

The adaptability of new_task paired with .sypharules creates numerous possibilities:

Proactive Context Window Management: Automatically initiate handoffs at designated percentages (e.g., 50%, 70%) or token counts to preserve optimal performance.
Intelligent Breakpoints: Direct Sypha to locate logical stopping points (e.g., following completion of a function or test) after a context threshold passes, guaranteeing cleaner handoffs.
Structured Task Decomposition: Employ Plan Mode to specify subtasks, then utilize .sypharules to have Sypha automatically generate a new task via new_task upon finishing each subtask.
Automated Session Summaries: Configure the <context> block to consistently include a summary of the previous session's essential discussion points.
Preloading Boilerplate/Setup: Initiate new tasks related to particular projects preloaded with standard setup directives or file templates.
"Memory Bank" Alternative: Utilize new_task context blocks as the principal method to persist information across sessions, potentially superseding file-based memory systems.

Experimentation with .sypharules is encouraged to uncover workflows that optimally suit your requirements!

Example `.sypharules`: Task Handoff Strategy Guide

Below is an example .sypharules file focused specifically on using new_task for context window management. Remember, this is just one specific strategy; the core new_task tool can be used differently with other custom rules.

# You MUST use the `new_task` tool: Task Handoff Strategy Guide

**CRITICAL INSTRUCTIONS - YOU MUST FOLLOW THESE GUIDELINES**

This 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.

## CONTEXT WINDOW MONITORING - MANDATORY ACTION REQUIRED

You **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.

Example of context window usage over 50% with a 200K context window:

\`\`\`text

# Context Window Usage

105,000 / 200,000 tokens (53%)
Model: anthropic/claude-sonnet-4 (200K context window)
\`\`\`

**IMPORTANT**: When you see context window usage at or above 50%, you MUST:

1. Complete your current logical step
2. Use the `ask_followup_question` tool to offer creating a new task
3. If approved, use the `new_task` tool with comprehensive handoff instructions

## Task Breakdown in Plan Mode - REQUIRED PROCESS

Plan Mode is specifically designed for analyzing complex tasks and breaking them into manageable subtasks. When in Plan Mode, you **MUST**:

### 1. Initial Task Analysis - REQUIRED

-   **MUST** begin by thoroughly understanding the full scope of the user's request
-   **MUST** identify all major components and dependencies of the task
-   **MUST** consider potential challenges, edge cases, and prerequisites

### 2. Strategic Task Decomposition - REQUIRED

-   **MUST** break the overall task into logical, discrete subtasks
-   **MUST** prioritize subtasks based on dependencies (what must be completed first)
-   **MUST** aim for subtasks that can be completed within a single session (15-30 minutes of work)
-   **MUST** consider natural breaking points where context switching makes sense

### 3. Creating a Task Roadmap - REQUIRED

-   **MUST** present a clear, numbered list of subtasks to the user
-   **MUST** explain dependencies between subtasks
-   **MUST** provide time estimates for each subtask when possible
-   **MUST** use Mermaid diagrams to visualize task flow and dependencies when helpful

\`\`\`mermaid
graph TD
A[Main Task] --> B[Subtask 1: Setup]
A --> C[Subtask 2: Core Implementation]
A --> D[Subtask 3: Testing]
A --> E[Subtask 4: Documentation]
B --> C
C --> D
\`\`\`

### 4. Getting User Approval - REQUIRED

-   **MUST** ask for user feedback on the proposed task breakdown
-   **MUST** adjust the plan based on user priorities or additional requirements
-   **MUST** confirm which subtask to begin with
-   **MUST** request the user to toggle to Act Mode when ready to implement

## Task Implementation and Handoff Process - MANDATORY PROCEDURES

When implementing tasks in Act Mode, you **MUST** follow these guidelines for effective task handoff:

### 1. Focused Implementation - REQUIRED

-   **MUST** focus on completing the current subtask fully
-   **MUST** document progress clearly through comments and commit messages
-   **MUST** create checkpoints at logical completion points

### 2. Recognizing Completion Points - CRITICAL

You **MUST** identify natural handoff points when:

-   The current subtask is fully completed
-   You've reached a logical stopping point in a larger subtask
-   The implementation is taking longer than expected and can be continued later
-   The task scope has expanded beyond the original plan
-   **CRITICAL**: The context window usage exceeds 50% (e.g., 100,000+ tokens for a 200K context window)

### 3. Initiating the Handoff Process - MANDATORY ACTION

When you've reached a completion point, you **MUST**:

1. Summarize what has been accomplished so far
2. Clearly state what remains to be done
3. **MANDATORY**: Use the `ask_followup_question` tool to offer creating a new task:

\`\`\`xml
<ask_followup_question>
<question>I've completed [specific accomplishment]. Would you like me to create a new task to continue with [remaining work]?</question>
<options>["Yes, create a new task", "No, continue in this session", "Let me think about it"]</options>
</ask_followup_question>
\`\`\`

### 4. Creating a New Task with Context - REQUIRED ACTION

If the user agrees to create a new task, you **MUST** use the `new_task` tool with comprehensive handoff instructions:

\`\`\`xml
<new_task>
<context>

# Task Continuation: [Brief Task Title]

## Completed Work

-   [Detailed list of completed items]
-   [Include specific files modified/created]
-   [Note any important decisions made]

## Current State

-   [Description of the current state of the project]
-   [Any running processes or environment setup]
-   [Key files and their current state]

## Next Steps

-   [Detailed list of remaining tasks]
-   [Specific implementation details to address]
-   [Any known challenges to be aware of]

## Reference Information

-   [Links to relevant documentation]
-   [Important code snippets or patterns to follow]
-   [Any user preferences noted during the current session]

Please continue the implementation by [specific next action].
</context>
</new_task>
\`\`\`

### 5. Detailed Context Transfer - MANDATORY COMPONENTS

When creating a new task, you **MUST** always include:

#### Project Context - REQUIRED

-   **MUST** include the overall goal and purpose of the project
-   **MUST** include key architectural decisions and patterns
-   **MUST** include technology stack and dependencies

#### Implementation Details - REQUIRED

-   **MUST** list files created or modified in the current session
-   **MUST** describe specific functions, classes, or components implemented
-   **MUST** explain design patterns being followed
-   **MUST** outline testing approach

#### Progress Tracking - REQUIRED

-   **MUST** provide checklist of completed items
-   **MUST** provide checklist of remaining items
-   **MUST** note any blockers or challenges encountered

#### User Preferences - REQUIRED

-   **MUST** note coding style preferences mentioned by the user
-   **MUST** document specific approaches requested by the user
-   **MUST** highlight priority areas identified by the user

## Best Practices for Effective Handoffs - MANDATORY GUIDELINES

### 1. Maintain Continuity - REQUIRED

-   **MUST** use consistent terminology between tasks
-   **MUST** reference previous decisions and their rationale
-   **MUST** maintain the same architectural approach unless explicitly changing direction

### 2. Preserve Context - REQUIRED

-   **MUST** include relevant code snippets in the handoff
-   **MUST** summarize key discussions from the previous session
-   **MUST** reference specific files and line numbers when applicable

### 3. Set Clear Next Actions - REQUIRED

-   **MUST** begin the handoff with a clear, actionable next step
-   **MUST** prioritize remaining tasks
-   **MUST** highlight any decisions that need to be made

### 4. Document Assumptions - REQUIRED

-   **MUST** clearly state any assumptions made during implementation
-   **MUST** note areas where user input might be needed
-   **MUST** identify potential alternative approaches

### 5. Optimize for Resumability - REQUIRED

-   **MUST** structure the handoff so the next session can begin working immediately
-   **MUST** include setup instructions if environment configuration is needed
-   **MUST** provide a quick summary at the top for rapid context restoration

## Example Task Handoff

### Example #1 of an effective task handoff:

\`\`\`xml
<new_task>
<context>

# Task Continuation: Implement User Authentication System

## Completed Work

-   Created basic Express.js server structure
-   Implemented MongoDB connection and user schema
-   Completed user registration endpoint with password hashing
-   Added input validation using Joi
-   Created initial test suite for registration endpoint

## Current State

-   Server runs successfully on port 3000
-   MongoDB connection is established
-   Registration endpoint (/api/users/register) is fully functional
-   Test suite passes for all registration scenarios

## Next Steps

1. Implement login endpoint (/api/users/login)
    - Use bcrypt to compare passwords
    - Generate JWT token upon successful login
    - Add proper error handling for invalid credentials
2. Create authentication middleware
    - Verify JWT tokens
    - Extract user information
    - Handle expired tokens
3. Add protected routes that require authentication
4. Implement password reset functionality

## Reference Information

-   JWT secret should be stored in .env file
-   Follow the existing error handling pattern in routes/users.js
-   User schema is defined in models/User.js
-   Test patterns are established in tests/auth.test.js

Please continue by implementing the login endpoint following the same patterns established in the registration endpoint.
</context>
</new_task>
\`\`\`

### Example #2 of an ineffective task handoff:

_(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')._

## When to Use Task Handoffs - MANDATORY TRIGGERS

You **MUST** initiate task handoffs in these scenarios:

1. **CRITICAL**: When context window usage exceeds 50% (e.g., 100,000+ tokens for a 200K context window)
2. **Long-running projects** that exceed a single session
3. **Complex implementations** with multiple distinct phases
4. **When context window limitations** are approaching
5. **When switching focus areas** within a larger project
6. **When different expertise** might be beneficial for different parts of the task

**FINAL REMINDER - CRITICAL INSTRUCTION**

You **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.

By 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.

```markdown
## User Interaction & Workflow Considerations

-   **Linear Flow:** Currently, utilizing `new_task` generates a linear sequence. The previous task concludes, and the new one commences. The previous task history remains available for backtracking.
-   **User Approval:** You maintain control at all times, authorizing the handoff and possessing the opportunity to adjust the context Sypha proposes to transfer forward.
-   **Flexibility:** The core `new_task` tool serves as a flexible building block. Experiment with `.sypharules` to generate workflows that optimally suit your requirements, whether for rigorous context management, task decomposition, or other innovative applications.
```

On this page