Optima

ClickUp-first delivery automation for OpenCode teams.

Optima is an OpenCode plugin that turns a repository into a coordinated delivery system: ClickUp is the source of truth, OpenCode sessions do the work, GitHub PRs carry validation, Vercel previews prove deployability, and .optima artifacts keep the evidence trail on disk.

The plugin installs the Optima Collective, a role-based agent team with Product Manager, Workflow Product Manager, Coder, QA, Tech Lead, architecture, analysis, and design roles. In webhook mode the only direct ClickUp runtime entrypoint is workflow_product_manager; it reuses the stored task session, routes specialists, updates task metadata, and keeps runtime/process failures in local logs instead of polluting ClickUp comments.

What Optima Does

• Registers OpenCode agents from bundled prompts plus repo-local .optima overrides and additions.
• Starts a signed ClickUp webhook listener and routes only eligible PM-assigned task/comment events.
• Creates or reuses task-specific branches, worktrees, and OpenCode sessions.
• Stores session/worktree/PR/QA state in ClickUp agent_metadata.
• Uses GitHub App authentication for PRs, comments, reviews, merges, and API commits so humans can approve the bot's work.
• Verifies Vercel PR deployments before parent-task validation handoff.
• Provides a serialized shared QA browser queue for authenticated ChatGPT / extension validation.
• Preserves OpenCode sessions and keeps merged branches/worktrees while ClickUp is completed; cleanup and session archiving run when it moves to Closed.

Install

Add the plugin to the OpenCode config used by the service that will run the agents:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@defend-tech/opencode-optima"]
}

For long-running server deployments, make sure OpenCode is launched with the intended config directory. For example:

OPENCODE_CONFIG_DIR=/home/staticduo/.config/opencode_defend \
opencode serve --port 3001 --hostname 0.0.0.0

See Installation and Configuration for the full runtime setup.

Repository Setup

Optima reads repository-local configuration from .optima/.config/optima.yaml. The PMA setup flow or optima_init can create the base scaffold:

• .optima/.config/optima.yaml
• .optima/codemap.yml
• .optima/tasks/current.md
• .optima/tasks/done.md
• .optima/docs/scrs/current.md
• .optima/docs/scrs/done.md
• .optima/policies/
• .optima/agents/
• .optima/agent-additions/

Use .optima/agent-additions/<agent>.md for normal repo-specific guidance. Use .optima/agents/<agent>.md only when you intentionally want a full local agent override or a custom agent.

ClickUp-First Workflow

In production mode, ClickUp owns task state and .optima owns local evidence.

The high-level flow is:

1. A ClickUp assignment/status/comment webhook wakes the stored workflow_product_manager session.
2. Optima verifies webhook signature, deduplicates the event, checks task type and status, provisions the correct worktree, and admits a prompt into the existing OpenCode session.
3. The agent plans, implements, delegates specialists, writes evidence under the task worktree, and updates ClickUp through model-owned comments and metadata.
4. The task enters Validation only after the required GitHub PR exists.
5. Parent tasks require a functional Vercel URL, GitHub PR URL, and extension install URL in the optima_finish validation handoff.
6. Human approval on the parent PR triggers merge automation, preproduction verification, cleanup, and final ClickUp completion.

Optima runtime code must not write operational noise to ClickUp comments. Webhook failures, launch failures, startup reconciliation, probe output, and queue diagnostics go to local logs. Human-facing ClickUp comments are produced by the model, normally through optima_finish.

Parent And Subtask Flow

Parent tasks may be split into ClickUp subtasks owned by Defend Product Manager. Subtasks are internal delivery units and should not be assigned to humans except for a true external blocker such as missing credentials or human login access.

• Parent branch: <type>/<parent-id>
• Subtask branch: <type>/<parent-id>-subtask-<subtask-id>
• Subtask PR target: parent task branch
• Parent PR target: dev

Subtasks plan, implement, test, and validate with unit/integration/quality evidence. Shared-browser E2E is reserved for the parent final QA after all subtasks are merged and the parent scope/acceptance coverage has been checked.

Validation, PRs, And Vercel

Validation is a PR-backed state.

• Subtasks open or update a PR into the parent branch.
• Parent tasks open or update a PR into dev.
• Commits for delivery branches should use optima_github_commit_worktree so GitHub attributes them to the Optima App/bot and humans can approve the PR.
• Parent-task validation must call optima_github_verify_vercel_pr.
• A parent task cannot be handed to human validation unless Vercel has a functional environment URL.
• optima_finish requires these fields for parent validation handoff: vercel_url, github_pr_url, and extension_install_url.

The ClickUp validation comment always includes:

URL Entorno Vercel: <url>
Github PR url: <url>
URL para instalar la extensión de ese entorno: <url>

QA Browser Queue

Optima provides one shared QA browser slot per configured provider. This is used for authenticated browser flows such as ChatGPT plus the Defend extension.

• Request a slot with optima_qa_request_slot.
• If another task owns it, Optima queues the requester and wakes its stored OpenCode session later.
• If Chrome/CDP is unhealthy, the slot is not denied; the current owner must repair or restart the QA browser and continue in the same session.
• Run browser actions through optima_qa_chrome_command.
• Release the slot with optima_qa_finish when the browser is no longer needed.
• End the task turn separately with optima_finish.

Tab 0 is reserved for persistent provider login. Task QA uses separate tabs and the extension state is reset/reloaded between tasks without clearing the provider login session.

Important Tools

Core repository tools:

• optima_init
• optima_validate
• optima_repair

OpenCode/session tools:

• optima_session_create
• optima_session_prompt
• optima_session_messages
• optima_session_probe

ClickUp workflow tools:

• optima_finish
• optima_clickup_claim_task
• optima_clickup_sync_summary
• optima_clickup_start_task
• optima_clickup_transition
• optima_clickup_create_subtasks
• optima_clickup_apply_payload

QA browser tools:

• optima_qa_browser_status
• optima_qa_request_slot
• optima_qa_chrome_command
• optima_qa_finish

GitHub tools:

• optima_github_auth_mode
• optima_github_commit_worktree
• optima_github_create_pr
• optima_github_comment_pr
• optima_github_reply_review_comment
• optima_github_review_pr
• optima_github_verify_vercel_pr
• optima_github_merge_pr
• optima_git_cleanup_merged_worktree

For argument-level reference, see Plugin Tools.

Documentation

• Project Summary And Operations Handbook
• Installation
• Configuration
• Releasing
• Workflow Agents
• Workflow Model
• Plugin Tools
• Task Model
• Agent Orchestration
• Documentation Structure

Release

Optima ships as @defend-tech/opencode-optima.

npm ci
npm run release:check

npm run release:check runs tests, builds dist/, and previews the npm package. Publishing is local and explicit: use the ignored .npmjs only with permissions 0600, require npm --userconfig .npmjs whoami to return exactly defend-tech, then follow Releasing. GitHub Actions does not publish Optima and there is no automatic RC publishing.