> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ctrlnode.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create task

> New task form — title, instructions, agent, MODE, and inputs

Create a standalone task from the project **Tasks** board or list.

**Route:** `/projects/{projectId}/tasks/new`

**In the app:** **+ New task** on the Kanban or list view.

You can also open create from a **workflow designer** step (**New task** on a stage); saving returns you to the designer when `from=pipeline-designer` is in the URL.

## Form fields

| Field               | Required                  | Notes                                                     |
| ------------------- | ------------------------- | --------------------------------------------------------- |
| **TITLE**           | Yes                       | Short name; Enter submits when filled                     |
| **INSTRUCTIONS**    | No                        | Markdown — goals, constraints, acceptance criteria        |
| **ASSIGN TO AGENT** | No                        | Pick an agent or leave **UNASSIGNED**                     |
| **MODE**            | Yes (default OUTPUT ONLY) | Where the agent may read/write on the Bridge — see below  |
| **INPUTS**          | No                        | Files uploaded after create (attached to the task folder) |

After **Create**, you land on **task detail** in **Backlog** (or return to the workflow designer when applicable).

***

## Work mode (MODE)

The **MODE** chips control where the agent may read and write files on the Bridge host. This is set at **create** time (the same control appears when editing a task in **Backlog** before dispatch).

### The MODE control

| UI label           | API value | Summary                                          |
| ------------------ | --------- | ------------------------------------------------ |
| **OUTPUT ONLY**    | `output`  | Default — isolated task folder under `.ctrlnode` |
| **WORK DIRECTORY** | `repo`    | Full project directory (or Bridge home)          |

### OUTPUT ONLY (default)

**Stored as:** `task_mode = output`

Help text in the app:

> Default: deliverables go to this task's isolated output folder under `.ctrlnode`. Uploaded **Inputs** are attachments for context.

| Behavior            | Detail                                                    |
| ------------------- | --------------------------------------------------------- |
| **Writes**          | Mainly to `{BASE_PATH}/.ctrlnode/tasks/...` for this task |
| **Uploaded inputs** | Context attachments — not a full repo checkout            |
| **Typical use**     | Reports, pipeline steps, review tasks, untrusted prompts  |

### WORK DIRECTORY

**Stored as:** `task_mode = repo`

The agent can read and change files across the **full directory** configured for the project — not only uploaded inputs.

#### Scope panel

A green-bordered panel shows either:

| Label                      | When                                                                  |
| -------------------------- | --------------------------------------------------------------------- |
| **PROJECT WORK DIRECTORY** | Project has `repositoryPaths[0]` set — shows the absolute path        |
| **BRIDGE WORKSPACE HOME**  | No project path — uses Bridge `BASE_PATH` (requires Bridge connected) |

If no project work directory is configured:

> No project work directory set — using the Bridge workspace root. Set one in project settings to scope tasks to a subfolder.

Configure the path in [Project work directory](/projects/project-work-directory).

#### Focus paths (optional)

| UI state                                           | Meaning                                          |
| -------------------------------------------------- | ------------------------------------------------ |
| **NO FOCUS PATHS — AGENT EXPLORES FULL DIRECTORY** | Agent may use the entire work directory          |
| **+ SELECT PATHS** / **EDIT**                      | File/folder picker limited to the work directory |
| **N FOCUS PATH(S) SELECTED**                       | Agent limited to those absolute paths            |

You can also describe paths in **Instructions** for soft guidance.

<Warning>
  **WORK DIRECTORY** lets the agent modify real project files. Prefer **OUTPUT ONLY** when you only need deliverables in the task folder or the prompt is not fully trusted.
</Warning>

### How it reaches the Bridge

1. CtrlNode saves `task_mode` and `focus_files` on the task.
2. On dispatch, the API sends `repositoryPaths` and focus paths when applicable.
3. The Bridge builds **repo dispatch context** for every provider.

Bridge must be **connected** to resolve **BRIDGE WORKSPACE HOME** when the project has no work directory.

### Quick comparison

|                  | OUTPUT ONLY                          | WORK DIRECTORY                      |
| ---------------- | ------------------------------------ | ----------------------------------- |
| Default          | Yes                                  | No                                  |
| Writes mainly to | Task output folder under `.ctrlnode` | Project path or `BASE_PATH`         |
| Uploaded inputs  | Context only                         | Context + full tree access          |
| Limit scope      | Task folder only                     | Optional focus paths + Instructions |
| Typical use      | Deliverables, isolated runs          | Refactors, repo-wide changes        |

***

## Related

<CardGroup cols={2}>
  <Card title="Task detail" icon="file-lines" href="/tasks/task-detail">
    After create — instructions, artifacts, agent activity.
  </Card>

  <Card title="Project work directory" icon="folder-open" href="/projects/project-work-directory">
    Path used by WORK DIRECTORY mode.
  </Card>
</CardGroup>