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
npx skills add zernie/vigiles --skill dogfood-cli -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/dogfood-cli/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/dogfood-cli/
1Skills CLI (Vercel)
npx skills add zernie/vigiles --skill dogfood-cli -a codex2Manually: put the files in place
.agents/skills/dogfood-cli/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add zernie/vigiles --skill dogfood-cli -a cursor2Manually: put the files in place
.cursor/skills/dogfood-cli/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install zernie/vigiles .claude/skills/dogfood-cli2Manually: put the files in place
.github/skills/dogfood-cli/SKILL.md1Skills CLI (Vercel)
npx skills add zernie/vigiles --skill dogfood-cli -a gemini-cli2Platform CLI
gemini skills install https://github.com/zernie/vigiles --path .claude/skills/dogfood-cliManually: put the files in place
.devin/skills/dogfood-cli/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add zernie/vigiles --skill dogfood-cli -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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