cortex-agents 4.0.3 → 4.0.5

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)
 
@@ -172,7 +178,7 @@ Before creating a plan, load relevant skills to inform your analysis. Use the `s
 | Security requirements, threat models | `security-hardening` |
 | CI/CD pipeline design, deployment strategy | `deployment-automation` |
 | Frontend architecture, component design | `frontend-development` |
-| UI design, visual design, page layouts | `ui-design` |
+| UI design, visual design, page layouts | `ui-design` (**must check `.cortex/design-spec.md` first** — create if missing) |
 | Backend service design, middleware, auth | `backend-development` |
 | Mobile app architecture | `mobile-development` |
 | Desktop app architecture | `desktop-development` |
@@ -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/coder.md

@@ -22,7 +22,7 @@ You are a fullstack developer. You implement complete features spanning frontend
 | Layer | Skill to Load |
 |-------|--------------|
 | Frontend (React, Vue, Svelte, Angular, etc.) | `frontend-development` |
-| UI/visual design (new pages, layouts, polish) | `ui-design` |
+| UI/visual design (new pages, layouts, polish) | `ui-design` (**must check `.cortex/design-spec.md` first** — create if missing) |
 | Backend (Express, Fastify, Django, Go, etc.) | `backend-development` |
 | API contracts (REST, GraphQL, gRPC) | `api-design` |
 | Database (schema, migrations, queries) | `database-design` |

package/.opencode/agents/fix.md

@@ -150,7 +150,7 @@ Before fixing, load relevant skills. Use the `skill` tool.
 | API errors | `api-design` + `backend-development` |
 | Database issues | `database-design` |
 | Frontend rendering issues | `frontend-development` |
-| UI visual bugs, layout issues, design inconsistencies | `ui-design` |
+| UI visual bugs, layout issues, design inconsistencies | `ui-design` (**must check `.cortex/design-spec.md` first** — create if missing) |
 | Deployment or CI/CD failures | `deployment-automation` |
 
 ## Debugging Quick Reference

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
@@ -346,7 +344,7 @@ Detect the project's technology stack and load relevant skills BEFORE writing co
 | Signal | Skill to Load |
 |--------|--------------|
 | `package.json` has react/next/vue/nuxt/svelte/angular | `frontend-development` |
-| UI work: new pages, components, visual design, layout | `ui-design` |
+| UI work: new pages, components, visual design, layout | `ui-design` (**must check `.cortex/design-spec.md` first** — create if missing) |
 | `package.json` has express/fastify/hono/nest OR Python with flask/django/fastapi | `backend-development` |
 | Database files: `migrations/`, `schema.prisma`, `models.py`, `*.sql` | `database-design` |
 | API routes, OpenAPI spec, GraphQL schema | `api-design` |

package/.opencode/skills/ui-design/SKILL.md

@@ -21,6 +21,182 @@ Use this skill when:
 > For accessibility (WCAG, ARIA, keyboard navigation), see `frontend-development`.
 > For component implementation patterns (React, Vue, Svelte), see `frontend-development`.
 
+## Design Spec (MANDATORY — before ANY UI work)
+
+**Every project with a UI MUST have a design spec.** Before making any visual or layout changes, you must check for and use the project's design spec. All UI work must be consistent with this spec.
+
+### Step 1: Check for Existing Spec
+
+Look for `.cortex/design-spec.md` in the project root. If it exists, **read it and follow it** — every color, font, spacing value, and component pattern you use must align with the spec.
+
+### Step 2: Create Spec if Missing
+
+If `.cortex/design-spec.md` does NOT exist, you **MUST create one before writing any UI code**:
+
+1. **Analyze the existing app** — scan all frontend files (components, pages, layouts, stylesheets, Tailwind config, theme files, CSS variables) to extract the current visual identity
+2. **Identify existing patterns** — colors in use, font families, spacing conventions, border radii, shadow usage, component styles
+3. **Synthesize into a spec** — consolidate findings into a coherent design spec, resolving any inconsistencies by choosing the dominant or best pattern
+4. **Save to `.cortex/design-spec.md`** using the template below
+
+If the project has no existing UI (greenfield), generate a design spec based on the project type (SaaS, marketing, developer tool, etc.) and ask the user to confirm key branding choices (primary color, font family, overall feel) before proceeding.
+
+### Step 3: Reference the Spec During Implementation
+
+For every UI change:
+- Use **only** the colors defined in the spec
+- Use **only** the typography scale from the spec
+- Follow the spacing system in the spec
+- Match the component patterns (border radius, shadows, button styles) from the spec
+- Maintain the overall look & feel described in the spec
+
+If a task requires something not covered by the spec (e.g., a new component type, a new color for a new feature), **extend the spec first**, then implement.
+
+### Design Spec Template
+
+```markdown
+# Design Spec — [Project Name]
+
+> Auto-generated from codebase analysis. Keep this file updated as the design evolves.
+> Location: `.cortex/design-spec.md`
+
+## Brand Identity
+
+### Brand Personality
+- **Tone**: [e.g., Professional & approachable / Bold & playful / Minimal & technical]
+- **Feel**: [e.g., Modern SaaS / Enterprise / Developer tool / Consumer app]
+- **Keywords**: [3-5 adjectives, e.g., clean, trustworthy, fast, friendly]
+
+### Logo & Assets
+- Logo location: [path or "not yet defined"]
+- Favicon: [path or "not yet defined"]
+- Brand mark usage notes: [any constraints]
+
+## Color Palette
+
+### Primary
+- **Primary**: [hex] — [Tailwind class, e.g., `blue-600`]
+- **Primary hover**: [hex] — [Tailwind class]
+- **Primary light** (backgrounds): [hex] — [Tailwind class]
+- **Primary dark** (text on light): [hex] — [Tailwind class]
+
+### Accent (if applicable)
+- **Accent**: [hex] — [Tailwind class]
+
+### Neutrals
+- **Background**: [hex] — [Tailwind class]
+- **Surface** (cards, panels): [hex] — [Tailwind class]
+- **Border**: [hex] — [Tailwind class]
+- **Text primary**: [hex] — [Tailwind class]
+- **Text secondary**: [hex] — [Tailwind class]
+- **Text muted**: [hex] — [Tailwind class]
+
+### Semantic Colors
+- **Success**: [hex] — [Tailwind class]
+- **Warning**: [hex] — [Tailwind class]
+- **Error**: [hex] — [Tailwind class]
+- **Info**: [hex] — [Tailwind class]
+
+### Dark Mode (if applicable)
+[Repeat the above structure for dark mode overrides, or note "N/A"]
+
+## Typography
+
+### Font Families
+- **Headings**: [font name] — [source, e.g., Google Fonts / system / @fontsource]
+- **Body**: [font name] — [source]
+- **Monospace** (code): [font name] — [source]
+
+### Type Scale
+| Level | Size | Weight | Line Height | Tailwind |
+|-------|------|--------|-------------|----------|
+| Display | [px] | [weight] | [lh] | [classes] |
+| H1 | [px] | [weight] | [lh] | [classes] |
+| H2 | [px] | [weight] | [lh] | [classes] |
+| H3 | [px] | [weight] | [lh] | [classes] |
+| H4 | [px] | [weight] | [lh] | [classes] |
+| Body | [px] | [weight] | [lh] | [classes] |
+| Small | [px] | [weight] | [lh] | [classes] |
+| Caption | [px] | [weight] | [lh] | [classes] |
+
+## Spacing & Layout
+
+### Base Unit
+- **Base**: [e.g., 8px / 4px]
+- **Scale**: [list the spacing scale used, e.g., 4, 8, 12, 16, 24, 32, 48, 64]
+
+### Container
+- **Max width**: [e.g., max-w-7xl / 1280px]
+- **Page padding**: [e.g., px-4 sm:px-6 lg:px-8]
+
+### Content Density
+- **Target**: [Spacious / Balanced / Dense]
+
+## Component Patterns
+
+### Border Radius
+- **Cards / Modals**: [e.g., rounded-xl / 12px]
+- **Buttons / Inputs**: [e.g., rounded-lg / 8px]
+- **Badges / Pills**: [e.g., rounded-full]
+
+### Shadows
+- **Cards**: [e.g., shadow-sm]
+- **Dropdowns**: [e.g., shadow-md]
+- **Modals**: [e.g., shadow-lg]
+
+### Buttons
+| Variant | Classes |
+|---------|---------|
+| Primary | [full Tailwind classes] |
+| Secondary | [full Tailwind classes] |
+| Ghost | [full Tailwind classes] |
+| Destructive | [full Tailwind classes] |
+
+### Inputs
+- **Height**: [e.g., h-10 / 40px]
+- **Border**: [e.g., border border-gray-300]
+- **Focus**: [e.g., ring-2 ring-primary-500]
+- **Error**: [e.g., border-red-500 + text-sm text-red-600 message below]
+
+### Navigation Pattern
+- **Type**: [Top navbar / Sidebar / Bottom tabs]
+- **Active state**: [classes for active nav item]
+
+## Look & Feel
+
+### Overall Aesthetic
+[1-2 sentences describing the visual identity, e.g., "Clean, minimal interface with generous whitespace, subtle shadows, and a blue-primary palette that conveys trust and professionalism."]
+
+### Motion
+- **Hover transitions**: [e.g., transition-colors duration-150]
+- **Panel animations**: [e.g., transition-all duration-200 ease-in-out]
+- **Respect reduced motion**: [yes/no]
+
+### Iconography
+- **Icon library**: [e.g., Lucide / Heroicons / Phosphor]
+- **Default size**: [e.g., w-5 h-5 / 20px]
+- **Style**: [e.g., outline / solid / duotone]
+
+### Imagery
+- **Style**: [e.g., illustrations / photos / abstract]
+- **Source**: [e.g., in-house / Unsplash / none yet]
+
+## Do's and Don'ts
+
+### Do
+- [e.g., Use the primary color for all main CTAs]
+- [e.g., Maintain consistent padding inside cards (p-6)]
+- [e.g., Use skeleton loaders for async content]
+
+### Don't
+- [e.g., Don't use arbitrary hex colors outside the palette]
+- [e.g., Don't mix border radius values within the same context]
+- [e.g., Don't skip hover/focus states on interactive elements]
+```
+
+### Updating the Spec
+
+When you make intentional design changes (new component patterns, color additions, etc.), **update `.cortex/design-spec.md`** to reflect them. The spec is a living document that must stay in sync with the codebase.
+
 ## Visual Hierarchy & Layout
 
 ### Scanning Patterns

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`. |
 
@@ -155,6 +154,17 @@ Implement Agent detects: package.json has React + Express + Prisma
   -> implements with deep framework-specific knowledge
 ```
 
+### Design Spec Enforcement
+
+All UI work is governed by a **mandatory design spec** (`.cortex/design-spec.md`). When any agent loads the `ui-design` skill:
+
+1. **Check** — looks for `.cortex/design-spec.md`
+2. **Create if missing** — analyzes the entire app (components, styles, Tailwind config, theme files, CSS variables) and synthesizes a spec covering brand identity, color palette, typography, spacing, component patterns, and look & feel
+3. **Follow it** — every color, font, spacing value, and component pattern must align with the spec
+4. **Extend it** — if a task needs something not in the spec, the spec is updated first
+
+This ensures visual consistency across all agents and sessions — no more one-off colors, mismatched radii, or inconsistent button styles.
+
 ---
 
 ## Tools
@@ -175,7 +185,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`
 
@@ -231,7 +241,7 @@ State persists to `.cortex/repl-state.json` — survives context compaction, ses
 | Skill | Covers |
 |-------|--------|
 | `frontend-development` | React, Vue, Svelte, CSS architecture, accessibility |
-| `ui-design` | Visual hierarchy, typography, color systems, spacing, motion, professional polish |
+| `ui-design` | Visual hierarchy, typography, color systems, spacing, motion, professional polish. **Enforces a mandatory design spec** (`.cortex/design-spec.md`) — auto-creates from codebase analysis if missing, ensuring brand consistency across all UI work. |
 | `backend-development` | API design, middleware, auth, caching, queue systems |
 | `mobile-development` | React Native, Flutter, native iOS/Android patterns |
 | `desktop-development` | Electron, Tauri, native desktop application patterns |
@@ -366,6 +376,7 @@ quality_gate_summary receives reports from 6 agents:
 your-project/
   .cortex/                     Project context (auto-initialized)
      config.json              Configuration
+     design-spec.md           UI design spec — branding, colors, typography, patterns
      plans/                   Implementation plans
      sessions/                Session summaries
      repl-state.json          REPL loop progress (auto-managed)

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