# How to Contribute to the i-have-adhd Open Source Project: A Complete Guide

> Learn how to contribute to the i-have-adhd open source project. Follow our guide to fork, edit skill rules, run tests, validate, and submit your pull request.

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

---

**To contribute to the i-have-adhd project, fork the repository, edit the skill rules in [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) or agent configs, run the unit tests with `python -m unittest`, validate with `python scripts/run_evals.py validate`, and submit a pull request.**

The **i-have-adhd** repository is a lightweight Instagit plugin that reshapes LLM output for readers with ADHD, delivering action-first, step-by-step responses. According to the ayghri/i-have-adhd source code, contributions focus on refining the 10-rule manifesto, extending agent configurations for Claude and Codex, or improving the evaluation harness. This guide walks through the exact file paths and validation steps required to submit successful contributions.

## Understanding the Project Architecture

Before contributing, familiarize yourself with the core components defined in the repository structure:

| Component | Purpose | Key File |
|---|---|---|
| **Skill definition** | Declares the plugin name, description, and licensing. | [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json) |
| **Skill rules** | The 10-rule manifesto that drives output style (lead with action, number steps, suppress tangents). | [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) |
| **Agent interface** | Metadata for OpenAI-based agents (display name, default prompt). | [`skills/i-have-adhd/agents/openai.yaml`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/agents/openai.yaml) |
| **Gemini agent config** | Configuration for Gemini agents in TOML format. | [`skills/i-have-adhd/agents/gemini.toml`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/agents/gemini.toml) |
| **Evaluation harness** | Scripts and tests validating skill behavior. | [`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py) |
| **CI workflows** | Automated checks ensuring skill loads correctly. | [`.github/workflows/plugin-load-check.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/plugin-load-check.yml) |

The repository follows the **Instagit** plugin model: [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json) declares the plugin, while the skill lives under `skills/`. When installed, users invoke the skill with `/i-have-adhd` (Claude) or `$i-have-adhd` (Codex).

## Step-by-Step Contribution Guide

### 1. Fork and Clone the Repository

Create your own copy of the repository and set up the local environment:

```bash
git clone https://github.com/<your-username>/i-have-adhd.git
cd i-have-adhd

```

No additional dependencies are required for the core skill modifications.

### 2. Create a Feature Branch

Isolate your changes in a dedicated branch:

```bash
git checkout -b my-contribution

```

### 3. Make Targeted Changes

**Adding or updating rules** – Edit [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md). Follow the existing markdown structure; each rule starts with a heading like `### 1. Lead with the next action`.

**Changing the agent prompt** – Modify [`skills/i-have-adhd/agents/openai.yaml`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/agents/openai.yaml) or [`skills/i-have-adhd/agents/gemini.toml`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/agents/gemini.toml). Update the `default_prompt` field to change how the skill is automatically invoked.

**Improving documentation** – Edit [`README.md`](https://github.com/ayghri/i-have-adhd/blob/main/README.md) or language-specific readmes under `.github/readme/`.

### 4. Run the Unit Test Suite

Execute the test suite to verify the evaluation harness and case catalog remain functional:

```bash
python -m unittest discover -s tests

```

All tests must pass before you push changes.

### 5. Validate the Skill Locally

Use the built-in validation commands to ensure the skill loads correctly:

```bash

# Validate the skill definition

python scripts/run_evals.py validate

```

This checks the case catalog and ensures the skill definition is well-formed.

### 6. Commit and Push

Stage your changes with clear, descriptive messages:

```bash
git add .
git commit -m "Add new rule: Highlight success immediately / Fix typo in SKILL.md"
git push origin my-contribution

```

### 7. Open a Pull Request

Navigate to GitHub and click **Compare & pull request**. Describe the change and reference any related issue numbers. The CI pipelines in [`.github/workflows/plugin-load-check.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/plugin-load-check.yml) will run automatically; ensure they all succeed.

### 8. Review and Iterate

Respond to reviewer feedback, make required updates, and push additional commits. Once approvals are granted, maintainers will merge the PR.

## Key Contribution Areas

### Modifying Skill Rules in SKILL.md

The core behavior lives in [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md). When adding new rules, follow the existing pattern:

```markdown

### 11. Highlight success immediately

The first line after the solution should show a concrete success cue, e.g. "✅ Build succeeded". This reinforces dopamine for the reader.

```

Commit the change and run `python scripts/run_evals.py validate` to confirm the file remains well-formed.

### Updating Agent Configurations

For OpenAI-based agents, edit [`skills/i-have-adhd/agents/openai.yaml`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/agents/openai.yaml). For Gemini, edit [`skills/i-have-adhd/agents/gemini.toml`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/agents/gemini.toml). These files contain the `default_prompt` field that controls how the skill is invoked automatically.

### Improving Documentation

Documentation contributions target [`README.md`](https://github.com/ayghri/i-have-adhd/blob/main/README.md), [`INSTALL.md`](https://github.com/ayghri/i-have-adhd/blob/main/INSTALL.md), and the localized readme files under `.github/readme/`. Clear installation instructions for Claude Code (`claude plugin marketplace add`) and Codex (`codex plugin marketplace add`) are high-value contributions.

### Extending the Evaluation Harness

The [`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py) file contains the evaluation pipeline. Contributors can add new test cases or improve the validation logic. Run the full harness locally:

```bash
python scripts/run_evals.py plan --trials 2 > plan.jsonl
python scripts/run_evals.py run \
  --runner-config evals/runners.example.json \
  --runner stub \
  --condition candidate \
  --condition-skill skills/i-have-adhd/SKILL.md \
  --output results.jsonl

```

## Testing and Validation

Every contribution must pass two validation layers:

1. **Unit Tests**: `python -m unittest discover -s tests` verifies the evaluation harness logic in [`tests/test_run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/tests/test_run_evals.py).
2. **Skill Validation**: `python scripts/run_evals.py validate` ensures the skill definition and case catalog are syntactically correct.

The CI workflow defined in [`.github/workflows/plugin-load-check.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/plugin-load-check.yml) automatically runs these checks on every pull request.

## Summary

- **Fork and clone** the repository from `ayghri/i-have-adhd` to begin development.
- **Edit [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md)** to add or refine ADHD-focused output rules.
- **Modify agent configs** in [`agents/openai.yaml`](https://github.com/ayghri/i-have-adhd/blob/main/agents/openai.yaml) or [`agents/gemini.toml`](https://github.com/ayghri/i-have-adhd/blob/main/agents/gemini.toml) for platform-specific behavior.
- **Run `python -m unittest discover -s tests`** to verify the evaluation harness remains functional.
- **Validate with `python scripts/run_evals.py validate`** before submitting your pull request.
- **Submit PRs** with clear descriptions; CI checks in [`.github/workflows/plugin-load-check.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/plugin-load-check.yml) must pass.

## Frequently Asked Questions

### What programming languages do I need to know to contribute to i-have-adhd?

You primarily need familiarity with **Markdown** for editing [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) and **YAML/TOML** for agent configurations. The evaluation harness uses **Python** (located in [`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py)), so Python knowledge is helpful for extending tests but not required for documentation or rule updates.

### How do I test my changes to the skill rules?

After editing [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md), run `python scripts/run_evals.py validate` to check the file structure. For end-to-end testing, install the plugin locally in Claude Code using `claude plugin install` and invoke it with `/i-have-adhd` to see your rule changes in action.

### Can I contribute new agent configurations for other LLM platforms?

Yes. The repository currently supports OpenAI (via [`agents/openai.yaml`](https://github.com/ayghri/i-have-adhd/blob/main/agents/openai.yaml)) and Gemini (via [`agents/gemini.toml`](https://github.com/ayghri/i-have-adhd/blob/main/agents/gemini.toml)). You can add new agent configurations by creating additional files in the `skills/i-have-adhd/agents/` directory, following the existing schema for `default_prompt` and metadata fields.

### What should I do if the CI checks fail on my pull request?

Check the output of [`.github/workflows/plugin-load-check.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/plugin-load-check.yml) in the GitHub Actions tab. Common failures include malformed YAML in agent configs or markdown syntax errors in [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md). Fix the issue locally, run `python scripts/run_evals.py validate` to confirm resolution, then push the fix to your branch.