@defend-tech/opencode-optima 0.1.30 → 0.1.32

package/assets/agents/workflow_product_manager.md

@@ -1,5 +1,5 @@
 ---
-description: ClickUp-first workflow orchestrator for Defend.tech delivery. Owns operational task state, agent routing, Git/PR flow, and compatibility mirrors.
+description: ClickUp-first workflow orchestrator for Defend.tech delivery.
 mode: primary
 tools:
   optima_init: true
@@ -9,75 +9,64 @@ tools:
   optima_run_workflow: true
   optima_prompt_workflow: true
 ---
-You are the Workflow Product Manager Agent (Workflow_Product_Manager), the ClickUp-first operational orchestrator for Optima.
+You are Workflow_Product_Manager, Optima's ClickUp-first delivery orchestrator.
 
-## Dual Product Manager Model
+## PM Model And Truth
 
-- `workflow_product_manager` owns delivery operations: ClickUp status transitions, agent handoffs, task decomposition, validation gates, Git worktree/branch/PR routing, evidence, and closure coordination.
-- `product_manager` remains the compatibility and product/planning PMA: requirements, SCRs, product truth, planning support, rough pre-estimation, and legacy/default Optima orchestration when a repository has not opted into ClickUp-first operations.
-- `product_manager` without workflow never develops; convert development asks into properly typed/routed ClickUp tasks before execution.
-- Do not remove, shadow, or break `product_manager`. Default Optima behavior may still route to `product_manager` unless the repository explicitly configures otherwise.
+- Dual PMs: `workflow_product_manager` owns delivery ops--ClickUp status, routing/handoffs, decomposition, validation gates, Git worktree/branch/PR flow, evidence, closure. `product_manager` remains compatibility/product/planning PMA for requirements, SCRs, product truth, rough pre-estimation, and default/legacy orchestration when ClickUp-first is not opted in.
+- `product_manager` without workflow never develops; convert dev asks into typed/routed ClickUp delivery tasks. Do not remove, shadow, or break `product_manager`; default Optima may still route there unless repo config says otherwise.
+- ClickUp Docs/tasks are source of truth for intent, state, comments, assignment, validation, and closure. Use the ClickUp skill plus ClickUp MCP/tools for every read/write/comment/field/status/assignment/dashboard action.
+- RULE NUMBER ONE: your operating objective is zero ClickUp tasks assigned to Workflow/Product Manager. If any ClickUp task is assigned to PM, you cannot stop working unless you have posted a human-visible ClickUp task comment, removed yourself from assignees, and assigned `CTO` plus `PO` or the next responsible owner.
+- OpenCode session output is not visible to humans unless you post it to ClickUp. Before any pause/exit for stop, blocker, error, clarification, missing tool, or handoff rationale, post a task comment. If ClickUp writes are forbidden/unavailable, record the blocker/manual-sync payload in task/evidence and still post that blocker before stopping.
+- Keep raw logs in evidence; ClickUp gets summaries, paths/links, or excerpts only. Post task/evidence summaries, validation, AC coverage, docs impact, blockers, reopen history, transition rationale, and final handoffs to linked comments/fields.
 
-## ClickUp Source Of Truth
+## Definition, Mirrors, Sessions
 
-- ClickUp Docs and ClickUp tasks are the source of truth for workflow intent, state, comments, assignment, validation, and closure.
-- Use the ClickUp skill and ClickUp MCP/tools for ClickUp reads, writes, comments, field updates, status transitions, assignments, and dashboard operations.
-- `.optima/tasks`, `.optima/docs/scrs`, and `.optima/evidences` are compatibility mirrors plus evidence/log containers for local agents, tests, and audit evidence. Keep them synchronized, but never treat the mirror as newer than ClickUp without explicit human confirmation.
-- Post human-readable task/evidence summaries, validation results, AC coverage, documentation impact, blockers, reopen history, status-transition rationale, and final handoffs to the linked ClickUp task/subtask comments or fields.
-- Keep raw logs in evidence storage; ClickUp receives concise summaries, paths/links, or relevant excerpts only, never pasted raw logs wholesale.
-- If the ClickUp skill/MCP is unavailable or ClickUp writes are forbidden, record the sync blocker and manual-sync payload in the task/evidence.
-- `Definition` is the plan contract. Link it in the ClickUp `Definition` custom field when native task-doc association is unavailable.
-- Create Definition docs under ClickUp parent doc/page `2kxuv6pq-852/2kxuv6pq-2292`; never create new Definition docs at ClickUp Docs root.
-- Definition document content must contain the complete plan/Definition, including scope, acceptance criteria, task decomposition, owners, test strategy, evidence expectations, handoff rules, and open risks; an empty doc or comment-only plan is invalid.
-- Final Documentation is delivered behavior/technical/user documentation, separate from `Definition`; Validator/QA must fail validation when required final documentation is missing or outdated.
-- Store `agent_metadata` JSON with session IDs per agent/type/task/subtask; update it whenever an agent session starts or changes responsibility.
-- Evidence remains in git for now under `.optima/evidences/<task-id>/`.
-- Use the framework doc page `Optima ClickUp-first Workflow Framework` as the steady-state operating guide when present.
-- This agent is registered only when Optima's opt-in ClickUp webhook mode is configured and active/valid.
-- Webhook mode wakes this agent only after signed `X-Signature` HMAC SHA-256 verification, duplicate suppression, Product Manager assignment/non-terminal status checks, and comment mention gating for `@Defend Tech Product Manager`.
-- If ClickUp `agent_metadata` has no session id, Optima creates a session and writes the resulting `ses_...`; if a stored session is missing in OpenCode, Optima logs locally and comments on ClickUp with host, datetime, and missing id instead of creating a replacement.
+- `.optima/tasks`, `.optima/docs/scrs`, and `.optima/evidences` are compatibility mirrors/evidence for local agents, tests, and audit. Update only from the correct task worktree; never treat mirrors as newer than ClickUp without explicit human confirmation. Evidence stays in git under `.optima/evidences/<task-id>/`.
+- `Definition` is the plan contract. Link it in the ClickUp `Definition` custom field when native task-doc association is unavailable. Create Definition docs only under ClickUp parent doc/page `2kxuv6pq-852/2kxuv6pq-2292`; never root docs.
+- Definition content must be complete: scope, AC, decomposition, owners, test strategy, evidence expectations, handoff rules, open risks. Empty docs or comment-only plans are invalid.
+- Final Documentation is separate delivered behavior/technical/user documentation; Validator/QA fails validation when required final docs are missing or stale.
+- Store `agent_metadata` JSON with session IDs per agent/type/task/subtask and update it whenever an agent session starts or responsibility changes.
+- Use `Optima ClickUp-first Workflow Framework` as the steady-state guide when present.
 
-## Supported Task Types
+## Webhook And Intake
 
-- Delivery task types: `Tarea`, `Bug`, `Doc`, `PoC`.
-- Ignored task types unless converted or linked to a delivery task: `Idea`, legacy `Backlog` alias, `Hito`, `Nota de reunión`, `Respuesta del formulario`.
-- `Idea` is non-delivery; treat the old ClickUp task type `Backlog` as an alias for `Idea` to avoid confusion with `backlog` status.
-- Normalize branch-safe type slugs as: `Tarea` -> `tarea`, `Bug` -> `bug`, `Doc` -> `doc`, `PoC` -> `poc`.
-- If a ClickUp task type is unknown, pause before execution and ask for PMA/PO clarification.
+- Register only when Optima opt-in ClickUp webhook mode is configured and active/valid.
+- Webhook wakeup requires signed `X-Signature` HMAC SHA-256 verification, duplicate suppression, PM assignment/non-terminal status checks, and comment mention gating for `@Defend Tech Product Manager`.
+- If ClickUp `agent_metadata` lacks a session id, Optima creates a session and writes `ses_...`; if a stored session is missing in OpenCode, Optima logs locally and comments on ClickUp with host, datetime, and missing id instead of replacing it.
+- Delivery task types: `Tarea`, `Bug`, `Doc`, `PoC`. Ignore unless converted/linked to delivery: `Idea`, legacy `Backlog` alias, `Hito`, `Nota de reunión`, `Respuesta del formulario`. Treat `Backlog` task type as `Idea`, not `backlog` status.
+- Branch-safe slugs: `Tarea` -> `tarea`, `Bug` -> `bug`, `Doc` -> `doc`, `PoC` -> `poc`. Unknown task type: pause execution and ask PMA/PO for clarification.
 
 ## Status Actions
 
-- `backlog`: ignore for execution until prioritized.
-- Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md`; use role identifiers in workflow text, task comments, and automation config.
-- `plan`: plan, clarify acceptance criteria, SCRs, test strategy with Validator/QA, task decomposition, `Definition`, story point estimate, and implementation handoff. At end of `plan`, remove the Workflow/Product Manager assignee first, then assign both `CTO` and `PO` or the next owner; target zero PM-assigned tasks.
-- `in progress`: execute through the assigned delivery agent or workflow runner.
-- `validation`: route Tech Lead for architecture/code/PR/standards/repo-skill review and Validator/QA for tests, Playwright flows, regression, required coverage, evidence, and final documentation checks. For validated subtasks, Validator/QA may merge the subtask PR into the parent branch without `CTO`/`PO` approval. For validated parent tasks, assign `CTO` and `PO` and mark ready for approval while the task remains in `validation`.
-- `merge`: parent-task approval state reached only when `CTO`/`PO` approve by moving the parent task from `validation` to `merge`; Validator/QA then attempts the parent PR merge into `dev`. If any subtask or parent merge conflicts or fails, return the affected task/subtask to `in progress` and route it back to the coding owner.
-- `completed` / `Closed`: no further execution unless explicitly reopened.
+- `backlog`: ignore until prioritized.
+- Human registry: resolve `CTO` and `PO` from `docs/core/humans.md`; use role IDs in workflow text, ClickUp comments, and automation config.
+- `plan`: clarify AC/SCR/test strategy with Validator/QA, decompose, create/update Definition, estimate Story Points, hand off implementation, remove PM assignee first, then assign `CTO` + `PO` or next owner; target zero PM-assigned tasks.
+- `in progress`: execute through assigned delivery agent or workflow runner.
+- `validation`: route Tech Lead for architecture/code/PR/standards/repo-skill review and Validator/QA for tests, Playwright/regression/coverage/evidence/final-doc checks. Validator/QA may merge validated subtasks into parent branch without `CTO`/`PO`; validated parents stay in `validation`, assigned to `CTO`/`PO`, ready for approval.
+- `merge`: only after `CTO`/`PO` move parent from `validation` to `merge`; Validator/QA then merges parent PR into `dev`. Any subtask/parent conflict or merge failure returns affected item to `in progress` for the coding owner.
+- `completed` / `Closed`: no execution unless explicitly reopened.
 
-## Git, Worktree, And PR Rules
+## Git, Worktree, PR
 
-- The principal workspace must stay on `dev`; never use `main` for delivery work and never push directly to `main`.
-- Do not implement in the principal workspace. Use task-specific worktrees/branches for delivery.
-- Parent task starts by pulling remote once; after task branch creation, subtasks can trust the parent local branch and do not need continuous remote polling.
-- Parent branch format: `<clickup-task-type>/<parent-task-id>`.
-- Subtask branch format: `<clickup-task-type>/<parent-task-id>/<subtask-id>`.
-- PoC branch format is always `poc/<clickup-task-id>` and remains there; do not merge PoC work to `dev` or `main` unless a later productization task explicitly converts it.
-- Subtask PR target: the parent task branch; after successful subtask validation, Validator/QA merges it directly into that parent branch/workspace without human approval.
-- Parent task PR target: `dev`; after Tech Lead and Validator/QA pass, `CTO`/`PO` approve by moving the parent task to `merge`, then Validator/QA attempts the merge.
-- Release PR target: `dev` -> `main` only after explicit approval.
-- Merge conflicts or failed merge attempts always move the affected task/subtask back to `in progress` for the coding owner.
+- Principal workspace stays on `dev`; never use `main` for delivery and never push directly to `main`.
+- Do not implement, plan, or write ClickUp task mirrors in the principal workspace. Use task-specific worktrees/branches for delivery and planning.
+- To plan a ClickUp task, first create or reuse that task's branch/worktree with `optima_clickup_start_task`, then do Definition planning and local `.optima` mirror writes inside that task worktree.
+- Do not update the principal `dev` workspace `.optima/tasks/current.md` for ClickUp task planning.
+- Unrelated active tasks in `.optima/tasks/current.md` must not block planning; move to/create the correct task worktree instead.
+- Parent setup pulls remote once; after parent branch creation, subtasks can trust the parent local branch without continuous remote polling.
+- Branches: parent `<clickup-task-type>/<parent-task-id>`; subtask `<clickup-task-type>/<parent-task-id>/<subtask-id>`; PoC always `poc/<clickup-task-id>` and remains there unless a later productization task converts it.
+- PR targets: subtask -> parent branch, merged by Validator/QA after validation; parent -> `dev`, merged by Validator/QA only after Tech Lead + Validator/QA pass and `CTO`/`PO` move to `merge`; release -> `dev` to `main` only after explicit approval.
 - Preserve user work and unrelated dirty files. Stop and ask if unexpected changes appear.
 
 ## Operating Style
 
-- Orchestrate; do not silently implement specialist work yourself.
-- Delegate with explicit ClickUp task context, acceptance criteria, expected evidence, ClickUp comment/field sync requirements, branch target, Story Points handling, `Definition` link, final Documentation needs, and validation requirements.
-- On initial pickup, rewrite the ClickUp task description with the complete current description of what must be done; do not rely on a status comment as the task description.
-- At plan completion, rewrite the ClickUp task description again with the complete final plan/Definition of what must be done, distinct from the plan comment.
-- Estimate Story Points during `plan`, write them to ClickUp `Story Points`, and re-estimate whenever material plan changes alter scope or risk.
-- Before assigning `CTO`/`PO` or any other next owner, remove the PM assignee from the ClickUp task and verify no task remains assigned to Workflow/Product Manager unless explicitly re-queued.
-- Keep `.optima` mirrors updated for compatibility evidence until a future SCR removes local mirrors.
+- Orchestrate; do not silently implement specialist work yourself. Delegate with ClickUp context, AC, evidence, sync duties, branch target, Story Points, Definition link, final Documentation needs, and validation requirements.
+- Never abandon a PM-assigned task: keep working until unblocked and handed off, or post the stop/blocker/clarification/error as a ClickUp comment, remove Workflow/Product Manager, and assign `CTO` plus `PO` or next owner.
+- On pickup, rewrite the ClickUp task description with the complete current description of what must be done; do not rely on status comments.
+- At plan completion, rewrite the ClickUp task description again with the complete final plan/Definition, distinct from the plan comment.
+- Estimate Story Points during `plan`, write them to ClickUp `Story Points`, and re-estimate when material plan changes alter scope/risk.
+- Before assigning `CTO`/`PO` or any next owner, remove the PM assignee and verify no task remains assigned to Workflow/Product Manager unless explicitly re-queued.
 - Final handoffs must include Summary, Work Performed, AC Coverage, Documentation Impact, Open Risks, Recommended Next Step, verification results, and commit/PR status.
 
 <include:plugin:Agents_Common.md>

package/dist/index.js

@@ -8571,6 +8571,13 @@ function buildClickUpStartTaskPayload({ taskId, taskType = "Tarea", parentTaskId
     ok: true,
     mode: apply ? "apply-requested" : "payload",
     dryRun: true,
+    required_first_actions: [
+      "Create or reuse the task-specific branch/worktree before planning or writing local .optima mirrors.",
+      `Use branch ${branch} from dev and worktree ${worktree} for this task workspace.`,
+      "Write planning state, .optima/tasks/current.md, task mirrors, and evidence only inside the task worktree.",
+      "Do not update the principal dev workspace .optima/tasks/current.md for ClickUp task planning.",
+      "If another active task is present in current.md, move to or create this task worktree instead of stopping."
+    ],
     git: {
       startFrom: "dev",
       branch,
@@ -8580,6 +8587,9 @@ function buildClickUpStartTaskPayload({ taskId, taskType = "Tarea", parentTaskId
     mirror: {
       taskPath: `.optima/tasks/${branchSafeClickUpId(taskId || subtaskId || effectiveParent)}.md`,
       evidenceSummaryPath: `.optima/evidences/${branchSafeClickUpId(taskId || subtaskId || effectiveParent)}/SUMMARY.md`,
+      workspace: "task_worktree_only",
+      principalWorkspaceCurrentMd: "do_not_update",
+      currentMdConflictPolicy: "move_to_or_create_task_worktree",
       wouldCreate: true
     },
     clickup: {
@@ -9296,6 +9306,14 @@ function recordClickUpCommentVersionProcessed({ ledgerPath, key, taskId, eventTy
 function clickUpTaskIdFromPayload(payload = {}) {
   return String(payload.task_id || payload.taskId || payload.task?.id || payload.task?.task_id || "").trim();
 }
+function clickUpTaskName(task = {}) {
+  return String(task?.name || "").trim();
+}
+function formatClickUpSessionTitle({ taskId, payloadTask, task } = {}) {
+  const id = String(taskId || "").trim();
+  const name = clickUpTaskName(payloadTask) || clickUpTaskName(task) || "ClickUp PM";
+  return `[${id}]: ${name}`;
+}
 function clickUpEventType(payload = {}) {
   return String(payload.event || payload.event_type || payload.eventType || "").trim();
 }
@@ -9692,6 +9710,7 @@ async function routeClickUpWebhookEventUnlocked({ payload, config, state = {}, w
     const latestTask = await clickupClient.getTask(taskId);
     if (latestTask) task = latestTask;
   }
+  const sessionTitle = formatClickUpSessionTitle({ taskId, payloadTask: payload.task, task });
   const existingMetadata = clickUpTaskAgentMetadata(task, config.routing.metadataFieldId);
   const metadata = normalizeAgentMetadataJson(existingMetadata);
   const existingSessionId = getNestedMetadataValue(metadata, config.routing.metadataKey);
@@ -9699,7 +9718,7 @@ async function routeClickUpWebhookEventUnlocked({ payload, config, state = {}, w
   if (!existingSessionId) {
     let pendingSessionId = getNestedMetadataValue(metadata, clickUpPendingSessionKey(config.routing.metadataKey)) || state.pendingSessions?.[taskId];
     if (!pendingSessionId) {
-      pendingSessionId = await createSession(openCodeClient, { title: `ClickUp PM: ${taskId}`, directory: config.basePath, agent: config.routing.targetAgent });
+      pendingSessionId = await createSession(openCodeClient, { title: sessionTitle, directory: config.basePath, agent: config.routing.targetAgent });
       if (!String(pendingSessionId || "").startsWith("ses_")) return { ok: false, action: "error", reason: "session_create_failed", taskId };
       if (saveState) {
         saveState({

package/dist/sanitize_cli.js

@@ -8578,6 +8578,13 @@ function buildClickUpStartTaskPayload({ taskId, taskType = "Tarea", parentTaskId
     ok: true,
     mode: apply ? "apply-requested" : "payload",
     dryRun: true,
+    required_first_actions: [
+      "Create or reuse the task-specific branch/worktree before planning or writing local .optima mirrors.",
+      `Use branch ${branch} from dev and worktree ${worktree} for this task workspace.`,
+      "Write planning state, .optima/tasks/current.md, task mirrors, and evidence only inside the task worktree.",
+      "Do not update the principal dev workspace .optima/tasks/current.md for ClickUp task planning.",
+      "If another active task is present in current.md, move to or create this task worktree instead of stopping."
+    ],
     git: {
       startFrom: "dev",
       branch,
@@ -8587,6 +8594,9 @@ function buildClickUpStartTaskPayload({ taskId, taskType = "Tarea", parentTaskId
     mirror: {
       taskPath: `.optima/tasks/${branchSafeClickUpId(taskId || subtaskId || effectiveParent)}.md`,
       evidenceSummaryPath: `.optima/evidences/${branchSafeClickUpId(taskId || subtaskId || effectiveParent)}/SUMMARY.md`,
+      workspace: "task_worktree_only",
+      principalWorkspaceCurrentMd: "do_not_update",
+      currentMdConflictPolicy: "move_to_or_create_task_worktree",
       wouldCreate: true
     },
     clickup: {
@@ -9303,6 +9313,14 @@ function recordClickUpCommentVersionProcessed({ ledgerPath, key, taskId, eventTy
 function clickUpTaskIdFromPayload(payload = {}) {
   return String(payload.task_id || payload.taskId || payload.task?.id || payload.task?.task_id || "").trim();
 }
+function clickUpTaskName(task = {}) {
+  return String(task?.name || "").trim();
+}
+function formatClickUpSessionTitle({ taskId, payloadTask, task } = {}) {
+  const id = String(taskId || "").trim();
+  const name = clickUpTaskName(payloadTask) || clickUpTaskName(task) || "ClickUp PM";
+  return `[${id}]: ${name}`;
+}
 function clickUpEventType(payload = {}) {
   return String(payload.event || payload.event_type || payload.eventType || "").trim();
 }
@@ -9699,6 +9717,7 @@ async function routeClickUpWebhookEventUnlocked({ payload, config, state = {}, w
     const latestTask = await clickupClient.getTask(taskId);
     if (latestTask) task = latestTask;
   }
+  const sessionTitle = formatClickUpSessionTitle({ taskId, payloadTask: payload.task, task });
   const existingMetadata = clickUpTaskAgentMetadata(task, config.routing.metadataFieldId);
   const metadata = normalizeAgentMetadataJson(existingMetadata);
   const existingSessionId = getNestedMetadataValue(metadata, config.routing.metadataKey);
@@ -9706,7 +9725,7 @@ async function routeClickUpWebhookEventUnlocked({ payload, config, state = {}, w
   if (!existingSessionId) {
     let pendingSessionId = getNestedMetadataValue(metadata, clickUpPendingSessionKey(config.routing.metadataKey)) || state.pendingSessions?.[taskId];
     if (!pendingSessionId) {
-      pendingSessionId = await createSession(openCodeClient, { title: `ClickUp PM: ${taskId}`, directory: config.basePath, agent: config.routing.targetAgent });
+      pendingSessionId = await createSession(openCodeClient, { title: sessionTitle, directory: config.basePath, agent: config.routing.targetAgent });
       if (!String(pendingSessionId || "").startsWith("ses_")) return { ok: false, action: "error", reason: "session_create_failed", taskId };
       if (saveState) {
         saveState({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defend-tech/opencode-optima",
-  "version": "0.1.30",
+  "version": "0.1.32",
   "repository": {
     "type": "git",
     "url": "git+ssh://git@github.com/defend-tech/opencode-optima.git"