One Policy, Many Runtimes

For i-have-adhd, portability is not the same as copying one file into many folders. The repository has to preserve one response policy while adapting activation, context, commands, and session state to different coding assistants. This chapter explains that boundary: which part defines behavior, which parts carry it into a host, and why installation must remain distinct from consent to activate the mode.

The canonical skill owns behavior

The repository’s most important architectural decision is also the easiest to overlook. The canonical skill file defines what the assistant should do: lead with the next action, number bounded work, restate state, suppress tangents, give concrete estimates, show progress, and obey explicit exceptions. That file is the behavior contract. It is not a runtime implementation for every assistant.

Around it sit adapters. An adapter tells a host where the skill is, how a user invokes it, how an always-on option is enabled, and what the host should do when a session reloads or its context changes. The adapter may be a plugin manifest, a startup hook, a context file, a native extension, or a system-prompt transformation. Those mechanisms differ because the hosts differ. Their job is to carry the policy, not silently rewrite what the policy means.

The distinction is useful when reading a change. If a rule changes from “end with one concrete next action” to something else, that is a policy change. It should be made in the canonical skill and then reflected in the places that intentionally mirror it. If a host’s command is missing from a menu, or a runtime loses the rules after compaction, that is an adapter or lifecycle problem. Fixing it should not require inventing a second version of the response rules.

The repository keeps a Cursor-compatible copy as a real file rather than a symlink. That choice supports environments where symlinks are inconvenient, including Windows clones and archive downloads, but it creates a synchronization obligation. The contribution guidance says to edit the canonical file first and copy it to the mirror. Continuous integration compares the two and fails when they drift.

This arrangement has both a benefit and a cost. The benefit is clear ownership: a contributor can find the policy in one authoritative place and reason about adapters separately. The cost is that a mirror is still duplication. A change can be correct in the canonical file and incomplete in the mirror until the synchronization check runs. The repository reduces that risk with CI, but the underlying maintenance work does not disappear.