Bernd Worsch
9d57ce430f
workplan-spec.md: - Task Close Gate: when marking a task done in the file, also call update_task_status(state_hub_task_id, "done") in the State Hub - HEUREKA Completion Sequence: before HEUREKA, for hub-integrated workplans: update all tasks, update_workstream_status → done, add_progress_event milestone, then set status: done and output HEUREKA plugin/ralph-workplan.md: - Added State-Hub Integration Notes section injected via stop-hook prompt so the worker follows Task Close Gate and HEUREKA Completion Sequence Resolves: state-hub progress event 1e73441e (2026-03-16) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
3.2 KiB
3.2 KiB
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` | 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>:
- For each task with a
state_hub_task_id: callupdate_task_status(id, "done")(idempotent — safe to call even if the Task Close Gate already did it) - Call
update_workstream_status(state_hub_workstream_id, "done") - Call
add_progress_event(summary="...", event_type="milestone", topic_id=..., workstream_id=...)summarising what was delivered - Update the workplan frontmatter:
status: active → status: done - 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.