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

## Task Close Gate (State-Hub Projects)

When a workplan contains `state_hub_workstream_id` in its frontmatter and a
task block contains `state_hub_task_id`, the worker must call
`update_task_status(state_hub_task_id, "done")` in the State Hub at the same
time as marking the task `done` in the file.

**Why:** The file is the authoritative source of truth (ADR-001), but the hub
is the read model used for dashboards and consistency checks. Keeping them in
sync per-task prevents drift from accumulating and avoids the manual repair
sessions that result from batch-syncing at the end only.

Example task block with hub binding:

```task
id: MRKD-WP-0003-T01
status: todo
priority: high
state_hub_task_id: 51e1b53e-a62f-496b-892d-615513c35d67
```

## HEUREKA Completion Sequence (State-Hub Projects)

When all task blocks are `done` and the workplan is about to be closed, a
state-hub-integrated workplan requires a close-out sequence **before**
outputting `<promise>HEUREKA</promise>`:

1. For each task with a `state_hub_task_id`: call `update_task_status(id, "done")`
   (idempotent — safe to call even if the Task Close Gate already did it)
2. Call `update_workstream_status(state_hub_workstream_id, "done")`
3. Call `add_progress_event(summary="...", event_type="milestone",
   topic_id=..., workstream_id=...)` summarising what was delivered
4. Update the workplan frontmatter: `status: active → status: done`
5. Output `<promise>HEUREKA</promise>`

This sequence ensures the hub dashboard reflects completion without requiring
a separate manual sync. The C-13 consistency check will WARN (and auto-fix)
if step 2 is missed, but completing it proactively avoids the warning.

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