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

> Execute verification commands from AGENTS.md for i-have-adhd. Follow our guide to run unittest discover, run_evals, check_context_compat, and claude plugin validate in sequence.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: how-to-guide
- Published: 2026-08-18

---

**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`](https://github.com/ayghri/i-have-adhd/blob/main/INSTALL.md):

```bash

# 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`](https://github.com/ayghri/i-have-adhd/blob/main/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.

```bash
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.

```bash
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`](https://github.com/ayghri/i-have-adhd/blob/main/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.

```bash
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`](https://github.com/ayghri/i-have-adhd/blob/main/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.

```bash
claude plugin validate .

```

**What it validates:**
- [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json) syntax and schema compliance
- Plugin entry point resolution
- Runtime loadability

The validator uses the manifest at [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.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:

```bash
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`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py) eval loading code |
| [`check_context_compat.ts`](https://github.com/ayghri/i-have-adhd/blob/main/check_context_compat.ts) error | TypeScript type error or import failure | [`scripts/check_context_compat.ts`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/check_context_compat.ts) compiler output |
| `claude plugin validate` rejection | Malformed [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json) or missing files | [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.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`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py)** — Evaluation driver with `validate` mode
- **[`scripts/check_context_compat.ts`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/check_context_compat.ts)** — TypeScript compatibility validator
- **[`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json)** — Plugin manifest validated by `claude plugin validate .`
- **[`AGENTS.md`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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.