cortex-agents 2.1.0 → 2.3.0

package/README.md

@@ -1,486 +1,422 @@
-# cortex-agents
-
 <p align="center">
-  <strong>Model-agnostic agents for OpenCode with agent handover notifications, mermaid documentation, worktree workflow, and plan persistence</strong>
+  <img src="https://img.shields.io/badge/cortex-agents-111?style=for-the-badge&labelColor=111&color=4d96ff" alt="cortex-agents" height="40">
 </p>
 
+<h3 align="center">Supercharge OpenCode with structured workflows, intelligent agents, and automated development practices.</h3>
+
 <p align="center">
-  <a href="https://www.npmjs.com/package/cortex-agents">
-    <img src="https://img.shields.io/npm/v/cortex-agents.svg?style=flat-square" alt="npm version">
-  </a>
-  <a href="https://www.npmjs.com/package/cortex-agents">
-    <img src="https://img.shields.io/npm/dm/cortex-agents.svg?style=flat-square" alt="npm downloads">
-  </a>
-  <a href="https://github.com/your-org/cortex-agents/blob/main/LICENSE">
-    <img src="https://img.shields.io/npm/l/cortex-agents.svg?style=flat-square" alt="license">
-  </a>
-  <a href="https://opencode.ai">
-    <img src="https://img.shields.io/badge/OpenCode-Plugin-blue?style=flat-square" alt="OpenCode Plugin">
-  </a>
+  <a href="https://www.npmjs.com/package/cortex-agents"><img src="https://img.shields.io/npm/v/cortex-agents.svg?style=flat-square&color=4d96ff" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/cortex-agents"><img src="https://img.shields.io/npm/dm/cortex-agents.svg?style=flat-square&color=6bcb77" alt="npm downloads"></a>
+  <a href="https://github.com/ps-carvalho/cortex-agents/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/cortex-agents.svg?style=flat-square&color=ffd93d" alt="license"></a>
+  <a href="https://opencode.ai"><img src="https://img.shields.io/badge/OpenCode-Plugin-4d96ff?style=flat-square" alt="OpenCode Plugin"></a>
 </p>
 
 <p align="center">
-  <a href="#quick-start">Quick Start</a> •
-  <a href="#model-configuration">Model Configuration</a> •
-  <a href="#features">Features</a> •
-  <a href="#agents">Agents</a> •
-  <a href="#tools">Tools</a> •
-  <a href="#documentation-system">Documentation</a>
+  <a href="#-quick-start">Quick Start</a>&nbsp;&nbsp;|&nbsp;&nbsp;
+  <a href="#-what-it-does">What It Does</a>&nbsp;&nbsp;|&nbsp;&nbsp;
+  <a href="#-agents">Agents</a>&nbsp;&nbsp;|&nbsp;&nbsp;
+  <a href="#-tools">Tools</a>&nbsp;&nbsp;|&nbsp;&nbsp;
+  <a href="#-skills">Skills</a>&nbsp;&nbsp;|&nbsp;&nbsp;
+  <a href="#-contributing">Contributing</a>
 </p>
 
----
-
-## Quick Start
-
-```bash
-# 1. Install the plugin
-npx cortex-agents install
-
-# 2. Choose your models interactively
-npx cortex-agents configure
-
-# 3. Restart OpenCode — done!
-```
+<br>
 
 ---
 
-## Model Configuration
+<br>
 
-Cortex agents are **model-agnostic**. You choose which models to use by running the interactive configure command:
+## Why Cortex Agents?
 
-```bash
-npx cortex-agents configure
-```
+AI coding assistants are powerful, but without structure they produce inconsistent results. **Cortex Agents** adds the missing layer: a complete development workflow that turns OpenCode into a disciplined engineering partner.
 
-You'll be prompted to select:
+- **Before**: AI writes code wherever, no branching discipline, no documentation, no plan.
+- **After**: AI checks git status, asks about branching strategy, loads implementation plans, creates docs with architecture diagrams, commits cleanly, and opens PRs.
 
-1. **Primary model** — for `build`, `plan`, and `debug` agents (complex tasks)
-2. **Subagent model** — for `fullstack`, `testing`, `security`, and `devops` agents (focused tasks)
+<br>
 
-### Example
+## Quick Start
 
+```bash
+npx cortex-agents install       # Add plugin + agents + skills
+npx cortex-agents configure     # Pick your models interactively
+# Restart OpenCode - done.
 ```
-$ npx cortex-agents configure
-
-🔧 Cortex Agents — Model Configuration
 
-Primary agents (build, plan, debug) handle complex tasks.
-Use your best available model.
+That's it. Your OpenCode session now has 7 specialized agents, 23 tools, and 14 domain skills.
 
-? Select model for PRIMARY agents:
-❯ Claude Sonnet 4    (anthropic)   Best balance of intelligence and speed
-  Claude Opus 4      (anthropic)   Most capable, best for complex architecture
-  GPT-4.1            (openai)      Fast multimodal model
-  o3                 (openai)      Advanced reasoning model
-  Gemini 2.5 Pro     (google)      Large context window, strong reasoning
-  Kimi K2P5          (kimi)        Optimized for code generation
-  Enter custom model ID
+<br>
 
-✓ Primary model: anthropic/claude-sonnet-4-20250514
+## What It Does
 
-? Select model for SUBAGENTS:
-❯ Claude 3.5 Haiku   (anthropic)   Fast and cost-effective for focused tasks
-  o4 Mini            (openai)      Fast reasoning, cost-effective
-  Gemini 2.5 Flash   (google)      Fast and efficient
-  Same as primary
-  Enter custom model ID
+### Plan, Build, Ship
 
-✓ Subagent model: anthropic/claude-haiku-3.5
+Cortex agents follow a structured workflow from planning through to PR:
 
-✓ Configuration saved to ~/.config/opencode/opencode.json
 ```
+You: "Add user authentication"
 
-### Supported Providers
-
-| Provider | Premium | Standard | Fast |
-|----------|---------|----------|------|
-| **Anthropic** | Claude Opus 4 | Claude Sonnet 4 | Claude 3.5 Haiku |
-| **OpenAI** | o3 | GPT-4.1 | o4 Mini |
-| **Google** | Gemini 2.5 Pro | — | Gemini 2.5 Flash |
-| **xAI** | Grok 3 | — | Grok 3 Mini |
-| **DeepSeek** | DeepSeek R1 | — | DeepSeek Chat |
-| **Kimi** | — | Kimi K2P5 | — |
+Plan Agent                              reads codebase, creates plan with mermaid diagrams
+   saves to .cortex/plans/             "Plan saved. Switch to Build?"
 
-> Don't see your provider? Select **"Enter custom model ID"** and enter any `provider/model` identifier.
-
-### Reconfigure or Reset
-
-```bash
-# Change models at any time
-npx cortex-agents configure
-
-# Reset to OpenCode defaults (removes model config)
-npx cortex-agents configure --reset
+Build Agent                             loads plan, checks git status
+   "You're on main. Create a branch     two-step prompt: strategy -> execution
+    or worktree?"
+   creates feature/user-auth            implements following the plan
+   "Ready to finalize?"                 stages, commits, pushes, opens PR
 ```
 
----
+### Worktree Launcher
 
-## Features
+Create isolated development environments and launch them instantly:
 
-- 🤖 **Model-Agnostic** — Works with any provider: Anthropic, OpenAI, Google, xAI, DeepSeek, Kimi, and more
-- 🔧 **Interactive Configuration** — `npx cortex-agents configure` to select models with arrow-key menus
-- 🔔 **Agent Handover Notifications** — Toast notifications when agents switch, so you always know which mode you're in
-- 📄 **Mermaid Documentation System** — Auto-prompted docs with architecture diagrams for decisions, features, and flows
-- 🌳 **Worktree Workflow** — Create isolated development environments with git worktrees
-- 📋 **Plan Persistence** — Save implementation plans with mermaid diagrams to `.cortex/plans/`
-- 📝 **Session Management** — Record key decisions and context in `.cortex/sessions/`
-- 🔄 **Pre-Implementation Workflow** — Agents ask about branch/worktree strategy before making changes
-- 🎯 **Agent Handoff** — Seamless transition between Plan → Build → Debug agents
-- 📚 **Skills System** — Domain-specific knowledge for web dev, testing, security, and more
+| Mode | What Happens |
+|------|-------------|
+| **New Terminal** | Opens a new terminal tab with OpenCode pre-configured in the worktree |
+| **In-App PTY** | Spawns an embedded terminal inside your current OpenCode session |
+| **Background** | AI implements headlessly while you keep working - toast notifications on completion |
 
----
+Plans are automatically propagated into the worktree's `.cortex/plans/` so the new session has full context.
 
-## Installation
+**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.
 
-### Option 1: Add to OpenCode Config (Recommended)
+### Task Finalizer
 
-Add the plugin to your `opencode.json`:
+One tool to close the loop:
 
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": ["cortex-agents"]
-}
 ```
-
-Then configure your models:
-
-```bash
-npx cortex-agents configure
-```
-
-### Option 2: Use the CLI Helper
-
-```bash
-# Install and configure
-npx cortex-agents install
-npx cortex-agents configure
+task_finalize
+   git add -A
+   git commit -m "feat: add user auth"
+   git push -u origin feature/user-auth
+   gh pr create --base main               auto-detected if in worktree
+       PR body auto-populated from .cortex/plans/
+   "PR created! Clean up worktree?"
 ```
 
-### Option 3: Global npm Install
+### Auto-Prompted Documentation
 
-```bash
-npm install -g cortex-agents
-cortex-agents install
-cortex-agents configure
-```
+After every task, agents prompt you to document what you built:
 
----
+| Type | What's Generated | Includes |
+|------|-----------------|----------|
+| **Decision** | Architecture Decision Record | Mermaid graph comparing options |
+| **Feature** | Feature documentation | Mermaid component diagram |
+| **Flow** | Process/data flow doc | Mermaid sequence diagram |
 
-## CLI Commands
+All docs are saved to `docs/` with an auto-generated `INDEX.md`.
 
-```bash
-npx cortex-agents install              # Add plugin to opencode.json
-npx cortex-agents configure            # Interactive model selection
-npx cortex-agents configure --reset    # Reset to OpenCode default models
-npx cortex-agents uninstall            # Remove plugin, agents, skills, and model config
-npx cortex-agents status               # Show installation and model status
-npx cortex-agents help                 # Show help
-```
-
----
+<br>
 
 ## Agents
 
 ### Primary Agents
 
-These agents handle complex tasks and use your **primary model**:
+Handle complex, multi-step work. Use your best model.
 
-| Agent | Description | Best For |
-|-------|-------------|----------|
-| **build** | Full-access development with branch/worktree workflow | Implementing features, refactoring |
-| **plan** | Read-only analysis with plan persistence and handoff | Architecture decisions, complex planning |
-| **debug** | Deep troubleshooting with hotfix workflow | Bug fixes, production issues |
+| Agent | Role | Superpower |
+|-------|------|-----------|
+| **build** | Full-access development | Two-step branching strategy, worktree launcher, task finalizer, docs prompting |
+| **plan** | Read-only analysis | Creates implementation plans with mermaid diagrams, hands off to build |
+| **debug** | Deep troubleshooting | Full bash/edit access with hotfix workflow |
 
-### Subagents (@mention)
-
-These agents handle focused tasks and use your **subagent model**:
-
-| Agent | Description |
-|-------|-------------|
-| **@fullstack** | End-to-end feature implementation across frontend and backend |
-| **@testing** | Test writing, coverage analysis, and test strategy |
-| **@security** | Security audit and vulnerability detection |
-| **@devops** | CI/CD pipelines and deployment automation |
-
----
-
-## Tools
+### Subagents
 
-All tools are bundled with the plugin and available automatically.
+Focused specialists launched **automatically** as parallel quality gates. Use a fast/cheap model.
 
-### Cortex Management
-- `cortex_init` - Initialize `.cortex` directory with config and templates
-- `cortex_status` - Check cortex status (exists, plan count, session count)
+| 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) |
 
-### Worktree Management
-- `worktree_create <name> <type>` - Create worktree in `../.worktrees/`
-- `worktree_list` - List all worktrees
-- `worktree_remove <name>` - Remove worktree (after merging)
-- `worktree_open <name>` - Get command to open terminal in worktree
+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.
 
-### Branch Management
-- `branch_create <name> <type>` - Create feature/bugfix/hotfix/refactor/docs/test branch
-- `branch_status` - Get current branch, check for uncommitted changes, detect protected branches
-- `branch_switch <branch>` - Switch to existing branch
+<br>
 
-### Plan Management
-- `plan_save <title> <type> <content>` - Save plan to `.cortex/plans/`
-- `plan_list [type]` - List saved plans (optionally filter by type)
-- `plan_load <filename>` - Load a plan
-- `plan_delete <filename>` - Delete a plan
+## Tools
 
-### Session Management
-- `session_save <summary> [decisions]` - Save session summary with key decisions
-- `session_list [limit]` - List recent sessions
-- `session_load <filename>` - Load a session summary
+23 tools bundled and auto-registered. No configuration needed.
 
-### Documentation
-- `docs_init [path]` - Initialize `docs/` directory with decisions, features, and flows folders
-- `docs_save <title> <type> <content>` - Save a documentation file with mermaid diagrams
-- `docs_list [type]` - List documentation files (filter by decision, feature, flow, or all)
-- `docs_index` - Rebuild `docs/INDEX.md` with links to all docs (auto-called by `docs_save`)
+<table>
+<tr><td width="50%">
 
----
+**Git Workflow**
+- `branch_status` - Current branch + change detection
+- `branch_create` - Convention-named branches (with toast notifications)
+- `branch_switch` - Safe branch switching
+- `worktree_create` - Isolated worktree in `.worktrees/` (with toast notifications)
+- `worktree_launch` - Launch worktree (terminal/PTY/background)
+- `worktree_list` / `worktree_remove` / `worktree_open`
 
-## Agent Handover Notifications
+</td><td width="50%">
 
-When agents switch (Plan → Build, Build → Debug, etc.), a **toast notification** appears automatically in the OpenCode TUI:
+**Planning & Sessions**
+- `plan_save` / `plan_load` / `plan_list` / `plan_delete`
+- `session_save` / `session_list` / `session_load`
+- `cortex_init` / `cortex_status` / `cortex_configure`
 
-```
-┌──────────────────────────────────┐
-│  Agent: build                    │
-│  Development mode — ready to     │
-│  implement                       │
-└──────────────────────────────────┘
-```
+</td></tr>
+<tr><td width="50%">
 
-This is fully automatic — no configuration needed. The plugin listens for agent switch events and displays the new agent's name and role context. Notifications last 4 seconds and cover all 7 agents (build, plan, debug, fullstack, testing, security, devops).
+**Documentation**
+- `docs_init` - Set up `docs/` structure
+- `docs_save` - Save doc with mermaid diagrams
+- `docs_list` - Browse all docs
+- `docs_index` - Rebuild `docs/INDEX.md`
 
----
+</td><td width="50%">
 
-## Documentation System
+**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
 
-After completing any task, primary agents (build, debug) prompt:
+</td></tr>
+</table>
 
-> **"Would you like to update project documentation?"**
+<br>
 
-You can create three types of documents, each with a **mandatory mermaid diagram**:
+## Skills
 
-| Type | Template | Diagram Style | Use Case |
-|------|----------|---------------|----------|
-| **Decision** | ADR format (Context → Decision → Rationale → Consequences) | Graph (options comparison) | Architecture/technology choices |
-| **Feature** | Overview → Architecture → Components → Usage | Component diagram | New feature documentation |
-| **Flow** | Overview → Flow Diagram → Steps | Sequence diagram | Process/data flow documentation |
+14 domain-specific skill packs loaded on demand via the `skill` tool:
+
+| Skill | Covers |
+|-------|--------|
+| **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 |
+| **desktop-development** | Electron, Tauri, native desktop application patterns |
+| **database-design** | Schema design, migrations, indexing, query optimization |
+| **api-design** | REST, GraphQL, gRPC, versioning, documentation |
+| **testing-strategies** | Unit, integration, E2E, TDD, coverage strategies |
+| **security-hardening** | OWASP, auth/authz, input validation, secure coding |
+| **deployment-automation** | CI/CD, Docker, Kubernetes, cloud deployment |
+| **architecture-patterns** | Microservices, monorepo, event-driven, CQRS |
+| **design-patterns** | GoF patterns, SOLID principles, DDD |
+| **performance-optimization** | Profiling, caching, lazy loading, bundle optimization |
+| **code-quality** | Refactoring, linting, code review, maintainability |
+| **git-workflow** | Branching strategies, worktrees, rebase vs merge |
+
+<br>
 
-### Setup
+## Model Configuration
 
-Documentation is initialized automatically when you first save a doc. You can also set it up manually:
+Cortex agents are **model-agnostic**. Configure globally or per-project:
 
-```
-docs_init
+```bash
+npx cortex-agents configure            # Global (all projects)
+npx cortex-agents configure --project  # Per-project (saves to .opencode/models.json)
 ```
 
-This creates:
-
 ```
-docs/
-├── INDEX.md            # Auto-generated index (rebuilt on every save)
-├── decisions/          # Architecture Decision Records
-├── features/           # Feature docs with component diagrams
-└── flows/              # Process/data flow docs with sequence diagrams
+? Select model for PRIMARY agents:
+  Claude Sonnet 4    (anthropic)     Best balance of intelligence and speed
+  Claude Opus 4      (anthropic)     Most capable, best for complex architecture
+  GPT-4.1            (openai)        Fast multimodal model
+  Gemini 2.5 Pro     (google)        Large context window, strong reasoning
+  Kimi K2P5          (kimi)          Optimized for code generation
+  Enter custom model ID
+
+? Select model for SUBAGENTS:
+  Claude 3.5 Haiku   (anthropic)     Fast and cost-effective
+  o4 Mini            (openai)        Fast reasoning, cost-effective
+  Gemini 2.5 Flash   (google)        Fast and efficient
+  Same as primary
 ```
 
-### Example: Decision Document
+### In-Agent Configuration
 
-```markdown
----
-title: "Use OAuth2 for Authentication"
-type: decision
-date: 2026-02-22T10:30:00.000Z
-status: accepted
-tags: ["auth", "security"]
-related_files: ["src/auth.ts", "src/middleware/jwt.ts"]
----
+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.
 
-# Decision: Use OAuth2 for Authentication
+### Per-Project vs Global
 
-## Context
-The application needs user authentication with third-party provider support.
+| 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 |
 
-## Decision
-Use OAuth2 with JWT tokens for stateless authentication.
+Per-project config takes priority. Team members get the same model settings when they clone the repo (`.opencode/models.json` is git-tracked).
 
-## Rationale
+### Supported Providers
 
-​```mermaid
-graph TD
-    A[OAuth2 + JWT] -->|Stateless, scalable| B[Selected ✓]
-    C[Session-based auth] -->|Server state required| D[Rejected]
-    E[API keys only] -->|No user identity| F[Rejected]
-​```
+| Provider | Premium | Standard | Fast |
+|----------|---------|----------|------|
+| **Anthropic** | Claude Opus 4 | Claude Sonnet 4 | Claude 3.5 Haiku |
+| **OpenAI** | o3 | GPT-4.1 | o4 Mini |
+| **Google** | Gemini 2.5 Pro | - | Gemini 2.5 Flash |
+| **xAI** | Grok 3 | - | Grok 3 Mini |
+| **DeepSeek** | DeepSeek R1 | - | DeepSeek Chat |
+| **Kimi** | - | Kimi K2P5 | - |
 
-OAuth2 provides industry-standard authorization with broad provider support.
+> Don't see your provider? Select **"Enter custom model ID"** and type any `provider/model` string.
 
-## Consequences
-- All API endpoints require JWT validation middleware
-- Token refresh logic needed on the frontend
-```
+<br>
 
-### Auto-Generated Index
+## Project Structure
 
-Every time you save a document, `docs/INDEX.md` is automatically rebuilt with a table of all docs grouped by type:
+```
+your-project/
+  .cortex/                     Project context (auto-initialized)
+     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/
+  docs/                        Documentation (git tracked)
+     INDEX.md                 Auto-generated index
+     decisions/               Architecture Decision Records
+     features/                Feature docs with diagrams
+     flows/                   Process/data flow docs
+```
 
-```markdown
-# Project Documentation
+<br>
 
-> Auto-generated by cortex-agents. Last updated: 2026-02-22
+## CLI Reference
 
-## 📋 Decisions (2)
+```bash
+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
+```
 
-| Date | Title | Status | Tags |
-|------|-------|--------|------|
-| 2026-02-22 | [Use OAuth2](decisions/2026-02-22-use-oauth2.md) | accepted | auth, security |
+<br>
 
-## 🚀 Features (1)
+## How It Works
 
-| Date | Title | Status | Tags |
-|------|-------|--------|------|
-| 2026-02-22 | [User Auth](features/2026-02-22-user-auth.md) | implemented | auth |
+### The Build Agent Workflow
 
-## 🔄 Flows (1)
+Every time the build agent starts, it follows a structured pre-implementation checklist:
 
-| Date | Title | Tags |
-|------|-------|------|
-| 2026-02-22 | [Login Flow](flows/2026-02-22-login-flow.md) | auth |
+```
+Step 1   branch_status           Am I on a protected branch?
+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           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   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.
 
-## Skills
+### Sub-Agent Quality Gates
 
-Load domain-specific knowledge with the `skill` tool:
+After implementation (Step 7), the build agent **automatically** launches sub-agents in parallel as quality gates:
 
-| Skill | Description |
-|-------|-------------|
-| **git-workflow** | Branching strategies, worktree management, collaborative workflows |
-| **web-development** | Full-stack patterns and best practices |
-| **testing-strategies** | Comprehensive testing approaches |
-| **security-hardening** | Security best practices and patterns |
-| **deployment-automation** | CI/CD pipelines and infrastructure |
-| **code-quality** | Refactoring patterns and maintainability |
+```
+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
 
-## Workflow Example
+### Agent Handover
 
-### Feature Development
+When agents switch, a toast notification tells you what mode you're in:
 
 ```
-User: "I want to add user authentication"
-
-Plan Agent:
-├── Analyzes codebase structure
-├── Creates implementation plan with mermaid diagrams
-├── Saves to .cortex/plans/2024-02-22-feature-user-auth.md
-└── Asks: "Plan saved. Switch to Build agent?"
-
-User: "Yes"
-
-Build Agent:                          🔔 Toast: "Agent: build — Development mode"
-├── Loads plan from .cortex/plans/
-├── Checks git status (detects protected branch)
-├── Asks: "Create branch or worktree?"
-├── Creates feature/user-authentication
-├── Implements following the plan
-├── Saves session summary with key decisions
-├── Asks: "Update project documentation?"
-└── Saves feature doc with mermaid architecture diagram
+Agent: build                 Development mode - ready to implement
+Agent: plan                  Planning mode - read-only analysis
+Agent: debug                 Debug mode - troubleshooting and fixes
 ```
 
----
+The Plan agent creates plans with mermaid diagrams and hands off to Build. Build loads the plan and implements it. If something breaks, Debug takes over with full access.
 
-## Configuration
-
-### opencode.json (after running `configure`)
-
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": ["cortex-agents"],
-  "agent": {
-    "build": { "model": "anthropic/claude-sonnet-4-20250514" },
-    "plan": { "model": "anthropic/claude-sonnet-4-20250514" },
-    "debug": { "model": "anthropic/claude-sonnet-4-20250514" },
-    "fullstack": { "model": "anthropic/claude-haiku-3.5" },
-    "testing": { "model": "anthropic/claude-haiku-3.5" },
-    "security": { "model": "anthropic/claude-haiku-3.5" },
-    "devops": { "model": "anthropic/claude-haiku-3.5" }
-  }
-}
-```
+<br>
 
-> Power users can edit `opencode.json` directly for per-agent model control.
+## Requirements
 
-### .cortex Directory
+- [OpenCode](https://opencode.ai) >= 1.0.0
+- Node.js >= 18.0.0
+- Git (for branch/worktree features)
+- [GitHub CLI](https://cli.github.com/) (optional, for `task_finalize` PR creation)
 
-```
-<project-root>/
-├── .cortex/
-│   ├── config.json         # Project configuration
-│   ├── .gitignore          # Ignores sessions/, keeps plans/
-│   ├── plans/              # Implementation plans (git tracked)
-│   │   └── YYYY-MM-DD-type-slug.md
-│   └── sessions/           # Session summaries (gitignored)
-│       └── YYYY-MM-DD-session-id.md
-└── docs/                   # Project documentation (git tracked)
-    ├── INDEX.md            # Auto-generated index
-    ├── decisions/          # Architecture Decision Records
-    ├── features/           # Feature docs with diagrams
-    └── flows/              # Process/data flow docs
-```
+<br>
 
----
+## Contributing
 
-## Branch Naming Convention
+Contributions are welcome! This is an Apache-2.0 licensed project and we'd love your help.
 
-| Type | Prefix | Example |
-|------|--------|---------|
-| Feature | `feature/` | `feature/user-authentication` |
-| Bugfix | `bugfix/` | `bugfix/login-validation` |
-| Hotfix | `hotfix/` | `hotfix/security-patch` |
-| Refactor | `refactor/` | `refactor/api-cleanup` |
-| Docs | `docs/` | `docs/api-reference` |
-| Test | `test/` | `test/e2e-coverage` |
+### Getting Started
 
----
+```bash
+git clone https://github.com/ps-carvalho/cortex-agents.git
+cd cortex-agents
+npm install
+npm run build
+```
 
-## Requirements
+### Development Workflow
 
-- **OpenCode**: >= 1.0.0
-- **Node.js**: >= 18.0.0
-- **Git**: For branch and worktree features
+```bash
+# Link for local testing
+npm link
+cd ~/.config/opencode && npm link cortex-agents
 
----
+# Make changes, rebuild, restart OpenCode
+npm run build
 
-## Contributing
+# Unlink when done
+cd ~/.config/opencode && npm unlink cortex-agents && npm install
+```
+
+### What We're Looking For
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+- **New skills** - Domain-specific knowledge packs (e.g., Rust, Go, DevOps for AWS)
+- **New agents** - Specialized agents (e.g., reviewer, migration, docs-writer)
+- **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
+
+### Submitting Changes
 
 1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+2. Create your branch (`git checkout -b feature/amazing-feature`)
+3. Commit with conventional format (`git commit -m 'feat: add amazing feature'`)
+4. Push and open a Pull Request
 
----
+<br>
 
 ## License
 
-[Apache-2.0](LICENSE) © OpenCode Contributors
+[Apache-2.0](LICENSE)
 
----
+<br>
 
 <p align="center">
-  Built for the <a href="https://opencode.ai">OpenCode</a> community
+  <sub>Built for the <a href="https://opencode.ai">OpenCode</a> community</sub>
 </p>