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

> Learn how to contribute to the i-have-adhd project. Fork the repo, edit rules, run tests, and submit a pull request with this developer guide.

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

---

**Fork the repository, edit the skill rules in [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) or agent configs, run the test suite with `python -m unittest discover -s tests`, and submit a pull request.**

The **i-have-adhd** repository is an open-source skill designed to reshape LLM output for readers with ADHD by enforcing action-first, step-by-step responses. Whether you want to refine the rule set, improve documentation, or extend the evaluation harness, this guide explains exactly how to contribute to the i-have-adhd project following the Instagit plugin model used by Claude Code and Codex.

## Understanding the Repository Architecture

The project follows the **Instagit** plugin model, where [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json) declares the plugin metadata while the actual skill logic resides under `skills/i-have-adhd/`.

Key files you will modify when you contribute to the i-have-adhd project include:

- **[`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json)** – Declares the plugin name, description, and licensing metadata.
- **[`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md)** – Contains the 10-rule manifesto that drives output style (lead with action, number steps, suppress tangents). This is the primary file for behavioral changes.
- **[`skills/i-have-adhd/agents/openai.yaml`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/agents/openai.yaml)** – Provides OpenAI-specific metadata including the `default_prompt` field auto-inserted when the skill invokes.
- **[`skills/i-have-adhd/agents/gemini.toml`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/agents/gemini.toml)** – Gemini-specific configuration in TOML format.
- **[`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py)** – The evaluation harness that validates skill behavior.
- **[`.github/workflows/plugin-load-check.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/plugin-load-check.yml)** – CI workflow ensuring the skill loads correctly.
- **[`tests/test_run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/tests/test_run_evals.py)** – Unit tests for the evaluation pipeline.

## Setting Up Your Development Environment

Begin by creating your own fork and local clone:

```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. Create a feature branch before making changes:

```bash
git checkout -b my-contribution

```

## Making Changes to the Skill

When you contribute to the i-have-adhd project, your changes will typically fall into three categories:

### 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)** to modify the behavioral manifesto. Follow the existing markdown structure where each rule starts with an H3 heading:

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

```

### Changing Agent Prompts

Modify **[`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)** to update the `default_prompt` field. This text is automatically inserted when the skill is invoked via `/i-have-adhd` (Claude) or `$i-have-adhd` (Codex).

### Improving Documentation

Edit **[`README.md`](https://github.com/ayghri/i-have-adhd/blob/main/README.md)** or language-specific readmes under `.github/readme/` to clarify installation or usage instructions.

## Testing and Validation

All contributions must pass the automated test suite before submission.

### Running Unit Tests

Execute the unit-test suite to verify the evaluation harness and case catalog:

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

```

### Validating the Skill

Use the built-in validation command to ensure the skill definition remains well-formed:

```bash

# Local validation

python scripts/run_evals.py validate

# CI-style load check (if Claude CLI is available)

claude plugin load-check i-have-adhd

```

### Running the Evaluation Harness

For deeper behavioral testing, execute the full evaluation pipeline:

```bash

# Check case catalog validity

python scripts/run_evals.py validate

# Generate evaluation plan

python scripts/run_evals.py plan --trials 2 > plan.jsonl

# Run evaluation with stub runner

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

```

The harness executes a stub runner (harmless `echo`) and produces scored rows for analysis.

## Submitting Your Contribution

Once tests pass, commit your changes and push to your fork:

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

```

Open a **Pull Request** on GitHub by clicking **Compare & pull request**. Describe your changes 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 succeed. Respond to reviewer feedback, push additional commits as needed, and maintainers will merge once approvals are granted.

## Summary

- **Fork and clone** the repository to your local machine.
- **Edit [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md)** to add or refine rules that shape ADHD-friendly output.
- **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 prompt adjustments.
- **Run `python -m unittest discover -s tests`** to verify the evaluation harness.
- **Validate** changes using `python scripts/run_evals.py validate`.
- **Submit a PR** only after all CI checks pass green.

## Frequently Asked Questions

### Do I need to install Python dependencies to contribute to the i-have-adhd project?

No. The core skill requires no additional dependencies beyond standard Python. You only need Python installed to run the unit tests in [`tests/test_run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/tests/test_run_evals.py) and the evaluation harness in [`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py).

### Which file should I edit to change how the AI formats its responses?

Edit **[`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md)**. This file contains the 10-rule manifesto that instructs the LLM to lead with actions, number steps, and suppress tangents. Each rule uses H3 headings (e.g., `### 1. Lead with the next action`).

### How do I test my changes locally before submitting a PR?

Run the unit tests with `python -m unittest discover -s tests` to check the evaluation pipeline. Then validate the skill structure with `python scripts/run_evals.py validate`. If you have Claude CLI installed, you can also run `claude plugin load-check i-have-adhd` to verify the plugin loads correctly.

### Can I contribute documentation improvements without changing code?

Yes. Documentation contributions are welcome. Edit **[`README.md`](https://github.com/ayghri/i-have-adhd/blob/main/README.md)** or the language-specific files under `.github/readme/` to improve installation instructions or usage examples. Ensure your markdown follows the existing style and validate that links are functional before submitting.