# 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.
    required: true
---
```

#### 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[].required` | boolean | no | Whether the input is required. |

### 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.
```