How i-have-adhd Handles Multi-Step Tasks in LLM Responses

The i-have-adhd repository eliminates cognitive overload by forcing LLMs to decompose complex workflows into single, numbered actions, delegating state management to the harness's plan or task tools rather than narrative prose.

The i-have-adhd open-source project provides a specialized skill for AI assistants that restructures how multi-step tasks appear in LLM responses. By codifying strict formatting rules in skills/i-have-adhd/SKILL.md, the system ensures users with attention-deficit challenges receive concise, actionable instructions instead of dense text blocks. This approach fundamentally changes how language models handle complex workflows by externalizing step tracking to dedicated tooling.

Core Architecture of the ADHD-Mode Skill

The multi-step handling mechanism centers on the skill definition file located at skills/i-have-adhd/SKILL.md. According to the source code, the skill enforces a rigid protocol for any response involving sequential actions. The file explicitly states: "If the harness has a task or plan tool, use it for multi-step work: one item per step, one in progress at a time. The checklist does the restating; do not also narrate the full plan as prose"【/skills/i-have-adhd/SKILL.md†L42-L44】.

This rule establishes three critical constraints:

• Single active step: Only one action may be "in progress" at any moment
• External state management: The checklist or plan tool handles state restatement
• Prose suppression: The LLM must not narrate the full plan as continuous text

Numbering and Bounded Actions

Every multi-step task must be expressed as a numbered list. The skill description emphasizes the need to "lead with the next action, number multi-step work, restate state across turns"【/skills/i-have-adhd/SKILL.md†L3-L4】. Each numbered item represents a bounded action with explicit time estimates, ensuring users can anticipate the cognitive load before engaging.

Runtime Activation and Persistence

The skill activates through a dedicated command defined in .opencode/command/i-have-adhd.md. This file establishes that the skill remains active until the user explicitly sends "stop adhd mode"【/.opencode/command/i-have-adhd.md†L6-L7】. During active sessions, a runtime hook implemented in hooks/always-on.mjs ensures every assistant response passes through the ADHD-mode filtering pipeline, maintaining consistent formatting across conversation turns.

Practical Implementation Examples

When the i-have-adhd skill is active, complex requests trigger specific formatting patterns that externalize step management to the harness.

Example 1: Manual Numbered Workflow

For environments without a dedicated task tool, the LLM generates inline numbered steps:

User: /i-have-adhd
User: Please help me set up a Node.js project, install Express, and write a hello-world route.

Assistant (ADHD-mode):
1️⃣ Initialize the project – Run `npm init -y` (≈ 1 min).
2️⃣ Add Express – Run `npm install express` (≈ 30 s).
3️⃣ Create the server file – Add a `server.js` with a basic GET route returning "Hello, world!" (≈ 2 min).

Each line represents a discrete, bounded action with timeboxing. The assistant pauses after presenting the steps, awaiting user confirmation before execution rather than performing all actions autonomously.

Example 2: Harness Task Tool Integration

When the runtime provides a task or plan tool, the skill delegates state tracking to the harness:

User: /i-have-adhd
User: Write a Python script that fetches weather data and logs it.

Assistant (ADHD-mode):
Task list created – The harness's `plan` tool now holds three items.

1️⃣ Fetch weather data – Use `requests.get` to call the API (≈ 1 min).
[User confirms]

2️⃣ Parse the JSON – Extract temperature and humidity (≈ 30 s).
[User confirms]

3️⃣ Log to a file – Write the data with timestamps (≈ 45 s).

Here, the harness maintains the checklist state, allowing the LLM to focus solely on the current active step while the system automatically restates progress between turns.

Summary

• Single-step focus: The i-have-adhd skill enforces a "one item per step, one in progress at a time" rule, preventing cognitive overload from parallel action streams.
• External state management: Multi-step state lives in the harness's plan or task tools, not in the LLM's narrative memory, ensuring consistent restatement between conversation turns.
• Strict formatting: All responses must lead with the immediate next action and use numbered lists for any sequential workflow.
• Persistent activation: Once invoked via .opencode/command/i-have-adhd.md, the skill remains active across the session until explicitly disabled, guaranteeing consistent response formatting through the hooks/always-on.mjs lifecycle management.

Frequently Asked Questions

How does the skill prevent LLMs from explaining entire plans at once?

The SKILL.md file explicitly prohibits narrative plan descriptions when task tools are available, instructing the model: "The checklist does the restating; do not also narrate the full plan as prose"【/skills/i-have-adhd/SKILL.md†L42-L44】. This constraint forces the LLM to externalize the plan state to the harness tool, presenting only the current active step to the user.

Can users execute multiple steps simultaneously in ADHD mode?

No. The architecture strictly enforces single-threaded step execution. The skill definition requires "one item per step, one in progress at a time"【/skills/i-have-adhd/SKILL.md†L42-L44】, ensuring users focus exclusively on the immediate bounded action rather than juggling multiple concurrent tasks.

Where is the skill behavior defined and activated?

The core behavior resides in skills/i-have-adhd/SKILL.md, which lists formatting rules including "number multi-step work" and "restate state across turns"【/skills/i-have-adhd/SKILL.md†L3-L4】. Activation occurs through .opencode/command/i-have-adhd.md, which binds the skill to the conversation session until the user issues "stop adhd mode"【/.opencode/command/i-have-adhd.md†L6-L7】.

What happens if the harness lacks a task or plan tool?

In environments without dedicated tooling, the skill falls back to manual numbered lists within the LLM response. While the automated checklist restating feature may not be available, the formatting rules still require numbered steps, time estimates, and leading with the next action to maintain cognitive accessibility.

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