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

To contribute to the i-have-adhd project, fork the repository, edit the skill rules in 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
Skill rules	The 10-rule manifesto that drives output style (lead with action, number steps, suppress tangents).	skills/i-have-adhd/SKILL.md
Agent interface	Metadata for OpenAI-based agents (display name, default prompt).	skills/i-have-adhd/agents/openai.yaml
Gemini agent config	Configuration for Gemini agents in TOML format.	skills/i-have-adhd/agents/gemini.toml
Evaluation harness	Scripts and tests validating skill behavior.	scripts/run_evals.py
CI workflows	Automated checks ensuring skill loads correctly.	.github/workflows/plugin-load-check.yml

The repository follows the Instagit plugin model: 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:

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:

git checkout -b my-contribution

3. Make Targeted Changes

Adding or updating rules – Edit 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 or 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 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:

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:

# 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:

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 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. When adding new rules, follow the existing pattern:

### 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. For Gemini, edit 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, 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 file contains the evaluation pipeline. Contributors can add new test cases or improve the validation logic. Run the full harness locally:

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.
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 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 to add or refine ADHD-focused output rules.
• Modify agent configs in agents/openai.yaml or 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 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 and YAML/TOML for agent configurations. The evaluation harness uses Python (located in 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, 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) and Gemini (via 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 in the GitHub Actions tab. Common failures include malformed YAML in agent configs or markdown syntax errors in SKILL.md. Fix the issue locally, run python scripts/run_evals.py validate to confirm resolution, then push the fix to your branch.

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