UditAkhourii/adhd Usage Examples: CLI, Agent, and Library Integration

The UditAkhourii/adhd repository exposes a two-phase reasoning engine for parallel divergent ideation through three primary interfaces: a global CLI, an agent skill command, and a programmatic TypeScript API.

The UditAkhourii/adhd project structures creative problem-solving into distinct divergence and focus phases. Developers can invoke the engine via terminal commands, integrate it into agent workflows, or import functions directly from the adhd-agent package. All usage patterns rely on core orchestration logic in src/engine.ts and frame selection utilities in src/frames.ts.

CLI Usage and Installation

The fastest way to experiment with UditAkhourii/adhd is through the global command-line interface. Install the package and run divergent ideation sessions directly from your terminal.

Installing the Global CLI

Install adhd-agent globally via npm to access the adhd command:

npm install -g adhd-agent

Running Basic and Customized Sessions

Invoke the engine with a problem statement. The CLI automatically handles reframing, frame selection, and idea generation according to the implementation in src/engine.ts:

# Basic prompt

adhd "design a rate limiter that survives a leader election"

# Custom breadth and depth

adhd "name this feature-flag service" --frames 3 --ideas 8 --top 2

These commands trigger the full workflow: reframeProblem strips incidental anchors using the REFRAME_SYSTEM prompt, selectFrames chooses N cognitive frames (default 5), and each frame spawns isolated LLM calls under the DIVERGE_SYSTEM prompt to produce JSON arrays validated against DivergeRowSchema.

Agent Skill Integration

For AI agent environments, UditAkhourii/adhd ships as a runnable skill that exposes the /adhd slash command. Install the skill using the skills CLI:

npx skills add UditAkhourii/adhd

Once installed, agents can invoke the divergent ideation engine inline:

# Then in the agent console

/adhd "design a retry strategy for an LLM request that sometimes hangs"

This interface leverages the same run function defined in src/engine.ts, returning structured results through the agent's messaging interface.

TypeScript Library API

For programmatic control, import the engine directly into Node.js or TypeScript projects. The library exposes granular functions for full execution and frame management.

Running the Full Ideation Engine

Import run and renderText from adhd-agent to execute the complete six-phase workflow:

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

const result = await run({
  problem: "How should we shard this queue under bursty load?",
  topK: 3,
  framesPerRun: 5,
  ideasPerFrame: 6,
});

console.log(renderText(result));
// Output contains: shortlist, nonObviousPick, traps, deepened ideas, provocation

According to the source code in src/engine.ts, the run function orchestrates: optional reframing via reframeProblem, divergence via divergeBranch across selected frames, scoring via scoreIdeas (parsing ScoreRowSchema), clustering via clusterIdeas, shortlisting to remove traps, and deepening via deepenIdea. The result object conforms to the DeepenSchema and related type definitions in src/types.ts.

Direct Frame Selection

Access the frame selection logic directly via selectFrames in src/frames.ts to inspect which cognitive frames will participate in divergence:

import { selectFrames } from "adhd-agent/src/frames";

const frames = selectFrames(5, true); // 5 code-oriented frames
console.log(frames.map(f => f.label));

This function returns frame objects that drive the divergeBranch calls, each operating under isolated system prompts to ensure diverse idea generation across the 15 available cognitive frames.

Core Implementation Details

Understanding the file structure helps when customizing usage of UditAkhourii/adhd.

Engine Orchestration (src/engine.ts)

The main entry point run coordinates the entire pipeline. Key functions include:

• reframeProblem: Strips incidental anchors using the REFRAME_SYSTEM prompt before frame distribution
• scoreIdeas: Parses ScoreRowSchema JSON to calculate weighted totals across novelty, viability, and fit dimensions
• clusterIdeas: Groups ideas by underlying angle using the CLUSTER_SYSTEM prompt
• deepenIdea: Expands shortlisted ideas into sketches, risks, first steps, and child ideas following DeepenSchema

Frame Management (src/frames.ts)

The selectFrames function chooses from 15 predefined cognitive frames. Each frame triggers an isolated LLM call via divergeBranch, producing ideas validated against DivergeRowSchema.

Type Safety (src/types.ts)

All JSON outputs are strictly typed. Key interfaces include DivergeRowSchema for raw ideas, ScoreRowSchema for critic evaluations, and DeepenSchema for expanded concept development.

Summary

• UditAkhourii/adhd exposes parallel divergent ideation through CLI, agent skills, and TypeScript APIs
• Install globally via npm install -g adhd-agent for terminal usage with customizable --frames and --ideas flags
• Add to agents via npx skills add UditAkhourii/adhd to enable the /adhd slash command
• Import run and selectFrames from adhd-agent for programmatic control over the six-phase engine
• Core logic resides in src/engine.ts (orchestration) and src/frames.ts (cognitive frame selection)
• All data structures are typed in src/types.ts using Zod schemas including DivergeRowSchema, ScoreRowSchema, and DeepenSchema

Frequently Asked Questions

How do I customize the number of frames and ideas in UditAkhourii/adhd?

Use the --frames and --ideas flags when running the CLI, or pass framesPerRun and ideasPerFrame to the run function in the TypeScript API. The default configuration selects 5 frames with 6 ideas per frame, as defined in src/engine.ts.

What determines the "non-obvious pick" in the output?

The engine scores all generated ideas using scoreIdeas against dimensions like novelty, viability, and fit. After filtering out traps, the highest-novelty viable idea becomes the non-obvious pick. This logic is implemented in the shortlisting phase of src/engine.ts.

Can I use UditAkhourii/adhd without installing it globally?

Yes. You can use npx adhd-agent for one-off CLI executions, integrate it as an agent skill without global installation, or import specific functions like selectFrames from adhd-agent/src/frames in your TypeScript projects.

Where are the system prompts defined for the divergence and scoring phases?

System prompts including DIVERGE_SYSTEM, REFRAME_SYSTEM, and CLUSTER_SYSTEM are imported and used within src/engine.ts and src/frames.ts. These prompts define the cognitive constraints for each phase of the ideation process, though they are typically internal to the package and invoked automatically by the run function.

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