clud-bug 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 thrillmot
+
+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,127 @@
+# Clud Bug 🐛
+### Crawling all over your code
+
+> **[cludbug.dev](https://cludbug.dev)** · A field guide.
+
+Claude PR review for any GitHub repo, with **project-aware skills** auto-discovered from [skills.sh](https://skills.sh) and a baseline of review-discipline skills bundled in.
+
+One command to install. The first PR you open afterwards gets a real review comment back.
+
+## Quickstart
+
+```bash
+cd your-repo
+npx clud-bug init
+git add .claude .github/workflows/clud-bug-review.yml
+git commit -m "Add clud-bug PR review"
+git push
+```
+
+Then in your repo on GitHub:
+**Settings → Secrets and variables → Actions → New repository secret** → set `ANTHROPIC_API_KEY`.
+
+Open a PR. A review comment should appear within ~2 minutes.
+
+## What `clud-bug init` does
+
+1. **Detects** your stack (Node, Python, Go, Rust, Ruby — reads `package.json`, `pyproject.toml`, `go.mod`, etc.).
+2. **Queries [skills.sh](https://skills.sh)** for review skills relevant to your dependencies (e.g. a Next.js project gets Next.js review skills).
+3. **Installs three baseline skills** 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.
+4. **Writes** the chosen skills to `.claude/skills/<name>/SKILL.md` (Claude Code auto-loads them in the GitHub Action).
+5. **Generates** `.github/workflows/clud-bug-review.yml` with the project description filled in and the right permissions/tool allowlist for `gh pr comment` to actually work.
+
+## CLI options
+
+```
+npx clud-bug init [options]
+
+  --offline       Skip skills.sh; install only the bundled baseline skills.
+  --accept-all,-y Accept the recommended skill set without prompting.
+  --commit        git add + commit the generated files when done.
+  --help,-h       Show help.
+```
+
+## Managing skills
+
+After `init`, four commands let you evolve the skill set without re-running the whole setup:
+
+```bash
+clud-bug list                                       # show what's installed
+clud-bug add vercel-labs/skills/next-best-practices # install one from skills.sh
+clud-bug remove next-best-practices                 # uninstall (refuses custom skills)
+clud-bug refresh                                    # re-query skills.sh, diff vs installed
+```
+
+Skills are tracked in `.claude/skills/.clud-bug.json` (a small manifest). Anything in `.claude/skills/` that *isn't* in the manifest is treated as your custom work and never modified by `clud-bug` commands.
+
+## Adding your own skills
+
+Drop any `.md` file into `.claude/skills/<your-skill>/SKILL.md` — Claude Code auto-discovers it on the next PR. Same format as skills from skills.sh:
+
+```markdown
+---
+name: my-team-rules
+description: One-line description of what this skill teaches the reviewer.
+---
+
+# My team rules
+
+Rules go here. Be specific, cite examples, explain the why.
+```
+
+This is how you encode your team's PR-review discipline (e.g. "always check for SQL injection in `db/queries/`", "API responses must include error codes from `lib/errors.ts`").
+
+## Why this works (and why the original `claude-code-action` install often doesn't)
+
+`anthropics/claude-code-action@v1` is the underlying engine — clud-bug just configures it correctly. Two things people commonly miss when wiring it themselves:
+
+- **`gh pr comment` is disabled by default.** Without `--allowedTools` whitelisting it, Claude runs, thinks, and exits silently. clud-bug's generated workflow includes the right allowlist.
+- **Skills are not auto-loaded from anywhere.** If you don't ship `.claude/skills/*` in your repo, Claude reviews with zero project context. clud-bug installs a curated set so the review is actually project-aware.
+
+## Fork PR caveat ⚠️
+
+GitHub does **not** pass repo secrets (including `ANTHROPIC_API_KEY`) to workflows triggered by PRs from forks. By default, `pull_request` workflows on fork PRs will run with no API key and produce no comment.
+
+If you want clud-bug to review fork PRs too, you have two options:
+
+1. **Maintainer re-pushes the branch** to your repo as a non-fork branch, and the review runs.
+2. **Switch the trigger to `pull_request_target`** (advanced) — this gives the workflow access to secrets but runs against the *base* ref, not the PR's code. To safely review the PR's actual code, follow [`anthropics/claude-code-action` security.md](https://github.com/anthropics/claude-code-action/blob/main/docs/security.md): check out the PR head into a **subdirectory** (not the workspace root) and pass it via `--add-dir`. Skipping this is a code-execution risk.
+
+clud-bug's generated workflow uses `pull_request` by default. If you understand the trade-offs, edit the trigger yourself.
+
+## Verifying it works
+
+After install:
+
+1. Confirm `ANTHROPIC_API_KEY` secret is set on the repo.
+2. Open a throwaway PR with an obvious bug (e.g. `const x = null; x.foo()`).
+3. Within ~2 min, Clud Bug should post a comment flagging it.
+4. If no comment: check the **Actions** tab logs. Look for `gh pr comment` invocations and any "Resource not accessible by integration" errors (usually a permissions issue or a fork PR).
+
+## Manual install (advanced)
+
+If you don't want to use the CLI, you can install a generic workflow by hand:
+
+```bash
+mkdir -p .github/workflows
+curl -o .github/workflows/clud-bug-review.yml \
+  https://raw.githubusercontent.com/thrillmot/clud-bug/main/templates/workflow.yml.tmpl
+# Edit {{PROJECT_DESCRIPTION}} and {{LANGUAGE_HINTS}} placeholders by hand.
+```
+
+The CLI does this for you, plus skill curation.
+
+## Contributing
+
+Pull requests welcome. If you're adding a new detector for a language ecosystem, put it in `lib/detect.js` and add a fixture-based test in `test/detect.test.js`.
+
+```bash
+npm test          # node:test, no runtime deps
+```
+
+## License
+
+MIT.

package/bin/clud-bug.js

@@ -0,0 +1,322 @@
+#!/usr/bin/env node
+import { mkdir, writeFile, readFile } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { createInterface } from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+
+import { detect, buildDescriptionLine } from '../lib/detect.js';
+import { renderFile, pickTemplate } from '../lib/render.js';
+import {
+  SkillsClient, rankAndCap, writeSkills, writeSkill, loadBaseline,
+  readManifest, writeManifest, removeSkill, listInstalled, diffManifest,
+} from '../lib/skills.js';
+
+const PKG_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const TEMPLATES = join(PKG_ROOT, 'templates');
+const BASELINE_DIR = join(TEMPLATES, 'skills', 'baseline');
+
+function parseArgs(argv) {
+  const args = { _: [], offline: false, acceptAll: false, commit: false, help: false, version: false };
+  for (const a of argv) {
+    if (a === '--offline') args.offline = true;
+    else if (a === '--accept-all' || a === '-y') args.acceptAll = true;
+    else if (a === '--commit') args.commit = true;
+    else if (a === '--help' || a === '-h') args.help = true;
+    else if (a === '--version' || a === '-v') args.version = true;
+    else args._.push(a);
+  }
+  return args;
+}
+
+const HELP = `clud-bug — Claude PR review with project-aware skills
+
+Usage:
+  npx clud-bug <command> [options]
+
+Commands:
+  init                  First-time setup: detect repo, install skills, write workflow.
+  list                  Show currently installed skills (baseline / remote / custom).
+  add <source/name>     Install one skill from skills.sh (e.g. vercel-labs/skills/next-best-practices).
+  remove <slug>         Remove an installed skill (refuses if it's a custom skill).
+  refresh               Re-query skills.sh and diff against installed; prompt to update.
+
+Options:
+  --offline             Skip skills.sh; only use bundled baseline skills (init/refresh).
+  --accept-all,-y       Accept recommendations without prompting.
+  --commit              git add + commit the generated files when done (init only).
+  --help,-h             Show this help.
+  --version,-v          Show version.
+`;
+
+async function readPkgVersion() {
+  const pkg = JSON.parse(await readFile(join(PKG_ROOT, 'package.json'), 'utf8'));
+  return pkg.version;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) { process.stdout.write(HELP); return; }
+  if (args.version) { process.stdout.write((await readPkgVersion()) + '\n'); return; }
+
+  const cmd = args._[0];
+  switch (cmd) {
+    case 'init':    return runInit(args);
+    case 'list':    return runList(args);
+    case 'add':     return runAdd(args);
+    case 'remove':  return runRemove(args);
+    case 'refresh': return runRefresh(args);
+    default:
+      process.stderr.write(`Unknown command: ${cmd || '(none)'}\n\n${HELP}`);
+      process.exit(2);
+  }
+}
+
+async function runInit(args) {
+  const cwd = process.cwd();
+  log(`🐛 clud-bug init in ${cwd}`);
+
+  log('  detecting repo signals...');
+  const signals = await detect(cwd);
+  log(`    primary language: ${signals.primaryLanguage || '(unknown)'}`);
+  log(`    search terms:     ${signals.searchTerms.join(', ') || '(none)'}`);
+
+  const baseline = await loadBaseline(BASELINE_DIR);
+  log(`    baseline skills:  ${baseline.length}`);
+
+  let curated = [];
+  let searched = [];
+  if (args.offline) {
+    log('  --offline: skipping skills.sh');
+  } else {
+    const client = new SkillsClient();
+    try {
+      log('  querying skills.sh...');
+      [curated, searched] = await Promise.all([
+        client.curated().catch(err => { warn(`curated query failed: ${err.message}`); return []; }),
+        client.search(signals.searchTerms).catch(err => { warn(`search failed: ${err.message}`); return []; }),
+      ]);
+      log(`    curated: ${curated.length}, search hits: ${searched.length}`);
+    } catch (err) {
+      warn(`skills.sh unreachable (${err.message}); continuing with baseline only`);
+    }
+  }
+
+  const recommended = rankAndCap(curated, searched, baseline);
+  log('');
+  log('Recommended skills:');
+  for (const s of recommended) {
+    const tag = s.kind === 'baseline' ? '[baseline]' : `[${s.source}]`;
+    log(`  • ${s.name} ${tag}`);
+    if (s.description && s.kind !== 'baseline') log(`      ${s.description}`);
+  }
+  log('');
+
+  let chosen = recommended;
+  if (!args.acceptAll && recommended.some(s => s.kind !== 'baseline')) {
+    chosen = await promptForSkills(recommended);
+  }
+
+  log('  installing skills into .claude/skills/...');
+  const client = new SkillsClient();
+  const written = await writeSkills(join(cwd, '.claude', 'skills'), chosen, client);
+  log(`    wrote ${written.length} skills`);
+
+  log('  rendering workflow...');
+  const tmplName = pickTemplate(signals.languages);
+  const tmplPath = join(TEMPLATES, tmplName);
+  const workflow = await renderFile(tmplPath, {
+    PROJECT_DESCRIPTION: buildDescriptionLine(signals),
+    LANGUAGE_HINTS: '',
+  });
+  const workflowPath = join(cwd, '.github', 'workflows', 'clud-bug-review.yml');
+  await mkdir(dirname(workflowPath), { recursive: true });
+  await writeFile(workflowPath, workflow);
+  log(`    wrote ${rel(cwd, workflowPath)}`);
+
+  if (args.commit) {
+    log('  committing...');
+    spawnSync('git', ['add', '.claude', '.github/workflows/clud-bug-review.yml'], { cwd, stdio: 'inherit' });
+    spawnSync('git', ['commit', '-m', 'Add clud-bug Claude PR review'], { cwd, stdio: 'inherit' });
+  }
+
+  log('');
+  log('Done. Next steps:');
+  log('  1. Set ANTHROPIC_API_KEY in your repo secrets:');
+  log('     Settings → Secrets and variables → Actions → New repository secret');
+  if (!args.commit) {
+    log('  2. git add .claude .github/workflows/clud-bug-review.yml && git commit && git push');
+    log('  3. Open a PR — Clud Bug should comment within ~2 min.');
+  } else {
+    log('  2. git push, then open a PR — Clud Bug should comment within ~2 min.');
+  }
+  log('');
+  log('Drop your own .claude/skills/<name>/SKILL.md files anytime — they\'re auto-loaded.');
+}
+
+async function promptForSkills(recommended) {
+  const rl = createInterface({ input, output });
+  try {
+    const answer = await rl.question('Install all of the above? [Y/n/select] ');
+    const a = answer.trim().toLowerCase();
+    if (a === '' || a === 'y' || a === 'yes') return recommended;
+    if (a === 'n' || a === 'no') return recommended.filter(s => s.kind === 'baseline');
+    if (a === 's' || a === 'select') {
+      const chosen = [];
+      for (const skill of recommended) {
+        if (skill.kind === 'baseline') { chosen.push(skill); continue; }
+        const ans = await rl.question(`  install ${skill.name}? [Y/n] `);
+        if (ans.trim().toLowerCase() !== 'n') chosen.push(skill);
+      }
+      return chosen;
+    }
+    return recommended;
+  } finally {
+    rl.close();
+  }
+}
+
+async function runList(_args) {
+  const skillsDir = join(process.cwd(), '.claude', 'skills');
+  const groups = await listInstalled(skillsDir);
+  const total = groups.baseline.length + groups.remote.length + groups.custom.length;
+  if (total === 0) {
+    log('No skills installed yet. Run `clud-bug init` to get started.');
+    return;
+  }
+  log(`🐛 ${total} skill${total === 1 ? '' : 's'} in .claude/skills/`);
+  if (groups.baseline.length) {
+    log('');
+    log('Baseline (always installed):');
+    for (const s of groups.baseline) log(`  • ${s.slug}`);
+  }
+  if (groups.remote.length) {
+    log('');
+    log('From skills.sh:');
+    for (const s of groups.remote) log(`  • ${s.slug}  ${s.source ? `[${s.source}]` : ''}`);
+  }
+  if (groups.custom.length) {
+    log('');
+    log('Custom (yours, never auto-modified):');
+    for (const s of groups.custom) {
+      log(`  • ${s.slug}${s.description ? `  — ${s.description}` : ''}`);
+    }
+  }
+}
+
+async function runAdd(args) {
+  const ref = args._[1];
+  if (!ref || !ref.includes('/')) {
+    process.stderr.write('Usage: clud-bug add <source/name>  (e.g. vercel-labs/skills/next-best-practices)\n');
+    process.exit(2);
+  }
+  // Last segment is the skill name; everything before is the source repo path.
+  const lastSlash = ref.lastIndexOf('/');
+  const source = ref.slice(0, lastSlash);
+  const name = ref.slice(lastSlash + 1);
+  const skillsDir = join(process.cwd(), '.claude', 'skills');
+  log(`  fetching ${source}/${name} from skills.sh...`);
+  const client = new SkillsClient();
+  const entry = await writeSkill(skillsDir, { source, name, kind: 'remote' }, client);
+  const manifest = await readManifest(skillsDir);
+  const merged = { version: 1, installed: [...manifest.installed.filter(e => e.slug !== entry.slug), entry] };
+  await writeManifest(skillsDir, merged);
+  log(`  ✓ installed ${entry.slug} → .claude/skills/${entry.slug}/SKILL.md`);
+  log('  Commit + push to apply on the next PR.');
+}
+
+async function runRemove(args) {
+  const slug = args._[1];
+  if (!slug) {
+    process.stderr.write('Usage: clud-bug remove <slug>  (run `clud-bug list` to see installed slugs)\n');
+    process.exit(2);
+  }
+  const skillsDir = join(process.cwd(), '.claude', 'skills');
+  const entry = await removeSkill(skillsDir, slug);
+  log(`  ✓ removed ${entry.slug}${entry.kind === 'baseline' ? ' (baseline — will return on next init)' : ''}`);
+}
+
+async function runRefresh(args) {
+  const cwd = process.cwd();
+  const skillsDir = join(cwd, '.claude', 'skills');
+  const manifest = await readManifest(skillsDir);
+  if (manifest.installed.length === 0) {
+    log('No clud-bug-managed skills found. Run `clud-bug init` first.');
+    return;
+  }
+
+  log('  detecting repo signals...');
+  const signals = await detect(cwd);
+  log(`    primary language: ${signals.primaryLanguage || '(unknown)'}`);
+  log(`    search terms:     ${signals.searchTerms.join(', ') || '(none)'}`);
+
+  const baseline = await loadBaseline(BASELINE_DIR);
+  let curated = [];
+  let searched = [];
+  if (args.offline) {
+    log('  --offline: skipping skills.sh — only baseline additions will be diffed; existing remote skills are preserved');
+  } else {
+    const client = new SkillsClient();
+    let curatedErr, searchedErr;
+    [curated, searched] = await Promise.all([
+      client.curated().catch(err => { curatedErr = err; return []; }),
+      client.search(signals.searchTerms).catch(err => { searchedErr = err; return []; }),
+    ]);
+    if (curatedErr || searchedErr) {
+      const err = curatedErr || searchedErr;
+      warn(`skills.sh unreachable (${err.message})`);
+      warn('refusing to compute removals — an empty API response would look like "delete everything from skills.sh".');
+      warn('Try again later, or run with --offline to install only baseline updates.');
+      process.exit(1);
+    }
+  }
+  const recommended = rankAndCap(curated, searched, baseline);
+  const diff = diffManifest(manifest, recommended);
+
+  // In --offline mode the recommendation set isn't authoritative (we only have
+  // baseline locally), so any "missing from recommendations" entry is a false
+  // positive. Suppress removals to avoid mass-deleting the user's remote skills.
+  if (args.offline) diff.remove = [];
+
+  log('');
+  log(`  add:       ${diff.add.length}`);
+  log(`  remove:    ${diff.remove.length} (custom skills untouched)`);
+  log(`  unchanged: ${diff.unchanged.length}`);
+
+  if (diff.add.length === 0 && diff.remove.length === 0) {
+    log('');
+    log('Nothing to update. Skills are in sync with skills.sh recommendations.');
+    return;
+  }
+
+  log('');
+  for (const s of diff.add)    log(`  + ${s.name} [${s.source || s.kind}]`);
+  for (const s of diff.remove) log(`  - ${s.slug} [${s.source || s.kind}]`);
+
+  if (!args.acceptAll) {
+    const rl = createInterface({ input, output });
+    const answer = await rl.question('\nApply these changes? [y/N] ');
+    rl.close();
+    if (answer.trim().toLowerCase() !== 'y') {
+      log('Aborted. No files changed.');
+      return;
+    }
+  }
+
+  const client = new SkillsClient();
+  if (diff.add.length) await writeSkills(skillsDir, diff.add, client);
+  for (const entry of diff.remove) await removeSkill(skillsDir, entry.slug);
+  log('  ✓ skills updated. Commit + push to apply on the next PR.');
+}
+
+function rel(from, to) {
+  return to.startsWith(from + '/') ? to.slice(from.length + 1) : to;
+}
+function log(msg) { process.stdout.write(msg + '\n'); }
+function warn(msg) { process.stderr.write(`  ! ${msg}\n`); }
+
+main().catch(err => {
+  process.stderr.write(`clud-bug: ${err.message}\n`);
+  process.exit(1);
+});

package/lib/detect.js

@@ -0,0 +1,231 @@
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join, extname } from 'node:path';
+
+const EXT_TO_LANG = {
+  '.ts': 'typescript', '.tsx': 'typescript',
+  '.js': 'javascript', '.jsx': 'javascript', '.mjs': 'javascript', '.cjs': 'javascript',
+  '.py': 'python',
+  '.go': 'go',
+  '.rs': 'rust',
+  '.rb': 'ruby',
+  '.java': 'java', '.kt': 'kotlin',
+  '.swift': 'swift',
+  '.php': 'php',
+  '.cs': 'csharp',
+  '.c': 'c', '.h': 'c',
+  '.cpp': 'cpp', '.cc': 'cpp', '.hpp': 'cpp',
+};
+
+// Dependency name → search term hint passed to skills.sh.
+// Only well-known frameworks; obscure packages get filtered out so the
+// skills.sh query doesn't get drowned in noise.
+const DEP_TO_TERM = {
+  'next': 'nextjs', 'react': 'react', 'vue': 'vue', 'svelte': 'svelte',
+  '@angular/core': 'angular', 'solid-js': 'solid',
+  'express': 'express', 'fastify': 'fastify', 'koa': 'koa', 'hono': 'hono',
+  'prisma': 'prisma', '@prisma/client': 'prisma', 'drizzle-orm': 'drizzle',
+  'mongoose': 'mongodb', 'mongodb': 'mongodb',
+  'tailwindcss': 'tailwind',
+  'vitest': 'vitest', 'jest': 'jest', 'playwright': 'playwright',
+  '@playwright/test': 'playwright',
+  'typescript': 'typescript',
+};
+
+const PY_DEP_TO_TERM = {
+  'django': 'django', 'flask': 'flask', 'fastapi': 'fastapi',
+  'click': 'click', 'typer': 'typer',
+  'pytest': 'pytest', 'sqlalchemy': 'sqlalchemy',
+  'pydantic': 'pydantic', 'numpy': 'numpy', 'pandas': 'pandas',
+};
+
+async function fileExists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readJsonSafe(path) {
+  try {
+    return JSON.parse(await readFile(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+async function readTextSafe(path) {
+  try {
+    return await readFile(path, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+async function detectFromPackageJson(root) {
+  const pkg = await readJsonSafe(join(root, 'package.json'));
+  if (!pkg) return null;
+  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  const terms = new Set();
+  for (const dep of Object.keys(deps)) {
+    if (DEP_TO_TERM[dep]) terms.add(DEP_TO_TERM[dep]);
+  }
+  return {
+    name: pkg.name,
+    description: pkg.description || null,
+    languages: ['javascript', ...(deps.typescript || pkg.devDependencies?.typescript ? ['typescript'] : [])],
+    terms: [...terms],
+  };
+}
+
+async function detectFromPyproject(root) {
+  const text = await readTextSafe(join(root, 'pyproject.toml'));
+  if (!text) return null;
+  const terms = new Set();
+  for (const [dep, term] of Object.entries(PY_DEP_TO_TERM)) {
+    // crude but adequate match — full TOML parse would be overkill for the
+    // dependency-name lookup we actually need
+    if (new RegExp(`["']${dep}[><=~ "']`, 'i').test(text)) terms.add(term);
+  }
+  const nameMatch = text.match(/^\s*name\s*=\s*["']([^"']+)["']/m);
+  const descMatch = text.match(/^\s*description\s*=\s*["']([^"']+)["']/m);
+  return {
+    name: nameMatch?.[1] || null,
+    description: descMatch?.[1] || null,
+    languages: ['python'],
+    terms: [...terms],
+  };
+}
+
+async function detectFromRequirements(root) {
+  const text = await readTextSafe(join(root, 'requirements.txt'));
+  if (!text) return null;
+  const terms = new Set();
+  for (const line of text.split('\n')) {
+    const dep = line.split(/[<>=~ #]/)[0].trim().toLowerCase();
+    if (PY_DEP_TO_TERM[dep]) terms.add(PY_DEP_TO_TERM[dep]);
+  }
+  return { name: null, description: null, languages: ['python'], terms: [...terms] };
+}
+
+async function detectFromGoMod(root) {
+  const text = await readTextSafe(join(root, 'go.mod'));
+  if (!text) return null;
+  const moduleMatch = text.match(/^module\s+(\S+)/m);
+  return {
+    name: moduleMatch?.[1]?.split('/').pop() || null,
+    description: null,
+    languages: ['go'],
+    terms: [],
+  };
+}
+
+async function detectFromCargo(root) {
+  const text = await readTextSafe(join(root, 'Cargo.toml'));
+  if (!text) return null;
+  const nameMatch = text.match(/^\s*name\s*=\s*["']([^"']+)["']/m);
+  const descMatch = text.match(/^\s*description\s*=\s*["']([^"']+)["']/m);
+  return {
+    name: nameMatch?.[1] || null,
+    description: descMatch?.[1] || null,
+    languages: ['rust'],
+    terms: [],
+  };
+}
+
+async function detectFromGemfile(root) {
+  const text = await readTextSafe(join(root, 'Gemfile'));
+  if (!text) return null;
+  return { name: null, description: null, languages: ['ruby'], terms: [] };
+}
+
+async function fileHistogram(root) {
+  const counts = {};
+  async function walk(dir, depth) {
+    if (depth > 3) return;
+    let entries;
+    try { entries = await readdir(dir, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      if (entry.name.startsWith('.') || entry.name === 'node_modules' ||
+          entry.name === 'dist' || entry.name === 'build' ||
+          entry.name === '__pycache__' || entry.name === 'target') continue;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(full, depth + 1);
+      } else {
+        const lang = EXT_TO_LANG[extname(entry.name)];
+        if (lang) counts[lang] = (counts[lang] || 0) + 1;
+      }
+    }
+  }
+  await walk(root, 0);
+  return counts;
+}
+
+function firstParagraph(readme) {
+  if (!readme) return null;
+  const lines = readme.split('\n').slice(0, 200);
+  const paragraphs = lines.join('\n').split(/\n\s*\n/);
+  for (const p of paragraphs) {
+    const cleaned = p.replace(/^#+\s*/, '').replace(/[*_`]/g, '').trim();
+    if (cleaned.length > 40) return cleaned.slice(0, 500);
+  }
+  return null;
+}
+
+export async function detect(root) {
+  const detectors = [
+    detectFromPackageJson, detectFromPyproject, detectFromRequirements,
+    detectFromGoMod, detectFromCargo, detectFromGemfile,
+  ];
+  const results = (await Promise.all(detectors.map(d => d(root)))).filter(Boolean);
+  const histogram = await fileHistogram(root);
+  const readme = await readTextSafe(join(root, 'README.md'))
+    || await readTextSafe(join(root, 'README'));
+
+  const languages = new Set();
+  const terms = new Set();
+  let name = null;
+  let description = null;
+  for (const r of results) {
+    for (const lang of r.languages) languages.add(lang);
+    for (const term of r.terms) terms.add(term);
+    if (!name && r.name) name = r.name;
+    if (!description && r.description) description = r.description;
+  }
+  for (const lang of Object.keys(histogram)) languages.add(lang);
+  if (!description) description = firstParagraph(readme);
+
+  // Prefer the language with the most files when picking a primary
+  const sortedLangs = [...languages].sort((a, b) => (histogram[b] || 0) - (histogram[a] || 0));
+
+  return {
+    name,
+    description,
+    languages: sortedLangs,
+    histogram,
+    searchTerms: [...new Set([...terms, ...sortedLangs.slice(0, 2)])],
+    primaryLanguage: sortedLangs[0] || null,
+  };
+}
+
+export function buildDescriptionLine(signals) {
+  const parts = [];
+  if (signals.name) parts.push(`This project is "${signals.name}".`);
+  if (signals.description) {
+    const desc = signals.description.trim();
+    parts.push(/[.!?]$/.test(desc) ? desc : `${desc}.`);
+  }
+  if (signals.primaryLanguage) {
+    const frameworks = [...new Set(signals.searchTerms)].filter(t =>
+      !['typescript', 'javascript', 'python', 'go', 'rust', 'ruby'].includes(t));
+    const frameworkPart = frameworks.length ? ` using ${frameworks.join(', ')}` : '';
+    parts.push(`It's primarily ${signals.primaryLanguage}${frameworkPart}.`);
+  }
+  if (parts.length === 0) return 'Project context unavailable — review on the merits of the diff alone.';
+  return parts.join(' ');
+}
+
+// Test seam: allow tests to inject the EXT_TO_LANG and DEP_TO_TERM tables
+export const _internal = { EXT_TO_LANG, DEP_TO_TERM, PY_DEP_TO_TERM, fileHistogram, firstParagraph };

package/lib/render.js

@@ -0,0 +1,27 @@
+import { readFile } from 'node:fs/promises';
+
+const PLACEHOLDER_RE = /\{\{([A-Z_]+)\}\}/g;
+
+export function render(template, vars) {
+  return template.replace(PLACEHOLDER_RE, (match, key) => {
+    if (!(key in vars)) {
+      throw new Error(`Missing template variable: ${key}`);
+    }
+    return vars[key];
+  });
+}
+
+export async function renderFile(path, vars) {
+  const tmpl = await readFile(path, 'utf8');
+  return render(tmpl, vars);
+}
+
+export function pickTemplate(languages) {
+  if (languages.includes('typescript') || languages.includes('javascript')) {
+    return 'workflow-ts.yml.tmpl';
+  }
+  if (languages.includes('python')) {
+    return 'workflow-py.yml.tmpl';
+  }
+  return 'workflow.yml.tmpl';
+}

package/lib/skills.js

@@ -0,0 +1,243 @@
+import { mkdir, writeFile, readdir, readFile, rm, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const API_BASE = 'https://skills.sh/api/v1';
+const MAX_SKILLS = 8;
+const MANIFEST_FILE = '.clud-bug.json';
+const MANIFEST_VERSION = 1;
+
+export class SkillsClient {
+  constructor({ fetch = globalThis.fetch, base, userAgent = 'clud-bug' } = {}) {
+    this.fetch = fetch;
+    this.base = base ?? process.env.CLUD_BUG_SKILLS_SH_BASE ?? API_BASE;
+    this.userAgent = userAgent;
+  }
+
+  async #json(path) {
+    const res = await this.fetch(`${this.base}${path}`, {
+      headers: { 'User-Agent': this.userAgent, accept: 'application/json' },
+    });
+    if (!res.ok) {
+      throw new Error(`skills.sh ${path} → ${res.status}`);
+    }
+    return res.json();
+  }
+
+  async search(terms) {
+    const q = terms.filter(Boolean).join(' ').trim();
+    if (!q) return [];
+    const data = await this.#json(`/skills/search?q=${encodeURIComponent(q)}`);
+    return normalizeList(data);
+  }
+
+  async curated() {
+    const data = await this.#json('/skills/curated');
+    return normalizeList(data);
+  }
+
+  async getContent(source, name) {
+    const data = await this.#json(`/skills/${encodeURIComponent(source)}/${encodeURIComponent(name)}`);
+    // The API may return content as `body`, `content`, or under `files[0].content`.
+    // Try the documented shapes in order; fail loudly if none match so we know
+    // the API contract changed.
+    if (typeof data?.content === 'string') return data.content;
+    if (typeof data?.body === 'string') return data.body;
+    if (typeof data?.files?.[0]?.content === 'string') return data.files[0].content;
+    throw new Error(`skills.sh response for ${source}/${name} had no content field`);
+  }
+}
+
+function normalizeList(data) {
+  // Tolerate either { skills: [...] } or a bare array.
+  const list = Array.isArray(data) ? data : (data?.skills || data?.results || []);
+  return list.map(item => ({
+    source: item.source || item.repo || '',
+    name: item.name || item.slug || '',
+    description: item.description || item.summary || '',
+    installs: item.installs || item.installCount || 0,
+  })).filter(s => s.source && s.name);
+}
+
+// Deduplicates by source/name and caps at MAX_SKILLS, preferring curated then by install count.
+export function rankAndCap(curated, searched, baseline, cap = MAX_SKILLS) {
+  const seen = new Set(baseline.map(b => `local:${b.name}`));
+  const out = [...baseline];
+  const remaining = cap - baseline.length;
+  if (remaining <= 0) return out.slice(0, cap);
+
+  const curatedSorted = [...curated].sort((a, b) => b.installs - a.installs);
+  const searchedSorted = [...searched].sort((a, b) => b.installs - a.installs);
+
+  for (const skill of [...curatedSorted, ...searchedSorted]) {
+    if (out.length >= cap) break;
+    const key = `${skill.source}/${skill.name}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push({ ...skill, kind: skill.kind || 'remote' });
+  }
+  return out;
+}
+
+export async function loadBaseline(baselineDir) {
+  const skills = [];
+  let entries;
+  try {
+    entries = await readdir(baselineDir, { withFileTypes: true });
+  } catch {
+    return skills;
+  }
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+    const content = await readFile(join(baselineDir, entry.name), 'utf8');
+    skills.push({
+      source: 'clud-bug-baseline',
+      name: entry.name.replace(/\.md$/, ''),
+      description: '(bundled baseline)',
+      installs: 0,
+      kind: 'baseline',
+      content,
+    });
+  }
+  return skills;
+}
+
+export async function writeSkills(targetDir, skills, client) {
+  await mkdir(targetDir, { recursive: true });
+  const written = [];
+  for (const skill of skills) {
+    const entry = await writeSkill(targetDir, skill, client);
+    written.push(entry);
+  }
+  await writeManifest(targetDir, mergeManifest(await readManifest(targetDir), written));
+  return written;
+}
+
+export async function writeSkill(targetDir, skill, client) {
+  await mkdir(targetDir, { recursive: true });
+  const slug = sanitizeSlug(skill.name);
+  const skillDir = join(targetDir, slug);
+  await mkdir(skillDir, { recursive: true });
+  const content = skill.content ?? await client.getContent(skill.source, skill.name);
+  await writeFile(join(skillDir, 'SKILL.md'), content);
+  return {
+    slug,
+    name: skill.name,
+    source: skill.source,
+    kind: skill.kind || 'remote',
+    description: skill.description || '',
+  };
+}
+
+export async function readManifest(targetDir) {
+  try {
+    const text = await readFile(join(targetDir, MANIFEST_FILE), 'utf8');
+    const data = JSON.parse(text);
+    return {
+      version: data.version || MANIFEST_VERSION,
+      installed: Array.isArray(data.installed) ? data.installed : [],
+    };
+  } catch {
+    return { version: MANIFEST_VERSION, installed: [] };
+  }
+}
+
+export async function writeManifest(targetDir, manifest) {
+  await mkdir(targetDir, { recursive: true });
+  const out = {
+    version: manifest.version || MANIFEST_VERSION,
+    installed: manifest.installed || [],
+  };
+  await writeFile(join(targetDir, MANIFEST_FILE), JSON.stringify(out, null, 2) + '\n');
+}
+
+export function mergeManifest(existing, newEntries) {
+  const byKey = new Map();
+  for (const entry of existing.installed || []) {
+    byKey.set(entryKey(entry), entry);
+  }
+  for (const entry of newEntries) {
+    byKey.set(entryKey(entry), entry);
+  }
+  return { version: MANIFEST_VERSION, installed: [...byKey.values()] };
+}
+
+function entryKey(entry) {
+  // Baseline skills have no source; key by slug. Remote skills key by source/name.
+  return entry.kind === 'baseline' ? `baseline:${entry.slug}` : `${entry.source}/${entry.name || entry.slug}`;
+}
+
+export async function removeSkill(targetDir, slug) {
+  const manifest = await readManifest(targetDir);
+  const entry = manifest.installed.find(e => e.slug === slug);
+  if (!entry) {
+    throw new Error(`'${slug}' is not in the clud-bug manifest. If it's a custom skill, delete it manually with: rm -rf .claude/skills/${slug}`);
+  }
+  await rm(join(targetDir, slug), { recursive: true, force: true });
+  manifest.installed = manifest.installed.filter(e => e.slug !== slug);
+  await writeManifest(targetDir, manifest);
+  return entry;
+}
+
+export async function listInstalled(targetDir) {
+  const manifest = await readManifest(targetDir);
+  const managedSlugs = new Set(manifest.installed.map(e => e.slug));
+  const groups = { baseline: [], remote: [], custom: [] };
+  for (const entry of manifest.installed) {
+    (groups[entry.kind === 'baseline' ? 'baseline' : 'remote']).push(entry);
+  }
+
+  let entries;
+  try {
+    entries = await readdir(targetDir, { withFileTypes: true });
+  } catch {
+    return groups;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (managedSlugs.has(entry.name)) continue;
+    const skillFile = join(targetDir, entry.name, 'SKILL.md');
+    let description = '';
+    try {
+      const text = await readFile(skillFile, 'utf8');
+      const m = text.match(/^description:\s*(.+)$/m);
+      description = m?.[1]?.trim() || '';
+    } catch {
+      continue; // not a skill dir
+    }
+    groups.custom.push({ slug: entry.name, kind: 'custom', description });
+  }
+  return groups;
+}
+
+// Diff a current manifest against a freshly-recommended skill set.
+// Returns { add: [], remove: [], unchanged: [] }. Custom skills are never affected.
+export function diffManifest(manifest, recommended) {
+  const recByKey = new Map(recommended.map(s => [
+    s.kind === 'baseline' ? `baseline:${sanitizeSlug(s.name)}` : `${s.source}/${s.name}`,
+    s,
+  ]));
+  const installedByKey = new Map(manifest.installed.map(e => [entryKey(e), e]));
+
+  const add = [];
+  const remove = [];
+  const unchanged = [];
+
+  for (const [key, skill] of recByKey) {
+    if (installedByKey.has(key)) {
+      unchanged.push(skill);
+    } else {
+      add.push(skill);
+    }
+  }
+  for (const [key, entry] of installedByKey) {
+    if (entry.kind === 'baseline') continue; // baseline always stays
+    if (!recByKey.has(key)) remove.push(entry);
+  }
+  return { add, remove, unchanged };
+}
+
+function sanitizeSlug(name) {
+  return name.toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '');
+}
+
+export const _internal = { normalizeList, sanitizeSlug, entryKey, MAX_SKILLS, API_BASE, MANIFEST_FILE };

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "clud-bug",
+  "version": "0.2.0",
+  "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",
+  "type": "module",
+  "license": "MIT",
+  "author": "thrillmot",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thrillmot/clud-bug.git"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "github-action",
+    "code-review",
+    "pull-request",
+    "ai",
+    "skills"
+  ],
+  "bin": {
+    "clud-bug": "./bin/clud-bug.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "prepublishOnly": "npm test"
+  }
+}

package/templates/skills/baseline/critical-issues-only.md

@@ -0,0 +1,28 @@
+---
+name: critical-issues-only
+description: PR review discipline - flag only correctness, security, and performance issues. Skip nits.
+---
+
+# Critical issues only
+
+When reviewing a pull request, only surface issues that fall into one of these buckets:
+
+1. **Correctness bugs** — the code does the wrong thing, mishandles a case, or breaks an existing contract.
+2. **Security vulnerabilities** — injection, auth bypass, secret exposure, unsafe deserialization, SSRF, etc.
+3. **Performance problems** — algorithmic blowups, N+1 queries, memory leaks, blocking calls in hot paths.
+4. **Missing or broken test coverage** for new code paths that meaningfully change behavior.
+
+## Do not surface
+
+- Style preferences, formatting, naming preferences.
+- Architectural rewrites unless the existing approach is actively broken.
+- "You could also..." suggestions that aren't bugs.
+- Nitpicks the author can fix in 30 seconds and don't change behavior.
+
+## How to phrase findings
+
+- One concrete issue per comment. No bundling unrelated nits.
+- Quote the specific line or block being criticized.
+- Say what's wrong, then what to do about it. Skip the throat-clearing.
+
+If the diff has no issues in the four buckets above, post a single short comment confirming that — don't invent problems.

package/templates/skills/baseline/evidence-based-review.md

@@ -0,0 +1,29 @@
+---
+name: evidence-based-review
+description: Every PR review claim must quote the specific code being criticized. No hand-waving.
+---
+
+# Evidence-based review
+
+Every claim in your review must be backed by evidence the PR author can verify in seconds.
+
+## Required for every finding
+
+- **Quote the exact line or block** you're talking about (use a fenced code block or `gh pr` inline-comment anchor).
+- **Cite the file and line range** so the author can navigate directly there.
+- **State the failure mode concretely**: what input produces what wrong output, or what attacker action exploits what gap.
+
+## Banned phrasings
+
+These are red flags that you're hand-waving instead of reviewing:
+
+- "This might cause issues" → say *which* issue, with the input that triggers it.
+- "Consider refactoring this" → either it has a bug, or it doesn't. Not your call to redesign their code.
+- "This doesn't follow best practices" → cite *which* practice and why it matters here.
+- "You should add tests" → name the specific code path that isn't covered.
+
+## Verifying your own claims
+
+Before posting a comment, ask: if the author asked "show me", could I point at the exact line and exact failure case? If not, delete the comment.
+
+A short, specific review of three real issues beats a long, vague review of fifteen maybes.

package/templates/skills/baseline/respect-existing-conventions.md

@@ -0,0 +1,27 @@
+---
+name: respect-existing-conventions
+description: Don't suggest changes that fight the codebase's established patterns. Match what's already there.
+---
+
+# Respect existing conventions
+
+A code review is not a redesign. The PR author is working within a codebase that has its own conventions, abstractions, and trade-offs that long predate this PR.
+
+## Before suggesting any change, check
+
+- **Is this pattern already used elsewhere in the repo?** If yes, the author is following convention. Don't push them off it.
+- **Did the team explicitly choose this approach?** Look at neighboring files, git log on related code, or comments. If the surrounding code already does it this way, that's a signal.
+- **Would adopting your suggestion require changing 50 other files?** If yes, your suggestion belongs in a separate refactor PR or RFC, not this review.
+
+## Things that often *look* like problems but usually aren't
+
+- Manual loops where a `.map()` would also work — both are fine.
+- Repeated three-line patterns that "could be a helper" — three is below the threshold to justify abstraction.
+- Type annotations the language can infer — explicitness is a valid choice.
+- Defensive null checks at module boundaries — context-dependent.
+
+## When convention itself is the bug
+
+If the existing pattern *is* the source of the bug, say so explicitly: "the convention used here propagates [specific bug]; this PR should break from it because [reason]." Don't quietly suggest a different approach without naming the trade-off.
+
+The bar for "you should do it differently than the rest of the codebase" is high. Clear it before suggesting.

package/templates/workflow-py.yml.tmpl

@@ -0,0 +1,71 @@
+name: Clud Bug 🐛 Crawls Your Code
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  clud-bug-review:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: anthropics/claude-code-action@v1
+        env:
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          track_progress: true
+          claude_args: |
+            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr review:*),Bash(gh api graphql:*),Bash(gh api repos/:*)"
+          prompt: |
+            {{PROJECT_DESCRIPTION}}
+
+            Review this pull request for critical issues only. Focus on:
+            - Bugs, logic errors, or incorrect behaviour
+            - Security vulnerabilities
+            - Performance problems
+            - Incorrect exception handling (bare excepts, swallowed errors, wrong exception types)
+            - Missing type hints on new functions
+            - Incorrect use of Click (exit codes, error messages) if the project uses it
+            - Missing pytest coverage for new code
+            {{LANGUAGE_HINTS}}
+
+            Skip style suggestions, minor naming issues, or anything that
+            doesn't affect correctness, security, or performance.
+
+            Any project-specific skills loaded from .claude/skills/ should
+            shape your review — defer to their guidance over generic advice.
+
+            When you finish, post your review as a single PR comment.
+            The comment body MUST start with this exact line so the
+            project's identity is visible (the bot account will say
+            claude[bot], but the comment header brands it as Clud Bug):
+
+              ## 🐛 Clud Bug review
+
+            Post it via:
+              gh pr comment "$PR_NUMBER" --body "<your review>"
+
+            If you previously reviewed this PR (you'll see prior claude[bot]
+            comments starting with "## 🐛 Clud Bug review"), resolve your
+            prior unresolved inline review threads where the flagged issue
+            is fixed in the current diff. List threads:
+
+              gh api graphql -f query='{ repository(owner: "${{ github.repository_owner }}", name: "${{ github.event.repository.name }}") { pullRequest(number: '"$PR_NUMBER"') { reviewThreads(first: 30) { nodes { id isResolved comments(first: 1) { nodes { body author { login } } } } } } } }'
+
+            For each unresolved thread you (claude[bot]) authored where the
+            issue is now addressed:
+
+              gh api graphql -f query='mutation { resolveReviewThread(input: {threadId: "<id>"}) { thread { isResolved } } }'
+
+            Only resolve threads where the fix is verifiable in the diff.
+            Leave unresolved any thread whose issue still stands.
+            For line-specific issues, use the github_inline_comment MCP tool
+            with confirmed: true.
+            If there are no critical issues, post a one-line comment saying so.

package/templates/workflow-ts.yml.tmpl

@@ -0,0 +1,72 @@
+name: Clud Bug 🐛 Crawls Your Code
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  clud-bug-review:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: anthropics/claude-code-action@v1
+        env:
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          track_progress: true
+          claude_args: |
+            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr review:*),Bash(gh api graphql:*),Bash(gh api repos/:*)"
+          prompt: |
+            {{PROJECT_DESCRIPTION}}
+
+            Review this pull request for critical issues only. Focus on:
+            - Bugs, logic errors, or incorrect behaviour
+            - Security vulnerabilities
+            - Performance problems
+            - Broken or missing test coverage for new code
+            - TypeScript type safety issues (unsafe casts, missing types, incorrect generics)
+            - Incorrect ESM/CJS module usage
+            - Improper async/await or Promise handling (unhandled rejections, missing awaits)
+            - Incorrect use of common Node.js patterns
+            {{LANGUAGE_HINTS}}
+
+            Skip style suggestions, minor naming issues, or anything that
+            doesn't affect correctness, security, or performance.
+
+            Any project-specific skills loaded from .claude/skills/ should
+            shape your review — defer to their guidance over generic advice.
+
+            When you finish, post your review as a single PR comment.
+            The comment body MUST start with this exact line so the
+            project's identity is visible (the bot account will say
+            claude[bot], but the comment header brands it as Clud Bug):
+
+              ## 🐛 Clud Bug review
+
+            Post it via:
+              gh pr comment "$PR_NUMBER" --body "<your review>"
+
+            If you previously reviewed this PR (you'll see prior claude[bot]
+            comments starting with "## 🐛 Clud Bug review"), resolve your
+            prior unresolved inline review threads where the flagged issue
+            is fixed in the current diff. List threads:
+
+              gh api graphql -f query='{ repository(owner: "${{ github.repository_owner }}", name: "${{ github.event.repository.name }}") { pullRequest(number: '"$PR_NUMBER"') { reviewThreads(first: 30) { nodes { id isResolved comments(first: 1) { nodes { body author { login } } } } } } } }'
+
+            For each unresolved thread you (claude[bot]) authored where the
+            issue is now addressed:
+
+              gh api graphql -f query='mutation { resolveReviewThread(input: {threadId: "<id>"}) { thread { isResolved } } }'
+
+            Only resolve threads where the fix is verifiable in the diff.
+            Leave unresolved any thread whose issue still stands.
+            For line-specific issues, use the github_inline_comment MCP tool
+            with confirmed: true.
+            If there are no critical issues, post a one-line comment saying so.

package/templates/workflow.yml.tmpl

@@ -0,0 +1,68 @@
+name: Clud Bug 🐛 Crawls Your Code
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  clud-bug-review:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: anthropics/claude-code-action@v1
+        env:
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          track_progress: true
+          claude_args: |
+            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr review:*),Bash(gh api graphql:*),Bash(gh api repos/:*)"
+          prompt: |
+            {{PROJECT_DESCRIPTION}}
+
+            Review this pull request for critical issues only. Focus on:
+            - Bugs, logic errors, or incorrect behaviour
+            - Security vulnerabilities
+            - Performance problems
+            - Broken or missing test coverage for new code
+            {{LANGUAGE_HINTS}}
+
+            Skip style suggestions, minor naming issues, or anything that
+            doesn't affect correctness, security, or performance.
+
+            Any project-specific skills loaded from .claude/skills/ should
+            shape your review — defer to their guidance over generic advice.
+
+            When you finish, post your review as a single PR comment.
+            The comment body MUST start with this exact line so the
+            project's identity is visible (the bot account will say
+            claude[bot], but the comment header brands it as Clud Bug):
+
+              ## 🐛 Clud Bug review
+
+            Post it via:
+              gh pr comment "$PR_NUMBER" --body "<your review>"
+
+            If you previously reviewed this PR (you'll see prior claude[bot]
+            comments starting with "## 🐛 Clud Bug review"), resolve your
+            prior unresolved inline review threads where the flagged issue
+            is fixed in the current diff. List threads:
+
+              gh api graphql -f query='{ repository(owner: "${{ github.repository_owner }}", name: "${{ github.event.repository.name }}") { pullRequest(number: '"$PR_NUMBER"') { reviewThreads(first: 30) { nodes { id isResolved comments(first: 1) { nodes { body author { login } } } } } } } }'
+
+            For each unresolved thread you (claude[bot]) authored where the
+            issue is now addressed:
+
+              gh api graphql -f query='mutation { resolveReviewThread(input: {threadId: "<id>"}) { thread { isResolved } } }'
+
+            Only resolve threads where the fix is verifiable in the diff.
+            Leave unresolved any thread whose issue still stands.
+            For line-specific issues, use the github_inline_comment MCP tool
+            with confirmed: true.
+            If there are no critical issues, post a one-line comment saying so.