@vibedx/vibekit 0.8.7 → 0.8.8

package/assets/config.yml

@@ -27,6 +27,10 @@ team:
 agent:
   timeout: 900
 
+swarm:
+  maxAgents: 3
+  timeout: 900
+
 ai:
   enabled: false
 

package/assets/standards/coding/default.md

@@ -0,0 +1,15 @@
+# Project Guidelines
+
+## Code Style
+- Follow the existing codebase conventions
+- Keep functions small and focused
+- Use descriptive variable and function names
+
+## Git Workflow
+- Write clear, concise commit messages
+- One logical change per commit
+- Keep PRs focused and reviewable
+
+## Testing
+- Write tests for new functionality
+- Ensure existing tests pass before committing

package/assets/standards/coding/karpathy.md

@@ -0,0 +1,58 @@
+# CLAUDE.md
+
+Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" -> "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" -> "Write a test that reproduces it, then make it pass"
+- "Refactor X" -> "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan with steps and verification checkpoints.
+
+---
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

package/assets/standards/frameworks/react.md

@@ -0,0 +1,36 @@
+# React Project Guidelines
+
+## Architecture
+- Use functional components with hooks
+- Keep components small and single-responsibility
+- Colocate related files (component, styles, tests, types)
+
+## State Management
+- Use local state (useState) for component-specific state
+- Lift state up when shared between siblings
+- Use context sparingly — prefer prop drilling for shallow trees
+
+## Patterns
+- Extract custom hooks for reusable logic
+- Use composition over inheritance
+- Prefer controlled components for forms
+- Memoize expensive computations with useMemo, not every render
+
+## Styling
+- Use CSS modules or the project's styling solution consistently
+- Follow mobile-first responsive design
+- Keep styles colocated with components
+
+## Testing
+- Test behavior, not implementation details
+- Use React Testing Library
+- Write integration tests for user flows, unit tests for utilities
+
+## Performance
+- Lazy load routes and heavy components
+- Avoid unnecessary re-renders — profile before optimizing
+- Use React.memo only when measured improvement exists
+
+## Git Workflow
+- One component/feature per PR
+- Write clear commit messages describing the user-facing change

package/assets/standards/languages/node.md

@@ -0,0 +1,34 @@
+# Node.js Project Guidelines
+
+## Architecture
+- Separate concerns: routes, controllers, services, data access
+- Use dependency injection for testability
+- Keep middleware thin — delegate to service layer
+
+## Error Handling
+- Use typed errors with meaningful messages
+- Let errors bubble up to a centralized handler
+- Never swallow errors silently
+- Return appropriate HTTP status codes
+
+## Security
+- Validate all external input at the boundary
+- Use parameterized queries — never interpolate user input into SQL/NoSQL
+- Keep dependencies updated; audit regularly
+- Never log sensitive data (tokens, passwords, PII)
+
+## Performance
+- Use streaming for large payloads
+- Cache expensive operations with TTLs
+- Use connection pooling for databases
+- Profile before optimizing — measure, don't guess
+
+## Testing
+- Unit test business logic in isolation
+- Integration test API endpoints with real database
+- Use fixtures, not mocks, for data layer tests
+
+## Git Workflow
+- One logical change per commit
+- Write commit messages that explain why, not what
+- Keep PRs reviewable — under 400 lines when possible

package/assets/standards/languages/python.md

@@ -0,0 +1,34 @@
+# Python Project Guidelines
+
+## Code Style
+- Follow PEP 8 — use a formatter (black, ruff) to enforce
+- Use type hints for function signatures and class attributes
+- Prefer f-strings over format() or % formatting
+- Use pathlib over os.path for file operations
+
+## Architecture
+- Keep modules focused — one responsibility per module
+- Use dataclasses or Pydantic for structured data
+- Prefer composition over deep inheritance hierarchies
+- Use context managers for resource management
+
+## Error Handling
+- Use specific exception types, not bare except
+- Let exceptions propagate — catch only when you can handle them
+- Use logging, not print, for operational output
+
+## Testing
+- Use pytest with fixtures
+- Test behavior, not implementation
+- Use parametrize for testing multiple inputs
+- Aim for integration tests over excessive mocking
+
+## Dependencies
+- Pin versions in requirements.txt or pyproject.toml
+- Use virtual environments — never install globally
+- Prefer standard library when it's sufficient
+
+## Git Workflow
+- One logical change per commit
+- Clear commit messages explaining the why
+- Keep PRs focused and reviewable

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'
+  'status', 'stats', 'pr', 'swarm'
 ];
 
 /**

package/package.json

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

package/src/commands/init/index.js

@@ -3,50 +3,129 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 import { dirname } from 'path';
 import getStartedCommand from '../get-started/index.js';
+import { arrowSelect } from '../../utils/arrow-select.js';
 
-// ESM replacement for __dirname
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-/**
- * Initialize a new VibeKit project
- * @param {string[]} args Command arguments
- */
-function initCommand(args) {
-  const targetFolder = ".vibe";
-  
-  if (fs.existsSync(targetFolder)) {
-    console.log(`⚠️  Folder '${targetFolder}' already exists. Skipping creation.`);
-    process.exit(0);
-  }
-
-  // Use real files instead of hardcoded template strings
-  const templateSrc = path.join(__dirname, "../../../assets", "default.md");
-  const configSrc = path.join(__dirname, "../../../assets", "config.yml");
-  const teamSrc = path.join(__dirname, "../../../assets", "team.yml");
-
-  fs.mkdirSync(targetFolder, { recursive: true });
-  fs.mkdirSync(path.join(targetFolder, "tickets"), { recursive: true });
-  fs.mkdirSync(path.join(targetFolder, ".templates"), { recursive: true });
-
-  // Copy files from assets directory instead of using hardcoded templates
-  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`);
-  
-  // Ask if the user wants to run get-started
-  console.log("\nWould you like to create sample tickets and documentation? (y/n)");
-  
-  // Since we can't get user input directly in this environment, we'll check for a flag
-  const runGetStarted = args.includes("--with-samples") || args.includes("-s");
-  
+const TEMPLATES = [
+  { name: 'default', value: 'default', category: 'coding', description: 'Minimal project conventions' },
+  { name: 'karpathy', value: 'karpathy', category: 'coding', description: 'Karpathy-style dev philosophy' },
+  { name: 'react', value: 'react', category: 'frameworks', description: 'React/frontend best practices' },
+  { name: 'node', value: 'node', category: 'languages', description: 'Node.js backend guidelines' },
+  { name: 'python', value: 'python', category: 'languages', description: 'Python project conventions' },
+];
+
+function getTemplatePath(templateName) {
+  const template = TEMPLATES.find(t => t.value === templateName);
+  if (!template) return null;
+  return path.join(__dirname, '../../../assets/standards', template.category, `${templateName}.md`);
+}
+
+function listTemplates() {
+  console.log('\n📋 Available templates:\n');
+  const categories = [...new Set(TEMPLATES.map(t => t.category))];
+  for (const cat of categories) {
+    console.log(`  ${cat}/`);
+    for (const t of TEMPLATES.filter(t => t.category === cat)) {
+      console.log(`    ${t.value.padEnd(18)} ${t.description}`);
+    }
+  }
+  console.log('\nUsage: vibe init --template <name>');
+  console.log('       vibe init --template          (interactive picker)\n');
+}
+
+function applyTemplate(templateName, targetDir) {
+  const templatePath = getTemplatePath(templateName);
+  if (!templatePath || !fs.existsSync(templatePath)) {
+    console.error(`❌ Template "${templateName}" not found.`);
+    process.exit(1);
+  }
+
+  const templateContent = fs.readFileSync(templatePath, 'utf-8');
+  const destPath = path.join(targetDir, 'CLAUDE.md');
+
+  if (fs.existsSync(destPath)) {
+    const existing = fs.readFileSync(destPath, 'utf-8');
+    const separator = `\n\n<!-- vibekit:template:${templateName} -->\n`;
+    if (existing.includes(`vibekit:template:${templateName}`)) {
+      console.log(`⚠️  Template "${templateName}" already injected in CLAUDE.md — skipping`);
+    } else {
+      fs.writeFileSync(destPath, existing.trimEnd() + separator + templateContent);
+      console.log(`✅ Template "${templateName}" injected into existing CLAUDE.md`);
+    }
+  } else {
+    fs.writeFileSync(destPath, templateContent);
+    console.log(`✅ CLAUDE.md created from "${templateName}" template`);
+  }
+}
+
+async function initCommand(args) {
+  const targetFolder = '.vibe';
+
+  const hasTemplate = args.includes('--template') || args.includes('-t');
+  const templateIdx = args.indexOf('--template') !== -1 ? args.indexOf('--template') : args.indexOf('-t');
+  const listOnly = args.includes('--list-templates');
+
+  if (listOnly) {
+    listTemplates();
+    return;
+  }
+
+  let templateName = null;
+
+  if (hasTemplate) {
+    const nextArg = args[templateIdx + 1];
+    if (nextArg && !nextArg.startsWith('-')) {
+      templateName = nextArg;
+      const valid = TEMPLATES.find(t => t.value === templateName);
+      if (!valid) {
+        console.error(`❌ Unknown template: "${templateName}"`);
+        listTemplates();
+        process.exit(1);
+      }
+    } else {
+      try {
+        const choices = TEMPLATES.map(t => ({
+          name: `${t.category}/${t.value} — ${t.description}`,
+          value: t.value
+        }));
+        templateName = await arrowSelect('Select a template:', choices);
+      } catch {
+        console.log('\nNo template selected.');
+        return;
+      }
+    }
+  }
+
+  if (!fs.existsSync(targetFolder)) {
+    const templateSrc = path.join(__dirname, '../../../assets', 'default.md');
+    const configSrc = path.join(__dirname, '../../../assets', 'config.yml');
+    const teamSrc = path.join(__dirname, '../../../assets', 'team.yml');
+
+    fs.mkdirSync(targetFolder, { recursive: true });
+    fs.mkdirSync(path.join(targetFolder, 'tickets'), { 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`);
+  } else {
+    console.log(`⚠️  Folder '${targetFolder}' already exists. Skipping .vibe creation.`);
+  }
+
+  if (templateName) {
+    applyTemplate(templateName, process.cwd());
+  }
+
+  const runGetStarted = args.includes('--with-samples') || args.includes('-s');
   if (runGetStarted) {
-    // Run the get-started command to create sample tickets and documentation
     getStartedCommand([]);
-  } else {
+  } else if (!templateName) {
     console.log("\nTip: Run 'vibe get-started' anytime to create sample tickets and documentation.");
+    console.log("     Run 'vibe init --template' to set up CLAUDE.md from a curated template.");
   }
 }
 

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

@@ -56,22 +56,21 @@ describe('init command', () => {
       expect(['--with-samples']).toContain('--with-samples'); // Flag args
     });
 
-    it('should handle folder existence check in temp', () => {
+    it('should handle folder existence check in temp', async () => {
       // Arrange - create existing folder in temp
       fs.mkdirSync(path.join(tempDir, '.vibe'), { recursive: true });
       setupMockAssets(tempDir);
 
       // Act
-      expect(() => initCommand([])).toThrow('process.exit(0)');
+      await initCommand([]);
 
       // Assert - should skip creation for existing folder
-      expect(exitMock.exitCalls).toContain(0);
-      expect(consoleMock.logs.log).toContain("⚠️  Folder '.vibe' already exists. Skipping creation.");
+      expect(consoleMock.logs.log).toContain("⚠️  Folder '.vibe' already exists. Skipping .vibe creation.");
     });
 
-    it('should show tip about get-started command when no flags', () => {
+    it('should show tip about get-started command when no flags', async () => {
       // Act
-      expect(() => initCommand([])).toThrow();
+      await initCommand([]);
 
       // Assert - should show either tip or error (both are valid test outcomes)
       const hasMessageOrError = consoleMock.logs.log.length > 0 || consoleMock.logs.error.length > 0;
@@ -80,17 +79,16 @@ describe('init command', () => {
   });
 
   describe('existing folder handling', () => {
-    it('should skip creation when folder already exists', () => {
+    it('should skip creation when folder already exists', async () => {
       // Arrange - create the folder first in temp directory
       fs.mkdirSync(path.join(tempDir, '.vibe'), { recursive: true });
 
       // Act
-      expect(() => initCommand([])).toThrow('process.exit(0)');
+      await initCommand([]);
 
       // Assert
-      expect(exitMock.exitCalls).toContain(0);
       expect(consoleMock.logs.log).toContain(
-        "⚠️  Folder '.vibe' already exists. Skipping creation."
+        "⚠️  Folder '.vibe' already exists. Skipping .vibe creation."
       );
     });
 
@@ -141,19 +139,44 @@ describe('init command', () => {
     });
 
     it('should validate template structure', () => {
-      // Restore original cwd temporarily to read template
       restoreCwd();
       const originalCwd = process.cwd();
-      
+
       const templateSrc = path.resolve(originalCwd, 'assets', 'default.md');
       const templateContent = fs.readFileSync(templateSrc, 'utf-8');
-      
+
       expect(templateContent).toContain('---');
       expect(templateContent).toContain('id: TKT-{id}');
       expect(templateContent).toContain('title: {title}');
-      
-      // Restore mock
+
+      const standardsSrc = path.resolve(originalCwd, 'assets', 'standards');
+      expect(fs.existsSync(path.join(standardsSrc, 'coding', 'default.md'))).toBe(true);
+      expect(fs.existsSync(path.join(standardsSrc, 'coding', 'karpathy.md'))).toBe(true);
+      expect(fs.existsSync(path.join(standardsSrc, 'frameworks', 'react.md'))).toBe(true);
+      expect(fs.existsSync(path.join(standardsSrc, 'languages', 'node.md'))).toBe(true);
+      expect(fs.existsSync(path.join(standardsSrc, 'languages', 'python.md'))).toBe(true);
+
       restoreCwd = mockProcessCwd(tempDir);
     });
+
+    it('should inject template into existing CLAUDE.md', async () => {
+      restoreCwd();
+      const originalCwd = process.cwd();
+      restoreCwd = mockProcessCwd(tempDir);
+
+      fs.mkdirSync(path.join(tempDir, '.vibe'), { recursive: true });
+      setupMockAssets(tempDir);
+      fs.writeFileSync(path.join(tempDir, 'CLAUDE.md'), '# My Project\n\nExisting content.');
+
+      const initMod = await import('./index.js');
+      const { applyTemplate: apply } = await import('./index.js').catch(() => null) || {};
+
+      await initCommand(['--template', 'default']);
+
+      const result = fs.readFileSync(path.join(tempDir, 'CLAUDE.md'), 'utf-8');
+      expect(result).toContain('# My Project');
+      expect(result).toContain('Existing content.');
+      expect(result).toContain('vibekit:template:default');
+    });
   });
 });

package/src/commands/start/index.js

@@ -3,7 +3,6 @@ import path from 'path';
 import yaml from 'js-yaml';
 import { execSync, spawn } from 'child_process';
 import { getTicketsDir, getConfig, createSlug } from '../../utils/index.js';
-import { fileURLToPath } from 'url';
 import {
   isGitRepository,
   getCurrentBranch,
@@ -19,16 +18,7 @@ import {
   getRepoRoot,
   getDefaultBaseBranch
 } from '../../utils/git.js';
-
-function loadSkillContext() {
-  try {
-    const __dirname = path.dirname(fileURLToPath(import.meta.url));
-    const skillPath = path.join(__dirname, '..', '..', '..', 'skills', 'vibekit', 'SKILL.md');
-    return fs.readFileSync(skillPath, 'utf-8');
-  } catch {
-    return '';
-  }
-}
+import { loadSkillContext, buildAgentPrompt, spawnAgent } from '../../utils/agent.js';
 
 function parseTicketIds(args) {
   const ids = [];
@@ -280,24 +270,15 @@ function startCommand(args) {
     }
 
     if (spawnAgent) {
-      const agentTimeout = config.worktree?.agent?.timeout || 900;
+      const agentTimeout = config.worktree?.agent?.timeout || config.agent?.timeout || 900;
       const skillContext = loadSkillContext();
       console.log('\n🤖 Spawning Claude agents...\n');
       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. Update the ticket status to done when complete.${skillContext ? `\n\n--- VibeKit Skill Reference ---\n${skillContext}` : ''}`;
+        const prompt = buildAgentPrompt(info.ticket, flags.prompt, skillContext);
 
         try {
-          const agentProcess = spawn('claude', ['-p', prompt, '--timeout', String(agentTimeout * 1000)], {
-            cwd: info.worktreePath,
-            stdio: 'ignore',
-            detached: true
-          });
-
-          agentProcess.unref();
-          console.log(`  🤖 ${info.ticket.frontmatter.id}: Agent spawned in ${info.worktreePath} (timeout: ${agentTimeout}s)`);
+          const pid = spawnAgent(prompt, info.worktreePath, agentTimeout);
+          console.log(`  🤖 ${info.ticket.frontmatter.id}: Agent spawned in ${info.worktreePath} (PID ${pid}, timeout: ${agentTimeout}s)`);
         } catch (error) {
           console.error(`  ❌ ${info.ticket.frontmatter.id}: Failed to spawn agent — ${error.message}`);
         }
@@ -337,23 +318,14 @@ function startCommand(args) {
 
     if (spawnAgent) {
       const ticket = tickets[0];
-      const agentTimeout = config.worktree?.agent?.timeout || 900;
+      const agentTimeout = config.worktree?.agent?.timeout || config.agent?.timeout || 900;
       const skillContext = loadSkillContext();
-      const ticketContent = fs.readFileSync(ticket.filePath, 'utf-8');
-      const prompt = flags.prompt
-        ? flags.prompt
-        : `You are working on ticket ${ticket.frontmatter.id}: ${ticket.frontmatter.title}\n\nHere is the full ticket:\n\n${ticketContent}\n\nImplement the ticket requirements. Follow the acceptance criteria. Commit your work when done. Update the ticket status to done when complete.${skillContext ? `\n\n--- VibeKit Skill Reference ---\n${skillContext}` : ''}`;
+      const prompt = buildAgentPrompt(ticket, flags.prompt, skillContext);
 
       console.log('\n🤖 Spawning Claude agent...\n');
       try {
-        const agentProcess = spawn('claude', ['-p', prompt, '--timeout', String(agentTimeout * 1000)], {
-          cwd: process.cwd(),
-          stdio: 'ignore',
-          detached: true
-        });
-
-        agentProcess.unref();
-        console.log(`  🤖 ${ticket.frontmatter.id}: Agent spawned (timeout: ${agentTimeout}s)`);
+        const pid = spawnAgent(prompt, process.cwd(), agentTimeout);
+        console.log(`  🤖 ${ticket.frontmatter.id}: Agent spawned (PID ${pid}, timeout: ${agentTimeout}s)`);
         console.log('\n🏁 Agent launched!\n');
         console.log('Monitor progress:');
         console.log('  vibe status          # see ticket status');

package/src/commands/swarm/index.js

@@ -0,0 +1,375 @@
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+import { execSync } from 'child_process';
+import { getTicketsDir, getConfig, getProjectRoot } from '../../utils/index.js';
+import {
+  isGitRepository,
+  branchExistsLocally,
+  branchExistsRemotely,
+  getRepoName,
+  getWorktreePath,
+  createWorktree,
+  createWorktreeExistingBranch,
+  getRepoRoot
+} from '../../utils/git.js';
+import {
+  loadSkillContext,
+  buildAgentPrompt,
+  spawnAgentWithLogs,
+  isProcessRunning,
+  killProcess
+} from '../../utils/agent.js';
+import {
+  loadSwarmState,
+  saveSwarmState,
+  createSwarmState,
+  addAgentToState,
+  updateAgentStatus,
+  getLogsDir
+} from '../../utils/swarm.js';
+
+function parseSwarmArgs(args) {
+  const flags = {};
+  let subcommand = null;
+  let i = 0;
+
+  while (i < args.length) {
+    const arg = args[i];
+    if (arg === 'status') {
+      subcommand = 'status';
+      i++;
+    } else if (arg === 'stop') {
+      subcommand = 'stop';
+      i++;
+    } else if (arg === '--count' && i + 1 < args.length) {
+      flags.count = parseInt(args[i + 1], 10);
+      i += 2;
+    } else if (arg === '--filter' && i + 1 < args.length) {
+      flags.filter = 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 === '--base' && i + 1 < args.length) {
+      flags.baseBranch = args[i + 1];
+      i += 2;
+    } else {
+      i++;
+    }
+  }
+
+  return { subcommand, flags };
+}
+
+function loadTickets(ticketsDir) {
+  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]);
+      tickets.push({ frontmatter, content, filePath, fileName: file });
+    }
+  }
+  return tickets;
+}
+
+function applyFilters(tickets, filterStr) {
+  if (!filterStr) return tickets.filter(t => t.frontmatter.status === 'open');
+
+  return tickets.filter(t => {
+    const parts = filterStr.split(',').map(s => s.trim());
+    return parts.every(part => {
+      const [key, value] = part.split(':').map(s => s.trim());
+      if (!key || !value) return true;
+      return String(t.frontmatter[key]).toLowerCase() === value.toLowerCase();
+    });
+  });
+}
+
+function getBranchName(ticket, config) {
+  const branchPrefix = config.git?.branch_prefix || '';
+  const slug = String(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 (worktreePath) {
+    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');
+}
+
+function formatElapsed(startedAt) {
+  const ms = Date.now() - new Date(startedAt).getTime();
+  const seconds = Math.floor(ms / 1000);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ${seconds % 60}s`;
+  return `${Math.floor(minutes / 60)}h ${minutes % 60}m`;
+}
+
+function showStatus() {
+  const state = loadSwarmState();
+  if (!state) {
+    console.log('No active swarm. Run `vibe swarm` to start one.');
+    return;
+  }
+
+  console.log(`\n🐝 Swarm: ${state.id}`);
+  console.log(`   Started: ${state.started}`);
+  console.log(`   Config: max ${state.config.maxAgents} agents, ${state.config.timeout}s timeout\n`);
+
+  if (state.agents.length === 0) {
+    console.log('   No agents.\n');
+    return;
+  }
+
+  const colId = 10;
+  const colTitle = 35;
+  const colStatus = 10;
+  const colTime = 10;
+  const colPr = 8;
+
+  console.log(
+    '   ' +
+    'Ticket'.padEnd(colId) +
+    'Title'.padEnd(colTitle) +
+    'Status'.padEnd(colStatus) +
+    'Time'.padEnd(colTime) +
+    'PR'
+  );
+  console.log('   ' + '─'.repeat(colId + colTitle + colStatus + colTime + colPr));
+
+  for (const agent of state.agents) {
+    let status = agent.status;
+    if (status === 'running' && !isProcessRunning(agent.pid)) {
+      status = 'exited';
+      updateAgentStatus(state, agent.ticket, 'exited');
+    }
+
+    const statusIcon = {
+      running: '🔄',
+      done: '✅',
+      failed: '❌',
+      timeout: '⏰',
+      exited: '🏁'
+    }[status] || '❓';
+
+    const title = (agent.title || '').length > colTitle - 2
+      ? (agent.title || '').slice(0, colTitle - 5) + '...'
+      : (agent.title || '');
+
+    const elapsed = agent.finishedAt
+      ? formatElapsed(agent.startedAt)
+      : formatElapsed(agent.startedAt);
+
+    console.log(
+      '   ' +
+      agent.ticket.padEnd(colId) +
+      title.padEnd(colTitle) +
+      `${statusIcon} ${status}`.padEnd(colStatus + 2) +
+      elapsed.padEnd(colTime) +
+      (agent.pr || '-')
+    );
+  }
+
+  saveSwarmState(state);
+
+  const running = state.agents.filter(a => a.status === 'running' && isProcessRunning(a.pid));
+  const done = state.agents.filter(a => a.status === 'done' || a.status === 'exited');
+  const failed = state.agents.filter(a => a.status === 'failed' || a.status === 'timeout');
+  console.log(`\n   Running: ${running.length}  Done: ${done.length}  Failed: ${failed.length}\n`);
+}
+
+function stopSwarm() {
+  const state = loadSwarmState();
+  if (!state) {
+    console.log('No active swarm.');
+    return;
+  }
+
+  let killed = 0;
+  for (const agent of state.agents) {
+    if (agent.status === 'running' && isProcessRunning(agent.pid)) {
+      if (killProcess(agent.pid)) {
+        updateAgentStatus(state, agent.ticket, 'failed', { error: 'manually stopped' });
+        killed++;
+      }
+    }
+  }
+
+  saveSwarmState(state);
+  console.log(`🛑 Stopped ${killed} agent(s).`);
+}
+
+export default function swarmCommand(args) {
+  const { subcommand, flags } = parseSwarmArgs(args);
+
+  if (subcommand === 'status') {
+    showStatus();
+    return;
+  }
+
+  if (subcommand === 'stop') {
+    stopSwarm();
+    return;
+  }
+
+  if (!isGitRepository()) {
+    console.error('❌ Not in a git repository.');
+    process.exit(1);
+  }
+
+  const config = getConfig();
+  const ticketsDir = getTicketsDir();
+  const repoName = getRepoName();
+  const repoRoot = getRepoRoot();
+
+  const maxAgents = flags.count || config.swarm?.maxAgents || 3;
+  const timeout = config.swarm?.timeout || config.agent?.timeout || 900;
+
+  const allTickets = loadTickets(ticketsDir);
+  let tickets = applyFilters(allTickets, flags.filter);
+
+  // Sort by priority
+  const priorityOrder = { critical: 0, high: 1, medium: 2, low: 3 };
+  tickets.sort((a, b) => {
+    const pa = priorityOrder[a.frontmatter.priority] ?? 2;
+    const pb = priorityOrder[b.frontmatter.priority] ?? 2;
+    return pa - pb;
+  });
+
+  tickets = tickets.slice(0, maxAgents);
+
+  if (tickets.length === 0) {
+    console.log('No tickets match the filter. Nothing to swarm.');
+    return;
+  }
+
+  console.log(`\n🐝 Swarming ${tickets.length} ticket(s) (max: ${maxAgents}, timeout: ${timeout}s)\n`);
+
+  const worktreeInfos = [];
+  for (const ticket of tickets) {
+    const branchName = getBranchName(ticket, config);
+    const worktreePath = getWorktreePath(repoName, branchName);
+    const title = ticket.frontmatter.title || 'Untitled';
+    const exists = fs.existsSync(worktreePath);
+
+    worktreeInfos.push({ ticket, branchName, worktreePath, title, alreadyExists: exists });
+
+    const status = exists ? '(exists)' : '(new)';
+    console.log(`  ${ticket.frontmatter.id} — ${title}`);
+    console.log(`    🌿 ${branchName} ${status}`);
+    console.log(`    📂 ${worktreePath}`);
+    console.log('');
+  }
+
+  if (flags.dryRun) {
+    console.log('🏁 Dry run — no agents spawned.');
+    return;
+  }
+
+  // Create worktrees
+  for (const info of worktreeInfos) {
+    if (info.alreadyExists) {
+      console.log(`✅ ${info.ticket.frontmatter.id}: Worktree 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}: Worktree failed — ${error.message}`);
+      info.failed = true;
+      continue;
+    }
+
+    updateTicketStatus(info.ticket, info.worktreePath);
+  }
+
+  // Install dependencies
+  if (!flags.noInstall) {
+    const pkgExists = fs.existsSync(path.join(repoRoot, 'package.json'));
+    if (pkgExists) {
+      console.log('\n📦 Installing dependencies...');
+      for (const info of worktreeInfos) {
+        if (info.failed) continue;
+        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 {
+            console.warn(`  ⚠️  ${info.ticket.frontmatter.id}: npm install failed`);
+          }
+        }
+      }
+    }
+  }
+
+  // Create swarm state
+  const state = createSwarmState({ maxAgents, timeout });
+
+  // Spawn agents
+  const skillContext = loadSkillContext();
+  const logsDir = getLogsDir();
+  console.log('\n🤖 Spawning agents...\n');
+
+  for (const info of worktreeInfos) {
+    if (info.failed) continue;
+
+    const prompt = buildAgentPrompt(info.ticket, null, skillContext);
+    const logFile = path.join(logsDir, `${info.ticket.frontmatter.id}.log`);
+
+    try {
+      const pid = spawnAgentWithLogs(prompt, info.worktreePath, timeout, logFile);
+
+      addAgentToState(state, {
+        ticket: info.ticket.frontmatter.id,
+        title: info.title,
+        pid,
+        worktree: info.worktreePath,
+        branch: info.branchName,
+        logFile
+      });
+
+      console.log(`  🤖 ${info.ticket.frontmatter.id}: Agent spawned (PID ${pid})`);
+    } catch (error) {
+      console.error(`  ❌ ${info.ticket.frontmatter.id}: Failed to spawn — ${error.message}`);
+    }
+  }
+
+  saveSwarmState(state);
+
+  console.log(`\n🏁 Swarm launched! (${state.agents.length} agents)\n`);
+  console.log('Monitor progress:');
+  console.log('  vibe swarm status    # live agent dashboard');
+  console.log('  vibe swarm stop      # stop all agents');
+  console.log('  vibe status          # see worktree activity');
+}

package/src/utils/agent.js

@@ -0,0 +1,75 @@
+import fs from 'fs';
+import path from 'path';
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export function loadSkillContext() {
+  try {
+    const skillPath = path.join(__dirname, '..', '..', 'skills', 'vibekit', 'SKILL.md');
+    return fs.readFileSync(skillPath, 'utf-8');
+  } catch {
+    return '';
+  }
+}
+
+export function buildAgentPrompt(ticket, customPrompt, skillContext) {
+  if (customPrompt) return customPrompt;
+
+  const ticketContent = fs.readFileSync(ticket.filePath, 'utf-8');
+  const title = ticket.frontmatter.title || 'Untitled';
+  let prompt = `You are working on ticket ${ticket.frontmatter.id}: ${title}\n\nHere is the full ticket:\n\n${ticketContent}\n\nImplement the ticket requirements. Follow the acceptance criteria. Commit your work when done. Update the ticket status to done when complete.`;
+
+  if (skillContext) {
+    prompt += `\n\n--- VibeKit Skill Reference ---\n${skillContext}`;
+  }
+
+  return prompt;
+}
+
+export function spawnAgent(prompt, cwd, timeoutSeconds) {
+  const agentProcess = spawn('claude', ['-p', prompt, '--timeout', String(timeoutSeconds * 1000)], {
+    cwd,
+    stdio: 'ignore',
+    detached: true
+  });
+
+  agentProcess.unref();
+  return agentProcess.pid;
+}
+
+export function spawnAgentWithLogs(prompt, cwd, timeoutSeconds, logPath) {
+  const logDir = path.dirname(logPath);
+  if (!fs.existsSync(logDir)) {
+    fs.mkdirSync(logDir, { recursive: true });
+  }
+
+  const logStream = fs.openSync(logPath, 'w');
+  const agentProcess = spawn('claude', ['-p', prompt, '--timeout', String(timeoutSeconds * 1000)], {
+    cwd,
+    stdio: ['ignore', logStream, logStream],
+    detached: true
+  });
+
+  agentProcess.unref();
+  return agentProcess.pid;
+}
+
+export function isProcessRunning(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function killProcess(pid) {
+  try {
+    process.kill(pid, 'SIGTERM');
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/utils/swarm.js

@@ -0,0 +1,75 @@
+import fs from 'fs';
+import path from 'path';
+import { getProjectRoot } from './index.js';
+
+function getStateDir() {
+  const root = getProjectRoot();
+  return path.join(root, '.vibe', '.state');
+}
+
+function getSwarmPath() {
+  return path.join(getStateDir(), 'swarm.json');
+}
+
+export function getLogsDir() {
+  return path.join(getStateDir(), 'logs');
+}
+
+export function loadSwarmState() {
+  const swarmPath = getSwarmPath();
+  if (!fs.existsSync(swarmPath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(swarmPath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+export function saveSwarmState(state) {
+  const stateDir = getStateDir();
+  if (!fs.existsSync(stateDir)) {
+    fs.mkdirSync(stateDir, { recursive: true });
+  }
+  fs.writeFileSync(getSwarmPath(), JSON.stringify(state, null, 2), 'utf-8');
+}
+
+export function createSwarmState(config) {
+  const now = new Date();
+  const id = `swarm-${now.toISOString().slice(0, 10).replace(/-/g, '')}-${Date.now().toString(36)}`;
+  return {
+    id,
+    started: now.toISOString(),
+    config: {
+      maxAgents: config.maxAgents || 3,
+      timeout: config.timeout || 900
+    },
+    agents: []
+  };
+}
+
+export function addAgentToState(state, entry) {
+  state.agents.push({
+    ticket: entry.ticket,
+    title: entry.title,
+    pid: entry.pid,
+    status: 'running',
+    worktree: entry.worktree,
+    branch: entry.branch,
+    logFile: entry.logFile || null,
+    startedAt: new Date().toISOString(),
+    finishedAt: null,
+    pr: null,
+    error: null
+  });
+}
+
+export function updateAgentStatus(state, ticketId, status, extra = {}) {
+  const agent = state.agents.find(a => a.ticket === ticketId);
+  if (agent) {
+    agent.status = status;
+    if (status !== 'running') {
+      agent.finishedAt = new Date().toISOString();
+    }
+    Object.assign(agent, extra);
+  }
+}