task-runner

# task-runner skill

Use this skill when the user wants to:
- Run one or more tasks with dependency resolution
- View current task status
- Understand tasks.yaml configuration
- Use the web dashboard to monitor a run

## Prerequisites

```
# Server must be running (starts automatically with mtr run)
node dist/mtr.js serve
# or just run tasks directly
node dist/mtr.js run --all
```

## tasks.yaml format

```yaml
tasks:
  <name>:
    command: <shell command>      # required
    depends_on: [task1, task2]    # optional - other task names
    inputs:                       # optional - glob patterns for cache key
      - "packages/*/src/**/*.ts"
    outputs:                      # optional - files to cache/restore
      - "packages/*/dist/**"
    env:                          # optional - extra env vars
      NODE_ENV: production
    cwd: packages/server          # optional - working directory
    timeout: 300000               # optional - ms (default 300s)
```

## Running tasks

```bash
# Run all tasks
mtr run --all

# Run specific tasks (includes their dependencies automatically)
mtr run build

# Run multiple tasks
mtr run lint typecheck

# Skip cache for a full re-run
mtr run --all --force

# Custom config file
mtr run --config ./ci/tasks.yaml --all
```

## Task status

```bash
mtr status
```

Output columns: TASK, STATUS, LAST RUN, DURATION, CACHE

Status values:
- success - completed successfully
- failed - exited non-zero
- cached - skipped, cache hit used
- skipped - not run because a dependency failed
- running - currently executing
- pending - waiting for dependencies

## Dependency resolution

Tasks are executed in topological order. Tasks at the same stage (no mutual dependency) run concurrently up to MTR_CONCURRENCY (default 4).

Example for tasks.yaml with `test -> build -> [lint, typecheck]`:
- Stage 1: lint and typecheck run concurrently
- Stage 2: build runs after both pass
- Stage 3: test runs after build passes

If any task fails: no new tasks start, running tasks finish, dependents marked skipped.

## Web dashboard

Open http://127.0.0.1:3300 to see:
- Pipeline view: stage grid with task cards, live status updates via SSE
- Run history: all past runs with status and duration
- Task detail: per-task run history, cache hit rate
- Cache view: list entries, delete individual or all

The dashboard auto-refreshes during active runs. No manual reload needed.

## Environment variables

```
MTR_PORT=3300           Web UI port
MTR_HOST=127.0.0.1      Bind address
MTR_CACHE_DIR=./.mtr-cache   Cache location
MTR_CONCURRENCY=4       Parallel task limit
MTR_WEB_ENABLED=1       0 to disable web UI
```

## Exit codes

- 0: all tasks passed
- 1: one or more tasks failed
- 2: config error (bad tasks.yaml, circular dependency)