@jgiox/goodvibes 1.0.0

package/dist/index.js

@@ -0,0 +1,295 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/commands/init.ts
+import { intro, outro, note, tasks } from "@clack/prompts";
+
+// src/steps/copy-templates.ts
+import { copy } from "fs-extra";
+import { readFile as readFile2 } from "fs/promises";
+import { readdir } from "fs/promises";
+import { existsSync } from "fs";
+import { join, relative } from "path";
+import { fileURLToPath } from "url";
+
+// src/utils/sentinel-merge.ts
+import { outputFile, pathExists } from "fs-extra";
+import { readFile, writeFile } from "fs/promises";
+var SENTINEL_START = "<!-- goodvibes:start -->";
+var SENTINEL_END = "<!-- goodvibes:end -->";
+function extractVersion(block) {
+  const match = block.match(/# goodvibes: v([\d.]+)/);
+  return match ? match[1] : null;
+}
+function versionGte(a, b) {
+  const pa = a.split(".").map((s) => parseInt(s, 10));
+  const pb = b.split(".").map((s) => parseInt(s, 10));
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const va = pa[i] ?? 0;
+    const vb = pb[i] ?? 0;
+    if (va > vb) return true;
+    if (va < vb) return false;
+  }
+  return true;
+}
+function extractSentinelBlock(content) {
+  const start = content.indexOf(SENTINEL_START);
+  const end = content.indexOf(SENTINEL_END);
+  if (start === -1 || end === -1) return "";
+  return content.slice(start, end + SENTINEL_END.length);
+}
+async function mergeClaude(destPath, templateContent) {
+  const templateBlock = extractSentinelBlock(templateContent);
+  if (!await pathExists(destPath)) {
+    await outputFile(destPath, templateContent);
+    return;
+  }
+  const existing = await readFile(destPath, "utf-8");
+  const startIdx = existing.indexOf(SENTINEL_START);
+  if (startIdx === -1) {
+    await writeFile(destPath, existing.trimEnd() + "\n\n" + templateBlock + "\n");
+    return;
+  }
+  const endIdx = existing.indexOf(SENTINEL_END);
+  const existingBlock = existing.slice(startIdx, endIdx + SENTINEL_END.length);
+  const existingVersion = extractVersion(existingBlock);
+  const templateVersion = extractVersion(templateBlock);
+  if (existingVersion && templateVersion && versionGte(existingVersion, templateVersion)) {
+    return;
+  }
+  const before = existing.slice(0, startIdx);
+  const after = existing.slice(endIdx + SENTINEL_END.length);
+  await writeFile(destPath, before + templateBlock + after);
+}
+
+// src/steps/copy-templates.ts
+function resolveTemplatesDir() {
+  const distRelative = fileURLToPath(new URL("../templates", import.meta.url));
+  if (existsSync(distRelative)) return distRelative;
+  return fileURLToPath(new URL("../../../../templates", import.meta.url));
+}
+async function listTemplateFiles(templateDir) {
+  const results = [];
+  async function walk(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(fullPath);
+      } else {
+        results.push(relative(templateDir, fullPath));
+      }
+    }
+  }
+  await walk(templateDir);
+  return results.sort();
+}
+async function copyTemplates(templateDir, destDir, dryRun, minimal) {
+  if (dryRun) {
+    return listTemplateFiles(templateDir);
+  }
+  await copy(templateDir, destDir, {
+    overwrite: false,
+    errorOnExist: false,
+    filter: (src) => {
+      if (src.endsWith("CLAUDE.md")) return false;
+      if (minimal && src.includes(".github/workflows")) return false;
+      if (relative(templateDir, src).includes("..")) return false;
+      return true;
+    }
+  });
+  const claudeSrc = join(templateDir, "CLAUDE.md");
+  const claudeDest = join(destDir, "CLAUDE.md");
+  const templateContent = await readFile2(claudeSrc, "utf-8");
+  await mergeClaude(claudeDest, templateContent);
+  return listTemplateFiles(templateDir);
+}
+
+// src/steps/install-headroom.ts
+import { execa as execa2 } from "execa";
+
+// src/utils/detect-python.ts
+import { execa } from "execa";
+async function detectPython() {
+  for (const cmd of ["python3", "python", "py"]) {
+    try {
+      const { stdout, stderr } = await execa(cmd, ["--version"]);
+      const output = stdout || stderr;
+      const match = output.match(/Python (\d+)\.(\d+)/);
+      if (!match) {
+        continue;
+      }
+      const major2 = parseInt(match[1], 10);
+      const minor = parseInt(match[2], 10);
+      if (major2 > 3) {
+        return cmd;
+      }
+      if (major2 === 3 && minor >= 10) {
+        return cmd;
+      }
+    } catch (e) {
+      if (e.code === "ENOENT") {
+        continue;
+      }
+      continue;
+    }
+  }
+  return null;
+}
+
+// src/steps/install-headroom.ts
+async function installHeadroom(log) {
+  const pythonCmd = await detectPython();
+  if (pythonCmd === null) {
+    log("Python 3.10+ not found \u2014 skipping headroom install. Install Python 3.10+ and run `goodvibes init` again.");
+    return;
+  }
+  log("Note: headroom will download its compression model on first use \u2014 this may take 1\u20133 minutes on a slow connection.");
+  const installers = [
+    { cmd: "uv", args: ["tool", "install", "headroom-ai[all]"] },
+    { cmd: "pipx", args: ["install", "headroom-ai[all]"] },
+    { cmd: pythonCmd, args: ["-m", "pip", "install", "--user", "headroom-ai[all]"] }
+  ];
+  for (const installer of installers) {
+    try {
+      await execa2(installer.cmd, installer.args);
+      return;
+    } catch (e) {
+      if (e.code === "ENOENT") {
+        continue;
+      }
+      const summary = e.message?.split("\n")[0] ?? "unknown error";
+      log(`headroom install failed: ${summary}`);
+      log('You can install headroom manually later: uv tool install "headroom-ai[all]"');
+      return;
+    }
+  }
+  log("No package installer found (uv, pipx, pip). Install Python 3.10+ with uv or pipx and run `goodvibes init` again.");
+}
+
+// src/steps/configure-mcp.ts
+import { execa as execa3 } from "execa";
+async function configureMcp(log) {
+  try {
+    await execa3("headroom", ["mcp", "status"]);
+    log("headroom MCP already configured \u2014 skipping");
+    return;
+  } catch {
+  }
+  try {
+    const list = await execa3("claude", ["mcp", "list"]);
+    if (list.stdout.includes("headroom")) {
+      log("headroom already registered in claude MCP \u2014 skipping");
+      return;
+    }
+    const whichCmd = process.platform === "win32" ? "where" : "which";
+    let absolutePath;
+    try {
+      const pathResult = await execa3(whichCmd, ["headroom"]);
+      absolutePath = pathResult.stdout.trim();
+    } catch {
+      log('headroom binary not found on PATH \u2014 MCP registration skipped. Run `uv tool install "headroom-ai[all]"` then re-run `goodvibes init`.');
+      return;
+    }
+    await execa3("claude", ["mcp", "add", "-s", "user", "headroom", absolutePath]);
+    log("headroom registered as global MCP server");
+    return;
+  } catch (e) {
+    if (e.code === "ENOENT") {
+      log("claude CLI not found \u2014 falling back to headroom mcp install");
+      log("Warning: if you use CLAUDE_CONFIG_DIR, you may need to run `headroom mcp install` manually");
+      try {
+        await execa3("headroom", ["mcp", "install"]);
+        return;
+      } catch (fallbackErr) {
+        if (fallbackErr.code === "ENOENT") {
+          log("headroom binary not found \u2014 MCP registration skipped. Install headroom and run `headroom mcp install` manually.");
+          return;
+        }
+        throw fallbackErr;
+      }
+    }
+    throw e;
+  }
+}
+
+// src/commands/init.ts
+function registerInitCommand(program2) {
+  program2.command("init").description("Bootstrap a project with goodvibes configuration").option("--dry-run", "Preview files without writing to disk").option("--minimal", "Skip headroom install and CI workflows").action(async (options) => {
+    const dryRun = options.dryRun ?? false;
+    const minimal = options.minimal ?? false;
+    const cwd = process.cwd();
+    const templateDir = resolveTemplatesDir();
+    intro("goodvibes init");
+    if (dryRun) {
+      const files = await listTemplateFiles(templateDir);
+      note(files.map((f) => `  Would write: ${f}`).join("\n"), "Dry run \u2014 no files written");
+      note(
+        [
+          "1. Open this project in Claude Code",
+          "2. Run /plugin marketplace add DietrichGebert/ponytail",
+          "3. Start coding \u2014 CLAUDE.md rules are already active"
+        ].join("\n"),
+        "Next steps"
+      );
+      outro("Run without --dry-run to apply these changes.");
+      return;
+    }
+    const createdFiles = [];
+    const taskList = [
+      {
+        title: "Copying template files",
+        task: async (message) => {
+          const files = await copyTemplates(templateDir, cwd, false, minimal);
+          createdFiles.push(...files);
+          return `Copied ${files.length} files`;
+        }
+      }
+    ];
+    if (!minimal) {
+      taskList.push(
+        {
+          title: "Installing headroom",
+          task: async (message) => {
+            await installHeadroom((msg) => message(msg));
+            return "headroom ready";
+          }
+        },
+        {
+          title: "Configuring headroom MCP",
+          task: async (message) => {
+            await configureMcp((msg) => message(msg));
+            return "MCP server registered";
+          }
+        }
+      );
+    }
+    await tasks(taskList);
+    note(createdFiles.join("\n"), "Files created");
+    const nextSteps = [
+      "1. Open this project in Claude Code",
+      "2. Run /plugin marketplace add DietrichGebert/ponytail",
+      "3. Start coding \u2014 CLAUDE.md rules are already active"
+    ].join("\n");
+    note(nextSteps, "Next steps");
+    outro("You're all set!");
+  });
+}
+
+// src/index.ts
+var [major] = process.version.replace("v", "").split(".").map(Number);
+if (major < 20) {
+  process.stderr.write(
+    `goodvibes requires Node.js 20 or higher.
+You are running Node.js ${process.version}.
+Install the latest LTS from https://nodejs.org
+`
+  );
+  process.exit(1);
+}
+var program = new Command();
+program.name("goodvibes").version("1.0.0").description("One-command bootstrap for vibe coding projects");
+registerInitCommand(program);
+await program.parseAsync(process.argv);

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@jgiox/goodvibes",
+  "version": "1.0.0",
+  "description": "One-command bootstrap for vibe coding projects",
+  "type": "module",
+  "bin": {
+    "goodvibes": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jgiox/goodvibes"
+  },
+  "keywords": [
+    "scaffold",
+    "vibe-coding",
+    "claude",
+    "llm",
+    "starter-kit",
+    "cli"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "Apache-2.0",
+  "scripts": {
+    "prebuild": "node -e \"const{cpSync}=require('fs');cpSync('../../templates','./templates',{recursive:true,force:true})\"",
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "commander": "^13",
+    "@clack/prompts": "^0.9",
+    "fs-extra": "^11",
+    "execa": "^9"
+  },
+  "devDependencies": {
+    "tsup": "^8",
+    "typescript": "^5.5",
+    "@types/node": "^20",
+    "vitest": "^2"
+  }
+}

package/templates/.claude/skills/cavecrew/README.md

@@ -0,0 +1,41 @@
+# cavecrew
+
+Decision guide. When to delegate to caveman subagents instead of doing the work inline.
+
+## What it does
+
+Tells the main thread when to spawn a caveman-style subagent versus the vanilla equivalent. The win: subagent tool-results inject back into main context verbatim, and caveman output is roughly 1/3 the size of vanilla prose. Across 20 delegations in one session, that is the difference between context exhaustion and finishing the task.
+
+Three subagents:
+
+| Subagent | Job | Use when |
+|----------|-----|----------|
+| `cavecrew-investigator` | Locate code (read-only) | "Where is X defined / what calls Y / list uses of Z" |
+| `cavecrew-builder` | Surgical edit, 1-2 files | Scope is obvious, ≤2 files. Refuses 3+ file scope. |
+| `cavecrew-reviewer` | Diff/file review | One-line findings with severity emoji |
+
+Use vanilla `Explore` or `Code Reviewer` when you want prose, architecture commentary, or rationale. Use main thread directly for one-line answers and 3+ file refactors.
+
+This skill is a decision guide, not a slash command. It activates when the conversation mentions delegation.
+
+## How to invoke
+
+Triggers on phrases like "delegate to subagent", "use cavecrew", "spawn investigator", "save context", "compressed agent output".
+
+## Example chaining
+
+Locate → fix → verify (most common):
+
+1. `cavecrew-investigator` returns site list (`path:line — symbol — note`)
+2. Main thread picks 1-2 sites, hands paths to `cavecrew-builder`
+3. `cavecrew-reviewer` audits the resulting diff
+
+Parallel scout: spawn 2-3 `cavecrew-investigator` calls in one message with different angles (defs, callers, tests). Aggregate in main.
+
+## See also
+
+- [`SKILL.md`](./SKILL.md) — full decision matrix and output contracts
+- [`agents/cavecrew-investigator.md`](../../agents/cavecrew-investigator.md)
+- [`agents/cavecrew-builder.md`](../../agents/cavecrew-builder.md)
+- [`agents/cavecrew-reviewer.md`](../../agents/cavecrew-reviewer.md)
+- [Caveman README](../../README.md) — repo overview

package/templates/.claude/skills/cavecrew/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: cavecrew
+description: >
+  Decision guide for delegating to caveman-style subagents. Tells the main
+  thread WHEN to spawn `cavecrew-investigator` (locate code), `cavecrew-builder`
+  (1-2 file edit), or `cavecrew-reviewer` (diff review) instead of doing the
+  work inline or using vanilla `Explore`. Subagent output is caveman-compressed
+  so the tool-result injected back into main context is ~60% smaller — main
+  context lasts longer across long sessions.
+  Trigger: "delegate to subagent", "use cavecrew", "spawn investigator/builder/reviewer",
+  "save context", "compressed agent output".
+---
+
+Cavecrew = three subagent presets that emit caveman output. Same job as Anthropic defaults (`Explore`, edit-style agents, reviewer); difference is the tool-result they return is compressed, so main context shrinks per delegation.
+
+## When to use cavecrew vs alternatives
+
+| Task | Use |
+|---|---|
+| "Where is X defined / what calls Y / list uses of Z" | `cavecrew-investigator` |
+| Same but you also want suggestions/architecture commentary | `Explore` (vanilla) |
+| Surgical edit, ≤2 files, scope obvious | `cavecrew-builder` |
+| New feature / 3+ files / cross-cutting refactor | Main thread or `feature-dev:code-architect` |
+| Review diff, branch, or file for bugs | `cavecrew-reviewer` |
+| Deep code review with rationale + alternatives | `Code Reviewer` (vanilla) |
+| One-line answer you already know | Main thread, no subagent |
+
+Rule of thumb: **if you'd want the subagent's output in 1/3 the tokens, pick cavecrew. If you'd want prose, pick vanilla.**
+
+## Why this exists (the real win)
+
+Subagent tool results get injected into main context verbatim. A vanilla `Explore` that returns 2k tokens of prose costs 2k tokens of main-context budget every time. The same finding from `cavecrew-investigator` returns ~700 tokens. Across 20 delegations in one session that's the difference between context exhaustion and finishing the task.
+
+## Output contracts
+
+What main thread can rely on per agent:
+
+**`cavecrew-investigator`**
+```
+<Header>:
+- path:line — `symbol` — short note
+totals: <counts>.
+```
+Or `No match.` Always file-path-first, line-number-attached, backticked symbols. Safe to grep with `path:\d+`.
+
+**`cavecrew-builder`**
+```
+<path:line-range> — <change ≤10 words>.
+verified: <re-read OK | mismatch @ path:line>.
+```
+Or one of: `too-big.` / `needs-confirm.` / `ambiguous.` / `regressed.` (terminal first token).
+
+**`cavecrew-reviewer`**
+```
+path:line: <emoji> <severity>: <problem>. <fix>.
+totals: N🔴 N🟡 N🔵 N❓
+```
+Or `No issues.` Findings sorted file → line ascending.
+
+## Chaining patterns
+
+**Locate → fix → verify** (most common):
+1. `cavecrew-investigator` returns site list.
+2. Main thread picks 1-2 sites, hands paths to `cavecrew-builder`.
+3. `cavecrew-reviewer` audits the diff.
+
+**Parallel scout** (when investigation is broad):
+Spawn 2-3 `cavecrew-investigator` calls in one message (different angles: defs vs callers vs tests). Aggregate in main thread.
+
+**Single-shot edit** (when site is already known):
+Skip investigator. Hand exact path:line to `cavecrew-builder` directly.
+
+## What NOT to do
+
+- Don't use `cavecrew-builder` when you don't already know the file. Spawn investigator first or main thread will eat tokens passing context.
+- Don't chain `cavecrew-investigator → cavecrew-builder` for a 5-file refactor. Builder will return `too-big.` and you'll have wasted a turn.
+- Don't ask `cavecrew-reviewer` for "general feedback" — it returns findings only, no architecture opinions. Use `Code Reviewer` for that.
+- Don't expect prose. Cavecrew output is structured, sometimes terse to the point of cryptic. If a human will read it directly, paraphrase.
+
+## Auto-clarity (inherited)
+
+Subagents drop caveman → normal English for security warnings, irreversible-action confirmations, and any output where fragment ambiguity could be misread. Resume caveman after.

package/templates/.claude/skills/caveman/README.md

@@ -0,0 +1,48 @@
+# caveman
+
+Talk like smart caveman. Same brain, fewer tokens.
+
+## What it does
+
+Compress every model response to caveman-style prose. Drops articles, filler, pleasantries, and hedging. Keeps every technical detail, code block, error string, and symbol exact. Cuts ~65-75% of output tokens with full accuracy preserved. Mode persists for the whole session until changed or stopped.
+
+Six intensity levels:
+
+| Level | What change |
+|-------|-------------|
+| `lite` | Drop filler/hedging. Sentences stay full. Professional but tight. |
+| `full` | Default. Drop articles, fragments OK, short synonyms. |
+| `ultra` | Bare fragments. Abbreviations (DB, auth, fn). Arrows for causality. |
+| `wenyan-lite` | Classical Chinese register, light compression. |
+| `wenyan-full` | Maximum 文言文. 80-90% character reduction. |
+| `wenyan-ultra` | Extreme classical compression. |
+
+Auto-clarity rule: caveman drops to normal prose for security warnings, irreversible-action confirmations, multi-step sequences where fragment ambiguity risks misread, and when user repeats a question. Resumes after the clear part.
+
+## How to invoke
+
+```
+/caveman              # full mode (default)
+/caveman lite         # lighter compression
+/caveman ultra        # extreme compression
+/caveman wenyan       # classical Chinese
+stop caveman          # back to normal prose
+```
+
+## Example output
+
+Question: "Why does my React component re-render?"
+
+Normal prose:
+> Your component re-renders because you create a new object reference each render. Wrapping it in `useMemo` will fix the issue.
+
+Caveman (full):
+> New object ref each render. Inline object prop = new ref = re-render. Wrap in `useMemo`.
+
+Caveman (ultra):
+> Inline obj prop → new ref → re-render. `useMemo`.
+
+## See also
+
+- [`SKILL.md`](./SKILL.md) — full LLM-facing instructions
+- [Caveman README](../../README.md) — repo overview, install, benchmarks

package/templates/.claude/skills/caveman/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: caveman
+description: >
+  Ultra-compressed communication mode. Cuts token usage ~75% by speaking like caveman
+  while keeping full technical accuracy. Supports intensity levels: lite, full (default), ultra,
+  wenyan-lite, wenyan-full, wenyan-ultra.
+  Use when user says "caveman mode", "talk like caveman", "use caveman", "less tokens",
+  "be brief", or invokes /caveman. Also auto-triggers when token efficiency is requested.
+---
+
+Respond terse like smart caveman. All technical substance stay. Only fluff die.
+
+## Persistence
+
+ACTIVE EVERY RESPONSE. No revert after many turns. No filler drift. Still active if unsure. Off only: "stop caveman" / "normal mode".
+
+Default: **full**. Switch: `/caveman lite|full|ultra`.
+
+## Rules
+
+Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). No tool-call narration, no decorative tables/emoji, no dumping long raw error logs unless asked — quote shortest decisive line. Standard well-known tech acronyms OK (DB/API/HTTP); never invent new abbreviations reader can't decode. Technical terms exact. Code blocks unchanged. Errors quoted exact.
+
+Preserve user's dominant language. User write Portuguese → reply Portuguese caveman. User write Spanish → reply Spanish caveman. Compress the style, not the language. No forced English openings or status phrases. ALWAYS keep technical terms, code, API names, CLI commands, commit-type keywords (feat/fix/...), and exact error strings verbatim — unless user explicitly ask for translation.
+
+No self-reference. Never name or announce the style. No "caveman mode on", "me caveman think", no third-person caveman tags. Output caveman-only — never normal answer plus "Caveman:" recap. Exception: user explicitly ask what the mode is.
+
+Pattern: `[thing] [action] [reason]. [next step].`
+
+Not: "Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by..."
+Yes: "Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"
+
+## Intensity
+
+| Level | What change |
+|-------|------------|
+| **lite** | No filler/hedging. Keep articles + full sentences. Professional but tight |
+| **full** | Drop articles, fragments OK, short synonyms. Classic caveman. No tool-call narration, no decorative tables/emoji, no long raw error-log dumps unless asked. Standard acronyms OK; no invented abbreviations |
+| **ultra** | Abbreviate prose words (DB/auth/config/req/res/fn/impl) — prose words only, never real code symbols/function names. Strip conjunctions, arrows for causality (X → Y), one word when one word enough. Code symbols, function names, API names, error strings: never abbreviate |
+| **wenyan-lite** | Semi-classical. Drop filler/hedging but keep grammar structure, classical register |
+| **wenyan-full** | Maximum classical terseness. Fully 文言文. 80-90% character reduction. Classical sentence patterns, verbs precede objects, subjects often omitted, classical particles (之/乃/為/其) |
+| **wenyan-ultra** | Extreme abbreviation while keeping classical Chinese feel. Maximum compression, ultra terse |
+
+Example — "Why React component re-render?"
+- lite: "Your component re-renders because you create a new object reference each render. Wrap it in `useMemo`."
+- full: "New object ref each render. Inline object prop = new ref = re-render. Wrap in `useMemo`."
+- ultra: "Inline obj prop → new ref → re-render. `useMemo`."
+- wenyan-lite: "組件頻重繪，以每繪新生對象參照故。以 useMemo 包之。"
+- wenyan-full: "每繪新生對象參照，故重繪；以 useMemo 包之則免。"
+- wenyan-ultra: "新參照→重繪。useMemo Wrap。"
+
+Example — "Explain database connection pooling."
+- lite: "Connection pooling reuses open connections instead of creating new ones per request. Avoids repeated handshake overhead."
+- full: "Pool reuse open DB connections. No new connection per request. Skip handshake overhead."
+- ultra: "Pool = reuse DB conn. Skip handshake → fast under load."
+- wenyan-full: "池reuse open connection。不每req新開。skip handshake overhead。"
+- wenyan-ultra: "池reuse conn。skip handshake → fast。"
+
+## Auto-Clarity
+
+Drop caveman when:
+- Security warnings
+- Irreversible action confirmations
+- Multi-step sequences where fragment order or omitted conjunctions risk misread
+- Compression itself creates technical ambiguity (e.g., `"migrate table drop column backup first"` — order unclear without articles/conjunctions)
+- User asks to clarify or repeats question
+
+Resume caveman after clear part done.
+
+Example — destructive op:
+> **Warning:** This will permanently delete all rows in the `users` table and cannot be undone.
+> ```sql
+> DROP TABLE users;
+> ```
+> Caveman resume. Verify backup exist first.
+
+## Boundaries
+
+Code/commits/PRs: write normal. "stop caveman" or "normal mode": revert. Level persist until changed or session end.

package/templates/.claude/skills/caveman-commit/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: caveman-commit
+description: >
+  Ultra-compressed commit message generator. Cuts noise from commit messages while preserving
+  intent and reasoning. Conventional Commits format. Subject ≤50 chars, body only when "why"
+  isn't obvious. Use when user says "write a commit", "commit message", "generate commit",
+  "/commit", or invokes /caveman-commit. Auto-triggers when staging changes.
+---
+
+Write commit messages terse and exact. Conventional Commits format. No fluff. Why over what.
+
+## Rules
+
+**Subject line:**
+- `<type>(<scope>): <imperative summary>` — `<scope>` optional
+- Types: `feat`, `fix`, `refactor`, `perf`, `docs`, `test`, `chore`, `build`, `ci`, `style`, `revert`
+- Imperative mood: "add", "fix", "remove" — not "added", "adds", "adding"
+- ≤50 chars when possible, hard cap 72
+- No trailing period
+- Match project convention for capitalization after the colon
+
+**Body (only if needed):**
+- Skip entirely when subject is self-explanatory
+- Add body only for: non-obvious *why*, breaking changes, migration notes, linked issues
+- Wrap at 72 chars
+- Bullets `-` not `*`
+- Reference issues/PRs at end: `Closes #42`, `Refs #17`
+
+**What NEVER goes in:**
+- "This commit does X", "I", "we", "now", "currently" — the diff says what
+- "As requested by..." — use Co-authored-by trailer
+- "Generated with Claude Code" or any AI attribution — unless the user's own rule requires an `Assisted-by`/AI-attribution trailer, then add it as a trailer
+- Emoji (unless project convention requires)
+- Restating the file name when scope already says it
+
+## Examples
+
+Diff: new endpoint for user profile with body explaining the why
+- ❌ "feat: add a new endpoint to get user profile information from the database"
+- ✅
+  ```
+  feat(api): add GET /users/:id/profile
+
+  Mobile client needs profile data without the full user payload
+  to reduce LTE bandwidth on cold-launch screens.
+
+  Closes #128
+  ```
+
+Diff: breaking API change
+- ✅
+  ```
+  feat(api)!: rename /v1/orders to /v1/checkout
+
+  BREAKING CHANGE: clients on /v1/orders must migrate to /v1/checkout
+  before 2026-06-01. Old route returns 410 after that date.
+  ```
+
+## Auto-Clarity
+
+Always include body for: breaking changes, security fixes, data migrations, anything reverting a prior commit. Never compress these into subject-only — future debuggers need the context.
+
+## Boundaries
+
+Only generates the commit message. Does not run `git commit`, does not stage files, does not amend. Output the message as a code block ready to paste. "stop caveman-commit" or "normal mode": revert to verbose commit style.