How to Execute the Verification Commands Listed in AGENTS.md for i-have-adhd

Run the four verification commands from the AGENTS.md file in sequence: python3 -m unittest discover -s tests -v, python3 scripts/run_evals.py validate, bun scripts/check_context_compat.ts, and claude plugin validate .

The ayghri/i-have-adhd repository uses a multi-layer verification pipeline defined in AGENTS.md to ensure code correctness, runtime adapter compatibility, and plugin validity. This guide explains how to execute each AGENTS.md verification command with practical examples and troubleshooting context.

Prerequisites for Running Verification Commands

Before executing the verification commands, ensure your environment matches the repository requirements. The codebase relies on Python 3, Bun (JavaScript/TypeScript runtime), and the Claude CLI for plugin validation.

Install dependencies according to INSTALL.md:

# Verify Python 3 is available

python3 --version

# Verify Bun is installed

bun --version

# Verify Claude CLI is available

claude --version

All commands assume you run them from the repository root where AGENTS.md is located.

The Four Verification Commands from AGENTS.md

The AGENTS.md verification section (lines 52–59) documents four distinct checks. Each targets a specific subsystem of the project.

1. Unit Test Discovery with Verbose Output

Command: python3 -m unittest discover -s tests -v

This command discovers and executes all unit tests in the tests/ directory using Python's built-in test framework with verbose reporting.

python3 -m unittest discover -s tests -v

What it validates:

• Core Python module functionality
• Adapter logic correctness
• Data processing pipeline integrity

Expected output: A list of test case names with OK or FAIL status for each. The -v flag ensures you see individual test names, not just a summary count.

2. Evaluation Script Validation Mode

Command: python3 scripts/run_evals.py validate

This runs the repository's evaluation driver in validation mode, which checks model-specific evaluation suites without running full evaluations.

python3 scripts/run_evals.py validate

What it validates:

• Evaluation configuration integrity
• Model adapter availability
• Dataset loading and preprocessing logic

The scripts/run_evals.py file defines multiple modes; validate is the mode used specifically for verification purposes per AGENTS.md.

3. TypeScript Context Compatibility Check

Command: bun scripts/check_context_compat.ts

This command uses the Bun runtime to execute a TypeScript file that validates context-compatibility layers compile and pass internal checks.

bun scripts/check_context_compat.ts

What it validates:

• TypeScript compilation of compatibility shims
• Cross-context API surface consistency
• Linting and type safety of adapter code

The scripts/check_context_compat.ts script ensures that code running in different JavaScript contexts (browser, Node.js, Bun, etc.) remains compatible.

4. Claude Plugin Manifest Validation

Command: claude plugin validate .

This invokes the Claude CLI plugin validator to verify that plugin manifest files in the current directory are well-formed and loadable.

claude plugin validate .

What it validates:

• .claude-plugin/plugin.json syntax and schema compliance
• Plugin entry point resolution
• Runtime loadability

The validator uses the manifest at .claude-plugin/plugin.json to determine validation rules.

Running All Verification Commands Together

For CI pipelines or pre-commit checks, chain the AGENTS.md verification commands with && to fail fast on any error:

python3 -m unittest discover -s tests -v && \
    python3 scripts/run_evals.py validate && \
    bun scripts/check_context_compat.ts && \
    claude plugin validate .

This sequence respects dependencies: Python unit tests and evaluations run first, then TypeScript compatibility, finally plugin validation.

Troubleshooting Failed Verifications

When a command fails, the error output indicates which subsystem needs attention:

Failure Point	Likely Cause	Investigation Start
unittest errors	Python logic bug or missing dependency	tests/ directory, traceback file:line
run_evals.py validate fails	Configuration or adapter issue	scripts/run_evals.py eval loading code
check_context_compat.ts error	TypeScript type error or import failure	scripts/check_context_compat.ts compiler output
claude plugin validate rejection	Malformed plugin.json or missing files	.claude-plugin/plugin.json schema

The AGENTS.md verification commands are designed to provide actionable diagnostics. Always run with full output (the -v flag for tests, default verbosity for others) to capture context.

Key Source Files Referenced

Understanding these files helps interpret verification results:

• tests/ — Unit test suite executed by the first command
• scripts/run_evals.py — Evaluation driver with validate mode
• scripts/check_context_compat.ts — TypeScript compatibility validator
• .claude-plugin/plugin.json — Plugin manifest validated by claude plugin validate .
• AGENTS.md (lines 52–59) — Canonical documentation of the verification command list

Summary

• Execute AGENTS.md verification commands in sequence from the repository root
• Use python3 -m unittest discover -s tests -v for Python unit tests
• Use python3 scripts/run_evals.py validate for evaluation suite validation
• Use bun scripts/check_context_compat.ts for TypeScript compatibility
• Use claude plugin validate . for plugin manifest verification
• Chain with && for automated pipelines that fail fast on errors

Frequently Asked Questions

Can I run a single verification command without the others?

Yes. Each AGENTS.md verification command is independent. Run only the command relevant to your changes: use the unittest command for Python modifications, the Bun command for TypeScript changes, and the Claude command for plugin configuration updates.

What if I don't have Bun installed?

The bun scripts/check_context_compat.ts command specifically requires the Bun runtime. If Bun is unavailable, you cannot execute this verification step. See INSTALL.md in the ayghri/i-have-adhd repository for Bun installation instructions.

How do I interpret verbose unittest output?

The -v flag prints each test name followed by OK, FAIL, or ERROR. A FAIL indicates an assertion that did not match expected output; ERROR indicates an exception during test execution. The file path and line number in the traceback point to the failing test code or the source code being tested.

Does the validation order in AGENTS.md matter?

The documented order in AGENTS.md proceeds from core Python logic (tests, evaluations) to TypeScript compatibility to plugin validation. This reflects typical dependency layers: Python failures likely affect downstream checks, so running in order helps isolate root causes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}