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                                    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

Interview-First Planning

The Architect agent doesn't jump straight to solutions. Before creating any plan, it conducts a structured conversation:

1. Acknowledge & Clarify — Summarizes your request and asks 3-5 targeted questions about scope, constraints, and success criteria
2. Deepen Understanding — Follows up on unclear areas, identifies risks, presents trade-offs
3. Readiness Check — Presents problem statement + proposed approach + assumptions, asks for your approval
4. Plan Review — Only saves the plan after you explicitly approve it

This ensures you get plans that actually solve the right problem — not AI hallucinations.

Quick Start

npx cortex-agents install       # Add plugin + agents + skills
npx cortex-agents configure     # Pick your models interactively
# Restart OpenCode — done.

Your OpenCode session now has 12 specialized agents, 33 tools, and 17 domain skills.

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.

Architecture

Agent Hierarchy

User Request
    |
    v
 Architect (read-only planning)
    |
     |-- read-only analysis -----> @security  @explore  @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

The Workflow

You: "Add user authentication"

Architect Agent                         reads codebase, creates plan with mermaid diagrams
   saves to .cortex/plans/             commits plan on current branch
   "Plan committed. Proceed?"          offers worktree, branch, or stay

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

Scope-Based Quality Gate

Not every change needs a full audit. The quality gate scales with risk:

| 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 |

Agents

Primary Agents (3)

Handle complex, multi-step work. Use your best model.

| Agent | Role | Key Capabilities | |-------|------|-----------------| | architect | Read-only analysis & planning | Plans with mermaid diagrams, acceptance criteria, NFR analysis. Conducts mandatory requirements interview and plan review before saving. Commits plans and defers branch creation to handoff. Delegates read-only analysis to @explore, @security, @perf only. | | 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. |

Sub-Agents (9)

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 | 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) | | @explore | Read-only codebase exploration | — | Architect only (read-only analysis) | | @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) | | @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:

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

Design Spec Enforcement

All UI work is governed by a mandatory design spec (.cortex/design-spec.md). When any agent loads the ui-design skill:

1. Check — looks for .cortex/design-spec.md
2. Create if missing — analyzes the entire app (components, styles, Tailwind config, theme files, CSS variables) and synthesizes a spec covering brand identity, color palette, typography, spacing, component patterns, and look & feel
3. Follow it — every color, font, spacing value, and component pattern must align with the spec
4. Extend it — if a task needs something not in the spec, the spec is updated first

This ensures visual consistency across all agents and sessions — no more one-off colors, mismatched radii, or inconsistent button styles.

Tools

33 tools bundled and auto-registered. No configuration needed.

Git Workflow

• 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

Planning & Sessions

• plan_save / plan_load / plan_list / plan_delete
• plan_commit — Commit plan artifacts on current branch (branch creation deferred to handoff)
• session_save / session_list / session_load
• cortex_init / cortex_status / cortex_configure

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

Finalization

• task_finalize — Stage, commit, push, create PR
  • Auto-detects worktree (targets main)
  • Auto-populates PR from .cortex/plans/
  • Auto-links issues via Closes #N
• quality_gate_summary — Aggregate sub-agent findings, GO/NO-GO recommendation

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.

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.

Skills

17 domain-specific skill packs loaded on demand:

| Skill | Covers | |-------|--------| | frontend-development | React, Vue, Svelte, CSS architecture, accessibility | | ui-design | Visual hierarchy, typography, color systems, spacing, motion, professional polish. Enforces a mandatory design spec (.cortex/design-spec.md) — auto-creates from codebase analysis if missing, ensuring brand consistency across all UI work. | | 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

Cortex agents are model-agnostic. Configure globally or per-project:

npx cortex-agents configure            # Global (all projects)
npx cortex-agents configure --project  # Per-project (saves to .opencode/models.json)

? 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
  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 (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

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.

How It Works

Implement Agent — Step by Step

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

REPL Loop Example

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

Quality Gate Example

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

Project Structure

your-project/
  .cortex/                     Project context (auto-initialized)
     config.json              Configuration
     design-spec.md           UI design spec — branding, colors, typography, patterns
     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
     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

CLI Reference

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

Requirements

• OpenCode >= 1.0.0
• Node.js >= 18.0.0
• Git (for branch/worktree features)
• GitHub CLI (optional — for PR creation and issue integration)

Contributing

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

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

Local Development

# Link for local testing with OpenCode
npm link
cd ~/.config/opencode && npm link cortex-agents

# 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/                    17 skill pack directories (SKILL.md each)

What We're Looking For

| 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. 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

Commit Convention

We use Conventional Commits:

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

Apache-2.0 — use it, modify it, ship it.