Goals Plugin

The Goals plugin provides long-lived intents: a goal is an on-disk namespace (a knowledge-base tree) with one or more worker conversations that fire on a schedule, coordinate through the goal's shared knowledge base, and pursue the intent over time. Everything is driven by agent-callable tools — the agent sets up a goal, and the Scheduler runs its workers.

Configuration

plugins:
  - module: codumentor.plugins.goals
    class: GoalsPlugin
    priority: 10
    args:
      enabled: true
      default_timezone: UTC
      # storage_repo: my-repo   # optional; see "Storage" below

Parameters

enabled (optional): Whether the plugin is active (default: true)
default_timezone (optional): IANA timezone for interpreting worker cron expressions (default: "UTC")
storage_repo (optional): Name of a configured repo (a key under repos) where goal trees are stored. When unset, falls back to the Agentic Memory plugin's repo, then to single-repo mode.
storage_path (optional): Path under the resolved repo root for goal trees (default: "goals")
setup_agent (optional): Enables a propose-before-commit flow for setup_goal:
enabled (default false): when true, setup_goal drafts the goal via a goal-role sub-agent and validates it before writing
max_iterations (default 12): re-prompt budget for the proposal

Tool Reference

The Goals tools are deferred (discovered via tool search) so they don't clutter the default tool set.

Tool	Description
`setup_goal`	Create a goal: validate, render the KB tree, and register its cron workers
`list_goals`	List the caller's goals with status and worker summaries
`get_goal`	Read a goal's definition, state, and live worker schedules
`delete_goal`	Cancel all worker schedules (optionally delete the KB)
`run_worker_now`	Fire one worker immediately as a one-off
`update_worker`	Change a worker's cron, instructions, role, allowed sub-agents, or timeout
`goal_kb_read`	Read a file from the goal KB by goal-relative path
`goal_kb_write`	Write/append a file in the goal KB by goal-relative path
`goal_kb_list`	List files/directories under a goal KB sub-path

Storage

Goal trees must live inside a configured repo so that goal workers running under Workspace Isolation can see them at /workspace/.... The location is resolved in order: explicit storage_repo → Agentic Memory's repo → single-repo mode. If none apply the plugin raises an error rather than writing outside repos_dir.

Notes

KB is the source of truth. Worker prompts and protocol live in the goal tree (<goal>/workers/<name>/prompt.md, protocol.md); the scheduler row holds only a static shim, so edits take effect on the next tick without rescheduling.
goal_kb_ is the door under isolation. Workers run with general file tools (read_file, write_file, shell, …) stripped, so the goal-relative goal_kb_ tools are the only way to durably read/write the goal tree from inside the sandbox.
Requirements: the core Scheduler and job queue (both on by default); the propose flow additionally needs the Model Profiles goal role.
Registration is all-or-nothing: if any worker fails to schedule, the whole goal is rolled back.