forge-openclaw-plugin 0.2.93 → 0.2.96

package/skills/forge-openclaw/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: forge-openclaw-plugin
-description: use when the user wants to save, search, update, review, start, stop, reward, explain, compare, or run Forge records, or when the conversation is clearly about a Forge entity or domain surface such as a goal, project, strategy, task, habit, note, wiki_page, calendar_event, calendar_connection, work_block_template, task_timebox, task_run, work_adjustment, insight, preference item, preference context, preference catalog, preference judgment, preference signal, questionnaire instrument, questionnaire run, self observation, movement, life_force, workbench, psyche_value, behavior_pattern, behavior, belief_entry, mode_profile, mode_guide_session, flashcard, trigger_report, event_type, emotion_definition, sleep_session, or workout_session. identify the exact Forge object or specialized surface, keep the main conversation natural, guide psyche intake with active listening before storing it, and for psyche issues that need understanding first usually begin with one exploratory question before any formulation or save suggestion.
+description: use when the user wants to save, search, update, review, start, stop, reward, explain, compare, or run Forge records, or when the conversation is clearly about a Forge entity or domain surface such as a goal, project, strategy, task, habit, note, wiki_page, calendar_event, calendar_connection, work_block_template, task_timebox, task_run, work_adjustment, insight, preference item, preference context, preference catalog, preference judgment, preference signal, questionnaire instrument, questionnaire run, self observation, movement, life_force, workbench, psyche_value, behavior_pattern, behavior, belief_entry, mode_profile, mode_guide_session, flashcard, trigger_report, event_type, emotion_definition, sleep_session, workout_session, or training_load. identify the exact Forge object or specialized surface, keep the main conversation natural, guide psyche intake with active listening before storing it, and for psyche issues that need understanding first usually begin with one exploratory question before any formulation or save suggestion.
 ---
 
 Forge is the user's structured system for planning work, doing work, reflecting on patterns, and keeping a truthful record of what is happening. Use it when the user is clearly working inside that system, or when they are describing something that naturally belongs there and would benefit from being stored, updated, reviewed, or acted on in Forge. Keep the conversation natural first. Do not turn every message into intake. When a real Forge entity is clearly present, name the exact entity type plainly, help with the substance of the conversation, and then offer Forge once, lightly, if storing it would genuinely help.
@@ -59,7 +59,7 @@ PM surface rule:
   human/bot ownership filters.
 - Guided modal flows handle create, edit, move, link, and closeout actions.
 
-Forge has four major stored-entity surfaces and three specialized domain surfaces. The planning side covers goals, projects, strategies, tasks, habits, notes, calendar events, recurring work blocks, task timeboxes, live work sessions, and agent-authored insights. The Health side covers sleep sessions, sports and workout sessions, companion pairing, and habit-generated workout records that should still stay linked to the broader Forge graph. The Preferences side covers contextual taste modeling, pairwise comparisons, direct signals, editable concept libraries, and preference items that can come from Forge entities or seeded concept domains such as food, activities, places, countries, fashion, people, media, and tools. The Psyche side covers values, patterns, behaviors, beliefs, modes, guided mode sessions, flashcards, trigger reports, event types, and reusable emotion definitions. The specialized domain surfaces are Movement, Life Force, and Workbench; agents must use their dedicated route families instead of forcing them through batch CRUD. Forge also has a SQLite-backed Wiki memory layer with explicit spaces, Markdown content in database rows, backlinks, optional embeddings, and structured links back to Forge entities. Forge is also multi-user: every entity can belong to a typed `human` or `bot` user through `userId`, and read routes can scope to one or many users with `userId` or repeated `userIds`. The current access posture is configurable through a directional user graph, but the live default is still permissive: Forge can list users directly, every relationship edge starts open, and a user can read or affect another user's linked records when the route explicitly asks for them. Use `forge_get_user_directory` when owner identity or cross-user access matters. Strategies can also be locked into a contract with `isLocked`; once locked, do not mutate the graph or target structure unless the user explicitly wants the strategy unlocked first. The model should use the real entity names, not vague substitutes. Say `project`, not “initiative”. Say `behavior_pattern`, not “theme”. Say `trigger_report`, not “incident note”.
+Forge has four major stored-entity surfaces and three specialized domain surfaces. The planning side covers goals, projects, strategies, tasks, habits, notes, calendar events, recurring work blocks, task timeboxes, live work sessions, and agent-authored insights. The Health side covers sleep sessions, sports and workout sessions, the read-only training-load surface for cardiovascular load and HR zone review, companion pairing, and habit-generated workout records that should still stay linked to the broader Forge graph. The Preferences side covers contextual taste modeling, pairwise comparisons, direct signals, editable concept libraries, and preference items that can come from Forge entities or seeded concept domains such as food, activities, places, countries, fashion, people, media, and tools. The Psyche side covers values, patterns, behaviors, beliefs, modes, guided mode sessions, flashcards, trigger reports, event types, and reusable emotion definitions. The specialized domain surfaces are Movement, Life Force, and Workbench; agents must use their dedicated route families instead of forcing them through batch CRUD. Forge also has a SQLite-backed Wiki memory layer with explicit spaces, Markdown content in database rows, backlinks, optional embeddings, and structured links back to Forge entities. Forge is also multi-user: every entity can belong to a typed `human` or `bot` user through `userId`, and read routes can scope to one or many users with `userId` or repeated `userIds`. The current access posture is configurable through a directional user graph, but the live default is still permissive: Forge can list users directly, every relationship edge starts open, and a user can read or affect another user's linked records when the route explicitly asks for them. Use `forge_get_user_directory` when owner identity or cross-user access matters. Strategies can also be locked into a contract with `isLocked`; once locked, do not mutate the graph or target structure unless the user explicitly wants the strategy unlocked first. The model should use the real entity names, not vague substitutes. Say `project`, not “initiative”. Say `behavior_pattern`, not “theme”. Say `trigger_report`, not “incident note”.
 Habits are a first-class recurring entity in the planning side.
 NEGATIVE HABIT CHECK-IN RULE: for a `negative` habit, the correct aligned/resisted outcome is `missed`. `missed` means the bad habit was resisted, the user stayed aligned, and the habit should award its XP bonus.
 
@@ -199,14 +199,16 @@ Wiki navigation and search rule:
 Health rule:
 
 - Sleep and sports records are first-class health surfaces, not generic notes or tasks.
-- Use `forge_get_sleep_overview` and `forge_get_sports_overview` for review and trend reading.
+- Use `forge_get_sleep_overview`, `forge_get_sports_overview`, and
+  `forge_get_training_load_overview` for health review and trend reading.
 - In `forge_get_agent_onboarding.entityRouteModel.readModelOnlySurfaces`, operator,
-  calendar, self-observation, sleep, and sports read models are published with
+  calendar, self-observation, sleep, sports, and training-load read models are published with
   both camelCase names and entity-style aliases where useful, including
   `operatorOverview`, `operatorContext`, `calendarOverview`, `sleepOverview`,
-  `sportsOverview`, `operator_overview`, `operator_context`,
-  `calendar_overview`, `self_observation`, `sleep_overview`, and
-  `sports_overview`. Treat those as read-only surfaces, not batch CRUD entities.
+  `sportsOverview`, `trainingLoad`, `operator_overview`, `operator_context`,
+  `calendar_overview`, `self_observation`, `sleep_overview`,
+  `sports_overview`, and `training_load`. Treat those as read-only surfaces,
+  not batch CRUD entities.
 - Use `forge_get_operator_overview` for a broad Forge status read, `forge_get_operator_context`
   for current work and risk, and `forge_get_calendar_overview` before calendar-aware
   planning or scheduling mutations.
@@ -237,6 +239,7 @@ Entity conversation rule:
 - When updating an entity, start with what is changing, what should stay true, and what prompted the update now.
 - When enough is clear, briefly summarize what you heard in the user's own language before asking for the last missing structural detail.
 - Treat `userId` and human/bot assignees as accountability and scope, not as opening form fields. Ask whose human or bot record it is only when ownership changes visibility, review scope, collaboration, automation behavior, or later filtering; for read requests, ask user scope only when the answer would differ across owners.
+- Treat questionnaire runs, self-observations, reflective notes, wiki pages, sleep/workout enrichment, and preference signals as reflection-sensitive records: ask what the record should help the user understand, decide, notice, remember, or change later, then choose the right route. Do not flatten them into forms, but also do not automatically turn them into full Psyche intake unless a belief, mode, trigger report, or behavior pattern clearly emerges.
 - The quick intake prompts later in this file are fallback checkpoints, not a script to read aloud.
 
 Forge data location rule:
@@ -524,7 +527,7 @@ Use the wiki tools for SQLite-backed memory work:
 `forge_get_wiki_settings`, `forge_list_wiki_pages`, `forge_get_wiki_page`, `forge_search_wiki`, `forge_upsert_wiki_page`, `forge_get_wiki_health`, `forge_sync_wiki_vault`, `forge_reindex_wiki_embeddings`, `forge_ingest_wiki_source`
 
 Use the health tools for review and reflective enrichment, not as the default CRUD architecture:
-`forge_get_sleep_overview`, `forge_get_sports_overview`, `forge_update_sleep_session`, `forge_update_workout_session`
+`forge_get_sleep_overview`, `forge_get_sports_overview`, `forge_get_training_load_overview`, `forge_update_sleep_session`, `forge_update_workout_session`
 
 Use the dedicated domain routes for specialized surfaces that are not simple batch entities:
 
@@ -679,9 +682,10 @@ Use the health tools when the request is about sleep or sports review:
 
 - `forge_get_sleep_overview` to inspect recent nights, averages, regularity, stage breakdown, and linked reflective context
 - `forge_get_sports_overview` to inspect training volume, workout types, effort trends, habit-generated sessions, and linked context
+- `forge_get_training_load_overview` to inspect cardiovascular load, HR zone balance, acute/chronic stress, high-intensity pressure, VO2max context, and training target fit
 - `forge_update_sleep_session` to add sleep-quality notes, tags, or links back to Forge entities after review
 - `forge_update_workout_session` to add subjective effort, mood, meaning, tags, or links on one workout after review
-- remember that the UI route is `/sports` while the backend overview route is `/api/v1/health/fitness`
+- remember that the UI route is `/sports` while the backend overview route is `/api/v1/health/fitness`; the dedicated training-load UI is `/training-load` and its backend route is `/api/v1/health/training-load`
 
 Use these exact health batch payload shapes when the user is creating or editing the stored records themselves:
 
@@ -776,6 +780,7 @@ When the user asks which Forge tools are available, list exactly these tools:
 `forge_get_current_work`
 `forge_get_sleep_overview`
 `forge_get_sports_overview`
+`forge_get_training_load_overview`
 `forge_update_sleep_session`
 `forge_update_workout_session`
 `forge_get_preferences_workspace`

package/skills/forge-openclaw/entity_conversation_playbooks.md

@@ -158,6 +158,42 @@ to the stronger container:
 - Use a linked `note` when nuance should be preserved without pretending it is the
   whole structured model.
 
+## Reflection-sensitive non-Psyche records
+
+Use this when the user is creating or updating a reflective record that is meaningful
+but not necessarily a full Psyche formulation: `questionnaire_instrument`,
+`questionnaire_run`, `self_observation`, reflective `note`, `wiki_page`,
+`sleep_session`, `workout_session`, and some `preference_judgment` or
+`preference_signal` moments.
+
+- Start by asking what the reflection should help the user understand, decide,
+  notice, remember, or change later.
+- Reflect the lived or practical stake once before asking for fields, but do not
+  over-therapize if the user is only trying to store a clear answer, note, or
+  health-context update.
+- For questionnaire instruments, ask what kind of honest moment, review, or decision
+  the instrument should reveal before asking for item wording, scales, scoring, or
+  provenance.
+- For questionnaire runs, ask whether the user is trying to start, continue, review,
+  or complete the run, then focus on the next answer, uncertainty, or insight that
+  changes the run. Do not turn answer collection into generic Psyche intake unless a
+  belief, mode, trigger report, or behavior pattern clearly emerges.
+- For self-observation, keep the chain concrete: situation, cue, emotion/body,
+  thought/meaning, behavior/urge, and consequence. If that chain reveals a recurring
+  loop, belief, mode, schema theme, or one charged trigger episode, route to the
+  stronger Psyche container.
+- For sleep and workout enrichment, ask what the user wants future review to remember:
+  recovery context, subjective effort, mood, meaning, social context, or links.
+  Preserve raw health facts through the health model and store reflection as notes,
+  tags, links, or batch updates.
+- For notes and wiki pages, distinguish temporary operating context from durable
+  memory. A note can preserve nuance around another record; a wiki page should carry
+  reusable knowledge, source synthesis, person/context memory, or a personal manual.
+- Route posture still matters: `questionnaire_instrument`, `note`, `sleep_session`,
+  and `workout_session` use shared batch routes for normal CRUD; `questionnaire_run`
+  uses questionnaire run actions; `self_observation` is note-backed; `wiki_page` uses
+  the wiki routes.
+
 ## Conversation arc
 
 Most good Forge intake flows follow this sequence:
@@ -257,10 +293,10 @@ Use this quick split before the conversation gets too detailed.
   the user is trying to do, then use the dedicated action tool or note-backed write
   model.
 - `operator_overview`, `operator_context`, `calendar_overview`, `sleep_overview`,
-  and `sports_overview` are read-model-only surfaces. Use them when the user wants
-  to understand current Forge state, work risk, calendar commitments, nights,
-  workouts, training load, recovery context, or health patterns before deciding
-  whether a stored entity needs creation or enrichment.
+  `sports_overview`, and `training_load` are read-model-only surfaces. Use them
+  when the user wants to understand current Forge state, work risk, calendar
+  commitments, nights, workouts, cardiovascular load, recovery context, or health
+  patterns before deciding whether a stored entity needs creation or enrichment.
 - Movement, Life Force, and Workbench are specialized domain areas. Use their
   dedicated route families for timelines and overlays, energy profile/templates and
   fatigue signals, and Workbench flow execution or result artifacts. When available,
@@ -332,9 +368,17 @@ still knowing the exact write/read family before it acts.
   score, stages, or recovery patterns before deciding whether a specific
   `sleep_session` needs reflective enrichment.
 - `sports_overview`: read-model-only health surface. Use the sports overview route or
-  `forge_get_sports_overview` when the user wants to review workouts, training load,
-  effort, type distribution, or recovery context before deciding whether a specific
-  `workout_session` needs reflective enrichment.
+  `forge_get_sports_overview` when the user wants to review workouts, effort, type
+  distribution, or recovery context before deciding whether a specific
+  `workout_session` needs reflective enrichment. Use
+  `forge_get_training_load_overview` or `/api/v1/health/training-load` for
+  cardiovascular load, HR zone balance, acute/chronic stress, VO2max context, or
+  training target questions.
+- `training_load`: read-model-only health surface. Use
+  `forge_get_training_load_overview` or `/api/v1/health/training-load` when the
+  user wants training-load trends, acute/chronic ratio, HR zone distribution,
+  threshold exposure, VO2max/resting-HR context, or optimization targets before
+  deciding whether a specific `workout_session` needs notes or links.
 - `movement`: specialized domain surface. Use the dedicated movement routes for day,
   month, all-time, timeline, places, trip detail, selection aggregates, manual
   overlays, and repair actions.
@@ -1360,14 +1404,15 @@ Preferred opening question:
 
 ## Sports Overview
 
-Aim: review workout and training-load context before deciding whether one workout
-needs a reflective update or recovery follow-up.
+Aim: review workout context before deciding whether one workout needs a
+reflective update, and route deeper cardiovascular load questions to the
+training-load read model.
 
 Arc:
 
 1. Ask what the user wants to understand from the sports picture: one workout, a
-   recent training trend, effort, volume, type mix, recovery, or links to mood and
-   goals.
+   recent training trend, effort, volume, type mix, recovery, zone balance, or
+   links to mood and goals.
 2. Read the sports overview before asking the user to reconstruct metrics from memory.
 3. Reflect the practical decision the review should support.
 4. Move to `workout_session` enrichment only when one specific workout needs context,
@@ -1382,8 +1427,12 @@ Helpful follow-up lanes:
 Route note:
 
 - `sports_overview` is a read-model-only surface. Use `forge_get_sports_overview` or
-  `/api/v1/health/fitness` for review. Do not create, update, or delete
+  `/api/v1/health/fitness` for session review. Do not create, update, or delete
   `sports_overview` through batch CRUD.
+- For cardiovascular load, HR zone distribution, acute/chronic load, VO2max
+  context, or training target questions, use `forge_get_training_load_overview`
+  or `/api/v1/health/training-load`. Treat `training_load` as read-model-only,
+  not a batch CRUD entity.
 - If the review reveals that one workout needs reflective context, switch to the
   stored `workout_session` batch route or reflective update helper for that known
   session.
@@ -1397,6 +1446,50 @@ Preferred opening question:
 
 - "What are you trying to understand from your workout picture right now?"
 
+## Training Load
+
+Aim: review cardiovascular load and training targets before deciding whether one
+workout needs reflective enrichment or a recovery/target adjustment.
+
+Arc:
+
+1. Ask what practical decision the user wants to support: build aerobic base,
+   control overload risk, preserve hard-day quality, understand combat-sport
+   intensity, or compare recent load against chronic base.
+2. Read the training-load overview before asking the user to reconstruct zones,
+   VO2max, or recent hard sessions from memory.
+3. Reflect the load signal with explicit confidence: HR coverage, sensor limits,
+   recent sample count, and whether kickboxing/wrist HR may be noisy.
+4. Move to `workout_session` enrichment only when one specific workout needs
+   notes, tags, context, or links.
+
+Helpful follow-up lanes:
+
+- whether the question is adaptation, overload risk, zone target, VO2max trend,
+  sport contribution, or one recent session
+- which date range matters if the default 7-day and 28-day windows are not enough
+- whether the user is optimizing health, performance, recovery, or a specific
+  upcoming training block
+
+Route note:
+
+- `training_load` is a read-model-only surface. Use
+  `forge_get_training_load_overview` or `/api/v1/health/training-load` for
+  cardiovascular load, HR zone distribution, acute/chronic load, VO2max context,
+  and training target analysis. Do not create, update, or delete `training_load`
+  through batch CRUD.
+- If one workout needs subjective effort, meaning, social context, or links,
+  switch to the stored `workout_session` batch route or reflective update helper.
+
+Ready to review when:
+
+- the user's practical adaptation or recovery question is clear
+- the relevant time window or default 7-day/28-day comparison is acceptable
+
+Preferred opening question:
+
+- "What training-load decision are you trying to support right now?"
+
 ## Calendar Overview
 
 Aim: review commitments, work blocks, provider state, and existing timeboxes before