Understanding the File Structure of UditAkhourii/adhd: A Complete Guide

The UditAkhourii/adhd repository follows a modular TypeScript architecture organized into six primary directories—src/, documentation/, tests/, bench/, skills/, and docs/—with a clear separation between the core LLM execution engine, public API surfaces, and supporting infrastructure.

The adhd project is a TypeScript-based library designed for LLM-driven generation workflows. Understanding the file structure of UditAkhourii/adhd reveals a component-oriented layout where type definitions, engine logic, and CLI interfaces are cleanly isolated, making the codebase easy to navigate and extend.

Top-Level Directory Layout

The repository root organizes functionality into distinct logical buckets. Rather than flattening all code into a single folder, the maintainer separated concerns using the following hierarchy:

adhd/
├─ src/                     – Core library code
├─ documentation/           – Guides, design docs, and usage notes
├─ tests/                   – Test suite (Jest)
├─ bench/                   – Benchmarking utilities and data
├─ skills/adhd/             – Skill definition used by the engine
├─ docs/                    – Generated documentation assets
├─ .github/                 – CI/CD workflow definitions
├─ package.json             – NPM package metadata
├─ tsconfig.json            – TypeScript compiler configuration
├─ README.md                – Project overview
└─ LICENSE                  – MIT license

This structure ensures that source code, user documentation, and evaluation tools live in separate namespaces, preventing circular dependencies and simplifying automated testing pipelines.

Core Source Code Organization (src/)

The src/ directory contains the executable TypeScript source that defines the library's behavior. Files here follow a specific dependency flow: type definitions → core engine → helpers → public entry points.

Entry Points and Public API (src/index.ts)

The file src/index.ts serves as the central export hub for the entire package. It re-exports the primary public API consumed by downstream users:

• run – Orchestrates the LLM-driven generation process
• renderText – Converts a RunResult into a human-readable string
• FRAMES and selectFrames – Provide the prompt templates that guide LLM behavior

When you import from "adhd" in your own projects, you are targeting the symbols defined in this file.

Execution Engine (src/engine.ts)

Located at src/engine.ts, the engine contains the core run implementation. This module iterates over selected frames, builds LLM query options using buildQueryOptions (imported from llm.ts), invokes the model via callLLM, parses JSON responses with parseJSON, and aggregates everything into a RunResult object.

The engine acts as the orchestration layer, coordinating between the frame selection logic and the raw LLM communication primitives.

Frame Management (src/frames.ts)

The src/frames.ts file defines a static array named FRAMES, where each element represents a prompt template containing system instructions, user prompts, and optional code snippets. The helper function selectFrames randomly picks a subset of these templates, optionally favoring "code mode" when that parameter is enabled.

This separation allows the engine to remain agnostic about specific prompt content while the frames file provides the configurational data that shapes LLM behavior.

LLM Integration (src/llm.ts)

The src/llm.ts module abstracts all communication with large language models. It exports utilities for:

• Building request payloads via buildQueryOptions
• Sending requests through callLLM
• Safely parsing JSON responses with optional Zod schema validation

By isolating network logic and response handling here, the codebase prevents the engine from directly managing HTTP concerns or validation errors.

Rendering and CLI (src/render.ts, src/cli.ts)

The src/render.ts file provides formatting utilities that extract fields like ideas and scores from a RunResult and produce tidy strings for CLI or API consumers. Meanwhile, src/cli.ts wires these components into a command-line interface, exposing the adhd run ... command that reads configuration, executes run, and prints rendered output.

Type Definitions (src/types.ts)

Centralized type definitions live in src/types.ts, declaring interfaces such as Idea, Score, and RunResult. Keeping types in a dedicated file ensures consistency across the engine, LLM utilities, and public API without creating circular import chains.

Documentation and Testing Infrastructure

User Guides (documentation/)

The documentation/ directory contains Markdown files offering detailed user guidance:

• quickstart.md – Getting started guide
• install.md – Installation instructions
• how-it-works.md – High-level architecture overview
• frames.md – Explanation of frame concepts
• api.md – Public API description

These files ensure newcomers can grasp the library's purpose and extend it without diving directly into source code.

Test Suite (tests/)

The tests/ directory houses the Jest-based test suite. The file tests/llm.test.ts verifies LLM utility behavior, including call handling, JSON parsing, and error cases. This location follows standard Node.js conventions, allowing npm test to discover specs automatically.

Benchmarking (bench/)

Performance and evaluation tools reside in bench/. Key files include:

• run-evals.ts – Runs the evaluation harness across different frames
• judge.ts – Implementation for benchmarking judgments
• baseline.ts – Baseline implementations for comparison

These scripts are essential when swapping LLM back-ends or tuning frame selection algorithms, providing empirical data on execution speed and output quality.

Supporting Assets and Configuration

Skill Definitions (skills/adhd/)

The skills/adhd/SKILL.md file provides a markdown description of the "adhd" skill used by the engine. This metadata allows the system to understand available capabilities without hard-coding descriptions into TypeScript.

Generated Documentation (docs/)

The docs/ folder contains generated assets such as index.html and hero.png. These are build artifacts produced from the source documentation, served as static HTML for GitHub Pages or similar hosting.

CI/CD Configuration (.github/)

The .github/workflows/ directory stores GitHub Actions pipelines for continuous integration, automated testing, and CodeQL security scanning.

Package Configuration

Root-level configuration files include package.json for NPM metadata, tsconfig.json for TypeScript compiler settings, README.md for project overview, and LICENSE for the MIT license terms.

Practical Usage Examples

Below are runnable TypeScript examples demonstrating how the file structure translates into API usage.

Running with Default Frames

import { run, renderText } from "adhd";

async function demo() {
  const result = await run({
    // Minimal required options; defaults will select random frames
    prompt: "Generate ideas for improving focus."
  });
  console.log(renderText(result));
}

demo().catch(console.error);

Selecting Specific Frames and Customizing LLM Options

import { run, selectFrames, FRAMES } from "adhd";
import { LLMOptions } from "adhd";

async function customRun() {
  // Pick three frames that include code snippets
  const frames = selectFrames(3, true);
  const llmOpts: LLMOptions = {
    model: "gpt-4",
    temperature: 0.7,
    maxTokens: 500
  };

  const result = await run({
    frames,
    llmOptions: llmOpts,
    prompt: "Suggest a TypeScript function that schedules Pomodoro sessions."
  });

  console.log(result);
}

customRun().catch(console.error);

Command-Line Interface

Once installed globally, you can invoke the CLI directly:

adhd run --prompt "List quick tactics for staying on task during a meeting."

The CLI internally calls the same run function exported from src/index.ts and prints output formatted by src/render.ts, providing a consistent interface between programmatic and shell usage.

Summary

• The file structure of UditAkhourii/adhd separates core logic (src/), user documentation (documentation/), and evaluation tools (bench//tests/) into distinct top-level directories.
• src/index.ts defines the public API surface, re-exporting run, renderText, and frame utilities.
• src/engine.ts orchestrates the execution flow, delegating LLM communication to src/llm.ts and frame selection to src/frames.ts.
• src/types.ts centralizes TypeScript interfaces to prevent circular dependencies across the codebase.
• Configuration and metadata (package.json, tsconfig.json, LICENSE) reside at the repository root, while .github/workflows/ manages CI/CD automation.
• The modular layout supports both library consumers importing TypeScript functions and end-users running CLI commands.

Frequently Asked Questions

What is the main entry point of the UditAkhourii/adhd library?

The main entry point is src/index.ts, which re-exports the public API including the run function, renderText formatter, and frame utilities (FRAMES and selectFrames). When you install the package via NPM and import from "adhd", the module resolver loads this file.

How does the engine.ts file interact with llm.ts?

The src/engine.ts module imports helper functions from src/llm.ts to handle LLM communication. Specifically, the engine calls buildQueryOptions to construct request payloads, callLLM to execute the network request, and parseJSON to safely deserialize responses. This abstraction keeps the engine focused on orchestration while llm.ts manages HTTP and validation concerns.

Where are the frame definitions stored in the repository?

Frame definitions reside in src/frames.ts, which exports a static array named FRAMES. Each frame object contains prompt templates (system and user messages) and optional code snippets. The selectFrames function in the same file provides logic for randomly selecting a subset of these templates, optionally weighting toward code-inclusive frames.

What testing framework does UditAkhourii/adhd use?

The repository uses Jest for testing, with test files located in the tests/ directory. The primary test file tests/llm.test.ts validates LLM utility behavior, JSON parsing, and error handling. Configuration for Jest is typically defined in package.json or a standalone jest.config.js at the repository root.

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