@defend-tech/opencode-optima 0.1.10

package/docs/core/ui_ux_guidelines.md

@@ -0,0 +1,24 @@
+# UI/UX Design Guidelines
+
+- Prioritize ease of use, accessibility, intuitive navigation, visual hierarchy, polish, and design-system consistency.
+- In pre-sync, define screen components, interactions, layout, visual hierarchy, color, typography, and usability risks.
+- In review, inspect screenshots/evidence from `.optima/evidences/<task_id>/`; do not review code.
+- If visual evidence is missing or inadequate, ask for better screenshots instead of guessing.
+- Judge results as `Good`, `Needs Fix Now`, or `Future Enhancement`.
+
+## Quality Checklist
+
+- Alignment and grid discipline are clear.
+- Spacing is consistent across related elements.
+- Typography hierarchy makes screens easy to scan.
+- Interactive elements have obvious affordance.
+- Color contrast supports accessibility.
+- The UI feels modern, focused, uncluttered, and professionally polished.
+
+## Mandatory Rejection
+
+- Blatant misalignment.
+- Ignored design system.
+- Overlap, cut-off text, or broken responsive layout.
+- Missing interaction flow from pre-sync.
+- Amateur visual polish or unreadable contrast.

package/docs/domains/README.md

@@ -0,0 +1,15 @@
+# Domains
+
+Use `docs/domains/` for stable product areas that contain multiple related features.
+
+At minimum, each domain should contain:
+
+- `OVERVIEW.md`
+
+Recommended supporting files:
+
+- `RULES.md`
+- `WORKFLOWS.md`
+- `ENTITIES.md`
+
+Domain docs should explain shared concepts and cross-feature rules, not low-level implementation details.

package/docs/domains/codemap.yml

@@ -0,0 +1,7 @@
+scope: module
+parent: ../codemap.yml
+modules:
+  - path: domain-template
+  - path: task-lifecycle
+sources_of_truth:
+  - path: README.md

package/docs/domains/domain-template/OVERVIEW.md

@@ -0,0 +1,37 @@
+# Domain Overview Template
+
+Use this template when introducing a new domain under `docs/domains/<domain>/`.
+
+## Domain Name
+
+`<domain-name>`
+
+## Purpose
+
+Describe the stable product area this domain covers and why it exists.
+
+## Scope
+
+- What belongs in this domain
+- What does not belong in this domain
+- How this domain interacts with neighboring domains
+
+## Core Concepts
+
+- List the shared concepts or terms that appear across multiple features in this domain.
+
+## Owned Features
+
+- List the primary features that belong to this domain.
+
+## Shared Rules
+
+- Summarize the rules or invariants that apply across multiple features in the domain.
+
+## Key Workflows
+
+- List or link the major workflows that matter in this domain.
+
+## Related Documents
+
+- Link to supporting `RULES.md`, `WORKFLOWS.md`, `ENTITIES.md`, related feature specs, and relevant architecture docs.

package/docs/domains/domain-template/codemap.yml

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

package/docs/domains/task-lifecycle/OVERVIEW.md

@@ -0,0 +1,69 @@
+# Task Lifecycle
+
+## Purpose
+
+This domain defines how work is classified, discussed, executed, verified, and archived inside Optima.
+
+It is the primary product area responsible for turning approved work into structured task execution with the right amount of process for the task's complexity and risk.
+
+## Scope
+
+This domain includes:
+
+- task classification by `tiny`, `standard`, and `complex`
+- task routing by `implementation`, `investigation`, and `spec`
+- slice-based task planning using `foundation`, `core`, `logic`, `ui`, `polish`, `qa`, and `docs`
+- definition-of-ready and definition-of-done expectations for task execution
+- pre-sync quorum rules
+- task execution flow and handoff expectations
+- verification and archiving expectations
+
+This domain does not include:
+
+- low-level technical architecture details
+- plugin installation and configuration guidance
+- CodeMap schema rules
+
+## Core Concepts
+
+- **Complexity:** The process weight of the task.
+- **Track:** The type of work being performed.
+- **Slice:** The dominant work surface for the task.
+- **Pre-Sync:** The required specialist discussion before execution starts.
+- **Decomposition:** Breaking `complex` work into slice-based subtasks.
+- **Verification:** The proof and checks required before closure.
+
+## Owned Features
+
+- task template structure
+- complexity-based routing
+- pre-sync specialist defaults
+- slice-based decomposition for complex work
+- evidence and verification expectations
+- task completion and archiving flow
+
+## Shared Rules
+
+- `tiny` work should stay narrowly scoped within one primary slice.
+- `standard` work should remain bounded and keep one dominant slice.
+- `complex` work should be decomposed into slice-based subtasks.
+- PMA always facilitates the discussion, but the required specialist quorum depends on task complexity and impact.
+- UI and other user-facing interface work must include `ui_ux_designer` in pre-sync.
+
+## Key Workflows
+
+- classify task complexity and track
+- select the required specialist quorum
+- define objective and acceptance criteria
+- decompose complex work when needed
+- execute, verify, and archive the task
+
+## Related Documents
+
+- `docs/core/task_model.md`
+- `docs/core/agent_orchestration.md`
+- `.optima/policies/definition-of-ready.md`
+- `.optima/policies/definition-of-done.md`
+- `.optima/tasks/task-template.md`
+- `.optima/tasks/subtask-template.md`
+- `docs/core/documentation_structure.md`

package/docs/domains/task-lifecycle/codemap.yml

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

package/docs/features/README.md

@@ -0,0 +1,11 @@
+# Features
+
+Use `docs/features/` for specific product or system capabilities.
+
+Each feature should:
+
+- belong to one primary domain
+- have one `SPECIFICATION.md`
+- describe concrete behavior and acceptance criteria
+
+Feature docs should stay capability-focused and should not become a second domain overview.

package/docs/features/codemap.yml

@@ -0,0 +1,6 @@
+scope: module
+parent: ../codemap.yml
+modules:
+  - path: feature-template
+sources_of_truth:
+  - path: README.md

package/docs/features/feature-template/SPECIFICATION.md

@@ -0,0 +1,36 @@
+# Feature Specification Template
+
+Use this template for `docs/features/<feature>/SPECIFICATION.md`.
+
+## Feature Name
+
+`<feature-name>`
+
+## Primary Domain
+
+`<domain-name>`
+
+## Summary
+
+Describe the specific capability this feature provides.
+
+## Users Or Systems Affected
+
+- Identify who uses this feature or which systems depend on it.
+
+## Behavior
+
+- Describe the expected behavior of the feature.
+- Include major success paths and key error or edge cases.
+
+## Acceptance Criteria
+
+- [ ] Define the conditions that must be true for the feature to be considered complete.
+
+## Dependencies
+
+- List related domains, features, contracts, or architecture documents.
+
+## Notes
+
+- Include any additional product notes, UX notes, or technical constraints that are important for delivery.

package/docs/features/feature-template/codemap.yml

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

package/docs/guides/AGENTS.md

@@ -0,0 +1,63 @@
+# Workflow Agents
+
+Optima installs the **Optima Collective** into OpenCode: a role-based AI software development team that behaves more like a delivery organization than a single assistant.
+
+The collective is designed so each agent represents a professional function inside an AI-native software company. Instead of one model improvising across all concerns, Optima distributes responsibility across product, architecture, implementation, QA, technical review, and design roles.
+
+## Primary orchestration agents
+
+- `product_manager`: The default primary agent. Routes work by complexity, delegates specialists, and decides when to use the Workflow Runner.
+- `workflow_runner`: Delegated orchestrator for complex implementation tasks. Handles task-readiness validation, pre-task sync, specialist delegation, post-task sync, finalization, and final reporting inside a PMA-started workflow.
+
+## Specialist agents
+
+- `business_analyst`: Maintains product truth, clarifies requirements, and improves SCR quality.
+- `technical_architect`: Defines interfaces, impact surfaces, and architectural consistency.
+- `tech_lead`: Performs behavioral verification, code quality checks, and technical sign-off.
+- `developer`: Implements code and tests.
+- `qa_engineer`: Designs and executes verification and test coverage.
+- `ui_ux_designer`: Reviews visual and interaction quality for UI-facing work.
+
+## Discussion-Capable Agents
+
+These agents can talk directly with the user and turn meaningful discussions into tracked handoff tasks:
+
+- `product_manager`
+- `business_analyst`
+- `tech_lead`
+
+## Agent Mode Semantics
+
+- `primary`: The default main agent the user lands in for the repository.
+- `subagent`: Intended for delegated specialist work rather than direct primary use.
+- `all`: Can be used either as a directly selected agent or as a delegated specialist, depending on the workflow.
+
+`mode: all` does not make an agent an orchestrator by default. PMA remains the sole workflow orchestrator. Discussion-capable agents may speak directly with the user, but workflow-relevant work must still be handed back through task files and PMA-owned orchestration.
+
+## Repository Customization
+
+- `.optima/agents/<agent>.md`: full repository-local agent definition. Use this to override a bundled agent's base prompt or define a brand new custom repository agent.
+- `.optima/agent-additions/<agent>.md`: appends repository-specific instructions to a bundled or custom agent prompt.
+- `.optima/policies/*.md`: overrides shared repository policy files used by multiple agents.
+
+Use shared policies and additive agent files by default. Use full agent definitions in `.optima/agents/` when a repository needs a custom agent or needs to take over an agent's base prompt.
+
+## Typical usage by task complexity
+
+### Tiny
+
+- PMA routes directly to the most relevant specialist.
+- Verification stays lightweight.
+- Use a single primary slice.
+
+### Standard
+
+- PMA orchestrates a bounded delivery sequence.
+- One primary slice, with adjacent work only when necessary.
+- Verification and documentation expectations remain normal.
+
+### Complex
+
+- PMA links the task to an approved SCR.
+- Architect helps decompose the work into slice-based subtasks.
+- `workflow_runner` executes the end-to-end delivery cycle through specialist delegation while PMA waits for completion notification.

package/docs/guides/TEAM_MODE_FULL.md

@@ -0,0 +1,44 @@
+# Full Team Mode
+
+Full team mode enables the complete Optima Collective.
+
+## Available Agents
+
+- `product_manager` (PMA)
+- `workflow_runner`
+- `business_analyst` (BA)
+- `technical_architect`
+- `tech_lead`
+- `developer`
+- `qa_engineer`
+- `ui_ux_designer`
+
+## Supported Work
+
+- `tiny`
+- `standard`
+- `complex`
+
+## Full Team Task Flow
+
+```text
+User request
+  -> PMA classifies task and track
+  -> BA + Tech Lead refine or review specification
+  -> For standard work, PMA orchestrates specialist handoffs directly
+  -> For complex work, PMA starts Workflow Runner in a separate session
+  -> Architect decomposes structural work into slices when needed
+  -> Developer / QA / UI-UX contribute by specialty
+  -> Workflow Runner or PMA returns evidence and completion state
+  -> PMA checks documentation closure
+  -> Commit and archive
+```
+
+## Full Team Responsibilities
+
+- **PMA:** orchestration, routing, final closure
+- **Workflow Runner:** separate-session orchestration for complex workflows
+- **BA:** product truth and acceptance criteria
+- **Technical Architect:** architecture and decomposition
+- **Tech Lead:** technical leadership and behavioral verification
+- **Developer / QA / UI-UX:** specialist execution and review

package/docs/guides/TEAM_MODE_MINI.md

@@ -0,0 +1,41 @@
+# Mini Team Mode
+
+Mini team mode is the lightest supported Optima operating model.
+
+## Available Agents
+
+- `product_manager` (PMA)
+- `business_analyst` (BA)
+- `tech_lead`
+
+## Supported Work
+
+- `tiny`
+- `standard`
+
+Not supported:
+
+- `complex`
+- `workflow_runner`
+
+## Mini Team Task Flow
+
+```text
+User request
+  -> PMA classifies task
+  -> BA clarifies requirements and product truth when needed
+  -> Tech Lead executes technical work
+  -> Tech Lead performs verification and review as separate task phases
+  -> PMA checks evidence and documentation closure
+  -> Commit and archive
+```
+
+## Mini Team Responsibilities
+
+- **PMA:** orchestration, routing, closure, documentation closure verification
+- **BA:** requirements, acceptance criteria, product documentation
+- **Tech Lead:** implementation, technical verification, review, technical documentation
+
+## Escalation Rule
+
+If the task clearly needs architecture decomposition, Workflow Runner orchestration, or broader specialist support, PMA should stop and ask to switch the repository to `full` team mode or rescope the work.

package/docs/guides/TOOLS.md

@@ -0,0 +1,117 @@
+# Plugin Tools
+
+This page documents the tools provided by the Optima plugin.
+
+## `optima_init`
+
+Initializes Optima in the current repository.
+
+### Arguments
+
+- `team_mode`: `mini` or `full`
+
+### What it creates
+
+- `.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` Optima local/private rules when the target is a git repository
+
+### Notes
+
+- Full repository-local agent definitions or custom agents are optional and can be created later under `.optima/agents/`.
+- Repository-specific additive agent instructions are optional and can be created later under `.optima/agent-additions/`.
+- Generated prompt dumps go to `.optima/.config/generated/agents/` when `features.debug_dumps` is enabled.
+- Generated reference policy files go to `.optima/.config/generated/policies/` when `policies.extract_defaults` is set to `all`.
+- The scaffolded README files in `.optima/agents/` and `.optima/agent-additions/` list common `plugin:` and `policy:` includes that custom agents can reuse.
+- After a successful init, Optima will request the OpenCode instance be disposed so the new config/agents can be reloaded.
+
+## `optima_validate`
+
+Validates Optima workflow artifacts and CodeMap integrity.
+
+It checks things like:
+
+- missing root `.optima/codemap.yml`
+- invalid or broken codemap references
+- missing codemaps in maintained source directories
+- placeholder documentation problems
+- hidden/tool-owned trees such as `.github/workflows/` are ignored
+
+## `optima_start_discussion`
+
+Starts or reopens an automatic discussion transcript for the current session.
+
+### Arguments
+
+Provide exactly one of:
+
+- `title`: title for a new discussion
+- `existing_discussion_id`: existing discussion ID to reopen
+
+Also provide:
+
+- `previous_message_count`: number of earlier **user and assistant** messages from the current session to include before live capture starts or before a discussion is reopened
+
+### Notes
+
+- Use `0` if the discussion starts now.
+- Use `existing_discussion_id` plus `previous_message_count` to reopen an older discussion and include a small amount of newer conversation that happened before the reopen call.
+- Only one active discussion is allowed per session.
+- While active, raw discussion transcripts are stored in `.optima/.config/runtime/discussions/`.
+- The durable workflow artifact is written to `.optima/tasks/discussions/` when the discussion is stopped and summarized.
+- Active discussion state is persisted in `.optima/.config/runtime/discussions.json`.
+- Only discussion-capable agents should use these discussion tools.
+
+## `optima_stop_discussion`
+
+Stops the automatic discussion transcript for the current session.
+
+This tool performs the full close flow synchronously:
+
+- marks the runtime transcript as summarizing
+- invokes `business_analyst` with a blocking prompt to write the structured summary to `.optima/tasks/discussions/`
+- verifies the summary file was written successfully
+- archives the raw runtime transcript
+- returns the final closed result from the tool call itself
+
+## `optima_run_workflow`
+
+Starts a `workflow_runner` session for a complex task.
+
+### Arguments
+
+- `task_path`: path to the task markdown file
+- `instructions`: detailed instructions for the workflow runner
+
+### Notes
+
+- Only available in `full` team mode.
+- Used for `complex` implementation tasks.
+- The runner executes in a separate session and reports completion back to PMA.
+- The runner is expected to orchestrate the lifecycle by validating task readiness, delegating implementation and verification work to specialists, and driving the task to delivery or a hard blocker.
+- For implementation tasks, the runner must create or append a Workflow Execution Plan in the task file after Pre-Task Sync and before implementation starts.
+- The runner must not directly edit product source code, tests, application configuration, or implementation files.
+- When a hard blocker is reached, the runner should end its run and return a final summary starting with `HARD BLOCKER:` so the plugin relays it back to the PMA session.
+
+## `optima_prompt_workflow`
+
+Sends a follow-up prompt to an existing `workflow_runner` session.
+
+### Arguments
+
+- `session_id`: workflow runner session ID
+- `text`: follow-up message for that session
+
+### Notes
+
+- Only available in `full` team mode.
+- Useful for bounce-backs, clarifications, and resumed runner work.

package/docs/guides/WORKFLOW.md

@@ -0,0 +1,116 @@
+# Workflow Usage
+
+Optima uses three task complexity levels and three work tracks.
+
+## Complexity
+
+- `tiny`: Minimal, low-risk work.
+- `standard`: Default bounded delivery work.
+- `complex`: Multi-step work that uses decomposition and the Workflow Runner.
+
+## Track
+
+- `implementation`: Delivery work that changes code, tests, config, or linked docs.
+- `investigation`: Discovery and debugging work intended to produce findings.
+- `spec`: SCR and specification work.
+
+## Slice set
+
+- `foundation`
+- `core`
+- `logic`
+- `ui`
+- `polish`
+- `qa`
+- `docs`
+
+## Routing rules
+
+- Prefer `tiny` when one specialist can complete the task in one slice with lightweight verification.
+- Use `standard` for the normal delivery path when a task is still bounded and does not require decomposition.
+- Use `complex` when the work needs an approved SCR, multiple handoffs, or slice-based subtasks.
+
+## SCR Requirement Rules
+
+- `tiny` + `implementation` + non-behavioral change: SCR optional, `scr: null` allowed
+- `standard` + `implementation`: SCR required
+- `complex` + `implementation`: SCR required
+- `spec`: SCR required by definition
+- `investigation`: SCR optional unless the work is already formalizing a proposed change
+
+## Team modes
+
+- `mini`: supports `tiny` and `standard` only, using `product_manager`, `business_analyst`, and `tech_lead`
+- `full`: supports `tiny`, `standard`, and `complex`, including `workflow_runner`
+
+See also:
+
+- `docs/guides/TEAM_MODE_MINI.md`
+- `docs/guides/TEAM_MODE_FULL.md`
+
+## Current parallelism rule
+
+- One shared-worktree implementation task may run at a time.
+- Investigation and spec tasks may run in parallel when they avoid conflicting edits.
+
+## Task metadata
+
+Task files use lightweight frontmatter to record only durable workflow fields. Use `scr: null` only for `tiny` work that does not change product behavior or shared specifications.
+
+```yaml
+---
+id: TASK-001
+complexity: standard
+track: implementation
+slice: logic
+status: todo
+scr: SCR-001
+parent: null
+assigned_to: product_manager
+handoff_from: null
+---
+```
+
+When PMA, BA, or Tech Lead need to hand workflow-relevant discussion context to one another, use a normal task file with:
+
+- `assigned_to` set to the next responsible agent
+- `handoff_from` set to the agent creating the handoff
+- a detailed `Discussion Record` section in the task body
+
+Track these task files under `Active Discussions` in `.optima/tasks/current.md` until they resolve into execution, SCR work, clarification, or closure.
+
+## Reopen And Resume
+
+- If a task was thought to be done but later needs discrepancies fixed or minor same-scope changes, reopen the same task instead of creating a new one.
+- Move it back into `Active` in `.optima/tasks/current.md`.
+- Keep the same task file ID and record the reason in `Reopen History`.
+- Reuse the same Task tool `task_id` for delegated task work when possible.
+- If the task used `workflow_runner`, reuse both the same Task tool `task_id` and the same Workflow Runner `session_id` when possible.
+
+## Evidence By Track
+
+- `implementation`: produce the normal evidence packet, including logs, screenshots when relevant, and AC coverage.
+- `investigation`: produce findings, reproduction notes, logs when useful, and a recommended next step.
+- `spec`: produce SCR and documentation updates that capture the accepted change definition and product/architecture impact.
+
+SCR files use similarly lightweight frontmatter:
+
+```yaml
+---
+id: SCR-001
+status: proposed
+tasks: []
+---
+```
+
+## Documentation lookup
+
+When deciding where documentation belongs:
+
+- use `docs/product/` for whole-product truth
+- use `docs/domains/` for stable product areas that contain multiple features
+- use `docs/features/` for one concrete capability
+- use `docs/architecture/` for technical design and cross-cutting engineering decisions
+- use `.optima/docs/scrs/` for proposed and approved changes, not steady-state truth
+
+See `docs/core/documentation_structure.md` for the canonical rules.

package/docs/guides/codemap.yml

@@ -0,0 +1,8 @@
+scope: module
+parent: ../codemap.yml
+sources_of_truth:
+  - path: AGENTS.md
+  - path: TEAM_MODE_FULL.md
+  - path: TEAM_MODE_MINI.md
+  - path: TOOLS.md
+  - path: WORKFLOW.md

package/docs/product/DOMAIN_MAP.md

@@ -0,0 +1,41 @@
+# Domain Map
+
+This document maps the major product domains and the features that belong to them.
+
+## How To Use This File
+
+- Add a new domain entry when the product introduces a stable new area of responsibility.
+- Link each feature to one primary domain.
+- Keep this file at the summary level. Put detailed rules and workflows into `docs/domains/<domain>/`.
+
+## Domain Entries
+
+### Agent Orchestration
+
+- **Purpose:** Defines how PMA, Workflow Runner, and specialist agents collaborate.
+- **Owned Features:** Product Manager routing, Workflow Runner handoff, specialist delegation, discussion protocols.
+- **Primary Docs:** `docs/guides/AGENTS.md`, `docs/core/agent_orchestration.md`
+
+### Task Lifecycle
+
+- **Purpose:** Defines how tasks are classified, discussed, executed, verified, and archived.
+- **Owned Features:** `tiny` / `standard` / `complex` routing, pre-sync quorum rules, task templates, evidence expectations.
+- **Primary Docs:** `docs/domains/task-lifecycle/OVERVIEW.md`, `docs/core/task_model.md`, `.optima/tasks/task-template.md`
+
+### Documentation System
+
+- **Purpose:** Defines how product, domain, feature, and architecture truth is organized and maintained.
+- **Owned Features:** documentation hierarchy, ownership model, domain map maintenance, feature specification placement.
+- **Primary Docs:** `docs/core/documentation_structure.md`, `docs/product/FEATURES_LIST.md`
+
+### Validation And Navigation
+
+- **Purpose:** Keeps the repository navigable and structurally correct for humans and agents.
+- **Owned Features:** CodeMap validation, local knowledge rule, source indexing, placeholder detection.
+- **Primary Docs:** `docs/core/codemap_conventions.md`, `codemap.yml`
+
+### Plugin Setup And Configuration
+
+- **Purpose:** Defines how Optima is installed, configured, and enabled in an OpenCode environment.
+- **Owned Features:** plugin installation, OpenCode config wiring, `optima.yaml`, repo-local agent definitions, agent additions, policy overrides.
+- **Primary Docs:** `docs/setup/INSTALLATION.md`, `docs/setup/CONFIGURATION.md`