@vibedx/vibekit 0.9.0 → 0.11.0

package/README.md

@@ -54,6 +54,22 @@ The skill teaches agents the ticket-driven workflow — they'll create focused t
 
 **Coordinating multiple agents?** See **[docs/agent-workflow.md](./docs/agent-workflow.md)** for a framework-agnostic pattern for running multi-agent teams on a shared repo — assignees, polling loops, escalation, and loop prevention.
 
+### 🧩 Claude Code Plugin
+
+Prefer Claude Code? Install the vibekit plugin to get the full ticket-driven workflow, agents, and hooks built in:
+
+```
+/plugin install vibekit
+```
+
+The plugin bundles:
+
+- **Skills** — `vibekit-workflow` (full create → start → implement → close flow) and `ticket-writer` (well-structured tickets with acceptance criteria)
+- **Agents** — `ticket-worker` (reads a ticket, implements it, closes it) and `reviewer` (checks completed work against acceptance criteria)
+- **Hooks** — `SessionStart` detects your `.vibe/` directory and surfaces open ticket counts
+
+See **[vibekit-plugin/](./vibekit-plugin/)** for details. The CLI is optional but recommended (`npm install -g @vibedx/vibekit`).
+
 ## 🤔 Why VibeKit?
 
 - **🎯 Vibe code with manageable smaller tasks** - Break down complex features into focused tickets
@@ -139,6 +155,27 @@ vibe plan to-ticket .vibe/plans/my-feature.md --auto
 vibe plan to-ticket .vibe/plans/my-feature.md --dry-run
 ```
 
+### 📚 Docs
+```bash
+# Create a doc from a template (types: guide, design-doc, code-doc, faq)
+vibe docs add "Getting Started"
+vibe docs add "Docs Architecture" --type design-doc
+
+# Also open it in $EDITOR after creating
+vibe docs add "API Reference" --type code-doc --edit
+
+# List docs, with optional filters
+vibe docs list
+vibe docs list --type design-doc --status draft --tag api
+
+# Print a doc to stdout
+vibe docs show DOC-001
+
+# AI refinement pass — expands sections and fills placeholders
+vibe docs refine DOC-001
+```
+Docs live in `.vibe/docs/` with their own `DOC-NNN` sequence (independent from tickets). Templates are scaffolded into `.vibe/.templates/docs/` on `vibe init`.
+
 ### 🔀 Pull Requests
 ```bash
 # Open a GitHub PR from the current ticket branch (title/body from the ticket)

package/assets/config.yml

@@ -21,6 +21,16 @@ tickets:
     - high
     - critical
 
+docs:
+  path: ".vibe/docs"
+  id_format: "DOC-{number}"
+  default_template: ".vibe/.templates/docs/default.md"
+  default_type: guide
+  status_options:
+    - draft
+    - review
+    - published
+
 team:
   path: .vibe/team.yml
 

package/assets/docs/code-doc.md

@@ -0,0 +1,39 @@
+---
+id: {id}
+title: {title}
+slug: {slug}
+type: code-doc
+status: draft
+tags: []
+author: ""
+created_at: {date}
+updated_at: {date}
+---
+
+## Summary
+
+<!-- What does this module/component/service do, in one or two sentences? -->
+
+## Architecture
+
+<!-- How it's structured: key files, modules, and how they fit together. -->
+
+## Public API
+
+<!-- Functions, classes, or endpoints exposed. Include signatures and `code` examples. -->
+
+## Usage
+
+<!-- How to use it, with examples. -->
+
+## Internals
+
+<!-- Notable implementation details, invariants, and gotchas. -->
+
+## Testing
+
+<!-- How this code is tested and how to run those tests. -->
+
+## AI Prompt
+
+<!-- Instructions for `vibe docs refine` to document undocumented parts of the code. -->

package/assets/docs/default.md

@@ -0,0 +1,35 @@
+---
+id: {id}
+title: {title}
+slug: {slug}
+type: guide
+status: draft
+tags: []
+author: ""
+created_at: {date}
+updated_at: {date}
+---
+
+## Overview
+
+<!-- What is this guide about? Who is it for and what will they be able to do after reading it? -->
+
+## Prerequisites
+
+<!-- Anything the reader needs to know or have set up first. -->
+
+## Steps
+
+<!-- Walk through the process step by step. Use code blocks for commands and file paths. -->
+
+## Examples
+
+<!-- Concrete examples that show the guide in action. -->
+
+## References
+
+<!-- Links to related docs, tickets, or external resources. -->
+
+## AI Prompt
+
+<!-- Instructions for `vibe docs refine` to expand or improve this guide. -->

package/assets/docs/design-doc.md

@@ -0,0 +1,43 @@
+---
+id: {id}
+title: {title}
+slug: {slug}
+type: design-doc
+status: draft
+tags: []
+author: ""
+created_at: {date}
+updated_at: {date}
+---
+
+## Context & Problem
+
+<!-- What problem are we solving? Why now? What's the current state? -->
+
+## Goals
+
+<!-- What must this design achieve? -->
+
+## Non-Goals
+
+<!-- Explicitly out of scope. -->
+
+## Proposed Design
+
+<!-- The core of the doc: architecture, data flow, key decisions. -->
+
+## Alternatives Considered
+
+<!-- Other approaches and why they were not chosen. -->
+
+## Risks & Trade-offs
+
+<!-- What could go wrong, and what are we trading away? -->
+
+## Rollout Plan
+
+<!-- How this ships: phases, migrations, feature flags. -->
+
+## AI Prompt
+
+<!-- Instructions for `vibe docs refine` to pressure-test or expand this design. -->

package/assets/docs/faq.md

@@ -0,0 +1,33 @@
+---
+id: {id}
+title: {title}
+slug: {slug}
+type: faq
+status: draft
+tags: []
+author: ""
+created_at: {date}
+updated_at: {date}
+---
+
+## Overview
+
+<!-- What topic does this FAQ cover? -->
+
+## Questions
+
+### Q: <question here>
+
+<!-- Answer. -->
+
+### Q: <question here>
+
+<!-- Answer. -->
+
+## Still stuck?
+
+<!-- Where to go for more help: docs, channels, contacts. -->
+
+## AI Prompt
+
+<!-- Instructions for `vibe docs refine` to add or improve answers. -->

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibedx/vibekit",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "A powerful CLI tool for managing development tickets and project workflows",
   "main": "index.js",
   "type": "module",
@@ -8,7 +8,8 @@
     "index.js",
     "src/",
     "assets/",
-    "skills/"
+    "skills/",
+    "vibekit-plugin/"
   ],
   "bin": {
     "vibe": "index.js"

package/src/commands/docs/add.js

@@ -0,0 +1,162 @@
+import fs from 'fs';
+import path from 'path';
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import { getProjectRoot, getConfig, createSlug } from '../../utils/index.js';
+import { getDocsDir, getNextDocId } from '../../utils/doc.js';
+import { logger } from '../../utils/cli.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const DEFAULT_TYPE = 'guide';
+
+// Doc type -> template filename (bundled and project-local share names, guide -> default)
+const TYPE_TEMPLATES = {
+  guide: 'default.md',
+  'design-doc': 'design-doc.md',
+  'code-doc': 'code-doc.md',
+  faq: 'faq.md'
+};
+
+/**
+ * Parse `vibe docs add` arguments.
+ * @param {string[]} args
+ * @returns {{title: string, type: string, edit: boolean}}
+ */
+function parseArguments(args) {
+  const titleParts = [];
+  let type = null;
+  let edit = false;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--type' && i + 1 < args.length) {
+      type = args[i + 1];
+      i++;
+    } else if (arg === '--edit' || arg === '-e') {
+      edit = true;
+    } else if (!arg.startsWith('--')) {
+      titleParts.push(arg);
+    }
+  }
+
+  const title = titleParts.join(' ').trim();
+  if (!title) {
+    throw new Error('Please provide a title. Usage: vibe docs add "title" [--type <type>]');
+  }
+
+  return { title, type, edit };
+}
+
+/**
+ * Resolve the type, falling back to the default if unrecognised.
+ * @param {string|null} type
+ * @param {Object} config
+ * @returns {string}
+ */
+function resolveType(type, config) {
+  const defaultType = config.docs?.default_type || DEFAULT_TYPE;
+  if (!type) {
+    return defaultType;
+  }
+  if (!TYPE_TEMPLATES[type]) {
+    logger.warning(`Unknown doc type '${type}'. Falling back to '${defaultType}'.`);
+    return defaultType;
+  }
+  return type;
+}
+
+/**
+ * Load the template for a type: project-local first, then bundled asset.
+ * @param {string} type
+ * @param {string} root
+ * @returns {string}
+ */
+function loadTemplate(type, root) {
+  const templateFile = TYPE_TEMPLATES[type] || TYPE_TEMPLATES[DEFAULT_TYPE];
+  const projectTemplate = path.join(root, '.vibe', '.templates', 'docs', templateFile);
+  const bundledTemplate = path.join(__dirname, '../../../assets', 'docs', templateFile);
+
+  if (fs.existsSync(projectTemplate)) {
+    return fs.readFileSync(projectTemplate, 'utf-8');
+  }
+  if (fs.existsSync(bundledTemplate)) {
+    return fs.readFileSync(bundledTemplate, 'utf-8');
+  }
+  throw new Error(`No template found for type '${type}'. Run "vibe init" to scaffold doc templates.`);
+}
+
+/**
+ * Fill template placeholders.
+ * @param {string} template
+ * @param {{id: string, title: string, slug: string, type: string, timestamp: string}} data
+ * @returns {string}
+ */
+function fillTemplate(template, { id, title, slug, type, timestamp }) {
+  return template
+    .replace(/{id}/g, id)
+    .replace(/{title}/g, title)
+    .replace(/{slug}/g, slug)
+    .replace(/{date}/g, timestamp)
+    .replace(/^type: .*$/m, `type: ${type}`);
+}
+
+/**
+ * Open a file in $EDITOR.
+ * @param {string} filePath
+ */
+function openInEditor(filePath) {
+  const editor = process.env.EDITOR || process.env.VISUAL;
+  if (!editor) {
+    logger.warning('No $EDITOR set — skipping auto-open.');
+    return;
+  }
+  const child = spawn(editor, [filePath], { stdio: 'inherit' });
+  child.on('error', (err) => {
+    logger.warning(`Could not open editor: ${err.message}`);
+  });
+}
+
+/**
+ * `vibe docs add` — create a new doc from a template.
+ * @param {string[]} args
+ */
+async function addDoc(args) {
+  try {
+    const { title, type: rawType, edit } = parseArguments(args);
+    const root = getProjectRoot();
+    const config = getConfig();
+
+    const type = resolveType(rawType, config);
+    const template = loadTemplate(type, root);
+
+    const id = getNextDocId();
+    const slug = createSlug(title, config);
+    const filename = `${id}-${slug}.md`;
+    const timestamp = new Date().toISOString().split('T')[0];
+
+    const docsDir = getDocsDir();
+    if (!fs.existsSync(docsDir)) {
+      fs.mkdirSync(docsDir, { recursive: true });
+    }
+
+    const outputPath = path.join(docsDir, filename);
+    const content = fillTemplate(template, { id, title, slug, type, timestamp });
+
+    fs.writeFileSync(outputPath, content, 'utf-8');
+
+    const relativePath = path.relative(process.cwd(), outputPath);
+    logger.success(`Created ${id} (${type}): ${relativePath}`);
+
+    if (edit) {
+      openInEditor(outputPath);
+    }
+  } catch (error) {
+    logger.error(error.message);
+    process.exit(1);
+  }
+}
+
+export default addDoc;

package/src/commands/docs/index.js

@@ -0,0 +1,47 @@
+import { logger } from '../../utils/cli.js';
+import addDoc from './add.js';
+import listDocs from './list.js';
+import refineDoc from './refine.js';
+import showDoc from './show.js';
+
+const SUBCOMMANDS = {
+  add: addDoc,
+  list: listDocs,
+  refine: refineDoc,
+  show: showDoc
+};
+
+function showHelp() {
+  console.log(`\n📚 vibe docs — project documentation\n`);
+  console.log('Usage: vibe docs <subcommand> [options]\n');
+  console.log('Subcommands:');
+  console.log('  add "title" [--type guide|design-doc|code-doc|faq] [--edit]   Create a new doc');
+  console.log('  list [--type <type>] [--status <status>] [--tag <tag>]        List docs');
+  console.log('  show <id>                                                     Print a doc to stdout');
+  console.log('  refine <id>                                                   AI refinement pass\n');
+}
+
+/**
+ * `vibe docs` entry point — routes to subcommands.
+ * @param {string[]} args - Command arguments
+ */
+async function docsCommand(args = []) {
+  const [subcommand, ...rest] = args;
+
+  if (!subcommand || subcommand === '--help' || subcommand === '-h') {
+    showHelp();
+    return;
+  }
+
+  const handler = SUBCOMMANDS[subcommand];
+
+  if (!handler) {
+    logger.error(`Unknown docs subcommand: ${subcommand}`);
+    showHelp();
+    process.exit(1);
+  }
+
+  await handler(rest);
+}
+
+export default docsCommand;

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

@@ -0,0 +1,130 @@
+import { describe, it, expect, beforeEach, afterEach } from '@jest/globals';
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+import {
+  createTempDir,
+  cleanupTempDir,
+  mockConsole,
+  mockProcessCwd,
+  mockProcessExit,
+  createMockVibeProject
+} from '../../utils/test-helpers.js';
+import addDoc from './add.js';
+import listDocs from './list.js';
+import showDoc from './show.js';
+
+function readFrontmatter(filePath) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  return yaml.load(match[1]);
+}
+
+describe('docs command', () => {
+  let tempDir;
+  let consoleMock;
+  let restoreCwd;
+  let exitMock;
+
+  beforeEach(() => {
+    tempDir = createTempDir('docs-test');
+    consoleMock = mockConsole();
+    restoreCwd = mockProcessCwd(tempDir);
+    exitMock = mockProcessExit();
+    createMockVibeProject(tempDir);
+  });
+
+  afterEach(() => {
+    consoleMock.restore();
+    restoreCwd();
+    exitMock.restore();
+    cleanupTempDir(tempDir);
+  });
+
+  describe('add', () => {
+    it('creates a DOC-001 file with correct frontmatter', async () => {
+      await addDoc(['My First Guide']);
+
+      const docsDir = path.join(tempDir, '.vibe', 'docs');
+      const files = fs.readdirSync(docsDir);
+      expect(files).toHaveLength(1);
+      expect(files[0]).toMatch(/^DOC-001-my-first-guide\.md$/);
+
+      const fm = readFrontmatter(path.join(docsDir, files[0]));
+      expect(fm.id).toBe('DOC-001');
+      expect(fm.title).toBe('My First Guide');
+      expect(fm.type).toBe('guide');
+      expect(fm.status).toBe('draft');
+    });
+
+    it('assigns sequential IDs', async () => {
+      await addDoc(['First']);
+      await addDoc(['Second']);
+
+      const docsDir = path.join(tempDir, '.vibe', 'docs');
+      const ids = fs.readdirSync(docsDir).map(f => readFrontmatter(path.join(docsDir, f)).id).sort();
+      expect(ids).toEqual(['DOC-001', 'DOC-002']);
+    });
+
+    it('selects the template for --type', async () => {
+      await addDoc(['A Design', '--type', 'design-doc']);
+
+      const docsDir = path.join(tempDir, '.vibe', 'docs');
+      const file = fs.readdirSync(docsDir)[0];
+      const content = fs.readFileSync(path.join(docsDir, file), 'utf-8');
+      expect(readFrontmatter(path.join(docsDir, file)).type).toBe('design-doc');
+      expect(content).toContain('## Proposed Design');
+    });
+
+    it('falls back to guide for an unknown type', async () => {
+      await addDoc(['Weird', '--type', 'bogus']);
+
+      const docsDir = path.join(tempDir, '.vibe', 'docs');
+      const file = fs.readdirSync(docsDir)[0];
+      expect(readFrontmatter(path.join(docsDir, file)).type).toBe('guide');
+    });
+
+    it('exits with an error when no title is given', async () => {
+      await expect(addDoc([])).rejects.toThrow(/process.exit/);
+      expect(exitMock.exitCalls).toContain(1);
+    });
+  });
+
+  describe('list', () => {
+    beforeEach(async () => {
+      await addDoc(['Alpha Guide']);
+      await addDoc(['Beta Design', '--type', 'design-doc']);
+    });
+
+    it('lists all docs', () => {
+      listDocs([]);
+      const output = consoleMock.logs.log.join('\n');
+      expect(output).toContain('DOC-001');
+      expect(output).toContain('DOC-002');
+      expect(output).toContain('Found 2 doc(s)');
+    });
+
+    it('filters by type', () => {
+      listDocs(['--type', 'design-doc']);
+      const output = consoleMock.logs.log.join('\n');
+      expect(output).toContain('Beta Design');
+      expect(output).toContain('Found 1 doc(s) (type: design-doc)');
+      expect(output).not.toContain('Alpha Guide');
+    });
+  });
+
+  describe('show', () => {
+    it('prints a doc by id', async () => {
+      await addDoc(['Show Me']);
+      showDoc(['1']);
+      const output = consoleMock.logs.log.join('\n');
+      expect(output).toContain('id: DOC-001');
+      expect(output).toContain('title: Show Me');
+    });
+
+    it('errors on a missing doc', () => {
+      expect(() => showDoc(['999'])).toThrow(/process.exit/);
+      expect(exitMock.exitCalls).toContain(1);
+    });
+  });
+});