@govindchaudhary/vibekit 0.1.2 → 0.1.4

package/README.md

@@ -43,7 +43,12 @@ Vibe coding — letting an AI assistant drive most of the code while you steer
 npx @govindchaudhary/vibekit init
 ```
 
-Answer **one question** ("What's this project mostly?") and Vibekit creates four files in your current directory:
+Answer **two short questions** and Vibekit is ready:
+
+1. **"What's this project mostly?"** — Dev / Data Engineering / Both / Skip → picks your principle packs
+2. **"Which AI tool(s) do you use?"** — GitHub Copilot / Claude Code / Windsurf / Cursor (multi-select) → creates *only* the mirror files those tools need
+
+That's it. Four context files are created in your current directory:
 
 | File | Purpose | Read by AI? |
 |---|---|---|
@@ -52,7 +57,9 @@ Answer **one question** ("What's this project mostly?") and Vibekit creates four
 | `DECISIONS.md` | Architecture decisions not to re-debate | ✅ Yes — automatically |
 | `principles-catalog.md` | Human menu of available packs | ❌ No — docs only |
 
-Then fill in the `Project Stack` and `Conventions` sections of `AGENTS.md` once. That's it. Every AI session from that point forward has full, accurate context.
+Plus the tool-specific mirror file(s) you selected (see [Tool integration](#tool-integration-no-clutter) below).
+
+Then fill in the `Project Stack` and `Conventions` sections of `AGENTS.md` once. Every AI session from that point forward has full, accurate context.
 
 ---
 
@@ -179,18 +186,43 @@ See [`principles-catalog.md`](./principles-catalog.md) for the full pack menu an
 
 ---
 
+## Tool integration (no clutter)
+
+Different AI assistants look for different filenames. `AGENTS.md` is the modern standard, but some tools still need their own filename:
+
+| Tool | Reads `AGENTS.md` natively? | Needs mirror file |
+|---|---|---|
+| **Cursor** | ✅ Yes | none |
+| **GitHub Copilot** | ⚠️ Setting-dependent — use mirror to be safe | `.github/copilot-instructions.md` |
+| **Claude Code** | ⚠️ Partial | `CLAUDE.md` |
+| **Windsurf** | ❌ No | `.windsurfrules` |
+
+**`vibekit init` only creates the mirror files for tools you actually use** — no orphan files in your repo. The default is GitHub Copilot (most common VS Code setup).
+
+**Add a tool later:**
+```bash
+vibekit sync --claude              # add Claude Code support
+vibekit sync --windsurf            # add Windsurf support
+vibekit sync --copilot --claude    # add multiple at once
+vibekit sync                       # add all three (legacy default)
+```
+
+---
+
 ## CLI reference
 
 | Command | What it does |
 |---|---|
-| `vibekit init` | Scaffold `AGENTS.md`, `CHANGELOG.md`, `DECISIONS.md`, `principles-catalog.md` in one step. |
+| `vibekit init` | Scaffold the 4 context files + auto-create mirror files for the AI tools you pick. Runs once per project. |
 | `vibekit log "<message>"` | Append a dated entry to `CHANGELOG.md` (newest on top, ISO date). |
 | `vibekit prune` | Remove `[DONE]` changelog entries, keeping the 5 most recent resolved ones. |
 | `vibekit packs add <name>` | Insert a pack block into `AGENTS.md` and update the active packs line. |
 | `vibekit packs remove <name>` | Remove a pack block from `AGENTS.md`. |
-| `vibekit sync` | Mirror `AGENTS.md` → `CLAUDE.md`, `.windsurfrules`, `.github/copilot-instructions.md`. |
+| `vibekit sync [--copilot] [--claude] [--windsurf]` | Mirror `AGENTS.md` to the chosen tool files. With no flags, mirrors to all three. |
 
-> **About `vibekit sync`:** Most modern tools (GitHub Copilot, Cursor, Windsurf) now read `AGENTS.md` natively. `sync` is a fallback for tools or older setups that use their own native filenames, or for teams who want all native filenames present simultaneously.
+> **Install vs init — they're different.**
+> `npm install -g @govindchaudhary/vibekit` installs the CLI on your machine (one time per computer).
+> `vibekit init` sets up the context files in a project (one time per project). You need both.
 
 ---
 
@@ -227,8 +259,12 @@ Drops the 4 files into any existing repo without touching your code.
 ## Recommended workflow
 
 ```bash
-# Day 1 — initialize
-npx @govindchaudhary/vibekit init
+# One time per machine
+npm install -g @govindchaudhary/vibekit
+
+# Day 1 of a new project — initialize (auto-creates mirror files for your tools)
+cd my-project
+vibekit init
 # → fill in AGENTS.md: Project Stack + Conventions sections
 
 # Add security if your project has auth/APIs/user data
@@ -238,14 +274,12 @@ vibekit packs add security
 vibekit log "Added rate limiting to /api/auth — middleware/rateLimit.ts"
 vibekit log "Switched from JWT to httpOnly session cookies — security decision"
 
-# When a change is complete, mark it done
-# Edit CHANGELOG.md: add [DONE] to the entry
-
-# Periodically keep the changelog lean
+# When a change is complete, mark it [DONE] in CHANGELOG.md by hand,
+# then keep the file lean:
 vibekit prune
 
-# If you use Claude, Cursor, or Windsurf with their native filenames
-vibekit sync
+# Add a new AI tool later
+vibekit sync --claude
 ```
 
 ---
@@ -267,148 +301,3 @@ Please keep pack principles **specific, verifiable, and actionable** — not vag
 
 [MIT](./LICENSE) © 2026 Vibekit contributors
 
-
-**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

@@ -13,7 +13,7 @@ program
     .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.2');
+    .version('0.1.4');
 program
     .command('init')
     .description('Scaffold AGENTS.md, CHANGELOG.md, DECISIONS.md, and principles-catalog.md in the current directory.')
@@ -52,13 +52,22 @@ packs
 });
 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)();
+    .description('Mirror AGENTS.md to tool-specific files. Use flags to pick which tools ' +
+    '(e.g. --copilot --claude). With no flags, syncs to all three (Copilot, ' +
+    'Claude, Windsurf). `vibekit init` runs sync automatically for the ' +
+    'tools you picked, so this is mainly for adding a new tool later.')
+    .option('--copilot', 'mirror to .github/copilot-instructions.md')
+    .option('--claude', 'mirror to CLAUDE.md')
+    .option('--windsurf', 'mirror to .windsurfrules')
+    .action((opts) => {
+    const picked = [];
+    if (opts.copilot)
+        picked.push('copilot');
+    if (opts.claude)
+        picked.push('claude');
+    if (opts.windsurf)
+        picked.push('windsurf');
+    (0, sync_1.syncCommand)(picked.length > 0 ? picked : sync_1.ALL_TOOLS);
 });
 async function main() {
     try {

package/dist/commands/init.js

@@ -41,6 +41,7 @@ const path = __importStar(require("path"));
 const prompts_1 = __importDefault(require("prompts"));
 const fileio_1 = require("../utils/fileio");
 const markers_1 = require("../utils/markers");
+const sync_1 = require("./sync");
 const KIND_TO_PACKS = {
     dev: ['core', 'dev'],
     data: ['core', 'data-eng'],
@@ -77,6 +78,41 @@ async function initCommand() {
     // Handle abort (Ctrl+C) gracefully.
     const selected = kind ?? 'skip';
     const packs = KIND_TO_PACKS[selected];
+    // Ask which AI tool(s) the user runs. Only those will get mirror files.
+    // GitHub Copilot is the default selection because it's the most common
+    // VS Code setup and Copilot doesn't read AGENTS.md natively yet.
+    const { tools } = await (0, prompts_1.default)({
+        type: 'multiselect',
+        name: 'tools',
+        message: 'Which AI tool(s) do you use? (space to toggle, enter to confirm)',
+        instructions: false,
+        choices: [
+            {
+                title: 'GitHub Copilot',
+                value: 'copilot',
+                selected: true,
+                description: 'creates .github/copilot-instructions.md',
+            },
+            {
+                title: 'Claude Code',
+                value: 'claude',
+                description: 'creates CLAUDE.md',
+            },
+            {
+                title: 'Windsurf',
+                value: 'windsurf',
+                description: 'creates .windsurfrules',
+            },
+            {
+                title: 'Cursor / other (reads AGENTS.md natively)',
+                value: 'none',
+                description: 'no extra file needed',
+            },
+        ],
+    });
+    const selectedTools = Array.isArray(tools)
+        ? tools.filter((t) => sync_1.ALL_TOOLS.includes(t))
+        : [];
     // Build AGENTS.md from the template.
     let agents = (0, fileio_1.readFile)((0, fileio_1.assetPath)('templates', 'AGENTS.md.template'));
     if (selected === 'skip') {
@@ -104,9 +140,20 @@ async function initCommand() {
     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)');
+    // Auto-sync to the tool files the user picked so they don't have to
+    // remember to run `vibekit sync` separately.
+    if (selectedTools.length > 0) {
+        console.log('');
+        (0, sync_1.syncCommand)(selectedTools);
+    }
     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');
+    if (selectedTools.length === 0) {
+        console.log('  3. (Optional) mirror AGENTS.md for older tools:  vibekit sync');
+    }
+    else {
+        console.log('  3. Add more tools later with:  vibekit sync --claude  (or --windsurf, --copilot)');
+    }
 }

package/dist/commands/sync.js

@@ -33,31 +33,43 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALL_TOOLS = void 0;
 exports.syncCommand = syncCommand;
 const path = __importStar(require("path"));
 const fileio_1 = require("../utils/fileio");
+exports.ALL_TOOLS = ['copilot', 'claude', 'windsurf'];
+const TOOL_FILES = {
+    copilot: '.github/copilot-instructions.md',
+    claude: 'CLAUDE.md',
+    windsurf: '.windsurfrules',
+};
+const TOOL_LABELS = {
+    copilot: 'GitHub Copilot',
+    claude: 'Claude Code',
+    windsurf: 'Windsurf',
+};
 /**
  * Mirror AGENTS.md to the filenames used by tools that don't yet read
- * AGENTS.md natively.
+ * AGENTS.md natively. If no tools are specified, syncs to all three
+ * (legacy behavior, preserved for backwards compatibility).
  */
-function syncCommand() {
+function syncCommand(tools = exports.ALL_TOOLS) {
     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.');
     }
+    if (tools.length === 0) {
+        console.log('No tools selected — nothing to sync.');
+        return;
+    }
     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) {
+    console.log('Synced AGENTS.md to:');
+    for (const tool of tools) {
+        const relPath = TOOL_FILES[tool];
+        const target = path.join(cwd, relPath);
+        (0, fileio_1.ensureDir)(path.dirname(target));
         (0, fileio_1.writeFile)(target, content);
+        console.log(`  - ${relPath}  (${TOOL_LABELS[tool]})`);
     }
-    console.log('Synced AGENTS.md to:');
-    console.log('  - CLAUDE.md');
-    console.log('  - .windsurfrules');
-    console.log('  - .github/copilot-instructions.md');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@govindchaudhary/vibekit",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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",

package/templates/AGENTS.md.template

@@ -11,6 +11,24 @@ 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.
 
+### For AI assistants — automation rules
+When you make changes in this repo, you are responsible for keeping these context
+files accurate. Do not wait to be asked. Run these terminal commands yourself:
+
+- After completing any meaningful code change, run:
+  `vibekit log "<one-line summary of what changed and why>"`
+  Be specific. Include the file or function touched. Skip trivial edits (typos, formatting).
+- When you finish a feature or fix that was previously logged, edit that CHANGELOG.md
+  line to insert ` [DONE]` right after the date — e.g. `### 2026-06-28 [DONE] — ...`
+- If CHANGELOG.md has more than 8 active (non-[DONE]) entries, run: `vibekit prune`
+- If you add code that touches auth, encryption, secrets, user input, or DB queries
+  and the `security` pack is not already active, run: `vibekit packs add security`
+- If you make a non-obvious architectural choice (library swap, pattern change,
+  schema decision), append a short entry to DECISIONS.md with the date, the
+  decision, and one sentence of rationale.
+- Never invent file paths, function names, or API shapes. Read the file first
+  to verify before referencing it in a log or decision entry.
+
 {{PACK_BLOCKS_INSERTED_HERE}}
 
 ### Project Stack