@defend-tech/opencode-optima 0.1.55 → 0.1.56

package/docs/guides/AGENTS.md

@@ -36,11 +36,11 @@ These agents can talk directly with the user and turn meaningful discussions int
 
 ## Repository Customization
 
-- `.optima/agents/<agent>.md`: full repository-local agent definition. Use this to override a bundled agent's base prompt or define a brand new custom repository agent.
-- `.optima/agent-additions/<agent>.md`: appends repository-specific instructions to a bundled or custom agent prompt.
+- `.optima/agents/<agent>.md`: full repository-local agent definition. Use this to override a bundled agent's base prompt or define a brand new custom repository agent. This replaces the plugin-bundled prompt for that agent, so future npm/plugin updates to that bundled prompt will not apply until the local override is removed or manually merged.
+- `.optima/agent-additions/<agent>.md`: appends repository-specific instructions to a bundled or custom agent prompt. This keeps receiving future plugin-bundled prompt updates.
 - `.optima/policies/*.md`: overrides shared repository policy files used by multiple agents.
 
-Use shared policies and additive agent files by default. Use full agent definitions in `.optima/agents/` when a repository needs a custom agent or needs to take over an agent's base prompt.
+Use shared policies and additive agent files by default. Do not create or populate `.optima/agents/<agent>.md` unless the user explicitly requests a full local override or custom repository agent; otherwise use `.optima/agent-additions/<agent>.md` so bundled plugin updates keep applying.
 
 ## Typical usage by task complexity
 

package/docs/guides/TOOLS.md

@@ -32,7 +32,7 @@ Initializes Optima in the current repository.
 - Generated prompt dumps go to `.optima/.config/generated/agents/` when `features.debug_dumps` is enabled.
 - Generated reference policy files go to `.optima/.config/generated/policies/` when `policies.extract_defaults` is set to `all`.
 - The scaffolded README files in `.optima/agents/` and `.optima/agent-additions/` list common `plugin:` and `policy:` includes that custom agents can reuse.
-- After a successful init, Optima will request the OpenCode instance be disposed so the new config/agents can be reloaded.
+- After a successful init, reload OpenCode manually if the newly scaffolded config or agents are not visible. Optima does not dispose the active instance automatically because that can abort the current session.
 
 ## `optima_validate`
 
@@ -46,6 +46,31 @@ It checks things like:
 - placeholder documentation problems
 - hidden/tool-owned trees such as `.github/workflows/` are ignored
 
+## `optima_repair`
+
+Inspects and repairs common Optima operational metadata problems.
+
+### Arguments
+
+- `apply`: optional boolean. Defaults to dry-run. Set `true` to write deterministic repairs.
+- `mode`: optional string. Use `apply` or `dry-run`; dry-run is the default.
+- `team_mode`: `mini` or `full` for a newly created config when `.optima/.config/optima.yaml` is missing.
+
+### What it checks
+
+- missing `.optima/` operational scaffolding
+- legacy/root artifacts that should be merged into `.optima/`
+- missing registries, task templates, policy README, config, and root CodeMap
+- Markdown references that still point at root `tasks/`, `evidences/`, `docs/scrs/`, `logs/`, or `screenshots/`
+- missing Optima `.gitignore` local/private rules
+- broken, over-deep, or incomplete CodeMap entries
+
+### Notes
+
+- Dry-run never mutates the worktree.
+- Apply mode runs `optima_validate` after repair and includes the validation result in the response.
+- Ambiguous CodeMap boundaries are reported as unresolved instead of guessed.
+
 ## `optima_start_discussion`
 
 Starts or reopens an automatic discussion transcript for the current session.
@@ -115,3 +140,120 @@ Sends a follow-up prompt to an existing `workflow_runner` session.
 
 - Only available in `full` team mode.
 - Useful for bounce-backs, clarifications, and resumed runner work.
+
+## OpenCode Session Control Tools
+
+These tools are intended for controlled automation paths such as ClickUp routing and diagnostics. They all resolve the requested directory through Optima's safe worktree rules.
+
+### `optima_session_create`
+
+Creates an OpenCode session.
+
+Arguments:
+
+- `directory`: project directory for the session
+- `title`: session title
+- `agent`: optional agent id
+
+### `optima_session_prompt`
+
+Sends a prompt to an existing OpenCode session.
+
+Arguments:
+
+- `session_id`: OpenCode session id
+- `directory`: project directory for the session
+- `text`: prompt text
+- `agent`: optional agent id
+- `omit_agent`: set to `true` to omit the agent field from the prompt body
+
+### `optima_session_messages`
+
+Reads and summarizes messages from an OpenCode session.
+
+Arguments:
+
+- `session_id`: OpenCode session id
+- `directory`: optional project directory for the session
+- `limit`: optional message limit
+
+### `optima_session_probe`
+
+Creates, prompts, and reads an OpenCode session without touching ClickUp state.
+
+Arguments:
+
+- `directory`: project directory for the session
+- `agent`: optional agent id
+- `omit_agent_on_prompt`: set to `true` to omit the agent field from the prompt body
+- `text`: optional marker text to send
+
+## ClickUp Dry-Run Payload Tools
+
+These tools generate or validate payloads for ClickUp-oriented workflows. Except for webhook runtime paths configured explicitly through OpenCode/plugin options, these helper tools are dry-run/no-op boundaries and do not directly mutate ClickUp.
+
+### `optima_clickup_sync_summary`
+
+Builds a ClickUp summary/comment payload from `.optima/evidences/<task>/SUMMARY.md` and optional task markdown.
+
+Arguments:
+
+- `summary_path`: path to the evidence summary markdown
+- `task_path`: optional path to `.optima/tasks/...` task markdown
+- `branch`: optional branch override
+- `worktree`: optional worktree display override
+- `pr`: optional PR override
+
+### `optima_clickup_start_task`
+
+Builds a start-task payload with branch, worktree, mirror paths, initial fields, and Definition content.
+
+Arguments include:
+
+- `task_id`
+- `task_type`
+- `parent_task_id`
+- `subtask_id`
+- `definition`
+- `task_description`
+- `complexity`
+- `files_changed`
+- `acceptance_criteria`
+- `unknowns`
+
+### `optima_clickup_transition`
+
+Builds a status transition payload and final-approval assignment plan.
+
+Arguments include:
+
+- `from_status`
+- `to_status`
+- `validation_passed`
+- `validation_failed`
+- `is_subtask`
+- `reopen`
+- `product_manager_assignee`
+- `plan_description`
+- `definition`
+
+### `optima_clickup_create_subtasks`
+
+Builds dry-run ClickUp subtask creation payloads from a strict Markdown `## Subtasks` section.
+
+Arguments:
+
+- `parent_task_id`
+- `markdown_path`
+- `parent_branch`
+- `parent_task_type`
+- `apply`: records an apply request, but live apply remains no-op
+
+### `optima_clickup_apply_payload`
+
+Validates a generated ClickUp payload at the dry-run/no-op apply boundary.
+
+Arguments:
+
+- `payload_json`
+- `apply`: set to `true` to request live apply; currently returns not implemented/configured without calling ClickUp

package/docs/setup/CONFIGURATION.md

@@ -96,6 +96,8 @@ This writes the bundled default policy files from package `assets/policies/` to
 
 Create `.optima/agent-additions/<agent>.md` to append repository-specific instructions to a bundled or custom agent prompt.
 
+Use additions for normal repository-specific guidance. Because additions are appended after the bundled prompt, future plugin updates to the bundled agent still apply.
+
 ### Add repository-local agents or override a bundled base prompt
 
 Create `.optima/agents/<agent>.md` to:
@@ -103,6 +105,8 @@ Create `.optima/agents/<agent>.md` to:
 - replace the bundled base prompt for an existing agent, or
 - define a brand new custom repository agent
 
+A file in `.optima/agents/<agent>.md` is a full local override. For that agent, Optima uses the repository-local definition instead of the plugin-bundled definition, so later npm/plugin updates to that bundled agent will not affect the overridden prompt until you remove or manually merge the local override. Do not create these files unless the user explicitly requests a full local override or custom repository agent; use `.optima/agent-additions/<agent>.md` for normal repo-specific guidance.
+
 ## Operational notes
 
 - The `product_manager` agent becomes the default primary agent when Optima is enabled.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defend-tech/opencode-optima",
-  "version": "0.1.55",
+  "version": "0.1.56",
   "repository": {
     "type": "git",
     "url": "git+ssh://git@github.com/defend-tech/opencode-optima.git"
@@ -35,7 +35,7 @@
   "dependencies": {
     "@opencode-ai/plugin": "^1.2.6",
     "ignore": "^5.3.2",
-    "yaml": "^2.3.0"
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "esbuild": "^0.25.0",