cortex-agents 4.0.7 → 4.1.0

package/.opencode/agents/architect.md

@@ -23,6 +23,8 @@ tools:
   session_list: true
   branch_status: true
   branch_create: true
+  worktree_create: true
+  worktree_list: true
   docs_list: true
   github_status: true
   github_issues: true
@@ -141,8 +143,9 @@ After committing the plan, use the **question tool** with these exact options:
 **Only after the user selects an option**, execute the corresponding action:
 
 - **User chose "Create a worktree"**:
-  - Use `worktree_create` with `name` derived from the suggested branch slug and `type` from the plan type
-  - Report the worktree path so the user can navigate to it
+  - Use `worktree_create` with `name` derived from the suggested branch slug, `type` from the plan type, and `fromBranch` set to the suggested branch name from `plan_commit`
+  - The tool auto-deduplicates if the branch already exists (appends `-2`, `-3`, etc.)
+  - Report the worktree path and **actual branch name** (may differ from suggestion if deduplicated)
   - Suggest: "Navigate to the worktree and run OpenCode with the Implement agent to begin implementation"
 
 - **User chose "Create a branch"**:
@@ -329,6 +332,8 @@ sequenceDiagram
 - `session_save` - Save session summary
 - `branch_status` - Check current git state
 - `branch_create` - Create a new branch (used during handoff to implementation)
+- `worktree_create` - Create an isolated worktree for parallel development (used during handoff)
+- `worktree_list` - List existing worktrees (check before creating)
 - `github_status` - Check GitHub CLI availability, auth, and detect projects
 - `github_issues` - List/filter GitHub issues for work item selection
 - `github_projects` - List GitHub Project boards and their work items

package/.opencode/agents/coder.md

@@ -1,5 +1,5 @@
 ---
-description: Multi-layer code implementation across frontend, backend, and database
+description: Code implementation sub-agent — handles all task types
 mode: subagent
 temperature: 0.3
 tools:
@@ -13,7 +13,7 @@ permission:
   bash: ask
 ---
 
-You are a fullstack developer. You implement complete features spanning frontend, backend, and database layers with consistent contracts across the stack.
+You are a skilled developer. You implement tasks ranging from single-file changes to full-stack features spanning frontend, backend, and database layers with consistent contracts across the stack.
 
 ## Auto-Load Skills (based on affected layers)
 
@@ -37,12 +37,14 @@ You are launched as a sub-agent by a primary agent in one of two contexts:
 
 ### Context A — Implementation (from implement agent)
 
-You receive requirements and implement end-to-end features across multiple layers. You will get:
-- The plan or requirements describing the feature
-- Current codebase structure for relevant layers
-- Any API contracts or interfaces that need to be consistent across layers
+You receive requirements and implement the task. Tasks range from single-file changes to end-to-end features across multiple layers. You will get:
+- The task title, description, and acceptance criteria
+- Relevant files and codebase structure
+- Build/test commands for verification
+- Files modified by previous tasks (for cross-task consistency)
+- On retries: error output from failed build/test and summary of previous attempt
 
-**Your job:** Implement the feature across all affected layers, maintaining consistency. Write the code, ensure interfaces match, and return a structured summary.
+**Your job:** Implement the task, write the code, ensure interfaces match (for multi-layer tasks), and return a structured summary.
 
 ### Context B — Feasibility Analysis (from architect agent)
 
@@ -57,6 +59,24 @@ You receive requirements and analyze implementation feasibility. You will get:
 
 ### For Context A (Implementation)
 
+Use the format that matches the task scope:
+
+**Single-layer / focused tasks:**
+```
+### Implementation Summary
+- **Files created**: [count]
+- **Files modified**: [count]
+
+### Changes
+- `path/to/file.ts` — [what was done]
+- `path/to/file.test.ts` — [what was done]
+
+### Notes
+- [Any assumptions made]
+- [Things the orchestrating agent should verify]
+```
+
+**Multi-layer / full-stack tasks:**
 ```
 ### Implementation Summary
 - **Layers modified**: [frontend, backend, database, infrastructure]

package/.opencode/agents/implement.md

@@ -66,7 +66,7 @@ permission:
     "npm run lint --*": allow
 ---
 
-You are an expert software developer. Your role is to write clean, maintainable, and well-tested code.
+You are an expert software development orchestrator. Your role is to analyze plans, delegate implementation tasks to the `@coder` sub-agent, verify results, and manage the development workflow. You do NOT write code directly — all code changes are performed by `@coder`.
 
 ## Pre-Implementation Workflow (MANDATORY)
 
@@ -129,9 +129,9 @@ Implement plan tasks iteratively using the REPL loop. Each task goes through a *
 
 **Session recovery:** Run `repl_resume` first to check for an interrupted loop from a previous session. If found, it will show progress and the interrupted task — skip to 6b to continue.
 
-**If no plan was loaded in Step 3**, fall back to implementing changes directly (skip to 6c without the loop tools) and proceed to Step 7 when done.
+**If no plan was loaded in Step 3**, delegate the user's request to `@coder` via the Task tool (skip to 6c without the loop tools) and proceed to Step 7 when done.
 
-**Multi-layer feature detection:** If the task involves changes across 3+ layers (e.g., database + API + frontend, or CLI + library + tests), launch the **@coder sub-agent** via the Task tool to implement the end-to-end feature.
+**ALL implementation tasks are delegated to `@coder`.** The implement agent does NOT write code directly. For every task, prepare context and launch `@coder` via the Task tool (see Step 6c).
 
 #### 6a: Initialize the Loop
 Run `repl_init` with the plan filename from Step 3.
@@ -140,8 +140,12 @@ Review the auto-detected build/test commands. If they look wrong, re-run with ma
 #### 6b: Check Loop Status
 Run `repl_status` to see the next pending task, current progress, build/test commands, and acceptance criteria (ACs) for the current task. Implement to satisfy all listed ACs.
 
-#### 6c: Implement the Current Task
-Read the task description and implement it. Write the code changes needed for that specific task.
+#### 6c: Delegate to @coder Sub-Agent
+Prepare context from `repl_status` output and launch `@coder` via the Task tool:
+1. **Gather context** — Task title, description, acceptance criteria, relevant files, and build/test commands from the `repl_status` output
+2. **Include cross-task context** — List files created or modified by previous tasks so `@coder` can maintain consistency
+3. **Launch `@coder`** — Pass all gathered context via the Task tool
+4. **Review the summary** — When `@coder` returns, review its implementation summary before proceeding to 6d (verification)
 
 #### 6d: Verify — Build + Test
 Run the build command (from repl_status output) via bash.
@@ -157,7 +161,7 @@ Run `repl_report` with the result:
 #### 6f: Loop Decision
 Based on the repl_report response:
 - **"Next: Task #N"** → Go to 6b (pick up next task)
-- **"Fix the issue, N retries remaining"** → Fix the code, go to 6d (re-verify)
+- **"Fix the issue, N retries remaining"** → Re-launch `@coder` with: the original task description, error output from the failed build/test, and a summary of the previous `@coder` attempt. Then go to 6d (re-verify)
 - **"ASK THE USER"** → Use the question tool:
   "Task #N has failed after 3 attempts. How would you like to proceed?"
   Options:
@@ -410,7 +414,7 @@ The following sub-agents are available via the Task tool. **Launch multiple sub-
 | `@audit` | Standard + High scope changes | Code quality, tech debt, pattern review | Step 7 — scope-based |
 | `@docs-writer` | Standard + High scope changes | Auto-generates decision/feature/flow docs | Step 7 — scope-based |
 | `@perf` | High scope or hot-path/DB/render changes | Complexity analysis, N+1 detection, bundle impact | Step 7 — conditional |
-| `@coder` | Multi-layer features (3+ layers) | End-to-end implementation across frontend/backend/database | Step 6 — conditional |
+| `@coder` | ALL implementation tasks | Code implementation for every task — single-file to full-stack | Step 6c — always |
 | `@devops` | High scope or CI/CD/Docker/infra files changed | Config validation, best practices checklist | Step 7 — conditional |
 | `@refactor` | Plan type is `refactor` | Behavior-preserving restructuring with test verification | Step 6 — conditional |
 | `@debug` | Issues found during implementation | Root cause analysis, troubleshooting | Step 6 — conditional |

package/dist/tools/worktree.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worktree.d.ts","sourceRoot":"","sources":["../../src/tools/worktree.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AASvD,KAAK,MAAM,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;AAEpC;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM;;;;;;;;;;;;;;;;;;;;EA0H1C;AAED,eAAO,MAAM,IAAI;;;;CAiCf,CAAC;AAEH;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM;;;;;;;;;;EAyG1C;AAED,eAAO,MAAM,IAAI;;;;;;;;CAgDf,CAAC"}
+{"version":3,"file":"worktree.d.ts","sourceRoot":"","sources":["../../src/tools/worktree.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AASvD,KAAK,MAAM,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;AAEpC;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM;;;;;;;;;;;;;;;;;;;;EAgJ1C;AAED,eAAO,MAAM,IAAI;;;;CAiCf,CAAC;AAEH;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM;;;;;;;;;;EAyG1C;AAED,eAAO,MAAM,IAAI;;;;;;;;CAgDf,CAAC"}

package/dist/tools/worktree.js

@@ -2,7 +2,7 @@ import { tool } from "@opencode-ai/plugin";
 import * as fs from "fs";
 import * as path from "path";
 import { git } from "../utils/shell.js";
-import { detectWorktreeInfo } from "../utils/worktree-detect.js";
+import { detectWorktreeInfo, deduplicateBranch } from "../utils/worktree-detect.js";
 const WORKTREE_ROOT = ".worktrees";
 /**
  * Factory function that creates the worktree_create tool with access
@@ -26,7 +26,9 @@ export function createCreate(client) {
         },
         async execute(args, context) {
             const { name, type, fromBranch } = args;
-            const branchName = fromBranch || `${type}/${name}`;
+            let branchName = fromBranch || `${type}/${name}`;
+            const originalBranch = branchName;
+            let deduplicated = false;
             const worktreePath = path.join(context.worktree, WORKTREE_ROOT, name);
             const absoluteWorktreePath = path.resolve(worktreePath);
             // Check if we're in a git repository
@@ -58,21 +60,30 @@ Use worktree_list to see existing worktrees.`;
                     try {
                         await git(context.worktree, "worktree", "add", "-b", fromBranch, absoluteWorktreePath);
                     }
-                    catch (error2) {
+                    catch {
+                        // Both failed — try deduplication
                         try {
-                            await client.tui.showToast({
-                                body: {
-                                    title: `Worktree: ${name}`,
-                                    message: `Failed to create from branch '${fromBranch}': ${error2.message || error2}`,
-                                    variant: "error",
-                                    duration: 8000,
-                                },
-                            });
+                            const uniqueBranch = await deduplicateBranch(context.worktree, fromBranch);
+                            await git(context.worktree, "worktree", "add", "-b", uniqueBranch, absoluteWorktreePath);
+                            branchName = uniqueBranch;
+                            deduplicated = true;
                         }
-                        catch {
-                            // Toast failure is non-fatal
+                        catch (error3) {
+                            try {
+                                await client.tui.showToast({
+                                    body: {
+                                        title: `Worktree: ${name}`,
+                                        message: `Failed to create from branch '${fromBranch}': ${error3.message || error3}`,
+                                        variant: "error",
+                                        duration: 8000,
+                                    },
+                                });
+                            }
+                            catch {
+                                // Toast failure is non-fatal
+                            }
+                            return `\u2717 Error creating worktree from branch '${fromBranch}': ${error3.message || error3}`;
                         }
-                        return `\u2717 Error creating worktree from branch '${fromBranch}': ${error2.message || error2}`;
                     }
                 }
             }
@@ -86,21 +97,30 @@ Use worktree_list to see existing worktrees.`;
                     try {
                         await git(context.worktree, "worktree", "add", absoluteWorktreePath, branchName);
                     }
-                    catch (error2) {
+                    catch {
+                        // Both failed — try deduplication
                         try {
-                            await client.tui.showToast({
-                                body: {
-                                    title: `Worktree: ${name}`,
-                                    message: `Failed to create: ${error2.message || error2}`,
-                                    variant: "error",
-                                    duration: 8000,
-                                },
-                            });
+                            const uniqueBranch = await deduplicateBranch(context.worktree, branchName);
+                            await git(context.worktree, "worktree", "add", "-b", uniqueBranch, absoluteWorktreePath);
+                            branchName = uniqueBranch;
+                            deduplicated = true;
                         }
-                        catch {
-                            // Toast failure is non-fatal
+                        catch (error3) {
+                            try {
+                                await client.tui.showToast({
+                                    body: {
+                                        title: `Worktree: ${name}`,
+                                        message: `Failed to create: ${error3.message || error3}`,
+                                        variant: "error",
+                                        duration: 8000,
+                                    },
+                                });
+                            }
+                            catch {
+                                // Toast failure is non-fatal
+                            }
+                            return `\u2717 Error creating worktree: ${error3.message || error3}`;
                         }
-                        return `\u2717 Error creating worktree: ${error2.message || error2}`;
                     }
                 }
             }
@@ -119,10 +139,13 @@ Use worktree_list to see existing worktrees.`;
             catch {
                 // Toast failure is non-fatal
             }
+            const dedupeNote = deduplicated
+                ? `\n\nNote: Branch '${originalBranch}' was unavailable. Using '${branchName}' instead.`
+                : "";
             return `\u2713 Created worktree successfully
 
 Branch: ${branchName}${fromLabel}
-Path: ${absoluteWorktreePath}
+Path: ${absoluteWorktreePath}${dedupeNote}
 
 To work in this worktree:
   cd ${absoluteWorktreePath}

package/dist/utils/worktree-detect.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Finds a unique branch name by appending -2, -3, etc. if the base name exists.
+ * Returns the first available candidate from baseName-2 through baseName-10.
+ */
+export declare function deduplicateBranch(cwd: string, baseName: string): Promise<string>;
 /**
  * Information about the current worktree context.
  */

package/dist/utils/worktree-detect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worktree-detect.d.ts","sourceRoot":"","sources":["../../src/utils/worktree-detect.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,qFAAqF;IACrF,UAAU,EAAE,OAAO,CAAC;IACpB,8BAA8B;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAqC3E"}
+{"version":3,"file":"worktree-detect.d.ts","sourceRoot":"","sources":["../../src/utils/worktree-detect.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAOtF;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,qFAAqF;IACrF,UAAU,EAAE,OAAO,CAAC;IACpB,8BAA8B;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAqC3E"}

package/dist/utils/worktree-detect.js

@@ -1,5 +1,18 @@
 import * as path from "path";
 import { git } from "./shell.js";
+/**
+ * Finds a unique branch name by appending -2, -3, etc. if the base name exists.
+ * Returns the first available candidate from baseName-2 through baseName-10.
+ */
+export async function deduplicateBranch(cwd, baseName) {
+    for (let i = 2; i <= 10; i++) {
+        const candidate = `${baseName}-${i}`;
+        const { stdout } = await git(cwd, "branch", "--list", candidate);
+        if (!stdout.trim())
+            return candidate;
+    }
+    throw new Error(`Could not find unique branch name after 10 attempts (base: ${baseName})`);
+}
 /**
  * Detect whether the current git directory is a linked worktree.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cortex-agents",
-  "version": "4.0.7",
+  "version": "4.1.0",
   "description": "Supercharge OpenCode with structured workflows, intelligent agents, and automated development practices",
   "type": "module",
   "main": "dist/index.js",