vibe-coder-kit 6.0.1 → 6.1.0

package/.cursorrules

@@ -0,0 +1,77 @@
+# Vibe Coder Kit - Cursor Rules
+
+## Rules
+
+When working in this project, you MUST:
+
+1. **Read `.vibe/config.json` first** to understand project configuration
+2. **Check current phase** with `vibe status` before making changes
+3. **Log all events** using `vibe_append_event` tool
+4. **Follow the DAG workflow** - don't skip phases
+5. **Block on blockers** - use `vibe_log_blocker` and wait for resolution
+
+## Phase Rules
+
+### init
+- Set up project structure
+- Initialize all configuration files
+
+### plan
+- Create detailed implementation plan
+- Get approval before proceeding to code
+
+### code
+- Write code according to plan
+- Log each significant change
+- Run tests before marking complete
+
+### review
+- Review all changes
+- Log any issues found
+- Fix issues before proceeding
+
+### test
+- Run all tests
+- Log test results
+- Fix failures before proceeding
+
+## Available Tools
+
+Use these MCP tools to interact with VCK:
+
+- `vibe_status` - Check current phase and status
+- `vibe_append_event` - Log events
+- `vibe_transition` - Move to next phase
+- `vibe_check_health` - Run health checks
+- `vibe_add_knowledge` - Add to knowledge base
+- `vibe_search_knowledge` - Search knowledge base
+- `vibe_log_blocker` - Log blockers
+- `vibe_resolve_blocker` - Resolve blockers
+- `vibe_get_blockers` - Check open blockers
+
+## Anti-Patterns
+
+DO NOT:
+- Skip phases without explicit user approval
+- Ignore blockers
+- Make assumptions - research or ask
+- Commit secrets or keys
+- Break the DAG workflow
+
+## Examples
+
+```
+User: Add user authentication
+
+Agent actions:
+1. vibe_status -> Check current phase
+2. vibe_transition(phase: "plan", reason: "Planning auth feature")
+3. [Create implementation plan]
+4. vibe_append_event(type: "plan_created", data: {plan: "..."})
+5. vibe_transition(phase: "code", reason: "Implementing auth")
+6. [Write code]
+7. vibe_append_event(type: "code_written", data: {files: [...]})
+8. vibe_transition(phase: "review", reason: "Reviewing auth")
+9. [Review code]
+10. vibe_resolve_blocker(blockerId: "auth_security", resolution: "Fixed")
+```

package/.github/copilot-instructions.md

@@ -0,0 +1,108 @@
+# Vibe Coder Kit - Copilot Instructions
+
+## Project Context
+
+This project uses Vibe Coder Kit (VCK) for AI agent workflow management.
+
+## Key Rules
+
+1. **Always check status first** - Run `vibe status` to know current phase
+2. **Log everything** - Use MCP tools to log events and decisions
+3. **Follow the workflow** - Respect phase transitions
+4. **No assumptions** - Research or ask user when uncertain
+5. **Block on blockers** - Don't proceed until blockers are resolved
+
+## MCP Tools Available
+
+When you see these tools, use them:
+
+| Tool | Purpose |
+|------|---------|
+| `vibe_status` | Check project status |
+| `vibe_append_event` | Log an event |
+| `vibe_transition` | Change phase |
+| `vibe_check_health` | Health check |
+| `vibe_add_knowledge` | Add to knowledge base |
+| `vibe_search_knowledge` | Search knowledge |
+| `vibe_log_blocker` | Log a blocker |
+| `vibe_resolve_blocker` | Resolve a blocker |
+| `vibe_get_blockers` | List blockers |
+
+## Workflow
+
+```
+User Request
+    ↓
+Check Status (vibe_status)
+    ↓
+Plan (vibe_transition to plan)
+    ↓
+Implement (vibe_transition to code)
+    ↓
+Review (vibe_transition to review)
+    ↓
+Test (vibe_transition to test)
+    ↓
+Done
+```
+
+## Code Style
+
+- TypeScript for all new code
+- Turkish for comments and docs
+- English for code identifiers
+- No secrets in code
+- Log significant decisions
+
+## Common Patterns
+
+### Starting Work
+```javascript
+// Check current phase
+vibe_status()
+
+// Transition to planning
+vibe_transition({
+  phase: "plan",
+  reason: "Starting new feature"
+})
+```
+
+### During Work
+```javascript
+// Log progress
+vibe_append_event({
+  type: "progress",
+  data: { 
+    description: "Implemented auth module",
+    files: ["auth.ts", "auth.test.ts"]
+  }
+})
+```
+
+### Finishing Work
+```javascript
+// Log completion
+vibe_append_event({
+  type: "task_complete",
+  data: {
+    task: "Add user authentication",
+    result: "success"
+  }
+})
+```
+
+## Error Handling
+
+If you encounter blockers:
+1. Log the blocker: `vibe_log_blocker({description: "...", severity: "high"})`
+2. Ask user for guidance
+3. Wait for resolution
+4. Resolve blocker: `vibe_resolve_blocker({blockerId: "...", resolution: "..."})`
+
+## Security
+
+- Never commit secrets
+- Use environment variables
+- Validate all inputs
+- Log security events

package/.vibe/mcp/mcp-config.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "vibe-coder-kit": {
+      "command": "node",
+      "args": [".vibe/mcp/server.js"],
+      "env": {
+        "VIBE_PROJECT_ROOT": "${workspaceFolder}"
+      }
+    }
+  }
+}

package/.vibe/mcp/server.js

@@ -0,0 +1,686 @@
+#!/usr/bin/env node
+
+/**
+ * Vibe Coder Kit - MCP Server
+ * 
+ * Exposes VCK modules as MCP tools for AI agents.
+ * Usage: node .vibe/mcp/server.js
+ * 
+ * Transport: stdio
+ * Protocol: MCP (Model Context Protocol)
+ */
+
+const { readFileSync, writeFileSync, existsSync, mkdirSync } = require('fs');
+const { join, resolve } = require('path');
+const { createHash } = require('crypto');
+
+// ============================================================
+// Configuration
+// ============================================================
+
+const PROJECT_ROOT = process.env.VIBE_PROJECT_ROOT || process.cwd();
+const VIBE_DIR = join(PROJECT_ROOT, '.vibe');
+const STATE_DIR = join(VIBE_DIR, 'state');
+const STATE_FILE = join(STATE_DIR, 'events.jsonl');
+const CONFIG_FILE = join(VIBE_DIR, 'config.json');
+const KNOWLEDGE_DIR = join(VIBE_DIR, 'memory');
+
+// ============================================================
+// Utility Functions
+// ============================================================
+
+function ensureDirectories() {
+  [VIBE_DIR, STATE_DIR, KNOWLEDGE_DIR].forEach(dir => {
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+  });
+}
+
+function readJSON(filePath) {
+  try {
+    if (!existsSync(filePath)) return null;
+    return JSON.parse(readFileSync(filePath, 'utf-8'));
+  } catch (e) {
+    return null;
+  }
+}
+
+function writeJSON(filePath, data) {
+  writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf-8');
+}
+
+function appendLine(filePath, line) {
+  writeFileSync(filePath, line + '\n', { flag: 'a' });
+}
+
+function generateId() {
+  return `evt_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+}
+
+function computeChecksum(event) {
+  return createHash('sha256')
+    .update(JSON.stringify(event))
+    .digest('hex')
+    .substring(0, 16);
+}
+
+function getTimestamp() {
+  return new Date().toISOString();
+}
+
+// ============================================================
+// Event Store Functions
+// ============================================================
+
+function readEvents() {
+  if (!existsSync(STATE_FILE)) return [];
+  const content = readFileSync(STATE_FILE, 'utf-8');
+  return content
+    .split('\n')
+    .filter(line => line.trim())
+    .map(line => {
+      try {
+        return JSON.parse(line);
+      } catch (e) {
+        return null;
+      }
+    })
+    .filter(e => e !== null);
+}
+
+function appendEvent(eventData) {
+  ensureDirectories();
+  
+  const event = {
+    id: generateId(),
+    timestamp: getTimestamp(),
+    ...eventData
+  };
+  
+  event.checksum = computeChecksum(event);
+  
+  appendLine(STATE_FILE, JSON.stringify(event));
+  
+  return event;
+}
+
+function getLatestPhase() {
+  const events = readEvents();
+  const phaseEvents = events.filter(e => e.type === 'phase_transition');
+  if (phaseEvents.length === 0) return 'init';
+  return phaseEvents[phaseEvents.length - 1].data?.phase || 'init';
+}
+
+// ============================================================
+// MCP Protocol Implementation
+// ============================================================
+
+const TOOLS = [
+  {
+    name: 'vibe_status',
+    description: 'Show current VCK status including phase, events, and blockers',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      required: []
+    }
+  },
+  {
+    name: 'vibe_append_event',
+    description: 'Append a new event to the event store',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        type: {
+          type: 'string',
+          description: 'Event type (e.g., phase_transition, code_written, review_done)'
+        },
+        data: {
+          type: 'object',
+          description: 'Event data payload'
+        },
+        phase: {
+          type: 'string',
+          description: 'Current phase (e.g., plan, code, review)'
+        }
+      },
+      required: ['type', 'data']
+    }
+  },
+  {
+    name: 'vibe_get_events',
+    description: 'Get all events from the event store',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        type: {
+          type: 'string',
+          description: 'Filter by event type (optional)'
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum number of events to return (default: 50)'
+        }
+      },
+      required: []
+    }
+  },
+  {
+    name: 'vibe_transition',
+    description: 'Transition to a new workflow phase',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        phase: {
+          type: 'string',
+          description: 'Target phase (e.g., plan, code, review, test)'
+        },
+        reason: {
+          type: 'string',
+          description: 'Reason for transition'
+        }
+      },
+      required: ['phase', 'reason']
+    }
+  },
+  {
+    name: 'vibe_check_health',
+    description: 'Run health checks on the VCK installation',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      required: []
+    }
+  },
+  {
+    name: 'vibe_add_knowledge',
+    description: 'Add an entry to the knowledge base',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        title: {
+          type: 'string',
+          description: 'Knowledge entry title'
+        },
+        content: {
+          type: 'string',
+          description: 'Knowledge entry content'
+        },
+        tags: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Tags for categorization'
+        }
+      },
+      required: ['title', 'content']
+    }
+  },
+  {
+    name: 'vibe_search_knowledge',
+    description: 'Search the knowledge base',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description: 'Search query'
+        }
+      },
+      required: ['query']
+    }
+  },
+  {
+    name: 'vibe_get_config',
+    description: 'Get the current project configuration',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      required: []
+    }
+  },
+  {
+    name: 'vibe_update_config',
+    description: 'Update project configuration',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        updates: {
+          type: 'object',
+          description: 'Configuration updates to apply'
+        }
+      },
+      required: ['updates']
+    }
+  },
+  {
+    name: 'vibe_log_blocker',
+    description: 'Log a blocker that prevents progress',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        description: {
+          type: 'string',
+          description: 'Description of the blocker'
+        },
+        severity: {
+          type: 'string',
+          enum: ['low', 'medium', 'high', 'critical'],
+          description: 'Blocker severity'
+        }
+      },
+      required: ['description']
+    }
+  },
+  {
+    name: 'vibe_resolve_blocker',
+    description: 'Mark a blocker as resolved',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        blockerId: {
+          type: 'string',
+          description: 'ID of the blocker to resolve'
+        },
+        resolution: {
+          type: 'string',
+          description: 'How the blocker was resolved'
+        }
+      },
+      required: ['blockerId', 'resolution']
+    }
+  },
+  {
+    name: 'vibe_get_blockers',
+    description: 'Get all open blockers',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      required: []
+    }
+  }
+];
+
+// ============================================================
+// Tool Handlers
+// ============================================================
+
+const handlers = {
+  vibe_status: () => {
+    const events = readEvents();
+    const phase = getLatestPhase();
+    const blockers = events.filter(e => 
+      e.type === 'blocker' && !e.data?.resolved
+    );
+    
+    return {
+      phase,
+      lastUpdated: events.length > 0 ? events[events.length - 1].timestamp : null,
+      totalEvents: events.length,
+      openBlockers: blockers.length,
+      recentEvents: events.slice(-5)
+    };
+  },
+
+  vibe_append_event: (args) => {
+    const event = appendEvent({
+      type: args.type,
+      phase: args.phase || getLatestPhase(),
+      data: args.data
+    });
+    
+    return {
+      success: true,
+      event
+    };
+  },
+
+  vibe_get_events: (args) => {
+    let events = readEvents();
+    
+    if (args.type) {
+      events = events.filter(e => e.type === args.type);
+    }
+    
+    const limit = args.limit || 50;
+    return events.slice(-limit);
+  },
+
+  vibe_transition: (args) => {
+    const fromPhase = getLatestPhase();
+    
+    const event = appendEvent({
+      type: 'phase_transition',
+      data: {
+        from: fromPhase,
+        to: args.phase,
+        reason: args.reason
+      }
+    });
+    
+    return {
+      success: true,
+      from: fromPhase,
+      to: args.phase,
+      event
+    };
+  },
+
+  vibe_check_health: () => {
+    const checks = [];
+    
+    // Check .vibe directory
+    checks.push({
+      name: '.vibe directory',
+      status: existsSync(VIBE_DIR) ? 'pass' : 'fail'
+    });
+    
+    // Check config.json
+    checks.push({
+      name: 'config.json',
+      status: existsSync(CONFIG_FILE) ? 'pass' : 'fail'
+    });
+    
+    // Check state directory
+    checks.push({
+      name: 'State directory',
+      status: existsSync(STATE_DIR) ? 'pass' : 'fail'
+    });
+    
+    // Check knowledge directory
+    checks.push({
+      name: 'Knowledge directory',
+      status: existsSync(KNOWLEDGE_DIR) ? 'pass' : 'fail'
+    });
+    
+    // Check events file
+    checks.push({
+      name: 'Events file',
+      status: existsSync(STATE_FILE) ? 'pass' : 'warn',
+      message: existsSync(STATE_FILE) ? undefined : 'No events yet'
+    });
+    
+    const allPassed = checks.every(c => c.status === 'pass');
+    
+    return {
+      healthy: allPassed,
+      checks,
+      timestamp: getTimestamp()
+    };
+  },
+
+  vibe_add_knowledge: (args) => {
+    ensureDirectories();
+    
+    const id = `kb_${Date.now()}`;
+    const entry = {
+      id,
+      title: args.title,
+      content: args.content,
+      tags: args.tags || [],
+      createdAt: getTimestamp()
+    };
+    
+    const filePath = join(KNOWLEDGE_DIR, `${id}.json`);
+    writeJSON(filePath, entry);
+    
+    // Update INDEX.md
+    const indexPath = join(KNOWLEDGE_DIR, 'INDEX.md');
+    const indexEntry = `- [${args.title}](${id}.json) - ${args.tags?.join(', ') || 'untagged'}\n`;
+    writeFileSync(indexPath, indexEntry, { flag: 'a' });
+    
+    return {
+      success: true,
+      entry
+    };
+  },
+
+  vibe_search_knowledge: (args) => {
+    if (!existsSync(KNOWLEDGE_DIR)) {
+      return { results: [], total: 0 };
+    }
+    
+    const { readdirSync } = require('fs');
+    const files = readdirSync(KNOWLEDGE_DIR).filter(f => f.endsWith('.json'));
+    const query = args.query.toLowerCase();
+    
+    const results = [];
+    
+    for (const file of files) {
+      const entry = readJSON(join(KNOWLEDGE_DIR, file));
+      if (!entry) continue;
+      
+      const matches = 
+        entry.title?.toLowerCase().includes(query) ||
+        entry.content?.toLowerCase().includes(query) ||
+        entry.tags?.some(t => t.toLowerCase().includes(query));
+      
+      if (matches) {
+        results.push(entry);
+      }
+    }
+    
+    return {
+      results,
+      total: results.length,
+      query: args.query
+    };
+  },
+
+  vibe_get_config: () => {
+    return readJSON(CONFIG_FILE) || {};
+  },
+
+  vibe_update_config: (args) => {
+    const current = readJSON(CONFIG_FILE) || {};
+    const updated = { ...current, ...args.updates };
+    writeJSON(CONFIG_FILE, updated);
+    
+    return {
+      success: true,
+      config: updated
+    };
+  },
+
+  vibe_log_blocker: (args) => {
+    const blockerId = `blocker_${Date.now()}`;
+    
+    const event = appendEvent({
+      type: 'blocker',
+      data: {
+        id: blockerId,
+        description: args.description,
+        severity: args.severity || 'medium',
+        resolved: false,
+        createdAt: getTimestamp()
+      }
+    });
+    
+    return {
+      success: true,
+      blockerId,
+      event
+    };
+  },
+
+  vibe_resolve_blocker: (args) => {
+    const events = readEvents();
+    const blockerEvent = events.find(e => 
+      e.type === 'blocker' && e.data?.id === args.blockerId
+    );
+    
+    if (!blockerEvent) {
+      return {
+        success: false,
+        error: `Blocker ${args.blockerId} not found`
+      };
+    }
+    
+    const event = appendEvent({
+      type: 'blocker_resolved',
+      data: {
+        id: args.blockerId,
+        resolution: args.resolution,
+        resolvedAt: getTimestamp()
+      }
+    });
+    
+    return {
+      success: true,
+      blockerId: args.blockerId,
+      event
+    };
+  },
+
+  vibe_get_blockers: () => {
+    const events = readEvents();
+    const blockers = events.filter(e => e.type === 'blocker');
+    
+    // Mark resolved ones
+    const resolved = events
+      .filter(e => e.type === 'blocker_resolved')
+      .map(e => e.data?.id);
+    
+    const open = blockers.filter(b => 
+      !resolved.includes(b.data?.id)
+    );
+    
+    return {
+      open: open.map(b => b.data),
+      resolved: blockers.filter(b => resolved.includes(b.data?.id)).map(b => b.data),
+      totalOpen: open.length
+    };
+  }
+};
+
+// ============================================================
+// MCP Message Handling
+// ============================================================
+
+function handleMessage(message) {
+  const { id, method, params } = message;
+  
+  // Initialize
+  if (method === 'initialize') {
+    return {
+      jsonrpc: '2.0',
+      id,
+      result: {
+        protocolVersion: '2024-11-05',
+        capabilities: {
+          tools: {}
+        },
+        serverInfo: {
+          name: 'vibe-coder-kit',
+          version: '6.0.0'
+        }
+      }
+    };
+  }
+  
+  // List tools
+  if (method === 'tools/list') {
+    return {
+      jsonrpc: '2.0',
+      id,
+      result: {
+        tools: TOOLS
+      }
+    };
+  }
+  
+  // Call tool
+  if (method === 'tools/call') {
+    const { name, arguments: args } = params;
+    
+    if (!handlers[name]) {
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({ error: `Unknown tool: ${name}` })
+          }],
+          isError: true
+        }
+      };
+    }
+    
+    try {
+      const result = handlers[name](args || {});
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: {
+          content: [{
+            type: 'text',
+            text: JSON.stringify(result, null, 2)
+          }]
+        }
+      };
+    } catch (error) {
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({ error: error.message })
+          }],
+          isError: true
+        }
+      };
+    }
+  }
+  
+  // Ping
+  if (method === 'ping') {
+    return {
+      jsonrpc: '2.0',
+      id,
+      result: {}
+    };
+  }
+  
+  return {
+    jsonrpc: '2.0',
+    id,
+    error: {
+      code: -32601,
+      message: `Method not found: ${method}`
+    }
+  };
+}
+
+// ============================================================
+// Main - stdio transport
+// ============================================================
+
+let buffer = '';
+
+process.stdin.setEncoding('utf-8');
+process.stdin.on('data', (chunk) => {
+  buffer += chunk;
+  
+  // Process complete messages
+  while (true) {
+    const newlineIndex = buffer.indexOf('\n');
+    if (newlineIndex === -1) break;
+    
+    const line = buffer.substring(0, newlineIndex).trim();
+    buffer = buffer.substring(newlineIndex + 1);
+    
+    if (!line) continue;
+    
+    try {
+      const message = JSON.parse(line);
+      const response = handleMessage(message);
+      process.stdout.write(JSON.stringify(response) + '\n');
+    } catch (e) {
+      // Ignore parse errors
+    }
+  }
+});
+
+process.stderr.write('VCK MCP Server started on stdio\n');

package/.vibe/state/events.jsonl

@@ -0,0 +1,3 @@
+{"id":"evt_1782678823750_hviim082n","timestamp":"2026-06-28T20:33:43.750Z","type":"phase_transition","data":{"from":"init","to":"plan","reason":"Starting feature planning"},"checksum":"3776bbcddf185329"}
+{"id":"evt_1782678823755_dzqwd4kek","timestamp":"2026-06-28T20:33:43.755Z","type":"task_started","phase":"init","data":{"task":"Add user authentication"},"checksum":"34ba543afd423c7c"}
+{"id":"evt_1782678823758_l74v7crfy","timestamp":"2026-06-28T20:33:43.758Z","type":"blocker","data":{"id":"blocker_1782678823757","description":"Need API key from user","severity":"high","resolved":false,"createdAt":"2026-06-28T20:33:43.757Z"},"checksum":"867c4d9c17a6aea8"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vibe-coder-kit",
-  "version": "6.0.1",
-  "description": "Production-ready AI agent workflow template with TypeScript enforcement",
+  "version": "6.1.0",
+  "description": "Production-ready AI agent workflow template with TypeScript enforcement and MCP server",
   "main": "dist/.vibe/core/index.js",
   "types": "dist/.vibe/core/index.d.ts",
   "bin": {
@@ -11,6 +11,8 @@
   "files": [
     "bin/",
     ".vibe/",
+    ".cursorrules",
+    ".github/copilot-instructions.md",
     "AGENTS.md",
     "README.md"
   ],
@@ -18,6 +20,7 @@
     "build": "tsc",
     "dev": "ts-node .vibe/core/cli.ts",
     "start": "node dist/.vibe/core/cli.js",
+    "mcp": "node .vibe/mcp/server.js",
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "eslint .vibe/core/**/*.ts",