How i-have-adhd Makes Progress Visible to Users: Rules, Runtime Hooks, and Examples

i-have-adhd makes progress visible by enforcing two strict rules in its skill definition: requiring the model to restate the current step index every turn (Rule 5) and explicitly surface completed functionality (Rule 7), enforced by an always-on runtime hook that auto-injects progress updates across all supported AI runtimes.

The i-have-adhd repository solves the common problem of losing context during multi-step AI-assisted workflows. By embedding specific behavioral constraints directly into its skill definition at skills/i-have-adhd/SKILL.md, the system ensures users always know exactly where they are in a task sequence and what concrete results have been achieved.

The Two Core Rules That Surface Progress

The progress visibility system relies on mandatory rules defined in the canonical skill file.

Rule 5: Restate State Every Turn

According to skills/i-have-adhd/SKILL.md (lines 73-80), Rule 5 mandates that the model must repeat the current step index and total step count at every turn. This eliminates the cognitive load of remembering position in a multi-step workflow.

The rule requires output formatted as "Step X of Y done" followed by the next action. For example, after completing the first step of a three-step task, the model must explicitly state: "Step 1 of 3 done: file opened. Next: apply the replacement."

Rule 7: Make Completed Work Visible

Rule 7, defined in skills/i-have-adhd/SKILL.md (lines 89-95), requires the model to explicitly demonstrate what now functions after each step completes. Rather than vague summaries like "the task is progressing," the model must provide concrete evidence such as runnable commands or observable UI states.

This transforms abstract progress into tangible wins. Instead of stating "login system updated," the model must show: "Login now works with magic links. Try: npm run dev, open /login."

Runtime Enforcement Across AI Platforms

The skill definition alone does not guarantee compliance. The repository implements runtime hooks that automatically enforce these visibility rules.

The Always-On Hook

The hooks/always-on.mjs file contains a runtime hook that consumes the skill's checklist and automatically injects the required "Step X of Y done" line into every response. This ensures consistent progress visibility without requiring manual prompting.

Cross-Platform Compatibility

The enforcement layer extends across multiple AI runtimes through dedicated entry points:

• .opencode/plugins/i-have-adhd.mjs loads the skill for OpenCode compatibility
• .cursor/skills/i-have-adhd/SKILL.md provides a mirror of the canonical skill for Cursor-specific runtimes
• The harness supports Claude, Gemini, and other major models through standardized hook interfaces

Practical Code Examples

The following examples demonstrate the required output formats that make progress concrete and actionable.

Example: Multi-Step Task Tracking

1. Open `src/auth.ts`
2. Replace `verifyToken` (lines 42-58) with the snippet below
3. Run `npm test -- auth.spec.ts`

Step 1 of 3 done: file opened. Next: apply the replacement.

This output illustrates Rule 5 in action, explicitly stating the current position (Step 1 of 3) while maintaining the checklist context.

Example: Demonstrating Completed Functionality

Login now works with magic links. Try: `npm run dev`, open `/login`.

This snippet fulfills Rule 7 by providing a concrete, testable statement of the newly working feature rather than an abstract status update.

Summary

• Progress visibility in i-have-adhd is enforced through mandatory rules in skills/i-have-adhd/SKILL.md, specifically Rule 5 (state restatement) and Rule 7 (completed work visibility).
• The always-on hook in hooks/always-on.mjs automatically injects step tracking into every response, ensuring consistent behavior.
• Users receive concrete, numbered progress indicators ("Step X of Y done") paired with actionable demonstrations of working functionality.
• The system operates across multiple AI runtimes including OpenCode, Cursor, Claude, and Gemini through dedicated skill mirrors and plugins.

Frequently Asked Questions

How does i-have-adhd ensure the AI follows progress visibility rules?

The repository combines static rule definitions in skills/i-have-adhd/SKILL.md with active runtime enforcement through hooks/always-on.mjs. The hook consumes the skill's checklist structure and automatically prepends the required "Step X of Y done" format to every AI response, making compliance automatic rather than optional.

What specific files control progress visibility behavior?

Three primary files govern the system: skills/i-have-adhd/SKILL.md contains Rules 5 and 7 defining the visibility requirements; hooks/always-on.mjs implements the runtime enforcement; and .opencode/plugins/i-have-adhd.mjs (along with .cursor/skills/i-have-adhd/SKILL.md) ensures cross-platform compatibility.

Why does i-have-adhd require showing completed work rather than just status updates?

Rule 7 mandates concrete demonstrations (such as runnable commands or functional UI states) because abstract status updates force users to verify progress manually. By requiring the model to prove functionality with specific examples like "Try: npm run dev", the system provides immediate, testable validation that reduces uncertainty and context-switching overhead.

Can I use i-have-adhd with AI platforms other than OpenCode?

Yes. The repository maintains compatibility layers for multiple runtimes. The .cursor/skills/i-have-adhd/SKILL.md file provides Cursor-specific integration, while the core hook architecture in hooks/always-on.mjs supports Claude, Gemini, and other major AI assistants through standardized interfaces.

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