check-agent-standards

model	sonnet
name	check-agent-standards
description	Audits current branch changes against local main for AGENTS.md conformance, reports violations inline (written report on request), and auto-fixes them. Use when asked to check agent standards, audit the branch against AGENTS.md, run a conformance check, or enforce project standards.

Check Agent Standards

Automatically audit the current branch's changes against AGENTS.md project standards, write a report, and fix all violations without intervention.

Prerequisites

• Must be in a git repository with a local main branch
• Must have an AGENTS.md file in the project root

Workflow

Step 1: Gather Context

1. Read AGENTS.md from the project root to understand all project standards.
2. Run git diff main...HEAD --name-only to list changed files.
3. Run git diff main...HEAD to get the full diff.
4. Run git log main..HEAD --oneline to understand commit history.
5. If no changes are found, report "No changes detected" and stop.

Step 2: Audit Changes

Check every changed file against all applicable rules from AGENTS.md. The audit must cover every section of AGENTS.md that applies to the changed files. The categories below are examples of common checks; always derive the actual checklist from the project's AGENTS.md, not from this list:

File & Naming Conventions:

• File naming matches conventions (PascalCase for components, camelCase for hooks/utils)
• Files are in the correct directories per architecture rules
• Test files are colocated with source

Code Standards:

• Formatting matches Prettier config (semi, quotes, trailing commas, print width, tab width)
• No any types: unknown with narrowing instead
• Props interfaces defined above components with Props suffix
• Type-only imports use import type { ... }
• Explicit return types on all exported functions
• JSDoc with @param and @returns on all exported functions and hooks
• No class components
• No console.log
• No React namespace imports (import React from 'react')
• Immutability: const by default, no mutation

Architecture:

• Pure functions extracted to /utils where possible
• State management follows hierarchy: URL params > Context > global store
• Path aliases use @/*

Testing:

• Changed util functions have corresponding test files
• Tests use describe blocks with descriptive it names (lowercase verbs)
• Pure functions have edge case and error handling coverage

Error Handling:

• Recoverable errors return null
• User feedback via callbacks or toasts, no silent swallowing

Step 3: Report Findings

Present the conformance report directly in the conversation as markdown. Do not write a file unless the user explicitly asks for one.

If the user requests a written report, save it to the project root as YYYY-MM-DD HHMM Conformance Report.md (e.g., 2026-02-13 1430 Conformance Report.md). Get the timestamp by running date "+%Y-%m-%d %H%M".

The report (whether inline or written) should follow this structure:

# Conformance Report

**Branch:** `<branch-name>`
**Date:** `<date>`
**Compared against:** `local main`
**Standards:** `AGENTS.md`

## Summary

- **Files changed:** <count>
- **Violations found:** <count>
- **Auto-fixable:** <count>
- **Manual review needed:** <count>

## Violations

### <filename>

| # | Rule | Severity | Description | Auto-fix |
|---|------|----------|-------------|----------|
| 1 | <AGENTS.md section> | error/warning | <description> | ✅/❌ |

## Actions Taken

- [ ] <description of each fix applied>

## Remaining Items

- [ ] <items requiring manual intervention, if any>

Step 4: Auto-Fix Violations

Apply the safe code-level fixes here. Formatting and lint auto-fixes are handled by the tool runs in Step 5, so do not run them separately in this step.

1. Missing return types: Add explicit return types to exported functions.
2. Missing JSDoc: Add JSDoc stubs with @param and @returns.
3. Type imports: Convert type-only imports to import type { ... }.
4. any types: Replace with unknown where safe (flag complex cases for manual review).
5. console.log: Remove from non-test files.
6. React namespace imports: Convert to named imports.
7. Missing tests: Create test file stubs for new utility functions.

Step 5: Run All Checks and Fix Issues

Run each check category in order below. After each run, if there are failures, fix the source code and re-run until the check passes (or flag as manual review if a fix is not safe). Do not proceed to the next category until the current one passes.

1. Formatting: Run the project formatter and verify no files changed.

   • Look in package.json scripts for a format command (e.g., npm run format, npx prettier --write .).
   • If files were reformatted, that counts as a fix; note it in the report.

2. Linting: Run the project linter and fix all errors and warnings.

   • Look in package.json scripts for a lint command (e.g., npm run lint).
   • First attempt auto-fix (e.g., npm run lint -- --fix), then manually fix any remaining issues.
   • Must pass with zero errors and zero warnings.

3. Unit Tests: Run the project unit test suite and fix all failures.

   • Look in package.json scripts for a test command (e.g., npm test, npm run test:unit, npx vitest run, npx jest).
   • Read failing test output carefully. Fix the source code, not the test expectations.
   • Re-run until all unit tests pass.

4. E2E Tests: Run the project E2E test suite and fix all failures.

   • Look in package.json scripts for an E2E command (e.g., npm run test:e2e, npx playwright test, npx cypress run).
   • If no E2E script exists, check for a playwright.config.* or cypress.config.* and run the appropriate CLI command.
   • If no E2E tests exist in the project, skip this step and note it in the report.
   • Read failing test output carefully. Fix the source code, not the test expectations.
   • Re-run until all E2E tests pass.

If any check cannot be made to pass after reasonable attempts, revert the offending changes and flag the issue for manual review in the report.

Step 6: Update Report

If a written report was requested, update it to reflect which fixes were applied and which items remain. Otherwise, present the updated status inline.

Important Rules

• Never leave the codebase broken. If a fix causes lint or test failures, revert it and mark as manual review.
• Do not modify test expectations to make tests pass; fix the source code instead.
• Do not touch files outside the branch diff unless running project-wide formatters.
• Be conservative with type changes: prefer flagging complex any replacements for manual review over introducing type errors.
• If a report file is written, add *Conformance Report.md to .gitignore if not already covered (it is a transient artifact).