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>
111 lines
3.2 KiB
Markdown
111 lines
3.2 KiB
Markdown
# 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.
|