Skip to main content
skill CX Codex

dogfood-cli — Claude Code skill: what it does, how to install

dogfood-cli audits the vigiles CLI against itself using parallel agents, traces bugs to exact lines, and applies direct fixes.

MIT 120 installs ★ 16 updated 2026-10-14

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add zernie/vigiles --skill dogfood-cli -a claude-code
Open on GitHub

What dogfood-cli does

This workflow partitions inspection surfaces across parallel agents without overlap. Separate workers tackle round-trip compilation, audit false positives, configuration parsing in .vigilesrc.json, and terminal error output. Agents must link every confirmed flaw to an exact file:line location alongside an actionable patch.

The process mandates reproducing each finding before writing production code, discarding items that fail on a fixture. Instead of filing tracker issues for deterministic bugs, the workflow applies fixes straight away. Every theme gets a dedicated unit assertion, builds via npm run build, verifies through targeted vitest, and commits with Conventional Commit headers.

Edits modifying shared roots such as src/cli.ts or src/scan-core.ts demand sequential handling or git worktree isolation. End-to-end checks execute dist/cli.js directly, making a fresh compile mandatory whenever source code changes.

What it helps with

  • audit the tool against itself across segregated surfaces
  • pinpoint defect origins to precise file paths and lines
  • eliminate false positive matches inside source comments and globs
  • verify scanning output parity between disk and browser routines

Example prompts for the agent

  • Dogfood the CLI across all modules and trace bugs to source lines
  • Audit audit false-positives on real plugins and prepare direct patches
  • Verify cross-harness parity between scanFiles and scanPlugin

How to install dogfood-cli

1Skills CLI (Vercel)

npx skills add zernie/vigiles --skill dogfood-cli -a claude-code

2Manually: put the files in place

~/.claude/skills/dogfood-cli/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/dogfood-cli/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about dogfood-cli

How to install dogfood-cli in Claude Code?

Run npx skills add zernie/vigiles --skill dogfood-cli -a claude-code from your terminal.

What does the dogfood-cli skill do?

It orchestrates multi-agent dogfooding runs on the vigiles codebase, enforcing source-traced reproductions and immediate code repairs with regression tests.

Why is running a full test suite required before pushing changes?

Strict assertions located in separate test files can break when install commands or formats change, which isolated per-file test runs frequently miss.

Source text

SKILL.md · MIT
---
name: dogfood-cli
description: Hunt for real bugs in the vigiles CLI/codebase with a parallel expert fan-out, then FIX them directly — source-trace each defect to file:line, add a regression test, commit per theme. Use when asked to dogfood vigiles, find/fix bugs across the CLI the source-traced way, or fan out agents to audit the tool on itself.
disable-model-invocation: true
---

# Dogfood the vigiles CLI (expert find + fix fan-out)

The repeatable method for finding real bugs in vigiles by running the tool on
itself and on real plugins, then FIXING them — not filing them. This is how the
2026-07 batch found and fixed 14 source-traced bugs.

## When to use

- "Dogfood the CLI", "find more bugs the source-traced way", "fan out agents to
  audit vigiles on itself", "hunt for false positives in audit/lint".
- NOT for a single known bug (just fix it) and NOT for shipped consumer features
  (this is a contributor-only dev process; `.claude/` is not published).

## The loop

```
fan out (parallel experts) → synthesize + VERIFY each finding → fix directly
   → regression test → build → targeted test → commit per theme → FULL SUITE → push
```

### 1. Fan out over DISTINCT surfaces

Spawn several agents (Sonnet — cheap parallel reads/traces; no synthesis needed
per agent), each owning ONE surface so they don't overlap. The surface map that
has paid off:

- **compile / eject** — round-trip correctness, frontmatter/data loss, integrity.
- **audit / lint false-positives** — a real plugin must stay CLEAN (don't cry
  wolf); phantom paths; glob/quote tokens misread; comment-only matches.
- **init / scaffold edge cases** — no `package.json`, config-driven `harness`,
  malformed frontmatter, `--target`, the scaffolded CI workflow, `--test`/`--lint`.
- **config parse-don't-validate** — `.vigilesrc.json` severities (`"off"`/0/1/2),
  string-or-array keys, unknown values.
- **CLI error UX** — an unknown flag/harness must print a clean message + exit 2,
  never a raw Node stack trace.
- **cross-harness (CC + Codex) + browser/disk parity** — `scanFiles` must match
  `scanPlugin` byte-for-byte; a Codex-shaped repo must not be scanned as CC.

Tell each agent: **SOURCE-TRACE every bug to `file:line` + a proposed fix.** A
finding without a trace is a lead, not a bug.

### 2. Synthesize + VERIFY yourself

Agents over-report. Before touching anything, reproduce each finding yourself
(run the real built CLI on a tmp fixture or a vendored `test/dogfood/*` plugin).
Discard what doesn't repro. Confirm the exact `file:line`.

### 3. FIX directly — don't file

A deterministic, source-traced bug needs **no issue**: fix it. File an issue ONLY
when the fix is genuinely **ambiguous** (several valid interpretations, or an
architecturally significant change the founder should weigh in on). "Fix, not
file" is the founder's standing call for this loop.

Per fix:

- **Repro → fix → regression test → `npm run build` → targeted `vitest` → commit.**
- **One theme per commit.** Conventional Commit subject; end the body with the
  `Co-Authored-By: Claude …` trailer. NEVER a session URL or a raw model id
  (public repo — see the `no-session-links` / model-identity rules).
- The fix must be **high-precision** — a false-positive fix must not silently
  UNDER-detect (don't trade crying wolf for missing the real thing).
- Honor the architecture: a shared detector has ONE home (`one-detector-no-drift`);
  `core ⊄ adapter`; no CC literal in `src/core/**` or the agnostic detectors.

## Hard-won discipline (the lessons)

- **Serialize/merge fixes that touch SHARED files** (`src/cli.ts`,
  `src/scan-core.ts`). Parallel edits to the same file conflict — do those
  sequentially, or give each agent its own git worktree (`isolation: "worktree"`).
- **RUN THE FULL SUITE before declaring done.** A strict assertion in an
  _unrelated_ test file can only surface in the whole run — the I2 fix changed an
  install command and a strict regex in a _different_ e2e file broke; per-file
  runs were all green, the full `vitest run` caught it.
- **Rebuild after every source edit** — the e2e tests run `dist/cli.js`, so a
  stale `dist/` silently tests the old code.
- **Watch the parity gate.** Any change to a scan detector must keep
  `scanFiles ↔ scanPlugin` byte-identical (`src/scan-files.test.ts`); if the disk
  side gains a field, the browser side needs it too.
- **Prettier + `fmt:check` before commit** — markdown code spans need surrounding
  spaces; CI runs `fmt:check`.
- **Coverage gate is an allowlist** (`vitest.config.ts` `coverage.include`) — a
  new file under it needs 100%; scan/cli files are NOT in it today.

## The two recurring bug classes — hunt for them, then PREVENT the class

Almost every bug this repo has produced is one of two shapes. When you find one
instance, GREP for its siblings, and add a GATE so the class can't come back.

### 1. An unverified assumption about an EXTERNAL contract

Code that guesses how an external thing behaves without checking: a CLI flag's
format (the `skills` `-s` was assumed comma-separated, is space-separated → the
install exited 1), a harness's frontmatter key (skills use `allowed-tools`, not
`tools:`), git's behavior (`git config origin` in a subdir walks UP to the parent
repo), module resolution (`vigiles` can't resolve without a package.json),
a linter's enabled-state (a checkstyle `severity=ignore` module is disabled).

- **PARSE, DON'T VALIDATE the boundary.** Read the REAL contract before coding —
  the tool's `--help`, its arg parser in `node_modules`, `git rev-parse`, the
  linter's own status logic. Don't guess; verify.
- **Add a UNIT assertion of the command/format's SHAPE**, not just a
  network/binary-gated e2e. The e2e that runs the real command SKIPS in dev (no
  network / no `claude` / no linter binary), so it's not a reliable guard — CI is
  the only place it runs. A unit test that parses the constructed command the SAME
  way the external tool does (e.g. the `-s` space-split assertion in
  `setup-plan.test.ts`) fails fast, offline, on a regression.

### 2. An incomplete fix — SOME call-sites of a pattern, not all

A pattern fixed in one place but left live elsewhere: `audit`/`init` honoured
`config.harness` but `test`/`eval`/`generate harness` didn't; `E1` fixed
`ScanAgent.path` but not the frontmatter-family findings; comment-stripping was
added to one detector but not the next.

- **GREP for every instance** of the pattern the moment you fix one.
- **MAKE-INVALID-STATES-IRREPRESENTABLE — one choke-point.** Route every caller
  through a single helper (e.g. `resolveCommandHarness`) so a new call-site can't
  bypass it, and add a gate test that FAILS if the old path reappears
  (`cli-harness-resolution.test.ts` asserts `cli.ts` never calls the raw detector).
- Detectors that scan raw text share a hazard (matching inside comments /
  examples / illustrative prose) — check the shared text-context helpers exist and
  are REUSED, not re-copied per detector, and keep the FP-guard fixtures green.

## NOT this skill

The **blind-agent onboarding dogfood** (a fresh agent runs `npx vigiles init` on
a real repo across an OS matrix in GHA + a subscription eval) is a SEPARATE,
roadmapped e2e — do not fold its OS-matrix here. This skill is the in-repo
find+fix loop; that one measures the cold onboarding experience end-to-end.

© zernie · MIT · zernie/vigiles

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set19

The whole set →
enforce-rules-format enforce-rules-format is a Claude Code skill that checks rule enforcement classes and suggests fixes for projects managing instructions with Vigiles. CX Codex +1 433installs generate-logo generate-logo generates logo variations for the vigiles project using the ImageRouter API. Useful when experimenting with visual branding or iterating on icons. CX Codex +1 410installs code-quality code-quality — a skill for refactoring TypeScript and JavaScript: tightens types, removes impossible states, and separates logic from IO. CX Codex +1 392installs audience-check audience-check reviews your README or documentation through six reader personas to reveal confusion points, missing definitions, and early drop-offs. CX Codex +1 387installs verify-docs-findable verify-docs-findable is a Claude Code skill that checks whether repo docs answer reader questions. Haiku agents read only the docs and show where answers get lost. CX Codex +1 340installs screenshot The screenshot skill renders local pages in Chromium and saves full-page desktop and mobile captures. Use it to inspect a landing page, report, or local dev server. CX Codex +1 337installs landing-site landing-site — a skill with UX and design rules for the vigiles.sh landing page. The agent reads it before editing site components, hero, or copy and checks every change against the standard. CX Codex +1 295installs add-a-linter The add-a-linter skill guides contributors through adding a linter to vigiles, including its adapter, registry entry, docs, tests, and CI checks. CX Codex +1 120installs

Project sponsors

Companies that keep this analytics open