@govindchaudhary/vibekit 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vibekit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+[![npm version](https://img.shields.io/npm/v/@govindchaudhary/vibekit.svg)](https://www.npmjs.com/package/@govindchaudhary/vibekit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+# Vibekit
+
+**Vibe code without losing the plot.** Vibekit keeps fast, AI-driven "vibe
+coding" accurate by giving your assistant lean, *verifiable* context — a
+lightweight alternative to heavyweight Spec-Driven Development (SDD). Instead of
+generating a spec/plan/tasks document set for every feature, Vibekit maintains
+**3 persistent markdown files** that any AI coding assistant — Copilot, Claude,
+Cursor, Windsurf — reads automatically. No per-feature ceremony, no token bloat,
+and a working setup in **under 2 minutes**. It's tool-agnostic by design: the
+canonical file is `AGENTS.md`, and everything else mirrors from it.
+
+> **Motto:** *vibe fast, stay grounded.* The `AGENTS.md` Verify-before-trust
+> rule means the AI treats notes as hints and the current code as ground truth.
+
+---
+
+## Quickstart
+
+```bash
+npx @govindchaudhary/vibekit init
+```
+
+Answer one question ("What's this project mostly?") and you're done — under two
+minutes to a working setup. Vibekit creates four files in your current
+directory:
+
+| File | Purpose |
+| --- | --- |
+| `AGENTS.md` | Stable context + coding principles (the file AI actually reads) |
+| `CHANGELOG.md` | Rolling log of recent changes |
+| `DECISIONS.md` | Architecture decisions worth not re-litigating |
+| `principles-catalog.md` | Human reference menu — **never loaded by AI** |
+
+---
+
+## Two ways to adopt it
+
+**(a) Use this template (zero install).** Click **"Use this template"** at the
+top of this GitHub repo to clone the structure into a fresh repository. Good for
+brand-new projects.
+
+**(b) npx CLI (add to an existing repo).** Run `npx @govindchaudhary/vibekit init` inside any
+existing project to drop the files in without touching the rest of your code.
+
+---
+
+## Vibekit vs. typical SDD tools
+
+| | Vibekit | Typical SDD tool (Spec-Kit, BMAD) |
+| --- | --- | --- |
+| Setup time | < 2 minutes | 15–60 minutes |
+| Files per feature | 0 (3 persistent files total) | 3+ (spec, plan, tasks) per feature |
+| Token overhead | Low — one stable context file | High — large generated specs reloaded |
+| Best when | Solo devs / small teams wanting fast AI context | Large teams needing formal, auditable specs for complex features |
+
+Use a full SDD framework when you genuinely need formal, reviewable
+specifications per feature. Reach for Vibekit when you just want your AI
+assistant to have accurate, lightweight context without the overhead.
+
+---
+
+## The 3 files
+
+### `AGENTS.md` — stable context
+The one file AI tools read by default. It holds your active principle packs, a
+**Verify-before-trust** safeguard, your project stack, and your conventions.
+Keep it accurate; it's the source of durable context.
+
+### `CHANGELOG.md` — rolling log
+Newest entry first. Each entry has an exact ISO date, what changed and why, and
+the files/functions touched. Mark resolved entries `[DONE]`; `vibekit prune`
+trims old resolved entries so the file stays small (~10 active entries max).
+
+### `DECISIONS.md` — architecture decisions
+Only record choices a future session would otherwise guess wrong or re-debate —
+architecture and library choices, not routine bug fixes.
+
+> **Verify-before-trust:** CHANGELOG and DECISIONS are *hints, not ground truth*.
+> Before relying on an entry, confirm the referenced code still matches. If it
+> doesn't, the current code wins.
+
+---
+
+## How packs work
+
+A **pack** is a small, reusable block of coding principles wrapped in markers:
+
+```markdown
+<!-- pack:dev:start -->
+### SOLID Principles
+- ...
+<!-- pack:dev:end -->
+```
+
+Built-in packs:
+
+- **`core`** — always included (SRP, DRY, KISS, fail fast)
+- **`dev`** — SOLID principles for application development
+- **`data-eng`** — idempotency, schema validation, ETL separation, immutable raw data, reproducibility
+
+Manage packs at any time:
+
+```bash
+vibekit packs add data-eng
+vibekit packs remove dev
+```
+
+### Add a custom pack
+
+1. Create `packs/<name>.md`, e.g. `packs/security.md`.
+2. Wrap the content in markers whose name matches the file:
+
+   ```markdown
+   <!-- pack:security:start -->
+   ### Security Principles
+   - Least privilege: grant the minimum access required
+   - Never trust client input: validate at every boundary
+   <!-- pack:security:end -->
+   ```
+
+3. Activate it: `vibekit packs add security`.
+
+See [`principles-catalog.md`](./principles-catalog.md) for the full menu.
+
+---
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `vibekit init` | Scaffold the 4 files (asks one question). |
+| `vibekit log "<message>"` | Append a dated changelog entry (newest on top). |
+| `vibekit prune` | Remove `[DONE]` entries except the 5 most recent. |
+| `vibekit packs add <name>` | Insert a pack block into `AGENTS.md`. |
+| `vibekit packs remove <name>` | Remove a pack block from `AGENTS.md`. |
+| `vibekit sync` | Mirror `AGENTS.md` to `CLAUDE.md`, `.windsurfrules`, `.github/copilot-instructions.md`. |
+
+> **About `sync`:** most modern tools (Copilot, Cursor, Windsurf) now read
+> `AGENTS.md` natively. `sync` is a fallback for tools/older setups that don't
+> yet, or for teams who want the explicit native filename present.
+
+---
+
+## License
+
+[MIT](./LICENSE)

package/dist/cli.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const init_1 = require("./commands/init");
+const log_1 = require("./commands/log");
+const prune_1 = require("./commands/prune");
+const packs_1 = require("./commands/packs");
+const sync_1 = require("./commands/sync");
+const program = new commander_1.Command();
+program
+    .name('vibekit')
+    .description('Lean, AI-tool-agnostic project context: 3 persistent markdown files ' +
+    '(AGENTS.md, CHANGELOG.md, DECISIONS.md) that keep vibe coding accurate, ' +
+    'instead of heavyweight SDD specs.')
+    .version('0.1.1');
+program
+    .command('init')
+    .description('Scaffold AGENTS.md, CHANGELOG.md, DECISIONS.md, and principles-catalog.md in the current directory.')
+    .action(async () => {
+    await (0, init_1.initCommand)();
+});
+program
+    .command('log')
+    .description('Append a new entry to CHANGELOG.md (newest on top) with today\'s date.')
+    .argument('<message>', 'short description of what changed')
+    .action((message) => {
+    (0, log_1.logCommand)(message);
+});
+program
+    .command('prune')
+    .description('Remove resolved [DONE] changelog entries, keeping the 5 most recent.')
+    .action(() => {
+    (0, prune_1.pruneCommand)();
+});
+const packs = program
+    .command('packs')
+    .description('Add or remove principle packs in AGENTS.md.');
+packs
+    .command('add')
+    .description('Insert a pack block (packs/<name>.md) into AGENTS.md.')
+    .argument('<name>', 'pack name, e.g. dev or data-eng')
+    .action((name) => {
+    (0, packs_1.packsAddCommand)(name);
+});
+packs
+    .command('remove')
+    .description('Remove a pack block from AGENTS.md.')
+    .argument('<name>', 'pack name, e.g. dev or data-eng')
+    .action((name) => {
+    (0, packs_1.packsRemoveCommand)(name);
+});
+program
+    .command('sync')
+    .description('Mirror AGENTS.md to CLAUDE.md, .windsurfrules, and ' +
+    '.github/copilot-instructions.md. Most modern tools (Copilot, Cursor, ' +
+    'Windsurf) now read AGENTS.md natively — sync is a fallback for older ' +
+    'setups that don\'t yet, or for teams who want the explicit native ' +
+    'filename present.')
+    .action(() => {
+    (0, sync_1.syncCommand)();
+});
+async function main() {
+    try {
+        await program.parseAsync(process.argv);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`Error: ${message}`);
+        process.exit(1);
+    }
+}
+main();

package/dist/commands/init.js

@@ -0,0 +1,112 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initCommand = initCommand;
+const path = __importStar(require("path"));
+const prompts_1 = __importDefault(require("prompts"));
+const fileio_1 = require("../utils/fileio");
+const markers_1 = require("../utils/markers");
+const KIND_TO_PACKS = {
+    dev: ['core', 'dev'],
+    data: ['core', 'data-eng'],
+    both: ['core', 'dev', 'data-eng'],
+    skip: ['core'],
+};
+async function initCommand() {
+    const cwd = process.cwd();
+    const agentsPath = path.join(cwd, 'AGENTS.md');
+    if ((0, fileio_1.exists)(agentsPath)) {
+        const { overwrite } = await (0, prompts_1.default)({
+            type: 'confirm',
+            name: 'overwrite',
+            message: 'AGENTS.md already exists. Overwrite it?',
+            initial: false,
+        });
+        if (!overwrite) {
+            console.log('Aborted — existing AGENTS.md left untouched.');
+            return;
+        }
+    }
+    const { kind } = await (0, prompts_1.default)({
+        type: 'select',
+        name: 'kind',
+        message: "What's this project mostly?",
+        choices: [
+            { title: 'Dev', value: 'dev' },
+            { title: 'Data Engineering', value: 'data' },
+            { title: 'Both', value: 'both' },
+            { title: "Skip — I'll write my own", value: 'skip' },
+        ],
+        initial: 0,
+    });
+    // Handle abort (Ctrl+C) gracefully.
+    const selected = kind ?? 'skip';
+    const packs = KIND_TO_PACKS[selected];
+    // Build AGENTS.md from the template.
+    let agents = (0, fileio_1.readFile)((0, fileio_1.assetPath)('templates', 'AGENTS.md.template'));
+    if (selected === 'skip') {
+        // Core only, with a hint comment about adding more packs later.
+        const coreBlock = (0, markers_1.extractBlock)((0, fileio_1.readFile)((0, fileio_1.assetPath)('packs', 'core.md')), 'core');
+        const hint = '<!-- Add more packs later, e.g. `vibekit packs add dev` ' +
+            'or `vibekit packs add data-eng`. See principles-catalog.md. -->';
+        agents = agents.replace(markers_1.PACK_PLACEHOLDER, `${coreBlock}\n\n${hint}\n`);
+    }
+    else {
+        for (const name of packs) {
+            const block = (0, markers_1.extractBlock)((0, fileio_1.readFile)((0, fileio_1.assetPath)('packs', `${name}.md`)), name);
+            agents = (0, markers_1.insertPack)(agents, block);
+        }
+    }
+    agents = (0, markers_1.setActivePacksLine)(agents, packs);
+    // Write the 4 files.
+    (0, fileio_1.writeFile)(agentsPath, agents);
+    (0, fileio_1.writeFile)(path.join(cwd, 'CHANGELOG.md'), (0, fileio_1.readFile)((0, fileio_1.assetPath)('templates', 'CHANGELOG.md.template')));
+    (0, fileio_1.writeFile)(path.join(cwd, 'DECISIONS.md'), (0, fileio_1.readFile)((0, fileio_1.assetPath)('templates', 'DECISIONS.md.template')));
+    (0, fileio_1.writeFile)(path.join(cwd, 'principles-catalog.md'), (0, fileio_1.readFile)((0, fileio_1.assetPath)('principles-catalog.md')));
+    console.log('');
+    console.log('Vibekit initialized. Created:');
+    console.log('  - AGENTS.md             (stable context + active packs: ' + packs.join(', ') + ')');
+    console.log('  - CHANGELOG.md          (rolling log of recent changes)');
+    console.log('  - DECISIONS.md          (architecture decisions worth keeping)');
+    console.log('  - principles-catalog.md (reference only — never loaded by AI)');
+    console.log('');
+    console.log("What's next:");
+    console.log('  1. Fill in the Project Stack & Conventions sections of AGENTS.md.');
+    console.log('  2. Record changes with:  vibekit log "what you changed"');
+    console.log('  3. (Optional) mirror AGENTS.md for older tools:  vibekit sync');
+}

package/dist/commands/log.js

@@ -0,0 +1,90 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logCommand = logCommand;
+const path = __importStar(require("path"));
+const fileio_1 = require("../utils/fileio");
+const CHANGELOG_HEADING = /^## Changelog\s*$/m;
+const EMPTY_PLACEHOLDER = /\(no entries yet — run `vibekit log "description"` after your first change\)\s*/;
+/**
+ * Append a new changelog entry (newest on top) with today's ISO date.
+ */
+function logCommand(message) {
+    if (!message || !message.trim()) {
+        throw new Error('A message is required: vibekit log "what you changed"');
+    }
+    const cwd = process.cwd();
+    const changelogPath = path.join(cwd, 'CHANGELOG.md');
+    if (!(0, fileio_1.exists)(changelogPath)) {
+        throw new Error('CHANGELOG.md not found. Run `vibekit init` first.');
+    }
+    let content = (0, fileio_1.readFile)(changelogPath);
+    const date = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
+    const entry = `### ${date} — ${message.trim()}\nFiles: \n`;
+    // Drop the "no entries yet" placeholder if present.
+    content = content.replace(EMPTY_PLACEHOLDER, '');
+    const headingMatch = content.match(CHANGELOG_HEADING);
+    if (headingMatch && headingMatch.index !== undefined) {
+        const insertAt = headingMatch.index + headingMatch[0].length;
+        const before = content.slice(0, insertAt).replace(/\s*$/, '');
+        const after = content.slice(insertAt).replace(/^\s*/, '');
+        content = `${before}\n\n${entry}\n${after}`.replace(/\n{3,}/g, '\n\n');
+    }
+    else {
+        // No heading found — prepend.
+        content = `## Changelog\n\n${entry}\n${content}`;
+    }
+    (0, fileio_1.writeFile)(changelogPath, content.replace(/\s*$/, '') + '\n');
+    console.log(`Logged entry for ${date}: ${message.trim()}`);
+    const activeCount = countActiveEntries(content);
+    if (activeCount > 10) {
+        console.log('');
+        console.log(`You now have ${activeCount} active entries. ` +
+            'Consider running `vibekit prune` to trim resolved [DONE] entries.');
+    }
+}
+/**
+ * Count entries (lines starting with "### ") that are NOT tagged [DONE].
+ */
+function countActiveEntries(content) {
+    const lines = content.split('\n');
+    let count = 0;
+    for (const line of lines) {
+        if (/^###\s+/.test(line) && !/\[DONE\]/i.test(line)) {
+            count++;
+        }
+    }
+    return count;
+}

package/dist/commands/packs.js

@@ -0,0 +1,83 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.packsAddCommand = packsAddCommand;
+exports.packsRemoveCommand = packsRemoveCommand;
+const path = __importStar(require("path"));
+const fileio_1 = require("../utils/fileio");
+const markers_1 = require("../utils/markers");
+function loadAgents() {
+    const cwd = process.cwd();
+    const agentsPath = path.join(cwd, 'AGENTS.md');
+    if (!(0, fileio_1.exists)(agentsPath)) {
+        throw new Error('AGENTS.md not found. Run `vibekit init` first.');
+    }
+    return { agentsPath, content: (0, fileio_1.readFile)(agentsPath) };
+}
+function packsAddCommand(name) {
+    if (!name) {
+        throw new Error('Usage: vibekit packs add <name>');
+    }
+    const packFile = (0, fileio_1.assetPath)('packs', `${name}.md`);
+    if (!(0, fileio_1.exists)(packFile)) {
+        throw new Error(`Pack "${name}" does not exist in packs/. ` +
+            'See principles-catalog.md for available packs, or create packs/' +
+            `${name}.md with matching <!-- pack:${name}:start --> markers.`);
+    }
+    const { agentsPath, content } = loadAgents();
+    if ((0, markers_1.hasPack)(content, name)) {
+        console.log(`Pack "${name}" is already active in AGENTS.md.`);
+        return;
+    }
+    const block = (0, markers_1.extractBlock)((0, fileio_1.readFile)(packFile), name);
+    let updated = (0, markers_1.insertPack)(content, block);
+    updated = (0, markers_1.setActivePacksLine)(updated, (0, markers_1.listActivePacks)(updated));
+    (0, fileio_1.writeFile)(agentsPath, updated);
+    console.log(`Added pack "${name}" to AGENTS.md.`);
+}
+function packsRemoveCommand(name) {
+    if (!name) {
+        throw new Error('Usage: vibekit packs remove <name>');
+    }
+    const { agentsPath, content } = loadAgents();
+    if (!(0, markers_1.hasPack)(content, name)) {
+        throw new Error(`Pack "${name}" is not currently active in AGENTS.md. ` +
+            `Active packs: ${(0, markers_1.listActivePacks)(content).join(', ') || '(none)'}.`);
+    }
+    let updated = (0, markers_1.removePack)(content, name);
+    updated = (0, markers_1.setActivePacksLine)(updated, (0, markers_1.listActivePacks)(updated));
+    (0, fileio_1.writeFile)(agentsPath, updated);
+    console.log(`Removed pack "${name}" from AGENTS.md.`);
+}

package/dist/commands/prune.js

@@ -0,0 +1,101 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pruneCommand = pruneCommand;
+const path = __importStar(require("path"));
+const fileio_1 = require("../utils/fileio");
+/**
+ * Remove all [DONE]-tagged entries except the 5 most recent ones.
+ *
+ * Entries are blocks starting at a line matching "### " and running until the
+ * next "### " line (or end of file). "Most recent" means earliest in the file,
+ * since the changelog keeps newest entries on top.
+ */
+function pruneCommand() {
+    const cwd = process.cwd();
+    const changelogPath = path.join(cwd, 'CHANGELOG.md');
+    if (!(0, fileio_1.exists)(changelogPath)) {
+        throw new Error('CHANGELOG.md not found. Run `vibekit init` first.');
+    }
+    const content = (0, fileio_1.readFile)(changelogPath);
+    const lines = content.split('\n');
+    // Identify entry start indices.
+    const entryStarts = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (/^###\s+/.test(lines[i])) {
+            entryStarts.push(i);
+        }
+    }
+    if (entryStarts.length === 0) {
+        console.log('No changelog entries found — nothing to prune.');
+        return;
+    }
+    const headerEnd = entryStarts[0];
+    const header = lines.slice(0, headerEnd).join('\n').replace(/\s*$/, '');
+    const entries = [];
+    for (let e = 0; e < entryStarts.length; e++) {
+        const start = entryStarts[e];
+        const end = e + 1 < entryStarts.length ? entryStarts[e + 1] : lines.length;
+        const text = lines.slice(start, end).join('\n').replace(/\s*$/, '');
+        const done = /\[DONE\]/i.test(lines[start]);
+        entries.push({ text, done });
+    }
+    // Keep the 5 most recent [DONE] entries (topmost = most recent).
+    let doneKept = 0;
+    const kept = [];
+    let removed = 0;
+    for (const entry of entries) {
+        if (entry.done) {
+            if (doneKept < 5) {
+                doneKept++;
+                kept.push(entry);
+            }
+            else {
+                removed++;
+            }
+        }
+        else {
+            kept.push(entry);
+        }
+    }
+    if (removed === 0) {
+        console.log('No prunable [DONE] entries (kept the 5 most recent).');
+        return;
+    }
+    const body = kept.map((e) => e.text).join('\n\n');
+    const rebuilt = `${header}\n\n${body}\n`.replace(/\n{3,}/g, '\n\n');
+    (0, fileio_1.writeFile)(changelogPath, rebuilt);
+    console.log(`Pruned ${removed} resolved [DONE] ${removed === 1 ? 'entry' : 'entries'} (kept the 5 most recent).`);
+}

package/dist/commands/sync.js

@@ -0,0 +1,63 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.syncCommand = syncCommand;
+const path = __importStar(require("path"));
+const fileio_1 = require("../utils/fileio");
+/**
+ * Mirror AGENTS.md to the filenames used by tools that don't yet read
+ * AGENTS.md natively.
+ */
+function syncCommand() {
+    const cwd = process.cwd();
+    const agentsPath = path.join(cwd, 'AGENTS.md');
+    if (!(0, fileio_1.exists)(agentsPath)) {
+        throw new Error('AGENTS.md not found. Run `vibekit init` first.');
+    }
+    const content = (0, fileio_1.readFile)(agentsPath);
+    const targets = [
+        path.join(cwd, 'CLAUDE.md'),
+        path.join(cwd, '.windsurfrules'),
+        path.join(cwd, '.github', 'copilot-instructions.md'),
+    ];
+    (0, fileio_1.ensureDir)(path.join(cwd, '.github'));
+    for (const target of targets) {
+        (0, fileio_1.writeFile)(target, content);
+    }
+    console.log('Synced AGENTS.md to:');
+    console.log('  - CLAUDE.md');
+    console.log('  - .windsurfrules');
+    console.log('  - .github/copilot-instructions.md');
+}

package/dist/utils/fileio.js

@@ -0,0 +1,99 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readFile = readFile;
+exports.writeFile = writeFile;
+exports.exists = exists;
+exports.ensureDir = ensureDir;
+exports.assetPath = assetPath;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Read a UTF-8 text file. Throws a clear error if it doesn't exist.
+ */
+function readFile(filePath) {
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`File not found: ${filePath}`);
+    }
+    return fs.readFileSync(filePath, 'utf8');
+}
+/**
+ * Write a UTF-8 text file, creating parent directories if needed.
+ */
+function writeFile(filePath, content) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(filePath, content, 'utf8');
+}
+/**
+ * True if a file or directory exists at the given path.
+ */
+function exists(filePath) {
+    return fs.existsSync(filePath);
+}
+/**
+ * Ensure a directory exists, creating it (and parents) if necessary.
+ */
+function ensureDir(dirPath) {
+    if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true });
+    }
+}
+/**
+ * Resolve a path inside the packaged template/pack assets.
+ *
+ * When compiled, this file lives in dist/utils/. The templates/ and packs/
+ * folders ship at the package root, one level above dist/. We walk upward
+ * until we find a directory that contains both, so the CLI works whether it
+ * runs from source (ts-node) or from the published dist build.
+ */
+function assetPath(...segments) {
+    let dir = __dirname;
+    for (let i = 0; i < 6; i++) {
+        if (fs.existsSync(path.join(dir, 'templates')) &&
+            fs.existsSync(path.join(dir, 'packs'))) {
+            return path.join(dir, ...segments);
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            break;
+        }
+        dir = parent;
+    }
+    throw new Error('Could not locate Vibekit assets (templates/ and packs/). ' +
+        'The package may be installed incorrectly.');
+}

package/dist/utils/markers.js

@@ -0,0 +1,132 @@
+"use strict";
+/**
+ * Utilities for parsing, inserting, and removing pack marker blocks of the form:
+ *
+ *   <!-- pack:<name>:start -->
+ *   ...content...
+ *   <!-- pack:<name>:end -->
+ *
+ * These markers live inside AGENTS.md and the packs/*.md source files.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PACKS_PLACEHOLDER = exports.PACK_PLACEHOLDER = void 0;
+exports.packBlockRegex = packBlockRegex;
+exports.anyPackBlockRegex = anyPackBlockRegex;
+exports.listActivePacks = listActivePacks;
+exports.hasPack = hasPack;
+exports.extractBlock = extractBlock;
+exports.removePack = removePack;
+exports.insertPack = insertPack;
+exports.setActivePacksLine = setActivePacksLine;
+exports.PACK_PLACEHOLDER = '{{PACK_BLOCKS_INSERTED_HERE}}';
+exports.PACKS_PLACEHOLDER = '{{PACKS}}';
+const ACTIVE_PACKS_LINE = /^### Active principle packs:.*$/m;
+/**
+ * Build a regex that matches a single pack block (start marker through end
+ * marker, inclusive) for the given pack name.
+ */
+function packBlockRegex(name) {
+    const escaped = escapeRegExp(name);
+    return new RegExp(`<!--\\s*pack:${escaped}:start\\s*-->[\\s\\S]*?<!--\\s*pack:${escaped}:end\\s*-->`, 'm');
+}
+/**
+ * Global regex matching any pack block, capturing the pack name in group 1.
+ */
+function anyPackBlockRegex() {
+    return /<!--\s*pack:([a-zA-Z0-9_-]+):start\s*-->[\s\S]*?<!--\s*pack:\1:end\s*-->/g;
+}
+/**
+ * Return the list of active pack names found in the given content, in order.
+ */
+function listActivePacks(content) {
+    const names = [];
+    const regex = anyPackBlockRegex();
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+        names.push(match[1]);
+    }
+    return names;
+}
+/**
+ * True if the named pack block is present in content.
+ */
+function hasPack(content, name) {
+    return packBlockRegex(name).test(content);
+}
+/**
+ * Extract the marker block for a pack from a packs/*.md source file.
+ * Falls back to the raw (trimmed) file content if no markers are present.
+ */
+function extractBlock(packFileContent, name) {
+    const match = packFileContent.match(packBlockRegex(name));
+    if (match) {
+        return match[0].trim();
+    }
+    return packFileContent.trim();
+}
+/**
+ * Remove a pack block (and surrounding blank lines) from content.
+ */
+function removePack(content, name) {
+    const regex = packBlockRegex(name);
+    if (!regex.test(content)) {
+        return content;
+    }
+    const without = content.replace(regex, '');
+    return collapseBlankLines(without);
+}
+/**
+ * Insert a pack block into AGENTS.md content.
+ *
+ * If other pack blocks already exist, the new block is inserted immediately
+ * after the last existing pack block. Otherwise it replaces the
+ * {{PACK_BLOCKS_INSERTED_HERE}} placeholder, or is appended after the
+ * Verify-before-trust section if the placeholder is gone.
+ */
+function insertPack(content, block) {
+    // If the placeholder still exists (fresh template), replace it.
+    if (content.includes(exports.PACK_PLACEHOLDER)) {
+        return content.replace(exports.PACK_PLACEHOLDER, `${block}\n`);
+    }
+    const activePacks = listLastBlockMatch(content);
+    if (activePacks) {
+        const insertAt = activePacks.index + activePacks.length;
+        return (content.slice(0, insertAt) + `\n\n${block}` + content.slice(insertAt));
+    }
+    // No existing packs and no placeholder: insert after Verify-before-trust.
+    const verifyRegex = /(### Verify-before-trust[\s\S]*?source of truth — not the note\.)/m;
+    const verifyMatch = content.match(verifyRegex);
+    if (verifyMatch && verifyMatch.index !== undefined) {
+        const insertAt = verifyMatch.index + verifyMatch[0].length;
+        return (content.slice(0, insertAt) + `\n\n${block}` + content.slice(insertAt));
+    }
+    // Last resort: append to the end.
+    return `${content.trimEnd()}\n\n${block}\n`;
+}
+/**
+ * Replace (or set) the "Active principle packs" line with the given names.
+ */
+function setActivePacksLine(content, names) {
+    const value = names.length > 0 ? names.join(', ') : '(none)';
+    const line = `### Active principle packs: ${value}`;
+    if (ACTIVE_PACKS_LINE.test(content)) {
+        return content.replace(ACTIVE_PACKS_LINE, line);
+    }
+    return content;
+}
+/** Find the last pack block and return its index and length. */
+function listLastBlockMatch(content) {
+    const regex = anyPackBlockRegex();
+    let match;
+    let last = null;
+    while ((match = regex.exec(content)) !== null) {
+        last = { index: match.index, length: match[0].length };
+    }
+    return last;
+}
+function collapseBlankLines(content) {
+    return content.replace(/\n{3,}/g, '\n\n');
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@govindchaudhary/vibekit",
+  "version": "0.1.1",
+  "description": "Make vibe coding accurate: 3 persistent markdown files (AGENTS.md, CHANGELOG.md, DECISIONS.md) that give any AI coding assistant lean, verifiable context — a lightweight alternative to heavyweight Spec-Driven Development.",
+  "keywords": [
+    "vibe-coding",
+    "ai-coding",
+    "agents-md",
+    "developer-tools",
+    "context",
+    "copilot",
+    "claude",
+    "cursor",
+    "windsurf",
+    "spec-driven-development"
+  ],
+  "license": "MIT",
+  "type": "commonjs",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "vibekit": "dist/cli.js"
+  },
+  "main": "dist/cli.js",
+  "files": [
+    "dist",
+    "templates",
+    "packs",
+    "principles-catalog.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/cli.js"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "prompts": "^2.4.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "@types/prompts": "^2.4.9",
+    "typescript": "^5.4.5"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/packs/core.md

@@ -0,0 +1,7 @@
+<!-- pack:core:start -->
+### Core Principles
+- Single Responsibility: one function/module does one job
+- DRY: don't duplicate logic, extract shared code
+- KISS: simplest solution that meets the requirement — no premature abstraction
+- Fail fast: validate inputs early, raise clear errors instead of failing silently
+<!-- pack:core:end -->

package/packs/data-eng.md

@@ -0,0 +1,8 @@
+<!-- pack:data-eng:start -->
+### Data Engineering Principles
+- Idempotency: re-running a job with the same input must not duplicate side effects
+- Validate at the boundary: enforce schema on ingestion, fail loudly on mismatch — never silently coerce
+- Separate Extract / Transform / Load: don't mix stages in one function
+- Immutable raw data: never mutate ingested source data; transformations always produce new datasets
+- Reproducibility: every run should be deterministic and log enough (row counts, versions, timestamps) to debug without re-running
+<!-- pack:data-eng:end -->

package/packs/dev.md

@@ -0,0 +1,7 @@
+<!-- pack:dev:start -->
+### SOLID Principles
+- Open/Closed: extend behavior with new code; don't modify working code to add a feature
+- Liskov Substitution: a subtype must be usable anywhere its base type is, without surprises
+- Interface Segregation: small focused interfaces beat one large general-purpose one
+- Dependency Inversion: depend on abstractions, not concrete implementations
+<!-- pack:dev:end -->

package/principles-catalog.md

@@ -0,0 +1,83 @@
+# Principles Catalog
+
+> A human-readable menu of the principle packs Vibekit ships with.
+>
+> **This file is pure documentation.** It is copied into your repo for reference
+> only and is **never loaded or referenced by any AI assistant**. The packs that
+> AI actually reads live inside `AGENTS.md`. Use this catalog to decide which
+> packs to add via `vibekit packs add <name>`.
+
+---
+
+## How to read this
+
+Each pack below maps 1:1 to a file in `packs/<name>.md`. When a pack is active,
+its block is inserted into `AGENTS.md` between markers like
+`<!-- pack:<name>:start -->` and `<!-- pack:<name>:end -->`.
+
+To add a pack:
+
+```bash
+vibekit packs add dev
+```
+
+To remove one:
+
+```bash
+vibekit packs remove data-eng
+```
+
+---
+
+## Available packs
+
+### `core` — Core Principles *(included by default)*
+
+Foundational rules that apply to almost any codebase.
+
+- **Single Responsibility** — one function/module does one job
+- **DRY** — don't duplicate logic, extract shared code
+- **KISS** — simplest solution that meets the requirement; no premature abstraction
+- **Fail fast** — validate inputs early, raise clear errors instead of failing silently
+
+### `dev` — SOLID Principles
+
+For general application/software development.
+
+- **Open/Closed** — extend behavior with new code; don't modify working code to add a feature
+- **Liskov Substitution** — a subtype must be usable anywhere its base type is, without surprises
+- **Interface Segregation** — small focused interfaces beat one large general-purpose one
+- **Dependency Inversion** — depend on abstractions, not concrete implementations
+
+### `data-eng` — Data Engineering Principles
+
+For pipelines, ETL/ELT, and analytics engineering.
+
+- **Idempotency** — re-running a job with the same input must not duplicate side effects
+- **Validate at the boundary** — enforce schema on ingestion, fail loudly on mismatch; never silently coerce
+- **Separate Extract / Transform / Load** — don't mix stages in one function
+- **Immutable raw data** — never mutate ingested source data; transformations always produce new datasets
+- **Reproducibility** — every run should be deterministic and log enough (row counts, versions, timestamps) to debug without re-running
+
+---
+
+## Adding your own custom pack
+
+1. Create a new file in `packs/`, e.g. `packs/security.md`.
+2. Wrap its content in start/end markers matching the file name:
+
+   ```markdown
+   <!-- pack:security:start -->
+   ### Security Principles
+   - Least privilege: grant the minimum access required
+   - Never trust client input: validate and sanitize at every boundary
+   <!-- pack:security:end -->
+   ```
+
+3. Activate it:
+
+   ```bash
+   vibekit packs add security
+   ```
+
+The marker name (`security`) must match the file name (`security.md`).

package/templates/AGENTS.md.template

@@ -0,0 +1,22 @@
+# AGENTS.md
+
+> Stable context and coding principles for AI assistants working in this repo.
+> This file is read automatically by most modern AI coding tools. Keep it accurate.
+
+### Active principle packs: {{PACKS}}
+(See principles-catalog.md in repo root for other available packs)
+
+### Verify-before-trust
+Treat CHANGELOG.md and DECISIONS.md as hints, not ground truth. Before relying
+on an entry, confirm the referenced file/function still matches what's described.
+If it doesn't, the current code is the source of truth — not the note.
+
+{{PACK_BLOCKS_INSERTED_HERE}}
+
+### Project Stack
+[Fill in: languages, frameworks, key libraries]
+
+### Conventions
+[Fill in: naming, testing approach, file structure — be specific and verifiable,
+e.g. "2-space indentation" not "clean formatting". Where a rule isn't obvious,
+add a one-line reason, e.g. "Use X instead of Y because Y is deprecated."]

package/templates/CHANGELOG.md.template

@@ -0,0 +1,10 @@
+<!--
+FORMAT: newest entry first. Each entry: exact date (never "yesterday"/"recently"),
+what changed, why, files/functions touched. Mark resolved entries [DONE] —
+the prune command deletes [DONE] entries older than the most recent 5.
+Keep this file under ~10 active entries at all times.
+-->
+
+## Changelog
+
+(no entries yet — run `vibekit log "description"` after your first change)

package/templates/DECISIONS.md.template

@@ -0,0 +1,6 @@
+<!-- Only add entries here for choices a future session would otherwise
+guess wrong or re-debate — architecture/library choices, not routine bug fixes. -->
+
+## Decisions
+
+(no entries yet)