Task

Tasks represent the unit of intent in the workspace. A task captures what you are trying to accomplish before any execution begins, such as implementing a feature, fixing a bug, investigating behavior, or reviewing changes.

The Tasks view provides a structured place to define, track, and manage this intent while coordinating agent-driven work across trials and sessions.

What a Task Is

A task defines the goal of work within a project. It describes the outcome you want, not how it should be achieved.

A task exists independently of any single agent interaction. Multiple execution attempts, conversations, or approaches can be explored under the same task without losing the original intent.

Tasks help separate:

• what needs to be done (the task),
• from how it is attempted (trials),
• and the conversational execution (sessions).

What the Tasks View Shows

The Tasks view surfaces all information related to a single task in one place.

This includes:

• the task title and description,
• current status and priority,
• associated labels and metadata,
• comments and discussion,
• linked trials and sessions,
• and any attached artifacts or references.

This view acts as the control center for managing work on a task over time.

Task Status and Metadata

Each task includes structured metadata that helps track progress and urgency.

Common attributes include:

• status indicators such as in progress or urgent,
• effort or time estimates,
• milestones or cycles,
• ownership or assignment,
• and labels used for categorization.

These attributes do not affect agent execution directly, but provide operational context for organizing and prioritizing work.

Example

A task labeled “Features & DX” with an urgent status communicates priority to collaborators, even though agent behavior remains scoped to explicit instructions.

Task Description and Context

The task description captures the problem statement or objective in natural language.

This description serves as a reference point for all trials under the task. Agents can use it to maintain alignment across multiple execution attempts without requiring you to restate the goal each time.

Well-defined task descriptions improve consistency, especially when:

• revisiting work later,
• running parallel trials,
• or collaborating across team members.

Comments and Collaboration

The Tasks view includes a comments section for discussion and clarification.

Comments are useful for:

• capturing decisions or constraints,
• leaving guidance for future trials,
• coordinating between team members,
• or documenting rationale that should not live in code.

Comments are not treated as executable instructions, but they remain visible context for anyone working on the task.

Trials and Execution Attempts

Each task can have multiple trials.

A trial represents a single attempt to work toward the task’s goal. Trials allow you to:

• explore different approaches,
• restart from a clean execution state,
• compare outcomes without losing prior work.

Each trial contains one or more sessions where actual agent interaction occurs.

Example

If an initial trial produces an unsatisfactory implementation, you can start a new trial under the same task to try a different approach while preserving the original attempt for reference.

Relationship Between Tasks, Trials, and Sessions

The hierarchy is intentional:

• A Task defines the goal.
• A Trial represents an execution attempt.
• A Session captures the conversational and execution flow.

This structure ensures that experimentation does not overwrite intent and that execution history remains traceable.

Using Tasks to Guide Agent Work

Tasks provide durable framing for agent interactions.

When a session is linked to a task, agents operate with awareness of:

• the task’s objective,
• any associated context or comments,
• and the history of prior attempts.

This allows work to remain coherent even across multiple sessions or restarts.

When to Use Tasks

Tasks are best used when:

• work spans multiple steps or iterations,
• you expect to try more than one approach,
• collaboration or handoff is involved,
• or traceability matters.

For quick, one-off questions or explorations, a standalone session may be sufficient. For anything that resembles real development work, tasks provide structure and continuity.

Boundaries and Control

Creating or modifying a task does not execute any code or trigger agent actions.

Tasks:

• define intent and organization,
• do not modify the repository,
• and do not bypass review or execution controls.

All execution still occurs through sessions and remains governed by project settings and permissions.