cortex-agents 2.3.1 → 4.0.0

package/README.md

@@ -2,7 +2,7 @@
   <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>
+<h3 align="center">Structured AI development workflows for <a href="https://opencode.ai">OpenCode</a>.<br>Plan. Build. Ship. With discipline.</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&color=4d96ff" alt="npm version"></a>
@@ -12,159 +12,170 @@
 </p>
 
 <p align="center">
-  <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="#-quick-start">Quick Start</a>&nbsp;&nbsp;&bull;&nbsp;&nbsp;
+  <a href="#-architecture">Architecture</a>&nbsp;&nbsp;&bull;&nbsp;&nbsp;
+  <a href="#-agents">Agents</a>&nbsp;&nbsp;&bull;&nbsp;&nbsp;
+  <a href="#-tools">Tools</a>&nbsp;&nbsp;&bull;&nbsp;&nbsp;
+  <a href="#-skills">Skills</a>&nbsp;&nbsp;&bull;&nbsp;&nbsp;
   <a href="#-contributing">Contributing</a>
 </p>
 
-<br>
-
 ---
 
-<br>
-
 ## Why Cortex Agents?
 
 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.
 
-- **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.
+```
+ Before                                    After
+ ──────                                    ─────
+ AI writes code wherever                   AI checks git status first
+ No branching discipline                   Creates worktrees/branches automatically
+ No documentation                          Generates docs with mermaid diagrams
+ No quality checks                         Runs parallel quality gates (6 sub-agents)
+ No plan, no traceability                  Plans with acceptance criteria, ships PRs
+```
 
-<br>
+---
 
 ## Quick Start
 
 ```bash
 npx cortex-agents install       # Add plugin + agents + skills
 npx cortex-agents configure     # Pick your models interactively
-# Restart OpenCode - done.
+# Restart OpenCode — done.
 ```
 
-That's it. Your OpenCode session now has 8 specialized agents, 23 tools, and 14 domain skills.
+Your OpenCode session now has **12 specialized agents**, **33 tools**, and **16 domain skills**.
 
-<br>
+> **Built-in Agent Replacement** — Cortex automatically disables OpenCode's native `build` and `plan` agents (replaced by `implement` and `architect`). The `architect` agent becomes the default, promoting a planning-first workflow. Native agents are fully restored on `uninstall`.
 
-## What It Does
+---
 
-### Plan, Build, Ship
+## Architecture
 
-Cortex agents follow a structured workflow from planning through to PR:
+### Agent Hierarchy
 
 ```
-You: "Add user authentication"
-
-Plan Agent                              reads codebase, creates plan with mermaid diagrams
-   saves to .cortex/plans/             "Plan saved. Switch to Build?"
-
-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
+User Request
+    |
+    v
+ Architect (read-only planning)
+    |
+    |-- read-only analysis -----> @security  @coder  @perf
+    |
+    v
+ Implement / Fix (execution)
+    |
+    |-- REPL Loop (task-by-task) --> build + test per task
+    |
+    v
+ Quality Gate (two-phase)
+    |
+    |-- Phase 1 (parallel, scope-based):
+    |     @testing  @security  @audit  @docs-writer  @devops  @perf
+    |
+    |-- Phase 2 (cross-agent):
+    |     @testing reacts to @security findings
+    |
+    v
+ quality_gate_summary --> GO / NO-GO / GO-WITH-WARNINGS
+    |
+    v
+ Fix blockers --> task_finalize --> PR
 ```
 
-### Worktree Launcher
-
-Create isolated development environments and launch them instantly:
-
-| 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.
+### The Workflow
 
-**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
+```
+You: "Add user authentication"
 
-One tool to close the loop:
+Architect Agent                         reads codebase, creates plan with mermaid diagrams
+   saves to .cortex/plans/             commits plan to feature branch
+   "Plan committed. Switch to          offers worktree or branch
+    Implement?"
 
+Implement Agent                         loads plan, checks git status
+   repl_init → parses tasks + ACs      iterates task-by-task with build+test
+   Quality Gate → 6 agents in parallel  testing + security + audit + docs + devops + perf
+   quality_gate_summary → GO            aggregates findings, recommends go/no-go
+   task_finalize                        stages, commits, pushes, opens PR
 ```
-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?"
-```
-
-### Auto-Prompted Documentation
 
-After every task, agents prompt you to document what you built:
+### Scope-Based Quality Gate
 
-| 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 |
+Not every change needs a full audit. The quality gate scales with risk:
 
-All docs are saved to `docs/` with an auto-generated `INDEX.md`.
+| Scope | Criteria | Sub-Agents Launched |
+|-------|----------|-------------------|
+| **Trivial** | Docs, comments, formatting | `@docs-writer` only (or skip) |
+| **Low** | Tests, config files | `@testing` |
+| **Standard** | Normal code changes | `@testing` + `@security` + `@audit` + `@docs-writer` |
+| **High** | Auth, payments, crypto, infra, DB migrations | All 6: `@testing` + `@security` + `@audit` + `@docs-writer` + `@devops` + `@perf` |
 
-<br>
+---
 
 ## Agents
 
-### Primary Agents
+### Primary Agents (3)
 
 Handle complex, multi-step work. Use your best model.
 
-| Agent | Role | Superpower |
-|-------|------|-----------|
-| **build** | Full-access development | Skill-aware implementation, worktree launcher, quality gates, task finalizer |
-| **plan** | Read-only analysis | Architectural plans with mermaid diagrams, NFR analysis, hands off to build |
-| **debug** | Deep troubleshooting | Performance debugging, distributed tracing, hotfix workflow |
-| **review** | Code quality assessment | Tech debt scoring, pattern review, refactoring advisor (read-only) |
+| Agent | Role | Key Capabilities |
+|-------|------|-----------------|
+| **architect** | Read-only analysis & planning | Plans with mermaid diagrams, acceptance criteria, NFR analysis. Commits plans to branches. Delegates read-only analysis to `@security`, `@coder`, `@perf`. |
+| **implement** | Full-access development | Skill-aware implementation, REPL loop with ACs, two-phase quality gate, parallel sub-agent orchestration, task finalizer. |
+| **fix** | Quick turnaround bug fixes | Rapid diagnosis, scope-based quality gate, optional REPL loop. Delegates deep debugging to `@debug`. |
 
-### Subagents
+### Sub-Agents (9)
 
-Focused specialists launched **automatically** as parallel quality gates. Each auto-loads its core domain skill for deeper analysis. Use a fast/cheap model.
+Focused specialists launched **automatically** by primary agents. Each auto-loads domain skills for deeper analysis. Use a fast/cheap model.
 
 | Agent | Role | Auto-Loads Skill | Triggered By |
 |-------|------|-----------------|-------------|
-| **@testing** | Writes tests, runs suite, reports coverage | `testing-strategies` | Build (always), Debug (always) |
-| **@security** | OWASP audit, secrets scan, code-level fix patches | `security-hardening` | Build (always), Debug (if security-relevant) |
-| **@fullstack** | Cross-layer implementation + feasibility analysis | Per-layer skills | Build (multi-layer features), Plan (analysis) |
-| **@devops** | CI/CD validation, IaC review, deployment strategy | `deployment-automation` | Build (when CI/Docker/infra files change) |
-
-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.
+| **@testing** | Test writing, suite execution, coverage | `testing-strategies` | Implement (standard+high), Fix (low+standard+high) |
+| **@security** | OWASP audit, secrets scan, threat modeling | `security-hardening` | Implement (standard+high), Fix (standard+high), Architect (read-only) |
+| **@audit** | Code quality, tech debt, pattern review | `code-quality` | Implement (standard+high) |
+| **@docs-writer** | Auto-documentation generation | — | Implement (standard+high) |
+| **@perf** | Complexity analysis, N+1 detection, bundle impact | `performance-optimization` | Implement (high), Fix (high), Architect (read-only) |
+| **@devops** | CI/CD validation, IaC review | `deployment-automation` | Implement (high, or infra files changed) |
+| **@coder** | Cross-layer implementation, feasibility | Per-layer skills | Implement (3+ layers), Architect (feasibility analysis) |
+| **@refactor** | Behavior-preserving restructuring | `design-patterns` + `code-quality` | Implement (refactor plans) |
+| **@debug** | Root cause analysis, troubleshooting | `testing-strategies` | Fix (complex issues) |
+
+Sub-agents 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.
 
 ### Skill Routing
 
-All agents detect the project's technology stack and **automatically load relevant skills** before working. This turns the 14 domain skills from passive knowledge into active intelligence:
+All agents detect the project's technology stack and **automatically load relevant skills** before working:
 
 ```
-Build Agent detects: package.json has React + Express + Prisma
-  → auto-loads: frontend-development, backend-development, database-design, api-design
-  → implements with deep framework-specific knowledge
+Implement Agent detects: package.json has React + Express + Prisma
+  -> auto-loads: frontend-development, backend-development, database-design, api-design
+  -> implements with deep framework-specific knowledge
 ```
 
-<br>
+---
 
 ## Tools
 
-23 tools bundled and auto-registered. No configuration needed.
+33 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 (with toast notifications)
-- `branch_switch` - Safe branch switching
-- `worktree_create` - Isolated worktree in `.worktrees/` (with toast notifications)
-- `worktree_launch` - Launch worktree (terminal/PTY/background)
+- `branch_status` — Current branch + change detection
+- `branch_create` — Convention-named branches (with toast)
+- `branch_switch` — Safe branch switching
+- `worktree_create` — Isolated worktree in `.worktrees/`
 - `worktree_list` / `worktree_remove` / `worktree_open`
 
 </td><td width="50%">
 
 **Planning & Sessions**
 - `plan_save` / `plan_load` / `plan_list` / `plan_delete`
+- `plan_commit` — Commit plan to feature branch
 - `session_save` / `session_list` / `session_load`
 - `cortex_init` / `cortex_status` / `cortex_configure`
 
@@ -172,47 +183,71 @@ Build Agent detects: package.json has React + Express + Prisma
 <tr><td width="50%">
 
 **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`
+- `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%">
 
-**Finalization & Config**
-- `task_finalize` - Stage, commit, push, create PR
+**Finalization**
+- `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
+  - Auto-links issues via `Closes #N`
+- `quality_gate_summary` — Aggregate sub-agent findings, GO/NO-GO recommendation
+
+</td></tr>
+<tr><td colspan="2">
+
+**GitHub Integration**
+- `github_status` — Check `gh` CLI availability, auth, and detect projects
+- `github_issues` — List/filter repo issues by state, labels, milestone, assignee
+- `github_projects` — List GitHub Project boards and their work items
+
+The architect uses these to browse your backlog and seed plans from real issues. Issue numbers stored in plan frontmatter (`issues: [42, 51]`) are automatically appended as `Closes #N` to the PR body.
+
+</td></tr>
+<tr><td colspan="2">
+
+**REPL Loop** — Iterative task-by-task implementation
+- `repl_init` — Initialize loop from plan (parses tasks + ACs, auto-detects build/test)
+- `repl_status` — Current progress, active task with ACs, retry counts
+- `repl_report` — Report outcome (`pass`/`fail`/`skip`) with auto-retry and escalation
+- `repl_resume` — Detect and resume interrupted loop from previous session
+- `repl_summary` — Markdown results table with AC satisfaction for PR body
+
+State persists to `.cortex/repl-state.json` — survives context compaction, session restarts, and agent switches.
 
 </td></tr>
 </table>
 
-<br>
+---
 
 ## Skills
 
-14 domain-specific skill packs loaded on demand via the `skill` tool:
+16 domain-specific skill packs loaded on demand:
 
 | 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>
+| `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 |
+| `monitoring-observability` | Structured logging, metrics, distributed tracing, health checks |
+| `data-engineering` | ETL pipelines, data validation, streaming, message queues, partitioning |
+
+---
 
 ## Model Configuration
 
@@ -224,7 +259,7 @@ npx cortex-agents configure --project  # Per-project (saves to .opencode/models.
 ```
 
 ```
-? Select model for PRIMARY agents:
+? Select model for PRIMARY agents (architect, implement, fix):
   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
@@ -232,40 +267,97 @@ npx cortex-agents configure --project  # Per-project (saves to .opencode/models.
   Kimi K2P5          (kimi)          Optimized for code generation
   Enter custom model ID
 
-? Select model for SUBAGENTS:
+? Select model for SUBAGENTS (debug, coder, testing, security, devops, audit, ...):
   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
 ```
 
-### In-Agent Configuration
+Agents can also configure models mid-session via `cortex_configure` — no need to leave OpenCode.
+
+> Don't see your provider in the picker? Select **"Enter custom model ID"** and type any `provider/model` string.
+
+---
 
-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.
+## How It Works
 
-### Per-Project vs Global
+### Implement Agent — Step by Step
 
-| 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 |
+```
+Step 1   branch_status           Am I on a protected branch?
+Step 2   cortex_status           Is .cortex initialized?
+Step 3   plan_list / plan_load   Is there a plan for this work?
+Step 4   Ask: strategy           Worktree (recommended) or branch?
+Step 5   Execute                 Create worktree/branch
+Step 6   REPL Loop               repl_init -> iterate tasks one-by-one
+  6a     repl_init               Parse tasks + ACs, detect build/test commands
+  6b     repl_status             Get current task with ACs, auto-advance
+  6c     Implement task          Write code to satisfy acceptance criteria
+  6d     Build + test            Run detected build/test commands
+  6e     repl_report             Report pass/fail/skip -> auto-advance or retry
+  6f     Loop                    Repeat 6b-6e until all tasks complete
+Step 7   Quality Gate            Two-phase sub-agent review (scope-based)
+  7a     repl_summary            Generate loop results
+  7b     Assess scope            Classify changed files by risk tier
+  7c     Phase 1                 Launch sub-agents in parallel
+  7d     Phase 2                 Cross-agent reactions (@testing <- @security)
+  7e     quality_gate_summary    Aggregate findings -> GO / NO-GO
+Step 8   Documentation           Review @docs-writer output or prompt user
+Step 9   session_save            Record what was done and why
+Step 10  task_finalize           Commit, push, create PR (with quality gate in body)
+Step 11  Cleanup                 Remove worktree if applicable
+```
 
-Per-project config takes priority. Team members get the same model settings when they clone the repo (`.opencode/models.json` is git-tracked).
+### REPL Loop Example
 
-### Supported Providers
+```
+repl_init("my-plan.md")
+  -> Parses tasks (- [ ] checkboxes) with ACs (- AC: lines)
+  -> Auto-detects: npm run build, npx vitest run
+  -> Creates .cortex/repl-state.json
+
+Loop:
+  repl_status              -> "Task #1: Implement user model"
+                               AC: User model has name, email, password
+                               AC: Email validation rejects malformed addresses
+  [implement task]
+  [run build + tests]
+  repl_report(pass, "42 tests pass")
+                           -> "Task #1 PASSED (1st attempt)"
+                           -> "Next: Task #2"
+
+  repl_status              -> "Task #2: Add API endpoints"
+  [implement task]
+  [run build + tests]
+  repl_report(fail, "POST /users 500")
+                           -> "Task #2 FAILED (attempt 1/3)"
+                           -> "Fix and retry. 2 retries remaining."
+  [fix issue, re-run tests]
+  repl_report(pass, "All green")
+                           -> "Task #2 PASSED (2nd attempt)"
+  ...
+
+repl_summary               -> Markdown table for PR body
+```
 
-| 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 | - |
+### Quality Gate Example
 
-> Don't see your provider? Select **"Enter custom model ID"** and type any `provider/model` string.
+```
+quality_gate_summary receives reports from 6 agents:
+  @testing:     PASS — 12 tests written, all passing
+  @security:    PASS WITH WARNINGS — 1 medium finding (XSS in tooltip)
+  @audit:       PASS — score A, no critical issues
+  @docs-writer: 1 feature doc created
+  @devops:      N/A
+  @perf:        PASS — no regressions, all O(n) or better
+
+  -> Recommendation: GO-WITH-WARNINGS
+  -> Blocker: none
+  -> PR body section auto-generated
+```
 
-<br>
+---
 
 ## Project Structure
 
@@ -273,11 +365,13 @@ Per-project config takes priority. Team members get the same model settings when
 your-project/
   .cortex/                     Project context (auto-initialized)
      config.json              Configuration
-     plans/                   Implementation plans (git tracked)
-     sessions/                Session summaries (gitignored)
+     plans/                   Implementation plans
+     sessions/                Session summaries
+     repl-state.json          REPL loop progress (auto-managed)
+     quality-gate.json        Last quality gate results
   .opencode/
      models.json              Per-project model config (git tracked)
-  .worktrees/                  Git worktrees (gitignored)
+  .worktrees/                  Git worktrees
      feature-auth/            Isolated development copy
      bugfix-login/
   docs/                        Documentation (git tracked)
@@ -287,7 +381,7 @@ your-project/
      flows/                   Process/data flow docs
 ```
 
-<br>
+---
 
 ## CLI Reference
 
@@ -301,87 +395,20 @@ npx cortex-agents uninstall                    # Clean removal of everything
 npx cortex-agents status                       # Show installation and model status
 ```
 
-<br>
-
-## How It Works
-
-### The Build Agent Workflow
-
-Every time the build agent starts, it follows a structured pre-implementation checklist:
-
-```
-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.
-
-### 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:
-
-```
-Agent: build                 Development mode - ready to implement
-Agent: plan                  Planning mode - read-only analysis
-Agent: debug                 Debug mode - troubleshooting and fixes
-Agent: review                Review mode - code quality assessment
-```
-
-The Plan agent creates plans with mermaid diagrams and hands off to Build. Build loads the plan, detects the tech stack, loads relevant skills, and implements. If something breaks, Debug takes over with performance debugging tools. Review provides code quality assessment and tech debt analysis on demand.
-
-<br>
+---
 
 ## Requirements
 
 - [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)
+- [GitHub CLI](https://cli.github.com/) (optional — for PR creation and issue integration)
 
-<br>
+---
 
 ## Contributing
 
-Contributions are welcome! This is an Apache-2.0 licensed project and we'd love your help.
+We welcome contributions of all sizes. Whether it's a typo fix, a new skill pack, or a whole new agent — we appreciate it.
 
 ### Getting Started
 
@@ -390,45 +417,109 @@ git clone https://github.com/ps-carvalho/cortex-agents.git
 cd cortex-agents
 npm install
 npm run build
+npm test                    # 447 tests, all should pass
 ```
 
-### Development Workflow
+### Local Development
 
 ```bash
-# Link for local testing
+# Link for local testing with OpenCode
 npm link
 cd ~/.config/opencode && npm link cortex-agents
 
-# Make changes, rebuild, restart OpenCode
+# Edit, rebuild, restart OpenCode to test
 npm run build
 
 # Unlink when done
 cd ~/.config/opencode && npm unlink cortex-agents && npm install
 ```
 
+### Project Layout
+
+```
+src/
+  index.ts                   Plugin entry point, tool registration, event hooks
+  registry.ts                Agent/model registry constants
+  cli.ts                     CLI (install, configure, uninstall, status)
+  tools/
+    repl.ts                  REPL loop tools (init, status, report, resume, summary)
+    quality-gate.ts          Quality gate aggregation tool
+    cortex.ts                Project initialization tools
+    worktree.ts              Git worktree tools
+    branch.ts                Git branch tools
+    plan.ts                  Plan persistence tools
+    session.ts               Session summary tools
+    docs.ts                  Documentation tools
+    task.ts                  Task finalization tool
+    github.ts                GitHub integration tools
+  utils/
+    repl.ts                  REPL state management, command detection, formatting
+    change-scope.ts          Risk-based file classification
+    plan-extract.ts          Plan parsing utilities
+    shell.ts                 Shell command helpers
+    github.ts                GitHub API helpers
+    worktree-detect.ts       Worktree detection
+  __tests__/                 Test files mirror src/ structure
+.opencode/
+  agents/                    12 agent definition files (.md frontmatter)
+  skills/                    16 skill pack directories (SKILL.md each)
+```
+
 ### What We're Looking For
 
-- **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
+| Type | Examples | Difficulty |
+|------|----------|-----------|
+| **New skills** | Rust, Go, AWS, Terraform, GraphQL | Easy — add a `SKILL.md` file |
+| **New agents** | Reviewer, migration specialist, API designer | Medium — agent `.md` + registry update |
+| **Tool improvements** | Better PR templates, test runners, linter integration | Medium — TypeScript + tests |
+| **Quality gate enhancements** | New parsers for agent report formats, smarter severity mapping | Medium |
+| **Bug fixes** | Anything that doesn't work as expected | Varies |
+| **Documentation** | Guides, examples, tutorials | Easy |
+
+### Adding a New Skill
+
+1. Create `.opencode/skills/your-skill/SKILL.md` with frontmatter (`name`, `description`, `license`, `compatibility`)
+2. Write the skill content — patterns, checklists, examples
+3. Update the skill count in tests if applicable
+4. Submit a PR
+
+### Adding a New Agent
+
+1. Create `.opencode/agents/your-agent.md` with frontmatter (`description`, `mode`, `temperature`, `tools`, `permission`)
+2. Add the agent name to `SUBAGENTS` or `PRIMARY_AGENTS` in `src/registry.ts`
+3. Add an agent description in `AGENT_DESCRIPTIONS` in `src/index.ts`
+4. Update test expectations in `src/__tests__/registry.test.ts`
+5. Submit a PR
 
 ### Submitting Changes
 
 1. Fork the repository
 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
+3. Write tests for new functionality
+4. Ensure all tests pass (`npm test`) and the build is clean (`npm run build`)
+5. Commit with conventional format (`feat:`, `fix:`, `docs:`, `chore:`)
+6. Push and open a Pull Request
 
-<br>
+### Commit Convention
 
-## License
+We use [Conventional Commits](https://www.conventionalcommits.org/):
 
-[Apache-2.0](LICENSE)
+```
+feat: add new capability
+fix: correct a bug
+docs: update documentation
+chore: maintenance, dependencies
+refactor: code restructuring without behavior change
+test: add or update tests
+```
+
+---
+
+## License
 
-<br>
+[Apache-2.0](LICENSE) — use it, modify it, ship it.
 
 <p align="center">
+  <br>
   <sub>Built for the <a href="https://opencode.ai">OpenCode</a> community</sub>
 </p>