@vibedx/vibekit 0.8.7 → 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/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', 'plan', 'pr', 'swarm'
 ];
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibedx/vibekit",
-  "version": "0.8.7",
+  "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

@@ -3,50 +3,130 @@ 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, '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/, plans/, 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');
+    });
   });
 });