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

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 – Validates the OpenCode plugin by verifying opencode.json and executing tests/test_opencode_plugin.py.
• pi-load-check.yml – Checks the Pi runtime package (defined in package.json with the "pi" entry) and ensures the TypeScript extension at extensions/i-have-adhd.ts compiles and loads correctly.
• cursor-skill-sync.yml – Maintains parity between the canonical skill definition at skills/i-have-adhd/SKILL.md and the Cursor-compatible copy at .cursor/skills/i-have-adhd/SKILL.md.
• 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 and 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 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, the pipeline specifically targets the OpenCode ecosystem. The workflow validates opencode.json to ensure the plugin manifest contains required fields and valid entry points. It then executes tests/test_opencode_plugin.py to verify that the plugin loads correctly within the OpenCode runtime environment.

# 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 workflow ensures compatibility with the Pi runtime by checking package.json for the "pi" entry point and compiling the TypeScript extension. The file extensions/i-have-adhd.ts undergoes strict type checking to prevent runtime errors in the Pi environment.

# Local Pi extension build test

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

Cursor Skill Synchronization

The cursor-skill-sync.yml workflow prevents documentation drift by comparing skills/i-have-adhd/SKILL.md against .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.

# 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 – Validates model outputs against defined rubrics to ensure response quality.
• 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

# 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

# OpenCode validation

npx @opencode-ai/plugin validate .

# Claude validation

claude plugin validate .

TypeScript Compilation Check

# 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), TypeScript compilation (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.

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