ralph-workplan/workplan-spec.md

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

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

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` \| `wait` | Task state |
| `priority` | no | `high` \| `medium` \| `low` | Execution priority |
| `depends_on` | with `wait` | list of workplan/task ids | External commitment: clears when every target is terminal |
| `needs_human` | with `wait` | `true` \| `false` | Human gate: a person clears it; the loop never picks the task up |
| `blocking_reason` | with `wait` | string | Required for `wait` |
| `decision_id` | no | string | Tracked decision or change request behind a human gate |

A `wait` task carries `depends_on`, `needs_human: true`, or both — never
neither (fleet standard: `the-custodian/canon/standards/task-wait-qualifiers_v0.1.md`).
The loop skips `wait` tasks; a workplan with only `wait` tasks left is not
done, so the loop stops with the wait reasons instead of emitting the promise.

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