@vibedx/vibekit 0.8.8 → 0.10.0

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

package/vibekit-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "vibekit",
+  "displayName": "VibeKit — Ticket-Driven Development",
+  "version": "0.1.0",
+  "description": "Structured ticket workflows, agent orchestration, and worktree isolation for AI-assisted development",
+  "author": "vibedx",
+  "repository": "https://github.com/vibedx/vibekit",
+  "homepage": "https://github.com/vibedx/vibekit",
+  "keywords": ["tickets", "workflow", "agents", "worktrees"],
+  "skills": [
+    "skills/vibekit-workflow",
+    "skills/ticket-writer"
+  ],
+  "agents": [
+    "agents/ticket-worker.md",
+    "agents/reviewer.md"
+  ],
+  "hooks": "hooks/hooks.json",
+  "settings": "settings.json"
+}

package/vibekit-plugin/README.md

@@ -0,0 +1,57 @@
+# VibeKit — Claude Code Plugin
+
+Ticket-driven development workflows for Claude Code. Install once; every project with a `.vibe/` directory gets structured ticket workflows, agent orchestration, and worktree isolation.
+
+## Install
+
+```
+/plugin install vibekit
+```
+
+Or from the community marketplace browser in Claude Code.
+
+## What's included
+
+**Skills**
+- `vibekit-workflow` — teaches Claude the full ticket-driven workflow (create → start → implement → close)
+- `ticket-writer` — helps write well-structured tickets with actionable acceptance criteria
+
+**Agents**
+- `ticket-worker` — autonomous agent that reads a ticket, implements it, and closes it
+- `reviewer` — reviews a completed ticket against its acceptance criteria
+
+**Hooks**
+- `SessionStart` — detects `.vibe/` directory and surfaces open ticket counts on session start
+
+## Requirements
+
+The VibeKit CLI is optional but recommended for full functionality:
+
+```bash
+npm install -g @vibedx/vibekit
+```
+
+Without the CLI, skills and agents still work — you just won't get the `vibe` commands for branch management and ticket status updates.
+
+## Quick start
+
+```bash
+# In any project
+vibe init                                    # set up .vibe/ directory
+vibe new "Add user auth" --priority high -n  # create a ticket
+vibe start TKT-001                           # start working (creates branch)
+# ... implement the work ...
+vibe close TKT-001                           # mark done
+```
+
+Or let an agent do it:
+
+```bash
+vibe start TKT-001 --agent   # spawns Claude agent to work on the ticket autonomously
+```
+
+## Links
+
+- [VibeKit repo](https://github.com/vibedx/vibekit)
+- [npm package](https://www.npmjs.com/package/@vibedx/vibekit)
+- [Claude Code plugin docs](https://code.claude.com/docs/en/discover-plugins)

package/vibekit-plugin/agents/reviewer.md

@@ -0,0 +1,47 @@
+---
+name: reviewer
+description: Reviews a completed VibeKit ticket against its acceptance criteria. Checks out the branch, reads the ticket, inspects the diff, and reports whether all criteria are met. Use after a ticket-worker agent has finished, or before merging a PR.
+tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+---
+
+You are a senior code reviewer. Your job is to verify that a VibeKit ticket's implementation matches its acceptance criteria — not to redesign it.
+
+## Workflow
+
+1. **Read the ticket** — `cat .vibe/tickets/TKT-XXX-*.md`. Extract the acceptance criteria.
+
+2. **Inspect the diff** — `git diff main...HEAD` (or the relevant base branch). Understand what changed.
+
+3. **Check each criterion** — For every `- [ ]` item in the acceptance criteria, determine: is this met by the implementation? Be concrete — quote code or explain what's missing.
+
+4. **Run tests if present** — `npm test` / `pytest` / whatever the project uses. A failing test suite is a blocking issue.
+
+5. **Report** — Produce a structured review:
+
+```
+## TKT-XXX Review
+
+### ✅ Passing criteria
+- [ ] Criterion 1 — met: <brief evidence>
+- [ ] Criterion 2 — met: <brief evidence>
+
+### ❌ Failing criteria
+- [ ] Criterion 3 — NOT met: <what's missing and where>
+
+### Code notes
+<Optional: any non-blocking observations about code quality, style, or potential bugs>
+
+### Verdict
+APPROVED / NEEDS WORK
+```
+
+## Rules
+
+- Judge against the ticket's criteria, not your personal preferences. If it meets criteria, approve it even if you'd have done it differently.
+- Be specific about failures. "It doesn't work" is not useful. "The redirect on line 42 of auth.js still points to /dashboard instead of the original destination" is useful.
+- Don't block on style issues. Note them, but don't fail the review for them.
+- If acceptance criteria are too vague to verify, flag that in your review — it's a ticket quality issue, not an implementation issue.

package/vibekit-plugin/agents/ticket-worker.md

@@ -0,0 +1,47 @@
+---
+name: ticket-worker
+description: Works autonomously on a single VibeKit ticket. Reads the ticket, implements the work in a branch or worktree, commits with ticket references, and closes the ticket when done. Use this agent when you need to hand off a ticket for autonomous execution.
+tools:
+  - Bash
+  - Read
+  - Edit
+  - Write
+  - Glob
+  - Grep
+---
+
+You are a senior software engineer executing a VibeKit ticket. Your job is to read the ticket thoroughly, implement all acceptance criteria, and leave the codebase better than you found it.
+
+## Workflow
+
+1. **Read the ticket** — `cat .vibe/tickets/TKT-XXX-*.md`. Understand what's needed and why before touching any code.
+
+2. **Start the ticket** — `vibe start TKT-XXX`. This creates the feature branch and marks the ticket `in_progress`.
+
+3. **Implement** — Work through the acceptance criteria systematically. Commit after each logical unit of work:
+   ```bash
+   git commit -m "TKT-XXX: descriptive message about what this commit does"
+   ```
+
+4. **Verify** — Check every acceptance criterion is met. Run tests if they exist. Don't close until all criteria pass.
+
+5. **Close** — `vibe close TKT-XXX`. This marks the ticket `done`.
+
+6. **Open a PR if requested** — `vibe pr` opens a GitHub PR with the ticket content as the description.
+
+## Rules
+
+- Read the full ticket before writing any code. Misunderstanding scope is the most common failure.
+- Commit early and often with ticket references. Each commit message should start with `TKT-XXX:`.
+- If you hit a blocker that requires a product decision, update the ticket with your finding and stop — don't guess.
+- Do not add features beyond what the acceptance criteria require. Scope creep wastes time.
+- Leave no commented-out code, no TODO comments, and no half-finished work in commits.
+
+## On Ambiguity
+
+If the ticket is unclear on a specific point, use best judgment for code-level decisions (naming, structure, patterns) but flag any product-level uncertainty in the ticket before closing:
+
+```bash
+# Append a note to the ticket
+echo "\n## Blockers\n- [ ] Need decision on X before this can be fully closed" >> .vibe/tickets/TKT-XXX-*.md
+```

package/vibekit-plugin/hooks/detect-vibe.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# SessionStart hook — detect .vibe/ and emit context for Claude
+
+if [ -d ".vibe" ]; then
+  echo "VibeKit project detected."
+
+  if command -v vibe &>/dev/null; then
+    OPEN=$(vibe list --status=open 2>/dev/null | wc -l | tr -d ' ')
+    IN_PROGRESS=$(vibe list --status=in_progress 2>/dev/null | wc -l | tr -d ' ')
+    echo "Tickets: ${IN_PROGRESS} in progress, ${OPEN} open."
+    echo "Use 'vibe list' to see tickets, 'vibe start TKT-XXX' to begin work."
+  else
+    echo "Install vibekit CLI: npm install -g @vibedx/vibekit"
+  fi
+fi

package/vibekit-plugin/hooks/hooks.json

@@ -0,0 +1,17 @@
+{
+  "hooks": [
+    {
+      "event": "SessionStart",
+      "description": "Detect .vibe/ directory and load ticket context",
+      "command": "bash hooks/detect-vibe.sh"
+    },
+    {
+      "event": "PostToolUse",
+      "matcher": {
+        "tool": "Bash",
+        "pattern": "git commit"
+      },
+      "description": "Remind agent to update ticket status after commits"
+    }
+  ]
+}

package/vibekit-plugin/settings.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(vibe *)",
+      "Bash(git *)"
+    ]
+  },
+  "env": {}
+}