forge-openclaw-plugin 0.2.4 → 0.2.10

package/skills/forge-openclaw/SKILL.md

@@ -1,328 +1,254 @@
 ---
 name: forge-openclaw
-description: Use the Forge OpenClaw plugin to collaborate with Forge through explicit plugin-owned routes and tools backed by the live /api/v1 contract.
+description: use when the user wants to save, search, update, review, start, stop, or explain work or psyche records inside forge, or when the conversation is clearly about a forge entity such as a goal, project, task, task_run, insight, psyche_value, behavior_pattern, behavior, belief_entry, mode_profile, mode_guide_session, trigger_report, event_type, or emotion_definition. identify the exact forge entity, keep the main conversation natural, offer saving once when helpful, ask only for missing fields, and use the correct forge tool and payload shape.
 ---
 
-# Forge OpenClaw
+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.
 
-Use this skill when Forge is available as a native OpenClaw plugin and you need truthful, structured access to the live Forge system.
+Forge has two major domains. The planning side covers goals, projects, tasks, notes, live work sessions, and agent-authored insights. The Psyche side covers values, patterns, behaviors, beliefs, modes, guided mode sessions, trigger reports, event types, and reusable emotion definitions. 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 is a life operating system with:
-- goals
-- projects
-- tasks
-- live work timers
-- comments, insights, and approvals
-- a sensitive Psyche module for values, patterns, beliefs, behaviors, modes, and trigger reports
+Write to Forge only with clear user consent. If the user is just thinking aloud, helping first is usually better than writing immediately. After helping, you may offer one short Forge prompt if the match is strong. If the user agrees, ask only for the missing fields and only one to three focused questions at a time. Do not offer Forge again after a decline unless the user reopens it.
 
-## Public working posture
+Forge data location rule:
 
-Keep the main discussion natural.
-Do not turn every conversation into a form.
+- by default, Forge stores data under the active runtime root at `data/forge.sqlite`
+- on a normal OpenClaw install, this usually means `~/.openclaw/extensions/forge-openclaw-plugin/data/forge.sqlite`
+- on a linked repo-local install, this usually means `<repo>/openclaw-plugin/data/forge.sqlite`
+- if the user wants the data somewhere else for persistence, backup, or manual control, tell them to set `plugins.entries["forge-openclaw-plugin"].config.dataRoot` and restart the OpenClaw gateway
+- if the user asks where the data is stored or how to move it, explain the current default plainly and show the exact config field
 
-Default flow:
-1. Continue the normal discussion first.
-2. If something clearly looks like a Forge entity, add one short optional suggestion near the end.
-3. Only start collection questions if the user accepts.
-4. Ask only for the missing fields.
-5. Ask at most 1 to 3 questions at a time.
+Use these exact entity meanings when deciding what the user is describing.
 
-Good suggestion style:
-- "This sounds like a concrete project. If you want, we can break it down and store it in Forge."
-- "This sounds like an important trigger event. If you want, we can map it together and save it in Forge."
+`goal` is a meaningful long-horizon direction or outcome. Use it for “be a great father”, “create meaningfully”, or “build a beautiful family”, not for one-off action items.
 
-Bad suggestion style:
-- interrupting the main reply too early
-- sounding pushy or repetitive
-- asking for every field before the user has agreed to save it
+`project` is a bounded workstream under a goal. Use it for “launch Forge plugin”, “plan summer move”, or “repair relationship with X”.
 
-## Advertised plugin interface
+`task` is a concrete action item or deliverable. Use it for “draft the plugin README”, “call the landlord”, or “book therapy session”.
 
-Treat this as the public mental model:
+`task_run` is one truthful live work session on a task. It is not the same thing as task status.
 
-Read first:
-- `forge_get_operator_overview`
+`note` is a Markdown evidence record that can link to one or many entities. Use it for work summaries, context, progress logs, handoff explanations, or reflective detail that should stay searchable and attached to the right records.
 
-High-level entity workflow:
-- `forge_search_entities`
-- `forge_create_entities`
-- `forge_update_entities`
-- `forge_delete_entities`
-- `forge_restore_entities`
+`insight` is an agent-authored observation, recommendation, or warning grounded in Forge data. It does not replace a requested goal, project, task, pattern, belief, or trigger report.
 
-Agent-authored recommendations:
-- `forge_post_insight`
+`psyche_value` is a direction the user wants to live toward, such as honesty, courage, steadiness, compassion, or creativity.
 
-Narrow CRUD tools still exist for exact operations, timers, settings, approvals, comments, rewards, and specialized Psyche flows, but they are fallback tools and should not be the main advertised workflow.
+`behavior_pattern` is a recurring loop across situations. Think in terms of cue, emotion, thought, action, short-term payoff, long-term cost, and preferred replacement response.
 
-## Source of truth
+`behavior` is one recurring action tendency or move, such as withdrawing, appeasing, attacking, numbing out, or taking a regulating walk.
 
-Forge remains the source of truth.
+`belief_entry` is one explicit belief sentence the user carries, such as “If I disappoint people, they will leave me.”
+
+`mode_profile` is one recurring state, voice, or inner role, such as inner critic, abandoned child, detached protector, overcontroller, or healthy adult.
+
+`mode_guide_session` is a guided exploration record used to understand what mode may be active right now. It is a structured worksheet, not the final durable profile unless the user wants it that way.
+
+`trigger_report` is one specific emotionally meaningful episode described as what happened, what was felt, what was thought, what was done, what happened next, and what would help next time.
+
+`event_type` is a reusable category for trigger reports, such as rejection, criticism, conflict, uncertainty, or abandonment cue.
+
+`emotion_definition` is a reusable emotion entry, such as fear, shame, anger, grief, relief, or disgust.
+
+Use this intake map when the user agrees to save or update something.
+
+`goal`
+Use for a meaningful direction over time.
+Minimum field: `title`
+Usually useful: `description`, `horizon`, `status`
+Ask:
+1. What should this goal be called?
+2. Why does it matter to you?
+3. Is this a quarter, year, or lifetime horizon?
+
+`project`
+Use for a bounded workstream under a goal.
+Minimum field: `title`
+Usually useful: `goalId`, `description`, `status`
+Ask:
+1. What should this project be called?
+2. Which goal does it support?
+3. What outcome should it produce?
+
+`task`
+Use for one concrete action or deliverable.
+Minimum field: `title`
+Usually useful: `projectId`, `goalId`, `priority`, `dueDate`, `status`, `owner`
+Ask:
+1. What is the task in one concrete sentence?
+2. Should it live under an existing goal or project?
+3. Does it need a due date, priority, or owner?
 
-Use:
-- plugin routes under `/forge/v1/...`
-- the batch entity tools for most entity work
-- `forge_post_insight` for structured recommendations
+`task_run`
+Use for live work happening now.
+Required fields to start: `taskId`, `actor`
+Ask only what is needed to start the run, such as the task, the actor, and whether the run is planned or unlimited.
 
-Do not:
-- mutate storage directly
-- scrape the UI instead of using the API
-- invent entities outside the real Forge model
+`psyche_value`
+Use for a value or committed direction.
+Minimum field: `title`
+Usually useful: `description`, `valuedDirection`, `whyItMatters`, links to goals, projects, or tasks
+Ask:
+1. What value or direction is this?
+2. How would you describe it in your own words?
+3. Why does it matter now?
 
-## Overview-first and batch-first rules
+`behavior_pattern`
+Use for a recurring loop across situations.
+Minimum field: `title`
+Usually useful: `description`, `targetBehavior`, `cueContexts`, `shortTermPayoff`, `longTermCost`, `preferredResponse`
+Ask:
+1. What would you call this pattern?
+2. What usually sets it off, and what tends to happen next?
+3. What does it give you in the short term, what does it cost later, and what response would you rather make?
 
-1. Start with `forge_get_operator_overview` unless the user is clearly asking for one exact known record.
-2. Before creating or updating ambiguous entities, use `forge_search_entities` to check for duplicates.
-3. Prefer batch tools even for small multi-step work when they keep the operation coherent.
-4. Use narrow tools only when the job is genuinely specialized:
-   - live timers and work logging
-   - settings
-   - approvals
-   - comments
-   - rewards
-   - exact single-record fallback flows
+`behavior`
+Use for one recurring move or action tendency.
+Minimum fields: `kind`, `title`
+Usually useful: `commonCues`, `urgeStory`, `shortTermPayoff`, `longTermCost`, `replacementMove`, `repairPlan`
+Ask:
+1. What happened, in plain language?
+2. Is it an `away`, `committed`, or `recovery` behavior?
+3. What cues show up, and what move would you want available instead?
 
-## When to offer saving to Forge
+`belief_entry`
+Use for one explicit belief sentence.
+Minimum fields: `statement`, `beliefType`
+Usually useful: `confidence`, `evidenceFor`, `evidenceAgainst`, `flexibleAlternative`, `originNote`
+Ask:
+1. What is the belief in one sentence?
+2. Is it `absolute` or `conditional`, and how true does it feel from 0 to 100?
+3. What supports it, what weakens it, and what would be a more flexible alternative?
 
-Offer once, gently, near the end of the reply, when the signal is strong.
+`mode_profile`
+Use for a recurring part-state or inner role.
+Minimum fields: `family`, `title`
+Usually useful: `fear`, `burden`, `protectiveJob`, `originContext`, links to patterns, behaviors, and values
+Ask:
+1. What kind of mode is this: `coping`, `child`, `critic_parent`, `healthy_adult`, or `happy_child`?
+2. What should this mode be called?
+3. What does it fear, carry, or try to protect?
 
-Offer for likely:
-- `goal`
-- `project`
-- `task`
-- `psyche_value`
-- `behavior_pattern`
-- `behavior`
-- `belief_entry`
-- `trigger_report`
-- retroactive work that should be logged
-- a recommendation that should become an `insight`
+`mode_guide_session`
+Use for guided exploration before or alongside a durable mode profile.
+Minimum fields: `summary`, `answers`, `results`
+Ask only what is needed to capture the guided exploration and the candidate interpretations.
 
-Do not offer when:
-- it was just a passing mention
-- the user needs support or clarity first
-- the record is still too vague to name honestly
-- the user already declined
-
-## What insights are for
-
-An `insight` is an agent-authored observation or recommendation grounded in the user's real Forge data.
-
-Use insights when the agent can see a meaningful pattern across:
-- goals, projects, and tasks
-- momentum, drift, or stalled progress
-- recurring trigger reports, beliefs, behaviors, or patterns
-- tradeoffs between what the user says matters and what their recent activity shows
+`trigger_report`
+Use for one specific emotionally important episode.
+Minimum field: `title`
+Usually useful: `eventSituation`, `occurredAt`, `emotions`, `thoughts`, `behaviors`, `consequences`, `nextMoves`, links to values, beliefs, patterns, modes, goals, projects, or tasks
+Ask:
+1. What happened?
+2. What emotions were present, and how intense were they?
+3. What thoughts showed up, what did you do next, and what would be the useful next move now?
 
-A good insight should do three things:
-- name the pattern or tension clearly
-- explain why it matters now
-- suggest one practical next move, experiment, or reframing
+`event_type`
+Use for a reusable trigger category.
+Minimum field: `label`
+Usually useful: `description`
+Ask:
+1. What should this event type be called?
+2. What kind of incident does it represent?
 
-Good examples:
-- "You are consistently moving the same goal forward, but the related admin work is what keeps stalling. It may help to split the admin work into one smaller recurring task and protect the creative block separately."
-- "Your trigger reports keep clustering around late-day overload. It may be worth defining one lighter recovery action that you can do before the full crash spiral starts."
+`emotion_definition`
+Use for a reusable emotion vocabulary entry.
+Minimum field: `label`
+Usually useful: `description`, `category`
+Ask:
+1. What emotion label do you want to reuse?
+2. How would you describe it?
+3. Does it belong to a broader category?
+
+Use these rules when choosing tools.
 
-Use `forge_post_insight` when you want to store that recommendation with agent provenance.
-Do not use an insight as a substitute for the main conversation. The main reply should still help the user directly.
-If storing the insight would be useful, mention it lightly near the end of the response, for example:
-- "There may be a useful insight here about how this pattern keeps showing up. If you want, I can turn it into a structured Forge insight so it stays visible."
+Read first with `forge_get_operator_overview`, `forge_get_operator_context`, or `forge_get_current_work` unless the user is clearly asking for one exact known record or one exact write.
 
-## Entity format cards
+Before creating or updating an ambiguous stored entity, use `forge_search_entities` to check for duplicates.
 
-These are the main advertised formats. Use them to decide what to ask next.
+Use the batch entity tools for stored records:
+`forge_search_entities`, `forge_create_entities`, `forge_update_entities`, `forge_delete_entities`, `forge_restore_entities`
 
-### `goal`
+These tools operate on:
+`goal`, `project`, `task`, `note`, `psyche_value`, `behavior_pattern`, `behavior`, `belief_entry`, `mode_profile`, `mode_guide_session`, `trigger_report`, `event_type`, `emotion_definition`
 
-Purpose:
-- a long-horizon life direction or outcome
+Use live work tools for `task_run`:
+`forge_log_work`, `forge_start_task_run`, `forge_heartbeat_task_run`, `forge_focus_task_run`, `forge_complete_task_run`, `forge_release_task_run`
 
-Minimum fields:
-- `title`: the name of the goal
+Use `forge_post_insight` for `insight`.
 
-Useful optional fields:
-- `description`: why it matters or what success looks like
-- `horizon`: `quarter`, `year`, or `lifetime`
-- `tagIds`: values, categories, or execution tags when already known
+Do not say you lack a creation path when these tools cover the request. Do not open the Forge UI or a browser for normal creation or updates that the tools already support. Use `forge_get_ui_entrypoint` only when visual review, Kanban movement, graph exploration, or complex multi-record editing would genuinely be easier there.
 
-What to ask:
-- "What would you like to call this goal?"
-- "Why does it matter to you?"
-- "Is this a quarter, year, or lifetime horizon?"
+Use these exact payload expectations.
 
-### `project`
+`forge_search_entities` expects a top-level `searches` array.
 
-Purpose:
-- a concrete workstream under a goal
+`forge_create_entities`, `forge_update_entities`, `forge_delete_entities`, and `forge_restore_entities` expect a top-level `operations` array.
 
-Minimum fields:
-- `title`: the project name
-- `goalId`: the parent goal if known
+For create operations, each item must include `entityType` and `data`.
 
-Useful optional fields:
-- `description`: desired outcome or scope
-- `status`: `active`, `paused`, or `completed`
-- `themeColor`: optional visual/editorial color
+When creating `goal`, `project`, or `task`, the create payload may also include `notes: [{ contentMarkdown, author?, links? }]`. Forge will create real linked `note` entities automatically and attach them to the new parent record.
 
-What to ask:
-- "What should this project be called?"
-- "Which goal does it support?"
-- "What outcome do you want this project to produce?"
+For update operations, each item must include `entityType`, `id`, and `patch`.
 
-### `task`
+For delete operations, each item must include `entityType` and `id`. Delete is soft by default unless the user explicitly wants hard delete.
 
-Purpose:
-- a concrete actionable work item
+For restore operations, each item must include `entityType` and `id`.
 
-Minimum fields:
-- `title`: the action itself
+Batch tools do not create or control `task_run` or `insight`.
 
-Useful optional fields:
-- `goalId`: linked goal if known
-- `projectId`: linked project if known
-- `dueDate`: when it matters
-- `priority`: `low`, `medium`, `high`, or `critical`
-- `status`: `backlog`, `focus`, `in_progress`, `blocked`, or `done`
-- `description`: useful detail, not a paragraph by default
+Use the exact route-facing field names. Do not invent friendlier aliases. If a field name is unclear, use `forge_get_agent_onboarding` as the schema source of truth.
 
-What to ask:
-- "What is the task in one concrete sentence?"
-- "Should this live under an existing goal or project?"
-- "Does it need a due date or priority?"
+Use these live work rules.
 
-### `psyche_value`
+A `task_run` is the truthful way to represent live work. Do not pretend that changing task status is the same as starting or stopping a work session.
 
-Purpose:
-- an ACT-style value or committed direction
+Use `forge_start_task_run` to begin live work. Required fields: `taskId`, `actor`. If `timerMode` is `planned`, include `plannedDurationSeconds`. If `timerMode` is `unlimited`, omit `plannedDurationSeconds` or set it to null.
 
-Minimum fields:
-- `title`: the value name
+Use `forge_heartbeat_task_run` to keep an active run alive.
 
-Useful optional fields:
-- `description`: what the value means in practice
-- `linkedGoalIds`
-- `linkedProjectIds`
-- `linkedTaskIds`
-
-What to ask:
-- "What value or direction does this point toward?"
-- "How would you describe that value in your own words?"
-- "Do you want it linked to an existing goal, project, or task?"
+Use `forge_focus_task_run` when one active run should become the current visible run.
 
-### `behavior_pattern`
+Use `forge_complete_task_run` to finish live work. When the user or agent wants to preserve what was done, include `closeoutNote` so Forge creates a real linked `note` instead of losing that explanation inside ephemeral run metadata.
 
-Purpose:
-- a recurring loop, trigger chain, or repeated behavior pattern
+Use `forge_release_task_run` to stop live work without completing the task. `closeoutNote` is also available there for handoff or pause context.
 
-Minimum fields:
-- `title`: short name for the pattern
+Use `forge_log_work` only for retroactive work that already happened. If the user explains the work in a way that should be preserved, include `closeoutNote`.
 
-Useful optional fields:
-- `description`: what usually happens
-- `triggerCue`: what tends to start it
-- `linkedValueIds`
-- `linkedReportIds`
+Use these interaction rules.
 
-What to ask:
-- "What would you call this pattern?"
-- "What usually triggers it?"
-- "What tends to happen once the pattern starts?"
+Keep the main discussion natural. Do not turn every conversation into a form. Do not offer Forge for every passing mention. Offer it once, near the end, only when the signal is strong and storing would help.
 
-### `behavior`
-
-Purpose:
-- one concrete behavior instance or repeated behavior you want tracked
-
-Minimum fields:
-- `title`: what happened
-
-Useful optional fields:
-- `kind`: `away`, `committed`, or `recovery`
-- `description`: short context
-- `linkedPatternIds`
-- `linkedValueIds`
-- `linkedReportIds`
-
-What to ask:
-- "What happened, in plain language?"
-- "Would you classify it as away, committed, or recovery?"
-- "Do you want it linked to a pattern, value, or report?"
-
-### `belief_entry`
-
-Purpose:
-- a belief worth tracking, examining, or linking to schema work
-
-Minimum fields:
-- `title`: short label or belief title
-
-Useful optional fields:
-- `belief`: the actual belief statement
-- `schemaFamily`: maladaptive or adaptive framing when known
-- `linkedReportIds`
-
-What to ask:
-- "What is the belief in one sentence?"
-- "Does it feel like an old pressure theme or a healthier stabilizing one?"
-- "Is this tied to a specific trigger report?"
-
-### `trigger_report`
-
-Purpose:
-- a reflective incident report that ties together trigger, emotions, thoughts, behaviors, beliefs, and next moves
-
-Minimum fields:
-- `title`: short name for the incident
-
-Useful optional fields:
-- `eventSummary`: what happened
-- `eventTypeId`
-- `emotionIds`
-- `thoughtSummary`
-- `behaviorSummary`
-- `nextMove`
-- `linkedGoalIds`
-- `linkedProjectIds`
-- `linkedTaskIds`
-- `linkedPatternIds`
-- `linkedValueIds`
-
-What to ask:
-- "What happened?"
-- "What emotions were present?"
-- "What thoughts or beliefs showed up?"
-- "What did you do next?"
-- "What would be a useful next move now?"
-
-## Mapping guidance
-
-Prefer:
-- `goal` for a meaningful long-horizon direction
-- `project` for a multi-step outcome under a goal
-- `task` for a concrete next action
-- `psyche_value` for a value or committed direction
-- `behavior_pattern` for a repeating loop
-- `behavior` for one behavior or behavior tendency
-- `belief_entry` for a trackable belief
-- `trigger_report` for a specific reflective event chain
-- `insight` when the agent is storing a data-grounded observation or recommendation rather than the user’s own work item or reflection record
-
-## Auth and provenance
-
-Plugin-originated requests carry:
-- `Authorization: Bearer <token>` when configured
-- `X-Forge-Source: openclaw`
-- `X-Forge-Actor: <actorLabel>`
-
-Localhost and Tailscale installs can bootstrap an operator session automatically.
-Remote non-local installs should use a token.
-
-## Working rules
-
-1. Prefer `forge_get_operator_overview` first.
-2. Prefer `forge_search_entities` before create/update when duplicate risk exists.
-3. Prefer batch tools for multi-entity work.
-4. Use `forge_log_work` if the work already happened.
-5. Use `forge_post_insight` for structured recommendations.
-6. Respect sensitive Psyche scopes. Psyche is not casual metadata.
-7. Default delete is soft delete. Hard delete requires explicit user intent.
+Good examples:
+“This is a `project` in Forge. Do you want to save it?”
+“This sounds like a `behavior_pattern`. Do you want to map it and save it?”
+“This is a `trigger_report`. Do you want to capture it in Forge?”
+
+Bad behavior:
+interrupting too early
+asking for every optional field
+using vague labels instead of the real entity name
+repeating the Forge prompt after the user has declined
+
+Treat Psyche as structured reflective work, not as casual metadata. When the user is distressed, prioritize support and clarity over structure. Only suggest storage when the user seems ready.
+
+When the user asks which Forge tools are available, list exactly these tools:
+`forge_get_operator_overview`
+`forge_get_operator_context`
+`forge_get_agent_onboarding`
+`forge_get_psyche_overview`
+`forge_get_xp_metrics`
+`forge_get_weekly_review`
+`forge_get_current_work`
+`forge_get_ui_entrypoint`
+`forge_search_entities`
+`forge_create_entities`
+`forge_update_entities`
+`forge_delete_entities`
+`forge_restore_entities`
+`forge_log_work`
+`forge_start_task_run`
+`forge_heartbeat_task_run`
+`forge_focus_task_run`
+`forge_complete_task_run`
+`forge_release_task_run`
+`forge_post_insight`