@vibedx/vibekit 0.8.8 → 0.10.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.10.0",
   "description": "A powerful CLI tool for managing development tickets and project workflows",
   "main": "index.js",
   "type": "module",
@@ -8,7 +8,8 @@
     "index.js",
     "src/",
     "assets/",
-    "skills/"
+    "skills/",
+    "vibekit-plugin/"
   ],
   "bin": {
     "vibe": "index.js"

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.');
+  });
+});