The Groundwork CLI

A deterministic detector for context-engineering anti-patterns. No LLM. Eighteen rules, JSON output, milliseconds. The thing you wire into CI so drift never ships.

Install and run

npx @ignitic/groundwork detect           # scan current directory
npx @ignitic/groundwork detect /path/to/repo
npx @ignitic/groundwork detect --json > findings.json
npx @ignitic/groundwork detect --fail-on P1
npx @ignitic/groundwork detect --only stale-claude-md,secrets-regex
npx @ignitic/groundwork list-rules

Node 18 or later. Two dependencies. MIT. Or npm i -g @ignitic/groundwork for a global install.

Flags

Flag	What it does
`--json`	Machine-readable output for CI logs or your reporting layer.
`--fail-on <sev>`	Exit non-zero at this severity or worse. Default `P0`.
`--only <rules>`	Comma-separated rule IDs. Runs only the rules you name.
`list-rules`	Prints every rule the CLI knows about, with default severity.

The eighteen rules

Rule	Severity	What it catches
`stale-claude-md`	P0	`CLAUDE.md` / `AGENTS.md` names a package manager or framework not in `package.json`.
`verification-command-missing`	P0	The Verification section names a command (`pnpm test`, `make build`) that does not resolve to a real script in `package.json` / `Makefile` / `pyproject.toml` / `Cargo.toml` / `go.mod`.
`skill-missing-frontmatter`	P0	A `SKILL.md` is missing YAML frontmatter, or `name` / `description` is missing or empty. The host harness cannot route invocations.
`mcp-literal-credentials`	P0	MCP config contains literal credentials instead of env var references.
`placeholder-comments`	P0	`TODO: implement`, `[fill this in]`, `not implemented` in source.
`secrets-regex`	P0	AWS, GitHub, OpenAI, Anthropic, Slack, PEM, JWT, Google keys in committed files.
`oversized-claude-md`	P1	`CLAUDE.md` / `AGENTS.md` over 200 lines. Push overflow into `docs/agents/`.
`missing-verification`	P1	Per-harness file has no Verification section.
`agents-claude-sync`	P1	`AGENTS.md` and `CLAUDE.md` diverge as separate files.
`agents-md-duplication`	P1	The same rule restated under two H2 sections. Plan-mode triggers belong only in Boundaries → Ask first; verification belongs only in Non-negotiables.
`agents-md-vague-rules`	P1	A Style rule uses vague phrasing ("write clean code", "use good judgment", "follow best practices") instead of a verb plus a named technology, command, or pattern.
`skill-oversized`	P1	A `SKILL.md` entry point over 200 prose lines (code excluded). Move detail into sub-files referenced from `SKILL.md`.
`skill-broken-link`	P1	A relative-path link in `SKILL.md` does not resolve to a real file or directory. The agent reads nothing where it expects content.
`missing-adr-xref`	P2	Decision-shaped statements without an ADR cross-link.
`missing-license-header`	P2	Copyleft repo, source files missing SPDX headers.
`todo-comments`	P2	`TODO` / `FIXME` / `HACK` markers above the noise threshold (25).
`oversized-cursor-rule`	P2	`.cursor/rules/*.mdc` exceeds the word budget for its trigger level (P1 if `alwaysApply: true`).
`skill-vague-description`	P2	A skill's frontmatter `description` uses hedge phrasing ("various", "helps with", "useful for"). The host cannot route by intent.

Severity bands

P0. Fix before the next agent session. Agent will actively do the wrong thing.
P1. Fix this sprint. Silent drift over weeks.
P2. Backlog. Hygiene.

Output

P0 2 findings
  ● stale-claude-md CLAUDE.md
    CLAUDE.md mentions "yarn" but package.json declares packageManager: pnpm.
    fix: Run: groundwork document
  ● secrets-regex src/config.ts:14
    Possible GitHub personal access token in committed file.
    > const token = "ghp_****************dEf"
    fix: Rotate the credential and remove from history (BFG / git-filter-repo).

18 rules, 47ms · 2 P0 · 0 P1 · 0 P2

For build gates, pipe with --json into your reporting layer. Each finding includes ruleId, severity, file, message, and fix.

Ignoring findings

The detector skips node_modules, .git, dist, build, .next, .turbo, coverage, .cache, target, __pycache__, and vendor automatically. For the four pattern-matching rules (placeholder-comments, secrets-regex, mcp-literal-credentials, todo-comments), use inline markers:

// ce-ignore: test fixture, not a real secret
const aws_key = "AKIAIOSFODNN7EXAMPLE";

// ce-ignore-file: vendored, do not edit  (anywhere in first 5 lines)

Structural rules (file length, missing sections, drift) do not honour these markers. Fix the underlying issue or use --only.

CI integration

- name: groundwork
  run: npx @ignitic/groundwork detect --fail-on P1

Start with --fail-on P0 on a repo with known P1 findings. Move to P1 once the backlog is clear. The detector runs under 100ms on a medium repo. Run it after tests and lint, not before: it is about context-file hygiene, not code correctness.

For the pre-commit side, the verify skill command writes both the detector hook and a project-specific drift script.