@vibedx/vibekit 0.9.0 → 0.11.0

package/src/commands/docs/list.js

@@ -0,0 +1,137 @@
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+import { getDocsDir } from '../../utils/doc.js';
+
+/**
+ * Parse `vibe docs list` filter flags.
+ * @param {string[]} args
+ * @returns {{type: string|null, status: string|null, tag: string|null}}
+ */
+function parseFilters(args) {
+  let type = null;
+  let status = null;
+  let tag = null;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--type' && i + 1 < args.length) {
+      type = args[++i];
+    } else if (arg === '--status' && i + 1 < args.length) {
+      status = args[++i];
+    } else if (arg === '--tag' && i + 1 < args.length) {
+      tag = args[++i];
+    } else if (arg.startsWith('--type=')) {
+      type = arg.split('=')[1];
+    } else if (arg.startsWith('--status=')) {
+      status = arg.split('=')[1];
+    } else if (arg.startsWith('--tag=')) {
+      tag = arg.split('=')[1];
+    }
+  }
+
+  return { type, status, tag };
+}
+
+function normalizeTags(raw) {
+  if (Array.isArray(raw)) return raw.map(String);
+  if (typeof raw === 'string' && raw.trim()) {
+    return raw.replace(/[\[\]]/g, '').split(',').map(t => t.trim()).filter(Boolean);
+  }
+  return [];
+}
+
+/**
+ * `vibe docs list` — render a filtered table of docs.
+ * @param {string[]} args
+ */
+function listDocs(args) {
+  const { type, status, tag } = parseFilters(args);
+  const docsDir = getDocsDir();
+
+  if (!fs.existsSync(docsDir)) {
+    console.log('No docs found. Create one with: vibe docs add "title"');
+    return;
+  }
+
+  const files = fs.readdirSync(docsDir).filter(f => f.endsWith('.md'));
+
+  if (files.length === 0) {
+    console.log('No docs found. Create one with: vibe docs add "title"');
+    return;
+  }
+
+  let docs = [];
+  for (const file of files) {
+    try {
+      const content = fs.readFileSync(path.join(docsDir, file), 'utf-8');
+      const match = content.match(/^---\n([\s\S]*?)\n---/);
+      if (match) {
+        const fm = yaml.load(match[1]) || {};
+        docs.push({
+          id: fm.id || 'Unknown',
+          title: fm.title || 'Untitled',
+          type: fm.type || 'guide',
+          status: fm.status || 'draft',
+          tags: normalizeTags(fm.tags),
+          file
+        });
+      }
+    } catch {
+      console.warn(`⚠️  Could not parse doc: ${file}`);
+    }
+  }
+
+  if (type) docs = docs.filter(d => d.type === type);
+  if (status) docs = docs.filter(d => d.status === status);
+  if (tag) docs = docs.filter(d => d.tags.includes(tag));
+
+  docs.sort((a, b) => {
+    const na = parseInt(a.id.replace(/\D/g, ''), 10) || 0;
+    const nb = parseInt(b.id.replace(/\D/g, ''), 10) || 0;
+    return na - nb;
+  });
+
+  const filters = [
+    type ? `type: ${type}` : '',
+    status ? `status: ${status}` : '',
+    tag ? `tag: ${tag}` : ''
+  ].filter(Boolean).join(', ');
+
+  if (docs.length === 0) {
+    console.log(filters ? `No docs found (${filters}).` : 'No docs found.');
+    return;
+  }
+
+  console.log('\n📚 VibeKit Docs 📚\n');
+
+  const idWidth = 10;
+  const typeWidth = 12;
+  const statusWidth = 11;
+  const titleWidth = 40;
+
+  console.log(
+    `${'ID'.padEnd(idWidth)}| ${'TYPE'.padEnd(typeWidth)}| ${'STATUS'.padEnd(statusWidth)}| TITLE`
+  );
+  console.log(`${'-'.repeat(idWidth)}+${'-'.repeat(typeWidth + 1)}+${'-'.repeat(statusWidth + 1)}+${'-'.repeat(titleWidth)}`);
+
+  for (const doc of docs) {
+    let statusColor = '\x1b[0m';
+    if (doc.status === 'published') statusColor = '\x1b[32m';
+    else if (doc.status === 'review') statusColor = '\x1b[36m';
+    else if (doc.status === 'draft') statusColor = '\x1b[33m';
+
+    const title = doc.title.length > titleWidth - 3
+      ? doc.title.substring(0, titleWidth - 3) + '...'
+      : doc.title;
+
+    console.log(
+      `${doc.id.padEnd(idWidth)}| ${doc.type.padEnd(typeWidth)}| ${statusColor}${doc.status.padEnd(statusWidth)}\x1b[0m| ${title}`
+    );
+  }
+
+  console.log(`${'-'.repeat(idWidth)}+${'-'.repeat(typeWidth + 1)}+${'-'.repeat(statusWidth + 1)}+${'-'.repeat(titleWidth)}`);
+  console.log(`Found ${docs.length} doc(s)${filters ? ` (${filters})` : ''}.\n`);
+}
+
+export default listDocs;

package/src/commands/docs/refine.js

@@ -0,0 +1,138 @@
+import fs from 'fs';
+import { spawn } from 'child_process';
+import { getConfig } from '../../utils/index.js';
+import { resolveDocId, parseDoc } from '../../utils/doc.js';
+import { logger, spinner } from '../../utils/cli.js';
+
+/**
+ * Send a prompt to Claude via the native CLI and return the text result.
+ * @param {string} prompt
+ * @returns {Promise<string>}
+ */
+function executeClaude(prompt) {
+  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', (c) => { stdout += c; });
+    child.stderr.on('data', (c) => { stderr += c; });
+    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 envelope = JSON.parse(stdout.trim());
+        if (envelope.is_error) {
+          reject(new Error(envelope.result || 'Claude reported an error'));
+          return;
+        }
+        const text = (envelope.result ?? '').trim();
+        if (!text) {
+          reject(new Error('Claude returned an empty result'));
+          return;
+        }
+        resolve(text);
+      } catch {
+        reject(new Error('Claude returned non-JSON output'));
+      }
+    });
+
+    child.stdin.write(prompt, 'utf8');
+    child.stdin.end();
+  });
+}
+
+/**
+ * Strip a leading markdown code fence if Claude wrapped the body.
+ * @param {string} text
+ * @returns {string}
+ */
+function stripCodeFence(text) {
+  const match = text.match(/^```(?:markdown|md)?\s*\n([\s\S]*?)\n```\s*$/);
+  return match ? match[1] : text;
+}
+
+function buildPrompt(metadata, body) {
+  const title = metadata.title || 'Untitled';
+  const type = metadata.type || 'guide';
+  return `You are a senior technical writer improving a project document.
+
+Document title: ${title}
+Document type: ${type}
+
+Current body (markdown, everything after the YAML frontmatter):
+---
+${body}
+---
+
+INSTRUCTIONS:
+1. Improve and expand the document body. Fill in empty sections and replace HTML comment placeholders (<!-- ... -->) with real, useful content inferred from the title, type, and surrounding context.
+2. Keep the existing section headings (## ...). You may add sub-sections where helpful.
+3. Use developer-friendly formatting: \`code\`, code blocks, file paths, and lists.
+4. Respond with ONLY the improved markdown body — no frontmatter, no explanation, no surrounding code fences.`;
+}
+
+/**
+ * `vibe docs refine <id>` — AI pass that improves and writes back the doc body.
+ * @param {string[]} args
+ */
+async function refineDoc(args) {
+  try {
+    const input = args[0];
+    if (!input) {
+      throw new Error('Please provide a doc ID. Usage: vibe docs refine <id>');
+    }
+
+    const config = getConfig();
+    if (!config.ai?.enabled) {
+      throw new Error('AI is not enabled. Run "vibe link" first.');
+    }
+
+    const docInfo = resolveDocId(input);
+    if (!docInfo) {
+      throw new Error(`Doc ${input} not found. Use "vibe docs list" to see available docs.`);
+    }
+
+    const doc = parseDoc(docInfo.path);
+    logger.info(`Refining ${docInfo.id} — ${doc.metadata.title || 'Untitled'}`);
+
+    const body = doc.contentLines.join('\n').trim();
+    const prompt = buildPrompt(doc.metadata, body);
+
+    const loading = spinner('🤖 Refining document...');
+    let result;
+    try {
+      result = await executeClaude(prompt);
+      loading.succeed('Refinement complete!');
+    } catch (error) {
+      loading.fail('Refinement failed');
+      throw error;
+    }
+
+    const newBody = stripCodeFence(result).trim();
+
+    const timestamp = new Date().toISOString().split('T')[0];
+    const yamlLines = doc.yamlLines.map(line =>
+      line.startsWith('updated_at:') ? `updated_at: ${timestamp}` : line
+    );
+
+    const reconstructed = ['---', ...yamlLines, '---', '', newBody, ''].join('\n');
+    fs.writeFileSync(docInfo.path, reconstructed, 'utf-8');
+
+    logger.success(`${docInfo.id} refined and updated.`);
+  } catch (error) {
+    logger.error(error.message);
+    process.exit(1);
+  }
+}
+
+export default refineDoc;

package/src/commands/docs/show.js

@@ -0,0 +1,28 @@
+import fs from 'fs';
+import { resolveDocId } from '../../utils/doc.js';
+import { logger } from '../../utils/cli.js';
+
+/**
+ * `vibe docs show <id>` — print a doc to stdout.
+ * @param {string[]} args
+ */
+function showDoc(args) {
+  try {
+    const input = args[0];
+    if (!input) {
+      throw new Error('Please provide a doc ID. Usage: vibe docs show <id>');
+    }
+
+    const docInfo = resolveDocId(input);
+    if (!docInfo) {
+      throw new Error(`Doc ${input} not found. Use "vibe docs list" to see available docs.`);
+    }
+
+    console.log(fs.readFileSync(docInfo.path, 'utf-8'));
+  } catch (error) {
+    logger.error(error.message);
+    process.exit(1);
+  }
+}
+
+export default showDoc;

package/src/commands/init/index.js

@@ -106,13 +106,25 @@ 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, 'docs'), { recursive: true });
     fs.mkdirSync(path.join(targetFolder, '.templates'), { recursive: true });
+    fs.mkdirSync(path.join(targetFolder, '.templates', 'docs'), { 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`);
+    const docsTemplatesSrc = path.join(__dirname, '../../../assets', 'docs');
+    if (fs.existsSync(docsTemplatesSrc)) {
+      for (const file of fs.readdirSync(docsTemplatesSrc)) {
+        fs.copyFileSync(
+          path.join(docsTemplatesSrc, file),
+          path.join(targetFolder, '.templates', 'docs', file)
+        );
+      }
+    }
+
+    console.log(`✅ '${targetFolder}' initialized with config, tickets/, plans/, docs/, and .templates/`);
   } else {
     console.log(`⚠️  Folder '${targetFolder}' already exists. Skipping .vibe creation.`);
   }

package/src/utils/doc.js

@@ -0,0 +1,137 @@
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+import { getProjectRoot } from './index.js';
+
+const DEFAULT_DOCS_PATH = '.vibe/docs';
+
+/**
+ * Get the docs directory from config or default.
+ * @returns {string} Absolute path to the docs directory
+ */
+export function getDocsDir() {
+  const root = getProjectRoot();
+  const configPath = path.join(root, '.vibe', 'config.yml');
+  let docsPath = DEFAULT_DOCS_PATH;
+
+  try {
+    if (fs.existsSync(configPath)) {
+      const config = yaml.load(fs.readFileSync(configPath, 'utf-8')) || {};
+      if (config.docs?.path && typeof config.docs.path === 'string') {
+        docsPath = config.docs.path;
+      }
+    }
+  } catch (error) {
+    console.error(`❌ Error reading config: ${error.message}`);
+  }
+
+  return path.resolve(root, docsPath);
+}
+
+/**
+ * Generate the next doc ID (DOC-NNN), independent from ticket IDs.
+ * @returns {string} Next doc ID, e.g. "DOC-002"
+ */
+export function getNextDocId() {
+  const docsDir = getDocsDir();
+
+  if (!fs.existsSync(docsDir)) {
+    return 'DOC-001';
+  }
+
+  try {
+    const numbers = fs.readdirSync(docsDir)
+      .filter(f => f.endsWith('.md'))
+      .map(f => f.match(/^DOC-(\d+)/))
+      .filter(Boolean)
+      .map(match => parseInt(match[1], 10))
+      .filter(num => !isNaN(num) && num > 0);
+
+    const next = Math.max(0, ...numbers) + 1;
+    return `DOC-${String(next).padStart(3, '0')}`;
+  } catch (error) {
+    console.error(`❌ Error scanning docs directory: ${error.message}`);
+    return 'DOC-001';
+  }
+}
+
+/**
+ * Resolve a doc identifier (1, 001, DOC-1, DOC-001) to its file.
+ * @param {string|number} input - The doc identifier
+ * @returns {Object|null} { id, file, path } or null if not found
+ * @throws {Error} If the input format is invalid
+ */
+export function resolveDocId(input) {
+  if (!input && input !== 0) {
+    return null;
+  }
+
+  const docsDir = getDocsDir();
+
+  if (!fs.existsSync(docsDir)) {
+    return null;
+  }
+
+  const files = fs.readdirSync(docsDir).filter(f => f.endsWith('.md'));
+
+  let clean = input.toString().trim().toUpperCase();
+  if (clean.startsWith('DOC-')) {
+    clean = clean.replace('DOC-', '');
+  }
+
+  if (!/^\d+$/.test(clean)) {
+    throw new Error(`Invalid doc ID format: ${input}. Expected numeric ID or DOC-XXX format.`);
+  }
+
+  const fullId = `DOC-${clean.padStart(3, '0')}`;
+  const matchingFile = files.find(file => file.startsWith(fullId));
+
+  if (matchingFile) {
+    return {
+      id: fullId,
+      file: matchingFile,
+      path: path.join(docsDir, matchingFile)
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Parse a doc markdown file, splitting frontmatter and content.
+ * @param {string} filePath - Path to the doc file
+ * @returns {Object} { metadata, yamlLines, contentLines, fullContent, filePath }
+ * @throws {Error} If the file is missing or malformed
+ */
+export function parseDoc(filePath) {
+  if (typeof filePath !== 'string') {
+    throw new Error('File path must be a string');
+  }
+
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`Doc file not found: ${filePath}`);
+  }
+
+  const content = fs.readFileSync(filePath, 'utf8');
+
+  if (!content.trim()) {
+    throw new Error('Doc file is empty');
+  }
+
+  const lines = content.split('\n');
+
+  if (lines[0] !== '---') {
+    throw new Error('Invalid doc format: missing opening frontmatter delimiter (---)');
+  }
+
+  const yamlEndIndex = lines.findIndex((line, index) => index > 0 && line === '---');
+  if (yamlEndIndex === -1) {
+    throw new Error('Invalid doc format: missing closing frontmatter delimiter (---)');
+  }
+
+  const yamlLines = lines.slice(1, yamlEndIndex);
+  const contentLines = lines.slice(yamlEndIndex + 1);
+  const metadata = yaml.load(yamlLines.join('\n')) || {};
+
+  return { metadata, yamlLines, contentLines, fullContent: content, filePath };
+}

package/src/utils/doc.test.js

@@ -0,0 +1,112 @@
+import { describe, it, expect, beforeEach, afterEach } from '@jest/globals';
+import fs from 'fs';
+import path from 'path';
+import {
+  createTempDir,
+  cleanupTempDir,
+  mockConsole,
+  mockProcessCwd,
+  createMockVibeProject
+} from './test-helpers.js';
+import { getNextDocId, resolveDocId, parseDoc, getDocsDir } from './doc.js';
+
+function writeDoc(docsDir, id, slug, extra = '') {
+  fs.mkdirSync(docsDir, { recursive: true });
+  const content = `---
+id: ${id}
+title: ${slug}
+type: guide
+status: draft
+tags: []
+---
+
+## Overview
+${extra}
+`;
+  fs.writeFileSync(path.join(docsDir, `${id}-${slug}.md`), content, 'utf-8');
+}
+
+describe('doc utils', () => {
+  let tempDir;
+  let consoleMock;
+  let restoreCwd;
+
+  beforeEach(() => {
+    tempDir = createTempDir('doc-util-test');
+    consoleMock = mockConsole();
+    restoreCwd = mockProcessCwd(tempDir);
+    createMockVibeProject(tempDir);
+  });
+
+  afterEach(() => {
+    consoleMock.restore();
+    restoreCwd();
+    cleanupTempDir(tempDir);
+  });
+
+  describe('getDocsDir', () => {
+    it('defaults to .vibe/docs', () => {
+      expect(getDocsDir()).toBe(path.join(tempDir, '.vibe', 'docs'));
+    });
+  });
+
+  describe('getNextDocId', () => {
+    it('returns DOC-001 when no docs exist', () => {
+      expect(getNextDocId()).toBe('DOC-001');
+    });
+
+    it('increments based on existing docs', () => {
+      const docsDir = path.join(tempDir, '.vibe', 'docs');
+      writeDoc(docsDir, 'DOC-001', 'first');
+      writeDoc(docsDir, 'DOC-002', 'second');
+      expect(getNextDocId()).toBe('DOC-003');
+    });
+
+    it('is independent from ticket IDs', () => {
+      const ticketsDir = path.join(tempDir, '.vibe', 'tickets');
+      fs.writeFileSync(path.join(ticketsDir, 'TKT-042-x.md'), '---\nid: TKT-042\n---\n');
+      expect(getNextDocId()).toBe('DOC-001');
+    });
+  });
+
+  describe('resolveDocId', () => {
+    beforeEach(() => {
+      writeDoc(path.join(tempDir, '.vibe', 'docs'), 'DOC-001', 'first');
+    });
+
+    it('resolves a bare number', () => {
+      expect(resolveDocId('1').id).toBe('DOC-001');
+    });
+
+    it('resolves a full DOC- id', () => {
+      expect(resolveDocId('DOC-001').id).toBe('DOC-001');
+    });
+
+    it('returns null for a missing doc', () => {
+      expect(resolveDocId('999')).toBeNull();
+    });
+
+    it('throws on invalid format', () => {
+      expect(() => resolveDocId('abc')).toThrow(/Invalid doc ID/);
+    });
+  });
+
+  describe('parseDoc', () => {
+    it('splits frontmatter and content', () => {
+      const docsDir = path.join(tempDir, '.vibe', 'docs');
+      writeDoc(docsDir, 'DOC-001', 'first', 'Body text');
+      const parsed = parseDoc(path.join(docsDir, 'DOC-001-first.md'));
+      expect(parsed.metadata.id).toBe('DOC-001');
+      expect(parsed.metadata.type).toBe('guide');
+      expect(parsed.contentLines.join('\n')).toContain('## Overview');
+    });
+
+    it('throws on missing frontmatter', () => {
+      const docsDir = path.join(tempDir, '.vibe', 'docs');
+      fs.mkdirSync(docsDir, { recursive: true });
+      const p = path.join(docsDir, 'DOC-009-bad.md');
+      fs.writeFileSync(p, 'no frontmatter here', 'utf-8');
+      expect(() => parseDoc(p)).toThrow(/frontmatter/);
+    });
+  });
+});

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)