Agent Code Guard

Human and agent workflow

This guide owns the repeated-use workflow for Agent Code Guard. The usage guide remains the CLI reference, and skill distribution explains skill discovery and activation.

Human setup and decisions

Install the published command in an isolated environment and verify the active installation:

pipx install agent-code-guard
code-guard --version
code-guard doctor

Ask your coding agent to locate the bundled version-matched skill with code-guard --skill-path and adopt the workflow below without creating an adoption baseline. Decide whether checks remain manual or use an optional platform hook. Exporting a skill into a persistent directory, installing a hook, or changing persistent user or repository configuration requires your authorization.

Require the agent to report its final result and any REVIEW findings it accepts with justification. Use CI as the final gate, not as a substitute for checks during development.

An explicitly reviewed, cohesive oversized Markdown document can use the document-size ratchet after acceptance is authorized. Ordinary checks never create or update a baseline. Unchanged or smaller accepted documents pass the document guard; growth returns REVIEW, and section findings remain independent. Do not use baseline updates to hide new growth or treat document acceptance as a section exemption.

The shared loop

edit supported code or Markdown
        ↓
run Code Guard on changed scope
        ↓
PASS → continue
REVIEW → inspect, justify or genuinely improve
FAIL → fix or obtain an explicitly authorized exception
INCOMPLETE → preserve completed evidence and restore unavailable syntax analysis
        ↓
rerun
        ↓
report the result before completion

After each meaningful turn that changes supported source code or Markdown, the agent runs Code Guard. It inspects every REVIEW and FAIL, loads only policies named by the result, and refactors only when doing so improves real structure. It must never split code mechanically or weaken thresholds, exclusions, configuration, or baselines to silence a measurement. After relevant corrections it reruns the check, and it always runs a final check before declaring completion.

PASS means continue. REVIEW means inspect and either make a genuine improvement or retain the code with an honest justification; it is not automatically a defect. FAIL blocks normal completion until corrected or covered by an explicitly authorized policy exception. INCOMPLETE means a known per-file syntax or provider failure prevented some syntax evidence; independent completed evidence remains authoritative, but the run blocks with exit 3. An argparse usage or invalid-choice error exits 2 with usage/error text on stderr and no completed report. Other Code Guard tool, configuration, scope, or unexpected errors exit 3 without an incomplete report.

Manual agent loop

In a Git repository, prefer changed-work scope and compact JSON when structured, low-noise output helps:

code-guard . --changed-only --json --json-mode compact

Git supplies staged, unstaged, and untracked candidates within the positional bounds. The process exits are exact:

• PASS: 0
• REVIEW: 1, or 0 with --ci
• completed FAIL: 2
• INCOMPLETE: 3, with retained completed evidence and unavailable records
• argparse usage/invalid-choice error: 2, stderr usage/error, no completed report
• other Code Guard tool/configuration/scope/unexpected error: 3

The agent inspects REVIEW and FAIL findings, applies judgment, loads only the named required policies, and reruns after relevant correction.

Git selection requires a Git repository and fails instead of silently becoming a recursive audit. Outside Git, pass the exact edited files:

code-guard path/to/edited.py docs/edited.md --json --json-mode compact

Do not recursively scan the whole tree after every turn.

Optional hook-assisted loop

Agent Code Guard does not install or manage hooks. If the coding-agent platform supports a post-edit or post-turn hook, and the user authorizes the persistent configuration change, that platform may invoke:

code-guard . --changed-only --ci --json --json-mode compact

--ci changes only REVIEW’s process exit from 1 to 0. REVIEW findings remain visible and require inspection. Completed FAIL remains 2; INCOMPLETE and other tool errors remain 3; argparse usage or invalid-choice errors remain 2 with stderr usage/error and no completed report. Hook output must not be suppressed.

Hook syntax and configuration paths are platform-specific. The agent must consult its platform’s own documentation; no universal hook configuration is implied. Outside Git, the integration must supply the exact edited files.

Completion and CI

Before completion, rerun Code Guard on the complete changed scope. Report the aggregate result, any FAIL, INCOMPLETE, or tool errors, and each accepted REVIEW with its reason. Then use the repository’s CI integration as the final gate. Humans remain responsible for deciding whether accepted REVIEW pressure warrants follow-up work and for authorizing exceptions or persistent integrations.