What Is the Purpose of the adhd Directory in UditAkhourii/adhd? A Complete Technical Guide

The adhd directory serves as the runnable skill definition that implements the ADHD (Parallel Divergent Ideation) method, enabling Claude Code and other coding agents to execute a two-phase reasoning loop that first diverges into multiple isolated cognitive frames before focusing on the most promising solutions.

The UditAkhourii/adhd repository packages a specialized reasoning framework designed to overcome premature convergence in large language model problem-solving. Located at skills/adhd/, this directory contains the complete declarative specification, runtime engine, and integration hooks required to deploy structured parallel ideation across open-ended design, architecture, and debugging tasks.

How the ADHD Directory Implements Parallel Divergent Ideation

The adhd directory acts as the centralized hub for the ADHD (Parallel Divergent Ideation) methodology. Unlike standard chain-of-thought prompting that risks early convergence on suboptimal solutions, the code here orchestrates a sophisticated two-phase loop that explores many reasoning paths simultaneously before committing to a final answer.

The Diverge-Score-Cluster-Deepen Cycle

According to the source code in src/engine.ts, the workflow follows a strict sequence:

1. Diverge – Generate multiple isolated reasoning branches, each operating under a distinct cognitive frame (defined in src/frames.ts)
2. Score – Evaluate each branch against quality criteria
3. Cluster – Group semantically similar ideas to identify patterns
4. Deepen – Expand the most promising clusters with additional reasoning

This architecture prevents the "trap" of locking onto the first viable solution, which plagues ordinary prompting strategies.

Pre-Flight Gating Logic

Before initiating the expensive multi-LLM process (requiring approximately 10 separate calls), the skill performs a lightweight suitability check. The SKILL.md file in skills/adhd/ contains a declarative "gate" that analyzes whether the presented problem warrants the computational overhead of full ADHD processing. This gate ensures that simple queries bypass the elaborate divergence workflow while complex architectural challenges receive the appropriate analytical depth.

Agent Integration: Installing the ADHD Skill

The adhd directory functions as a portable skill package that integrates directly with agent frameworks. When installed via npx skills add UditAkhourii/adhd, the directory exposes a /adhd command accessible from the chat interface.

Inside skills/adhd/SKILL.md, the specification maps this command to the TypeScript engine in src/engine.ts. Upon invocation, the engine:

• Accepts the user's problem statement
• Loads cognitive frames from src/frames.ts
• Orchestrates parallel LLM calls
• Returns a structured RunResult (defined in src/types.ts)

This integration allows agents to automatically apply structured, parallel-ideation reasoning patterns without manual prompt engineering.

Key Files Within the adhd Directory

The adhd directory contains several critical components that collectively deliver the complete workflow:

File	Technical Role
skills/adhd/SKILL.md	Declarative skill specification including the pre-flight gate, frame definitions, and output shape requirements
src/engine.ts	Core runtime implementing the diverge-score-cluster-deepen loop and parallel call orchestration
src/frames.ts	Registry of cognitive frames and frame-selection algorithms
src/types.ts	TypeScript definitions for RunResult, Idea, Score, and Cluster entities
documentation/how-it-works.md	Architectural documentation explaining the two-phase ADHD methodology
documentation/api.md	Public API documentation for the adhd-agent library

Practical Implementation Examples

You can interact with the adhd directory's functionality through three primary interfaces, depending on your integration requirements.

Command Line Interface

Install the global CLI to run the skill directly against complex problems:

npm install -g adhd-agent
adhd "design a rate limiter that survives a leader election"

This invokes the same engine located in src/engine.ts that the Claude Code skill uses internally.

Library Integration via TypeScript

Import the packaged library to embed ADHD reasoning into custom tooling:

import { run, renderText } from "adhd-agent";

const result = await run({
  problem: "How should we shard a queue under bursty load?",
  framesPerRun: 5,
  topK: 3,
});
console.log(renderText(result));

The run() function accepts a configuration object conforming to the interfaces defined in src/types.ts, returning a structured RunResult that includes scored and clustered ideas.

Direct Engine Access

For internal development or custom orchestration, import the core engine directly:

import { run } from "./src/engine";

const res = await run({
  problem: "Add exponential backoff to our retry logic",
  ideasPerFrame: 4,
  topK: 2,
});
console.log(res);

This pattern accesses the same diverge-score-cluster-deepen logic that powers the high-level API, allowing fine-grained control over the ideation process.

Summary

• The adhd directory in UditAkhourii/adhd is the runnable skill definition implementing the Parallel Divergent Ideation method.
• It contains a two-phase reasoning loop (diverge then focus) that prevents premature convergence by exploring multiple cognitive frames simultaneously.
• The SKILL.md file includes a pre-flight gate that determines whether a problem warrants the expensive multi-LLM workflow.
• The src/engine.ts file orchestrates parallel calls, scoring, clustering, and deepening logic.
• It integrates with Claude Code via the /adhd command and ships as a reusable Node.js library (adhd-agent) for custom tooling.

Frequently Asked Questions

What does the adhd directory actually contain?

The adhd directory contains the complete skill specification for the ADHD method, including the declarative SKILL.md configuration, the TypeScript engine in src/engine.ts that executes the parallel ideation loop, cognitive frame definitions, type definitions, and documentation. It functions as both a Claude Code skill and a standalone npm package.

How does the adhd directory prevent premature convergence in LLM reasoning?

According to the implementation in src/engine.ts, the directory ships code that enforces a diverge-then-focus architecture. First, it generates many isolated reasoning branches under different cognitive frames. Then it scores, clusters, and prunes these branches before deepening only the most promising ideas. This structured workflow prevents the model from fixating on the first acceptable solution.

Can I use the adhd directory without Claude Code?

Yes. While the skills/adhd/ path contains the Claude Code skill definition, the underlying engine is packaged as the adhd-agent npm module. You can install it globally with npm install -g adhd-agent or import specific functions like run() and renderText() into your TypeScript projects to leverage the same parallel ideation workflow in custom scripts or CLI tools.

What is the purpose of the pre-flight gate in the adhd skill?

The pre-flight gate, defined in skills/adhd/SKILL.md, acts as a lightweight classifier that runs before the expensive multi-LLM process begins. It evaluates whether a problem requires the full ADHD treatment (approximately 10 LLM calls) or if a simpler approach suffices. This optimization prevents wasted computation on straightforward queries while ensuring complex architectural challenges receive appropriate analytical depth.

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