@vibedx/vibekit 0.10.0 → 0.11.1

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.10.0",
+  "version": "0.11.1",
   "description": "A powerful CLI tool for managing development tickets and project workflows",
   "main": "index.js",
   "type": "module",

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

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/get-started/index.js

@@ -41,12 +41,12 @@ function createSampleTicket(title, description, priority = "medium", status = "o
   content = content.replace(/^status: .*$/m, `status: ${status}`);
   
   // Add description
-  content = content.replace(/## Description\\s*\\n\\s*\\n/m, `## Description\\n\\n${description}\\n\\n`);
-  
+  content = content.replace(/## Description\s*\n\s*\n/m, `## Description\n\n${description}\n\n`);
+
   // Add AI prompt for the feature request example
   if (title.includes("AI Prompt")) {
-    content = content.replace(/## AI Prompt\\s*\\n\\s*\\n/m, 
-      `## AI Prompt\\n\\nGenerate ideas for implementing this feature in a Node.js CLI application. Consider user experience, error handling, and performance.\\n\\n`);
+    content = content.replace(/## AI Prompt\s*\n\s*\n/m,
+      `## AI Prompt\n\nGenerate ideas for implementing this feature in a Node.js CLI application. Consider user experience, error handling, and performance.\n\n`);
   }
   
   const outputPath = path.join(ticketDir, filename);

package/src/commands/get-started/index.test.js

@@ -122,6 +122,10 @@ describe('get-started command', () => {
       expect(content).toContain('status: open');
       expect(content).toContain('## Description');
       expect(content).toContain('Simple Task Example');
+      // The description text must be injected under the Description heading (regression: TKT-028)
+      expect(content).toContain('This is a simple task ticket example showing the basic structure.');
+      // Injected content must be real newlines, never literal backslash sequences
+      expect(content).not.toMatch(/\\n|\\s/);
       
       // Find the bug report example
       const bugReportFile = files.find(f => f.includes('bug-report-example'));
@@ -222,8 +226,12 @@ describe('get-started command', () => {
       
       const content = fs.readFileSync(path.join(ticketsDir, aiPromptFile), 'utf-8');
       expect(content).toContain('## AI Prompt');
-      expect(content).toContain('## AI Prompt');
       expect(content).toContain('Feature Request with AI Prompt');
+      // The AI prompt body must be injected under the heading (regression: TKT-028)
+      expect(content).toContain('Generate ideas for implementing this feature in a Node.js CLI application.');
+      // And the description for this ticket too
+      expect(content).toContain('This example shows how to use the AI prompt section');
+      expect(content).not.toMatch(/\\n|\\s/);
     });
 
     it('should create tickets with proper slug formatting', () => {

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