# Workplan File Specification

A workplan is a Markdown file with YAML frontmatter that describes a unit of
work. It is the only input the `/ralph-workplan` skill needs.

## File Format

```markdown
---
id: WP-0001
title: "Build a thing"
status: active
---

Optional free-text description of the workplan scope and goals.

## Task: Do the first thing

```task
id: T-01
status: todo
priority: high
```

## Task: Do the second thing

```task
id: T-02
status: todo
priority: medium
```
```

## Frontmatter Fields

| Field | Required | Values | Description |
|-------|----------|--------|-------------|
| `id` | yes | string | Unique workplan identifier |
| `title` | yes | string | Human-readable name |
| `status` | yes | `active` \| `done` \| `paused` | Workplan lifecycle state |

## Task Blocks

Each task is a fenced code block with language tag `task`, embedded anywhere in
the document body. Fields:

| Field | Required | Values | Description |
|-------|----------|--------|-------------|
| `id` | yes | string | Unique task identifier within the workplan |
| `status` | yes | `todo` \| `in_progress` \| `done` | Task state |
| `priority` | no | `high` \| `medium` \| `low` | Execution priority |

## Completion Rule

A workplan is **done** when:
1. Every task block has `status: done`
2. The frontmatter `status` field is `done`

The skill updates both as work progresses — tasks individually, then the
workplan when all tasks are complete.

## Naming Convention

The skill works with any filename. A common convention used in custodian-family
projects is:

```
workplans/<PREFIX>-WP-NNNN-<slug>.md
```

but this is not required.