@vibedx/vibekit 0.8.8 → 0.9.0

package/README.md

@@ -126,6 +126,40 @@ vibe start TKT-001 --agent                  # Single ticket, current directory
 vibe start TKT-001 TKT-002 -w --agent       # Multiple tickets in worktrees with agents
 ```
 
+### 📋 Plans → Tickets
+```bash
+# Save a Claude implementation plan to .vibe/plans/, then break it into tickets.
+# Preview the extracted tickets (nothing is written by default)
+vibe plan to-ticket .vibe/plans/my-feature.md
+
+# Create the tickets once the breakdown looks right
+vibe plan to-ticket .vibe/plans/my-feature.md --auto
+
+# Show the extracted items without creating anything
+vibe plan to-ticket .vibe/plans/my-feature.md --dry-run
+```
+
+### 🔀 Pull Requests
+```bash
+# Open a GitHub PR from the current ticket branch (title/body from the ticket)
+vibe pr
+
+# Open PRs for specific tickets
+vibe pr TKT-003 TKT-004
+
+# Open PRs for all worktree branches
+vibe pr --all
+
+# Open as a draft
+vibe pr --draft
+```
+
+### 🐝 Swarm (Parallel Agents)
+```bash
+# Spawn parallel Claude agents across multiple tickets in isolated worktrees
+vibe swarm TKT-001 TKT-002 TKT-003
+```
+
 ### 👥 Team Management
 ```bash
 # List team members

package/index.js

@@ -24,7 +24,7 @@ const __dirname = dirname(__filename);
 const AVAILABLE_COMMANDS = [
   'init', 'new', 'close', 'list', 'get-started',
   'start', 'link', 'unlink', 'refine', 'lint', 'review', 'team', 'skills',
-  'status', 'stats', 'pr', 'swarm'
+  'status', 'stats', 'plan', 'pr', 'swarm'
 ];
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibedx/vibekit",
-  "version": "0.8.8",
+  "version": "0.9.0",
   "description": "A powerful CLI tool for managing development tickets and project workflows",
   "main": "index.js",
   "type": "module",

package/skills/vibekit/SKILL.md

@@ -69,6 +69,8 @@ vibe init          # Creates .vibe/ directory with config, team, templates
 | `vibe lint` | Validate ticket format |
 | `vibe lint --fix` | Auto-fix missing sections |
 | `vibe refine <id>` | AI-enhance ticket details |
+| `vibe plan to-ticket <file>` | Convert a saved plan into tickets (AI) |
+| `vibe swarm` | Spawn parallel agents across open tickets in worktrees |
 | `vibe team` | Manage team members |
 
 ## Creating Tickets (for AI agents)
@@ -232,6 +234,58 @@ vibe pr --draft
 
 PR title and body are auto-populated from ticket content. Ticket status is set to `review`.
 
+### Plans → Tickets
+
+When you (Claude) produce an implementation plan, save it to `.vibe/plans/` as a
+markdown file, then turn it into tickets:
+
+```bash
+# Preview the tickets vibekit would extract from a plan (no files written)
+vibe plan to-ticket .vibe/plans/my-feature.md
+
+# Create the tickets once the breakdown looks right
+vibe plan to-ticket .vibe/plans/my-feature.md --auto
+
+# Dry-run shows the extracted items without creating anything
+vibe plan to-ticket .vibe/plans/my-feature.md --dry-run
+```
+
+The command sends the plan to Claude, which extracts discrete work items
+(title, description, acceptance criteria, priority, estimate) and writes one
+ticket per item to `.vibe/tickets/`. Default is preview-then-confirm: it shows
+the breakdown and only writes files when you pass `--auto`. Chain it with
+`vibe start TKT-XXX` to begin work.
+
+### Swarming (Parallel Agents)
+
+`vibe swarm` spins up multiple Claude agents at once, each in its own worktree,
+to burn down a batch of tickets in parallel:
+
+```bash
+# Swarm all open tickets (capped by config swarm.maxAgents, default 3)
+vibe swarm
+
+# Limit the number of concurrent agents
+vibe swarm --count 5
+
+# Only swarm tickets matching a filter (frontmatter key:value)
+vibe swarm --filter priority:high
+
+# Use a specific base branch for the worktrees
+vibe swarm --base main
+
+# Check on a running swarm
+vibe swarm status
+```
+
+Configure caps and timeout in `.vibe/config.yml`:
+
+```yaml
+swarm:
+  maxAgents: 3
+  timeout: 900  # seconds
+```
+
 ### Monitoring Progress
 
 ```bash

package/src/commands/init/index.js

@@ -105,13 +105,14 @@ async function initCommand(args) {
 
     fs.mkdirSync(targetFolder, { recursive: true });
     fs.mkdirSync(path.join(targetFolder, 'tickets'), { recursive: true });
+    fs.mkdirSync(path.join(targetFolder, 'plans'), { recursive: true });
     fs.mkdirSync(path.join(targetFolder, '.templates'), { recursive: true });
 
     fs.copyFileSync(configSrc, path.join(targetFolder, 'config.yml'));
     fs.copyFileSync(templateSrc, path.join(targetFolder, '.templates', 'default.md'));
     fs.copyFileSync(teamSrc, path.join(targetFolder, 'team.yml'));
 
-    console.log(`✅ '${targetFolder}' initialized with config, tickets/, and .templates/default.md`);
+    console.log(`✅ '${targetFolder}' initialized with config, tickets/, plans/, and .templates/default.md`);
   } else {
     console.log(`⚠️  Folder '${targetFolder}' already exists. Skipping .vibe creation.`);
   }

package/src/commands/plan/index.js

@@ -0,0 +1,283 @@
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+import { execSync, spawn } from 'child_process';
+import { getTicketsDir, getConfig } from '../../utils/index.js';
+import {
+  isGitRepository,
+  getRepoName,
+  getRepoRoot,
+  getWorktreePath,
+  createWorktree,
+  createWorktreeExistingBranch,
+  branchExistsLocally,
+  branchExistsRemotely,
+  getDefaultBaseBranch
+} from '../../utils/git.js';
+import toTicketCommand from './to-ticket.js';
+
+function parseTicketIds(args) {
+  const ids = [];
+  const flags = {};
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+    if (arg === '--base' && i + 1 < args.length) {
+      flags.baseBranch = args[i + 1];
+      i += 2;
+    } else if (arg === '--dry-run') {
+      flags.dryRun = true;
+      i++;
+    } else if (arg === '--no-install') {
+      flags.noInstall = true;
+      i++;
+    } else if (arg === '--prompt' && i + 1 < args.length) {
+      flags.prompt = args[i + 1];
+      i += 2;
+    } else if (arg.startsWith('--status=')) {
+      flags.statusFilter = arg.split('=')[1];
+      i++;
+    } else if (!arg.startsWith('-')) {
+      ids.push(arg);
+      i++;
+    } else {
+      i++;
+    }
+  }
+  return { ids, flags };
+}
+
+function normalizeTicketId(input) {
+  if (input.startsWith('TKT-')) return input;
+  if (/^\d+$/.test(input)) return `TKT-${input.padStart(3, '0')}`;
+  return null;
+}
+
+function loadTicket(ticketsDir, ticketId) {
+  const files = fs.readdirSync(ticketsDir).filter(f => f.startsWith(`${ticketId}-`));
+  if (files.length === 0) return null;
+  const filePath = path.join(ticketsDir, files[0]);
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+  const frontmatter = yaml.load(match[1]);
+  return { frontmatter, content, filePath, fileName: files[0] };
+}
+
+function loadTicketsByStatus(ticketsDir, status) {
+  const files = fs.readdirSync(ticketsDir).filter(f => f.endsWith('.md'));
+  const tickets = [];
+  for (const file of files) {
+    const filePath = path.join(ticketsDir, file);
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (match) {
+      const frontmatter = yaml.load(match[1]);
+      if (frontmatter.status === status) {
+        tickets.push({ frontmatter, content, filePath, fileName: file });
+      }
+    }
+  }
+  return tickets;
+}
+
+function getBranchName(ticket, config) {
+  const branchPrefix = config.git?.branch_prefix || '';
+  const slug = ticket.frontmatter.slug || ticket.frontmatter.id;
+  return slug.includes(ticket.frontmatter.id)
+    ? `${branchPrefix}${slug}`
+    : `${branchPrefix}${ticket.frontmatter.id}-${slug}`;
+}
+
+function updateTicketStatus(ticket, worktreePath) {
+  const now = new Date().toISOString();
+  let updatedContent = ticket.content;
+
+  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}"`);
+  }
+
+  updatedContent = updatedContent
+    .replace(/^status: (.+)$/m, 'status: in_progress')
+    .replace(/^updated_at: (.+)$/m, `updated_at: "${now}"`);
+
+  fs.writeFileSync(ticket.filePath, updatedContent, 'utf-8');
+}
+
+async function planCommand(args) {
+  // Handle subcommands
+  if (args.length > 0 && args[0] === 'to-ticket') {
+    return toTicketCommand(args.slice(1));
+  }
+
+  if (!isGitRepository()) {
+    console.error('❌ Not in a git repository.');
+    process.exit(1);
+  }
+
+  const { ids, flags } = parseTicketIds(args);
+
+  if (ids.length === 0 && !flags.statusFilter) {
+    console.error('❌ Usage:');
+    console.error('  vibe plan <TKT-001> <TKT-002> ...  Spawn parallel agents for tickets');
+    console.error('  vibe plan to-ticket <file> [--auto] [--dry-run]  Convert plan to tickets');
+    console.error('');
+    console.error('Options for parallel agents:');
+    console.error('  --status=<status>  Start all tickets with this status (e.g. --status=open)');
+    console.error('  --base <branch>    Base branch for worktrees (default: main)');
+    console.error('  --dry-run          Show what would happen without doing it');
+    console.error('  --no-install       Skip npm install in worktrees');
+    console.error('  --prompt "..."     Custom prompt to pass to each Claude agent');
+    console.error('');
+    console.error('Options for plan to-ticket:');
+    console.error('  --auto             Automatically create tickets (shows preview by default)');
+    console.error('  --dry-run          Show extracted tickets without creating them');
+    process.exit(1);
+  }
+
+  const config = getConfig();
+  const ticketsDir = getTicketsDir();
+  const repoName = getRepoName();
+  const repoRoot = getRepoRoot();
+
+  let tickets = [];
+
+  if (flags.statusFilter) {
+    tickets = loadTicketsByStatus(ticketsDir, flags.statusFilter);
+    if (tickets.length === 0) {
+      console.error(`❌ No tickets found with status: ${flags.statusFilter}`);
+      process.exit(1);
+    }
+    console.log(`📋 Found ${tickets.length} ticket(s) with status "${flags.statusFilter}"`);
+  }
+
+  for (const id of ids) {
+    const ticketId = normalizeTicketId(id);
+    if (!ticketId) {
+      console.error(`❌ Invalid ticket ID: ${id}`);
+      process.exit(1);
+    }
+    const ticket = loadTicket(ticketsDir, ticketId);
+    if (!ticket) {
+      console.error(`❌ Ticket ${ticketId} not found.`);
+      process.exit(1);
+    }
+    if (!tickets.find(t => t.frontmatter.id === ticket.frontmatter.id)) {
+      tickets.push(ticket);
+    }
+  }
+
+  if (tickets.length === 0) {
+    console.error('❌ No tickets to start.');
+    process.exit(1);
+  }
+
+  console.log('');
+  console.log(`🚀 Planning ${tickets.length} ticket(s) for parallel work:\n`);
+
+  const worktreeInfos = [];
+
+  for (const ticket of tickets) {
+    const branchName = getBranchName(ticket, config);
+    const worktreePath = getWorktreePath(repoName, branchName);
+    const title = ticket.frontmatter.title || 'Untitled';
+
+    worktreeInfos.push({
+      ticket,
+      branchName,
+      worktreePath,
+      title,
+      alreadyExists: fs.existsSync(worktreePath)
+    });
+
+    const status = fs.existsSync(worktreePath) ? '(exists)' : '(new)';
+    console.log(`  ${ticket.frontmatter.id} — ${title}`);
+    console.log(`    🌿 ${branchName} ${status}`);
+    console.log(`    📂 ${worktreePath}`);
+    console.log('');
+  }
+
+  if (flags.dryRun) {
+    console.log('🏁 Dry run complete. No changes made.');
+    return;
+  }
+
+  // Create worktrees
+  for (const info of worktreeInfos) {
+    if (info.alreadyExists) {
+      console.log(`✅ ${info.ticket.frontmatter.id}: Worktree already exists`);
+      continue;
+    }
+
+    try {
+      const branchExists = branchExistsLocally(info.branchName) || branchExistsRemotely(info.branchName);
+      if (branchExists) {
+        createWorktreeExistingBranch(info.worktreePath, info.branchName);
+      } else {
+        createWorktree(info.worktreePath, info.branchName, flags.baseBranch);
+      }
+      console.log(`✅ ${info.ticket.frontmatter.id}: Worktree created`);
+    } catch (error) {
+      console.error(`❌ ${info.ticket.frontmatter.id}: Failed to create worktree — ${error.message}`);
+      continue;
+    }
+
+    updateTicketStatus(info.ticket, info.worktreePath);
+  }
+
+  // Install dependencies in worktrees
+  if (!flags.noInstall) {
+    const pkgExists = fs.existsSync(path.join(repoRoot, 'package.json'));
+    if (pkgExists) {
+      console.log('\n📦 Installing dependencies in worktrees...');
+      for (const info of worktreeInfos) {
+        if (fs.existsSync(path.join(info.worktreePath, 'package.json'))) {
+          try {
+            execSync('npm install --silent', { cwd: info.worktreePath, stdio: 'ignore' });
+            console.log(`  ✅ ${info.ticket.frontmatter.id}: npm install done`);
+          } catch (error) {
+            console.warn(`  ⚠️  ${info.ticket.frontmatter.id}: npm install failed — ${error.message}`);
+          }
+        }
+      }
+    }
+  }
+
+  // Spawn Claude agents
+  console.log('\n🤖 Spawning Claude agents...\n');
+
+  const agents = [];
+  for (const info of worktreeInfos) {
+    const ticketContent = fs.readFileSync(info.ticket.filePath, 'utf-8');
+    const prompt = flags.prompt
+      ? flags.prompt
+      : `You are working on ticket ${info.ticket.frontmatter.id}: ${info.title}\n\nHere is the full ticket:\n\n${ticketContent}\n\nImplement the ticket requirements. Follow the acceptance criteria. Commit your work when done.`;
+
+    try {
+      const agentProcess = spawn('claude', ['-p', prompt, '--allowedTools', 'Edit,Write,Bash,Read,Glob,Grep'], {
+        cwd: info.worktreePath,
+        stdio: 'ignore',
+        detached: true
+      });
+
+      agentProcess.unref();
+      agents.push({ id: info.ticket.frontmatter.id, pid: agentProcess.pid });
+      console.log(`  🤖 ${info.ticket.frontmatter.id}: Agent spawned (PID ${agentProcess.pid}) in ${info.worktreePath}`);
+    } catch (error) {
+      console.error(`  ❌ ${info.ticket.frontmatter.id}: Failed to spawn agent — ${error.message}`);
+    }
+  }
+
+  console.log('\n🏁 All agents launched!\n');
+  console.log('Monitor progress:');
+  console.log('  vibe list --status=in_progress   # see active tickets');
+  console.log('  git worktree list                 # see all worktrees');
+  console.log('');
+  console.log('When agents finish, open PRs:');
+  console.log('  vibe pr --all                     # open PRs for all worktree branches');
+  console.log(`  vibe pr ${tickets.map(t => t.frontmatter.id).join(' ')}     # open PRs for specific tickets`);
+}
+
+export default planCommand;

package/src/commands/plan/index.test.js

@@ -0,0 +1,127 @@
+import { jest } from '@jest/globals';
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+
+// Mock dependencies
+jest.unstable_mockModule('child_process', () => ({
+  execSync: jest.fn(),
+  spawn: jest.fn(() => ({ unref: jest.fn(), pid: 12345 }))
+}));
+
+let ticketIdCounter = 1;
+jest.unstable_mockModule('../../utils/index.js', () => ({
+  getTicketsDir: jest.fn(),
+  getConfig: jest.fn(() => ({ git: { branch_prefix: 'feature/' } })),
+  createSlug: jest.fn(title => title.toLowerCase().replace(/\s+/g, '-')),
+  getNextTicketId: jest.fn(() => `TKT-${String(ticketIdCounter++).padStart(3, '0')}`)
+}));
+
+jest.unstable_mockModule('../../utils/git.js', () => ({
+  isGitRepository: jest.fn(() => true),
+  getRepoName: jest.fn(() => 'test-repo'),
+  getRepoRoot: jest.fn(() => '/tmp/test-repo'),
+  getWorktreePath: jest.fn((repo, branch) => `/tmp/.vibekit/worktrees/${repo}/${branch}`),
+  createWorktree: jest.fn(),
+  createWorktreeExistingBranch: jest.fn(),
+  branchExistsLocally: jest.fn(() => false),
+  branchExistsRemotely: jest.fn(() => false),
+  getDefaultBaseBranch: jest.fn(() => 'main')
+}));
+
+const { default: planCommand } = await import('./index.js');
+const { getTicketsDir, getConfig } = await import('../../utils/index.js');
+const { isGitRepository, getWorktreePath, createWorktree } = await import('../../utils/git.js');
+const childProcess = await import('child_process');
+
+const TICKET_CONTENT = `---
+id: TKT-001
+title: Add login page
+slug: TKT-001-add-login-page
+status: open
+priority: high
+assignee: dev1
+author: pm
+created_at: "2026-01-01T00:00:00Z"
+updated_at: "2026-01-01T00:00:00Z"
+---
+
+## Description
+Add a login page.
+
+## Acceptance Criteria
+- [ ] Login form exists
+`;
+
+describe('plan command', () => {
+  let tempDir;
+  let mockExit;
+  let mockConsoleLog;
+  let mockConsoleError;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join('/tmp', 'vibe-plan-test-'));
+    const ticketsDir = path.join(tempDir, '.vibe', 'tickets');
+    fs.mkdirSync(ticketsDir, { recursive: true });
+    fs.writeFileSync(path.join(ticketsDir, 'TKT-001-add-login-page.md'), TICKET_CONTENT);
+
+    getTicketsDir.mockReturnValue(ticketsDir);
+    mockExit = jest.spyOn(process, 'exit').mockImplementation(() => { throw new Error('process.exit'); });
+    mockConsoleLog = jest.spyOn(console, 'log').mockImplementation(() => {});
+    mockConsoleError = jest.spyOn(console, 'error').mockImplementation(() => {});
+    childProcess.execSync.mockImplementation(() => '');
+
+    // Worktree path doesn't exist yet
+    getWorktreePath.mockReturnValue(path.join(tempDir, 'worktree-TKT-001'));
+  });
+
+  afterEach(() => {
+    mockExit.mockRestore();
+    mockConsoleLog.mockRestore();
+    mockConsoleError.mockRestore();
+    fs.rmSync(tempDir, { recursive: true, force: true });
+    jest.clearAllMocks();
+  });
+
+  test('shows usage when no arguments provided', async () => {
+    await expect(planCommand([])).rejects.toThrow('process.exit');
+    expect(mockConsoleError).toHaveBeenCalledWith(expect.stringContaining('Usage:'));
+  });
+
+  test('exits if not in git repo', async () => {
+    isGitRepository.mockReturnValueOnce(false);
+    await expect(planCommand(['TKT-001'])).rejects.toThrow('process.exit');
+    expect(mockConsoleError).toHaveBeenCalledWith('❌ Not in a git repository.');
+  });
+
+  test('dry run shows plan without creating worktrees', async () => {
+    await planCommand(['TKT-001', '--dry-run']);
+    expect(mockConsoleLog).toHaveBeenCalledWith('🏁 Dry run complete. No changes made.');
+    expect(createWorktree).not.toHaveBeenCalled();
+  });
+
+  test('creates worktree and spawns agent for ticket', async () => {
+    await planCommand(['TKT-001', '--no-install']);
+    expect(createWorktree).toHaveBeenCalled();
+    expect(childProcess.spawn).toHaveBeenCalledWith(
+      'claude',
+      expect.arrayContaining(['-p']),
+      expect.objectContaining({ stdio: 'ignore', detached: true })
+    );
+  });
+
+  test('handles --status=open filter', async () => {
+    await planCommand(['--status=open', '--dry-run']);
+    expect(mockConsoleLog).toHaveBeenCalledWith(expect.stringContaining('TKT-001'));
+  });
+
+  test('errors on invalid ticket ID', async () => {
+    await expect(planCommand(['INVALID'])).rejects.toThrow('process.exit');
+    expect(mockConsoleError).toHaveBeenCalledWith(expect.stringContaining('Invalid ticket ID'));
+  });
+
+  test('errors when ticket not found', async () => {
+    await expect(planCommand(['TKT-999'])).rejects.toThrow('process.exit');
+    expect(mockConsoleError).toHaveBeenCalledWith('❌ Ticket TKT-999 not found.');
+  });
+});

package/src/commands/plan/to-ticket.js

@@ -0,0 +1,312 @@
+import fs from 'fs';
+import path from 'path';
+import { spawn } from 'child_process';
+import yaml from 'js-yaml';
+import { getTicketsDir, getConfig, getNextTicketId, createSlug } from '../../utils/index.js';
+import { logger } from '../../utils/cli.js';
+
+/**
+ * Parse CLI arguments for the to-ticket subcommand
+ */
+function parseToTicketArgs(args) {
+  let planFile = null;
+  let dryRun = false;
+  let autoCreate = false;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--dry-run') {
+      dryRun = true;
+    } else if (arg === '--auto') {
+      autoCreate = true;
+    } else if (!arg.startsWith('-')) {
+      planFile = arg;
+    }
+  }
+
+  return { planFile, dryRun, autoCreate };
+}
+
+/**
+ * Read and validate a plan file
+ */
+function readPlanFile(planFile) {
+  if (!planFile) {
+    throw new Error('Plan file path is required');
+  }
+
+  // Resolve path relative to cwd if not absolute
+  const filePath = path.isAbsolute(planFile)
+    ? planFile
+    : path.join(process.cwd(), planFile);
+
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`Plan file not found: ${filePath}`);
+  }
+
+  const content = fs.readFileSync(filePath, 'utf-8');
+  return { filePath, content };
+}
+
+/**
+ * Create a prompt for Claude to extract tickets from a plan
+ */
+function createExtractionPrompt(planContent) {
+  return `You are a senior software engineer analyzing a project plan.
+
+Plan content:
+${planContent}
+
+Extract all actionable work items from this plan and convert them to a JSON list of tickets.
+
+For each ticket, provide:
+- title: A clear, descriptive title (max 80 chars)
+- description: The main work to be done
+- acceptance_criteria: An array of 2-4 specific, measurable criteria
+- priority: One of: low, medium, high, critical
+- estimated_hours: Rough estimate (0.5, 1, 2, 4, 8, 16, 32)
+
+Return ONLY a valid JSON object with this structure:
+{
+  "tickets": [
+    {
+      "title": "...",
+      "description": "...",
+      "acceptance_criteria": ["...", "..."],
+      "priority": "medium",
+      "estimated_hours": 4
+    }
+  ]
+}
+
+Ensure each ticket is focused, actionable, and independent.`;
+}
+
+/**
+ * Parse Claude envelope and extract text
+ */
+function parseClaudeEnvelope(raw) {
+  let envelope;
+  try {
+    envelope = JSON.parse(raw.trim());
+  } catch {
+    throw new Error('Claude returned non-JSON output');
+  }
+
+  if (envelope.is_error) {
+    throw new Error(envelope.result || 'Claude reported an error');
+  }
+
+  const text = envelope.result ?? '';
+  if (!text.trim()) {
+    throw new Error('Claude returned an empty result');
+  }
+
+  return text;
+}
+
+/**
+ * Extract JSON from Claude's text response
+ */
+function extractJsonFromResponse(text) {
+  const cleaned = text.trim();
+
+  // 1. Direct parse — Claude responded with pure JSON
+  try {
+    JSON.parse(cleaned);
+    return cleaned;
+  } catch { /* fall through */ }
+
+  // 2. Markdown code block — ```json ... ``` or ``` ... ```
+  const codeBlockMatch = cleaned.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
+  if (codeBlockMatch) {
+    const inner = codeBlockMatch[1].trim();
+    try {
+      JSON.parse(inner);
+      return inner;
+    } catch { /* fall through */ }
+  }
+
+  // 3. Loose extraction — grab first {...} block
+  const objMatch = cleaned.match(/\{[\s\S]*\}/);
+  if (objMatch) {
+    try {
+      JSON.parse(objMatch[0]);
+      return objMatch[0];
+    } catch { /* fall through */ }
+  }
+
+  throw new Error('No valid JSON object found in Claude response');
+}
+
+/**
+ * Execute Claude to extract tickets from plan
+ */
+async function extractTicketsFromPlan(planContent) {
+  const prompt = createExtractionPrompt(planContent);
+
+  return new Promise((resolve, reject) => {
+    const env = { ...process.env };
+    delete env.ANTHROPIC_API_KEY;
+
+    const child = spawn('claude', ['--print', '--output-format', 'json'], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk;
+    });
+
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk;
+    });
+
+    child.on('error', (err) => {
+      reject(new Error(`Failed to spawn Claude: ${err.message}`));
+    });
+
+    child.on('close', (code) => {
+      if (!stdout.trim()) {
+        reject(new Error(stderr.trim() || `Claude exited with code ${code}`));
+        return;
+      }
+
+      try {
+        const text = parseClaudeEnvelope(stdout);
+        const jsonStr = extractJsonFromResponse(text);
+        const result = JSON.parse(jsonStr);
+        resolve(result.tickets || []);
+      } catch (err) {
+        reject(new Error(`Failed to parse Claude response: ${err.message}`));
+      }
+    });
+
+    child.stdin.write(prompt, 'utf8');
+    child.stdin.end();
+  });
+}
+
+/**
+ * Create a ticket in .vibe/tickets/
+ */
+function createTicketFile(ticketData, ticketsDir, ticketId) {
+  const slug = createSlug(ticketData.title);
+  const fileName = `${ticketId}-${slug}.md`;
+  const filePath = path.join(ticketsDir, fileName);
+
+  const acceptanceCriteria = (ticketData.acceptance_criteria || [])
+    .map(criterion => `- [ ] ${criterion}`)
+    .join('\n');
+
+  const content = `---
+id: ${ticketId}
+title: ${ticketData.title}
+slug: ${slug}
+description: ${ticketData.description || ''}
+priority: ${ticketData.priority || 'medium'}
+status: open
+created_at: "${new Date().toISOString()}"
+updated_at: "${new Date().toISOString()}"
+estimated_hours: ${ticketData.estimated_hours || 0}
+---
+
+## Description
+
+${ticketData.description || 'No description provided'}
+
+## Acceptance Criteria
+
+${acceptanceCriteria || '- [ ] Complete the work'}
+
+## Notes
+
+Generated from plan via \`vibe plan to-ticket\`.
+`;
+
+  fs.writeFileSync(filePath, content, 'utf-8');
+  return { fileName, filePath };
+}
+
+/**
+ * Main to-ticket subcommand
+ */
+async function toTicketCommand(args) {
+  try {
+    const { planFile, dryRun, autoCreate } = parseToTicketArgs(args);
+
+    // Validate plan file
+    const { filePath, content: planContent } = readPlanFile(planFile);
+
+    console.log(`📄 Reading plan: ${path.basename(filePath)}`);
+    console.log('');
+
+    // Extract tickets using Claude
+    console.log('🤖 Analyzing plan with Claude...');
+    const tickets = await extractTicketsFromPlan(planContent);
+
+    if (!tickets || tickets.length === 0) {
+      console.log('⚠️  No tickets extracted from plan.');
+      process.exit(0);
+    }
+
+    console.log(`✅ Extracted ${tickets.length} ticket(s)\n`);
+
+    // Show extracted tickets
+    for (const ticket of tickets) {
+      console.log(`📋 ${ticket.title}`);
+      console.log(`   Priority: ${ticket.priority || 'medium'}`);
+      console.log(`   Est. hours: ${ticket.estimated_hours || '?'}`);
+      if (ticket.acceptance_criteria && ticket.acceptance_criteria.length > 0) {
+        console.log(`   Criteria: ${ticket.acceptance_criteria.length} items`);
+      }
+      console.log('');
+    }
+
+    if (dryRun) {
+      console.log('🏁 Dry run complete. No tickets created.');
+      process.exit(0);
+    }
+
+    if (!autoCreate) {
+      console.log('💡 Use --auto to create these tickets automatically.');
+      process.exit(0);
+    }
+
+    // Create tickets
+    const ticketsDir = getTicketsDir();
+    if (!fs.existsSync(ticketsDir)) {
+      fs.mkdirSync(ticketsDir, { recursive: true });
+    }
+
+    console.log('✨ Creating tickets...\n');
+
+    const createdTickets = [];
+    for (const ticketData of tickets) {
+      try {
+        const ticketId = getNextTicketId(ticketsDir);
+        const result = createTicketFile(ticketData, ticketsDir, ticketId);
+        createdTickets.push({ id: ticketId, ...result });
+        console.log(`  ✅ ${ticketId}: ${ticketData.title}`);
+      } catch (error) {
+        console.error(`  ❌ Failed to create ticket: ${error.message}`);
+      }
+    }
+
+    console.log('');
+    console.log(`🎉 Created ${createdTickets.length} ticket(s)`);
+    console.log('');
+    console.log('Next steps:');
+    console.log('  vibe list           # See all tickets');
+    console.log('  vibe start TKT-XXX  # Start working on a ticket');
+
+  } catch (error) {
+    console.error(`❌ ${error.message}`);
+    process.exit(1);
+  }
+}
+
+export default toTicketCommand;

package/src/commands/plan/to-ticket.test.js

@@ -0,0 +1,149 @@
+import { jest } from '@jest/globals';
+import fs from 'fs';
+import path from 'path';
+
+let ticketIdCounter = 1;
+jest.unstable_mockModule('../../utils/index.js', () => ({
+  getTicketsDir: jest.fn(),
+  getConfig: jest.fn(() => ({})),
+  createSlug: jest.fn(title => title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '')),
+  getNextTicketId: jest.fn(() => `TKT-${String(ticketIdCounter++).padStart(3, '0')}`)
+}));
+
+const mockChild = {
+  stdout: { on: jest.fn() },
+  stderr: { on: jest.fn() },
+  stdin: { write: jest.fn(), end: jest.fn() },
+  on: jest.fn()
+};
+
+jest.unstable_mockModule('child_process', () => ({
+  spawn: jest.fn(() => mockChild)
+}));
+
+const { default: toTicketCommand } = await import('./to-ticket.js');
+const { getTicketsDir } = await import('../../utils/index.js');
+const childProcess = await import('child_process');
+
+const PLAN_CONTENT = `# Feature Plan
+
+## Goals
+- Build a login page
+- Add a settings page
+`;
+
+const CLAUDE_TICKETS = {
+  tickets: [
+    {
+      title: 'Build login page',
+      description: 'Create the login form',
+      acceptance_criteria: ['Form renders', 'Submits credentials'],
+      priority: 'high',
+      estimated_hours: 4
+    },
+    {
+      title: 'Add settings page',
+      description: 'User settings screen',
+      acceptance_criteria: ['Settings persist'],
+      priority: 'medium',
+      estimated_hours: 2
+    }
+  ]
+};
+
+// Drive the mocked Claude process: feed it a JSON envelope and close.
+function primeClaude(resultObj, { isError = false } = {}) {
+  const envelope = JSON.stringify({
+    is_error: isError,
+    result: isError ? 'boom' : JSON.stringify(resultObj)
+  });
+
+  mockChild.stdout.on.mockImplementation((event, cb) => {
+    if (event === 'data') cb(Buffer.from(envelope));
+  });
+  mockChild.stderr.on.mockImplementation(() => {});
+  mockChild.on.mockImplementation((event, cb) => {
+    if (event === 'close') cb(0);
+  });
+}
+
+describe('plan to-ticket command', () => {
+  let tempDir;
+  let ticketsDir;
+  let planFile;
+  let mockExit;
+  let mockConsoleLog;
+  let mockConsoleError;
+
+  beforeEach(() => {
+    ticketIdCounter = 1;
+    tempDir = fs.mkdtempSync(path.join('/tmp', 'vibe-to-ticket-'));
+    ticketsDir = path.join(tempDir, '.vibe', 'tickets');
+    fs.mkdirSync(ticketsDir, { recursive: true });
+    planFile = path.join(tempDir, 'plan.md');
+    fs.writeFileSync(planFile, PLAN_CONTENT);
+
+    getTicketsDir.mockReturnValue(ticketsDir);
+    mockExit = jest.spyOn(process, 'exit').mockImplementation(() => { throw new Error('process.exit'); });
+    mockConsoleLog = jest.spyOn(console, 'log').mockImplementation(() => {});
+    mockConsoleError = jest.spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    mockExit.mockRestore();
+    mockConsoleLog.mockRestore();
+    mockConsoleError.mockRestore();
+    fs.rmSync(tempDir, { recursive: true, force: true });
+    jest.clearAllMocks();
+  });
+
+  test('errors when plan file is missing', async () => {
+    await expect(toTicketCommand(['/tmp/does-not-exist.md'])).rejects.toThrow('process.exit');
+    expect(mockConsoleError).toHaveBeenCalledWith(expect.stringContaining('Plan file not found'));
+  });
+
+  test('dry-run extracts tickets without creating files', async () => {
+    primeClaude(CLAUDE_TICKETS);
+    await expect(toTicketCommand([planFile, '--dry-run'])).rejects.toThrow('process.exit');
+    expect(mockConsoleLog).toHaveBeenCalledWith(expect.stringContaining('Dry run complete'));
+    expect(fs.readdirSync(ticketsDir)).toHaveLength(0);
+  });
+
+  test('preview (no --auto) does not create tickets', async () => {
+    primeClaude(CLAUDE_TICKETS);
+    await expect(toTicketCommand([planFile])).rejects.toThrow('process.exit');
+    expect(mockConsoleLog).toHaveBeenCalledWith(expect.stringContaining('--auto'));
+    expect(fs.readdirSync(ticketsDir)).toHaveLength(0);
+  });
+
+  test('--auto creates one ticket file per extracted item', async () => {
+    primeClaude(CLAUDE_TICKETS);
+    await toTicketCommand([planFile, '--auto']);
+    const files = fs.readdirSync(ticketsDir).sort();
+    expect(files).toEqual([
+      'TKT-001-build-login-page.md',
+      'TKT-002-add-settings-page.md'
+    ].sort());
+
+    const first = fs.readFileSync(path.join(ticketsDir, 'TKT-001-build-login-page.md'), 'utf-8');
+    expect(first).toContain('id: TKT-001');
+    expect(first).toContain('priority: high');
+    expect(first).toContain('- [ ] Form renders');
+  });
+
+  test('surfaces Claude errors', async () => {
+    primeClaude(null, { isError: true });
+    await expect(toTicketCommand([planFile, '--auto'])).rejects.toThrow('process.exit');
+    expect(mockConsoleError).toHaveBeenCalledWith(expect.stringContaining('boom'));
+  });
+
+  test('spawns claude with json output format', async () => {
+    primeClaude(CLAUDE_TICKETS);
+    await toTicketCommand([planFile, '--auto']);
+    expect(childProcess.spawn).toHaveBeenCalledWith(
+      'claude',
+      expect.arrayContaining(['--print', '--output-format', 'json']),
+      expect.any(Object)
+    );
+  });
+});