# Best Practices for Developing with i-have-adhd: A Technical Guide

> Master i-have-adhd development with essential best practices. Treat SKILL.md as your single source of truth for consistent, ADHD-friendly output across all runtimes.

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

---

**The essential practice for developing with i-have-adhd is to treat [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) as the single source of truth while preserving the public API surface across the TypeScript extension and always-on hook to ensure consistent ADHD-friendly output across Pi, OMP, and Cursor runtimes.**

The `ayghri/i-have-adhd` repository provides a minimal, self-contained skill that reshapes LLM output for ADHD accessibility. Developing with this codebase requires strict adherence to its canonical architecture and deterministic build constraints to preserve compatibility across multiple assistant runtimes.

## Understanding the Minimal Architecture

The repository follows a deliberately minimal design pattern consisting of six core components:

- **Skill Definition**: The canonical [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) houses the 10-rule checklist that drives the assistant's behavior, including mandated numbered steps and specific time estimates.
- **Cursor Mirror**: A synchronized copy resides at [`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md) to support developers using the Cursor IDE.
- **Platform Extensions**: The [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) TypeScript file exposes the skill as a plugin for Pi and OMP runtimes.
- **Always-On Hooks**: The `hooks/always-on.mjs` script guarantees automatic skill loading for every session unless explicitly disabled.
- **Package Metadata**: [`package.json`](https://github.com/ayghri/i-have-adhd/blob/main/package.json) registers extensions and enforces private package status to prevent npm publication.
- **Documentation**: [`README.md`](https://github.com/ayghri/i-have-adhd/blob/main/README.md) and [`INSTALL.md`](https://github.com/ayghri/i-have-adhd/blob/main/INSTALL.md) provide installation pathways across supported platforms.

## Core Development Guidelines

When contributing to or extending i-have-adhd, follow these seven essential practices:

### Edit the Canonical Skill Only

All rule modifications must occur in [`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 canonical 10-rule checklist that defines ADHD-friendly formatting. After editing, execute the sync command from the contribution guide to update the Cursor mirror at [`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md).

### Preserve the Public API

Maintain the existing signatures in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) and `hooks/always-on.mjs`. These files constitute the only public entry points for Pi and OMP integration. Adding new exports or altering hook signatures will break runtime compatibility.

### Maintain Self-Containment

The repository must not make external network calls or handle secrets. All dependencies remain bundled under `.opencode/node_modules` to ensure the skill operates in isolated environments without external connectivity requirements.

### Enforce Deterministic Builds

Keep `"private": true` in [`package.json`](https://github.com/ayghri/i-have-adhd/blob/main/package.json) to prevent accidental npm publication. Install the skill directly from the repository URL rather than package registries, ensuring consistent dependency resolution across installations.

### Write Comprehensive Tests

Every behavioral change requires test coverage in the `tests/` directory. The repository uses Python's built-in `unittest` framework. Validate modifications by running:

```bash
python3 -m unittest discover -s tests -v

```

Add test cases whenever you modify skill logic or the extension entry point to verify numbered output formatting and time estimate inclusion.

### Document Synchronously

Update [`README.md`](https://github.com/ayghri/i-have-adhd/blob/main/README.md) or platform-specific readmes whenever you modify installation steps or add runtime support. The documentation must remain synchronized with functional changes to prevent drift between the canonical skill and user-facing guides.

### Follow Contribution Workflow

Use the labels and PR description template from [`CONTRIBUTING.md`](https://github.com/ayghri/i-have-adhd/blob/main/CONTRIBUTING.md). Verify changes with the commands listed under the Verification section before requesting review.

## Implementation Examples

### Installing the Skill

```bash

# Clone the repository

git clone https://github.com/ayghri/i-have-adhd.git
cd i-have-adhd

# Install for Pi or OMP runtimes

npm install

# or

bun install

```

### Registering the Extension

```ts
// pi-config.ts
import { registerExtension } from "pi-runtime";

registerExtension("./extensions/i-have-adhd.ts");

```

### Invoking and Testing

```js
// Activate ADHD-friendly mode
await assistant.invoke("/i-have-adhd");

// Deactivate when finished
await assistant.invoke("stop adhd mode");

```

```python

# tests/test_behavior.py

import unittest

class TestADHDRules(unittest.TestCase):
    def test_numbered_output(self):
        response = skill.apply("Explain brewing coffee.")
        self.assertTrue(response.startswith("1."))

if __name__ == "__main__":
    unittest.main()

```

## Summary

- Treat [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) as the immutable source of truth for all rule changes.
- Never modify the public API signatures in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) or `hooks/always-on.mjs`.
- Maintain the repository as a private, self-contained package without external network dependencies.
- Accompany every code change with unit tests in the `tests/` directory.
- Update documentation simultaneously with functional changes.

## Frequently Asked Questions

### Where should I modify the skill rules when developing with i-have-adhd?

Always edit [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) directly. This file serves as the canonical source of truth. After making changes, run the synchronization command specified in the contribution guide to propagate updates to the Cursor-specific 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).

### Can I publish the i-have-adhd package to npm?

No. The [`package.json`](https://github.com/ayghri/i-have-adhd/blob/main/package.json) explicitly sets `"private": true` to prevent accidental publication. Install the skill directly from the GitHub repository URL using npm or bun, which ensures deterministic builds and maintains the bundled dependencies in `.opencode/node_modules`.

### How do I ensure my changes don't break Pi or OMP runtime integration?

Preserve the existing export signatures in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) and the initialization pattern in `hooks/always-on.mjs`. These constitute the public API surface. Additionally, run the full test suite using `python3 -m unittest discover -s tests -v` before submitting pull requests.

### What testing framework does i-have-adhd use?

The repository uses Python's built-in `unittest` framework for behavioral validation. Add test cases to the `tests/` directory whenever modifying skill logic or extension entry points, ensuring numbered steps and time estimates render correctly in output.