cortex-agents 2.3.1 → 3.4.0

package/README.md

@@ -43,7 +43,9 @@ npx cortex-agents configure     # Pick your models interactively
 # Restart OpenCode - done.
 ```
 
-That's it. Your OpenCode session now has 8 specialized agents, 23 tools, and 14 domain skills.
+That's it. Your OpenCode session now has 8 specialized agents, 32 tools, and 14 domain skills.
+
+> **Built-in Agent Replacement** — When installed, cortex-agents 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`.
 
 <br>
 
@@ -56,10 +58,10 @@ Cortex agents follow a structured workflow from planning through to PR:
 ```
 You: "Add user authentication"
 
-Plan Agent                              reads codebase, creates plan with mermaid diagrams
-   saves to .cortex/plans/             "Plan saved. Switch to Build?"
+Architect Agent                         reads codebase, creates plan with mermaid diagrams
+   saves to .cortex/plans/             "Plan saved. Switch to Implement?"
 
-Build Agent                             loads plan, checks git status
+Implement 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
@@ -72,13 +74,19 @@ Create isolated development environments and launch them instantly:
 
 | Mode | What Happens |
 |------|-------------|
+| **IDE Terminal** | Opens in your detected IDE (VS Code, Cursor, Windsurf, Zed) with integrated terminal |
 | **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.
 
-**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.
+**IDE-Aware Launch Options** — The launcher detects your development environment and offers contextual options:
+- **VS Code / Cursor / Windsurf / Zed**: "Open in [IDE] (Recommended)" as the first option
+- **JetBrains IDEs**: Terminal tab with manual IDE opening instructions
+- **Terminal only**: Standard terminal tab options
+
+**Cross-platform terminal support** via the terminal driver system — automatically detects and integrates with VS Code, Cursor, Windsurf, Zed, JetBrains IDEs, 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
 
@@ -116,10 +124,10 @@ 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) |
+| **implement** | Full-access development | Skill-aware implementation, worktree launcher, quality gates, task finalizer |
+| **architect** | Read-only analysis | Architectural plans with mermaid diagrams, NFR analysis, hands off to implement |
+| **fix** | Deep troubleshooting | Performance debugging, distributed tracing, hotfix workflow |
+| **audit** | Code quality assessment | Tech debt scoring, pattern review, refactoring advisor (read-only) |
 
 ### Subagents
 
@@ -127,10 +135,10 @@ Focused specialists launched **automatically** as parallel quality gates. Each a
 
 | 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) |
+| **@qa** | Writes tests, runs suite, reports coverage | `testing-strategies` | Implement (always), Fix (always) |
+| **@guard** | OWASP audit, secrets scan, code-level fix patches | `security-hardening` | Implement (always), Fix (if security-relevant) |
+| **@crosslayer** | Cross-layer implementation + feasibility analysis | Per-layer skills | Implement (multi-layer features), Architect (analysis) |
+| **@ship** | CI/CD validation, IaC review, deployment strategy | `deployment-automation` | Implement (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.
 
@@ -139,7 +147,7 @@ Subagents return **structured reports** with severity levels (`BLOCKING`, `CRITI
 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:
 
 ```
-Build Agent detects: package.json has React + Express + Prisma
+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
 ```
@@ -148,7 +156,7 @@ Build Agent detects: package.json has React + Express + Prisma
 
 ## Tools
 
-23 tools bundled and auto-registered. No configuration needed.
+32 tools bundled and auto-registered. No configuration needed.
 
 <table>
 <tr><td width="50%">
@@ -167,6 +175,7 @@ Build Agent detects: package.json has React + Express + Prisma
 - `plan_save` / `plan_load` / `plan_list` / `plan_delete`
 - `session_save` / `session_list` / `session_load`
 - `cortex_init` / `cortex_status` / `cortex_configure`
+- `detect_environment` - Detect IDE/terminal for contextual launch options
 
 </td></tr>
 <tr><td width="50%">
@@ -183,9 +192,31 @@ Build Agent detects: package.json has React + Express + Prisma
 - `task_finalize` - Stage, commit, push, create PR
   - Auto-detects worktree (targets main)
   - Auto-populates PR from `.cortex/plans/`
+  - Auto-links issues via `Closes #N` from plan metadata
   - Warns if docs are missing
 - `cortex_configure` - Set models from within an agent session
 
+</td></tr>
+<tr><td colspan="2">
+
+**GitHub Integration**
+- `github_status` - Check `gh` CLI availability, authentication, and detect GitHub Projects
+- `github_issues` - List/filter repo issues by state, labels, milestone, assignee
+- `github_projects` - List GitHub Project boards and their work items
+
+The architect agent uses these tools to browse your backlog and seed plans from real GitHub issues. Issue numbers are stored in plan frontmatter (`issues: [42, 51]`) and automatically appended as `Closes #N` to the PR body when `task_finalize` runs — GitHub auto-closes the issues when the PR merges. Supports both github.com and GitHub Enterprise Server URLs.
+
+</td></tr>
+<tr><td colspan="2">
+
+**REPL Loop** (Iterative Task-by-Task Implementation)
+- `repl_init` - Initialize a loop from a plan (parses tasks, auto-detects build/test commands)
+- `repl_status` - Get current progress, active task, retry counts (auto-advances to next task)
+- `repl_report` - Report task outcome (`pass`/`fail`/`skip`) with auto-retry and escalation
+- `repl_summary` - Generate markdown summary table for PR body
+
+The implement agent uses these tools to work through plan tasks one at a time, running build+test verification after each task. Failed tasks are automatically retried (up to a configurable limit) before escalating to the user. State is persisted to `.cortex/repl-state.json` so progress survives context compaction and session restarts.
+
 </td></tr>
 </table>
 
@@ -273,8 +304,9 @@ 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)
+     plans/                   Implementation plans (gitignored)
      sessions/                Session summaries (gitignored)
+     repl-state.json          REPL loop progress (gitignored, auto-managed)
   .opencode/
      models.json              Per-project model config (git tracked)
   .worktrees/                  Git worktrees (gitignored)
@@ -305,9 +337,9 @@ npx cortex-agents status                       # Show installation and model sta
 
 ## How It Works
 
-### The Build Agent Workflow
+### The Implement Agent Workflow
 
-Every time the build agent starts, it follows a structured pre-implementation checklist:
+Every time the implement agent starts, it follows a structured pre-implementation checklist:
 
 ```
 Step 1   branch_status           Am I on a protected branch?
@@ -316,8 +348,14 @@ 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 6   REPL Loop               If plan loaded: repl_init → iterate tasks one-by-one
+  6a     repl_init               Parse plan tasks, auto-detect build/test commands
+  6b     repl_status             Get current task, auto-advance from pending
+  6c     Implement task          Write code for the current task only
+  6d     Build + test            Run detected build/test commands
+  6e     repl_report             Report pass/fail/skip → auto-advance or retry
+  6f     Repeat 6b-6e            Until all tasks done or user intervenes
+Step 7   Quality Gate            Launch @qa + @guard in parallel (includes repl_summary)
 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
@@ -328,45 +366,83 @@ This isn't just documentation - it's enforced by the agent's instructions. The A
 
 ### Sub-Agent Quality Gates
 
-After implementation (Step 7), the build agent **automatically** launches sub-agents in parallel as quality gates:
+After implementation (Step 7), the implement agent **automatically** launches sub-agents in parallel as quality gates:
 
 ```
-Build Agent completes implementation
+Implement Agent completes implementation
    |
    +-- launches in parallel (single message) --+
    |                                            |
    v                                            v
-@testing                                   @security
+@qa                                        @guard
   Writes unit tests                          OWASP audit
   Runs test suite                            Secrets scan
   Reports coverage                           Severity ratings
   Returns: PASS/FAIL                         Returns: PASS/FAIL
    |                                            |
-   +-------- results reviewed by Build ---------+
+   +------ results reviewed by Implement ------+
    |
    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.
+The fix agent uses the same pattern: `@qa` for regression tests (always) and `@guard` 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
 
+### REPL Loop (Iterative Implementation)
+
+When a plan is loaded, the implement agent activates a **Read-Eval-Print Loop** that works through tasks one at a time with build+test verification after each:
+
+```
+repl_init("my-plan.md")
+  → Parses plan tasks (- [ ] checkboxes)
+  → Auto-detects: npm run build, npx vitest run (vitest)
+  → Creates .cortex/repl-state.json
+
+Loop:
+  repl_status                    → "Task #1: Implement user model"
+  [agent implements task]
+  [agent runs build + tests]
+  repl_report(pass, "42 tests pass")  → "✓ Task #1 PASSED (1st attempt)"
+                                       → "→ Next: Task #2"
+
+  repl_status                    → "Task #2: Add API endpoints"
+  [agent implements task]
+  [agent runs build + tests]
+  repl_report(fail, "POST /users 500") → "⚠ Task #2 FAILED (attempt 1/3)"
+                                        → "Fix and retry. 2 retries remaining."
+  [agent fixes the issue]
+  [agent runs build + tests]
+  repl_report(pass, "All green")  → "✓ Task #2 PASSED (2nd attempt)"
+                                   → "→ Next: Task #3"
+  ...
+
+repl_summary                     → Markdown table for PR body
+```
+
+**Key behaviors:**
+- **Opt-in**: Only activates when a plan is loaded. No-plan sessions use the standard linear workflow.
+- **Auto-detection**: Scans `package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, `Makefile`, `mix.exs` for build/test/lint commands.
+- **Retry with escalation**: Failed tasks retry up to `maxRetries` (default: 3) before asking the user how to proceed.
+- **Persistent state**: Progress saved to `.cortex/repl-state.json` — survives context compaction, session restarts, and agent switches.
+- **Skip support**: Tasks can be skipped with a reason, which is tracked in the summary.
+
 ### 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
+Agent: implement              Development mode - ready to implement
+Agent: architect             Planning mode - read-only analysis
+Agent: fix                   Debug mode - troubleshooting and fixes
+Agent: audit                 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.
+The Architect agent creates plans with mermaid diagrams and hands off to Implement. Implement loads the plan, detects the tech stack, loads relevant skills, and implements. If something breaks, Fix takes over with performance debugging tools. Audit provides code quality assessment and tech debt analysis on demand.
 
 <br>
 
@@ -375,7 +451,7 @@ The Plan agent creates plans with mermaid diagrams and hands off to Build. Build
 - [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 `task_finalize` PR creation and `github_*` tools)
 
 <br>
 

package/dist/cli.js

@@ -3,8 +3,8 @@ import * as fs from "fs";
 import * as path from "path";
 import { fileURLToPath } from "url";
 import prompts from "prompts";
-import { PRIMARY_AGENTS, SUBAGENTS, ALL_AGENTS, getPrimaryChoices, getSubagentChoices, } from "./registry.js";
-const VERSION = "2.3.0";
+import { PRIMARY_AGENTS, SUBAGENTS, ALL_AGENTS, DISABLED_BUILTIN_AGENTS, STALE_AGENT_FILES, getPrimaryChoices, getSubagentChoices, } from "./registry.js";
+const VERSION = "3.4.0";
 const PLUGIN_NAME = "cortex-agents";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -138,6 +138,23 @@ function installAgentsAndSkills(targetDir) {
         console.log(`  Installed ${count} skills -> ${skillsDest}`);
     }
 }
+function cleanupStaleAgents(globalDir) {
+    const agentsDir = path.join(globalDir, "agents");
+    if (!fs.existsSync(agentsDir))
+        return;
+    for (const file of STALE_AGENT_FILES) {
+        const filePath = path.join(agentsDir, file);
+        try {
+            if (fs.existsSync(filePath)) {
+                fs.unlinkSync(filePath);
+                console.log(`  Cleaned up stale agent: ${file}`);
+            }
+        }
+        catch (err) {
+            console.warn(`  Warning: Could not remove stale agent ${file}: ${err.message}`);
+        }
+    }
+}
 function removeAgentsAndSkills(targetDir) {
     const agentsSrc = path.join(PACKAGE_OPENCODE_DIR, "agents");
     const skillsSrc = path.join(PACKAGE_OPENCODE_DIR, "skills");
@@ -173,9 +190,15 @@ function install() {
             fs.mkdirSync(globalDir, { recursive: true });
         }
         const globalPath = path.join(globalDir, "opencode.json");
+        const disabledAgents = {};
+        for (const name of DISABLED_BUILTIN_AGENTS) {
+            disabledAgents[name] = { disable: true };
+        }
         const newConfig = {
             $schema: "https://opencode.ai/config.json",
             plugin: [PLUGIN_NAME],
+            default_agent: "architect",
+            agent: disabledAgents,
         };
         writeConfig(globalPath, newConfig);
         console.log(`Created config: ${globalPath}`);
@@ -187,16 +210,26 @@ function install() {
             config.plugin = [];
         if (!config.plugin.includes(PLUGIN_NAME)) {
             config.plugin.push(PLUGIN_NAME);
-            writeConfig(configInfo.path, config);
-            console.log(`Added plugin to config: ${configInfo.path}\n`);
         }
-        else {
-            console.log(`Plugin already in config: ${configInfo.path}\n`);
+        // Disable built-in agents that cortex-agents replaces
+        if (!config.agent)
+            config.agent = {};
+        for (const name of DISABLED_BUILTIN_AGENTS) {
+            if (!config.agent[name])
+                config.agent[name] = {};
+            config.agent[name].disable = true;
         }
+        // Set default_agent, clean legacy camelCase key
+        config.default_agent = "architect";
+        delete config.defaultAgent;
+        writeConfig(configInfo.path, config);
+        console.log(`Updated config: ${configInfo.path}\n`);
     }
     // Copy agents and skills into the global opencode config dir
     console.log("Installing agents and skills...");
     installAgentsAndSkills(globalDir);
+    // Clean up stale agent files from previous cortex-agents versions
+    cleanupStaleAgents(globalDir);
     // Sync per-project models if .opencode/models.json exists
     if (hasProjectModelsConfig()) {
         console.log("\nPer-project model config found (.opencode/models.json)");
@@ -233,11 +266,23 @@ function uninstall() {
                 }
             }
         }
+        // Re-enable built-in agents
+        for (const name of DISABLED_BUILTIN_AGENTS) {
+            if (config.agent[name]) {
+                delete config.agent[name].disable;
+                if (Object.keys(config.agent[name]).length === 0) {
+                    delete config.agent[name];
+                }
+            }
+        }
         // Clean up empty agent object
         if (Object.keys(config.agent).length === 0) {
             delete config.agent;
         }
     }
+    // Remove default_agent + clean legacy key
+    delete config.default_agent;
+    delete config.defaultAgent;
     writeConfig(configInfo.path, config);
     // Remove agents and skills
     const globalDir = getGlobalDir();
@@ -276,6 +321,12 @@ async function configure() {
             config.plugin = [];
         config.plugin.push(PLUGIN_NAME);
     }
+    // Set default agent to architect (planning-first workflow)
+    if (!config.default_agent) {
+        config.default_agent = "architect";
+    }
+    // Clean legacy camelCase key
+    delete config.defaultAgent;
     // ── Primary model selection ────────────────────────────────
     const { primary, subagent } = await promptModelSelection();
     // ── Write config ───────────────────────────────────────────
@@ -283,6 +334,14 @@ async function configure() {
         // Per-project: write .opencode/models.json + sync to local opencode.json
         writeProjectModels(primary, subagent);
         syncProjectModelsToConfig();
+        // Ensure default agent is set in local opencode.json
+        const localConfig = readConfig(path.join(process.cwd(), "opencode.json"));
+        if (!localConfig.default_agent) {
+            localConfig.default_agent = "architect";
+        }
+        // Clean legacy camelCase key
+        delete localConfig.defaultAgent;
+        writeConfig(path.join(process.cwd(), "opencode.json"), localConfig);
         const modelsPath = getProjectModelsPath();
         const localConfigPath = path.join(process.cwd(), "opencode.json");
         console.log("━".repeat(50));
@@ -304,6 +363,12 @@ async function configure() {
                 config.agent[name] = {};
             config.agent[name].model = subagent;
         }
+        // Re-assert disable entries for built-in agents
+        for (const name of DISABLED_BUILTIN_AGENTS) {
+            if (!config.agent[name])
+                config.agent[name] = {};
+            config.agent[name].disable = true;
+        }
         const targetPath = configInfo?.path || path.join(getGlobalDir(), "opencode.json");
         writeConfig(targetPath, config);
         console.log("━".repeat(50));
@@ -330,7 +395,7 @@ async function promptModelSelection() {
         description: "provider/model format",
         value: "__custom__",
     });
-    console.log("Primary agents (build, plan, debug, review) handle complex tasks.\nUse your best available model.\n");
+    console.log("Primary agents (implement, architect, fix, audit) handle complex tasks.\nUse your best available model.\n");
     const { primaryModel } = await prompts({
         type: "select",
         name: "primaryModel",
@@ -364,7 +429,7 @@ async function promptModelSelection() {
         description: "provider/model format",
         value: "__custom__",
     });
-    console.log("Subagents (fullstack, testing, security, devops) handle focused tasks.\nA faster/cheaper model works great here.\n");
+    console.log("Subagents (crosslayer, qa, guard, ship) handle focused tasks.\nA faster/cheaper model works great here.\n");
     const { subagentModel } = await prompts({
         type: "select",
         name: "subagentModel",
@@ -566,18 +631,20 @@ EXAMPLES:
   npx ${PLUGIN_NAME} status                     # Check status
 
 AGENTS:
-  Primary (build, plan, debug, review):
+  Primary (implement, architect, fix, audit):
     Handle complex tasks — select your best model.
 
-  Subagents (fullstack, testing, security, devops):
+  Subagents (crosslayer, qa, guard, ship):
     Handle focused tasks — a fast/cheap model works great.
 
-TOOLS (23):
+TOOLS (32):
   cortex_init, cortex_status      .cortex directory management
   cortex_configure                Per-project model configuration
   worktree_create, worktree_list  Git worktree management
   worktree_remove, worktree_open
   worktree_launch                 Launch worktree (terminal/PTY/background)
+  detect_environment              Detect IDE/terminal for launch options
+  get_environment_info            Quick environment info for agents
   branch_create, branch_status    Git branch operations
   branch_switch
   plan_save, plan_list            Plan persistence
@@ -587,13 +654,17 @@ TOOLS (23):
   docs_init, docs_save            Mermaid documentation
   docs_list, docs_index
   task_finalize                   Commit, push, and create PR
+  github_status, github_issues    GitHub issue and project browsing
+  github_projects
+  repl_init, repl_status          Iterative task-by-task implementation loop
+  repl_report, repl_summary
 
 SKILLS (14):
-  web-development, frontend-development, backend-development,
-  mobile-development, desktop-development, database-design,
-  api-design, architecture-patterns, design-patterns,
-  testing-strategies, security-hardening, deployment-automation,
-  performance-optimization, code-quality, git-workflow
+  frontend-development, backend-development, mobile-development,
+  desktop-development, database-design, api-design,
+  architecture-patterns, design-patterns, testing-strategies,
+  security-hardening, deployment-automation, performance-optimization,
+  code-quality, git-workflow
 `);
 }
 // ─── CLI Entry Point ─────────────────────────────────────────────────────────

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAmJlD,eAAO,MAAM,YAAY,EAAE,MAuJ1B,CAAC;AAGF,eAAe,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAiLlD,eAAO,MAAM,YAAY,EAAE,MAsK1B,CAAC;AAGF,eAAe,YAAY,CAAC"}

package/dist/index.js

@@ -6,15 +6,19 @@ import * as plan from "./tools/plan";
 import * as session from "./tools/session";
 import * as docs from "./tools/docs";
 import * as task from "./tools/task";
+import * as environment from "./tools/environment";
+import * as github from "./tools/github";
+import * as repl from "./tools/repl";
 // ─── Agent Descriptions (for handover toasts) ───────────────────────────────
 const AGENT_DESCRIPTIONS = {
-    build: "Development mode — ready to implement",
-    plan: "Planning mode — read-only analysis",
-    debug: "Debug mode — troubleshooting and fixes",
-    fullstack: "Fullstack subagent — end-to-end implementation",
-    testing: "Testing subagent — writing tests",
-    security: "Security subagent — vulnerability audit",
-    devops: "DevOps subagent — CI/CD and deployment",
+    implement: "Development mode — ready to implement",
+    architect: "Planning mode — read-only analysis",
+    fix: "Debug mode — troubleshooting and fixes",
+    audit: "Review mode — code quality assessment",
+    crosslayer: "Crosslayer subagent — end-to-end implementation",
+    qa: "QA subagent — writing tests",
+    guard: "Security subagent — vulnerability audit",
+    ship: "DevOps subagent — CI/CD and deployment",
 };
 const TOOL_NOTIFICATIONS = {
     task_finalize: {
@@ -79,6 +83,30 @@ const TOOL_NOTIFICATIONS = {
             .split("\n")[0]
             .substring(0, 100),
     },
+    github_status: {
+        successTitle: "GitHub Connected",
+        successMsg: (_args, output) => {
+            const repoMatch = output.match(/Repository:\s+(.+)/);
+            return repoMatch ? `Connected to ${repoMatch[1].substring(0, 100)}` : "GitHub CLI available";
+        },
+        errorTitle: "GitHub Not Available",
+        errorMsg: (_, out) => out
+            .replace(/^✗\s*/, "")
+            .split("\n")[0]
+            .substring(0, 100),
+    },
+    repl_init: {
+        successTitle: "REPL Loop Started",
+        successMsg: (args) => `${(args.planFilename ?? "Plan").split("/").pop()?.substring(0, 40)} — tasks loaded`,
+        errorTitle: "REPL Init Failed",
+        errorMsg: (_, out) => out.substring(0, 100),
+    },
+    repl_report: {
+        successTitle: "Task Update",
+        successMsg: (args) => `Result: ${args.result ?? "reported"}`,
+        errorTitle: "Report Failed",
+        errorMsg: (_, out) => out.substring(0, 100),
+    },
 };
 // ─── Error Message Extraction ────────────────────────────────────────────────
 //
@@ -138,6 +166,18 @@ export const CortexPlugin = async (ctx) => {
             docs_index: docs.index,
             // Task tools - finalize workflow (commit, push, PR)
             task_finalize: task.finalize,
+            // Environment tools - IDE/terminal detection for contextual options
+            detect_environment: environment.detectEnvironment,
+            get_environment_info: environment.getEnvironmentInfo,
+            // GitHub integration tools - work item listing, issue selection, project boards
+            github_status: github.status,
+            github_issues: github.issues,
+            github_projects: github.projects,
+            // REPL loop tools - iterative task-by-task implementation
+            repl_init: repl.init,
+            repl_status: repl.status,
+            repl_report: repl.report,
+            repl_summary: repl.summary,
         },
         // ── Post-execution toast notifications ────────────────────────────────
         //

package/dist/registry.d.ts

@@ -19,11 +19,16 @@ export interface ModelEntry {
 }
 export declare const MODEL_REGISTRY: ModelEntry[];
 /** Primary agents receive the best available model */
-export declare const PRIMARY_AGENTS: readonly ["build", "plan", "debug", "review"];
+export declare const PRIMARY_AGENTS: readonly ["implement", "architect", "fix", "audit"];
 /** Subagents receive a fast/cost-effective model */
-export declare const SUBAGENTS: readonly ["fullstack", "testing", "security", "devops"];
+export declare const SUBAGENTS: readonly ["crosslayer", "qa", "guard", "ship"];
 /** All agent names combined */
-export declare const ALL_AGENTS: readonly ["build", "plan", "debug", "review", "fullstack", "testing", "security", "devops"];
+export declare const ALL_AGENTS: readonly ["implement", "architect", "fix", "audit", "crosslayer", "qa", "guard", "ship"];
+/** OpenCode built-in agents disabled when cortex-agents is installed.
+ *  Replaced by cortex equivalents: build → implement, plan → architect */
+export declare const DISABLED_BUILTIN_AGENTS: readonly ["build", "plan"];
+/** Old agent files to clean up from previous cortex-agents versions */
+export declare const STALE_AGENT_FILES: readonly ["build.md", "plan.md", "debug.md", "review.md", "fullstack.md", "testing.md", "security.md", "devops.md"];
 /**
  * Build the interactive choices list for primary model selection.
  * Shows premium and standard tier models (excluding fast).

package/dist/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,UAAU;IACzB,uDAAuD;IACvD,EAAE,EAAE,MAAM,CAAC;IACX,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;IACtC,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,cAAc,EAAE,UAAU,EAuGtC,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,cAAc,+CAAgD,CAAC;AAE5E,oDAAoD;AACpD,eAAO,MAAM,SAAS,yDAA0D,CAAC;AAEjF,+BAA+B;AAC/B,eAAO,MAAM,UAAU,6FAA6C,CAAC;AAErE;;;GAGG;AACH,wBAAgB,iBAAiB;;;;IAMhC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,cAAc,EAAE,MAAM;;;;IAcxD"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,UAAU;IACzB,uDAAuD;IACvD,EAAE,EAAE,MAAM,CAAC;IACX,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;IACtC,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,cAAc,EAAE,UAAU,EAuGtC,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,cAAc,qDAAsD,CAAC;AAElF,oDAAoD;AACpD,eAAO,MAAM,SAAS,gDAAiD,CAAC;AAExE,+BAA+B;AAC/B,eAAO,MAAM,UAAU,0FAA6C,CAAC;AAErE;0EAC0E;AAC1E,eAAO,MAAM,uBAAuB,4BAA6B,CAAC;AAElE,uEAAuE;AACvE,eAAO,MAAM,iBAAiB,qHASpB,CAAC;AAEX;;;GAGG;AACH,wBAAgB,iBAAiB;;;;IAMhC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,cAAc,EAAE,MAAM;;;;IAcxD"}

package/dist/registry.js

@@ -105,11 +105,25 @@ export const MODEL_REGISTRY = [
     },
 ];
 /** Primary agents receive the best available model */
-export const PRIMARY_AGENTS = ["build", "plan", "debug", "review"];
+export const PRIMARY_AGENTS = ["implement", "architect", "fix", "audit"];
 /** Subagents receive a fast/cost-effective model */
-export const SUBAGENTS = ["fullstack", "testing", "security", "devops"];
+export const SUBAGENTS = ["crosslayer", "qa", "guard", "ship"];
 /** All agent names combined */
 export const ALL_AGENTS = [...PRIMARY_AGENTS, ...SUBAGENTS];
+/** OpenCode built-in agents disabled when cortex-agents is installed.
+ *  Replaced by cortex equivalents: build → implement, plan → architect */
+export const DISABLED_BUILTIN_AGENTS = ["build", "plan"];
+/** Old agent files to clean up from previous cortex-agents versions */
+export const STALE_AGENT_FILES = [
+    "build.md",
+    "plan.md",
+    "debug.md",
+    "review.md",
+    "fullstack.md",
+    "testing.md",
+    "security.md",
+    "devops.md",
+];
 /**
  * Build the interactive choices list for primary model selection.
  * Shows premium and standard tier models (excluding fast).

package/dist/tools/cortex.d.ts

@@ -12,8 +12,8 @@ export declare const status: {
 /**
  * cortex_configure — Write per-project model configuration to ./opencode.json.
  *
- * Accepts a primary model (for build/plan/debug) and a subagent model
- * (for fullstack/testing/security/devops). Merges into any existing
+ * Accepts a primary model (for implement/architect/fix/audit) and a subagent model
+ * (for crosslayer/qa/guard/ship). Merges into any existing
  * opencode.json at the project root, preserving other settings.
  */
 export declare const configure: {