cortex-agents 2.2.0 → 2.3.0

package/.opencode/agents/plan.md

@@ -13,6 +13,7 @@ tools:
   grep: true
   cortex_init: true
   cortex_status: true
+  cortex_configure: true
   plan_save: true
   plan_list: true
   plan_load: true
@@ -31,18 +32,66 @@ You are a software architect and analyst. Your role is to analyze codebases, pla
 ## Planning Workflow
 
 ### Step 1: Initialize Cortex
-Run `cortex_status` to check if .cortex exists. If not, run `cortex_init`.
+Run `cortex_status` to check if .cortex exists. If not:
+1. Run `cortex_init`
+2. Check if `./opencode.json` already has agent model configuration. If it does, skip to Step 2.
+3. Use the question tool to ask:
+
+"Would you like to customize which AI models power each agent for this project?"
+
+Options:
+1. **Yes, configure models** - Choose models for primary agents and subagents
+2. **No, use defaults** - Use OpenCode's default model for all agents
+
+If the user chooses to configure models:
+1. Use the question tool to ask "Select a model for PRIMARY agents (build, plan, debug) — these handle complex tasks":
+   - **Claude Sonnet 4** — Best balance of intelligence and speed (anthropic/claude-sonnet-4-20250514)
+   - **Claude Opus 4** — Most capable, best for complex architecture (anthropic/claude-opus-4-20250514)
+   - **o3** — Advanced reasoning model (openai/o3)
+   - **GPT-4.1** — Fast multimodal model (openai/gpt-4.1)
+   - **Gemini 2.5 Pro** — Large context window, strong reasoning (google/gemini-2.5-pro)
+   - **Kimi K2P5** — Optimized for code generation (kimi-for-coding/k2p5)
+   - **Grok 3** — Powerful general-purpose model (xai/grok-3)
+   - **DeepSeek R1** — Strong reasoning, open-source foundation (deepseek/deepseek-r1)
+2. Use the question tool to ask "Select a model for SUBAGENTS (fullstack, testing, security, devops) — a faster/cheaper model works great":
+   - **Same as primary** — Use the same model selected above
+   - **Claude 3.5 Haiku** — Fast and cost-effective (anthropic/claude-haiku-3.5)
+   - **o4 Mini** — Fast reasoning, cost-effective (openai/o4-mini)
+   - **Gemini 2.5 Flash** — Fast and efficient (google/gemini-2.5-flash)
+   - **Grok 3 Mini** — Lightweight and fast (xai/grok-3-mini)
+   - **DeepSeek Chat** — Fast general-purpose chat model (deepseek/deepseek-chat)
+3. Call `cortex_configure` with the selected `primaryModel` and `subagentModel` IDs. If the user chose "Same as primary", pass the primary model ID for both.
+4. Tell the user: "Models configured! Restart OpenCode to apply."
 
 ### Step 2: Check for Existing Plans and Documentation
 Run `plan_list` to see if there are related plans that should be considered.
 Run `docs_list` to check existing project documentation (decisions, features, flows) for context.
 
 ### Step 3: Analyze and Create Plan
+
 - Read relevant files to understand the codebase
 - Review existing documentation (feature docs, flow docs, decision docs) for architectural context
 - Analyze requirements thoroughly
 - Create a comprehensive plan with mermaid diagrams
 
+**Sub-agent assistance for complex plans:**
+
+When the plan involves complex, multi-faceted features, launch sub-agents via the Task tool to gather expert analysis. **Launch multiple sub-agents in a single message for parallel execution when both conditions apply.**
+
+1. **@fullstack sub-agent** — Launch when the feature spans multiple layers (frontend, backend, database, infrastructure). Provide:
+   - The feature requirements or user story
+   - Current codebase structure and technology stack
+   - Ask it to: analyze implementation feasibility, estimate effort, identify challenges and risks, recommend an approach
+
+   Use its feasibility analysis to inform the plan's technical approach, effort estimates, and risk assessment.
+
+2. **@security sub-agent** — Launch when the feature involves authentication, authorization, data handling, cryptography, or external API integrations. Provide:
+   - The feature requirements and current security posture
+   - Any existing auth/security patterns in the codebase
+   - Ask it to: perform a threat model, identify security requirements, flag potential vulnerabilities in the proposed design
+
+   Use its findings to add security-specific tasks and risks to the plan.
+
 ### Step 4: Save the Plan
 Use `plan_save` with:
 - Descriptive title
@@ -56,9 +105,9 @@ Use `plan_save` with:
 "Plan saved to .cortex/plans/. How would you like to proceed?"
 
 Options:
-1. **Switch to Build agent** - Hand off for implementation in this session
-2. **Launch worktree in new terminal** - Create a worktree and open a new terminal tab with the plan auto-loaded
-3. **Launch worktree in background** - Create a worktree and let the AI implement headlessly while you continue
+1. **Launch worktree in new terminal (Recommended)** - Create a worktree and open a new terminal tab with the plan auto-loaded
+2. **Launch worktree in background** - Create a worktree and let the AI implement headlessly while you continue
+3. **Switch to Build agent** - Hand off for implementation in this session
 4. **Switch to Debug agent** - Hand off for investigation/fixing
 5. **Stay in Plan mode** - Continue planning or refine the plan
 6. **End session** - Stop here, plan is saved for later
@@ -188,10 +237,31 @@ sequenceDiagram
 ## Tool Usage
 - `cortex_init` - Initialize .cortex directory
 - `cortex_status` - Check cortex status
+- `cortex_configure` - Save per-project model config to ./opencode.json
 - `plan_save` - Save implementation plan
 - `plan_list` - List existing plans
 - `plan_load` - Load a saved plan
 - `session_save` - Save session summary
 - `branch_status` - Check current git state
 - `skill` - Load architecture and planning skills
-- `@fullstack` subagent - For detailed implementation considerations
+
+## Sub-Agent Orchestration
+
+The following sub-agents are available via the Task tool for analysis assistance. **Launch multiple sub-agents in a single message for parallel execution when both conditions apply.**
+
+| Sub-Agent | Trigger | What It Does | When to Use |
+|-----------|---------|--------------|-------------|
+| `@fullstack` | Feature spans 3+ layers | Feasibility analysis, effort estimation, challenge identification | Step 3 — conditional |
+| `@security` | Feature involves auth/data/crypto/external APIs | Threat modeling, security requirements, vulnerability flags | Step 3 — conditional |
+
+### How to Launch Sub-Agents
+
+Use the **Task tool** with `subagent_type` set to the agent name. Example:
+
+```
+# Parallel launch when both conditions apply:
+Task(subagent_type="fullstack", prompt="Feature: [requirements]. Stack: [tech stack]. Analyze feasibility and estimate effort.")
+Task(subagent_type="security", prompt="Feature: [requirements]. Current auth: [patterns]. Perform threat model and identify security requirements.")
+```
+
+Both will execute in parallel and return their structured reports. Use the results to enrich the plan with implementation details and security considerations.

package/.opencode/agents/security.md

@@ -17,7 +17,66 @@ permission:
 
 You are a security specialist. Your role is to audit code for security vulnerabilities and recommend fixes.
 
+## When You Are Invoked
+
+You are launched as a sub-agent by a primary agent (build, debug, or plan). You run in parallel alongside other sub-agents (typically @testing). You will receive:
+
+- A list of files to audit (created, modified, or planned)
+- A summary of what was implemented, fixed, or planned
+- Specific areas of concern (if any)
+
+**Your job:** Read every listed file, perform a thorough security audit, scan for secrets, and return a structured report with severity-rated findings.
+
+## What You Must Do
+
+1. **Read** every file listed in the input
+2. **Audit** for OWASP Top 10 vulnerabilities (injection, broken auth, XSS, etc.)
+3. **Scan** for hardcoded secrets, API keys, tokens, passwords, and credentials
+4. **Check** input validation, output encoding, and error handling
+5. **Review** authentication, authorization, and session management (if applicable)
+6. **Run** dependency audit if applicable (`npm audit`, `pip-audit`, `cargo audit`)
+7. **Report** results in the structured format below
+
+## What You Must Return
+
+Return a structured report in this **exact format**:
+
+```
+### Security Audit Summary
+- **Files audited**: [count]
+- **Findings**: [count] (CRITICAL: [n], HIGH: [n], MEDIUM: [n], LOW: [n])
+- **Verdict**: PASS / PASS WITH WARNINGS / FAIL
+
+### Findings
+
+#### [CRITICAL/HIGH/MEDIUM/LOW] Finding Title
+- **Location**: `file:line`
+- **Category**: [OWASP category or CWE ID]
+- **Description**: What the vulnerability is
+- **Recommendation**: How to fix it
+- **Evidence**: Code snippet showing the issue
+
+(Repeat for each finding, ordered by severity)
+
+### Secrets Scan
+- **Hardcoded secrets found**: [yes/no] — [details if yes]
+
+### Dependency Audit
+- **Vulnerabilities found**: [count or "not applicable"]
+- **Critical/High**: [details if any]
+
+### Recommendations
+- **Priority fixes** (must do before merge): [list]
+- **Suggested improvements** (can defer): [list]
+```
+
+**Severity guide for the orchestrating agent:**
+- **CRITICAL / HIGH** findings → block finalization, must fix first
+- **MEDIUM** findings → include in PR body as known issues
+- **LOW** findings → note for future work, do not block
+
 ## Core Principles
+
 - Assume all input is malicious
 - Defense in depth (multiple security layers)
 - Principle of least privilege
@@ -86,4 +145,4 @@ You are a security specialist. Your role is to audit code for security vulnerabi
 ## Tools & Commands
 - Check for secrets: `grep -r "password\|secret\|token\|key" --include="*.js" --include="*.ts" --include="*.py"`
 - Dependency audit: `npm audit`, `pip-audit`, `cargo audit`
-- Static analysis: Semgrep, Bandit, ESLint security
+- Static analysis: Semgrep, Bandit, ESLint security

package/.opencode/agents/testing.md

@@ -15,7 +15,51 @@ permission:
 
 You are a testing specialist. Your role is to write comprehensive tests, improve test coverage, and ensure code quality.
 
+## When You Are Invoked
+
+You are launched as a sub-agent by a primary agent (build or debug). You run in parallel alongside other sub-agents (typically @security). You will receive:
+
+- A list of files that were created or modified
+- A summary of what was implemented or fixed
+- The test framework in use (e.g., vitest, jest, pytest, go test)
+
+**Your job:** Read the provided files, understand the implementation, write tests, run them, and return a structured report.
+
+## What You Must Do
+
+1. **Read** every file listed in the input to understand the implementation
+2. **Identify** the test framework and conventions used in the project (check `package.json`, existing `__tests__/` or `*.test.*` files)
+3. **Write** unit tests for all new or modified public functions/classes
+4. **Run** the test suite (`npm test`, `pytest`, `go test`, etc.) to verify:
+   - Your new tests pass
+   - Existing tests are not broken
+5. **Report** results in the structured format below
+
+## What You Must Return
+
+Return a structured report in this **exact format**:
+
+```
+### Test Results Summary
+- **Tests written**: [count] new tests across [count] files
+- **Tests passing**: [count]/[count]
+- **Coverage**: [percentage or "unable to determine"]
+- **Critical gaps**: [list of untested critical paths, or "none"]
+
+### Files Created/Modified
+- `path/to/test/file1.test.ts` — [what it tests]
+- `path/to/test/file2.test.ts` — [what it tests]
+
+### Issues Found
+- [BLOCKING] Description of any test that reveals a bug in the implementation
+- [WARNING] Description of any coverage gap or test quality concern
+- [INFO] Suggestions for additional test coverage
+```
+
+The orchestrating agent will use **BLOCKING** issues to decide whether to proceed with finalization.
+
 ## Core Principles
+
 - Write tests that serve as documentation
 - Test behavior, not implementation details
 - Use appropriate testing levels (unit, integration, e2e)
@@ -85,4 +129,4 @@ describe('FeatureName', () => {
 - Playwright/Cypress for e2e
 - React Testing Library for components
 - Supertest for API testing
-- MSW for API mocking
+- MSW for API mocking

package/README.md

@@ -43,7 +43,7 @@ npx cortex-agents configure     # Pick your models interactively
 # Restart OpenCode - done.
 ```
 
-That's it. Your OpenCode session now has 7 specialized agents, 22 tools, and 14 domain skills.
+That's it. Your OpenCode session now has 7 specialized agents, 23 tools, and 14 domain skills.
 
 <br>
 
@@ -78,6 +78,8 @@ Create isolated development environments and launch them instantly:
 
 Plans are automatically propagated into the worktree's `.cortex/plans/` so the new session has full context.
 
+**Cross-platform terminal support** via the terminal driver system — automatically detects and integrates with tmux, iTerm2, Terminal.app, kitty, wezterm, Konsole, and GNOME Terminal. Tabs opened by the launcher are tracked and automatically closed when the worktree is removed.
+
 ### Task Finalizer
 
 One tool to close the loop:
@@ -120,29 +122,31 @@ Handle complex, multi-step work. Use your best model.
 
 ### Subagents
 
-Focused specialists. Invoked with `@mention`. Use a fast/cheap model.
+Focused specialists launched **automatically** as parallel quality gates. Use a fast/cheap model.
+
+| Agent | Role | Triggered By |
+|-------|------|-------------|
+| **@testing** | Writes tests, runs suite, reports coverage gaps | Build (always), Debug (always) |
+| **@security** | OWASP audit, secrets scan, severity-rated findings | Build (always), Debug (if security-relevant) |
+| **@fullstack** | End-to-end implementation + feasibility analysis | Build (multi-layer features), Plan (analysis) |
+| **@devops** | Config validation, CI/CD best practices | Build (when CI/Docker/infra files change) |
 
-| Agent | Role |
-|-------|------|
-| **@fullstack** | End-to-end feature implementation across frontend + backend |
-| **@testing** | Test writing, coverage analysis, TDD workflow |
-| **@security** | Vulnerability scanning, secure coding review |
-| **@devops** | CI/CD pipelines, Docker, deployment automation |
+Subagents return **structured reports** with severity levels (`BLOCKING`, `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`) that the orchestrating agent uses to decide whether to proceed or fix issues first.
 
 <br>
 
 ## Tools
 
-22 tools bundled and auto-registered. No configuration needed.
+23 tools bundled and auto-registered. No configuration needed.
 
 <table>
 <tr><td width="50%">
 
 **Git Workflow**
 - `branch_status` - Current branch + change detection
-- `branch_create` - Convention-named branches
+- `branch_create` - Convention-named branches (with toast notifications)
 - `branch_switch` - Safe branch switching
-- `worktree_create` - Isolated worktree in `.worktrees/`
+- `worktree_create` - Isolated worktree in `.worktrees/` (with toast notifications)
 - `worktree_launch` - Launch worktree (terminal/PTY/background)
 - `worktree_list` / `worktree_remove` / `worktree_open`
 
@@ -151,7 +155,7 @@ Focused specialists. Invoked with `@mention`. Use a fast/cheap model.
 **Planning & Sessions**
 - `plan_save` / `plan_load` / `plan_list` / `plan_delete`
 - `session_save` / `session_list` / `session_load`
-- `cortex_init` / `cortex_status`
+- `cortex_init` / `cortex_status` / `cortex_configure`
 
 </td></tr>
 <tr><td width="50%">
@@ -164,11 +168,12 @@ Focused specialists. Invoked with `@mention`. Use a fast/cheap model.
 
 </td><td width="50%">
 
-**Finalization**
+**Finalization & Config**
 - `task_finalize` - Stage, commit, push, create PR
   - Auto-detects worktree (targets main)
   - Auto-populates PR from `.cortex/plans/`
   - Warns if docs are missing
+- `cortex_configure` - Set models from within an agent session
 
 </td></tr>
 </table>
@@ -181,7 +186,6 @@ Focused specialists. Invoked with `@mention`. Use a fast/cheap model.
 
 | Skill | Covers |
 |-------|--------|
-| **web-development** | Full-stack patterns, REST/GraphQL, SSR, state management |
 | **frontend-development** | React, Vue, Svelte, CSS architecture, accessibility |
 | **backend-development** | API design, middleware, auth, caching, queue systems |
 | **mobile-development** | React Native, Flutter, native iOS/Android patterns |
@@ -201,10 +205,11 @@ Focused specialists. Invoked with `@mention`. Use a fast/cheap model.
 
 ## Model Configuration
 
-Cortex agents are **model-agnostic**. Pick any provider:
+Cortex agents are **model-agnostic**. Configure globally or per-project:
 
 ```bash
-npx cortex-agents configure
+npx cortex-agents configure            # Global (all projects)
+npx cortex-agents configure --project  # Per-project (saves to .opencode/models.json)
 ```
 
 ```
@@ -223,6 +228,19 @@ npx cortex-agents configure
   Same as primary
 ```
 
+### In-Agent Configuration
+
+Agents can also configure models during a session via the `cortex_configure` tool — no need to leave OpenCode. The agent will prompt you to select models when `.cortex/` is first initialized.
+
+### Per-Project vs Global
+
+| Scope | Where | Use Case |
+|-------|-------|----------|
+| **Global** | `~/.config/opencode/opencode.json` | Default for all projects |
+| **Per-project** | `.opencode/models.json` + `opencode.json` | Different models for different repos |
+
+Per-project config takes priority. Team members get the same model settings when they clone the repo (`.opencode/models.json` is git-tracked).
+
 ### Supported Providers
 
 | Provider | Premium | Standard | Fast |
@@ -246,6 +264,8 @@ your-project/
      config.json              Configuration
      plans/                   Implementation plans (git tracked)
      sessions/                Session summaries (gitignored)
+  .opencode/
+     models.json              Per-project model config (git tracked)
   .worktrees/                  Git worktrees (gitignored)
      feature-auth/            Isolated development copy
      bugfix-login/
@@ -261,11 +281,13 @@ your-project/
 ## CLI Reference
 
 ```bash
-npx cortex-agents install              # Install plugin, agents, and skills
-npx cortex-agents configure            # Interactive model selection
-npx cortex-agents configure --reset    # Reset to OpenCode defaults
-npx cortex-agents uninstall            # Clean removal of everything
-npx cortex-agents status               # Show installation status
+npx cortex-agents install                      # Install plugin, agents, and skills
+npx cortex-agents configure                    # Global model selection
+npx cortex-agents configure --project          # Per-project model selection
+npx cortex-agents configure --reset            # Reset global models
+npx cortex-agents configure --project --reset  # Reset per-project models
+npx cortex-agents uninstall                    # Clean removal of everything
+npx cortex-agents status                       # Show installation and model status
 ```
 
 <br>
@@ -278,20 +300,50 @@ Every time the build agent starts, it follows a structured pre-implementation ch
 
 ```
 Step 1   branch_status           Am I on a protected branch?
-Step 2   cortex_status           Is .cortex initialized?
+Step 2   cortex_status           Is .cortex initialized? Offer model config if new project.
 Step 3   plan_list / plan_load   Is there a plan for this work?
-Step 4   Ask: strategy           Branch or worktree?
-Step 4b  Ask: launch mode        Stay / terminal / PTY / background?
-Step 5   Execute                 Create branch or launch worktree
+Step 4   Ask: strategy           Worktree (recommended) or branch?
+Step 4b  Ask: launch mode        Terminal tab (recommended) / stay / PTY / background?
+Step 5   Execute                 Create worktree/branch, auto-detect terminal
 Step 6   Implement               Write code following the plan
-Step 7   Ask: documentation      Decision doc / feature doc / flow doc?
-Step 8   session_save            Record what was done and why
-Step 9   task_finalize           Commit, push, create PR
-Step 10  Ask: cleanup            Remove worktree? (if applicable)
+Step 7   Quality Gate            Launch @testing + @security in parallel
+Step 8   Ask: documentation      Decision doc / feature doc / flow doc?
+Step 9   session_save            Record what was done and why
+Step 10  task_finalize           Commit, push, create PR
+Step 11  Ask: cleanup            Remove worktree + close terminal tab? (if applicable)
 ```
 
 This isn't just documentation - it's enforced by the agent's instructions. The AI follows this workflow every time.
 
+### Sub-Agent Quality Gates
+
+After implementation (Step 7), the build agent **automatically** launches sub-agents in parallel as quality gates:
+
+```
+Build Agent completes implementation
+   |
+   +-- launches in parallel (single message) --+
+   |                                            |
+   v                                            v
+@testing                                   @security
+  Writes unit tests                          OWASP audit
+  Runs test suite                            Secrets scan
+  Reports coverage                           Severity ratings
+  Returns: PASS/FAIL                         Returns: PASS/FAIL
+   |                                            |
+   +-------- results reviewed by Build ---------+
+   |
+   v
+Quality Gate Summary included in PR body
+```
+
+The debug agent uses the same pattern: `@testing` for regression tests (always) and `@security` when the fix touches sensitive code.
+
+Sub-agents use **structured return contracts** so results are actionable:
+- `BLOCKING` / `CRITICAL` / `HIGH` findings block finalization
+- `MEDIUM` findings are noted in the PR body
+- `LOW` findings are deferred
+
 ### Agent Handover
 
 When agents switch, a toast notification tells you what mode you're in:
@@ -346,7 +398,7 @@ cd ~/.config/opencode && npm unlink cortex-agents && npm install
 
 - **New skills** - Domain-specific knowledge packs (e.g., Rust, Go, DevOps for AWS)
 - **New agents** - Specialized agents (e.g., reviewer, migration, docs-writer)
-- **Platform support** - Improve terminal detection for Linux/Windows
+- **Terminal drivers** - Improve detection/support for additional terminal emulators
 - **Tool improvements** - Better PR templates, test runners, linter integration
 - **Bug fixes** - Anything that doesn't work as expected