@vibedx/vibekit 0.11.0 → 0.12.0

package/assets/config.yml

@@ -12,6 +12,7 @@ tickets:
   use_status_folders: false
   status_options:
     - open
+    - ready
     - in_progress
     - review
     - done

package/assets/default.md

@@ -12,19 +12,19 @@ updated_at: {date}
 
 ## Description
 
-<!-- Write the task details, requirements, and any other relevant information here. -->
+<!-- What is being built and why? Include context on the problem being solved and the desired outcome. Fill this in before writing any code. -->
 
 ## Acceptance Criteria
 
-<!-- List the specific conditions that must be met for this ticket to be considered complete. -->
+<!-- List specific, testable conditions for "done". Use checkboxes: - [ ] criterion. Fill this in before writing any code. -->
 
 ## Code Quality
 
-<!-- List the specific conditions that must be met for this ticket to be considered complete. -->
+<!-- Non-functional requirements: tests, no breaking changes, shared utilities, edge cases handled. -->
 
 ## Implementation Notes
 
-<!-- Technical details, references, or implementation context that might be helpful. -->
+<!-- Key technical decisions, files to modify, dependencies, and edge cases to handle. Fill this in before writing any code. -->
 
 ## Design / UX Considerations
 

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibedx/vibekit",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "A powerful CLI tool for managing development tickets and project workflows",
   "main": "index.js",
   "type": "module",

package/skills/vibekit/SKILL.md

@@ -22,6 +22,23 @@ Then read the ticket, plan the work, and `vibe start TKT-XXX` before touching an
 
 **Only skip the ticket for truly trivial changes**: typo fixes, single-line config tweaks, or answering a quick question.
 
+## 🔴 MANDATORY RULE: Detail the Ticket Before Writing Code
+
+**Before writing ANY code on a ticket, the ticket must be documented.** Tickets are often created with empty sections (just HTML comment placeholders). Do not start implementing against an empty ticket.
+
+When you `vibe start` a ticket:
+
+1. Read the ticket file.
+2. Check whether **Description**, **Acceptance Criteria**, and **Implementation Notes** have real content (a section that contains only whitespace or `<!-- ... -->` comments counts as empty).
+3. If any are empty, fill them in based on:
+   - The ticket title
+   - Your understanding of the codebase
+   - The context from the conversation
+4. Commit the updated ticket file with message `docs: add details to TKT-XXX`.
+5. Only then proceed to implementation.
+
+This applies to every AI tool using vibekit, not just Claude. `vibe start` warns when key sections are empty; `vibe start --agent` prepends this instruction to the agent's prompt automatically. Pass `--skip-detail-check` only for intentionally minimal tickets.
+
 ## Why This Matters
 
 Tickets break work into scoped, focused chunks that reduce AI drift and create documentation as a side effect. They also give humans a clear trail of what was done and why — critical for collaboration between humans and agents.
@@ -58,6 +75,7 @@ vibe init          # Creates .vibe/ directory with config, team, templates
 | `vibe init` | Initialize vibekit in a project |
 | `vibe new "title"` | Create a ticket |
 | `vibe list` | List all tickets |
+| `vibe ready <id>` | Mark a ticket ready for agent pickup (swarm) |
 | `vibe start <id>` | Start work (creates git branch) |
 | `vibe start <id> --worktree` | Start work in a separate worktree |
 | `vibe start <id> --agent` | Spawn a Claude agent to work on the ticket |
@@ -70,7 +88,7 @@ vibe init          # Creates .vibe/ directory with config, team, templates
 | `vibe lint --fix` | Auto-fix missing sections |
 | `vibe refine <id>` | AI-enhance ticket details |
 | `vibe plan to-ticket <file>` | Convert a saved plan into tickets (AI) |
-| `vibe swarm` | Spawn parallel agents across open tickets in worktrees |
+| `vibe swarm` | Spawn parallel agents across `ready` tickets in worktrees |
 | `vibe team` | Manage team members |
 
 ## Creating Tickets (for AI agents)

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

@@ -0,0 +1,72 @@
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+import { getTicketsDir } from '../../utils/index.js';
+import { checkEmptySections, KEY_TICKET_SECTIONS } from '../../utils/ticket.js';
+
+/**
+ * Mark a ticket as `ready` for agent pickup (e.g. by `vibe swarm`).
+ *
+ * A ticket should only be `ready` when it is fully fleshed out, so this refuses
+ * to promote tickets that still have empty key sections unless --force is passed.
+ * @param {string[]} args Command arguments
+ */
+function readyCommand(args) {
+  const ticketArg = args.find(a => !a.startsWith('-'));
+  const forceFlag = args.includes('--force') || args.includes('-f');
+
+  if (!ticketArg) {
+    console.error('❌ Usage: vibe ready <TKT-XXX> [--force]');
+    console.error('   Marks a ticket as ready for agent pickup (swarm).');
+    process.exit(1);
+  }
+
+  const ticketFolder = getTicketsDir();
+  if (!fs.existsSync(ticketFolder)) {
+    console.error(`❌ Tickets directory not found: ${ticketFolder}`);
+    process.exit(1);
+  }
+
+  const normalizedInput = ticketArg.startsWith('TKT-')
+    ? ticketArg
+    : `TKT-${ticketArg.padStart(3, '0')}`;
+
+  const files = fs.readdirSync(ticketFolder).filter(f => f.endsWith('.md'));
+
+  for (const file of files) {
+    const fullPath = path.join(ticketFolder, file);
+    if (fs.statSync(fullPath).isDirectory()) continue;
+
+    const content = fs.readFileSync(fullPath, 'utf-8');
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match) continue;
+
+    const frontmatter = yaml.load(match[1]);
+    if (frontmatter.id !== normalizedInput && !file.includes(normalizedInput)) continue;
+
+    const empty = checkEmptySections(content, KEY_TICKET_SECTIONS);
+    if (empty.length > 0 && !forceFlag) {
+      console.error(`❌ ${frontmatter.id} is not ready — empty section(s): ${empty.join(', ')}.`);
+      console.error(`   Fill them in (or run \`vibe refine ${frontmatter.id}\`) before marking ready.`);
+      console.error('   Use --force to mark ready anyway.');
+      process.exit(1);
+    }
+
+    frontmatter.status = 'ready';
+    frontmatter.updated_at = new Date().toISOString();
+
+    const updated = `---\n${yaml.dump(frontmatter)}---${content.split('---').slice(2).join('---')}`;
+    fs.writeFileSync(fullPath, updated, 'utf-8');
+
+    console.log(`✅ Ticket ${frontmatter.id} marked as ready for pickup.`);
+    if (empty.length > 0) {
+      console.log(`⚠️  Forced despite empty section(s): ${empty.join(', ')}.`);
+    }
+    return;
+  }
+
+  console.log(`❌ No ticket matching '${ticketArg}' found.`);
+  process.exit(1);
+}
+
+export default readyCommand;

package/src/commands/start/index.js

@@ -19,6 +19,7 @@ import {
   getDefaultBaseBranch
 } from '../../utils/git.js';
 import { loadSkillContext, buildAgentPrompt, spawnAgent } from '../../utils/agent.js';
+import { checkEmptySections, KEY_TICKET_SECTIONS } from '../../utils/ticket.js';
 
 function parseTicketIds(args) {
   const ids = [];
@@ -35,6 +36,9 @@ function parseTicketIds(args) {
     } else if (arg === '--no-install') {
       flags.noInstall = true;
       i++;
+    } else if (arg === '--skip-detail-check') {
+      flags.skipDetailCheck = true;
+      i++;
     } else if (arg === '--agent') {
       flags.agent = true;
       i++;
@@ -123,6 +127,25 @@ function updateTicketStatus(ticket, worktreePath) {
   fs.writeFileSync(ticket.filePath, updatedContent, 'utf-8');
 }
 
+function getEmptySections(ticket) {
+  try {
+    return checkEmptySections(fs.readFileSync(ticket.filePath, 'utf-8'));
+  } catch {
+    return [];
+  }
+}
+
+function buildDetailInstruction(ticketId, emptySections) {
+  return [
+    `⚠️ Ticket ${ticketId} is missing detail in: ${emptySections.join(', ')}.`,
+    'BEFORE writing any code:',
+    `1. Fill in the empty section(s) (${emptySections.join(', ')}) based on the ticket title, the codebase, and this conversation.`,
+    `2. Commit the updated ticket file with message "docs: add details to ${ticketId}".`,
+    '3. Only then start implementation.',
+    ''
+  ].join('\n');
+}
+
 /**
  * Start working on ticket(s) by checking out branches or creating worktrees
  * @param {string[]} args Command arguments
@@ -147,6 +170,7 @@ function startCommand(args) {
     console.error('  --base <branch>    Base branch for new branches/worktrees (default: main)');
     console.error('  --dry-run          Show what would happen without doing it');
     console.error('  --no-install       Skip npm install in worktrees');
+    console.error('  --skip-detail-check  Skip the empty-section detail check');
     process.exit(1);
   }
 
@@ -204,6 +228,14 @@ function startCommand(args) {
     const branchName = getBranchName(ticket, config);
     const title = ticket.frontmatter.title || 'Untitled';
 
+    if (!spawnAgent && !flags.skipDetailCheck) {
+      const empty = getEmptySections(ticket);
+      if (empty.length > 0) {
+        console.log(`  ⚠️  ${ticket.frontmatter.id}: empty section(s) — ${empty.join(', ')}`);
+        console.log(`     Fill these in before coding (or run \`vibe refine ${ticket.frontmatter.id}\`). Use --skip-detail-check to bypass.`);
+      }
+    }
+
     if (useWorktree) {
       const worktreePath = getWorktreePath(repoName, branchName);
       worktreeInfos.push({
@@ -274,7 +306,13 @@ function startCommand(args) {
       const skillContext = loadSkillContext();
       console.log('\n🤖 Spawning Claude agents...\n');
       for (const info of worktreeInfos) {
-        const prompt = buildAgentPrompt(info.ticket, flags.prompt, skillContext);
+        let prompt = buildAgentPrompt(info.ticket, flags.prompt, skillContext);
+        if (!flags.prompt && !flags.skipDetailCheck) {
+          const empty = getEmptySections(info.ticket);
+          if (empty.length > 0) {
+            prompt = buildDetailInstruction(info.ticket.frontmatter.id, empty) + '\n' + prompt;
+          }
+        }
 
         try {
           const pid = spawnAgent(prompt, info.worktreePath, agentTimeout);
@@ -320,7 +358,13 @@ function startCommand(args) {
       const ticket = tickets[0];
       const agentTimeout = config.worktree?.agent?.timeout || config.agent?.timeout || 900;
       const skillContext = loadSkillContext();
-      const prompt = buildAgentPrompt(ticket, flags.prompt, skillContext);
+      let prompt = buildAgentPrompt(ticket, flags.prompt, skillContext);
+      if (!flags.prompt && !flags.skipDetailCheck) {
+        const empty = getEmptySections(ticket);
+        if (empty.length > 0) {
+          prompt = buildDetailInstruction(ticket.frontmatter.id, empty) + '\n' + prompt;
+        }
+      }
 
       console.log('\n🤖 Spawning Claude agent...\n');
       try {

package/src/commands/swarm/index.js

@@ -81,10 +81,14 @@ function loadTickets(ticketsDir) {
 }
 
 function applyFilters(tickets, filterStr) {
-  if (!filterStr) return tickets.filter(t => t.frontmatter.status === 'open');
+  // Swarm only picks up `ready` tickets by default — `open` tickets are drafts.
+  if (!filterStr) return tickets.filter(t => t.frontmatter.status === 'ready');
+
+  const parts = filterStr.split(',').map(s => s.trim()).filter(Boolean);
+  const specifiesStatus = parts.some(p => p.split(':')[0].trim().toLowerCase() === 'status');
 
   return tickets.filter(t => {
-    const parts = filterStr.split(',').map(s => s.trim());
+    if (!specifiesStatus && t.frontmatter.status !== 'ready') return false;
     return parts.every(part => {
       const [key, value] = part.split(':').map(s => s.trim());
       if (!key || !value) return true;
@@ -263,7 +267,8 @@ export default function swarmCommand(args) {
   tickets = tickets.slice(0, maxAgents);
 
   if (tickets.length === 0) {
-    console.log('No tickets match the filter. Nothing to swarm.');
+    console.log('No `ready` tickets to swarm. Mark tickets ready with `vibe ready TKT-XXX`.');
+    console.log('(Swarm only picks up tickets with status: ready. Use --filter "status:open" to override.)');
     return;
   }
 

package/src/utils/ticket.js

@@ -409,15 +409,63 @@ function hasSectionContent(lines, sectionHeader) {
   if (!Array.isArray(lines)) {
     return false;
   }
-  
+
   if (typeof sectionHeader !== 'string' || !sectionHeader.trim()) {
     return false;
   }
-  
-  const sectionIndex = lines.findIndex(line => 
+
+  const sectionIndex = lines.findIndex(line =>
     line && typeof line === 'string' && line.trim() === sectionHeader.trim()
   );
-  
+
   return sectionIndex !== -1;
 }
 
+// Sections an agent must fill in before writing code.
+export const KEY_TICKET_SECTIONS = ['Description', 'Acceptance Criteria', 'Implementation Notes'];
+
+/**
+ * Determine whether a ticket section has real content. A section is "empty" if,
+ * after its header, it contains only whitespace, HTML comments, or nothing at
+ * all before the next `##` header or end of file.
+ * @param {string} ticketContent - Full ticket markdown (frontmatter optional)
+ * @param {string} sectionName - Section name without the leading `## `
+ * @returns {boolean} True when the section is missing or has no real content
+ */
+export function isTicketSectionEmpty(ticketContent, sectionName) {
+  if (typeof ticketContent !== 'string' || typeof sectionName !== 'string') {
+    return true;
+  }
+
+  const lines = ticketContent.split('\n');
+  const headerRegex = new RegExp(`^##\\s+${sectionName.trim().replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`);
+
+  let start = lines.findIndex(line => headerRegex.test(line));
+  if (start === -1) {
+    return true;
+  }
+
+  const body = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^##\s+/.test(lines[i])) break;
+    body.push(lines[i]);
+  }
+
+  const meaningful = body
+    .join('\n')
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .trim();
+
+  return meaningful.length === 0;
+}
+
+/**
+ * Return the list of key sections that are empty in a ticket.
+ * @param {string} ticketContent - Full ticket markdown
+ * @param {string[]} [sections] - Sections to check (defaults to KEY_TICKET_SECTIONS)
+ * @returns {string[]} Names of empty sections
+ */
+export function checkEmptySections(ticketContent, sections = KEY_TICKET_SECTIONS) {
+  return sections.filter(section => isTicketSectionEmpty(ticketContent, section));
+}
+

package/src/utils/ticket.test.js

@@ -7,7 +7,7 @@ import {
   mockProcessCwd, 
   createMockVibeProject
 } from './test-helpers.js';
-import { resolveTicketId } from './ticket.js';
+import { resolveTicketId, isTicketSectionEmpty, checkEmptySections } from './ticket.js';
 
 describe('ticket utilities', () => {
   let tempDir;
@@ -183,6 +183,60 @@ describe('ticket utilities', () => {
     });
   });
 
+  describe('isTicketSectionEmpty', () => {
+    it('treats a missing section as empty', () => {
+      expect(isTicketSectionEmpty('## Other\ncontent', 'Description')).toBe(true);
+    });
+
+    it('treats a comment-only section as empty', () => {
+      const md = '## Description\n\n<!-- write here -->\n\n## Acceptance Criteria\n';
+      expect(isTicketSectionEmpty(md, 'Description')).toBe(true);
+    });
+
+    it('treats a whitespace-only section as empty', () => {
+      expect(isTicketSectionEmpty('## Description\n\n   \n\n## Next\n', 'Description')).toBe(true);
+    });
+
+    it('treats a section with real content as non-empty', () => {
+      const md = '## Description\n\nBuild the login flow.\n\n## Next\n';
+      expect(isTicketSectionEmpty(md, 'Description')).toBe(false);
+    });
+
+    it('treats brief content as non-empty (no false positives)', () => {
+      expect(isTicketSectionEmpty('## Description\nFix typo.\n', 'Description')).toBe(false);
+    });
+
+    it('returns true for invalid input', () => {
+      expect(isTicketSectionEmpty(null, 'Description')).toBe(true);
+      expect(isTicketSectionEmpty('## Description\nx', null)).toBe(true);
+    });
+  });
+
+  describe('checkEmptySections', () => {
+    it('reports only the empty key sections', () => {
+      const md = [
+        '## Description',
+        'A real description here.',
+        '',
+        '## Acceptance Criteria',
+        '<!-- todo -->',
+        '',
+        '## Implementation Notes',
+        ''
+      ].join('\n');
+      expect(checkEmptySections(md)).toEqual(['Acceptance Criteria', 'Implementation Notes']);
+    });
+
+    it('returns empty array when all key sections have content', () => {
+      const md = [
+        '## Description', 'd', '',
+        '## Acceptance Criteria', '- [ ] a', '',
+        '## Implementation Notes', 'notes'
+      ].join('\n');
+      expect(checkEmptySections(md)).toEqual([]);
+    });
+  });
+
   // Note: parseTicket and updateTicket have complex error handling and validation
   // that would require extensive mocking of file system operations and YAML parsing.
   // These functions are better tested through integration tests that test the