@vibedx/vibekit 0.6.1 → 0.6.3

package/README.md

@@ -63,6 +63,7 @@ The skill teaches agents the ticket-driven workflow — they'll create focused t
 - **🚀 AI-native ticket management** - Purpose-built for AI-assisted development workflows
 - **⚡ Generate tickets using Claude Code and Codex power** - Leverage cutting-edge AI for planning
 - **🔄 Seamless git workflow** - Automatic branch creation and status tracking
+- **🌿 Parallel worktrees** - Work on multiple tickets simultaneously with `--worktree`
 - **📝 Living documentation** - Your tickets in git become your project's development story
 
 ## ✨ Features
@@ -74,7 +75,8 @@ The skill teaches agents the ticket-driven workflow — they'll create focused t
 ```
 
 - **🎯 Smart Tickets**: Create, manage, and track development tickets with unique IDs
-- **🔗 Git Integration**: Automatic branch creation and workflow management  
+- **🔗 Git Integration**: Automatic branch creation and workflow management
+- **🌿 Worktree Support**: Work on multiple tickets in parallel without switching branches
 - **🤖 AI Enhancement**: Claude Code integration for ticket refinement and content improvement
 - **📋 Interactive CLI**: Beautiful terminal interface with arrow navigation
 - **📝 Templates**: Customizable ticket templates for consistent workflows
@@ -110,6 +112,10 @@ vibe close TKT-001
 # Start working on a ticket (creates git branch)
 vibe start TKT-001
 vibe start TKT-001 --base main --update-status
+
+# Start in a separate worktree (parallel work without switching branches)
+vibe start TKT-001 --worktree
+vibe start TKT-001 -w
 ```
 
 ### 👥 Team Management
@@ -229,6 +235,31 @@ Fix responsive layout issues in `src/components/Layout.jsx`
 - Test on devices: iPhone SE, iPad, desktop (1920px+)
 ```
 
+### Working with Worktrees (Parallel Development)
+```bash
+# Start a ticket in its own worktree
+$ vibe start TKT-005 --worktree
+🌿 Created worktree at ~/.vibekit/worktrees/myproject/feature--TKT-005-add-api-cache/
+📝 Updated ticket status to in_progress
+💡 cd ~/.vibekit/worktrees/myproject/feature--TKT-005-add-api-cache/
+💡 Run npm install in the worktree if needed
+
+# Your main branch stays untouched — work on TKT-005 in the worktree
+# List tickets shows worktree indicator
+$ vibe list
+┌─────────┬──────────────┬─────────────────────────────┬──────────┐
+│ ID      │ Status       │ Title                       │ Worktree │
+├─────────┼──────────────┼─────────────────────────────┼──────────┤
+│ TKT-005 │ in_progress  │ Add API cache               │ 🌿       │
+│ TKT-004 │ in_progress  │ Add dark mode toggle        │          │
+└─────────┴──────────────┴─────────────────────────────┴──────────┘
+
+# Close removes the worktree automatically
+$ vibe close TKT-005
+🗑️  Removed worktree at ~/.vibekit/worktrees/myproject/feature--TKT-005-add-api-cache/
+✅ Closed TKT-005
+```
+
 ### Quality Control with Lint
 ```bash
 # Check all tickets for formatting issues
@@ -359,6 +390,7 @@ ai:
 git:
   branch_prefix: feature/
   default_base: main
+  worktrees_path: ~/.vibekit/worktrees  # Where worktrees are created
 
 # Hooks
 hooks:

package/index.js

@@ -23,7 +23,7 @@ const __dirname = dirname(__filename);
 // Available commands in VibeKit
 const AVAILABLE_COMMANDS = [
   'init', 'new', 'close', 'list', 'get-started',
-  'start', 'link', 'unlink', 'refine', 'lint', 'review', 'team'
+  'start', 'link', 'unlink', 'refine', 'lint', 'review', 'team', 'skills'
 ];
 
 /**

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@vibedx/vibekit",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "A powerful CLI tool for managing development tickets and project workflows",
   "main": "index.js",
   "type": "module",
   "files": [
     "index.js",
     "src/",
-    "assets/"
+    "assets/",
+    "skills/"
   ],
   "bin": {
     "vibe": "index.js"

package/skills/README.md

@@ -0,0 +1,23 @@
+# VibeKit Skills
+
+Agent skills for the [open agent skills ecosystem](https://skills.sh).
+
+## Installing
+
+```bash
+npx skills add vibedx/vibekit
+```
+
+Or install directly:
+
+```bash
+npx skills add https://github.com/vibedx/vibekit/tree/main/skills/vibekit
+```
+
+## Available Skills
+
+### vibekit
+
+Ticket-driven development workflow. Teaches AI coding agents how to use the vibekit CLI to create scoped tickets before writing code, track work through git branches, and maintain living documentation.
+
+See [skills/vibekit/SKILL.md](./vibekit/SKILL.md) for full details.

package/skills/vibekit/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: vibekit
+description: Ticket-driven development workflow for AI coding agents using VibeKit CLI. Use when the user asks to create a task, feature, bug fix, or ticket; mentions "vibe new", "vibe list", or vibekit commands; or wants structured, scoped work breakdown. Triggers on phrases like "add a ticket", "track this task", "break this down", or "start a new feature". Helps agents create focused tickets with clear acceptance criteria before writing code.
+license: MIT
+---
+
+# VibeKit — Ticket-Driven Development
+
+VibeKit is a CLI for managing development tickets and AI-assisted workflows. This skill teaches agents how to use vibekit properly — create tickets before coding, work through them systematically, and keep tickets as living documentation.
+
+## 🔴 MANDATORY RULE: Always Create a Ticket First
+
+**Before writing ANY code on a repo that has a `.vibe/` directory, you MUST create a vibekit ticket.** No exceptions for features, bug fixes, refactors, or multi-step tasks.
+
+This is not a suggestion — it's the core workflow. If the user asks you to "add X", "fix Y", or "build Z", your first action should be:
+
+```bash
+vibe new "descriptive title" --assignee <your-username> --priority <level> -n
+```
+
+Then read the ticket, plan the work, and `vibe start TKT-XXX` before touching any code.
+
+**Only skip the ticket for truly trivial changes**: typo fixes, single-line config tweaks, or answering a quick question.
+
+## Why This Matters
+
+Tickets break work into scoped, focused chunks that reduce AI drift and create documentation as a side effect. They also give humans a clear trail of what was done and why — critical for collaboration between humans and agents.
+
+```bash
+# 1. Create a ticket
+vibe new "Add user authentication" --assignee <username> --priority high -n
+
+# 2. Start working (creates git branch feature/TKT-XXX-slug)
+vibe start TKT-001
+
+# 3. Implement the work, commit with ticket reference
+git commit -m "TKT-001: add login endpoint"
+
+# 4. Close when done
+vibe close TKT-001
+```
+
+## Installation
+
+```bash
+npm install -g @vibedx/vibekit
+```
+
+Then in any project:
+```bash
+vibe init          # Creates .vibe/ directory with config, team, templates
+```
+
+## Core Commands
+
+| Command | Purpose |
+|---------|---------|
+| `vibe init` | Initialize vibekit in a project |
+| `vibe new "title"` | Create a ticket |
+| `vibe list` | List all tickets |
+| `vibe start <id>` | Start work (creates git branch) |
+| `vibe start <id> --worktree` | Start work in a separate worktree |
+| `vibe close <id>` | Mark ticket done (cleans up worktree if any) |
+| `vibe lint` | Validate ticket format |
+| `vibe lint --fix` | Auto-fix missing sections |
+| `vibe refine <id>` | AI-enhance ticket details |
+| `vibe team` | Manage team members |
+
+## Creating Tickets (for AI agents)
+
+**Always use `-n` / `--no-interactive` when creating tickets programmatically.** This skips the AI enhancement prompt which would otherwise block automation.
+
+```bash
+vibe new "Fix login redirect loop" --assignee alice --priority high -n
+vibe new "Add dark mode" --assignee bob --author alice -n
+```
+
+### Useful flags
+
+- `--priority low|medium|high|critical` (default: medium)
+- `--status open|in_progress|review|done` (default: open)
+- `--assignee <username>` — who works on it
+- `--author <username>` — who created it
+- `-n` / `--no-interactive` — skip AI enhancement prompt
+
+## Ticket Structure
+
+Tickets live in `.vibe/tickets/` as markdown files with YAML frontmatter:
+
+```markdown
+---
+id: TKT-001
+title: Add user authentication
+slug: TKT-001-add-user-authentication
+status: open
+priority: high
+assignee: "alice"
+author: "bob"
+created_at: 2026-04-11T10:00:00Z
+updated_at: 2026-04-11T10:00:00Z
+---
+
+## Description
+What needs to be done and why.
+
+## Acceptance Criteria
+- [ ] Concrete checkbox 1
+- [ ] Concrete checkbox 2
+
+## Implementation Notes
+Technical details, file paths, API references.
+
+## Testing & Test Cases
+Brief test scenarios.
+```
+
+## Filtering Tickets
+
+```bash
+vibe list                       # All tickets
+vibe list --status=open         # Only open
+vibe list --assignee=alice      # Only alice's tickets
+```
+
+## Team Management
+
+Teams are stored in `.vibe/team.yml`. Assignee values in tickets should match team member IDs.
+
+```bash
+vibe team add alice --name "Alice" --github alice --slack U0ABC123 --role Engineer
+vibe team                       # List members
+vibe team show alice            # Show one member
+```
+
+## When to Use This Skill
+
+Apply vibekit workflow when:
+
+- User asks to "add a feature", "fix a bug", "implement X", "build Y"
+- Task is non-trivial (more than a one-line fix)
+- Work touches multiple files or requires planning
+- User mentions `vibe`, tickets, tracking, or task management
+- Working in a project that has a `.vibe/` directory
+
+**Don't force tickets for trivial changes** — typo fixes, config tweaks, or single-line edits can skip the ticket workflow.
+
+## Integration with Git
+
+`vibe start TKT-001` automatically:
+1. Creates branch `feature/TKT-001-<slug>` (or configured prefix)
+2. Updates ticket status to `in_progress`
+3. Switches to the new branch
+
+`vibe close TKT-001`:
+1. Updates ticket status to `done`
+2. Leaves the branch for manual merge/PR
+
+### Worktree Support (Parallel Development)
+
+Use `--worktree` / `-w` to work on multiple tickets simultaneously without switching branches:
+
+```bash
+# Start ticket in a dedicated worktree
+vibe start TKT-002 --worktree
+
+# The worktree is created at ~/.vibekit/worktrees/<repo>/<branch>/
+# Your main working directory stays on its current branch
+# cd into the worktree path to work on the ticket
+
+# Close automatically removes the worktree
+vibe close TKT-002
+
+# If the worktree has uncommitted changes, use --force
+vibe close TKT-002 --force
+```
+
+`vibe list` shows a 🌿 indicator next to tickets with active worktrees.
+
+## Automation Pattern
+
+For bots and automated agents working through tickets:
+
+```bash
+# Find open tickets assigned to you
+vibe list --assignee=mybotname --status=open
+
+# For each ticket:
+# 1. Read .vibe/tickets/TKT-XXX-*.md for full context
+# 2. Do the work on branch opus/<ticket-id>-<description>
+# 3. Commit changes
+# 4. Close: vibe close TKT-XXX
+# 5. Notify team
+```
+
+## Links
+
+- Repo: https://github.com/vibedx/vibekit
+- npm: https://www.npmjs.com/package/@vibedx/vibekit
+- Issues: https://github.com/vibedx/vibekit/issues

package/src/commands/close/index.js

@@ -2,6 +2,8 @@ import fs from 'fs';
 import path from 'path';
 import yaml from 'js-yaml';
 import { getTicketsDir } from '../../utils/index.js';
+import { removeWorktree, getGitStatus } from '../../utils/git.js';
+import { execSync } from 'child_process';
 
 /**
  * Mark a ticket as done
@@ -9,6 +11,7 @@ import { getTicketsDir } from '../../utils/index.js';
  */
 function closeCommand(args) {
   const ticketArg = args[0];
+  const forceFlag = args.includes('--force') || args.includes('-f');
 
   if (!ticketArg) {
     console.error("❌ Please provide a ticket ID or number.");
@@ -16,12 +19,12 @@ function closeCommand(args) {
   }
 
   const ticketFolder = getTicketsDir();
-  
+
   if (!fs.existsSync(ticketFolder)) {
     console.error(`❌ Tickets directory not found: ${ticketFolder}`);
     process.exit(1);
   }
-  
+
   const files = fs.readdirSync(ticketFolder);
   const normalizedInput = ticketArg.startsWith("TKT-")
     ? ticketArg
@@ -31,12 +34,11 @@ function closeCommand(args) {
 
   for (const file of files) {
     const fullPath = path.join(ticketFolder, file);
-    
-    // Skip directories
+
     if (fs.statSync(fullPath).isDirectory()) {
       continue;
     }
-    
+
     const content = fs.readFileSync(fullPath, "utf-8");
     const match = content.match(/^---\n([\s\S]*?)\n---/);
 
@@ -46,7 +48,34 @@ function closeCommand(args) {
         frontmatter.id === normalizedInput ||
         file.includes(normalizedInput)
       ) {
+        // Clean up worktree if one exists
+        if (frontmatter.worktree_path) {
+          const wtPath = frontmatter.worktree_path;
+          if (fs.existsSync(wtPath)) {
+            try {
+              // Check for uncommitted changes in the worktree
+              const wtStatus = execSync(`git -C "${wtPath}" status --porcelain`, { encoding: 'utf-8' }).trim();
+              if (wtStatus && !forceFlag) {
+                console.error(`❌ Worktree at ${wtPath} has uncommitted changes.`);
+                console.error(`   Use --force to remove it anyway, or commit/stash changes first.`);
+                process.exit(1);
+              }
+              removeWorktree(wtPath, forceFlag);
+              console.log(`🗑️  Removed worktree: ${wtPath}`);
+            } catch (error) {
+              console.warn(`⚠️  Could not remove worktree: ${error.message}`);
+            }
+          }
+          // Prune stale worktree entries
+          try {
+            execSync('git worktree prune', { stdio: 'ignore' });
+          } catch (error) {
+            // Ignore prune errors
+          }
+        }
+
         frontmatter.status = "done";
+        delete frontmatter.worktree_path;
 
         const updated = `---\n${yaml.dump(frontmatter)}---${content.split("---").slice(2).join("---")}`;
         fs.writeFileSync(fullPath, updated, "utf-8");

package/src/commands/list/index.js

@@ -54,6 +54,7 @@ function listCommand(args) {
           priority: frontmatter.priority || "medium",
           assignee: frontmatter.assignee || frontmatter.owner || "",
           author: frontmatter.author || "",
+          worktree_path: frontmatter.worktree_path || "",
           file
         });
       }
@@ -114,8 +115,7 @@ function listCommand(args) {
   
   for (const ticket of filteredTickets) {
     let statusColor = "";
-    
-    // Add color based on status
+
     switch (ticket.status) {
       case "done":
         statusColor = "\x1b[32m"; // Green
@@ -129,8 +129,8 @@ function listCommand(args) {
       default:
         statusColor = "\x1b[0m"; // Default
     }
-    
-    // Format each row
+
+    const wtIndicator = ticket.worktree_path ? " 🌿" : "";
     const truncatedTitle = ticket.title.length > titleWidth - 3
       ? ticket.title.substring(0, titleWidth - 3) + "..."
       : ticket.title;
@@ -141,13 +141,13 @@ function listCommand(args) {
           statusColor + ticket.status.padEnd(statusWidth - 1) + "\x1b[0m"
         }${"|"} ${
           (ticket.assignee || "").padEnd(assigneeWidth - 1)
-        }${"|"} ${truncatedTitle}`
+        }${"|"} ${truncatedTitle}${wtIndicator}`
       );
     } else {
       console.log(
         `${ticket.id.padEnd(idWidth)}${"|"} ${
           statusColor + ticket.status.padEnd(statusWidth - 1) + "\x1b[0m"
-        }${"|"} ${truncatedTitle}`
+        }${"|"} ${truncatedTitle}${wtIndicator}`
       );
     }
   }

package/src/commands/skills/index.js

@@ -0,0 +1,65 @@
+import { execSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+
+const SKILL_PACKAGE = 'vibedx/vibekit';
+
+function runVibeLink() {
+  const hasVibeDir = fs.existsSync(path.join(process.cwd(), '.vibe'));
+  if (!hasVibeDir) {
+    console.log('\n💡 No .vibe/ directory found. Run "vibe init" then "vibe link" to complete setup.');
+    return;
+  }
+
+  console.log('\n🔗 Running post-install: vibe link\n');
+  try {
+    execSync('vibe link', { stdio: 'inherit' });
+  } catch {
+    try {
+      execSync('npx @vibedx/vibekit link', { stdio: 'inherit' });
+    } catch {
+      console.log('\n💡 To complete setup, run: vibe link');
+    }
+  }
+}
+
+export default function skillsCommand(args) {
+  const subcommand = args[0] || 'add';
+
+  if (subcommand === 'add' || subcommand === 'install') {
+    const target = args[1] || SKILL_PACKAGE;
+    console.log(`📦 Installing skill: ${target}\n`);
+    try {
+      execSync(`npx skills add ${target}`, { stdio: 'inherit' });
+    } catch {
+      console.error('\n❌ Failed to install skill. Make sure npx is available.');
+      process.exit(1);
+    }
+
+    if (target === SKILL_PACKAGE) {
+      runVibeLink();
+    }
+  } else if (subcommand === 'remove' || subcommand === 'uninstall') {
+    const target = args[1] || SKILL_PACKAGE;
+    console.log(`🗑️  Removing skill: ${target}\n`);
+    try {
+      execSync(`npx skills remove ${target}`, { stdio: 'inherit' });
+    } catch {
+      console.error('\n❌ Failed to remove skill.');
+      process.exit(1);
+    }
+  } else if (subcommand === 'list' || subcommand === 'ls') {
+    try {
+      execSync('npx skills list', { stdio: 'inherit' });
+    } catch {
+      console.error('❌ Failed to list skills.');
+      process.exit(1);
+    }
+  } else {
+    console.log('Usage: vibe skills [command]\n');
+    console.log('Commands:');
+    console.log('  add [package]      Install a skill (default: vibedx/vibekit)');
+    console.log('  remove [package]   Remove a skill');
+    console.log('  list               List installed skills');
+  }
+}

package/src/commands/start/index.js

@@ -2,14 +2,18 @@ import fs from 'fs';
 import path from 'path';
 import yaml from 'js-yaml';
 import { getTicketsDir, getConfig, createSlug } from '../../utils/index.js';
-import { 
-  isGitRepository, 
-  getCurrentBranch, 
-  branchExistsLocally, 
+import {
+  isGitRepository,
+  getCurrentBranch,
+  branchExistsLocally,
   branchExistsRemotely,
   createAndCheckoutBranch,
   checkoutBranch,
-  getGitStatus
+  getGitStatus,
+  getRepoName,
+  getWorktreePath,
+  createWorktree,
+  createWorktreeExistingBranch
 } from '../../utils/git.js';
 
 /**
@@ -33,14 +37,17 @@ function startCommand(args) {
   let ticketId = args[0];
   let baseBranch = null;
   let updateStatus = true;
-  
+  let useWorktree = false;
+
   // Process additional arguments
   for (let i = 1; i < args.length; i++) {
     if (args[i] === '--base' && i + 1 < args.length) {
       baseBranch = args[i + 1];
-      i++; // Skip the next argument as it's the base branch
+      i++;
     } else if (args[i] === '--update-status' || args[i] === '-u') {
       updateStatus = true;
+    } else if (args[i] === '--worktree' || args[i] === '-w') {
+      useWorktree = true;
     }
   }
   
@@ -111,70 +118,126 @@ function startCommand(args) {
     ? `${branchPrefix}${slug}` 
     : `${branchPrefix}${ticketId}-${slug}`;
   
-  // Check if there are uncommitted changes
-  const gitStatus = getGitStatus();
-  if (gitStatus) {
-    console.warn('⚠️  You have uncommitted changes. Stash or commit them before switching branches.');
-    console.log('');
-  }
-  
-  // Check if the branch already exists
-  const branchExistsLocal = branchExistsLocally(branchName);
-  const branchExistsRemote = branchExistsRemotely(branchName);
-  
-  if (branchExistsLocal || branchExistsRemote) {
-    console.log(`🔍 Branch ${branchName} already exists.`);
-    
-    // Checkout the existing branch
-    if (checkoutBranch(branchName)) {
-      console.log(`✅ Switched to branch: ${branchName}`);
-    } else {
-      console.error(`❌ Failed to switch to branch: ${branchName}`);
-      process.exit(1);
-    }
-  } else {
-    console.log(`🔍 Creating new branch: ${branchName}`);
-    
-    // Create and checkout the new branch
-    if (createAndCheckoutBranch(branchName, baseBranch)) {
-      console.log(`✅ Created and switched to branch: ${branchName}`);
+  if (useWorktree) {
+    const repoName = getRepoName();
+    const worktreePath = getWorktreePath(repoName, branchName);
+
+    if (fs.existsSync(worktreePath)) {
+      console.log(`🔍 Worktree already exists at: ${worktreePath}`);
+      console.log(`✅ Ready to work in: ${worktreePath}`);
     } else {
-      console.error(`❌ Failed to create branch: ${branchName}`);
-      process.exit(1);
+      const branchExistsLocal = branchExistsLocally(branchName);
+      const branchExistsRemote = branchExistsRemotely(branchName);
+
+      try {
+        if (branchExistsLocal || branchExistsRemote) {
+          console.log(`🔍 Creating worktree for existing branch: ${branchName}`);
+          createWorktreeExistingBranch(worktreePath, branchName);
+        } else {
+          console.log(`🔍 Creating worktree with new branch: ${branchName}`);
+          createWorktree(worktreePath, branchName, baseBranch);
+        }
+        console.log(`✅ Worktree created at: ${worktreePath}`);
+      } catch (error) {
+        console.error(`❌ Failed to create worktree: ${error.message}`);
+        process.exit(1);
+      }
     }
-  }
-  
-  // Update ticket status if requested
-  if (updateStatus) {
+
+    // Store worktree_path in ticket frontmatter
     try {
-      // Read the ticket file
-      const ticketContent = fs.readFileSync(ticketPath, 'utf-8');
-      
-      // Get current timestamp in ISO format
+      const currentContent = fs.readFileSync(ticketPath, 'utf-8');
       const now = new Date().toISOString();
-      
-      // Update the status to in_progress and update the timestamp
-      let updatedContent = ticketContent
-        .replace(/^status: (.+)$/m, 'status: in_progress')
-        .replace(/^updated_at: (.+)$/m, `updated_at: ${now}`);
-      
-      // Write the updated content back to the file
+      let updatedContent = currentContent;
+
+      if (updatedContent.match(/^worktree_path: .+$/m)) {
+        updatedContent = updatedContent.replace(/^worktree_path: .+$/m, `worktree_path: "${worktreePath}"`);
+      } else {
+        updatedContent = updatedContent.replace(/^(updated_at: .+)$/m, `$1\nworktree_path: "${worktreePath}"`);
+      }
+
+      if (updateStatus) {
+        updatedContent = updatedContent
+          .replace(/^status: (.+)$/m, 'status: in_progress')
+          .replace(/^updated_at: (.+)$/m, `updated_at: "${now}"`);
+      }
+
       fs.writeFileSync(ticketPath, updatedContent, 'utf-8');
-      
-      console.log(`✅ Updated ticket status to: in_progress`);
-      console.log(`✅ Updated timestamp to: ${now}`);
+      if (updateStatus) {
+        console.log(`✅ Updated ticket status to: in_progress`);
+      }
     } catch (error) {
-      console.error(`❌ Failed to update ticket status: ${error.message}`);
+      console.error(`❌ Failed to update ticket: ${error.message}`);
+    }
+
+    console.log('');
+    console.log(`🎯 Now working on: ${ticketId} - ${title}`);
+    console.log(`🌿 Branch: ${branchName}`);
+    console.log(`📂 Worktree: ${worktreePath}`);
+    console.log('');
+    console.log('To start working in the worktree:');
+    console.log(`  cd ${worktreePath}`);
+    console.log('');
+    console.log('💡 Run `npm install` in the worktree to install dependencies.');
+  } else {
+    // Check if there are uncommitted changes
+    const gitStatus = getGitStatus();
+    if (gitStatus) {
+      console.warn('⚠️  You have uncommitted changes. Stash or commit them before switching branches.');
+      console.log('');
+    }
+
+    // Check if the branch already exists
+    const branchExistsLocal = branchExistsLocally(branchName);
+    const branchExistsRemote = branchExistsRemotely(branchName);
+
+    if (branchExistsLocal || branchExistsRemote) {
+      console.log(`🔍 Branch ${branchName} already exists.`);
+
+      if (checkoutBranch(branchName)) {
+        console.log(`✅ Switched to branch: ${branchName}`);
+      } else {
+        console.error(`❌ Failed to switch to branch: ${branchName}`);
+        process.exit(1);
+      }
+    } else {
+      console.log(`🔍 Creating new branch: ${branchName}`);
+
+      if (createAndCheckoutBranch(branchName, baseBranch)) {
+        console.log(`✅ Created and switched to branch: ${branchName}`);
+      } else {
+        console.error(`❌ Failed to create branch: ${branchName}`);
+        process.exit(1);
+      }
+    }
+
+    // Update ticket status if requested
+    if (updateStatus) {
+      try {
+        const currentContent = fs.readFileSync(ticketPath, 'utf-8');
+        const now = new Date().toISOString();
+
+        let updatedContent = currentContent
+          .replace(/^status: (.+)$/m, 'status: in_progress')
+          .replace(/^updated_at: (.+)$/m, `updated_at: ${now}`);
+
+        fs.writeFileSync(ticketPath, updatedContent, 'utf-8');
+
+        console.log(`✅ Updated ticket status to: in_progress`);
+        console.log(`✅ Updated timestamp to: ${now}`);
+      } catch (error) {
+        console.error(`❌ Failed to update ticket status: ${error.message}`);
+      }
     }
+
+    // Summary
+    console.log('');
+    console.log(`🎯 Now working on: ${ticketId} - ${title}`);
+    console.log(`🌿 Branch: ${branchName}`);
+    console.log('');
+    console.log('To push this branch to remote:');
+    console.log(`  git push -u origin ${branchName}`);
   }
-  
-  // Summary
-  console.log('');
-  console.log(`🎯 Now working on: ${ticketId} - ${title}`);
-  console.log(`🌿 Branch: ${branchName}`);
-  console.log('');
-  console.log('To push this branch to remote:');
-  console.log(`  git push -u origin ${branchName}`);
 }
 
 export default startCommand;

package/src/utils/git.js

@@ -1,5 +1,6 @@
 import { execSync } from 'child_process';
 import fs from 'fs';
+import os from 'os';
 import path from 'path';
 
 /**
@@ -134,6 +135,106 @@ function getGitStatus() {
   }
 }
 
+function getRepoRoot() {
+  try {
+    return execSync('git rev-parse --show-toplevel', { encoding: 'utf-8' }).trim();
+  } catch (error) {
+    return null;
+  }
+}
+
+function getMainWorktreeRoot() {
+  try {
+    const worktrees = execSync('git worktree list --porcelain', { encoding: 'utf-8' });
+    const firstWorktreeLine = worktrees.split('\n').find(line => line.startsWith('worktree '));
+    if (firstWorktreeLine) {
+      return firstWorktreeLine.replace('worktree ', '');
+    }
+    return getRepoRoot();
+  } catch (error) {
+    return getRepoRoot();
+  }
+}
+
+function getRepoName() {
+  try {
+    const remoteUrl = execSync('git remote get-url origin', { encoding: 'utf-8' }).trim();
+    // Handle git@github.com:org/repo.git
+    let match = remoteUrl.match(/[:/]([^/]+?)(?:\.git)?$/);
+    if (match) return match[1];
+  } catch (error) {
+    // No remote — fall through
+  }
+  const root = getRepoRoot();
+  return root ? path.basename(root) : 'unknown-repo';
+}
+
+function getWorktreesDir(repoName) {
+  const name = repoName || getRepoName();
+  return path.join(os.homedir(), '.vibekit', 'worktrees', name);
+}
+
+function sanitizeBranchForPath(branch) {
+  return branch.replace(/\//g, '--');
+}
+
+function getWorktreePath(repoName, branch) {
+  return path.join(getWorktreesDir(repoName), sanitizeBranchForPath(branch));
+}
+
+function createWorktree(worktreePath, branch, baseBranch) {
+  const base = baseBranch || getDefaultBaseBranch();
+  try {
+    execSync(`git fetch origin ${base}`, { stdio: 'ignore' });
+  } catch (error) {
+    // Ignore fetch errors
+  }
+  fs.mkdirSync(path.dirname(worktreePath), { recursive: true });
+  try {
+    execSync(`git worktree add "${worktreePath}" -b ${branch} origin/${base}`, { stdio: 'pipe' });
+  } catch (error) {
+    execSync(`git worktree add "${worktreePath}" -b ${branch} ${base}`, { stdio: 'pipe' });
+  }
+  return true;
+}
+
+function createWorktreeExistingBranch(worktreePath, branch) {
+  fs.mkdirSync(path.dirname(worktreePath), { recursive: true });
+  execSync(`git worktree add "${worktreePath}" ${branch}`, { stdio: 'pipe' });
+  return true;
+}
+
+function removeWorktree(worktreePath, force = false) {
+  const forceFlag = force ? ' --force' : '';
+  execSync(`git worktree remove "${worktreePath}"${forceFlag}`, { stdio: 'pipe' });
+  return true;
+}
+
+function listWorktrees() {
+  try {
+    const output = execSync('git worktree list --porcelain', { encoding: 'utf-8' });
+    const worktrees = [];
+    let current = {};
+    for (const line of output.split('\n')) {
+      if (line.startsWith('worktree ')) {
+        if (current.path) worktrees.push(current);
+        current = { path: line.replace('worktree ', '') };
+      } else if (line.startsWith('branch refs/heads/')) {
+        current.branch = line.replace('branch refs/heads/', '');
+      } else if (line === 'bare') {
+        current.bare = true;
+      } else if (line === '') {
+        if (current.path) worktrees.push(current);
+        current = {};
+      }
+    }
+    if (current.path) worktrees.push(current);
+    return worktrees;
+  } catch (error) {
+    return [];
+  }
+}
+
 export {
   isGitRepository,
   getCurrentBranch,
@@ -142,5 +243,15 @@ export {
   getDefaultBaseBranch,
   createAndCheckoutBranch,
   checkoutBranch,
-  getGitStatus
+  getGitStatus,
+  getRepoRoot,
+  getMainWorktreeRoot,
+  getRepoName,
+  getWorktreesDir,
+  getWorktreePath,
+  sanitizeBranchForPath,
+  createWorktree,
+  createWorktreeExistingBranch,
+  removeWorktree,
+  listWorktrees
 };

package/src/utils/index.js

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import yaml from 'js-yaml';
+import { getRepoRoot, getMainWorktreeRoot } from './git.js';
 
 /**
  * Get the path to the tickets directory from config or use default
@@ -9,9 +10,26 @@ import yaml from 'js-yaml';
  * @returns {string} Absolute path to the tickets directory
  * @throws {Error} Logs error but doesn't throw - returns default path
  */
+function getProjectRoot() {
+  const cwd = process.cwd();
+  if (fs.existsSync(path.join(cwd, '.vibe'))) {
+    return cwd;
+  }
+  // Only resolve to main worktree when cwd IS a worktree root (not a subdirectory)
+  const repoRoot = getRepoRoot();
+  if (repoRoot && repoRoot === cwd) {
+    const mainRoot = getMainWorktreeRoot();
+    if (mainRoot && mainRoot !== cwd && fs.existsSync(path.join(mainRoot, '.vibe'))) {
+      return mainRoot;
+    }
+  }
+  return cwd;
+}
+
 function getTicketsDir() {
-  const configPath = path.join(process.cwd(), '.vibe', 'config.yml');
-  let ticketDir = path.join(process.cwd(), '.vibe', 'tickets');
+  const root = getProjectRoot();
+  const configPath = path.join(root, '.vibe', 'config.yml');
+  let ticketDir = path.join(root, '.vibe', 'tickets');
   
   try {
     if (fs.existsSync(configPath)) {
@@ -19,7 +37,7 @@ function getTicketsDir() {
       const config = yaml.load(configContent) || {};
       
       if (config.tickets?.path && typeof config.tickets.path === 'string') {
-        const customPath = path.resolve(process.cwd(), config.tickets.path);
+        const customPath = path.resolve(root, config.tickets.path);
         ticketDir = customPath;
       }
     }
@@ -40,7 +58,8 @@ function getTicketsDir() {
  * console.log(config.tickets?.path); // Access tickets path
  */
 function getConfig() {
-  const configPath = path.join(process.cwd(), '.vibe', 'config.yml');
+  const root = getProjectRoot();
+  const configPath = path.join(root, '.vibe', 'config.yml');
   let config = {};
   
   try {
@@ -180,10 +199,12 @@ function createFullSlug(ticketId, slugText) {
  * @returns {string} Absolute path to the config.yml file
  */
 function getConfigPath() {
-  return path.join(process.cwd(), '.vibe', 'config.yml');
+  const root = getProjectRoot();
+  return path.join(root, '.vibe', 'config.yml');
 }
 
 export {
+  getProjectRoot,
   getTicketsDir,
   getConfig,
   getConfigPath,