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

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, which coordinates between generation and critique phases.

2. LLM interaction layer – Handles all language model calls through 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 and exports the public API through src/index.ts.

The CLI entry point at src/cli.ts parses arguments and forwards them to the engine, while agent integration relies on 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.

git checkout main
git pull origin main

This updates core files like src/engine.ts and 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.

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 before building.

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.

npm test

The repository ships with Jest tests in 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.

npm run build

This command uses the tsc configuration defined in tsconfig.json to generate the compiled output required by both the npx adhd CLI and the programmatic API exported from src/index.ts.

6. Verify the CLI Installation

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

npx adhd "design a rate limiter"

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

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.

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 exports the updated engine and renderer correctly:

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 entry point correctly parses arguments and forwards them to the engine:

# 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:

npx skills add UditAkhourii/adhd

Then verify the skill responds correctly:

/adhd "generate a secure password policy"

Validate the LLM Wrapper Directly

Test the src/llm.ts module independently to ensure generation and critique functions work:

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 – Core orchestration of divergent frames and critic pass; depends on src/llm.ts for LLM calls
• src/llm.ts – Abstraction layer for language model interactions (generation and critique)
• src/frames.ts – Defines the 15 cognitive frames used for divergent ideation
• src/cli.ts – Entry point for the adhd command-line tool; forwards arguments to the engine
• src/index.ts – Public API surface exported by the adhd-agent npm package
• src/render.ts – Formats engine output for CLI display and programmatic consumption
• skills/adhd/SKILL.md – Agent-skill manifest used by Claude-style agents to load the ADHD capability
• tests/llm.test.ts – Minimal test suite validating LLM wrapper behavior and JSON responses
• package.json & 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 and src/index.ts depend on compiled JavaScript
• Verify the engine integration by running npx adhd with a sample prompt to ensure src/engine.ts correctly coordinates with 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 validates that src/llm.ts returns JSON objects with the expected shape that src/engine.ts and 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 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, then run npm install to eliminate dependency conflicts. Check 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. If errors persist, review the imports in src/engine.ts to verify they correctly reference updated exports from src/llm.ts.

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