Goals Plugin

The Goals plugin provides long-lived intents: a goal is a knowledge-base tree on disk plus one or more workers that fire on a cron schedule, share that knowledge base, and pursue the intent over time. You (or the agent, through tools) set up a goal once; the Scheduler runs its workers after that.

Ask the agent to create a goal, list yours, pause one, or inspect what a worker last wrote. You do not talk to a worker directly — input goes through the goal tools.

Configuration

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

Parameter	Type	Default	Description
enabled	bool	true	Enable or disable the plugin.
default_timezone	string	"UTC"	IANA timezone for interpreting worker cron expressions.
storage_repo	string	unset	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	string	"goals"	Path under the resolved repo root for goal trees.
setup_agent.enabled	bool	false	When true, setup_goal can draft the goal via a goal-role sub-agent and validate it before writing.
setup_agent.max_iterations	int	12	Re-prompt budget for that proposal.
commit_enabled	bool	true	Commit each goal's knowledge-base subtree into git so state is never only an uncommitted working tree. Set to false for a non-git workspace — otherwise the plugin warns once that it cannot commit.
push_enabled	bool	true	Push after committing, through the Agentic Memory plugin's shared push path. Ignored when commit_enabled is false.
push_timeout	int	30	Push timeout in seconds.
push_max_consecutive_failures	int	5	Consecutive push failures before the circuit breaker opens.
commit_signature	string	"Made with Codumentor"	Trailer appended to every goal commit.
flush_after_minutes	int	30	Commit a running worker's subtree once its state has gone this long uncommitted, so a long tick does not hold everything until it ends. 0 disables the flush.
worker_denied_tools	list	unset	Replaces the built-in list of general file tools hidden from goal workers. Omit to keep the built-in list; set [] to stop stripping file tools. Lifecycle tools and the allowed-subagents gate still apply.
target_agents	string	"main"	Which agents get the goal tools: "main", "subagent", or "all". Default keeps create/delete/write off subagents.

Tools

The Goals tools are discovered on demand (they are not in the default tool list), so they do not clutter every turn.

Tool	Description
setup_goal	Create a goal: validate, write the knowledge-base 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 knowledge base)
pause_goal / resume_goal	Halt or restart every worker's cron ticks without deleting the goal
import_goal	Re-register a goal tree copied into the storage root (restore/portability)
add_worker	Add a cron worker to an existing goal
remove_worker	Remove one worker (schedule and its subtree)
run_worker_now	Fire one worker immediately as a one-off
update_worker	Change a worker's cron, instructions, role, allowed sub-agents, timeout, or model_role
goal_kb_read	Read a file from the goal knowledge base by goal-relative path
goal_kb_write	Write a file in the goal knowledge base by goal-relative path
goal_kb_append_entry	Append one item to a YAML list in a knowledge-base file (for growing logs that are too large to rewrite whole)
goal_kb_list	List files/directories under a goal knowledge-base sub-path

Storage

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

Under workspace isolation, workers should use the goal_kb_* tools to read and write the goal's files. Those tools write the shared tree on disk; ordinary file tools in a sandboxed worker would not persist for the next tick.

Notes

• The knowledge base is the source of truth. Worker instructions live in the goal tree; editing them takes effect on the next tick without rescheduling.
• Registration is all-or-nothing: if any worker fails to schedule, the whole goal is rolled back.
• Commits recover on their own. A tick normally commits its subtree when the run ends. If that never happens (restart, timeout), the next tick of any worker — and the next server start — commits whatever is still dirty.
• Requirements: the core Scheduler and job queue (both on by default); the propose flow additionally needs the Model Profiles goal role.
• Per-worker model_role (cost lever). A worker may name a model_role — a profile the deployment configures under Model Profiles. Put high-frequency collectors on a cheap slot and analysts on the strong one; an unset or unmapped role falls back to the default agent model. Editable live via update_worker and inherited by run_worker_now.