# CI/CD Pipeline for i-have-adhd: GitHub Actions Workflow Guide

> Explore the CI/CD pipeline for i-have-adhd. Learn how GitHub Actions automates validation for OpenCode plugins, Pi runtime extensions, Cursor skills, and Claude compatibility on every push and pull request.

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

---

**The i-have-adhd repository uses GitHub Actions as its complete CI/CD pipeline, with four workflow files in `.github/workflows/` that validate OpenCode plugins, Pi runtime extensions, Cursor skills, and Claude compatibility on every push and pull request.**

The ayghri/i-have-adhd project automates quality assurance through a comprehensive, version-controlled CI/CD pipeline. Every commit triggers automated checks across multiple AI coding platforms, ensuring that plugin manifests, TypeScript extensions, and Python test suites meet strict compatibility requirements before merging.

## GitHub Actions Workflow Structure

The CI/CD pipeline for i-have-adhd consists of four distinct workflow files, each targeting a specific runtime or platform. All workflows trigger on `push` and `pull_request` events and execute on the latest Ubuntu runner.

- **[`plugin-load-check.yml`](https://github.com/ayghri/i-have-adhd/blob/main/plugin-load-check.yml)** – Validates the **OpenCode plugin** by verifying [`opencode.json`](https://github.com/ayghri/i-have-adhd/blob/main/opencode.json) and executing [`tests/test_opencode_plugin.py`](https://github.com/ayghri/i-have-adhd/blob/main/tests/test_opencode_plugin.py).
- **[`pi-load-check.yml`](https://github.com/ayghri/i-have-adhd/blob/main/pi-load-check.yml)** – Checks the **Pi runtime package** (defined in [`package.json`](https://github.com/ayghri/i-have-adhd/blob/main/package.json) with the `"pi"` entry) and ensures the TypeScript extension at [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) compiles and loads correctly.
- **[`cursor-skill-sync.yml`](https://github.com/ayghri/i-have-adhd/blob/main/cursor-skill-sync.yml)** – Maintains parity between the canonical skill definition at [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) and the Cursor-compatible copy at [`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md).
- **[`claude.yml`](https://github.com/ayghri/i-have-adhd/blob/main/claude.yml)** – Executes `claude plugin validate .` to confirm Claude-specific plugin adherence and runs associated sanity checks.

Each workflow is defined as YAML under `.github/workflows/`, making the pipeline fully transparent and auditable alongside the source code.

## Pipeline Execution Flow

The CI/CD pipeline for i-have-adhd follows a strict seven-stage execution sequence that aborts on the first failure. This fail-fast approach ensures that only code passing all validations reaches the main branch.

### 1. Repository Checkout

The pipeline checks out the exact commit that triggered the workflow, ensuring tests run against the precise code state proposed for merge.

### 2. Environment Setup

**Node.js** and **Python** environments are initialized using `actions/setup-node` and `actions/setup-python`, configured to match the versions declared in [`package.json`](https://github.com/ayghri/i-have-adhd/blob/main/package.json) and [`requirements.txt`](https://github.com/ayghri/i-have-adhd/blob/main/requirements.txt).

### 3. Dependency Installation

The workflow installs exact dependency trees to guarantee reproducible builds:
- `npm ci` installs Node dependencies using the lockfile.
- `pip install -r requirements.txt` installs Python packages required for the test suite.

### 4. Static Analysis

Code style and format validation run via `npm run lint` (or equivalent), enforcing consistent formatting across TypeScript and Python files.

### 5. Unit and Integration Testing

The pipeline executes the full Python test suite and TypeScript compilation checks:
- `python3 -m unittest discover -s tests -v` runs unit tests for core logic and plugin drivers.
- [`scripts/check_context_compat.ts`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/check_context_compat.ts) verifies that OMP and Pi extensions compile without type errors.

### 6. Plugin Validation

Platform-specific validators confirm manifest integrity:
- `npx @opencode-ai/plugin validate .` checks OpenCode plugin structure.
- `claude plugin validate .` verifies Claude manifest compliance.

### 7. Result Reporting

Failures surface immediately in the GitHub UI, with detailed logs attached to the specific workflow step that encountered the error. Successful runs provide a green checkmark required for merge qualification.

## OpenCode Plugin Validation Details

In [`.github/workflows/plugin-load-check.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/plugin-load-check.yml), the pipeline specifically targets the OpenCode ecosystem. The workflow validates [`opencode.json`](https://github.com/ayghri/i-have-adhd/blob/main/opencode.json) to ensure the plugin manifest contains required fields and valid entry points. It then executes [`tests/test_opencode_plugin.py`](https://github.com/ayghri/i-have-adhd/blob/main/tests/test_opencode_plugin.py) to verify that the plugin loads correctly within the OpenCode runtime environment.

```bash

# Local validation mirroring CI

npx @opencode-ai/plugin validate .
python3 -m unittest discover -s tests -v

```

## Pi Runtime and Extension Checks

The [`pi-load-check.yml`](https://github.com/ayghri/i-have-adhd/blob/main/pi-load-check.yml) workflow ensures compatibility with the Pi runtime by checking [`package.json`](https://github.com/ayghri/i-have-adhd/blob/main/package.json) for the `"pi"` entry point and compiling the TypeScript extension. The file [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) undergoes strict type checking to prevent runtime errors in the Pi environment.

```bash

# Local Pi extension build test

npm run build  # Runs tsc on extensions/*.ts

```

## Cursor Skill Synchronization

The [`cursor-skill-sync.yml`](https://github.com/ayghri/i-have-adhd/blob/main/cursor-skill-sync.yml) workflow prevents documentation drift by comparing [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) against [`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md). If the canonical skill definition changes without updating the Cursor-specific copy, the workflow fails, enforcing synchronized documentation across AI platforms.

```bash

# Manual sync command (mirrors CI logic)

cp skills/i-have-adhd/SKILL.md .cursor/skills/i-have-adhd/SKILL.md

```

## Evaluation and Compatibility Scripts

Beyond standard unit tests, the pipeline executes specialized evaluation scripts:
- **[`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py)** – Validates model outputs against defined rubrics to ensure response quality.
- **[`scripts/check_context_compat.ts`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/check_context_compat.ts)** – Verifies that context handling logic remains compatible across OMP (OpenCode Model Platform) and Pi runtimes.

These scripts execute during the integration test phase, providing platform-specific validation that unit tests alone cannot cover.

## Local Development and Testing

Developers can replicate the CI/CD pipeline for i-have-adhd locally to verify changes before pushing. The following commands mirror the automated checks performed in GitHub Actions.

### Running Python Tests Locally

```bash

# Create and activate virtual environment

python3 -m venv .venv
source .venv/bin/activate

# Install dependencies (match CI environment)

pip install -r requirements.txt

# Execute test suite

python3 -m unittest discover -s tests -v

```

### Validating Plugin Manifests

```bash

# OpenCode validation

npx @opencode-ai/plugin validate .

# Claude validation

claude plugin validate .

```

### TypeScript Compilation Check

```bash

# Ensure extensions compile without errors

npx tsc --noEmit extensions/i-have-adhd.ts

```

## Summary

- **The CI/CD pipeline for i-have-adhd** uses GitHub Actions with four specialized workflows targeting OpenCode, Pi, Cursor, and Claude platforms.
- **Workflow files** reside in `.github/workflows/` and trigger on every push and pull request to enforce quality gates.
- **Validation steps** include manifest verification ([`opencode.json`](https://github.com/ayghri/i-have-adhd/blob/main/opencode.json)), TypeScript compilation ([`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts)), Python unit tests (`tests/`), and skill synchronization.
- **Local testing** is supported through `npm`, `npx`, and `python3 -m unittest`, allowing developers to validate changes before CI execution.
- **Fail-fast behavior** ensures that any validation failure blocks the merge, maintaining code integrity across all supported AI coding platforms.

## Frequently Asked Questions

### What triggers the CI/CD pipeline for i-have-adhd?

The pipeline triggers on `push` events to any branch and `pull_request` events targeting the main branch. Additionally, some workflows may run on scheduled intervals to validate against updated external dependencies. All triggers are configured in the `on:` sections of the YAML files within `.github/workflows/`.

### Can I run the i-have-adhd CI checks locally before committing?

Yes. Install the Node.js and Python versions specified in the project configuration, then run `npm ci` and `pip install -r requirements.txt`. Execute `python3 -m unittest discover -s tests -v` for Python validation, `npx @opencode-ai/plugin validate .` for OpenCode checks, and `npm run build` for TypeScript compilation verification.

### Which Ubuntu version does the CI/CD pipeline use?

The workflows specify `ubuntu-latest` as the runner environment. This ensures the pipeline always executes on the most recent stable Ubuntu image available in GitHub Actions, providing up-to-date system libraries and security patches.

### How do I add a new validation step to the pipeline?

Create a new workflow file in `.github/workflows/` or extend an existing one. Define the trigger conditions, specify `ubuntu-latest` as the runner, and add steps following the established pattern: checkout, setup (Node/Python), dependency installation, then your custom validation command. Ensure the step returns a non-zero exit code on failure to maintain the fail-fast behavior.