@defend-tech/opencode-optima 0.1.10

package/docs/architecture/TECHNICAL_ARCHITECTURE.md

@@ -0,0 +1,21 @@
+# Technical Architecture
+
+This document defines the global patterns and technical strategy for this project.
+
+## Global Patterns
+- **Orchestrated Subagent Workflow:** Using Product Manager as central coordinator.
+- **File-Based Task Management:** All work is tracked in the `tasks/` directory.
+- **Complexity-Based Routing:** The workflow weight is determined by task complexity: `tiny`, `standard`, or `complex`.
+- **Slice-Based Decomposition:** Complex work is decomposed into `foundation`, `core`, `logic`, `ui`, `polish`, `qa`, and `docs` slices.
+- **Shared-Worktree Concurrency Guard:** Only one implementation workflow may own the shared worktree at a time.
+
+## Tech Stack
+- **Runtime:** Node.js with ECMAScript modules
+- **Plugin SDK:** `@opencode-ai/plugin`
+- **Configuration Format:** YAML for Optima config and CodeMaps
+- **Tests:** Jest
+
+## Architectural Patterns
+- **Feature-First Organization:** Code and documentation are grouped by feature.
+- **Prompt-Driven Agent Composition:** Agents are defined as markdown prompts with frontmatter and reusable includes.
+- **Tool-Supervised Orchestration:** The plugin supervises session creation, agent registration, and workflow handoff tools.

package/docs/architecture/codemap.yml

@@ -0,0 +1,4 @@
+scope: module
+parent: ../codemap.yml
+sources_of_truth:
+  - path: TECHNICAL_ARCHITECTURE.md

package/docs/codemap.yml

@@ -0,0 +1,12 @@
+scope: module
+parent: ../.optima/codemap.yml
+modules:
+  - path: architecture
+  - path: core
+  - path: domains
+  - path: features
+  - path: guides
+  - path: product
+  - path: setup
+sources_of_truth: []
+internals: []

package/docs/core/agent_orchestration.md

@@ -0,0 +1,62 @@
+# Agent Orchestration
+
+- PMA is sole orchestrator; subagents execute PMA-delegated task files and do not self-initiate workflow work.
+- Dual PM model: `workflow_product_manager` owns ClickUp-first operational delivery, while `product_manager` remains product/planning support and compatibility/default PMA; without workflow, `product_manager` never develops and converts development asks into ClickUp tasks.
+- ClickUp Docs and tasks are the source of truth in ClickUp-first mode; `.optima` task/SCR/evidence files are local compatibility mirrors plus evidence/log containers until a future SCR changes that.
+- Agents must use the ClickUp skill and ClickUp MCP/tools for ClickUp reads, writes, comments, field updates, status transitions, assignments, and dashboards.
+- Human-readable task/evidence summaries, validation results, AC coverage, documentation impact, blockers, reopen history, status-transition rationale, and final handoffs must be synced to linked ClickUp task/subtask comments or fields.
+- Raw logs stay in evidence storage; ClickUp receives concise summaries, paths/links, or relevant excerpts only, never wholesale raw logs.
+- Registries: `.optima/tasks/current.md` tracks Active Discussions, Active, Todo, Blocked; `.optima/tasks/done.md` records completed tasks, SCRs, commits, and summaries.
+- Task files follow `.optima/tasks/task-template.md` and normally stay under `.optima/tasks/todo/` while active through registry status.
+- Routing is defined in `docs/core/task_model.md`: `tiny` stays lightweight, `standard` bounded, `complex` decomposed; complex implementation generally uses `workflow_runner`.
+
+## Two-Phase Flow
+
+- Negotiation: requirement discovery -> PMA/BA/Tech Lead sync -> SCR in `.optima/docs/scrs/` when behavior/spec changes -> PO iteration/approval -> SCR becomes truth anchor.
+- Delegated implementation: PMA activates one task, runs pre-task sync, delegates execution, verifies evidence in post-task sync, finalizes docs/registries, authorizes commit/archive, then starts the next task.
+- PMA and Technical Architect map impact surface and slice complex work into micro-tasks.
+- A task is complete only after implementation, verification, documentation closure, registry updates, and authorized finalization are done.
+
+## ClickUp-First Flow
+
+- `product_manager` may answer, investigate, operate dashboards, and pre-estimate "a qué huele" small/medium/large plus rough story points; WPM owns delivery routing.
+- Supported delivery task types are `Tarea`, `Bug`, `Doc`, and `PoC`; ignore `Idea`, legacy `Backlog` alias, `Hito`, `Nota de reunión`, and `Respuesta del formulario` unless converted or linked to delivery work.
+- Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md`; use role identifiers in workflow text and automation config.
+- Status actions are deterministic: `backlog` ignore, `plan` plan plus `Story Points`, test strategy, `Definition`, and `CTO`/`PO` assignment, `in progress` execute, `validation` split Tech Lead and Validator/QA gates, `merge` parent approval state after `CTO`/`PO` move a validated parent task there, and `completed`/`Closed` ignore unless reopened.
+- Store ClickUp `agent_metadata` JSON with session IDs per agent/type/task/subtask; keep `Definition` as the plan contract and final Documentation as delivered behavior docs.
+- `workflow_product_manager` is registered only when explicit ClickUp webhook mode is configured and the local webhook subscription state is active/valid.
+- Webhook mode is opt-in: Optima validates signed `X-Signature` HMAC SHA-256 requests, routes status/assignee events only for Product Manager-assigned non-terminal tasks, routes comments only when they mention `@Defend Tech Product Manager`, stores new `ses_...` ids in ClickUp `agent_metadata`, and reports stale/missing sessions to ClickUp without creating replacements.
+- The listener is a gated in-process HTTP listener for local runtime use; deployments still need a stable public URL/tunnel and local `.optima/.config/runtime/` state containing the ClickUp webhook id/secret. When a ClickUp client exposes webhook validation, Optima validates remote state; otherwise local-only validation is limited to ignored runtime state with matching URL/events and present id/secret.
+
+## Shared Worktree And Git
+
+- Only one shared-worktree `implementation` task may be active.
+- ClickUp-first delivery should use task-specific worktrees/branches; the principal workspace must remain on `dev` and never on `main`.
+- Parent task start pulls remote once; after branch creation, subtasks trust the parent local branch instead of continuous remote polling.
+- Parent branch format is `<clickup-task-type>/<parent-task-id>`; subtask branch format is `<clickup-task-type>/<parent-task-id>/<subtask-id>`; PoC branch format is always `poc/<clickup-task-id>` and stays there until a later productization task.
+- Subtask PRs target the parent branch, parent task PRs target `dev`, and release PRs target `main` from `dev` only after explicit approval.
+- After successful subtask validation, Validator/QA merges the subtask PR into the parent branch/workspace without `CTO`/`PO` approval.
+- After parent Tech Lead and Validator/QA validation passes, the parent task stays in `validation`, `CTO`/`PO` are assigned and marked as approval owners, and they approve by moving it to `merge`; only then does Validator/QA attempt the parent PR merge into `dev`.
+- If any subtask or parent merge conflicts or fails, Validator/QA returns the affected ClickUp item to `in progress` and routes it to the coding owner.
+- Never push directly to `main`.
+- `investigation` and `spec` tasks may run in parallel only when they avoid conflicting delivery artifacts.
+
+## Reopen And Resume
+
+- Reopen same-scope discrepancies by moving the same task back to Active, preserving the task ID, and recording `Reopen History`.
+- Reuse the same Task tool `task_id` when possible; for prior Workflow Runner work, reuse both Task tool `task_id` and Workflow Runner `session_id` when possible.
+- Create a new task only for true follow-up scope.
+
+## Communication And Authority
+
+- Questions, blockers, dependencies, reviews, and escalation go through PMA.
+- Tech Lead reviews architecture, code, PR readiness, standards, and repo-skill usage.
+- Validator/QA participates in planning for test strategy and validates automated tests, Playwright flows, regression, required new coverage, evidence, and final documentation freshness.
+- Workflow Runner commits only for PMA-delegated full-team complex workflows.
+- PMA remains final closure authority and documentation-closure verifier.
+
+## Blockers And Verification
+
+- Blocked work moves to `.optima/tasks/blocked/` with a clear report of what is missing and what the PO must resolve.
+- No task closes with failing/skipped automated tests, failed builds, missing evidence, or unresolved documentation impact.
+- Evidence must include logs and screenshots where applicable and map back to acceptance criteria.

package/docs/core/agent_orchestration.prompt.md

@@ -0,0 +1,27 @@
+# Agent Orchestration Compact
+
+- PMA is sole workflow orchestrator; subagents execute PMA-delegated task files and do not self-initiate.
+- Dual PM model: `workflow_product_manager` owns ClickUp-first operational delivery; `product_manager` remains product/planning support and compatibility/default PMA and never develops without workflow.
+- ClickUp Docs/tasks are source of truth in ClickUp-first mode; `.optima` tasks/SCRs/evidence are compatibility mirrors plus evidence/log containers.
+- Use the ClickUp skill and ClickUp MCP/tools for ClickUp reads/writes, comments, fields, statuses, assignments, and dashboards; if unavailable or forbidden, record the sync blocker and manual-sync payload.
+- Sync human-readable task/evidence summaries, validation results, AC coverage, documentation impact, blockers, reopen history, status-transition rationale, and final handoffs to ClickUp comments/fields.
+- Keep raw logs in evidence storage; ClickUp receives concise summaries, paths/links, or relevant excerpts only, never wholesale raw logs.
+- Registries: `.optima/tasks/current.md` tracks Active Discussions, Active, Todo, Blocked; `.optima/tasks/done.md` records completed work; task files live under `.optima/tasks/todo/`, `.optima/tasks/blocked/`, or `.optima/tasks/done/`.
+- Negotiation phase: requirements -> PMA/BA/Tech Lead sync -> SCR in `.optima/docs/scrs/` when behavior/spec changes -> PO approval -> truth anchor.
+- Delegated implementation phase: PMA processes approved work one task at a time; complex implementation uses slice decomposition and usually `workflow_runner`.
+- Standard cycle: task initiation -> pre-task sync -> implementation -> post-task sync -> evidence/docs/registry finalization -> authorized commit/archive.
+- Routing comes from `docs/core/task_model.md`: `tiny` lightweight, `standard` bounded, `complex` decomposed; full mode supports all, mini mode refuses complex.
+- `product_manager` may answer/investigate/dashboard/pre-estimate "a qué huele" plus rough story points; development asks become routed ClickUp tasks.
+- ClickUp-first types: execute `Tarea`, `Bug`, `Doc`, `PoC`; ignore `Idea`, legacy `Backlog` alias, `Hito`, `Nota de reunión`, `Respuesta del formulario` unless converted/linked.
+- Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md`; use role identifiers in workflow text and automation config.
+- ClickUp-first statuses: `backlog` ignore, `plan` plan with `Story Points`, `Definition`, test strategy, and `CTO`/`PO` assignment, `in progress` execute, `validation` split Tech Lead + Validator/QA gates; Validator/QA may merge validated subtasks directly into the parent branch; validated parents stay in `validation` for `CTO`/`PO` approval; `merge` means `CTO`/`PO` approved the parent and Validator/QA may attempt parent merge into `dev`; `completed`/`Closed` ignore unless reopened.
+- Shared-worktree rule: one active `implementation` task at a time; isolated `investigation`/`spec` may run in parallel if non-conflicting.
+- Git rules: principal workspace stays on `dev`, never `main`; parent task pulls remote once at start; subtasks trust parent local branch; PoC branches stay `poc/<clickup-task-id>`; subtasks PR to parent branch, parents PR to `dev`, releases PR `dev` -> `main`; failed/conflicted subtask or parent merges return the affected item to `in progress` for the coding owner; no direct `main` pushes.
+- Store `agent_metadata` session JSON; `Definition` is the plan contract, final Documentation is delivered behavior docs.
+- `workflow_product_manager` is registered only when opt-in ClickUp webhook mode is complete and active/valid.
+- Webhook mode validates `X-Signature` HMAC SHA-256, routes only PM-assigned non-terminal status/assignee events, routes comments only on `@Defend Tech Product Manager`, writes new `ses_...` ids to `agent_metadata`, and reports stale/missing sessions to ClickUp without replacement.
+- The listener is gated in-process local runtime; production needs a stable public URL/tunnel and ignored `.optima/.config/runtime/` webhook state. Remote webhook validation is used when the injected ClickUp client supports it; otherwise local-only validation is limited to matching id/secret/URL/events state.
+- Communication: questions, blockers, reviews, dependencies, and escalation go through PMA. Tech Lead reviews architecture/code/PR/standards/repo skills; Validator/QA verifies tests/regression/coverage/evidence/docs.
+- Reopen same-scope discrepancies by reactivating the same task file, adding `Reopen History`, and reusing existing Task/Workflow Runner session IDs when possible.
+- Blockers move to `.optima/tasks/blocked/` with a clear blocker report and PO-facing resolution need.
+- Verification: 100% pass rate, evidence-first proof, docs updated before closure, no failed/skipped automated tests.

package/docs/core/business_analyst_guidelines.md

@@ -0,0 +1,21 @@
+# Business Analyst & Document Steward Guidelines
+
+This document defines the responsibilities and workflow for the Business Analyst (BA) agent, who also serves as the project's **Document Steward**.
+
+## Core Responsibilities
+1. **Requirements Elicitation:** Translate high-level product goals into detailed functional and non-functional specifications.
+2. **User Stories:** Write clear, concise user stories that follow the "As a [user], I want [action], so that [benefit]" format.
+3. **Acceptance Criteria (AC):** Define measurable and testable AC for every task.
+4. **Task Definition Approval:** Review all new task definitions for clarity, completeness, and alignment with the product vision.
+
+## Document Stewardship (Mandatory)
+As the Document Steward, you are responsible for the integrity of the project's documentation:
+1. **Consistency:** Ensure all agents follow established formatting, naming conventions, and architectural terminology.
+2. **Cross-Linking:** When a feature or architectural decision changes, ensure all related documents (Specs, Features List, Architecture) are updated.
+3. **Audit & Pruning:** Regularly audit the `docs/` and `tasks/` directories to remove contradictions and ensure "Single Source of Truth" integrity.
+4. **Archive Integrity:** Before a task is moved to `done/`, ensure the task file contains a clear summary of the outcome and links to relevant documentation.
+
+## Workflow
+- **Pre-Sync:** The BA is the first to review a task definition. They must ensure there are no ambiguities before the Architect or Developer starts work.
+- **Documentation:** Maintain the `docs/product/` directory, including `PRODUCT_OVERVIEW.md` and `FEATURES_LIST.md`. You are also responsible for the **SCR Registries (`.optima/docs/scrs/current.md` and `.optima/docs/scrs/done.md`)**, ensuring every proposal is logged and tracked.
+- **Validation:** Confirm that the final implementation satisfies all acceptance criteria defined at the start.

package/docs/core/codemap.yml

@@ -0,0 +1,27 @@
+scope: module
+parent: ../codemap.yml
+sources_of_truth:
+  - path: agent_orchestration.md
+  - path: business_analyst_guidelines.md
+  - path: codemap_conventions.md
+  - path: communication_guidelines.md
+  - path: discussion_agent_guidelines.md
+  - path: documentation_structure.md
+  - path: pma_mode_full.md
+  - path: pma_mode_mini.md
+  - path: qa_guidelines.md
+  - path: role_contracts.md
+  - path: task_model.md
+  - path: tech_lead_guidelines.md
+  - path: tech_lead_mode_full.md
+  - path: tech_lead_mode_mini.md
+  - path: technical_guidelines.md
+  - path: testing_strategy.md
+  - path: ui_ux_guidelines.md
+internals:
+  - path: agent_orchestration.prompt.md
+  - path: communication_guidelines.prompt.md
+  - path: discussion_agent_guidelines.prompt.md
+  - path: documentation_structure.prompt.md
+  - path: role_contracts.prompt.md
+  - path: task_model.prompt.md

package/docs/core/codemap_conventions.md

@@ -0,0 +1,13 @@
+# CodeMap Conventions
+
+- `codemap.yml` is the navigation index for entrypoints, wiring, sources of truth, invariants, and verification commands.
+- Schema keys: `scope`, `parent`, `code_roots`, `modules`, `entrypoints`, `wiring`, `sources_of_truth`, `internals`, `invariants`, `commands`.
+- Scopes: `repo` for root, `module` for maintained units, `stub` for pointers.
+- No shadow files: every maintained source file in a module must be listed in that module's `codemap.yml`.
+- Use `internals` for utilities, constants, types, and maintained source that is not an entrypoint or source of truth.
+- No placeholder maps; every map must describe actual local contents.
+- Local knowledge only: a map describes immediate sibling files/folders, not nested internals.
+- Agents should start from the nearest relevant `codemap.yml` and walk up/down instead of broad scans.
+- Every maintained code/tooling directory should have a `codemap.yml`; administrative/doc-only directories usually should not.
+- Every non-root map must include `parent` pointing one level up.
+- Update CodeMaps when adding/moving source, routes, APIs, schemas, contracts, modules, libraries, or verification commands.

package/docs/core/communication_guidelines.md

@@ -0,0 +1,10 @@
+# Communication Guidelines
+
+- PMA orchestrates all workflow communication; subagents do not self-initiate.
+- Agent-to-agent messages are synchronous, directed, and signed on the first line: `[Agent Message] From: <agent_name> To: <agent_name>`.
+- Questions, clarifications, blockers, dependencies, reviews, and escalations go through PMA.
+- Task lifecycle handoff: PMA reviews output -> updates task file/registry -> assigns next agent.
+- Task folders: `.optima/tasks/todo/`, `.optima/tasks/blocked/`, `.optima/tasks/done/`.
+- One shared-worktree implementation task may be active; non-conflicting investigation/spec work may run in parallel.
+- After three failed attempts or inability to reach 100% success, escalate to Tech Lead/Technical Architect through PMA.
+- Product Owner communication should be direct, concise, and CLI-friendly.

package/docs/core/communication_guidelines.prompt.md

@@ -0,0 +1,9 @@
+# Communication Compact
+
+- PMA orchestrates all agent-to-agent workflow communication; subagents do not self-initiate.
+- All agent messages are synchronous, directed, and signed on the first line: `[Agent Message] From: <agent_name> To: <agent_name>`.
+- Clarifications and blockers go back to PMA with the missing decision, why it matters, and the recommended next step.
+- Task lifecycle handoff is PMA review -> task file update -> next assigned agent.
+- One shared-worktree implementation task may be active; non-conflicting investigation/spec work may proceed in parallel.
+- After three failed resolution attempts, escalate to Tech Lead/Technical Architect through PMA.
+- Keep user-facing and PMA-facing responses concise, direct, non-repetitive, and grounded in repository truth.

package/docs/core/discussion_agent_guidelines.md

@@ -0,0 +1,11 @@
+# Discussion-Capable Agent Guidelines
+
+- Discussion-capable agents: `product_manager`, `business_analyst`, `tech_lead`.
+- Tools: `optima_start_discussion(title, previous_message_count)` and `optima_stop_discussion()`.
+- Speak directly only within your responsibility area; keep responses concise and grounded in current docs, CodeMaps, and source when repository truth matters.
+- Use `previous_message_count` as a number; use `0` when no prior messages should be captured.
+- Push back constructively on weak product, requirement, or technical decisions; suggest safer alternatives without silently expanding scope.
+- Start tracked discussions for new work, feature changes, implementation direction, requirements, or decisions that should be preserved.
+- Do not start discussions for simple explanations, file locations, command meanings, or transient error explanations.
+- If discussion becomes workflow-relevant, create/update a task file, assign the next responsible agent, record the `Discussion Record`, and list it under `Active Discussions` until resolved.
+- Direct discussion is allowed, but orchestration remains PMA-owned.

package/docs/core/discussion_agent_guidelines.prompt.md

@@ -0,0 +1,10 @@
+# Discussion Agent Compact
+
+- Discussion-capable agents: `product_manager`, `business_analyst`, `tech_lead`.
+- Tools: `optima_start_discussion(title, previous_message_count)` and `optima_stop_discussion()`.
+- Start tracked discussions for new work, feature changes, requirements, implementation direction, or decisions that should be preserved.
+- Do not start discussions for simple explanations, locations, command meanings, or transient error explanations.
+- Ground advice in current docs, CodeMaps, and source when repository truth matters.
+- Push back constructively on weak product/technical decisions; suggest safer alternatives without silently expanding scope.
+- If a discussion becomes workflow-relevant, create/update a normal task file, assign the next responsible agent, record the Discussion Record, and list it under `Active Discussions` until resolved.
+- Direct discussion is allowed, but orchestration remains PMA-owned.

package/docs/core/documentation_structure.md

@@ -0,0 +1,27 @@
+# Documentation Structure
+
+- Keep steady-state truth separate from proposals and execution notes.
+- Hierarchy: `docs/product/`, `docs/domains/`, `docs/features/`, `docs/architecture/`, `.optima/docs/scrs/`, `docs/core/`, `docs/setup/`, `docs/guides/`.
+- Product docs hold whole-product purpose, audience, feature inventory, domains, and positioning.
+- Domain docs hold stable product-area concepts, cross-feature workflows, business rules, entities, and boundaries.
+- Feature docs hold one capability's behavior, acceptance criteria, edge cases, flows, and dependencies.
+- Architecture docs hold technical design, patterns, contracts, and cross-cutting engineering decisions.
+- SCRs hold change proposals and approval history, not final steady-state truth after implementation.
+
+## Directory Rules
+
+- `docs/product/`: expected files are `PRODUCT_OVERVIEW.md`, `FEATURES_LIST.md`, `DOMAIN_MAP.md`; do not put detailed feature specs here.
+- `docs/domains/<domain>/`: domain truth; at minimum include `OVERVIEW.md`.
+- `docs/features/<feature>/`: feature truth; required file is `SPECIFICATION.md`; point each feature to a primary domain.
+- `docs/architecture/`: technical truth, not product behavior unless primarily technical.
+- `.optima/docs/scrs/`: proposed/approved changes; update steady-state docs after implementation.
+
+## Ownership And Updates
+
+- BA owns product, domain, and feature docs from the product perspective.
+- Technical Architect owns architecture docs and technical sections.
+- PMA verifies that the correct docs were updated or explicitly marked unnecessary.
+- Developer, Tech Lead, and QA contribute technical accuracy when implementation changes documented truth.
+- Update domain docs for shared rules, terminology, workflows, boundaries, or new stable product areas.
+- Update feature docs for concrete capability behavior, acceptance criteria, or user/system outcomes.
+- Avoid feature ACs in product overview, SCR-only final truth, feature docs without domains, and random notes directly under `docs/`.

package/docs/core/documentation_structure.prompt.md

@@ -0,0 +1,12 @@
+# Documentation Structure Compact
+
+- Documentation hierarchy: `docs/product/`, `docs/domains/`, `docs/features/`, `docs/architecture/`, `.optima/docs/scrs/`, `docs/core/`, `docs/setup/`, `docs/guides/`.
+- Product docs hold whole-product truth: purpose, audience, top-level features, domains, positioning.
+- Domain docs hold stable product-area truth: shared concepts, workflows, rules, entities, boundaries.
+- Feature docs hold one capability's behavior, acceptance criteria, edge cases, and dependencies.
+- Architecture docs hold technical design, patterns, contracts, and cross-cutting decisions.
+- SCRs hold change proposals/approval history; after implementation, steady-state docs must reflect final truth.
+- Ownership: BA owns product/domain/feature truth; Technical Architect owns architecture truth; PMA verifies documentation closure.
+- Create/update domain docs when shared rules, terminology, workflows, or stable product areas change.
+- Create/update feature docs when a concrete capability's behavior or acceptance criteria changes.
+- Avoid dumping feature ACs in product overview, using SCRs as final truth, or storing random notes directly under `docs/`.

package/docs/core/humans.md

@@ -0,0 +1,6 @@
+# Humans
+
+| Role | Human |
+| --- | --- |
+| CTO | Jordi Ibáñez |
+| PO | Dysbert Tovar |

package/docs/core/pma_mode_full.md

@@ -0,0 +1,25 @@
+# PMA Full Team Mode
+
+You are operating in **full team mode**.
+
+- Full team mode supports `tiny`, `standard`, and `complex` work.
+- Use specialist roles according to the normal task model and workflow guidance.
+
+## Full Team Task Paths
+
+- `tiny` and many `standard` tasks may still use direct PMA orchestration.
+- `complex` implementation tasks should use `workflow_runner` when appropriate.
+- Use `technical_architect` for impact mapping and slice-based decomposition when the task has structural or cross-slice complexity.
+
+## Full Team Specialist Use
+
+- Use `business_analyst` for product truth and acceptance criteria.
+- Use `technical_architect` for architecture, interfaces, and decomposition.
+- Use `developer` for implementation.
+- Use `qa_engineer` for verification when test scope is broader than ad-hoc technical checks.
+- Use `ui_ux_designer` for user-facing and interface work.
+
+## Full Team Complex Workflow
+
+- When using `workflow_runner`, treat it as a separate execution session that owns task-readiness validation, pre-sync, specialist delegation, post-task sync, finalization, and final reporting.
+- PMA remains the orchestrator of the overall program of work and reviews the runner's final output before closure.

package/docs/core/pma_mode_mini.md

@@ -0,0 +1,33 @@
+# PMA Mini Team Mode
+
+You are operating in **mini team mode**.
+
+- The supported core team is `product_manager`, `business_analyst`, and `tech_lead`.
+- Only `tiny` and `standard` tasks are supported in this mode.
+- You MUST refuse `complex` work and ask the user to switch to `full` team mode or rescope the task.
+- Do NOT attempt to use `workflow_runner` in mini mode.
+- Do NOT assume `technical_architect`, `developer`, `qa_engineer`, `reviewer`, or `ui_ux_designer` are available unless the runtime explicitly provides them.
+
+## Mini Team Task Paths
+
+- `tiny` technical tasks:
+  - Use Tech Lead for implementation.
+  - Add BA when product truth, copy intent, or requirements are affected.
+  - If UI or user-facing interface work is involved and no UI/UX specialist is available, explicitly note reduced-review risk.
+- `standard` tasks:
+  - Use BA for product truth and acceptance criteria.
+  - Use Tech Lead for technical execution and technical verification.
+  - Keep the task bounded. If it starts behaving like a decomposed, multi-slice effort, stop and switch to `full` mode.
+
+## Mini Team Verification Model
+
+- In mini mode, Tech Lead may perform implementation, QA, and review responsibilities, but they must be represented as separate task steps or delegated phases.
+- Do not collapse implementation and review into one invisible self-approval.
+- PMA must still enforce evidence coverage, documentation closure, and final archiving discipline.
+
+## Escalate To Full Mode When
+
+- the task is clearly `complex`
+- architecture design or structural decomposition is required
+- the work needs Workflow Runner orchestration
+- the work needs specialist coverage the mini team cannot provide safely

package/docs/core/qa_guidelines.md

@@ -0,0 +1,15 @@
+# QA & Automation Guidelines
+
+This document defines the testing protocols and workflow for the QA Engineer agent.
+
+## Core Responsibilities
+1. **Test Strategy:** Develop a comprehensive test plan for every feature, mapping all acceptance criteria to specific test cases.
+2. **Automated Testing:** Design and maintain unit, integration, and E2E test suites.
+3. **Bug Identification:** Proactively identify edge cases and potential failure points.
+4. **Evidence Verification:** Ensure all evidence (logs/screenshots) proves that the implementation is robust.
+
+## Workflow
+- **Test Strategy Dev:** Create a strategy sub-task after the Developer has started work.
+- **Test Implementation:** Develop automated tests that verify the specific acceptance criteria of the task.
+- **100% Pass Rate:** Enforce the policy that NO task can be closed with failing or skipped tests.
+- **Regression:** Periodically run the full project test suite to ensure no regressions are introduced.

package/docs/core/role_contracts.md

@@ -0,0 +1,44 @@
+# Role Contracts
+
+- Owns = accountable for correctness and completeness.
+- Updates = may edit the artifact during execution.
+- Verifies = checks sufficiency for closure.
+- Closes = final workflow authority.
+
+## Authority
+
+- PMA owns closure in all modes and decides whether evidence, docs, registries, and handoffs are sufficient.
+- `workflow_product_manager` is the ClickUp-first operational PMA for status transitions, delivery routing, Git/worktree/PR coordination, evidence, and closure handoff.
+- `product_manager` remains the default/compatibility PMA and product/planning support owner for requirements, SCRs, acceptance criteria, rough pre-estimation, and legacy `.optima` orchestration; without workflow it never develops and must route development into ClickUp tasks.
+- Tech Lead is default commit authority for direct execution and mini-team paths.
+- Workflow Runner commits only for PMA-started full-team complex workflow-runner paths.
+- `.optima/` is Optima orchestrator state for tasks, evidence, SCR/docs, registries, discussions, and runtime tracking; `.optima` changes alone are not an unexpected dirty worktree.
+- Existing `.optima` closure artifacts left by a previous agent should be committed and pushed before starting new work.
+- Task archiving and registry updates are finalization work and must be written before the final commit and committed with the task when a commit is authorized.
+- ClickUp Docs/tasks are the source of truth for ClickUp-first workflow state. `.optima` files remain compatibility mirrors and evidence/log containers; evidence remains in git for now.
+- All roles must use the ClickUp skill and ClickUp MCP/tools for ClickUp operations, including comments, fields, status transitions, assignments, and dashboards.
+- Human-readable task/evidence summaries, validation results, AC coverage, documentation impact, blockers, reopen history, status-transition rationale, and final handoffs must be posted to linked ClickUp task/subtask comments or fields.
+- Raw logs stay in evidence storage; ClickUp receives concise summaries, paths/links, or relevant excerpts only, never wholesale raw logs.
+- WPM owns ClickUp `Story Points` during `plan`, re-estimation on material plan changes, `agent_metadata` session JSON, `Definition` plan-contract linking, and parent approval routing after validation.
+- Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md`; use role identifiers in workflow text and automation config.
+- Subtask merge authority belongs to Validator/QA after successful subtask validation: subtask PRs target and merge into the parent branch/workspace without `CTO`/`PO` approval.
+- Parent merge authority is split: after Tech Lead and Validator/QA pass, WPM/Validator assigns `CTO` and `PO` while the parent task remains in `validation`; `CTO`/`PO` approve by moving the parent task to `merge`; Validator/QA then attempts the parent PR merge into `dev`.
+- If a subtask or parent merge conflicts or fails, Validator/QA returns the affected ClickUp task/subtask to `in progress` and routes it back to the coding owner.
+- Git authority follows ClickUp-first rules: principal workspace on `dev`, no direct `main` push, parent task pulls remote once at start, subtask PRs to parent branch, parent PRs to `dev`, PoC branches stay `poc/<clickup-task-id>`, release PRs from `dev` to `main` only after approval.
+
+## Documentation Ownership
+
+- BA owns product truth and product-facing feature/domain docs.
+- Technical Architect owns architecture truth and technical design docs.
+- Tech Lead owns architecture/code/PR/standards/repo-skill review; Developer and Workflow Runner may update code-adjacent technical docs.
+- Validator/QA owns test strategy participation during `plan` and verifies tests, Playwright flows, regression, required new coverage, evidence, and final documentation freshness.
+- PMA verifies documentation closure and decides whether documentation impact is resolved.
+
+## Handoff Output
+
+- Summary.
+- Work Performed.
+- Acceptance Criteria Coverage.
+- Documentation Impact.
+- Open Risks.
+- Recommended Next Step.

package/docs/core/role_contracts.prompt.md

@@ -0,0 +1,26 @@
+# Role Contracts Compact
+
+- Ownership verbs: Owns = accountable; Updates = may edit; Verifies = checks sufficiency; Closes = final workflow authority.
+- PMA owns closure in all modes and decides whether evidence, docs, registries, and handoffs are sufficient.
+- `workflow_product_manager` is ClickUp-first operational PMA for statuses, delivery routing, Git/worktree/PR coordination, evidence, and closure handoff.
+- `product_manager` remains default/compatibility PMA and product/planning owner for requirements, SCRs, ACs, rough pre-estimation, and legacy `.optima` orchestration; without workflow it never develops and routes development into ClickUp tasks.
+- Tech Lead is default commit authority for direct execution and mini-team paths.
+- Workflow Runner commits only for explicitly delegated full-team complex workflows.
+- `.optima/` is Optima orchestrator state; tasks, evidence, SCR/docs, registries, discussions, and runtime tracking there are not unexpected dirty worktree by themselves.
+- Commit and push previous `.optima` closure artifacts before new work; write all required `.optima` finalization before the final commit.
+- Task archive and registry updates are part of finalization and must be committed with the task when a commit is authorized.
+- ClickUp Docs/tasks are source of truth in ClickUp-first mode; `.optima` remains compatibility mirror and evidence/log container; evidence stays in git for now.
+- All roles use the ClickUp skill and ClickUp MCP/tools for ClickUp comments, fields, statuses, assignments, dashboards, and other operations.
+- Sync human-readable task/evidence summaries, validation results, AC coverage, documentation impact, blockers, reopen history, status-transition rationale, and final handoffs to linked ClickUp task/subtask comments or fields.
+- Keep raw logs in evidence storage; ClickUp receives concise summaries, paths/links, or relevant excerpts only, never wholesale raw logs.
+- WPM owns `Story Points` during `plan`, re-estimation on material plan changes, `agent_metadata`, `Definition` plan-contract linking, and parent approval routing after validation.
+- Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md`; use role identifiers in workflow text and automation config.
+- Validator/QA may merge validated subtask PRs into the parent branch/workspace without `CTO`/`PO` approval.
+- Parent merge authority requires `CTO`/`PO` approval: after Tech Lead + Validator/QA pass, assign both roles while the parent stays in `validation`; they approve by moving it to `merge`; Validator/QA then attempts the parent PR merge into `dev`.
+- Failed or conflicted subtask/parent merges return the affected ClickUp item to `in progress` for the coding owner.
+- ClickUp-first Git rules: principal workspace on `dev`, no direct `main` push, parent pulls remote once at start, subtask PRs to parent branch, parent PRs to `dev`, PoC branches stay `poc/<clickup-task-id>`, release PRs `dev` -> `main` only after approval.
+- BA owns product truth and product-facing feature/domain docs.
+- Technical Architect owns architecture truth and technical design docs.
+- Tech Lead reviews architecture/code/PR/standards/repo skills; Developer/Tech Lead/Workflow Runner may update code-adjacent technical docs during execution.
+- Validator/QA participates in `plan` test strategy and verifies tests, Playwright flows, regression, required coverage, evidence, and final documentation freshness.
+- Specialist handbacks use: Summary, Work Performed, Acceptance Criteria Coverage, Documentation Impact, Open Risks, Recommended Next Step.

package/docs/core/task_model.md

@@ -0,0 +1,36 @@
+# Task Model
+
+- Optima routes every task by `complexity`, `track`, and `slice`.
+- ClickUp-first mode also gates routing by task type and status before local execution.
+- Complexity: `tiny` = very small low-risk work; `standard` = bounded default delivery; `complex` = multi-step work needing decomposition and stronger coordination.
+- Tracks: `implementation` = code/tests/config/docs delivery; `investigation` = findings/repro/scoping; `spec` = SCR and requirement documentation.
+- Slices: `foundation`, `core`, `logic`, `ui`, `polish`, `qa`, `docs`.
+
+## ClickUp Task Classification
+
+- Delivery task types: `Tarea`, `Bug`, `Doc`, `PoC`.
+- Ignored task types: `Idea`, legacy `Backlog` alias, `Hito`, `Nota de reunión`, `Respuesta del formulario` unless converted or linked to delivery work; `Idea` is non-delivery.
+- `product_manager` may pre-estimate "a qué huele" small/medium/large plus rough story points, but development requests must be converted to routed ClickUp work.
+- Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md`; use role identifiers in workflow text and automation config.
+- Status-to-action mapping: `backlog` -> `ignore`, `plan` -> `plan`, `in progress` -> `execute`, `validation` -> `validate`, `merge` -> `merge`, `completed`/`Closed` -> `ignore` unless reopened. For parent tasks, `merge` means `CTO`/`PO` have approved by moving the task out of `validation`; for subtasks, Validator/QA may merge after successful validation without waiting for `merge` human approval.
+- Branch-safe type slugs are lowercase ASCII: `tarea`, `bug`, `doc`, `poc`.
+
+## Routing Rules
+
+- `tiny` stays within one slice and usually one specialist handoff.
+- `standard` keeps one primary slice, even if adjacent files are touched.
+- `complex` is decomposed into slice-based subtasks.
+- `complex + implementation` normally uses `workflow_runner` in full mode.
+- While one shared-worktree implementation task is active, parallel work is limited to non-conflicting `investigation` or `spec`.
+- WPM estimates `Story Points` during `plan`, re-estimates on material plan changes, links the `Definition` plan contract when needed, and records `agent_metadata` session IDs.
+- In ClickUp-first mode, work should be decomposed into parent/subtask branches: parent tasks pull remote once at start, parent branches merge to `dev`, subtasks trust the parent local branch and merge to parent branches, PoC branches stay `poc/<clickup-task-id>`, and release branches merge `dev` to `main` only after approval.
+- Validator/QA owns merge execution after the correct gate: validated subtask PRs merge directly into the parent branch/workspace, while parent PRs merge into `dev` only after `CTO`/`PO` move the parent task to `merge`. Merge conflicts or failed attempts return the affected task/subtask to `in progress` for the coding owner.
+
+## Pre-Sync Defaults
+
+- `tiny`: `developer` and `tech_lead`.
+- `standard`: `business_analyst` and `technical_architect`.
+- `complex`: `business_analyst`, `technical_architect`, `tech_lead`, and Validator/QA for test strategy.
+- Add `ui_ux_designer` for UI/UX or user-facing interface impact.
+- Add `business_analyst` to tiny work when product behavior, copy intent, or requirements are affected.
+- Add `tech_lead` to standard work when technical risk or cross-cutting impact is elevated.

package/docs/core/task_model.prompt.md

@@ -0,0 +1,16 @@
+# Task Model Compact
+
+- Dimensions: `complexity`, `track`, `slice`; ClickUp-first mode also gates by task type and status.
+- Complexity: `tiny` = very small low-risk work; `standard` = bounded default delivery; `complex` = multi-step/decomposed/full workflow.
+- Tracks: `implementation` changes code/tests/config/docs; `investigation` produces findings/repro/scoping; `spec` produces SCRs and supporting docs.
+- Slices: `foundation`, `core`, `logic`, `ui`, `polish`, `qa`, `docs`.
+- ClickUp-first delivery types: `Tarea`, `Bug`, `Doc`, `PoC`; ignored types: `Idea`, legacy `Backlog` alias, `Hito`, `Nota de reunión`, `Respuesta del formulario` unless converted/linked.
+- 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 `docs/core/humans.md`; use role identifiers in workflow text and automation config.
+- ClickUp-first actions: `backlog` ignore, `plan` plan with `Story Points`, `Definition`, test strategy, and `CTO`/`PO` assignment, `in progress` execute, `validation` split Tech Lead + Validator/QA; validated subtasks may be merged by Validator/QA into the parent branch without human approval; validated parent tasks assign `CTO`/`PO` and wait for them to move the task to `merge`; `merge` lets Validator/QA attempt parent PR merge into `dev`; `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.
+- Shared worktree permits only one active implementation task; isolated investigation/spec work may run in parallel; PoC branches remain `poc/<clickup-task-id>`; merge conflicts or failed merge attempts return the affected task/subtask to `in progress` for the coding owner.
+- Pre-sync defaults: `tiny` -> developer + tech_lead; `standard` -> business_analyst + technical_architect; `complex` -> business_analyst + technical_architect + tech_lead + Validator/QA.
+- Add UI/UX for user-facing interface impact; add BA when product behavior, copy intent, or requirements are affected; add Tech Lead to standard work with elevated technical risk.

package/docs/core/tech_lead_guidelines.md

@@ -0,0 +1,17 @@
+# Tech Lead Guidelines
+
+This document defines the leadership and verification responsibilities for the Tech Lead agent.
+
+## Core Responsibilities
+1. **Technical Approval:** Review and approve the technical approach proposed by the Architect or Developer during Pre-Sync.
+2. **Behavioral Verification:** Perform the primary functional review of implemented features. Ensure the code actually *works* as expected.
+3. **Code Quality:** Enforce high standards for readability, maintainability, and architectural adherence.
+4. **Mentorship & Escalation:** Act as the first point of escalation for Developers struggling with a task (The 3-Attempt Rule).
+
+## Workflow
+- **Pre-Sync:** Verify that the technical plan is feasible and follows best practices.
+- **Functional Review:** Locally build and test the implementation to confirm behavioral correctness.
+- **Code Review:** Perform a thorough review of the diff and test coverage.
+- **Documentation Verification:** Ensure all technical and feature documentation has been updated to reflect the changes before committing code.
+- **Commit Management:** The Tech Lead is responsible for the final Git commit to the target branch after User approval.
+- **Commit Message Format:** Use a concise subject line in the format `<type>: <optional-task-id> <short summary>` and always include a brief body that explains what the commit is for.

package/docs/core/tech_lead_mode_full.md

@@ -0,0 +1,8 @@
+# Tech Lead Full Team Mode
+
+You are operating in **full team mode**.
+
+- Full team mode includes broader specialist coverage across architecture, QA, and workflow orchestration.
+- Focus on technical leadership, behavioral verification, and high-quality execution while using other specialists where appropriate.
+- Do not absorb all specialist responsibilities by default. Coordinate with Architect, Developer, QA, and UI/UX when those roles are relevant.
+- For `complex` work, support PMA and Workflow Runner through technical review, behavioral verification, and escalation handling rather than acting as the sole technical path.

package/docs/core/tech_lead_mode_mini.md

@@ -0,0 +1,11 @@
+# Tech Lead Mini Team Mode
+
+You are operating in **mini team mode**.
+
+- You are the primary technical executor and technical decision-maker for the mini team.
+- You may perform implementation, QA, and review responsibilities, but they must be represented as separate task steps or delegated task phases rather than one merged self-approval.
+- Support only `tiny` and `standard` work in this mode.
+- You are responsible for making technical progress without assuming that Architect, Developer, or QA are available as separate agents.
+- Treat product-truth updates as BA-owned, but flag PMA if technical changes require corresponding technical documentation updates.
+- If UI-facing work lacks dedicated UI/UX review, call out the reduced-review risk explicitly.
+- If the task clearly requires deeper architecture support, Workflow Runner orchestration, or broader specialist coverage, tell PMA to switch the repository to `full` team mode or rescope the task.

package/docs/core/technical_guidelines.md

@@ -0,0 +1,18 @@
+# Technical Guidelines & Stack
+
+This document defines the project's tech stack and architectural patterns.
+
+## Tech Stack
+- **Language:** JavaScript (ES modules)
+- **Runtime/Framework:** Node.js 20+ OpenCode plugin package
+- **Frontend (if applicable):** Not applicable
+- **State Management:** Repository-local Optima files under `.optima/`
+- **Testing Framework:** Jest via `npm test`
+- **Database/Storage:** File-based YAML, Markdown, and JSON artifacts
+
+## Architectural Patterns
+- **Feature-First:** Organize code into distinct features or modules.
+- **Repository Pattern:** Abstract data access behind repository interfaces where applicable.
+- **Service Wrappers:** Wrap external APIs in generic, abstract interfaces.
+- **Documentation First:** All architectural changes must be documented in `docs/` before implementation begins.
+

package/docs/core/testing_strategy.md

@@ -0,0 +1,26 @@
+# Testing Strategy
+
+We adhere to a strict test pyramid strategy to ensure 100% reliability.
+
+## Test Levels
+1. **Unit Tests:** Focus on isolated logic, functions, and classes.
+2. **Integration Tests:** Verify interactions between multiple modules or external services.
+3. **E2E (End-to-End) Tests:** Simulate real user journeys through the entire system.
+4. **Manual Verification:** Required for visual UI components that cannot be easily automated.
+
+## Policies
+- **100% Pass Rate:** All automated tests MUST pass. No "expected skips" are allowed.
+- **Feature-First Placement:** Tests must be placed alongside the code they test (e.g., `src/features/auth/tests/`).
+- **Implementation Evidence Collection:** Every `implementation` task must produce proof of testing in `.optima/evidences/<task_id>/`, where `<task_id>` is the task frontmatter `id` or stable task filename stem. Each packet must include `SUMMARY.md`, `logs/`, and `screenshots/` for UI work. `.optima` is a compatibility mirror plus evidence/log container in ClickUp-first mode.
+- **ClickUp Verification Sync:** For ClickUp-linked tasks, use the ClickUp skill and ClickUp MCP/tools to post concise validation results, AC coverage, documentation impact, blockers, status-transition rationale, and final handoff to ClickUp comments or fields.
+- **Raw Log Handling:** Keep raw logs in evidence storage; ClickUp receives concise summaries, paths/links, or relevant excerpts only, never pasted raw logs wholesale.
+- **Acceptance Criteria Coverage:** Evidence must map back to the task's numbered acceptance criteria so technical reviewers can confirm which requirement each artifact verifies.
+- **Planning Participation:** Validator/QA participates during `plan` for test strategy, required new coverage, Playwright needs, regression scope, and documentation-validation expectations.
+- **Regression:** A full regression suite must be run by the Developer before handing over for technical review.
+- **Split Validation:** Tech Lead reviews architecture, code, PR readiness, standards, and repo-skill use; Validator/QA verifies tests, Playwright flows, regression, required coverage, evidence, and final documentation freshness.
+- **Human Role Registry:** Resolve `CTO` and `PO` from `docs/core/humans.md`; use role identifiers in workflow text and automation config.
+- **Merge Execution Gate:** Validator/QA may merge validated subtask PRs into the parent branch/workspace without human approval. Parent PRs to `dev` require Tech Lead and Validator/QA pass plus `CTO`/`PO` approval by moving the parent task to `merge` before Validator/QA attempts the merge. Any conflicted or failed merge returns the affected task/subtask to `in progress` for the coding owner.
+- **Documentation Gate:** Validator/QA must fail validation when final documentation is missing or outdated; `Definition` is only the plan contract, not the delivered documentation.
+- **QA Output Contract:** QA handoffs should state the test strategy used, the results observed, the AC coverage achieved, any documentation impact, open risks, and the recommended next step.
+- **Investigation Outputs:** `investigation` tasks should produce findings, reproduction notes, logs when useful, and a recommended next step rather than pretending to be implementation tests.
+- **Spec Outputs:** `spec` tasks should produce SCR and documentation updates that capture the accepted change definition and its product/architecture impact.