forge-openclaw-plugin 0.2.99 → 0.2.101

package/skills/forge-openclaw/entity_conversation_playbooks.md

@@ -83,6 +83,9 @@ Forge correctly, and gather only the structure that still matters.
 - Do not read schema fields out loud unless the user explicitly wants a checklist.
 - One focused question is the default. Ask two only when both questions serve the same
   job and the user is steady enough for it.
+- For operational create flows, do not bundle name, scope, and timing into one opener
+  when the user has already supplied part of it. Ask the route-changing missing detail
+  first, then move to the next detail only if it is still unknown.
 - Do not ask the user to do naming work alone when the meaning is already clear. Offer
   a tentative title or formulation and invite correction.
 - When the meaning is clearer than the wording, offer a tentative title or summary
@@ -132,6 +135,32 @@ choice is an internal classification step, not a user-facing menu.
 - Once the lane is selected, use the exact route key internally and do not invent a
   friendlier path.
 
+## Mixed-intent sequencing
+
+Use this when one user message combines several Forge jobs, such as "review this and
+fix it", "save the pattern and make me a card", or "inspect the run and publish the
+output".
+
+- Name the primary job first in plain language, then do the smallest first action that
+  reduces uncertainty. Do not answer a mixed request by asking a broad "what do you
+  want to do?" question when the verbs already show the sequence.
+- If a read changes the truth of a later write, read first. Movement timeline or box
+  detail comes before correction; Workbench run or node detail comes before editing a
+  flow or published output; Life Force overview comes before changing planning
+  assumptions when the current energy picture is uncertain.
+- If a Psyche formulation and a utility record are both requested, formulate the
+  Psyche record first, then create the support record from that accepted wording. A
+  behavior pattern can lead to a flashcard, note, value link, task, or habit, but the
+  agent should not ask for every adjacent record at once.
+- If the user asks to save and act, finish the write shape before asking for follow-up
+  action details unless the action changes which record should be saved.
+- If two routes are needed, keep them in order internally and tell the user the
+  product sequence briefly: "I will check the timeline first, then correct the missing
+  block if the span matches." Avoid route-key language unless the user asks.
+- After the first action, ask only the next decision-relevant question. Do not restart
+  intake for the second action when the first answer already supplied the wording,
+  span, flow, run, node, weekday, or link.
+
 ## Psyche and memory routing
 
 Self-observation is not the default container for psychological material. Use it only
@@ -379,6 +408,14 @@ still knowing the exact write/read family before it acts.
   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.
+- `weight_loss`: nutrition and body-composition health surface. Use
+  `forge_get_weight_loss_overview` or `/api/v1/health/weight-loss` when the user
+  wants calorie balance, food quality, protein/fiber targets, training fuel,
+  body trend, aesthetic look, subjective energy, cravings, gut comfort,
+  hypotheses, or nutrition experiments. Use `forge_parse_food_log_with_chatgpt`
+  for rough meal text/photo descriptions through the configured `openai-codex`
+  ChatGPT subscription connection, then use `forge_log_food` and the body,
+  appearance, subjective, gut, and experiment tools for durable evidence.
 - `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.
@@ -689,6 +726,57 @@ Connect:
 - If the user is emotionally loaded but the record is still non-Psyche, reflect the
   lived stake once and then return to the one operational question that still matters.
 
+## Search-before-write and existing-record disambiguation
+
+Use this before a create or update when a near-duplicate, existing target, or owner
+scope could change the write.
+
+- For normal stored entities, search the shared batch route by entity type, useful
+  title or wording, linked owner, and distinctive content before creating when
+  duplicate risk is plausible. Do not ask the user to re-supply fields that a quick
+  search can answer.
+- If a likely existing record appears, ask the narrow product question: should this
+  update that record, link to it, or become a separate new record? Do not reopen the
+  whole create flow.
+- For update requests, look up the current record before asking for replacement
+  wording when the user has not provided the current id, title, or owner scope.
+- For Psyche, a similar existing belief, pattern, mode, trigger report, value, or
+  flashcard is not a blocker. Treat it as a choice between updating, linking, or
+  saving a distinct version of the experience.
+- For `wiki_page` and `calendar_connection`, use the dedicated search/list/read routes
+  before creating another page or connection. Do not use batch entity search as the
+  source of truth for these specialized CRUD surfaces.
+- For Movement, Life Force, and Workbench, do not use batch duplicate search. Use the
+  dedicated read lane: known places or timeline for Movement, overview/profile or
+  weekday template for Life Force, and saved flows, run history, node result, latest
+  output, or published output for Workbench.
+- If the user already chose "new record" after seeing a near match, keep going with
+  create. Do not challenge the choice repeatedly.
+
+## Destructive and replacement actions
+
+Use this when the next action would delete, archive, invalidate, overwrite, replace,
+disconnect, or substantially narrow a record.
+
+- Confirm the exact target and the preservation need before destructive work. Ask one
+  narrow question such as what should be deleted versus kept, whether history should
+  remain visible, or what future behavior should change.
+- For normal stored entities, prefer the normal soft-delete path unless the user
+  explicitly asks for hard deletion or permanent removal. Do not make the user choose
+  a delete mode unless it changes the actual action.
+- For Psyche records, do not delete an old belief, pattern, mode, trigger report,
+  value, or flashcard just because a newer formulation exists. Ask whether the old
+  record should be updated, linked as history, archived, or kept distinct.
+- For Movement repair, distinguish deleting a user-defined overlay from invalidating
+  an automatic box or deleting an already-recorded stay, trip, or point. Read the
+  specific span first when the target is uncertain.
+- For calendar connections, Workbench flows, wiki pages, and questionnaire
+  instruments, ask what downstream sync, published output, backlinks, run history,
+  or completed runs should remain understandable before deleting or replacing the
+  saved object.
+- If the user has already explicitly confirmed the target and preservation choice,
+  act. Do not add a ceremonial second confirmation.
+
 ## Ready-to-save check
 
 Before saving, make sure you can answer all of these in plain language:
@@ -1053,7 +1141,7 @@ Ready to save when:
 
 Preferred opening question:
 
-- "What is the event, and when should it happen in your local time?"
+- "What time should Forge hold for this event in your local timezone?"
 
 ## Work Block Template
 
@@ -1081,7 +1169,7 @@ Ready to save when:
 
 Preferred opening question:
 
-- "What recurring block do you want to set up, and when should it repeat?"
+- "When should this recurring block repeat?"
 
 ## Task Timebox
 
@@ -1109,7 +1197,7 @@ Ready to save when:
 
 Preferred opening question:
 
-- "Which task are you trying to make time for, and when should the slot be?"
+- "When should Forge reserve focused time for this task?"
 
 ## Task Run
 
@@ -1491,6 +1579,47 @@ Preferred opening question:
 
 - "What training-load decision are you trying to support right now?"
 
+## Weight Loss
+
+Aim: review and capture nutrition, body-composition, sport-fueling, aesthetic,
+subjective-energy, craving, and gut-comfort evidence before turning observations
+into a testable food or training hypothesis.
+
+Arc:
+
+1. Ask what link the user is trying to understand: fat loss pace, food intake,
+   training fuel, look/puffiness, energy, cravings, gut comfort, or a specific
+   meal reaction.
+2. Read `forge_get_weight_loss_overview` before asking the user to reconstruct
+   recent food, weight, workouts, or subjective state from memory.
+3. Use `forge_parse_food_log_with_chatgpt` for rough meal text or photo
+   descriptions. This must go through Forge's configured `openai-codex` ChatGPT
+   subscription connection, not a metered OpenAI API path.
+4. Use `forge_log_food`, `forge_log_body_checkin`,
+   `forge_log_appearance_checkin`, `forge_log_subjective_food_effect`, and
+   `forge_log_gut_checkin` to preserve the user's actual evidence.
+5. Use `forge_get_nutrition_patterns`, `forge_start_nutrition_experiment`, and
+   `forge_update_nutrition_experiment` when repeated observations should become
+   an N-of-1 test instead of vague advice.
+
+Helpful follow-up lanes:
+
+- whether the decision is weight trend, protein/fiber sufficiency, sport fuel,
+  visual look, water retention, gut comfort, cravings, or energy
+- whether a meal should be confirmed precisely or logged as a candidate estimate
+- which outcome metric should define a nutrition experiment before interpreting it
+
+Route note:
+
+- `weight_loss` is a health read model plus dedicated nutrition write workflow.
+  Use `/api/v1/health/weight-loss` or `forge_get_weight_loss_overview` for the
+  overview. Do not invent generic batch entities for food logs or body check-ins
+  when the dedicated tools exist.
+
+Preferred opening question:
+
+- "What food-body link are you trying to test or understand right now?"
+
 ## Calendar Overview
 
 Aim: review commitments, work blocks, provider state, and existing timeboxes before
@@ -1578,7 +1707,7 @@ Ready to act when:
 
 Preferred opening question:
 
-- "Which calendar provider are you trying to connect, and what do you want Forge to do with it?"
+- "What workflow do you want this calendar connection to unlock?"
 
 ## Preference Judgment
 
@@ -2183,7 +2312,7 @@ Ready to act when:
 
 Preferred opening question:
 
-- "What do you want from this questionnaire run right now: start, continue, review, or finish it?"
+- "Are you trying to start, continue, review, or finish this run right now?"
 
 ## Event Type
 

package/skills/forge-openclaw/psyche_entity_playbooks.md

@@ -197,6 +197,25 @@ material without a usable formulation.
 - Do not make the user supply every interpretation alone. If the sequence is clear
   enough, do the formulation work in plain language and invite correction.
 
+## Hypothesis Wording Shape
+
+Use this when reflection alone would leave the user with warmth but no clearer
+formulation.
+
+1. Start with the evidence in the user's own example:
+   "When X happened, Y seemed to happen inside you."
+2. Offer one testable interpretation:
+   "One hypothesis is that this response is trying to protect you from Z."
+3. Name the function without blame:
+   what it predicts, what it prevents, what relief it creates, or what it costs.
+4. Ask for correction:
+   "Does that fit, or is the danger/need somewhere else?"
+
+Do not say "this is your schema" or "this is your mode" as a verdict. Say what in the
+example makes the hypothesis plausible, then let the user correct the danger,
+protection, payoff, cost, or wording. If the correction is usable, revise once and move
+toward the record shape instead of asking for another broad story.
+
 ## Hypothesis To Record Bridge
 
 Once a hypothesis lands or is corrected, turn it into a saveable Forge shape instead
@@ -452,6 +471,22 @@ Use `forge_search_entities` before creating when a duplicate is plausible. Use
 and useful links are clear enough. Preserve nuance in a linked `note` when the
 experience is richer than the normalized fields.
 
+When search finds a similar Psyche record, do not treat similarity as a cold duplicate
+failure. Briefly name the difference that may matter and ask one narrow question:
+should this update the existing record, link to it, or stand as a distinct new version
+of the experience? For beliefs, compare the sentence; for patterns, compare the cue,
+payoff, and cost; for modes, compare the protective job; for trigger reports, compare
+the episode; for flashcards, compare the urge sentence and message. If the user wants
+a new record after seeing the near match, respect that and save the distinct version.
+
+For destructive or replacement requests, preserve therapeutic history unless the user
+clearly wants removal. If a new belief, pattern, mode, trigger interpretation, value
+wording, or flashcard message supersedes an old one, ask whether the old record should
+be updated, linked as history, archived, or kept as a distinct version. Do not delete a
+Psyche record merely because a cleaner formulation now exists. If the user already
+confirmed deletion and the exact target is clear, honor the request without reopening
+the whole exploration.
+
 Do not divert Psyche material into `self_observation` just because it started as an
 episode. Use `trigger_report` for one emotionally meaningful incident, use
 `behavior_pattern` for a recurring functional loop, use `belief_entry` for one
@@ -459,6 +494,16 @@ explicit sentence, and use `mode_guide_session` or `mode_profile` when a part-st
 central. Use `flashcard` when the user needs a small rehearsable message to retrieve
 during an urge, trigger, mode activation, belief activation, or values-based pivot.
 
+When the user asks for understanding plus an immediate support action, keep the order
+therapeutic and practical. Clarify or formulate the primary Psyche record first, then
+derive the support action from the accepted wording: a `behavior_pattern` can produce a
+`flashcard`, a `belief_entry` can produce a counter-message or note, a `trigger_report`
+can link to an `event_type` or `emotion_definition`, and a `mode_guide_session` can
+later become a durable `mode_profile`. Do not ask for every adjacent entity at once.
+If the user already supplied a clear action, say the sequence briefly in product
+language and ask only for the missing wording, cue, or link that changes the first
+save.
+
 When a user says they feel an urge or asks for help not doing something, search
 existing `flashcard` records before creating a new one. Use `forge_search_entities`
 with `entityTypes: ["flashcard"]` and query text from the urge, tags, trigger