clud-bug 0.4.1 → 0.5.1

package/README.md

@@ -28,12 +28,14 @@ The naturalist arrives at your repo, surveys the habitat, and assembles a field
 
 1. **Surveys habitat.** Reads `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, etc., to learn what your stack is.
 2. **Consults [skills.sh](https://skills.sh).** Pulls review skills relevant to your dependencies (e.g. a Next.js project gets Next.js review specimens).
-3. **Pins three baseline specimens** that enforce review discipline regardless of stack:
+3. **Pins baseline specimens** that enforce review discipline regardless of stack:
    - `critical-issues-only` — flag bugs, security, perf only. Skip nits.
    - `evidence-based-review` — every claim must quote the line being criticized.
    - `respect-existing-conventions` — don't suggest fights with the codebase's patterns.
+   - `clud-bug-collaboration` — guidance for any other Claude Code agents working in your repo: how to coexist with bot review threads, how to read the gate, why workflow self-mods break the action, etc.
 4. **Writes** the chosen specimens to `.claude/skills/<name>/SKILL.md` (Claude Code auto-loads them in the GitHub Action).
 5. **Drafts the field kit** at `.github/workflows/clud-bug-review.yml` with your project description filled in and the right permissions/tool allowlist for `gh pr comment` to actually post.
+6. **Briefs other agents** by adding a `<!-- clud-bug-start -->` block to `AGENTS.md` (creating it if missing — it's the cross-tool canonical), and idempotently to `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`, `.cursorrules`, `.windsurfrules`, `.clinerules`, `.continuerules`, and `.cursor/rules/*.md` where they already exist. Re-runs replace the prior block in place. Files you didn't already have are left uncreated — no proliferating stubs.
 
 ## CLI options
 

package/bin/clud-bug.js

@@ -15,6 +15,7 @@ import {
 import { computeAuditFileSet, renderAuditHeader } from '../lib/audit.js';
 import { runUpdate } from '../lib/update.js';
 import { getPendingWorkflowEdits, makeBranchName, git as gitCmd } from '../lib/edit-workflow.js';
+import { applyToRepo as applyAgentDocs } from '../lib/agents-md.js';
 
 const PKG_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const TEMPLATES = join(PKG_ROOT, 'templates');
@@ -107,7 +108,13 @@ async function runInit(args) {
   log(`    search terms:     ${signals.searchTerms.join(', ') || '(none)'}`);
 
   const baseline = await loadBaseline(BASELINE_DIR);
-  log(`    baseline kit:     ${baseline.length} specimens`);
+  const fromAgentSkills = baseline.filter((s) => s._source === 'agent-skills').length;
+  const sourceLabel = baseline.length === 0
+    ? ''
+    : fromAgentSkills === baseline.length ? ' (from thrillmot/agent-skills)'
+    : fromAgentSkills === 0               ? ' (bundled fallback)'
+                                          : ` (${fromAgentSkills} from agent-skills, ${baseline.length - fromAgentSkills} bundled)`;
+  log(`    baseline kit:     ${baseline.length} specimens${sourceLabel}`);
 
   let curated = [];
   let searched = [];
@@ -198,9 +205,34 @@ async function runInit(args) {
   }
   await writeManifest(skillsDirPath, manifest);
 
+  // Tell other agents what's installed and how to coexist with the bot.
+  // Idempotent — re-runs replace the prior block in place. AGENTS.md is the
+  // canonical home (cross-tool); CLAUDE.md / GEMINI.md / Cursor / Windsurf
+  // / Cline / Continue rules files get the same block appended IF they
+  // already exist (we don't proliferate stubs the user didn't ask for).
+  log('  briefing other agents (AGENTS.md / CLAUDE.md)...');
+  // Pass `=== true` (not `!== false`) so the rendered block matches the
+  // workflow's gate predicate exactly. A v0.3 advisory upgrade where
+  // strictMode is undefined renders "off" — which is what the workflow
+  // actually does on that manifest.
+  const agentDocs = await applyAgentDocs(cwd, {
+    version: manifest.lastUpdateVersion,
+    strictMode: manifest.strictMode === true,
+  });
+  for (const p of agentDocs.created) log(`    created ${p}`);
+  for (const p of agentDocs.touched) log(`    updated ${p}`);
+
   if (args.commit) {
     log('  committing...');
-    spawnSync('git', ['add', '.claude', '.github/workflows/clud-bug-review.yml', '.github/workflows/clud-bug-audit.yml', '.github/workflows/clud-bug-self-update.yml'], { cwd, stdio: 'inherit' });
+    const toAdd = [
+      '.claude',
+      '.github/workflows/clud-bug-review.yml',
+      '.github/workflows/clud-bug-audit.yml',
+      '.github/workflows/clud-bug-self-update.yml',
+      ...agentDocs.created,
+      ...agentDocs.touched,
+    ];
+    spawnSync('git', ['add', ...toAdd], { cwd, stdio: 'inherit' });
     spawnSync('git', ['commit', '-m', 'Add clud-bug 🐛 — a field guide to specimens crawling your code'], { cwd, stdio: 'inherit' });
   }
 

package/lib/agents-md.js

@@ -0,0 +1,183 @@
+import { readFile, writeFile, stat, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+// Manages a clud-bug-owned section inside AGENTS.md / CLAUDE.md and adjacent
+// agent-instruction files. Mirrors the well-established `<!-- logmind-start -->`
+// pattern: a marked block that other agents can read for collaboration rules,
+// idempotently rewritten on each `clud-bug init` so the content stays current.
+
+const START_MARKER = '<!-- clud-bug-start -->';
+const END_MARKER   = '<!-- clud-bug-end -->';
+const BLOCK_VERSION = 'v1';
+
+// Files we'll touch when present, plus files we'll create if missing.
+// AGENTS.md is the cross-tool canonical (logmind made it canonical too).
+// CLAUDE.md, GEMINI.md, .cursorrules, .windsurfrules etc. are tool-specific
+// stubs/instructions; we append the same block where they exist but don't
+// create them (logmind already creates the ones it knows about).
+const ALWAYS_TOUCH = ['AGENTS.md'];                         // create if missing
+const TOUCH_IF_PRESENT = [
+  'CLAUDE.md',
+  'GEMINI.md',
+  '.github/copilot-instructions.md',
+  '.cursorrules',
+  '.windsurfrules',
+  '.clinerules',
+  '.continuerules',
+];
+
+// Render the clud-bug block. Bundled here rather than in a template file so
+// updates ship with the CLI itself.
+//
+// `strictMode` MUST match the workflow's gate predicate exactly so the block
+// can't lie about repo state. The workflow at `templates/workflow*.yml.tmpl`
+// reads the manifest with `JSON.parse(s).strictMode === true` — meaning the
+// gate fires ONLY on an explicit `true`, and anything else (missing field,
+// `false`, `null`) is advisory. Mirror that here: render "on" only when the
+// caller explicitly passes `true`. Anything else is "off".
+//
+// Why this matters: a v0.3-era install (no `strictMode` field, `lastUpdate`
+// set) is a documented advisory upgrade path — `clud-bug init` deliberately
+// preserves that state. If the block rendered "on" for that case, other
+// agents reading AGENTS.md would get a wrong model of the gate.
+export function renderBlock({ version, strictMode } = {}) {
+  const versionLine = version ? `_Installed at clud-bug v${version}._` : '';
+  const strictNote = strictMode === true
+    ? 'Strict mode is **on** in this repo (workflow check fails on critical findings).'
+    : 'Strict mode is **off** in this repo (advisory only).';
+  return `${START_MARKER}
+<!-- clud-bug-block-version: ${BLOCK_VERSION} -->
+## clud-bug — Claude PR review
+
+This repository uses [clud-bug](https://cludbug.dev) to review pull requests
+automatically. Three things matter when other agents (or future-you) work
+in this repo:
+
+### When you push fixes addressing prior Clud Bug review threads
+
+The bot resolves its own prior review threads on the next pass when it can
+verify the fix in the diff. You don't need to manually resolve threads it
+opened — push the fix, wait ~2 minutes, and check the PR. If a thread it
+left isn't auto-resolved after a fix, the bot judged the issue still open;
+read its latest review comment for what it's still flagging.
+
+### Strict mode
+
+${strictNote} Toggle by editing \`.claude/skills/.clud-bug.json\`:
+
+\`\`\`json
+{ "strictMode": true | false, ... }
+\`\`\`
+
+The setting is read from the **base ref** of any open PR, so PRs cannot
+disable strict mode on themselves. Changes take effect on PRs opened after
+they merge to the base branch.
+
+### Where the skills live
+
+Project-aware review rules live in \`.claude/skills/<name>/SKILL.md\`. A
+small baseline kit ships with every install — see
+\`.claude/skills/.clud-bug.json\` for the current set. Add more via
+\`clud-bug add <source/name>\` (from skills.sh) or by dropping your own
+\`.md\` files there. They auto-load into the reviewer.
+
+### Editing the workflow
+
+Anthropic's \`claude-code-action\` refuses to run on PRs that modify its own
+workflow file. Use \`clud-bug edit-workflow\` to bundle workflow tweaks into
+their own isolated PR — see [README](https://github.com/thrillmot/clud-bug#when-you-edit-the-workflow).
+
+${versionLine}
+${END_MARKER}`;
+}
+
+// Replace an existing clud-bug block in `content`, OR append if absent.
+// Idempotent: running multiple times leaves a single block.
+export function upsertBlock(content, block) {
+  const startRe = new RegExp(escapeRe(START_MARKER));
+  const endRe   = new RegExp(escapeRe(END_MARKER));
+  if (startRe.test(content) && endRe.test(content)) {
+    // Replace from START_MARKER through END_MARKER (greedy multi-line).
+    const re = new RegExp(`${escapeRe(START_MARKER)}[\\s\\S]*?${escapeRe(END_MARKER)}`);
+    return content.replace(re, block);
+  }
+  // Append with a separating blank line, no trailing newline duplication.
+  const sep = content.endsWith('\n') ? '\n' : '\n\n';
+  return `${content}${sep}${block}\n`;
+}
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// Touches all relevant agent-instruction files in `cwd`.
+// Creates AGENTS.md if it doesn't exist (it's the canonical home).
+// Updates other files only if they already exist (don't proliferate stubs;
+// logmind or the user owns those creation decisions).
+//
+// Returns { touched: string[], created: string[] } for the caller to log.
+export async function applyToRepo(cwd, blockOpts = {}) {
+  const block = renderBlock(blockOpts);
+  const touched = [];
+  const created = [];
+
+  for (const path of ALWAYS_TOUCH) {
+    const full = join(cwd, path);
+    const existed = await fileExists(full);
+    const prior = existed ? await readFile(full, 'utf8') : seedFile(path);
+    const next = upsertBlock(prior, block);
+    if (next !== prior) {
+      await writeFile(full, next);
+      (existed ? touched : created).push(path);
+    }
+  }
+
+  for (const path of TOUCH_IF_PRESENT) {
+    const full = join(cwd, path);
+    if (!(await fileExists(full))) continue;
+    const prior = await readFile(full, 'utf8');
+    const next = upsertBlock(prior, block);
+    if (next !== prior) {
+      await writeFile(full, next);
+      touched.push(path);
+    }
+  }
+
+  // .cursor/rules/*.md — append to every file that exists.
+  const cursorRulesDir = join(cwd, '.cursor', 'rules');
+  if (await fileExists(cursorRulesDir)) {
+    let entries = [];
+    try { entries = await readdir(cursorRulesDir); } catch {}
+    for (const name of entries) {
+      if (!name.endsWith('.md')) continue;
+      const full = join(cursorRulesDir, name);
+      const prior = await readFile(full, 'utf8');
+      const next = upsertBlock(prior, block);
+      if (next !== prior) {
+        await writeFile(full, next);
+        touched.push(`.cursor/rules/${name}`);
+      }
+    }
+  }
+
+  return { touched, created };
+}
+
+function seedFile(name) {
+  // When AGENTS.md doesn't exist (no logmind, no prior tooling), seed with a
+  // minimal canonical header so the clud-bug block has context.
+  if (name === 'AGENTS.md') {
+    return `# AGENTS.md
+
+This file is the canonical instruction file for AI coding agents working in
+this repository. Tools that understand AGENTS.md (Cursor, Codex, Windsurf,
+Claude Code, Cline, Continue, Aider, ...) read it directly.
+
+`;
+  }
+  return '';
+}
+
+async function fileExists(path) {
+  try { await stat(path); return true; } catch { return false; }
+}

package/lib/skills.js

@@ -1,11 +1,26 @@
 import { mkdir, writeFile, readdir, readFile, rm, stat } from 'node:fs/promises';
 import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
 
 const API_BASE = 'https://skills.sh/api/v1';
 const MAX_SKILLS = 8;
 const MANIFEST_FILE = '.clud-bug.json';
 const MANIFEST_VERSION = 1;
 
+// Canonical home for clud-bug's baseline skills.
+// PINNED TO A COMMIT SHA, NOT `main`. This re-couples the trust boundary
+// to clud-bug releases: a compromised commit on agent-skills@main cannot
+// silently land in users' Claude review skills mid-cycle. To roll new
+// skill content, bump BASELINE_SKILLS_REF below in the same clud-bug PR
+// that ships the corresponding bundled fallback update.
+// See thrillmot/agent-skills — skills.sh `skills/<name>/SKILL.md` layout.
+const BASELINE_SKILLS_REF = '977e439ec861860351239ed89dd56edcd48cbf6b';
+const AGENT_SKILLS_BASE = process.env.CLUD_BUG_AGENT_SKILLS_BASE
+  ?? `https://raw.githubusercontent.com/thrillmot/agent-skills/${BASELINE_SKILLS_REF}/skills`;
+const SKILL_FETCH_TIMEOUT_MS = 5000;
+const SKILL_CACHE_TTL_MS = 24 * 60 * 60 * 1000;   // 24h
+
 export class SkillsClient {
   constructor({ fetch = globalThis.fetch, base, userAgent = 'clud-bug' } = {}) {
     this.fetch = fetch;
@@ -78,7 +93,34 @@ export function rankAndCap(curated, searched, baseline, cap = MAX_SKILLS) {
   return out;
 }
 
-export async function loadBaseline(baselineDir) {
+// Loads the baseline skills, preferring the pinned thrillmot/agent-skills
+// commit and falling back to the bundled npm-package copy on any fetch failure.
+// Returns the same shape as before, plus a `_source` of either 'agent-skills'
+// or 'bundled' so the CLI can report which path was used.
+//
+// Options:
+//   - fetch     — injectable for tests (defaults to globalThis.fetch)
+//   - cacheDir  — where to cache fetched SKILL.md files (defaults to
+//                 ~/.cache/clud-bug/skills/, skipped if null)
+export async function loadBaseline(baselineDir, opts = {}) {
+  const fetchImpl = opts.fetch ?? globalThis.fetch;
+  const cacheDir = opts.cacheDir === null ? null
+    : (opts.cacheDir ?? join(homedir(), '.cache', 'clud-bug', 'skills'));
+
+  // First, enumerate the bundled baseline skills (source of truth for which
+  // names exist). Then fetch each in parallel — sequential awaits would
+  // stack timeouts (3 baselines × 5s = 15s before fallback when offline).
+  const bundled = await readBundled(baselineDir);
+  const remotes = await Promise.all(
+    bundled.map((s) => tryFetchSkill(s.name, fetchImpl, cacheDir)),
+  );
+  return bundled.map((skill, i) => remotes[i]
+    ? { ...skill, content: remotes[i], _source: 'agent-skills' }
+    : { ...skill, _source: 'bundled' });
+}
+
+// Reads the bundled baseline from the npm-package directory.
+async function readBundled(baselineDir) {
   const skills = [];
   let entries;
   try {
@@ -92,7 +134,7 @@ export async function loadBaseline(baselineDir) {
     skills.push({
       source: 'clud-bug-baseline',
       name: entry.name.replace(/\.md$/, ''),
-      description: '(bundled baseline)',
+      description: '(baseline)',
       installs: 0,
       kind: 'baseline',
       content,
@@ -101,6 +143,65 @@ export async function loadBaseline(baselineDir) {
   return skills;
 }
 
+// Try to read from cache, then fall back to network. Returns the SKILL.md
+// content string on success, null on any failure (caller falls back to bundled).
+async function tryFetchSkill(name, fetchImpl, cacheDir) {
+  // Cache lookup first.
+  if (cacheDir) {
+    const cached = await readFromCache(cacheDir, name);
+    if (cached !== null) return cached;
+  }
+
+  // Network fetch with timeout covering BOTH the connection AND the body
+  // read (clearTimeout in finally guarantees the timer doesn't keep the
+  // event loop alive for up to 5s past a failed CLI run).
+  const url = `${AGENT_SKILLS_BASE}/${encodeURIComponent(name)}/SKILL.md`;
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), SKILL_FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetchImpl(url, { signal: ctrl.signal });
+    if (!res.ok) return null;
+    const content = await res.text();
+    if (!content || !content.trim()) return null;
+    if (cacheDir) await writeToCache(cacheDir, name, content);
+    return content;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function readFromCache(cacheDir, name) {
+  const path = cachePath(cacheDir, name);
+  try {
+    const st = await stat(path);
+    if (Date.now() - st.mtimeMs > SKILL_CACHE_TTL_MS) return null;
+    return await readFile(path, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+async function writeToCache(cacheDir, name, content) {
+  try {
+    await mkdir(cacheDir, { recursive: true });
+    await writeFile(cachePath(cacheDir, name), content);
+  } catch {
+    // Cache write failures are non-fatal — we already have the content.
+  }
+}
+
+function cachePath(cacheDir, name) {
+  // Include AGENT_SKILLS_BASE in the hash so different upstream URLs (e.g.
+  // a fork via CLUD_BUG_AGENT_SKILLS_BASE, or a different pinned SHA after
+  // a clud-bug release) get different cache entries. Otherwise switching
+  // bases would silently return the previously-cached content from a
+  // different upstream — cross-base cache poisoning.
+  const hash = createHash('sha256').update(`${AGENT_SKILLS_BASE}\n${name}`).digest('hex').slice(0, 16);
+  return join(cacheDir, `${hash}.md`);
+}
+
 export async function writeSkills(targetDir, skills, client) {
   await mkdir(targetDir, { recursive: true });
   const written = [];

package/lib/update.js

@@ -3,6 +3,7 @@ import { join, dirname } from 'node:path';
 import { renderFile, pickTemplate } from './render.js';
 import { detect, buildDescriptionLine } from './detect.js';
 import { loadBaseline, readManifest, writeManifest } from './skills.js';
+import { applyToRepo as applyAgentDocs } from './agents-md.js';
 
 // Re-render the user's workflow + refresh baseline skills using the
 // templates / baseline shipped with the currently-installed clud-bug.
@@ -21,6 +22,7 @@ export async function runUpdate({
   baselineDir,
   ourVersion,
   refreshRemote = false,
+  loadBaselineOpts,    // forwarded to loadBaseline (e.g. for tests: { fetch, cacheDir: null })
 } = {}) {
   if (!cwd || !templatesDir || !baselineDir || !ourVersion) {
     throw new Error('runUpdate requires cwd, templatesDir, baselineDir, ourVersion');
@@ -51,7 +53,7 @@ export async function runUpdate({
   }
 
   // 3. Refresh baseline skills (always controlled by clud-bug).
-  const baseline = await loadBaseline(baselineDir);
+  const baseline = await loadBaseline(baselineDir, loadBaselineOpts);
   for (const skill of baseline) {
     const skillPath = join(skillsDir, sanitize(skill.name), 'SKILL.md');
     await maybeWrite(skillPath, skill.content, changed, unchanged, `baseline ${skill.name}`);
@@ -66,7 +68,22 @@ export async function runUpdate({
     // `clud-bug refresh`. We just emit an advisory.
   }
 
-  // 5. Stamp the manifest with the version that ran the update.
+  // 5. Refresh the AGENTS.md / CLAUDE.md clud-bug block. The block embeds
+  //    the version + strict-mode state, so an update with a new version
+  //    rewrites it. Files that don't already exist (other than AGENTS.md)
+  //    are left alone, so this never silently creates instruction stubs.
+  // `=== true` mirrors the workflow's gate predicate at
+  // templates/workflow*.yml.tmpl. A v0.3 advisory manifest (strictMode
+  // undefined, lastUpdate set) renders "off" — matching the gate, not the
+  // default-on behavior of fresh v0.4+ installs.
+  const agentDocs = await applyAgentDocs(cwd, {
+    version: ourVersion,
+    strictMode: manifest.strictMode === true,
+  });
+  for (const p of agentDocs.created) changed.push({ path: join(cwd, p), label: `agent docs: created ${p}` });
+  for (const p of agentDocs.touched) changed.push({ path: join(cwd, p), label: `agent docs: ${p}` });
+
+  // 6. Stamp the manifest with the version that ran the update.
   manifest.lastUpdate = new Date().toISOString();
   manifest.lastUpdateVersion = ourVersion;
   await writeManifest(skillsDir, manifest);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clud-bug",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Claude PR review with project-aware skills. CLI installs a working GitHub Actions workflow and curates skills from skills.sh.",
   "homepage": "https://cludbug.dev",
   "bugs": "https://github.com/thrillmot/clud-bug/issues",

package/templates/skills/baseline/clud-bug-collaboration.md

@@ -0,0 +1,124 @@
+---
+name: clud-bug-collaboration
+description: How Claude Code agents working in a clud-bug-installed repo should interact with the bot's review threads, strict-mode gate, and skill set. Use this skill whenever you're about to push a commit, address a clud-bug PR review comment, edit anything under .claude/skills/, modify .github/workflows/clud-bug-*.yml, or wonder why a PR check is red. Also use when planning work in a repo that has a `clud-bug-review` workflow installed — even if the user didn't mention clud-bug by name.
+---
+
+# Working in a clud-bug-installed repo
+
+Clud Bug reviews every PR via `anthropics/claude-code-action`. As another
+Claude Code agent working alongside it, here's what to know — these aren't
+arbitrary rules, they're the consequences of how the gate is wired.
+
+## When you push fixes to a clud-bug-reviewed PR
+
+The bot reviews on `pull_request: synchronize` (every push). When you push
+a commit that addresses an issue Clud Bug flagged in a prior review, the bot
+will re-review the PR within ~2 minutes and **resolve its own prior
+unresolved inline review threads** where the flagged issue is verifiably
+fixed in the current diff. You don't have to resolve threads manually.
+
+If a thread it left isn't auto-resolved after your fix:
+- The bot judged the issue still open (read its latest comment for why).
+- Or the resolution call hit a transient API issue (re-push to retry).
+
+Don't manually resolve clud-bug threads on its behalf. The check
+(`required_conversation_resolution` branch protection) will block merge if
+unresolved threads remain — and the right fix is usually "fix the actual
+issue and re-push," not "mark the conversation resolved."
+
+## When you read the PR's `clud-bug-review` check status
+
+- **Green** = Clud Bug ran and either found no critical issues OR strict
+  mode is off (advisory).
+- **Red** = either the action errored OR strict mode is on AND Clud Bug
+  flagged a critical issue. Read the latest `## 🐛 Clud Bug review` comment
+  on the PR — the body indicates "critical findings" or "clean."
+- **Skipped/green-with-comment** = bot- or fork-authored PR (Dependabot,
+  Renovate, fork contributor). GitHub deliberately doesn't pass repo
+  secrets to those workflows. The bot posts a one-line "Clud Bug skipped"
+  comment and exits 0. Review the diff manually.
+
+## Strict mode
+
+Read `.claude/skills/.clud-bug.json` to check this repo's setting.
+`strictMode: true` means the workflow check fails on critical findings.
+The setting is read from the **base ref**, so a PR cannot disable strict
+mode on itself by editing the manifest. Changes take effect for PRs opened
+after the change merges to the base branch.
+
+To disable strict mode for a repo, edit the manifest on the base branch:
+
+```json
+{ "strictMode": false, ... }
+```
+
+## When you modify a clud-bug skill
+
+Skills live in `.claude/skills/<slug>/SKILL.md`. Three groups:
+
+- **Baseline** (`critical-issues-only`, `evidence-based-review`,
+  `respect-existing-conventions`) — managed by clud-bug; if you edit them
+  in-place they'll be overwritten on the next `clud-bug update`. To
+  customize behavior for this repo, write a NEW skill rather than mutating
+  a baseline.
+- **From skills.sh** — installed via `clud-bug add <source/name>`. Tracked
+  in `.claude/skills/.clud-bug.json`. Use `clud-bug refresh` to sync.
+- **Custom** (anything not in the manifest) — yours, never touched by any
+  clud-bug command. Drop a new `.md` here and it auto-loads on the next PR.
+
+When you write a custom skill, follow the SKILL.md frontmatter format
+(`name`, `description`) and write specific, evidence-anchored guidance.
+Generic advice gets ignored; rules with examples and quoted-line evidence
+move the bot's behavior.
+
+## When you edit `.github/workflows/clud-bug-*.yml`
+
+`anthropics/claude-code-action` **refuses to run on PRs that modify its
+own workflow file** (App token exchange fails with 401, "Workflow
+validation failed"). This is a security guard against PRs that try to
+neuter the reviewer or exfiltrate secrets.
+
+Consequence: if you bundle a workflow tweak with other work, the
+`clud-bug-review` check on that PR will fail and not actually review your
+other changes either.
+
+The fix: split workflow edits into their own PR. The CLI helps:
+
+```bash
+# After editing .github/workflows/clud-bug-*.yml locally:
+clud-bug edit-workflow
+```
+
+It refuses to run if your working tree has non-workflow changes, so the
+isolation guarantee is enforced. Branches from `origin/main`, not HEAD —
+unrelated commits on a feature branch can't leak in.
+
+## When the secret is missing
+
+`ANTHROPIC_API_KEY` must be set in the repo's Actions secrets. Without it,
+the workflow's guard step fails loudly with an `::error::` annotation
+explaining how to set it. (For bot/fork PRs where the secret legitimately
+isn't passed, the guard posts a one-line advisory comment and exits 0
+instead of failing red.)
+
+## Updating clud-bug itself
+
+`clud-bug-self-update.yml` runs weekly (Mondays 12:00 UTC) and opens a PR
+when a newer clud-bug version is published to npm. Pin to a specific
+version by adding `pinVersion: "x.y.z"` to `.claude/skills/.clud-bug.json`.
+
+To trigger an update on demand:
+
+```bash
+clud-bug update
+```
+
+Re-renders workflow templates and refreshes baseline skills from the
+currently-installed clud-bug version. Custom and skills.sh-installed
+skills are left untouched.
+
+## Where to find more
+
+- Site: https://cludbug.dev
+- Repo: https://github.com/thrillmot/clud-bug
+- Skill catalog: https://github.com/thrillmot/agent-skills