crop-planner

SKILL.md

---
name: crop-planner
description: Plan crop rotations, planting schedules, and companion planting for garden beds and fields. Use when asked to manage a farm, garden, or plot layout; schedule what to plant and when; check companion planting relationships; track rotation history; or generate a printable planting schedule. Triggers include "crop rotation", "planting schedule", "companion planting", "garden bed", "what to plant", "frost dates", or any task involving seasonal crop planning.
---

# crop-planner

Plan what to grow, where, and when. Tracks beds, crops, rotations, and generates a planting calendar from your frost dates.

## When to Use

- Planning what crops to plant in which garden beds this season
- Checking companion planting relationships (friends and enemies)
- Detecting crop rotation conflicts (same family in same bed too soon)
- Computing planting dates from frost dates
- Generating a printable planting schedule
- Tracking crop history per bed across multiple seasons

## Prerequisites

1. crop-planner server running (local or Docker)
2. At least one bed added to the system
3. Frost dates configured for your location

## Installation

Self-hosted. Run with Docker:

```bash
docker compose up -d
# App accessible at http://localhost:3000
```

Or run locally:

```bash
pnpm install
pnpm dev
# App accessible at http://localhost:3000
```

## Key Concepts

### Beds

A bed represents a physical growing area: a raised bed, in-ground plot, or field strip. Each bed has dimensions (in feet or meters) and a grid layout where you assign crops to cells.

### Crops

The crop database includes 30 common crops with growing data: days to maturity, spacing, sun requirements, water needs, whether to direct sow or transplant, and weeks before frost to start indoors.

### Planting Calendar

The calendar computes all sow, transplant, and harvest dates from:
- Your last spring frost date
- Your first fall frost date
- Each crop's growing requirements

### Companion Planting

Each crop has defined friend and enemy relationships. The bed layout editor shows warnings when enemy crops are placed in adjacent cells.

### Crop Rotation

The system tracks which plant family was grown in each bed each year. When the same family is planted again before the required rest period, a conflict is flagged.

## API Reference

All endpoints are at `/api/`. Requires session cookie if `AUTH_PASSWORD` is set.

### Beds

| Method | Path | Description |
|---|---|---|
| GET | /api/beds | List all beds |
| POST | /api/beds | Create bed |
| GET | /api/beds/:id | Get bed with plantings |
| PATCH | /api/beds/:id/layout | Save layout JSON |

### Crops

| Method | Path | Description |
|---|---|---|
| GET | /api/crops | List crops (supports ?search= and ?family=) |
| POST | /api/crops | Create crop |
| GET | /api/crops/:id/companions | Get companion relationships |

### Calendar

| Method | Path | Description |
|---|---|---|
| GET | /api/calendar | Planting calendar for active location |
| GET | /api/calendar?year=2025 | Specific year |

### Rotation

| Method | Path | Description |
|---|---|---|
| GET | /api/rotation | Rotation history per bed |
| GET | /api/rotation/conflicts | Detected conflicts |

## Environment Variables

| Variable | Description | Default |
|---|---|---|
| PORT | HTTP server port | 3000 |
| DATA_DIR | Directory for database and uploads | ./data |
| AUTH_PASSWORD | Optional password (empty = no auth) | (empty) |
| NODE_ENV | development or production | development |
| SESSION_SECRET | Session signing secret | (required in prod) |
| LOG_LEVEL | debug, info, warn, error | info |

Boolean env vars use `0` (false) and `1` (true).

## Workflow Example

```
1. Add beds: POST /api/beds {name: "North Bed", width_ft: 4, length_ft: 12}
2. Set frost dates: POST /api/frost-dates {location_name: "Springfield, IL", last_spring_frost: "04-15", first_fall_frost: "10-15", usda_zone: "6a"}
3. Activate location: POST /api/frost-dates/:id/activate
4. View calendar: GET /api/calendar?year=2025
5. Create planting: POST /api/plantings {bed_id: "...", crop_id: "...", year: 2025, season: "spring", planned_sow_date: "2025-04-15"}
6. Check conflicts: GET /api/rotation/conflicts
```

## Troubleshooting

### Calendar shows no events

Ensure a frost date location is active: `GET /api/frost-dates`. At least one record must have `is_active: 1`.

### Companion warnings not showing in layout

The companion relationship must exist in both directions. Check `GET /api/crops/:id/companions` for each crop.

### Rotation conflict not detected

Confirm the plant family is spelled exactly as in the crop record. Conflicts are detected per `family` field value.