Skill: farm-task-manager

# Skill: farm-task-manager

## Purpose

Create, update, query, and complete farm tasks. Manage recurring templates, crew assignments, and task categories. Understand task status flow and how the cron job generates daily tasks.

## Data Model Quick Reference

### Task status flow

```
todo -> in-progress -> done
todo -> overdue (cron, when due_date < today and status != done)
in-progress -> overdue (cron, when due_date < today)
```

Overdue is set automatically by the cron job at 06:00 each morning. An overdue task can still be marked done by a user.

### Task priority levels

| Value | Color token | Description |
|-------|-------------|-------------|
| low | --priority-low (#6b7280) | Non-urgent background work |
| medium | --priority-medium (#2563eb) | Standard farm tasks |
| high | --priority-high (#d97706) | Time-sensitive, same-day |
| urgent | --priority-urgent (#dc2626) | Safety or animal welfare |

### Recurring schedule types

| Type | schedule_days | schedule_day_of_month | season_start / season_end |
|------|---------------|----------------------|---------------------------|
| daily | null | null | null |
| weekly | JSON array of integers 0-6 (0=Sun) | null | null |
| monthly | null | integer 1-28 | null |
| seasonal | null | null | "MM-DD" strings (e.g. "07-01" / "09-30") |

## API Quick Reference

### Tasks

```
GET    /api/tasks                  list tasks; filters: status, priority, assigned_to, category_id, due_date
GET    /api/tasks/:id              get single task with assignees
POST   /api/tasks                  create task
PUT    /api/tasks/:id              update task fields
POST   /api/tasks/:id/complete     mark done: { completed_by_id, actual_hours?, notes? }
DELETE /api/tasks/:id              delete task
```

#### Create task body

```json
{
  "title": "Harvest Tomatoes - North Field rows 1-4",
  "category_id": "uuid",
  "priority": "high",
  "due_date": "2025-07-20T12:00:00.000Z",
  "location": "North Field",
  "estimated_hours": 3.0,
  "description": "Harvest ripe tomatoes from rows 1-4. Sort by grade A/B/C.",
  "assigned_to": ["crew-member-uuid-1", "crew-member-uuid-2"],
  "template_id": "uuid-or-null"
}
```

#### Complete task body

```json
{
  "completed_by_id": "crew-member-uuid",
  "actual_hours": 2.8,
  "notes": "Completed rows 1-4, approximately 240kg harvested."
}
```

### Recurring Templates

```
GET    /api/recurring              list all templates
GET    /api/recurring/:id          get template
POST   /api/recurring              create template
PUT    /api/recurring/:id          update template
DELETE /api/recurring/:id          delete template
POST   /api/recurring/:id/generate force-generate today's task instance
```

#### Create template body

```json
{
  "title": "Morning livestock feeding - all paddocks",
  "category_id": "uuid",
  "priority": "high",
  "assigned_to_id": "crew-member-uuid",
  "schedule_type": "daily",
  "schedule_days": null,
  "schedule_day_of_month": null,
  "season_start": null,
  "season_end": null,
  "estimated_hours": 1.5,
  "location": "All paddocks",
  "description": "Feed all livestock in paddocks 1-4. Check water and hay levels.",
  "active": 1
}
```

Weekly template example:

```json
{
  "title": "Weekly equipment safety inspection",
  "schedule_type": "weekly",
  "schedule_days": "[1,3,5]",
  "priority": "high"
}
```

Seasonal template example:

```json
{
  "title": "Tomato harvest - season peak",
  "schedule_type": "seasonal",
  "season_start": "07-01",
  "season_end": "09-30",
  "priority": "high"
}
```

### Crew

```
GET    /api/crew                   list active crew members
GET    /api/crew/:id               get crew member with task stats
POST   /api/crew                   create crew member: { name, role, active? }
PUT    /api/crew/:id               update crew member
DELETE /api/crew/:id               deactivate (sets active=0)
```

### Categories

```
GET    /api/categories             list categories (id, name, color_hex)
POST   /api/categories             create: { name, color_hex }
PUT    /api/categories/:id         update
DELETE /api/categories/:id         delete (only if no tasks reference it)
```

### Analytics

```
GET    /api/analytics/completion-rate     ?period=week|month|year
GET    /api/analytics/crew-workload       ?period=week|month
GET    /api/analytics/overdue-report      list all currently overdue tasks
GET    /api/analytics/category-breakdown  task counts and hours by category
```

#### Completion rate response shape

```json
{
  "period": "week",
  "total_tasks": 42,
  "completed": 30,
  "rate": 0.714,
  "by_priority": {
    "urgent": { "total": 3, "completed": 2 },
    "high": { "total": 15, "completed": 12 }
  }
}
```

### Settings

```
GET    /api/settings               get all settings as key-value object
PUT    /api/settings               update: { farm_name?, timezone?, work_start_time? }
```

## Cron Job Behavior

The cron job runs daily at `work_start_time` (default 06:00 local farm time).

**Step 1 - Generate from templates:**
- For each active template where `active = 1`:
  - daily: always generate
  - weekly: generate if `day_of_week` in `schedule_days`
  - monthly: generate if today's day-of-month matches `schedule_day_of_month`
  - seasonal: generate if today's MM-DD is within `season_start` to `season_end` inclusive
- Skip if a task with the same `template_id` and the same `due_date` already exists (idempotent)

**Step 2 - Mark overdue:**
- Set `status = 'overdue'` for all tasks where `status IN ('todo','in-progress')` and `due_date < today 00:00`

## Task Assignment

A task can have zero or more assignees stored in the `task_assignments` join table. The `assigned_to` array in create/update requests replaces all existing assignments. An empty array means unassigned.

## Example: Creating a One-Off Task

```json
POST /api/tasks
{
  "title": "Repair fence - South boundary breach",
  "category_id": "<field-work-category-id>",
  "priority": "urgent",
  "due_date": "2025-07-18T17:00:00.000Z",
  "location": "South boundary",
  "estimated_hours": 3.0,
  "assigned_to": ["<carlos-id>"]
}
```

## Example: Completing a Task

```json
POST /api/tasks/<task-id>/complete
{
  "completed_by_id": "<carlos-id>",
  "actual_hours": 3.5,
  "notes": "Replaced three posts and 12m of wire fencing."
}
```

Response sets `status = 'done'`, `completed_at = now()`, stores `actual_hours` and `notes`.