---
name: task
---
# Task Workflow

The task workflow produces `task.md` — the starting point for any unit of work. It takes a raw description or a Linear issue ID and turns it into a structured task file with frontmatter (name, modules) and a body.

## Inputs

- `work_folder` (required) — where the task will be created. The folder name is used as the task ID (e.g. `tasks/SYS-42` → task_id is `SYS-42`). Created automatically if it doesn't exist.
- `description` — what needs to be done. Required for local tasks that don't exist yet.
- `modules` — which project modules this task affects. Accepts `"all"` or comma-separated names. If omitted, the router agent resolves it.
- `sync` / `sync_to_linear` — push the task to Linear after creation.
- `task_prefix`, `api_key`, `team_id` — Linear configuration overrides.
- `instructions` — optional free-text guidance for the builder agent.

## Orchestration

The orchestrator (`create_task.py`) has two main branches:

- **Linear** — if the task ID matches the project's configured Linear prefix (e.g., `MIXER-123`), the orchestrator fetches the issue from Linear and writes it as `task.md`.
- **Local** — otherwise, it creates `task.md` from the provided description. The builder agent generates the title.

After the task file exists, the orchestrator determines which modules the task affects. If modules were passed explicitly, it uses those. If not, it calls the router agent to figure it out from the task description and project docs.

Optionally, tasks can be synced back to Linear — either updating an existing issue or pushing a new one (which renames the work folder to the new issue ID).

## Agents

**Builder** (`task_builder.py`, model L) — takes a raw description and structures it into `task.md` following the template. Extracts clear requirements, sets frontmatter, preserves original intent.

**Router** (`agents/task_router.py`, model M, read-only) — determines which project modules a task affects. Returns a comma-separated list of module names or `"all"`. Only called when modules aren't specified.
