@akalsey/openclaw-goals 0.1.0

package/README.md

@@ -0,0 +1,146 @@
+# OpenClaw Goals
+
+Some things worth doing aren't tasks. They're directions — fuzzy, long-running, and valuable even when the path isn't clear. "Our teams aren't scoring OKRs regularly" is a goal, not a ticket.
+
+This plugin accepts those kinds of objectives, decomposes them into candidate approaches, tracks incremental progress, and delivers a weekly status update. You stay oriented without managing the detail.
+
+This plugin is part of the Sapience Suite that gives your OpenClaw agent genuine agency — not just the ability to execute tasks, but the judgment to know when to act, when to ask, when to propose, and when to say "I'm not sure how you want me to handle this."
+
+This plugin can be used without Sapience if all you want to do is track multi-step tasks.
+
+---
+
+## Setup
+
+### Install
+
+```bash
+openclaw plugins install local:/path/to/openclaw-goals
+```
+
+### Configuration
+
+```json
+{
+  "plugins": {
+    "goals": {
+      "weeklyCheckInDay": "monday",
+      "weeklyCheckInTime": "09:00",
+      "activeHours": {
+        "start": "08:00",
+        "end": "20:00",
+        "timezone": "America/Los_Angeles"
+      },
+      "inboxPath": "~/.openclaw/sapience/goals-inbox.md"
+    }
+  }
+}
+```
+
+All settings are optional — defaults above are used if omitted.
+
+### Create the inbox file
+
+```bash
+touch ~/.openclaw/sapience/goals-inbox.md
+```
+
+The plugin won't error if the file is missing, but you need it to submit goals.
+
+### Output files
+
+| File | Purpose |
+|------|---------|
+| `~/.openclaw/sapience/goals.json` | All goals with status, approaches, progress, blockers |
+| `~/.openclaw/sapience/goals-inbox.md` | Where you write new goals |
+| `~/.openclaw/sapience/goals-inbox-position.json` | Byte offset tracking — don't edit this |
+
+---
+
+## Submitting a goal
+
+Just tell the agent in conversation:
+
+> "I want to improve our OKR scoring rate"
+> "Figure out why PostHog costs keep spiking"
+> "Help me build a habit of writing weekly team updates"
+
+The agent recognizes long-running objectives and calls `goal_submit` automatically. A `[GOALS: DECOMPOSE]` prompt arrives within seconds with concrete approaches to choose from.
+
+### Via the inbox file (scripting/external use)
+
+You can also append goals directly to the inbox file for use from scripts or other tools:
+
+```bash
+echo "Our teams aren't scoring OKRs regularly — improve that" >> ~/.openclaw/sapience/goals-inbox.md
+```
+
+The next cron pass (within 15 minutes) picks it up.
+
+---
+
+## Decomposition
+
+When a new goal is detected, the agent delivers a `[GOALS: DECOMPOSE]` prompt to your active session:
+
+> "I noticed this goal: 'Our teams aren't scoring OKRs regularly.' Here are 3 approaches I could take…"
+
+It presents 2–4 concrete approaches, explains what each would accomplish and what it would need from you, and asks you to pick one (or none).
+
+Your selection is recorded as the `active_approach`. Goals without a selected approach stay in `decomposing` status and don't receive weekly updates until you pick one.
+
+---
+
+## Tracking progress
+
+Progress is tracked through the weekly status loop — the agent notes what it did toward the goal and what it plans next. You can also add progress notes manually:
+
+```bash
+# Not yet a built-in command — edit goals.json directly for now
+```
+
+To mark a goal complete or pause it, update the `status` field in `~/.openclaw/sapience/goals.json`:
+
+```json
+{ "status": "completed" }
+```
+
+Valid statuses: `decomposing` | `active` | `paused` | `completed` | `abandoned`
+
+---
+
+## Weekly status
+
+Every Monday at 9am (or your configured day/time), active goals get a `[GOALS: WEEKLY STATUS]` prompt delivered to your session:
+
+> "Weekly status for 'Improve OKR scoring rates':
+> - What happened this week: …
+> - What's blocked: …
+> - What I plan next week: …"
+
+Each goal gets its own delivery. If nothing happened and nothing is blocked, the agent says so briefly and doesn't pad.
+
+The next delivery date is stored per-goal in `goals.json` and rolls forward automatically after each delivery.
+
+---
+
+## Troubleshooting
+
+**Goal submitted but no decomposition prompt**
+The cron fires every 15 minutes. Wait for the next pass, or trigger manually:
+```bash
+openclaw cron run goals-check-pass
+```
+Also confirm the inbox path matches your config and that the file is readable.
+
+**Same goals showing up again after re-install**
+The byte-position tracker (`goals-inbox-position.json`) tracks what's been read. If it's missing, the inbox is read from the beginning. Delete old content from the inbox file, or manually set the position to the file's current byte length.
+
+**Weekly status not delivering**
+Check `goals.json` — the goal must have `status: "active"` and `next_status_delivery` must be a past date. If `active_approach` is empty, the goal is still in `decomposing` status and won't get weekly updates.
+
+**Too many goals with no progress**
+Goals without active approaches accumulate in the store. Periodically review `goals.json` and mark stale goals as `paused` or `abandoned` to keep the weekly status meaningful.
+
+**Goal decomposition is generic / not useful**
+The quality of decomposition depends on how specific the goal statement is. "Improve things" is hard to decompose. "Get weekly OKR scoring rates above 80% by end of Q3" gives the agent something concrete to work with.

package/SKILL.md

@@ -0,0 +1,32 @@
+# Using openclaw-goals
+
+## When to submit a goal
+
+Call `goal_submit` when the user expresses a fuzzy, long-running objective — something that can't be finished in one session and doesn't have an obvious single action:
+
+- "I want to improve our OKR scoring rate"
+- "We need to get better signal on what's blocking engineers"
+- "Figure out why our PostHog costs keep spiking"
+- "Help me build a habit of writing weekly team updates"
+
+**Don't** submit routine tasks, one-off requests, or things that are already well-defined tickets. Goals are directions, not tasks.
+
+## How to submit
+
+Call `goal_submit(description)` with the user's objective as stated — fuzzy language is fine. You don't need to clean it up or restate it formally. The system handles decomposition.
+
+After submitting, confirm to the user: "I've recorded that as a goal and will come back with some approaches."
+
+## What happens next
+
+Within the next cron pass (up to 15 minutes), a `[GOALS: DECOMPOSE]` prompt will arrive in the session presenting 2–4 concrete approaches. The user picks one and the goal becomes active.
+
+## Weekly check-ins
+
+Every Monday (or the configured day), active goals receive a `[GOALS: WEEKLY STATUS]` prompt. You report what happened, what's blocked, and what's planned next. Keep it brief — if nothing happened, say so.
+
+## When NOT to submit
+
+- The user is describing a task they want done now → just do it
+- The user mentions something in passing without expressing intent → don't submit without confirming
+- The goal is already in the active list → update it, don't duplicate

package/dist/index.js

@@ -0,0 +1 @@
+export { default } from "./src/service.js";

package/dist/src/delivery.js

@@ -0,0 +1,52 @@
+export function buildDecompositionPrompt(description) {
+    return `[GOALS: DECOMPOSE] A new goal was submitted. Decompose it into candidate approaches and present them to the user for selection.
+
+Goal: "${description}"
+
+Your job:
+1. Think about what you could realistically do toward this goal given your available tools and access.
+2. Identify 2–4 concrete approaches. For each: describe what you'd do, what tools you'd use, what you could accomplish without human input, and what you'd need from the human to make progress.
+3. Present the approaches to the user and ask them to pick one (or say "none of these").
+
+Keep it practical. Only propose approaches you can actually execute with your current tools. Don't promise what you can't deliver.`;
+}
+export function buildWeeklyStatusPrompt(goal) {
+    const recentNotes = goal.progress_notes.slice(-3);
+    const progressText = recentNotes.length > 0
+        ? recentNotes.map(n => `- ${n.timestamp.slice(0, 10)}: ${n.summary}\n  (${n.what_changed})`).join("\n")
+        : "No progress logged yet.";
+    const blockerText = goal.blockers.length > 0
+        ? goal.blockers.map(b => `- ${b.description} (waiting on: ${b.waiting_on})`).join("\n")
+        : "None.";
+    return `[GOALS: WEEKLY STATUS] Deliver a weekly status update for this goal.
+
+Goal: "${goal.description}"
+Active approach: ${goal.active_approach || "(not yet selected)"}
+Status: ${goal.status}
+
+Recent progress:
+${progressText}
+
+Current blockers:
+${blockerText}
+
+Deliver a brief status update to the user covering:
+- What happened toward this goal this week
+- What's currently blocked and what would unblock it
+- What you plan to try next week
+- Any questions you need answered to make progress
+
+Be concise. If there's nothing new to report, say so briefly.`;
+}
+export async function deliverDecomposition(description, api) {
+    await api.session.workflow.enqueueNextTurnInjection({
+        sessionTarget: "main",
+        text: buildDecompositionPrompt(description),
+    });
+}
+export async function deliverWeeklyStatus(goal, api) {
+    await api.session.workflow.enqueueNextTurnInjection({
+        sessionTarget: "main",
+        text: buildWeeklyStatusPrompt(goal),
+    });
+}

package/dist/src/goal-store.js

@@ -0,0 +1,42 @@
+import { readFile, writeFile, mkdir } from "fs/promises";
+import { dirname } from "path";
+import { resolvePath } from "./utils.js";
+export async function loadGoals(path) {
+    try {
+        return JSON.parse(await readFile(resolvePath(path), "utf-8"));
+    }
+    catch {
+        return [];
+    }
+}
+export async function saveGoals(goals, path) {
+    const resolved = resolvePath(path);
+    await mkdir(dirname(resolved), { recursive: true });
+    await writeFile(resolved, JSON.stringify(goals, null, 2), "utf-8");
+}
+export function addGoal(goals, goal) {
+    return [...goals, goal];
+}
+export function updateGoalStatus(goals, id, status) {
+    return goals.map(g => g.id === id
+        ? { ...g, status, updated_at: new Date().toISOString() }
+        : g);
+}
+export function addProgressNote(goals, id, note) {
+    return goals.map(g => g.id === id
+        ? { ...g, progress_notes: [...g.progress_notes, note], updated_at: new Date().toISOString() }
+        : g);
+}
+export function setActiveApproach(goals, id, approach) {
+    return goals.map(g => g.id === id
+        ? { ...g, active_approach: approach, status: "active", updated_at: new Date().toISOString() }
+        : g);
+}
+export function addBlocker(goals, id, blocker) {
+    return goals.map(g => g.id === id
+        ? { ...g, blockers: [...g.blockers, { ...blocker, since: new Date().toISOString() }], updated_at: new Date().toISOString() }
+        : g);
+}
+export function updateNextDelivery(goals, id, nextDelivery) {
+    return goals.map(g => g.id === id ? { ...g, next_status_delivery: nextDelivery } : g);
+}

package/dist/src/inbox-reader.js

@@ -0,0 +1,43 @@
+import { readFile, writeFile, open, mkdir } from "fs/promises";
+import { dirname } from "path";
+import { resolvePath } from "./utils.js";
+export async function loadPosition(posPath) {
+    try {
+        const data = JSON.parse(await readFile(resolvePath(posPath), "utf-8"));
+        return data.position;
+    }
+    catch {
+        return 0;
+    }
+}
+export async function savePosition(position, posPath) {
+    const resolved = resolvePath(posPath);
+    await mkdir(dirname(resolved), { recursive: true });
+    await writeFile(resolved, JSON.stringify({ position }, null, 2), "utf-8");
+}
+export async function readNewGoals(inboxPath, posPath) {
+    const resolved = resolvePath(inboxPath);
+    let fh;
+    try {
+        fh = await open(resolved, "r");
+        const stat = await fh.stat();
+        const position = await loadPosition(posPath);
+        if (stat.size <= position)
+            return { goals: [], newPosition: position };
+        const buffer = Buffer.alloc(stat.size - position);
+        await fh.read(buffer, 0, buffer.length, position);
+        const newText = buffer.toString("utf-8");
+        const newPosition = stat.size;
+        const goals = newText
+            .split("\n")
+            .map(l => l.trim())
+            .filter(l => l.length > 0 && !l.startsWith("#"));
+        return { goals, newPosition };
+    }
+    catch {
+        return { goals: [], newPosition: 0 };
+    }
+    finally {
+        await fh?.close();
+    }
+}

package/dist/src/service.js

@@ -0,0 +1,110 @@
+// src/service.ts
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { DEFAULT_CONFIG } from "./types.js";
+import { resolveDataPath, generateId, isWithinActiveHours, nextWeeklyDate } from "./utils.js";
+import { loadGoals, saveGoals, addGoal, updateNextDelivery } from "./goal-store.js";
+import { readNewGoals, savePosition } from "./inbox-reader.js";
+import { deliverDecomposition, deliverWeeklyStatus } from "./delivery.js";
+function mergeConfig(raw, workspaceDir) {
+    return {
+        ...DEFAULT_CONFIG,
+        ...raw,
+        activeHours: { ...DEFAULT_CONFIG.activeHours, ...(raw.activeHours ?? {}) },
+        output: {
+            ...DEFAULT_CONFIG.output,
+            ...(raw.output ?? {}),
+            goalsPath: resolveDataPath(raw.output?.goalsPath, workspaceDir, DEFAULT_CONFIG.output.goalsPath),
+        },
+        inboxPath: resolveDataPath(raw.inboxPath, workspaceDir, DEFAULT_CONFIG.inboxPath),
+        inboxPositionPath: resolveDataPath(raw.inboxPositionPath, workspaceDir, DEFAULT_CONFIG.inboxPositionPath),
+    };
+}
+function isWeeklyCheckInDue(goal) {
+    return goal.status === "active" && new Date(goal.next_status_delivery) <= new Date();
+}
+export default definePluginEntry({
+    id: "goals",
+    name: "Goals",
+    description: "Persistent fuzzy goal tracking with weekly status delivery",
+    register(api) {
+        const workspaceDir = api.runtime.agent.resolveAgentWorkspaceDir(api.pluginConfig);
+        const config = mergeConfig(api.pluginConfig, workspaceDir);
+        api.registerTool({
+            name: "goal_submit",
+            description: "Submit a new long-running goal. Call this when the user expresses a fuzzy objective that spans multiple sessions. Returns the new goal's id.",
+            parameters: {
+                type: "object",
+                properties: {
+                    description: { type: "string", description: "The goal as stated by the user — fuzzy and long-running is fine" },
+                },
+                required: ["description"],
+            },
+            async execute(_id, params) {
+                const { description } = params;
+                let goals = await loadGoals(config.output.goalsPath);
+                const goal = {
+                    id: generateId(),
+                    description,
+                    decomposed_approaches: [],
+                    active_approach: "",
+                    status: "decomposing",
+                    created_at: new Date().toISOString(),
+                    updated_at: new Date().toISOString(),
+                    progress_notes: [],
+                    blockers: [],
+                    next_status_delivery: nextWeeklyDate(config.weeklyCheckInDay, config.weeklyCheckInTime, config.activeHours.timezone),
+                };
+                goals = addGoal(goals, goal);
+                await saveGoals(goals, config.output.goalsPath);
+                await deliverDecomposition(description, api);
+                return { content: [{ type: "text", text: JSON.stringify({ id: goal.id }) }] };
+            },
+        });
+        api.registerTool({
+            name: "check_goals",
+            description: "Check inbox for new goals and deliver weekly status for active goals. Called by the goals cron.",
+            parameters: {},
+            async execute(_id, _params) {
+                if (!isWithinActiveHours(config)) {
+                    return { content: [{ type: "text", text: "SILENT_REPLY_TOKEN" }] };
+                }
+                let goals = await loadGoals(config.output.goalsPath);
+                const { goals: newDescriptions, newPosition } = await readNewGoals(config.inboxPath, config.inboxPositionPath);
+                for (const description of newDescriptions) {
+                    const goal = {
+                        id: generateId(),
+                        description,
+                        decomposed_approaches: [],
+                        active_approach: "",
+                        status: "decomposing",
+                        created_at: new Date().toISOString(),
+                        updated_at: new Date().toISOString(),
+                        progress_notes: [],
+                        blockers: [],
+                        next_status_delivery: nextWeeklyDate(config.weeklyCheckInDay, config.weeklyCheckInTime, config.activeHours.timezone),
+                    };
+                    goals = addGoal(goals, goal);
+                    await deliverDecomposition(description, api);
+                }
+                if (newDescriptions.length > 0) {
+                    await savePosition(newPosition, config.inboxPositionPath);
+                }
+                for (const goal of goals) {
+                    if (isWeeklyCheckInDue(goal)) {
+                        await deliverWeeklyStatus(goal, api);
+                        goals = updateNextDelivery(goals, goal.id, nextWeeklyDate(config.weeklyCheckInDay, config.weeklyCheckInTime, config.activeHours.timezone));
+                    }
+                }
+                await saveGoals(goals, config.output.goalsPath);
+                return { content: [{ type: "text", text: "SILENT_REPLY_TOKEN" }] };
+            },
+        });
+        api.session.workflow.scheduleSessionTurn({
+            schedule: { cron: config.schedule },
+            sessionTarget: "isolated",
+            tag: "goals-check-pass",
+            systemPrompt: `You are the goals tracking agent. Call check_goals() to process new goals and deliver weekly status updates. Reply SILENT_REPLY_TOKEN after the tool call.`,
+            maxTurns: 2,
+        });
+    },
+});

package/dist/src/types.js

@@ -0,0 +1,9 @@
+export const DEFAULT_CONFIG = {
+    schedule: "*/15 * * * *",
+    activeHours: { start: "08:00", end: "20:00", timezone: "America/Los_Angeles" },
+    weeklyCheckInDay: "monday",
+    weeklyCheckInTime: "09:00",
+    inboxPath: "goals/inbox.md",
+    inboxPositionPath: "goals/inbox-position.json",
+    output: { goalsPath: "goals/goals.json" },
+};

package/dist/src/utils.js

@@ -0,0 +1,38 @@
+import { homedir } from "os";
+import { join } from "path";
+export function resolvePath(p) {
+    return p.startsWith("~/") ? join(homedir(), p.slice(2)) : p;
+}
+export function resolveDataPath(override, workspaceDir, defaultRelative) {
+    if (!override)
+        return join(workspaceDir, defaultRelative);
+    if (override.startsWith('/') || override.startsWith('~/'))
+        return resolvePath(override);
+    return join(workspaceDir, override);
+}
+export function generateId() {
+    return `goal-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+export function isWithinActiveHours(config) {
+    const formatter = new Intl.DateTimeFormat("en-US", {
+        timeZone: config.activeHours.timezone,
+        hour: "2-digit", minute: "2-digit", hour12: false,
+    });
+    const [hours, minutes] = formatter.format(new Date()).split(":").map(Number);
+    const now = (hours ?? 0) * 60 + (minutes ?? 0);
+    const [sh, sm] = config.activeHours.start.split(":").map(Number);
+    const [eh, em] = config.activeHours.end.split(":").map(Number);
+    return now >= (sh ?? 0) * 60 + (sm ?? 0) && now <= (eh ?? 0) * 60 + (em ?? 0);
+}
+export function nextWeeklyDate(day, time, timezone) {
+    const dayNames = ["sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday"];
+    const targetDay = dayNames.indexOf(day.toLowerCase());
+    const now = new Date();
+    const formatter = new Intl.DateTimeFormat("en-US", { timeZone: timezone, weekday: "long" });
+    const currentDay = dayNames.indexOf(formatter.format(now).toLowerCase());
+    const daysUntil = ((targetDay - currentDay) + 7) % 7 || 7;
+    const next = new Date(now.getTime() + daysUntil * 24 * 60 * 60 * 1000);
+    const [h, m] = time.split(":").map(Number);
+    next.setHours(h ?? 9, m ?? 0, 0, 0);
+    return next.toISOString();
+}

package/openclaw.plugin.json

@@ -0,0 +1,14 @@
+{
+  "id": "goals",
+  "name": "Goals",
+  "version": "0.1.0",
+  "description": "Persistent fuzzy goal tracking: accepts vague objectives, decomposes them into candidate approaches, tracks incremental progress, and delivers weekly status",
+  "contracts": {
+    "tools": ["goal_submit", "check_goals"]
+  },
+  "activation": { "onStartup": true },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": true
+  }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@akalsey/openclaw-goals",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "openclaw.plugin.json",
+    "README.md",
+    "SKILL.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "compat": {
+      "pluginApi": ">=2026.3.24-beta.2",
+      "minGatewayVersion": "2026.3.24-beta.2"
+    },
+    "install": {
+      "localPath": "."
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "openclaw": "latest",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.3.24-beta.2"
+  }
+}