tegwick
4ab66e363e
Assistant: codex Assistant-Model: gpt-6-astra Assistant-Session: 01a13eab-1e6a-7b33-9c37-372e90ada3a2
112 lines
5.6 KiB
Text
112 lines
5.6 KiB
Text
## Workplan Convention (ADR-001)
|
|
|
|
File location: `workplans/{WP_PREFIX}-NNNN-<slug>.md`
|
|
ID prefix: `{WP_PREFIX}-`
|
|
|
|
Work items originate as files in this repo **before** being registered in the hub.
|
|
|
|
Canonical workplan frontmatter statuses are:
|
|
`proposed`, `ready`, `active`, `blocked`, `backlog`, `finished`, `archived`.
|
|
Use `proposed` for a newly drafted plan, `ready` after review against current
|
|
repo state, and `finished` when implementation is complete. `stalled` and
|
|
`needs_review` are derived health labels, not stored statuses.
|
|
|
|
Closed workplans may be moved to `workplans/archived/` with a completion-date
|
|
prefix: `YYMMDD-{WP_PREFIX}-NNNN-<slug>.md`. The frontmatter id remains
|
|
unchanged; the prefix is only for quick visual reference.
|
|
|
|
Small opportunistic tasks discovered during another session use **Ad Hoc Tasks**:
|
|
`workplans/ADHOC-YYYY-MM-DD.md`, workplan id
|
|
`{WP_PREFIX}-ADHOC-YYYY-MM-DD`, and task ids
|
|
`{WP_PREFIX}-ADHOC-YYYY-MM-DD-T01`, `T02`, etc. `{WP_PREFIX}` includes its final
|
|
`-WP` token. Unqualified historic `ADHOC-*` ids are grandfathered and must not
|
|
be copied into new records. Use adhocs only for low-risk work completed directly.
|
|
Promote anything requiring analysis, design, approval, dependencies, or multiple
|
|
planned phases into a normal workplan.
|
|
|
|
Ecosystem todos from other agents arrive as `[repo:{REPO_SLUG}]` hub tasks —
|
|
visible at session start. Pick one up by creating the workplan file, then run
|
|
the fast authoritative projection path:
|
|
|
|
```bash
|
|
uv run --project ~/repo-manager rmgr sync --path . --push
|
|
```
|
|
|
|
Repo Manager assigns only missing deterministic identifiers. Central reads the
|
|
exact pushed Forgejo commit and updates its replaceable projection. Never
|
|
register by hand with `create_workplan` or `create_task`. Use
|
|
`statehub fix-consistency` separately for a deep audit.
|
|
|
|
Task blocks use this shape:
|
|
|
|
```task
|
|
id: {WP_PREFIX}-NNNN-T01
|
|
status: wait | todo | progress | done | cancel
|
|
priority: high | medium | low
|
|
state_hub_task_id: "<uuid>" # written by fix-consistency — do not edit
|
|
```
|
|
|
|
Status progression is `todo` → `progress` → `done`; use `wait` for waiting or
|
|
blocked work and `cancel` for stopped work.
|
|
|
|
### Residuals (role, not kind)
|
|
|
|
When finishing a workplan, **actionable leftovers must become live work
|
|
records** before `status: finished`. Residual is not a registered kind and
|
|
must not be parked only in `SCOPE.md` or finished-file prose.
|
|
|
|
| Shape | Capture as | Links |
|
|
| --- | --- | --- |
|
|
| Small Green/Blue parkable | intake (queue YAML / `*-IN-*`) | `origin: residual`, `origin_ref: {WP_PREFIX}-NNNN` |
|
|
| Multi-step | next workplan | name parent WP; optional promote from residual intake |
|
|
| Founder gate / time | decision / engagement | same origin fields when from residual intake |
|
|
|
|
Fleet listing of residuals is a State Hub concern (`list_intakes` + origin
|
|
filters; planned `statehub residuals`). Canon:
|
|
`the-custodian/canon/standards/work-record-types_v0.1.md` § Residuals.
|
|
|
|
Workplan frontmatter carries `state_hub_workstream_id` — a legacy field name
|
|
kept for compatibility; it holds the hub workplan UUID and is written by
|
|
fix-consistency. Do not edit or rename it.
|
|
|
|
### Legacy terminology (compatibility footnote)
|
|
|
|
**Workplan** is the fleet term — see
|
|
`the-custodian/canon/standards/workplan-terminology-fleet_v0.1.md`.
|
|
**Workstream** is legacy only: some API routes (`/workstreams/`), params
|
|
(`workstream_id`), MCP aliases (`create_workstream`), and the frontmatter field
|
|
above remain until `STATE-WP-0069` retires them via legacy-meter. Treat those
|
|
identifiers as workplan IDs. Prefer `GET /workplans/` and `workplan_id` in new
|
|
examples and scripts.
|
|
|
|
<!-- Ralph Loop rules and HEUREKA sequence: ~/.claude/CLAUDE.md — do not duplicate here -->
|
|
|
|
### Task refinement after substantial work (required)
|
|
|
|
At each substantive checkpoint and before session close, compare the completed
|
|
work and new knowledge with the current task structure. If substantial work was
|
|
completed while the workplan's task granularity stayed unchanged, **add completed
|
|
task records for those evidenced outcomes and refine the remaining tasks**.
|
|
A long progress note inside the same broad open task does not satisfy this rule.
|
|
|
|
- Give each substantial completed deliverable a task with its actual outcome,
|
|
completion date, evidence and limits. Retrospective recording is allowed; do
|
|
not invent completion dates, deliveries, native acceptance or approvals.
|
|
- Split remaining work into independently manageable deliverables with an owner,
|
|
next action, completion criteria and real dependencies. Use `todo` for work
|
|
that can start; use `wait` only with a concrete prerequisite and unblock condition.
|
|
- Preserve existing task IDs, Hub UUIDs and history. When narrowing an umbrella
|
|
task, explain the split and map moved scope to the new task IDs. Do not mark
|
|
the umbrella done unless its retained scope is complete; preserve externally
|
|
referenced acceptance gates until their dependencies are satisfied.
|
|
- Keep task counts honest: extracting completed scope must not count the same
|
|
outcome twice or imply an effort-based completion percentage. Distinguish
|
|
source/fixture proof, actual operational proof and owner acceptance.
|
|
- Record new risks and out-of-scope findings as explicit disposition/handoff
|
|
tasks or linked live work records; do not silently expand authorization.
|
|
|
|
Make these changes in the repository source, commit/push, run the repository's
|
|
required projection sync, and verify the actual projected task counts, statuses
|
|
and dependencies. Progress events supplement the task structure; they do not
|
|
replace it. A checkpoint report must show both substantive outcomes and newly
|
|
refined remaining work when this rule is triggered.
|