How to Debug Issues in i-have-adhd: A Complete Troubleshooting Guide

Debugging i-have-adhd requires verifying the always-on flag at $XDG_CONFIG_HOME/opencode/.i-have-adhd-always, ensuring SKILL.md files remain synchronized across runtime directories, and running the Python test suite to isolate plugin failures.

The i-have-adhd repository provides an ADHD-friendly coding assistant skill that injects formatted response rules into multiple LLM backends including OpenCode, Claude, Codex, and Gemini. When the plugin fails to activate or produces malformed output, systematic debugging involves checking the filesystem flag, validating skill file consistency, and executing the comprehensive test suite located in the tests/ directory.

Understanding the i-have-adhd Architecture

The project separates skill definitions from runtime plugins, creating multiple potential failure points during execution.

Skill Definition and Runtime Plugins

The canonical behavior rules live in skills/i-have-adhd/SKILL.md, which serves as the source of truth for how the assistant formats output (leading with next actions, numbering steps, providing concrete time estimates). This content is mirrored at .cursor/skills/i-have-adhd/SKILL.md for Cursor IDE compatibility. When editing the skill, you must keep both files synchronized.

Each runtime loads a specific plugin entry point: .opencode/plugins/i-have-adhd.mjs for OpenCode, .claude-plugin/plugin.json for Claude, .codex-plugin/plugin.json for Codex, and .agents/plugins/marketplace.json for Pi and other agents. These plugins read the skill file, strip YAML front-matter when the always-on flag is active, and inject the transformed text into the LLM response pipeline.

The Always-On Flag Mechanism

The always-on flag determines whether the plugin processes the skill or returns an empty string. The system checks for the existence of $XDG_CONFIG_HOME/opencode/.i-have-adhd-always. When this file is present, the plugin becomes active; when absent, it silently passes through without modification.

Checking the Always-On Flag Configuration

If the plugin returns empty responses or behaves as though uninstalled, first verify the flag file exists and is readable:

if [ -f "$XDG_CONFIG_HOME/opencode/.i-have-adhd-always" ]; then
  echo "Flag is set - plugin should be active"
else
  echo "Flag missing - plugin will return empty string"
fi

The repository provides always-on hooks to manage this flag for the current session:

• hooks/always-on.mjs – Node.js script for setting the flag
• hooks/always-on.sh – Bash implementation for Unix systems
• hooks/always-on.ps1 – PowerShell script for Windows environments

If you suspect the plugin is not triggering, confirm that one of these scripts executed successfully and created the flag file. The behavior is explicitly tested in tests/test_always_on_hooks.py and tests/test_opencode_plugin.py.

Validating Skill File Synchronization

Symptoms where skill content appears unchanged after editing typically indicate the mirror file is outdated. The repository maintains two copies of the skill definition:

1. skills/i-have-adhd/SKILL.md – Primary source of truth
2. .cursor/skills/i-have-adhd/SKILL.md – Cursor-specific mirror

After editing the primary file, verify synchronization by running:

git diff .cursor/skills/i-have-adhd/SKILL.md

If differences appear, copy the updated content to the Cursor directory to ensure consistent behavior across IDEs.

Running the Test Suite

The repository ships with comprehensive unit tests that validate flag handling, front-matter stripping, and runtime compatibility. Execute the full suite with:

python3 -m unittest discover -s tests -v

The test suite specifically validates:

• Correct handling of the always-on flag presence and absence
• Proper front-matter stripping, including edge cases with unclosed fences or trailing whitespace
• OpenCode plugin compatibility via the driver script tests/opencode_plugin_driver.mjs

To manually invoke the OpenCode plugin driver for reproducing CI failures:

node tests/opencode_plugin_driver.mjs .opencode/plugins/i-have-adhd.mjs

For testing specific skill processing without the full framework, create a minimal skill file and inspect the plugin output:

from pathlib import Path
skill_path = Path('skills/i-have-adhd/SKILL.md')
skill_path.write_text('---\nname: test\n---\nTest body.')

# Now run the plugin as shown in the test_opencode_plugin.py implementation

Common Debugging Scenarios

Use the following diagnostic approach when encountering specific failure modes:

Empty Response from Plugin

• Likely cause: The always-on flag file is missing or unreadable
• Debug step: Verify $XDG_CONFIG_HOME/opencode/.i-have-adhd-always exists using the bash check shown above

Skill Content Not Updating

• Likely cause: The Cursor mirror file is out of sync with the primary skill definition
• Debug step: Run git diff between skills/i-have-adhd/SKILL.md and .cursor/skills/i-have-adhd/SKILL.md to identify discrepancies

Front-Matter Not Stripped

• Likely cause: Malformed YAML fences or extra whitespace in the skill file
• Debug step: Run the plugin directly with a test skill (referencing the test_strips_frontmatter_with_trailing_whitespace test case) and inspect the transformed output

Runtime Crashes on Load

• Likely cause: Missing Node.js dependency for the OpenCode plugin
• Debug step: Check if tests skip with shutil.which("node") returning None; install Node if required

Unexpected Logs in CI Pipelines

• Likely cause: Hook scripts failing to set the flag in the CI environment
• Debug step: Examine .github/workflows/plugin-load-check.yml and .github/workflows/pi-load-check.yml to verify environment setup steps are creating the flag file before test execution

Summary

• The always-on flag at $XDG_CONFIG_HOME/opencode/.i-have-adhd-always controls plugin activation; verify its existence first when debugging silent failures.
• Skill files must remain synchronized between skills/i-have-adhd/SKILL.md and .cursor/skills/i-have-adhd/SKILL.md to ensure consistent behavior across runtimes.
• Run the test suite using python3 -m unittest discover -s tests -v to validate flag handling, front-matter stripping, and plugin functionality.
• Hook scripts in the hooks/ directory manage flag creation for different shells and environments.
• Manual debugging can utilize the tests/opencode_plugin_driver.mjs script to isolate runtime-specific issues without the full test framework overhead.

Frequently Asked Questions

Why does the i-have-adhd plugin return an empty response?

The plugin returns an empty string when the always-on flag is missing. Verify that $XDG_CONFIG_HOME/opencode/.i-have-adhd-always exists and is readable by the process. If running in a fresh terminal session, ensure you executed one of the hook scripts (hooks/always-on.sh, hooks/always-on.mjs, or hooks/always-on.ps1) to create the flag.

How do I test if the skill file is being processed correctly?

Run the Python test suite to verify processing: python3 -m unittest discover -s tests -v. For manual inspection, use the Node.js driver at tests/opencode_plugin_driver.mjs to pass a test skill file through the plugin and observe the output. This bypasses IDE integration and isolates the transformation logic.

What causes front-matter stripping to fail?

Front-matter stripping fails when YAML fences are malformed, contain unclosed delimiters, or include unexpected trailing whitespace. The test case test_strips_frontmatter_with_trailing_whitespace in tests/test_opencode_plugin.py specifically covers these edge cases. Ensure your SKILL.md uses clean --- delimiters without extra characters on the fence lines.

Why do changes to SKILL.md not appear in my Cursor IDE?

Cursor reads from .cursor/skills/i-have-adhd/SKILL.md, not the primary skills/ directory. After editing the main skill file, copy the updated content to the Cursor mirror location and verify with git diff .cursor/skills/i-have-adhd/SKILL.md to ensure both files match byte-for-byte.

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