cortex-agents 4.0.8 → 4.1.1

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
@@ -42,27 +44,37 @@ You CAN use the Task tool to launch sub-agents for **read-only analysis** during
 
 | Sub-Agent | Mode | Purpose | When to Use |
 |-----------|------|---------|-------------|
+| `@explore` | Read-only codebase exploration | Find files, search code, understand structure | Need to explore unfamiliar parts of the codebase |
 | `@security` | Audit-only (no code changes) | Threat modeling, security review of proposed design | Plan involves auth, sensitive data, or security-critical features |
-| `@coder` | Feasibility analysis (no implementation) | Estimate effort, identify blockers, assess cross-layer complexity | Plan involves 3+ layers or unfamiliar technology |
 | `@perf` | Complexity analysis (no code changes) | Analyze existing code performance, assess proposed approach | Plan involves performance-sensitive changes |
 
 ### How to Launch Read-Only Sub-Agents
 
 ```
-# Threat modeling during design:
-Task(subagent_type="security", prompt="AUDIT ONLY — no code changes. Review this proposed design for security concerns: [design summary]. Files to review: [list]. Report threat model and recommendations.")
+# Codebase exploration:
+Task(subagent_type="explore", prompt="ANALYSIS ONLY — no code changes. Explore the codebase to understand: [what you need to know]. Search for: [patterns/files]. Report structure, patterns, and relevant findings.")
 
-# Feasibility analysis:
-Task(subagent_type="coder", prompt="FEASIBILITY ANALYSIS ONLY — no implementation. Assess effort and identify blockers for: [feature summary]. Layers involved: [list]. Report feasibility, estimated effort, and potential issues.")
+# Threat modeling during design:
+Task(subagent_type="security", prompt="ANALYSIS ONLY — no code changes. Review this proposed design for security concerns: [design summary]. Files to review: [list]. Report threat model and recommendations.")
 
 # Performance analysis of existing code:
 Task(subagent_type="perf", prompt="ANALYSIS ONLY — no code changes. Review performance characteristics of: [files/functions]. Assess whether proposed approach [summary] will introduce regressions. Report complexity analysis.")
 ```
 
 ### NOT Allowed
-- **Never launch `@coder` for implementation** — only for feasibility analysis
+- **Never launch `@coder`** — has write/edit/bash permissions, WILL implement code regardless of prompt instructions
 - **Never launch `@testing`, `@audit`, or `@devops`** — these are implementation-phase agents
 - **Never launch `@refactor` or `@docs-writer`** — these modify files
+- **Never launch `@debug`** — this is a troubleshooting agent for the fix/implement agents
+- **Never launch `@general`** — uncontrolled agent with no permission restrictions
+
+### Sub-Agent Safety Rule (ABSOLUTE)
+
+You may ONLY launch sub-agents from this exact allowlist: `explore`, `security`, `perf`.
+
+Any other sub-agent type is FORBIDDEN. There are NO exceptions.
+
+If you are unsure whether a sub-agent is safe, DO NOT launch it.
 
 When the user wants to proceed with implementation, you must:
 - **Hand off by switching agents** — Use the question tool to offer "Switch to Implement agent" or "Create a worktree"
@@ -97,25 +109,78 @@ If `./opencode.json` does not have agent model configuration, offer to configure
 Run `plan_list` to see if there are related plans that should be considered.
 Run `docs_list` to check existing project documentation (decisions, features, flows) for context.
 
-### Step 3: Analyze and Create Plan
+### Step 3: Requirements Discovery Interview (MANDATORY)
+
+**You MUST conduct an interview before creating any plan. NEVER skip this step.**
+
+This is a conversation, not a monologue. Your job is to understand what the user actually needs — not assume it.
+
+#### Round 1: Acknowledge & Clarify
+1. **Summarize** what you understood from the user's request (1-3 sentences)
+2. **Ask 3-5 targeted questions** about:
+   - Scope boundaries (what's in, what's out)
+   - Existing constraints (tech stack, timeline, dependencies)
+   - Success criteria (how will we know this is done?)
+   - Edge cases or error scenarios
+   - Non-functional requirements (performance, security, scale)
+3. **Wait for answers** — do NOT proceed until the user responds
+
+#### Round 2+: Deepen Understanding
+Based on answers, you may:
+- Ask follow-up questions on unclear areas
+- Present your understanding of the problem for validation
+- Identify risks or trade-offs the user may not have considered
+- Suggest alternative approaches with pros/cons
+
+#### Readiness Check
+When you believe you have enough information, present:
+1. **Problem Statement** — 2-3 sentence summary of what needs to be solved
+2. **Proposed Approach** — High-level direction (not the full plan yet)
+3. **Key Assumptions** — What you're assuming that hasn't been explicitly stated
+4. **Ask**: "Does this capture what you need? Should I proceed to create the detailed plan, or do you want to adjust anything?"
+
+**Only proceed to Step 4 when the user explicitly confirms readiness.**
+
+#### Exceptions (when you can shorten the interview)
+- User provides a highly detailed specification with clear acceptance criteria
+- User explicitly says "just plan it, I'll review"
+- User references a GitHub issue with full requirements (loaded in Step 0)
+
+Even in these cases, present at minimum a **Readiness Check** summary before proceeding.
+
+### Step 4: Analyze and Create Plan
 
 - Read relevant files to understand the codebase
 - Review existing documentation (feature docs, flow docs, decision docs) for architectural context
 - Analyze requirements thoroughly
 - Create a comprehensive plan with mermaid diagrams
 
-### Step 4: Save the Plan
+### Step 5: Plan Review (MANDATORY)
+
+**Present the plan to the user BEFORE saving it.**
+
+1. Output the full plan in the conversation
+2. Ask: "Here's the plan I've drafted. Would you like to:
+   - **Approve** — I'll save and commit it
+   - **Revise** — Tell me what to change
+   - **Start over** — Let's rethink the approach"
+3. If the user requests revisions, make the changes and present again
+4. Only call `plan_save` after explicit approval
+
+This prevents premature plan commits and ensures the user owns the plan.
+
+### Step 6: Save the Plan
 Use `plan_save` with:
 - Descriptive title
 - Appropriate type (feature/bugfix/refactor/architecture/spike)
 - Full plan content including mermaid diagrams
 - Task list
 
-### Step 4.5: Commit Plan (MANDATORY)
+### Step 6.5: Commit Plan (MANDATORY)
 
 **After saving the plan**, commit the `.cortex/` artifacts on the current branch:
 
-1. Call `plan_commit` with the plan filename from Step 4
+1. Call `plan_commit` with the plan filename from Step 6
 2. This automatically:
    - Computes a suggested branch name (`feature/`, `bugfix/`, `refactor/`, or `docs/` prefix based on plan type)
    - Writes the suggested branch into the plan frontmatter as `branch: feature/xyz`
@@ -126,7 +191,7 @@ Use `plan_save` with:
 
 **If plan_commit fails** (e.g., nothing to stage), inform the user.
 
-### Step 5: Handoff to Implementation (MUST ASK — NEVER skip)
+### Step 7: Handoff to Implementation (MUST ASK — NEVER skip)
 
 **CRITICAL: You MUST use the question tool to ask the user before creating any branch or worktree. NEVER call `branch_create` or `worktree_create` without explicit user selection. Do NOT assume a choice — always present the options and WAIT for the user's response.**
 
@@ -141,8 +206,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"**:
@@ -154,7 +220,7 @@ After committing the plan, use the **question tool** with these exact options:
   - Do NOT create any branch or worktree
   - Continue in the current session for further planning
 
-### Step 6: Provide Handoff Context
+### Step 8: Provide Handoff Context
 If user chooses to switch agents, provide:
 - Plan file location
 - **Branch name** (the one just created during handoff)
@@ -172,6 +238,9 @@ If user chooses to switch agents, provide:
 - Never write or modify code files — only analyze and advise
 - Always save plans for future reference
 - Always commit plans via plan_commit for persistence
+- Interview before planning — understand before you prescribe
+- Plans require user approval — never save without explicit buy-in
+- Sub-agent safety — only launch proven read-only agents
 
 ## Skill Loading (load based on plan topic)
 
@@ -280,7 +349,7 @@ sequenceDiagram
 `feature/[descriptive-name]` or `refactor/[descriptive-name]`
 
 > **Note**: `plan_commit` writes a suggested branch name into the plan frontmatter as `branch: feature/xyz`.
-> The actual branch is created during the handoff step (Step 5), not during plan_commit.
+> The actual branch is created during the handoff step (Step 7), not during plan_commit.
 ```
 
 ---
@@ -311,8 +380,11 @@ sequenceDiagram
 ## Constraints
 - You cannot write, edit, or delete code files
 - You cannot execute bash commands
-- You CAN launch read-only sub-agents (@security, @coder, @perf) for analysis during planning
-- You CANNOT launch implementation sub-agents (@testing, @audit, @devops, @refactor, @docs-writer)
+- You CANNOT launch any sub-agent with write, edit, or bash capabilities (@coder, @testing, @refactor, @devops, @debug, @docs-writer, @audit, @general)
+- You may ONLY launch: @explore, @security, @perf — no exceptions
+- You MUST conduct a requirements interview before creating any plan (see Step 3 for exceptions)
+- You MUST present the plan to the user and get approval before saving it
+- You MUST NOT produce a plan in your first response to the user — interview first
 - You can only read, search, and analyze
 - You CAN save plans to .cortex/plans/
 - You CAN commit plans via `plan_commit` (stages + commits .cortex/ on the current branch, no branch creation)
@@ -329,6 +401,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/README.md

@@ -36,6 +36,17 @@ AI coding assistants are powerful, but without structure they produce inconsiste
  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
@@ -62,7 +73,7 @@ User Request
     v
  Architect (read-only planning)
     |
-    |-- read-only analysis -----> @security  @coder  @perf
+     |-- read-only analysis -----> @security  @explore  @perf
     |
     v
  Implement / Fix (execution)
@@ -122,7 +133,7 @@ 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. Commits plans and defers branch creation to handoff. Delegates read-only analysis to `@security`, `@coder`, `@perf`. |
+| **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`. |
 
@@ -134,11 +145,12 @@ Focused specialists launched **automatically** by primary agents. Each auto-load
 |-------|------|-----------------|-------------|
 | **@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), Architect (feasibility analysis) |
+| **@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) |
 

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.8",
+  "version": "4.1.1",
   "description": "Supercharge OpenCode with structured workflows, intelligent agents, and automated development practices",
   "type": "module",
   "main": "dist/index.js",