| 1 | # Goal Plugin DOX |
| 2 | |
| 3 | ## Purpose |
| 4 | |
| 5 | - Own the built-in chat goal strip, `/goal` slash command, goal state API, and agent-facing goal tools. |
| 6 | - Keep chat goals scoped to the active chat context and stored as user data outside tracked plugin code. |
| 7 | |
| 8 | ## Ownership |
| 9 | |
| 10 | - `plugin.yaml` owns the always-enabled `_goal` plugin metadata. |
| 11 | - `tools/goal.py` owns the single agent-facing goal tool, file-backed state under `usr/plugins/_goal/goals/`, and goal status normalization. |
| 12 | - `api/goal.py` owns the WebUI JSON API for reading, editing, pausing, resuming, and deleting goals. |
| 13 | - `commands/` owns the `/goal` slash command contributed to `_commands`. |
| 14 | - `webui/` and `extensions/webui/` own the composer goal strip, Goal mode shortcut, and inline controls. |
| 15 | - `tools/goal.py` and `prompts/agent.system.tool.goal.md` own agent-facing goal inspection, creation, and status updates. |
| 16 | - `tools/response.py` overrides the core response tool so an active goal continues the current monologue. |
| 17 | - `extensions/python/message_loop_prompts_after/` owns injecting the active goal into agent context. |
| 18 | |
| 19 | ## Local Contracts |
| 20 | |
| 21 | - Goal status values are `active`, `paused`, `complete`, and `blocked`. |
| 22 | - Active goals are injected into agent extras; paused and blocked goals remain visible in the UI, while complete goals are hidden. |
| 23 | - Goal records track accumulated active time with `elapsed_seconds` and `active_since`; pausing freezes elapsed time until resume. |
| 24 | - User controls may pause, resume, edit, or delete a goal; destructive delete uses inline confirmation. Model tools may create goals and mark them complete or blocked. |
| 25 | - Saving an edit that reactivates a complete or blocked goal resends the edited objective so agent processing resumes. |
| 26 | - `/goal <objective>` creates the goal and sends the objective as the user message so the agent starts working immediately. |
| 27 | - The composer Goal mode shortcut only prefills `/goal ` and focuses the input; it never sends the command. |
| 28 | - `/goal auto` fills the composer with a prompt asking the agent to create and manage its own goal instead of silently sending a message. |
| 29 | - While a goal is active, response-tool calls are intermediate updates; only completing or blocking the goal restores normal loop termination. |
| 30 | - Goal UI feedback uses toast notifications and inline controls, not modal dialogs. |
| 31 | - Goal state changes publish a context revision through the shared state-push |
| 32 | lifecycle; the WebUI refreshes on context or revision changes and never polls |
| 33 | the Goal API while idle. |
| 34 | |
| 35 | ## Work Guidance |
| 36 | |
| 37 | - Keep goal state in `usr/plugins/_goal/`; do not store runtime goal data in tracked files. |
| 38 | - Keep the goal strip mounted through WebUI extension points instead of modifying core composer templates. |
| 39 | - Keep `_commands` compatibility in mind: `/goal` is a plugin-contributed command and should remain read-only in the command manager. |
| 40 | |
| 41 | ## Verification |
| 42 | |
| 43 | - Run `conda run -n a0 pytest plugins/_goal/tests` after changing `_goal` backend behavior. |
| 44 | - Run `_commands` discovery tests when changing the `/goal` command contribution contract. |
| 45 | |
| 46 | ## Child DOX Index |
| 47 | |
| 48 | No child DOX files. |