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

The essential practice for developing with i-have-adhd is to treat 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 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 to support developers using the Cursor IDE.
• Platform Extensions: The 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 registers extensions and enforces private package status to prevent npm publication.
• Documentation: README.md and 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. 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.

Preserve the Public API

Maintain the existing signatures in 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 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:

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 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. Verify changes with the commands listed under the Verification section before requesting review.

Implementation Examples

Installing the Skill

# 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

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

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

Invoking and Testing

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

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

# 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 as the immutable source of truth for all rule changes.
• Never modify the public API signatures in 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 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.

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

No. The 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 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.

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