cortex-agents 4.0.4 → 4.0.6

package/.opencode/agents/architect.md

@@ -126,24 +126,33 @@ Use `plan_save` with:
 
 **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. Note the **suggested branch** from plan_commit output.
+### Step 5: 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.**
+
+After committing the plan, use the **question tool** with these exact options:
 
 "Plan committed. Suggested branch: `{suggestedBranch}`. How would you like to proceed?"
 
-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
+1. **Create a worktree (Recommended)** — Isolated copy in `.worktrees/` for parallel development. This is the safest option.
+2. **Create a branch** — Create and switch to `{suggestedBranch}` in this repo
 3. **Stay in Architect mode** — Continue planning or refine the plan
 
-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"
+**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
+  - Suggest: "Navigate to the worktree and run OpenCode with the Implement agent to begin implementation"
+
+- **User chose "Create a branch"**:
+  - 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
 
-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
+- **User chose "Stay in Architect mode"**:
+  - Do NOT create any branch or worktree
+  - Continue in the current session for further planning
 
 ### Step 6: Provide Handoff Context
 If user chooses to switch agents, provide:
@@ -178,7 +187,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` |

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

@@ -88,37 +88,40 @@ If a plan exists, load it with `plan_load`.
 
 **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
+### Step 4: Ask User About Branch Strategy (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.**
 
 **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 the branch doesn't exist yet or you're on a different branch:**
-Offer to create it:
+Use the **question tool** with these options:
 
 "The plan suggests branch `{branch}`. How would you like to proceed?"
 
-Options:
-1. **Create a worktree (Recommended)** — Isolated copy with the suggested branch name
+1. **Create a worktree (Recommended)** — Isolated copy with the suggested branch name. This is the safest option.
 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 exists AND on a protected branch:**
-Use the original prompt:
+Use the **question tool** with these options:
 
 "I'm ready to implement changes. How would you like to proceed?"
 
-Options:
-1. **Create a worktree (Recommended)** - Isolated copy in .worktrees/ for parallel development
-2. **Create a new branch** - Stay in this repo, create feature/bugfix branch
-3. **Continue here** - Only if you're certain (not recommended on protected branches)
+1. **Create a worktree (Recommended)** — Isolated copy in `.worktrees/` for parallel development. This is the safest option.
+2. **Create a new branch** — Stay in this repo, create feature/bugfix branch
+3. **Continue here** — Only if you're certain (not recommended on protected branches)
 
 ### Step 5: Execute Based on Response
-- **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
+
+**Only after the user selects an option**, execute the corresponding action:
+
+- **User chose "Worktree"**: Use `worktree_create` with appropriate type and name. Report the worktree path. Continue working in the current session.
+- **User chose "Create branch"**: Use `branch_create` with the suggested branch name (or custom name)
+- **User chose "Continue"**: Proceed with caution, warn user about risks
 
 ### Step 6: REPL Implementation Loop
 
@@ -344,7 +347,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

@@ -154,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
@@ -230,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 |
@@ -365,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/package.json

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