# How to Update the UditAkhourii/adhd Repository: The Complete 7-Step Workflow

> Learn how to update the UditAkhourii/adhd repository with our 7-step workflow. Pull latest changes, reinstall dependencies, run tests, rebuild, and verify CLI to ensure a smooth update process.

- Repository: [Udit Akhouri/adhd](https://github.com/UditAkhourii/adhd)
- Tags: how-to-guide
- Published: 2026-07-30

---

**To update the UditAkhourii/adhd repository, pull the latest changes from the main branch, reinstall dependencies with npm install, run the test suite, rebuild the TypeScript sources, and verify the CLI functionality before publishing.**

The ADHD project is a TypeScript-based cognitive framework that implements divergent-convergent thinking for AI agents, functioning as a CLI tool, Node.js library, or agent skill. Keeping your local copy updated ensures you benefit from the latest improvements to the engine orchestration and LLM interaction layers. This guide walks you through the exact commands and verification steps needed to safely update UditAkhourii/adhd while maintaining compatibility across all three usage modes.

## Understanding the ADHD Repository Architecture

Before updating, it helps to understand how the components interact so you can verify each layer after the upgrade.

### The Three-Layer Architecture

The repository is organized into distinct layers that communicate via JSON objects:

1. **Engine layer** – Orchestrates the two-phase divergent-then-convergent loop using the frames system. Core logic resides in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts), which coordinates between generation and critique phases.

2. **LLM interaction layer** – Handles all language model calls through [`src/llm.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/llm.ts), abstracting the generation and critique passes into typed function calls.

3. **Presentation layer** – Formats results for human or programmatic consumption via [`src/render.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/render.ts) and exports the public API through [`src/index.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/index.ts).

The CLI entry point at [`src/cli.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/cli.ts) parses arguments and forwards them to the engine, while agent integration relies on [`skills/adhd/SKILL.md`](https://github.com/UditAkhourii/adhd/blob/main/skills/adhd/SKILL.md) pointing to the same underlying logic.

## Step-by-Step Guide to Update UditAkhourii/adhd

Follow these seven steps in order to ensure a clean update that preserves functionality across the engine, LLM wrapper, and renderer components.

### 1. Pull the Latest Changes

Synchronize your local repository with the upstream `main` branch to retrieve the latest TypeScript source code.

```bash
git checkout main
git pull origin main

```

This updates core files like [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) and [`src/llm.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/llm.ts) that may contain breaking changes to the JSON objects passed between layers.

### 2. Install Updated Dependencies

After pulling, reinstall Node.js packages to capture any additions or upgrades specified in [`package.json`](https://github.com/UditAkhourii/adhd/blob/main/package.json).

```bash
npm install

```

The project dependencies include LLM client libraries and TypeScript build tools that must remain in sync with the source code.

### 3. Bump the Version (Optional)

If you are maintaining a fork or preparing a release, update the version field in [`package.json`](https://github.com/UditAkhourii/adhd/blob/main/package.json) before building.

```bash
npm version patch

# Or: npm version minor / npm version major

```

This creates a git tag and updates the version string that the CLI reports when running `adhd --version`.

### 4. Run the Test Suite

Validate that the recent changes have not broken the LLM wrapper or engine logic.

```bash
npm test

```

The repository ships with Jest tests in [`tests/llm.test.ts`](https://github.com/UditAkhourii/adhd/blob/main/tests/llm.test.ts) that verify the generation and critique functions still return expected object shapes. Running these catches mismatches early, before they propagate to the renderer.

### 5. Build the TypeScript Sources

Compile the TypeScript to JavaScript so the CLI and library entry points execute the updated code.

```bash
npm run build

```

This command uses the `tsc` configuration defined in [`tsconfig.json`](https://github.com/UditAkhourii/adhd/blob/main/tsconfig.json) to generate the compiled output required by both the `npx adhd` CLI and the programmatic API exported from [`src/index.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/index.ts).

### 6. Verify the CLI Installation

Execute a quick command to confirm the runtime behavior matches expectations after the update.

```bash
npx adhd "design a rate limiter"

```

For deeper verification, test with custom parameters that exercise the frame generation logic:

```bash
npx adhd "name this function" --frames 3 --ideas 8 --top 2

```

### 7. Publish the Update (Optional)

If distributing the update to npm or team members, publish the package and tag the release.

```bash
npm publish --access public
git tag vX.Y.Z
git push --tags

```

This makes the new version available via `npm install adhd-agent` and updates the skill registry for agent-based installations.

## Testing Your Update with Code Examples

After completing the update workflow, verify specific components using these patterns that exercise the core files.

### Verify the Library API

Test that [`src/index.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/index.ts) exports the updated engine and renderer correctly:

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

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

  console.log(renderText(result));
  // Access result.shortlist, result.nonObviousPick, result.traps, 
  // result.deepened, result.clusters
}

validateUpdate();

```

### Test the CLI After Update

Confirm the [`src/cli.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/cli.ts) entry point correctly parses arguments and forwards them to the engine:

```bash

# Verify basic functionality

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

# Verify custom frame counts work

npx adhd "refactor this module" --frames 4 --ideas 10 --top 3

```

### Update the Agent Skill

If using ADHD as a Claude-style agent skill, reinstall the skill after updating the repository:

```bash
npx skills add UditAkhourii/adhd

```

Then verify the skill responds correctly:

```bash
/adhd "generate a secure password policy"

```

### Validate the LLM Wrapper Directly

Test the [`src/llm.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/llm.ts) module independently to ensure generation and critique functions work:

```typescript
import { generate, critique } from "adhd-agent/llm";

(async () => {
  const gen = await generate({ prompt: "Suggest three caching strategies." });
  const crit = await critique({ ideas: gen });
  console.log(crit);
})();

```

## Key Files You Should Know

Understanding these paths helps diagnose issues during the update process:

- **[`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts)** – Core orchestration of divergent frames and critic pass; depends on [`src/llm.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/llm.ts) for LLM calls
- **[`src/llm.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/llm.ts)** – Abstraction layer for language model interactions (generation and critique)
- **[`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts)** – Defines the 15 cognitive frames used for divergent ideation
- **[`src/cli.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/cli.ts)** – Entry point for the `adhd` command-line tool; forwards arguments to the engine
- **[`src/index.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/index.ts)** – Public API surface exported by the `adhd-agent` npm package
- **[`src/render.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/render.ts)** – Formats engine output for CLI display and programmatic consumption
- **[`skills/adhd/SKILL.md`](https://github.com/UditAkhourii/adhd/blob/main/skills/adhd/SKILL.md)** – Agent-skill manifest used by Claude-style agents to load the ADHD capability
- **[`tests/llm.test.ts`](https://github.com/UditAkhourii/adhd/blob/main/tests/llm.test.ts)** – Minimal test suite validating LLM wrapper behavior and JSON responses
- **[`package.json`](https://github.com/UditAkhourii/adhd/blob/main/package.json)** & **[`tsconfig.json`](https://github.com/UditAkhourii/adhd/blob/main/tsconfig.json)** – Configuration files governing dependencies and TypeScript compilation

## Summary

- **Update UditAkhourii/adhd** by pulling the latest changes, running `npm install`, and executing `npm test` to catch breaking changes early
- **Always rebuild** the TypeScript sources with `npm run build` before testing the CLI or library, as [`src/cli.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/cli.ts) and [`src/index.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/index.ts) depend on compiled JavaScript
- **Verify the engine integration** by running `npx adhd` with a sample prompt to ensure [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) correctly coordinates with [`src/llm.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/llm.ts)
- **Reinstall agent skills** after updating using `npx skills add UditAkhourii/adhd` to ensure the skill manifest points to the latest engine logic
- **Test the LLM layer independently** using the `generate` and `critique` functions imported from `adhd-agent/llm` if you encounter runtime errors

## Frequently Asked Questions

### What is the quickest way to update ADHD if I only use the CLI?

If you installed ADHD globally via npm, run `npm update -g adhd-agent` to pull the latest version without cloning the repository. If working from a local clone, simply run `git pull origin main` followed by `npm install` and `npm run build` in the repository root.

### Why do I need to run npm test after updating the repository?

The test suite in [`tests/llm.test.ts`](https://github.com/UditAkhourii/adhd/blob/main/tests/llm.test.ts) validates that [`src/llm.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/llm.ts) returns JSON objects with the expected shape that [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) and [`src/render.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/render.ts) depend upon. Changes to the LLM wrapper can break the rendering logic, and tests catch these interface mismatches before they cause runtime failures in the CLI or library.

### How do I update the ADHD skill for Claude-style agents?

After updating the repository code, reinstall the skill using `npx skills add UditAkhourii/adhd` to refresh the [`skills/adhd/SKILL.md`](https://github.com/UditAkhourii/adhd/blob/main/skills/adhd/SKILL.md) manifest and underlying engine logic. The skill points to the compiled JavaScript in the repository, so ensure you have run `npm run build` before reinstalling.

### What should I do if the build fails after pulling latest changes?

First, delete the `node_modules` directory and [`package-lock.json`](https://github.com/UditAkhourii/adhd/blob/main/package-lock.json), then run `npm install` to eliminate dependency conflicts. Check [`tsconfig.json`](https://github.com/UditAkhourii/adhd/blob/main/tsconfig.json) for any new TypeScript configuration requirements introduced in the update, and ensure your Node.js version matches the `engines` field specified in [`package.json`](https://github.com/UditAkhourii/adhd/blob/main/package.json). If errors persist, review the imports in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) to verify they correctly reference updated exports from [`src/llm.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/llm.ts).