cortex-agents 4.0.3 → 4.0.4

package/.opencode/agents/architect.md

@@ -22,6 +22,7 @@ tools:
   session_save: true
   session_list: true
   branch_status: true
+  branch_create: true
   docs_list: true
   github_status: true
   github_issues: true
@@ -110,39 +111,44 @@ Use `plan_save` with:
 - Full plan content including mermaid diagrams
 - Task list
 
-### Step 4.5: Commit Plan to Branch (MANDATORY)
+### Step 4.5: Commit Plan (MANDATORY)
 
-**After saving the plan**, commit it to a dedicated branch to keep `main` clean:
+**After saving the plan**, commit the `.cortex/` artifacts on the current branch:
 
 1. Call `plan_commit` with the plan filename from Step 4
 2. This automatically:
-   - Creates a branch (`feature/`, `bugfix/`, `refactor/`, or `docs/` prefix based on plan type)
-   - Updates the plan frontmatter with `branch: feature/xyz`
+   - 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`
    - Stages all `.cortex/` artifacts
    - Commits with `chore(plan): {title}`
-3. The plan and `.cortex/` artifacts now live on the feature branch, not `main`
-4. Report the branch name to the user
+3. **No branch is created** — the plan is committed on the current branch. Branch creation happens during handoff.
+4. Report the suggested branch name to the user
 
-**If plan_commit fails** (e.g., uncommitted changes blocking checkout), inform the user and suggest they stash or commit their changes first.
+**If plan_commit fails** (e.g., nothing to stage), inform the user.
 
 ### Step 5: Handoff to Implementation
-**After committing the plan**, offer the user options to proceed:
+**After committing the plan**, offer the user options to proceed. Note the **suggested branch** from plan_commit output.
 
-"Plan committed to `{branch}`. How would you like to proceed?"
+"Plan committed. Suggested branch: `{suggestedBranch}`. How would you like to proceed?"
 
-1. **Create a worktree (Recommended)** — Create an isolated worktree from the plan branch, then switch to Implement
-2. **Switch to Implement agent** — Hand off for implementation on the plan branch in this repo
+1. **Create a worktree (Recommended)** — Create an isolated worktree with the suggested branch, then switch to Implement
+2. **Continue in this session** — Create the branch here, then switch to Implement agent
 3. **Stay in Architect mode** — Continue planning or refine the plan
 
-If the user chooses "Create a worktree":
-- Use `worktree_create` with `fromBranch` set to the plan branch name
+If the user chooses **"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
 - Suggest: "Navigate to the worktree and run OpenCode with the Implement agent to begin implementation"
 
+If the user chooses **"Continue in this session"**:
+- Use `branch_create` with the suggested branch name (type and name from the plan)
+- This creates and switches to the new branch
+- Then switch to the Implement agent
+
 ### Step 6: Provide Handoff Context
 If user chooses to switch agents, provide:
 - Plan file location
-- **Actual branch name** (from plan_commit result, not a suggestion)
+- **Branch name** (the one just created during handoff)
 - Key tasks to implement first
 - Critical decisions to follow
 
@@ -156,7 +162,7 @@ If user chooses to switch agents, provide:
 - Think about scalability, maintainability, and performance
 - Never write or modify code files — only analyze and advise
 - Always save plans for future reference
-- Always commit plans to a branch to keep main clean
+- Always commit plans via plan_commit for persistence
 
 ## Skill Loading (load based on plan topic)
 
@@ -264,8 +270,8 @@ sequenceDiagram
 ## Suggested Branch Name
 `feature/[descriptive-name]` or `refactor/[descriptive-name]`
 
-> **Note**: The actual branch is created by `plan_commit` in Step 4.5.
-> The branch name is written into the plan frontmatter as `branch: feature/xyz`.
+> **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.
 ```
 
 ---
@@ -300,7 +306,7 @@ sequenceDiagram
 - You CANNOT launch implementation sub-agents (@testing, @audit, @devops, @refactor, @docs-writer)
 - You can only read, search, and analyze
 - You CAN save plans to .cortex/plans/
-- You CAN commit plans to a branch via `plan_commit` (creates branch + commits .cortex/ only)
+- You CAN commit plans via `plan_commit` (stages + commits .cortex/ on the current branch, no branch creation)
 - Always ask clarifying questions when requirements are unclear
 
 ## Tool Usage
@@ -310,9 +316,10 @@ sequenceDiagram
 - `plan_save` - Save implementation plan
 - `plan_list` - List existing plans
 - `plan_load` - Load a saved plan
-- `plan_commit` - Create branch from plan, commit .cortex/ artifacts, write branch to frontmatter
+- `plan_commit` - Commit .cortex/ artifacts on current branch, write suggested branch to frontmatter
 - `session_save` - Save session summary
 - `branch_status` - Check current git state
+- `branch_create` - Create a new branch (used during handoff to implementation)
 - `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/implement.md

@@ -86,26 +86,26 @@ If `./opencode.json` does not have agent model configuration, offer to configure
 Run `plan_list` to see if there's a relevant plan for this work.
 If a plan exists, load it with `plan_load`.
 
-**Plan branch detection:** If the loaded plan has a `branch` field in its frontmatter (set by the architect's `plan_commit`), note the branch name. This branch already contains the committed plan and `.cortex/` artifacts. You should use this branch for implementation.
+**Suggested branch detection:** If the loaded plan has a `branch` field in its frontmatter (set by `plan_commit`), this is the **suggested branch name** for implementation. The branch may or may not exist yet — `plan_commit` only writes the suggestion, it does not create the branch.
 
 ### Step 4: Ask User About Branch Strategy
 
-**If the plan has a `branch` field AND you are already on that branch:**
+**If you are already on the suggested branch (it was created during architect handoff):**
 Skip the branch creation prompt entirely — you're already set up. Inform the user:
 "You're on the plan branch `{branch}`. Ready to implement."
 
-**If the plan has a `branch` field BUT you are on a different branch (e.g., main):**
-Offer to switch or create a worktree from the plan branch:
+**If the plan has a `branch` field BUT the branch doesn't exist yet or you're on a different branch:**
+Offer to create it:
 
-"The plan has a branch `{branch}`. How would you like to proceed?"
+"The plan suggests branch `{branch}`. How would you like to proceed?"
 
 Options:
-1. **Create a worktree from the plan branch (Recommended)** — Isolated copy using the existing `{branch}`
-2. **Switch to the plan branch** — Checkout `{branch}` directly in this repo
-3. **Create a new branch** — Ignore the plan branch, start fresh
+1. **Create a worktree (Recommended)** — Isolated copy with the suggested branch name
+2. **Create the branch here** — Create and switch to `{branch}` in this repo
+3. **Create a different branch** — Use a custom branch name
 4. **Continue here** — Only if you're certain (not recommended on protected branches)
 
-**If no plan branch exists AND on a protected branch:**
+**If no plan exists AND on a protected branch:**
 Use the original prompt:
 
 "I'm ready to implement changes. How would you like to proceed?"
@@ -116,10 +116,8 @@ Options:
 3. **Continue here** - Only if you're certain (not recommended on protected branches)
 
 ### Step 5: Execute Based on Response
-- **Worktree from plan branch**: Use `worktree_create` with `fromBranch` set to the plan branch. Report the worktree path. Continue working in the current session.
-- **Worktree (new branch)**: Use `worktree_create` with appropriate type. Report the worktree path. Continue working in the current session.
-- **Switch to plan branch**: Use `branch_switch` with the plan branch name
-- **Branch**: Use `branch_create` with appropriate type (feature/bugfix/refactor)
+- **Worktree**: Use `worktree_create` with appropriate type and name. Report the worktree path. Continue working in the current session.
+- **Create branch**: Use `branch_create` with the suggested branch name (or custom name)
 - **Continue**: Proceed with caution, warn user about risks
 
 ### Step 6: REPL Implementation Loop

package/README.md

@@ -91,9 +91,8 @@ User Request
 You: "Add user authentication"
 
 Architect Agent                         reads codebase, creates plan with mermaid diagrams
-   saves to .cortex/plans/             commits plan to feature branch
-   "Plan committed. Switch to          offers worktree or branch
-    Implement?"
+   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
@@ -123,7 +122,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 to branches. Delegates read-only analysis to `@security`, `@coder`, `@perf`. |
+| **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`. |
 | **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`. |
 
@@ -175,7 +174,7 @@ Implement Agent detects: package.json has React + Express + Prisma
 
 **Planning & Sessions**
 - `plan_save` / `plan_load` / `plan_list` / `plan_delete`
-- `plan_commit` — Commit plan to feature branch
+- `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`
 

package/dist/tools/plan.d.ts

@@ -63,20 +63,18 @@ export declare const delete_: {
  * Factory function that creates the plan_commit tool with access
  * to the OpenCode client for toast notifications.
  *
- * Creates a git branch from plan metadata, stages .cortex/ artifacts,
- * commits them, and writes the branch name back into the plan frontmatter.
+ * Stages .cortex/ artifacts and commits them on the current branch.
+ * Writes a suggested branch name into the plan frontmatter for handoff.
+ * Branch creation is deferred to the handoff step (worktree_create,
+ * branch_create, or "continue in this session").
  */
 export declare function createCommit(client: Client): {
     description: string;
     args: {
         planFilename: import("zod").ZodString;
-        branchType: import("zod").ZodOptional<import("zod").ZodString>;
-        branchName: import("zod").ZodOptional<import("zod").ZodString>;
     };
     execute(args: {
         planFilename: string;
-        branchType?: string | undefined;
-        branchName?: string | undefined;
     }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
 };
 export { delete_ as delete };

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

@@ -1 +1 @@
-{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../src/tools/plan.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAgBvD,KAAK,MAAM,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;AA2BpC,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;CAgEf,CAAC;AAEH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;CAkEf,CAAC;AAEH,eAAO,MAAM,IAAI;;;;;;;;CA6Bf,CAAC;AAEH,eAAO,MAAM,OAAO;;;;;;;;CAwBlB,CAAC;AAEH;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM;;;;;;;;;;;;EAsN1C;AAGD,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,CAAC"}
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../src/tools/plan.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAgBvD,KAAK,MAAM,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;AA2BpC,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;CAgEf,CAAC;AAEH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;CAkEf,CAAC;AAEH,eAAO,MAAM,IAAI;;;;;;;;CA6Bf,CAAC;AAEH,eAAO,MAAM,OAAO;;;;;;;;CAwBlB,CAAC;AAEH;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM;;;;;;;;EAoK1C;AAGD,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,CAAC"}

package/dist/tools/plan.js

@@ -195,28 +195,23 @@ export const delete_ = tool({
  * Factory function that creates the plan_commit tool with access
  * to the OpenCode client for toast notifications.
  *
- * Creates a git branch from plan metadata, stages .cortex/ artifacts,
- * commits them, and writes the branch name back into the plan frontmatter.
+ * Stages .cortex/ artifacts and commits them on the current branch.
+ * Writes a suggested branch name into the plan frontmatter for handoff.
+ * Branch creation is deferred to the handoff step (worktree_create,
+ * branch_create, or "continue in this session").
  */
 export function createCommit(client) {
     return tool({
-        description: "Create a git branch from a saved plan, commit .cortex/ artifacts to it, and " +
-            "write the branch name into the plan frontmatter. Keeps main clean.",
+        description: "Stage and commit .cortex/ plan artifacts on the current branch. " +
+            "Writes a suggested branch name into frontmatter for handoff. " +
+            "Does NOT create or switch branches.",
         args: {
             planFilename: tool.schema
                 .string()
                 .describe("Plan filename from .cortex/plans/ (e.g., '2026-02-26-feature-auth.md')"),
-            branchType: tool.schema
-                .string()
-                .optional()
-                .describe("Override branch prefix (default: derived from plan type)"),
-            branchName: tool.schema
-                .string()
-                .optional()
-                .describe("Override branch slug (default: derived from plan title)"),
         },
         async execute(args, context) {
-            const { planFilename, branchType, branchName: nameOverride } = args;
+            const { planFilename } = args;
             const cwd = context.worktree;
             // ── 1. Validate: git repo ─────────────────────────────────
             try {
@@ -247,71 +242,32 @@ Expected YAML frontmatter with title and type fields.`;
             }
             const planTitle = fm.title || "untitled";
             const planType = fm.type || "feature";
-            // ── 3. Determine branch name ──────────────────────────────
+            // ── 3. Compute suggested branch name (stored for handoff) ──
             const VALID_PREFIXES = Object.values(TYPE_TO_PREFIX);
-            const rawPrefix = branchType || TYPE_TO_PREFIX[planType] || "feature";
+            const rawPrefix = TYPE_TO_PREFIX[planType] || "feature";
             const prefix = VALID_PREFIXES.includes(rawPrefix) ? rawPrefix : "feature";
-            // Always sanitize name through slugify (even overrides)
-            const slug = slugify(nameOverride || planTitle);
-            const fullBranchName = `${prefix}/${slug}`;
-            // ── 4. Check current branch ───────────────────────────────
+            const slug = slugify(planTitle);
+            const suggestedBranch = `${prefix}/${slug}`;
+            // Write suggested branch into frontmatter so handoff knows what to create
+            planContent = upsertFrontmatterField(planContent, "branch", suggestedBranch);
+            fs.writeFileSync(filepath, planContent);
+            // ── 4. Get current branch for reporting ────────────────────
             let currentBranch = "";
             try {
                 const { stdout } = await git(cwd, "branch", "--show-current");
                 currentBranch = stdout.trim();
             }
             catch {
-                currentBranch = "";
-            }
-            const isOnProtected = PROTECTED_BRANCHES.includes(currentBranch);
-            let branchCreated = false;
-            // ── 5. Create or switch to branch ─────────────────────────
-            if (isOnProtected || !currentBranch) {
-                // Try to create the branch
-                try {
-                    await git(cwd, "checkout", "-b", fullBranchName);
-                    branchCreated = true;
-                }
-                catch {
-                    // Branch may already exist — try switching to it
-                    try {
-                        await git(cwd, "checkout", fullBranchName);
-                    }
-                    catch (switchErr) {
-                        try {
-                            await client.tui.showToast({
-                                body: {
-                                    title: `Plan Commit: ${planFilename}`,
-                                    message: `Failed to create/switch branch: ${switchErr.message || switchErr}`,
-                                    variant: "error",
-                                    duration: 8000,
-                                },
-                            });
-                        }
-                        catch {
-                            // Toast failure is non-fatal
-                        }
-                        return `✗ Error creating branch '${fullBranchName}': ${switchErr.message || switchErr}
-
-You may have uncommitted changes. Commit or stash them first.`;
-                    }
-                }
+                currentBranch = "(detached)";
             }
-            // If already on a non-protected branch, skip branch creation
-            // ── 6. Update plan frontmatter with branch ────────────────
-            // If we created/switched to a new branch → use that name
-            // If already on a non-protected branch → use whatever we're on
-            const targetBranch = (isOnProtected || branchCreated) ? fullBranchName : currentBranch;
-            planContent = upsertFrontmatterField(planContent, "branch", targetBranch);
-            fs.writeFileSync(filepath, planContent);
-            // ── 7. Stage .cortex/ directory ───────────────────────────
+            // ── 5. Stage .cortex/ directory ───────────────────────────
             try {
                 await git(cwd, "add", path.join(cwd, CORTEX_DIR));
             }
             catch (stageErr) {
                 return `✗ Error staging .cortex/ directory: ${stageErr.message || stageErr}`;
             }
-            // ── 8. Commit ─────────────────────────────────────────────
+            // ── 6. Commit ─────────────────────────────────────────────
             const commitMsg = `chore(plan): ${planTitle}`;
             let commitHash = "";
             try {
@@ -333,7 +289,7 @@ You may have uncommitted changes. Commit or stash them first.`;
                     try {
                         await client.tui.showToast({
                             body: {
-                                title: `Plan: ${targetBranch}`,
+                                title: `Plan: ${planFilename}`,
                                 message: "Already committed — no new changes",
                                 variant: "info",
                                 duration: 4000,
@@ -343,14 +299,14 @@ You may have uncommitted changes. Commit or stash them first.`;
                     catch {
                         // Toast failure is non-fatal
                     }
-                    return `✓ Plan already committed on branch: ${targetBranch}
+                    return `✓ Plan already committed
 
-Branch: ${targetBranch}
-Commit: ${commitHash} (no new changes)
+On: ${currentBranch} (no new changes)
+Commit: ${commitHash}
 Plan: ${planFilename}
+Suggested branch: ${suggestedBranch}
 
-The plan branch is ready for implementation.
-Use worktree_create or switch to the Implement agent.`;
+Ready for handoff — branch will be created when you proceed to implementation.`;
                 }
                 await git(cwd, "commit", "-m", commitMsg);
                 const { stdout: hashOut } = await git(cwd, "rev-parse", "--short", "HEAD");
@@ -372,12 +328,12 @@ Use worktree_create or switch to the Implement agent.`;
                 }
                 return `✗ Error committing: ${commitErr.message || commitErr}`;
             }
-            // ── 9. Success notification ───────────────────────────────
+            // ── 7. Success notification ───────────────────────────────
             try {
                 await client.tui.showToast({
                     body: {
                         title: `Plan Committed`,
-                        message: `${targetBranch} — ${commitHash}`,
+                        message: `${currentBranch} — ${commitHash}`,
                         variant: "success",
                         duration: 5000,
                     },
@@ -386,18 +342,14 @@ Use worktree_create or switch to the Implement agent.`;
             catch {
                 // Toast failure is non-fatal
             }
-            return `✓ Plan committed to branch
+            return `✓ Plan committed
 
-Branch: ${targetBranch}${branchCreated ? " (created)" : ""}
+On: ${currentBranch}
 Commit: ${commitHash} — ${commitMsg}
 Plan: ${planFilename}
+Suggested branch: ${suggestedBranch}
 
-The plan and .cortex/ artifacts are committed on '${targetBranch}'.
-Main branch is clean.
-
-Next steps:
-  • Switch to Implement agent to begin coding
-  • Or use worktree_create to work in an isolated copy`;
+The .cortex/ artifacts are committed. Branch creation happens during handoff.`;
         },
     });
 }

package/package.json

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