@defend-tech/opencode-optima 0.1.10

package/docs/product/FEATURES_LIST.md

@@ -0,0 +1,17 @@
+# Features List
+
+This document is the "Single Source of Truth" for all features implemented or planned.
+
+## 1. Core Features
+- **Plugin-Based Agent Installation:** [Status: Done]
+- **Product Manager Default Agent:** [Status: Done]
+- **Workflow Runner Session Orchestration:** [Status: Done]
+- **CodeMap Validation:** [Status: Done]
+- **Complexity-Based Task Routing (`tiny`, `standard`, `complex`):** [Status: In Progress]
+- **Standard Slice Model (`foundation`, `core`, `logic`, `ui`, `polish`, `qa`, `docs`):** [Status: In Progress]
+- **Plugin Onboarding Docs:** [Status: In Progress]
+
+## 2. Infrastructure
+- **Agent Orchestration Workflow:** [Status: Done]
+- **Task Management System:** [Status: Done]
+- **Shared-Worktree Limited Parallelism:** [Status: In Progress]

package/docs/product/PRODUCT_OVERVIEW.md

@@ -0,0 +1,12 @@
+# Product Overview
+
+*   **One-Liner:** Optima is an OpenCode plugin that installs the Optima Collective, an AI-native software development team with specialized delivery roles.
+*   **Target Audience:** Teams and solo builders who want AI agents to collaborate through explicit roles, task files, SCRs, and verification gates.
+*   **Problem Statement:** Default agent workflows are fast but often inconsistent because one assistant is expected to behave like an entire engineering organization. Optima solves that by introducing a structured AI software team with product, architecture, development, QA, review, and design roles that work through explicit artifacts and gated handoffs.
+
+## Design Principles
+- **Spec Before Delivery:** Significant changes should be grounded in approved SCRs and task artifacts.
+- **Right-Sized Process:** Tiny work should stay lightweight, while complex work gets full orchestration.
+- **Explicit Ownership:** Every task has a clear orchestrator, specialist handoff path, and verification gate.
+- **Navigable Repos:** CodeMaps and documentation should make the repository understandable to future agents.
+- **Team, Not Toolchain:** Optima should feel like an AI software company embedded in the repository, with clear roles and disciplined collaboration.

package/docs/product/codemap.yml

@@ -0,0 +1,6 @@
+scope: module
+parent: ../codemap.yml
+sources_of_truth:
+  - path: DOMAIN_MAP.md
+  - path: FEATURES_LIST.md
+  - path: PRODUCT_OVERVIEW.md

package/docs/setup/CONFIGURATION.md

@@ -0,0 +1,117 @@
+# Configuration
+
+Optima reads repository-local configuration from `.optima/.config/optima.yaml`.
+
+This file is typically created during the PMA-led repository setup flow.
+
+## Minimal config
+
+```yaml
+enabled: true
+team_mode: full
+
+defaults:
+  # provider: openai
+  # model: gpt-5.4
+
+features:
+  debug_dumps: true
+  codemap_verification: true
+
+policies:
+  extract_defaults: none
+
+agents:
+  product_manager:
+    enabled: true
+```
+
+## Top-level sections
+
+- `enabled`: Turns the Optima agent set on for the repository.
+- `team_mode`: The supported team preset. Use `mini` for PMA + BA + Tech Lead only, or `full` for the complete collective. If omitted in an existing repository, Optima defaults to `full`.
+- `defaults`: Shared defaults for providers, models, permissions, and other agent config fields.
+- `features`: Plugin feature flags such as debug dumps and validation behavior.
+- `policies`: Policy extraction controls for generated reference policy files.
+- `agents`: Per-agent enablement and config overrides from `optima.yaml`.
+
+## Supported team modes
+
+### `mini`
+
+- Enabled by default: `product_manager`, `business_analyst`, `tech_lead`
+- Intended for: `tiny` and `standard` tasks in simple repositories
+- Not supported: `complex` work and `workflow_runner`
+
+### `full`
+
+- Enables the full Optima Collective by default
+- Intended for: repositories that need the complete role set, including `workflow_runner`
+- Supports: `tiny`, `standard`, and `complex`
+
+## Common uses
+
+### Override a model for one agent
+
+```yaml
+agents:
+  developer:
+    provider: openai
+    model: gpt-5.4
+```
+
+### Disable an optional agent in a repo
+
+```yaml
+agents:
+  ui_ux_designer:
+    enabled: false
+```
+
+Mandatory agents cannot be disabled:
+
+- `product_manager`
+- `business_analyst`
+- `tech_lead`
+
+### Extend agent tools
+
+```yaml
+agents:
+  workflow_runner:
+    tools_add:
+      - optima_validate
+```
+
+### Generate bundled policy references
+
+```yaml
+policies:
+  extract_defaults: all
+```
+
+This writes the bundled default policy files to `.optima/.config/generated/policies/` for reference. Those generated files are not used directly at runtime. To customize one, copy it into `.optima/policies/` and edit the copy.
+
+### Add repository-specific agent instructions
+
+Create `.optima/agent-additions/<agent>.md` to append repository-specific instructions to a bundled or custom agent prompt.
+
+### Add repository-local agents or override a bundled base prompt
+
+Create `.optima/agents/<agent>.md` to:
+
+- replace the bundled base prompt for an existing agent, or
+- define a brand new custom repository agent
+
+## Operational notes
+
+- The `product_manager` agent becomes the default primary agent when Optima is enabled.
+- Repository-local full agent definitions can live in `.optima/agents/`.
+- Repository-local additive agent instructions can live in `.optima/agent-additions/`.
+- Repository-local policy overrides can live in `.optima/policies/`.
+- Generated reference policy files are written to `.optima/.config/generated/policies/` when `policies.extract_defaults` is set to `all`.
+- Final agent prompts are dumped to `.optima/.config/generated/agents/` when `features.debug_dumps` is enabled.
+
+## Feature flags
+
+- `features.keep_builtin_agents`: when `true`, Optima will not disable agents that OpenCode already registered, including built-in agents such as `build`, `plan`, `general`, and `explore`. Optima will still set `product_manager` as the default agent.

package/docs/setup/INSTALLATION.md

@@ -0,0 +1,66 @@
+# Installation
+
+## 1. Install the package
+
+Add the Optima plugin package to the environment where OpenCode resolves plugins.
+
+```json
+{
+  "plugin": ["@defend-tech/opencode-optima"]
+}
+```
+
+OpenCode's config schema allows plugin entries to be strings or `[package, options]` tuples. Use the form that matches your broader OpenCode setup.
+
+## 2. Add the plugin to OpenCode config
+
+Add Optima to your OpenCode configuration file and restart OpenCode so the plugin is loaded.
+
+Minimal example:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@defend-tech/opencode-optima"]
+}
+```
+
+## 3. Start with PMA
+
+After the plugin loads, open the repository you want to enable and start talking to the `product_manager` agent (PMA).
+
+PMA is the default orchestrator and will help you set up the repository for Optima. If the repository has not been initialized yet, PMA can trigger the required setup flow on your behalf.
+
+During setup, PMA should ask whether you want:
+
+- `mini` team mode for simple repositories and `tiny` / `standard` work
+- `full` team mode for the complete collective, including `complex` workflows
+
+You do not need to manually run Optima initialization commands as a first step.
+
+## 4. Repository initialization artifacts
+
+When PMA initializes the repository, Optima creates these artifacts and, in git repositories, ensures `.gitignore` protects Optima local/private state:
+
+- `.optima/.config/optima.yaml`
+- `.optima/policies/README.md`
+- `.optima/agents/README.md`
+- `.optima/agent-additions/README.md`
+- `.optima/.config/generated/agents/README.md`
+- `.optima/.config/generated/policies/README.md`
+- `.optima/codemap.yml`
+- `.optima/tasks/current.md`
+- `.optima/tasks/done.md`
+- `.optima/docs/scrs/current.md`
+- `.optima/docs/scrs/done.md`
+- `.gitignore` rules for `.optima/.config/` and Optima env/secret/token/credential patterns, if the target is a git repository
+
+## 5. Configure Optima
+
+Edit `.optima/.config/optima.yaml` to set defaults, features, policy extraction behavior, and per-agent config overrides. Use `.optima/agents/` for full repository-local agent definitions or custom agents, and `.optima/agent-additions/` for additive repo-specific agent instructions.
+
+See:
+
+- `docs/setup/CONFIGURATION.md`
+- `docs/guides/AGENTS.md`
+- `docs/guides/WORKFLOW.md`

package/docs/setup/RELEASING.md

@@ -0,0 +1,101 @@
+# Releasing
+
+Optima publishes to npm as `@defend-tech/opencode-optima`.
+
+## Release Model
+
+- Versioning, build verification, and npm publishing are handled by the GitHub Actions workflow `Release npm package`.
+- Pushes to `dev` automatically publish npm prereleases.
+- Pushes to `main` automatically publish stable npm releases.
+- GitHub Actions publishes through npm Trusted Publishing with provenance enabled.
+- The workflow does not commit or tag version changes back to the repository. It derives the publish version from `package.json` and npm's already-published versions.
+
+## Trusted Publishing Setup
+
+Configure npm Trusted Publishing for this GitHub repository before relying on CI publishes.
+
+At a minimum, npm must trust this repository's GitHub Actions workflow as a publisher for `@defend-tech/opencode-optima`.
+
+Expected setup:
+
+1. Open the npm package settings for `@defend-tech/opencode-optima`.
+2. Configure a Trusted Publisher for this GitHub repository.
+3. Allow GitHub Actions from this repository to publish the package.
+
+Critical npm-side details:
+
+- GitHub organization or user: `defend-tech`
+- Repository: `opencode-optima`
+- Workflow filename: `release.yml`
+- If you use an optional environment in npm's Trusted Publisher settings, it must exactly match the GitHub Actions environment name used by the workflow.
+- `package.json` must include a `repository.url` that exactly matches `git+ssh://git@github.com/defend-tech/opencode-optima.git`.
+- GitHub Actions must run on a supported Node.js version for npm Trusted Publishing. This workflow uses Node.js `24`.
+
+No `NPM_TOKEN` repository secret is required once Trusted Publishing is configured correctly.
+
+## Workflow Behavior
+
+The release workflow performs these steps:
+
+1. Triggers automatically on pushes to `dev` and `main`.
+2. Installs dependencies with `npm ci`.
+3. Runs `npm run release:check`, which executes tests, builds `dist/`, and previews the publish tarball.
+4. Resolves the publish version based on the current branch and npm registry history.
+5. Applies that version locally with `npm version --no-git-tag-version`.
+6. Publishes the package with `npm publish --provenance` using npm Trusted Publishing.
+
+## Branch Behavior
+
+### `dev`
+
+- Publishes prereleases using the `rc` dist-tag.
+- Reads the stable base version from `package.json`.
+- Looks up already published versions on npm.
+- Publishes the next version in the sequence: `<package.json version>-rc.N`
+
+Example:
+
+- `package.json`: `1.4.0`
+- published prereleases: `1.4.0-rc.0`, `1.4.0-rc.1`
+- next `dev` publish: `1.4.0-rc.2`
+
+### `main`
+
+- Publishes stable releases using the default `latest` dist-tag.
+- Publishes the exact stable version in `package.json`.
+- Skips publishing if that version already exists on npm.
+
+Example:
+
+- `package.json`: `1.4.0`
+- push to `main`
+- publish: `1.4.0`
+
+## Versioning Expectations
+
+- Keep `package.json` on a stable semver base such as `1.4.0`.
+- Do not commit prerelease versions like `1.4.0-rc.2` into `package.json`.
+- Use `dev` to publish release candidates for the current base version.
+- When the package is ready, merge the versioned changes to `main` to publish the stable release.
+
+## Local Verification
+
+Before triggering a release, you can run the same verification locally:
+
+```bash
+npm run release:check
+```
+
+This command:
+
+- runs the test suite
+- builds `dist/`
+- runs `npm pack --dry-run` to preview the package contents
+
+## Notes
+
+- `prepack` runs `npm run build`, so local `npm pack` and `npm publish` always include a fresh `dist/` build.
+- `publishConfig.access` is set to `public` so the scoped package can publish correctly on npm.
+- The prerelease counter is remembered via npm registry history, not via git tags or committed prerelease versions.
+- CI publishing depends on npm Trusted Publishing plus the workflow permission `id-token: write`.
+- If you need to dry-run a release locally without publishing, use `npm run release:check` and inspect the tarball preview output.

package/docs/setup/codemap.yml

@@ -0,0 +1,6 @@
+scope: module
+parent: ../codemap.yml
+sources_of_truth:
+  - path: CONFIGURATION.md
+  - path: INSTALLATION.md
+  - path: RELEASING.md

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@defend-tech/opencode-optima",
+  "version": "0.1.10",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/defend-tech/opencode-optima.git"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "optima-sanitize-host": "dist/sanitize_cli.js"
+  },
+  "opencode": {
+    "server": "default"
+  },
+  "scripts": {
+    "sanitize:host": "node scripts/optima-sanitize-host.js",
+    "build": "node scripts/build.js",
+    "prepack": "npm run build",
+    "release:check": "npm test && npm run build && npm pack --dry-run",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "agents",
+    "docs",
+    "policies",
+    "templates",
+    "scripts/optima-sanitize-host.js",
+    "Agents_Common.md",
+    "Agents_Common.prompt.md"
+  ],
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.2.6",
+    "ignore": "^5.3.2",
+    "yaml": "^2.3.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.0",
+    "@types/node": "^20.0.0",
+    "jest": "^30.2.0",
+    "typescript": "^5.0.0"
+  }
+}

package/scripts/optima-sanitize-host.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const sourceCli = path.join(scriptDir, "..", "src", "sanitize_cli.js");
+const distCli = path.join(scriptDir, "..", "dist", "sanitize_cli.js");
+const cliPath = fs.existsSync(sourceCli) ? sourceCli : distCli;
+const { main } = await import(cliPath);
+
+process.exitCode = await main();

package/templates/codemap.yml.template

@@ -0,0 +1,30 @@
+scope: repo
+name: {{projectName}}
+purpose: >
+  Repository navigation index. Points to current-state
+  product specs, process docs, and module entrypoints.
+
+code_roots:
+  - src/
+  - agents/
+  - docs/
+
+links:
+  - title: Global Context
+    path: Agents_Common.md
+    summary: "Core rules and agent roles."
+
+  - title: Orchestration Strategy
+    path: docs/core/agent_orchestration.md
+    summary: "Collaboration and handoff protocols."
+
+  - title: Technical Architecture
+    path: docs/architecture/TECHNICAL_ARCHITECTURE.md
+    summary: "Global patterns and tech stack."
+
+entrypoints: []
+commands:
+  test: "echo 'No global test command defined'"
+  lint: "echo 'No global lint command defined'"
+
+modules: []

package/templates/optima.yaml.template

@@ -0,0 +1,68 @@
+# Optima repository configuration
+enabled: true
+team_mode: {{teamMode}}
+
+defaults:
+  # provider: openai
+  # model: gpt-5.4
+  # temperature: 0.2
+  # permissions: allow
+
+features:
+  debug_dumps: true # Dumps final agent configs to .optima/.config/generated/agents/ for verification
+  # debug_logs: false # Enable detailed console logging for the plugin
+  # keep_builtin_agents: false # If true, do not disable agents OpenCode already registered, including built-ins
+  codemap_verification: true
+
+policies:
+  extract_defaults: none # Set to 'all' to write bundled policy defaults to .optima/.config/generated/policies/
+
+workflow:
+  source_of_truth: clickup # ClickUp Docs/tasks are primary; .optima remains a local compatibility mirror
+  local_mirror: true # Keep .optima/tasks, .optima/docs/scrs, and .optima/evidences synchronized for agents/tests
+  actors:
+    cto: CTO
+    product_owner: PO
+    workflow_product_manager: workflow_product_manager
+  clickup:
+    statuses:
+      backlog: ignore
+      plan: plan
+      in progress: execute
+      validation: validate
+      merge: merge # Parent-task approval by CTO/PO after Tech Lead + Validator/QA pass; subtasks merge after Validator/QA validation
+      completed: ignore
+      Closed: ignore
+    delivery_task_types:
+      - Tarea
+      - Bug
+      - Doc
+      - PoC
+    ignored_task_types:
+      - Idea # Non-delivery; legacy ClickUp task type "Backlog" normalizes to Idea
+      - Backlog # Legacy alias for Idea
+      - Hito
+      - Nota de reunión
+      - Respuesta del formulario
+    custom_fields:
+      definition: Definition # Plan contract URL when native task-doc association is unavailable
+      story_points: Story Points # WPM estimates during plan and re-estimates on material plan changes
+      agent_metadata: agent_metadata # JSON session IDs per agent/type/task/subtask
+    running_label: Running # Optional webhook mode uses local runtime state; enable only through explicit OpenCode ClickUp webhook config
+    final_approval_roles:
+      - CTO
+      - PO
+  github:
+    remote: origin
+    main_branch: main
+    dev_branch: dev
+    worktree_root: ../worktrees # Parent directory for task-specific delivery worktrees
+    parent_branch_format: "<clickup-task-type>/<parent-task-id>"
+    subtask_branch_format: "<clickup-task-type>/<parent-task-id>/<subtask-id>"
+    poc_branch_format: "poc/<clickup-task-id>" # PoC branches persist and do not merge unless later productized
+    pr_targets:
+      subtask: parent_branch
+      parent: dev
+      release: main
+
+agents: