How to Add Custom Cognitive Frames to the ADHD Framework: A Complete Guide

To add custom cognitive frames to the ADHD framework, create a Frame object with a unique id, descriptive label, system prompt text, and relevant tags, then append it to the exported FRAMES array in src/frames.ts.

The ADHD framework, available in the UditAkhourii/adhd repository, drives cognitive diversification through frames—small prompt snippets that re-ask problems from different perspectives. Learning how to add custom cognitive frames to the ADHD framework allows you to inject domain-specific thinking modes directly into the generation pipeline controlled by src/engine.ts.

Understanding the Frame Architecture

According to the UditAkhourii/adhd source code, the Frame type is defined in src/frames.ts (lines 5-22) with four required properties: id (unique string identifier), label (human-readable name), prompt (the system-prompt fragment injected during generation), and tags (array of strings influencing selection weight).

The framework exports a constant FRAMES array containing all available frame objects. During execution, the selectFrames() function in src/engine.ts randomly samples from this array, biasing toward entries tagged with "code" when code mode is enabled. Because frames load statically at import time, no additional configuration or runtime registration is required.

Step-by-Step: Adding a Custom Cognitive Frame

Step 1: Define the Frame Object

Create a new Frame object that encapsulates your desired cognitive perspective. Ensure the id is unique across the existing FRAMES array.

// Frame definition example
const quantumFrame = {
  id: "quantum-physicist",
  label: "Quantum Physicist",
  prompt: "You think like a quantum physicist: consider superposition, entanglement, and probabilistic outcomes. Re‑ask the problem as if the solution could exist in multiple states simultaneously.",
  tags: ["code", "wild"]
};

Step 2: Append to the FRAMES Array

Register your frame by adding the object to the exported FRAMES array in src/frames.ts. This makes it available to the selector immediately upon the next execution.

// src/frames.ts
export const FRAMES: Frame[] = [
  // …existing frames…

  {
    id: "quantum-physicist",
    label: "Quantum Physicist",
    prompt: "You think like a quantum physicist: consider superposition, entanglement, and probabilistic outcomes. Re‑ask the problem as if the solution could exist in multiple states simultaneously.",
    tags: ["code", "wild"]
  },
];

Step 3: Verify Frame Selection

Test your implementation by calling selectFrames() from src/engine.ts. The function will now consider your custom entry when shuffling the pool.

import { selectFrames } from "./engine";

// Request 3 frames; codeMode=true prefers "code" tags
const chosen = selectFrames(3, true);
console.log(chosen.map(f => f.label));
/* Example output:
   [
     "Hardware engineer",
     "Quantum Physicist",
     "Inversion"
   ]
*/

Frame Tagging and Selection Logic

Tags control how selectFrames() weights frames during random sampling. The implementation in src/engine.ts recognizes specific strings that alter selection probability:

• "code": Biased toward when the second parameter of selectFrames() is true
• "wild": Guarantees diversity by marking the frame as a wildcard entry
• "design" and "general": Alternative categories for specific contexts

Include multiple tags to increase selection likelihood across different modes. The engine specifically checks for the "code" tag to determine weighting during code mode operations.

Running Custom Frames via CLI

After modifying src/frames.ts, the ADHD CLI automatically recognizes new frames. Use the --frames flag to specify how many perspectives the engine should sample.

# Request 4 cognitive frames; custom entries may appear

npx adhd run --frames 4

The CLI in src/cli.ts internally calls selectFrames(), passing the count and mode preferences to the engine.

Summary

• Frame objects require id, label, prompt, and tags properties as defined in src/frames.ts.
• Registration occurs by appending to the exported FRAMES array; no runtime registration is necessary due to static imports.
• Selection logic resides in src/engine.ts within the selectFrames() function, which respects tag weighting for code mode and wildcards.
• Immediate availability means changes to src/frames.ts are reflected in the next CLI execution or library import.

Frequently Asked Questions

Do I need to rebuild the project after adding a custom frame?

No. Because src/frames.ts exports FRAMES as a statically imported constant, the framework loads frames at import time. Simply save the modified TypeScript file and the next execution of the CLI or library import will automatically include your new frame in the selection pool.

What happens if two frames share the same id?

While the source code does not enforce uniqueness constraints at runtime, duplicate id values may cause ambiguity in logging and potential conflicts if the framework implements future caching mechanisms. Always ensure your frame's id is unique among entries in the FRAMES array.

How do tags affect the probability of frame selection?

The selectFrames() function in src/engine.ts uses tags to weight random selection. When the second parameter is true (code mode), the selector biases toward frames tagged with "code". The "wild" tag guarantees inclusion for diversity purposes. Multiple tags increase a frame's eligibility across different runtime configurations.

Can I create frames without any tags?

Yes, frames can include an empty tags array, but they will receive no selection bias during the random sampling process. Untagged frames compete equally with all other entries, making them less likely to appear in code-specific contexts where the engine actively prefers tagged alternatives.

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