Agent Sub-Tasks

Agent Sub-Tasks allow you to break down a session’s objective into smaller, trackable units of work. They provide lightweight structure within an active session, helping organize complex implementation or analysis into discrete steps.

Sub-tasks exist inside a session and are tied to the work being performed in that specific branch and workspace state.

What an Agent Sub-Task Is

An Agent Sub-Task represents a focused unit of work within a session.

It is used to:

• define a specific objective,
• track progress toward completion,
• and isolate work items under a broader session goal.

Sub-tasks are not separate sessions and do not create new branches. They operate within the current session’s environment.

How Agent Sub-Tasks Fit Into the Work Hierarchy

The execution hierarchy is structured as follows:

• A Project contains the deployed repository.
• A Task defines the high-level goal.
• A Trial represents an attempt to complete that goal.
• A Session captures the working conversation and execution.
• An Agent Sub-Task breaks that session into smaller actionable units.

Sub-tasks provide micro-structure within a session without requiring a new session or trial.

Creating a Sub-Task

Inside a session, you can add a sub-task directly.

Each sub-task:

• has a short descriptive title,
• appears in the session’s task panel,
• and can be marked as complete once finished.

Sub-tasks are designed to be concise and action-oriented.

Example

If a session’s objective is:

“Write test cases for major components”

Sub-tasks might include:

• Write tests for navigation flows
• Add tests for form validation
• Cover edge cases in API error handling

This allows incremental progress tracking without losing overall context.

When to Use Agent Sub-Tasks

Agent Sub-Tasks are most useful when:

Implementing Multi-Step Features

Breaking a feature into steps improves clarity and prevents large, unstructured changes.

Example:

• Create database schema
• Implement API endpoints
• Add UI components
• Write integration tests

Large Refactors

For architectural changes, sub-tasks can separate concerns such as:

• Remove deprecated utilities
• Update imports across modules
• Refactor service layer
• Validate backward compatibility

Test Coverage Expansion

When adding coverage, sub-tasks can group related test areas without starting new sessions.

Structured Debugging

If debugging spans multiple components, sub-tasks help track investigation steps:

• Reproduce issue
• Inspect logs
• Identify failing dependency
• Apply fix

Progress Tracking

Each sub-task can be marked complete independently.

This provides:

• visual feedback inside the session,
• clarity on what remains,
• and a structured record of execution steps.

Completion of sub-tasks does not automatically finalize the session. They serve as internal execution checkpoints.

Relationship to Agent Execution

Sub-tasks do not change how the agent reasons or executes code. They provide organizational structure for the user.

However, clearly defined sub-tasks can improve agent performance by:

• narrowing scope,
• clarifying expectations,
• and reducing ambiguity in instructions.

They act as execution scaffolding rather than independent workflows.

Boundaries

Agent Sub-Tasks:

• do not create new branches,
• do not modify repository state on their own,
• and do not replace Tasks or Sessions.

They exist only within the active session and are scoped to its branch and execution history.