@defend-tech/opencode-optima 0.1.83 → 0.1.85

package/docs/core/task_model.md

@@ -22,6 +22,7 @@
 - **Parent planning questions:** only a parent task in `plan` may assign `CTO`/`PO`, and only after clear, concrete questions have been posted in ClickUp comments. Subtasks are planned and executed end-to-end without CTO/PO planning assignment.
 - **Real in-progress blocker:** a task in `in progress` may assign/escalate to `CTO`/`PO` only when blocked by missing credentials, permissions, authenticated browser/Agent Jake access, external tools, or live third-party access after local/subagent attempts are exhausted. Escalation means calling `optima_finish` with a concrete ClickUp help request in castellano explaining exactly what is needed; Optima assigns CTO/PO and removes the Product Manager assignee so watchdogs stop re-queueing PM until a human replies/reassigns. Agents must not stop at informal phase boundaries such as "I reached phase 1"; phases should have been subtasks, otherwise finish the accepted task.
 - **Temporary human-requested PM ownership:** when a human asks Product Manager to take a task back and test/fix it, the task may be PM-assigned only for that execution attempt. After trying the requested work, if anything still needs human help, access, login, approval, or validation, the agent must call `optima_finish` and let Optima assign CTO/PO and remove Product Manager. Human-requested PM reassignment is not permission to keep the task assigned to PM while waiting.
+- **Shared browser QA slot:** Playwright/Chrome QA against shared persistent providers such as ChatGPT is serialized. Agents must request `optima_qa_request_slot` before using the browser; if queued they stop, let Optima set `waiting QA slot` and remove Product Manager, and wait for the stored session wakeup. Active holders use `optima_qa_chrome_command`, keep tab 0 untouched, call `optima_qa_finish` at completion, and keep the slot alive with activity at least every 5 minutes.
 - **Parent validation approval:** only a parent task in `validation` may assign `CTO`/`PO` for final validation, and only after `optima_github_verify_vercel_pr` returns `ready: true` for the current parent PR with a functional Vercel preproduction/preview URL. After a human comments `Approved`, automation reassigns to itself or the merge owner, removes human assignees, merges, cleans workspaces/worktrees/branches, pushes to `dev`, and ensures the dev/preproduction environment contains the code.
 
 ## Routing Rules

package/docs/core/task_model.prompt.md

@@ -8,7 +8,7 @@
 - Product Manager without workflow never develops; it may pre-estimate "a qué huele" small/medium/large plus rough story points and route development into ClickUp tasks.
 - Human role registry: resolve `CTO` and `PO` from available human role context/configured ClickUp IDs. Missing repo-local human registry files are internal routing detail; do not mention internal role-resolution details in ClickUp comments unless asked for routing diagnostics.
 - Final task handoffs must use `optima_finish` when available; Optima applies final status, comment, and assignments.
-- ClickUp-first actions: `backlog` ignore, `plan` plan with `Story Points`, `Definition`, and test strategy; assign `CTO`/`PO` only for parent planning questions with clear ClickUp comments, real `in progress` blockers caused by missing credentials/tools/access/authenticated browser or Agent Jake/live third-party access after local/subagent attempts, or parent `validation` after `optima_github_verify_vercel_pr` returns `ready: true` with a functional Vercel URL. If a human asks Product Manager to take a task back and test/fix it, that assignment is temporary: after the requested attempt, any remaining human help, access, login, approval, or validation must go through `optima_finish` with PM removal. For true external `in progress` blockers, call `optima_finish` with a concrete castellano ClickUp help request explaining exactly what is needed; Optima assigns CTO/PO and removes Product Manager so PM watchdogs stop looping until a human replies/reassigns. Subtasks execute end-to-end and merge to the parent branch after Validator/QA passes without CTO/PO approval; parent `Approved` comments trigger automation to remove humans, assign merge owner/self, merge to `dev`, clean workspaces/worktrees/branches, push, and ensure dev/preproduction receives the code; `completed`/`Closed` ignore unless reopened.
+- ClickUp-first actions: `backlog` ignore, `plan` plan with `Story Points`, `Definition`, and test strategy; assign `CTO`/`PO` only for parent planning questions with clear ClickUp comments, real `in progress` blockers caused by missing credentials/tools/access/authenticated browser or Agent Jake/live third-party access after local/subagent attempts, or parent `validation` after `optima_github_verify_vercel_pr` returns `ready: true` with a functional Vercel URL. Shared browser QA is serialized: request `optima_qa_request_slot`, stop if queued, use `optima_qa_chrome_command` only while active, keep tab 0 untouched, and call `optima_qa_finish` when done. If a human asks Product Manager to take a task back and test/fix it, that assignment is temporary: after the requested attempt, any remaining human help, access, login, approval, or validation must go through `optima_finish` with PM removal. For true external `in progress` blockers, call `optima_finish` with a concrete castellano ClickUp help request explaining exactly what is needed; Optima assigns CTO/PO and removes Product Manager so PM watchdogs stop looping until a human replies/reassigns. Subtasks execute end-to-end and merge to the parent branch after Validator/QA passes without CTO/PO approval; parent `Approved` comments trigger automation to remove humans, assign merge owner/self, merge to `dev`, clean workspaces/worktrees/branches, push, and ensure dev/preproduction receives the code; `completed`/`Closed` ignore unless reopened.
 - Routing: keep `tiny` to one slice and usually one specialist; keep `standard` bounded; decompose `complex` into slice-based subtasks.
 - `complex + implementation` normally uses `workflow_runner` in full mode.
 - WPM stores `agent_metadata`, re-estimates `Story Points` on material plan changes, and keeps `Definition` plan contract separate from final Documentation.

package/docs/guides/TOOLS.md

@@ -188,6 +188,56 @@ Arguments:
 - `omit_agent_on_prompt`: set to `true` to omit the agent field from the prompt body
 - `text`: optional marker text to send
 
+## Shared QA Browser Tools
+
+These tools serialize real browser QA against a persistent Chrome instance, primarily for authenticated ChatGPT validation. Only one ClickUp task may own the QA slot at a time. Chrome tab 0 is reserved for the persistent login session and must never be used for task QA.
+
+### `optima_qa_request_slot`
+
+Requests the exclusive QA browser slot for a ClickUp task.
+
+Arguments:
+
+- `clickup_task_id`: ClickUp task id requesting QA
+- `provider`: optional provider, defaults to `chatgpt`
+- `session_id`: optional OpenCode session id to wake when a queued task is promoted
+- `worktree`: optional task worktree/directory for the wake prompt
+- `reason`: optional short QA scenario
+
+If the slot is free, Optima grants it and the agent must call `optima_qa_chrome_command` within 5 minutes. If another task is active, Optima queues the requester, marks the ClickUp task `waiting QA slot`, removes Product Manager assignment, and wakes the stored session when the slot becomes available.
+
+### `optima_qa_chrome_command`
+
+Runs one generic Playwright/CDP command against the QA tab owned by the active ClickUp task. Optima creates or reuses a task-specific tab and never uses tab 0.
+
+Arguments:
+
+- `clickup_task_id`: ClickUp task id that owns the slot
+- `provider`: optional provider, defaults to `chatgpt`
+- `command_json`: JSON command object or raw async JavaScript
+- `cdp_url`: optional Chrome DevTools URL
+- `start_url`: optional initial URL for a new QA tab
+
+Supported JSON actions: `status`, `goto`, `evaluate`, `screenshot`, `set_input_files`, and `script`. Every successful call renews the 5 minute lease.
+
+### `optima_qa_finish`
+
+Finishes the current QA slot, resets/reloads extension state, releases the slot, and promotes the next queued task if present.
+
+Arguments:
+
+- `clickup_task_id`: ClickUp task id finishing QA
+- `provider`: optional provider, defaults to `chatgpt`
+- `cdp_url`: optional Chrome DevTools URL
+- `extension_path`: optional extension source path to sync into the stable QA extension directory before reset/reload
+- `extension_id`: optional Chrome extension id
+- `reset_extension`: defaults to `true`
+- `reload_extension`: defaults to `true`
+
+### `optima_qa_browser_status`
+
+Shows current queue state, active lease, browser tabs, and extension service workers for diagnostics.
+
 ## 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.

package/docs/setup/CONFIGURATION.md

@@ -107,6 +107,17 @@ Create `.optima/agents/<agent>.md` to:
 
 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.
 
+### Configure the shared QA browser
+
+```yaml
+qa:
+  provider: chatgpt
+  cdp_url: http://127.0.0.1:9222
+  lease_ms: 300000
+```
+
+The QA browser tools use this Chrome DevTools URL to connect to a persistent Chrome session. Tab 0 keeps the authenticated provider session alive; task QA runs in separate task-owned tabs and the slot lease is renewed by `optima_qa_chrome_command`.
+
 ## 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.83",
+  "version": "0.1.85",
   "repository": {
     "type": "git",
     "url": "git+ssh://git@github.com/defend-tech/opencode-optima.git"
@@ -35,11 +35,12 @@
   "dependencies": {
     "@opencode-ai/plugin": "^1.2.6",
     "ignore": "^5.3.2",
+    "playwright-core": "^1.61.1",
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "esbuild": "^0.25.0",
     "@types/node": "^20.0.0",
+    "esbuild": "^0.25.0",
     "jest": "^30.2.0",
     "typescript": "^5.0.0"
   }