# Tasks

A task is a set of instructions to accomplish an atomic goal. Each task lives in its own directory under `tasks/` and is defined by a `TASK.md` file.

## File Structure

```
tasks/
  <task-slug>/
    TASK.md
```

## TASK.md Format

A task file has two parts: **frontmatter** (YAML metadata) and **body** (Markdown instructions).

### Frontmatter

```yaml
---
name: Task Name
description: A short description of what the task does.
version: 1
author: pastilhas
tags:
  - tag1
  - tag2
skills:
  - skill-name
trigger:
  - type: file
    extensions:
      - ext1
      - ext2
  - type: directory
inputs:
  - name: input_name
    description: What this input is.
    type: string
    required: true
  - name: count
    description: How many items to process.
    type: number
    default: 10
    required: false
  - name: verbose
    description: Enable verbose output.
    type: boolean
    default: false
    required: false
  - name: format
    description: Output format.
    type: select
    default: json
    required: false
    options:
      - value: json
        label: JSON
      - value: csv
        label: CSV
      - value: md
        label: Markdown
---
```

#### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | yes | Human-readable name of the task. |
| `description` | string | yes | Short description of what the task does. |
| `version` | integer | no | Version number of the task definition. |
| `author` | string | no | Author of the task. |
| `tags` | string[] | no | Tags for categorization. |
| `skills` | string[] | no | Skills required to execute the task. |
| `trigger` | object[] | no | List of triggers that define when this task is applicable. |
| `trigger[].type` | string | yes | What the trigger applies to (`file` or `directory`). |
| `trigger[].extensions` | string[] | no | File extensions that match this trigger. Only applicable when `type` is `file`. |
| `inputs` | object[] | no | Inputs the task expects. |
| `inputs[].name` | string | yes | Name of the input parameter. |
| `inputs[].description` | string | yes | Description of the input. |
| `inputs[].type` | string | no | Input type. Determines how a task runner renders the input. One of: `string`, `number`, `boolean`, `select`. Defaults to `string`. |
| `inputs[].default` | any | no | Default value for the input. |
| `inputs[].required` | boolean | no | Whether the input is required. |
| `inputs[].options` | object[] | no | Available choices when `type` is `select`. Each option has a `value` and a `label`. |
| `inputs[].options[].value` | string | yes | The value passed to the task. |
| `inputs[].options[].label` | string | yes | Human-readable label displayed in the UI. |

### Body

The body contains:

1. **Title** — `# Task Name`, matching the frontmatter `name`.
2. **Description** — A one-line summary, matching the frontmatter `description`.
3. **Steps** — An ordered list under `## Steps` describing the instructions to accomplish the task.

### Example

```markdown
---
name: Transcribe Audio File
description: Transcribe an audio file to text using whisper.cpp.
version: 1
author: pastilhas
tags:
  - audio
  - transcription
skills:
  - whisper.cpp
trigger:
  - type: file
    extensions:
      - mp3
      - wav
      - m4a
inputs:
  - name: file_path
    description: Path to the audio file to transcribe.
    required: true
---

# Transcribe Audio File

Transcribe an audio file to text using whisper.cpp.

## Steps

1. First step.
2. Second step.
3. Third step.
```
