How to Create Custom Cognitive Frames for ADHD: A Complete Guide

You create custom cognitive frames for ADHD by defining a Frame object with a unique id, label, prompt, and tags, then appending it to the FRAMES array in src/frames.ts.

The ADHD framework generates cognitive diversification by injecting perspective-shifting prompts—called frames—into AI generation passes. These frames are statically defined TypeScript objects that reframe problems through different professional or philosophical lenses. Because the frame registry loads at import time, adding custom perspectives requires only a quick edit to the source code, with no runtime configuration or service restarts needed.

Understanding the Frame Architecture

The ADHD framework maintains its frame collection in src/frames.ts, where the Frame interface and the exported FRAMES constant reside. According to the source code, a Frame object requires four properties:

• id: A unique string identifier (e.g., "quantum-physicist")
• label: A human-readable name displayed in output
• prompt: The system-prompt fragment injected to shift perspective
• tags: An array of strings (e.g., "code", "design", "general", "wild") used by the selection algorithm

During execution, the selectFrames() function in src/engine.ts randomly selects a subset from the FRAMES array. When codeMode is enabled, the selector biases toward entries tagged with "code", while the "wild" tag guarantees diversity by ensuring the frame appears in randomized selections.

Step-by-Step Guide to Creating Custom Cognitive Frames

Define the Frame Object

Create a TypeScript object conforming to the Frame interface. The prompt field should contain specific instructions that re-ask the problem from your desired perspective.

Register the Frame

Append your object to the FRAMES array exported from src/frames.ts. Because this array is imported statically by the engine, the new frame becomes available immediately upon the next execution.

Configure Tags for Selection Behavior

Choose tags strategically to control when your frame appears:

• "code": Prioritized when running with codeMode: true
• "design": Targets creative and UX-oriented generation passes
• "general": Suitable for broad, non-technical reasoning
• "wild": Forces inclusion in random selections to guarantee cognitive diversity

Practical Code Examples

Adding a Domain-Specific Frame

The following example adds a "Quantum Physicist" frame to src/frames.ts. This frame instructs the AI to consider superposition and probabilistic outcomes:

// src/frames.ts – append to the FRAMES array
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"],   // appears in code‑mode and guarantees diversity
  },
];

Programmatic Frame Selection

After modifying src/frames.ts, your custom frame automatically enters the selection pool. Use the selectFrames utility to test the integration:

import { selectFrames } from "./engine";

// Request 3 frames with codeMode enabled
const chosen = selectFrames(3, true);
console.log(chosen.map(f => f.label));
/* Example output:
   [
     "Hardware engineer",
     "Quantum Physicist",   // custom frame appears automatically
     "Inversion"
   ]
*/

Using Custom Frames via CLI

The command-line interface exposes frame selection through the --frames option. After saving your changes to src/frames.ts, the next CLI invocation immediately recognizes the new perspective:

# Request 4 cognitive frames; custom frames are eligible for selection

npx adhd run --frames 4

Key Implementation Details

The frame system relies on two critical source files:

• src/frames.ts: Defines the Frame type (lines 5–22) and the FRAMES constant (lines 16–22). This is the only file you modify when adding custom frames.
• src/engine.ts: Houses the selectFrames function that implements the random selection logic with tag-based weighting.

Because the framework uses static imports rather than dynamic registration, the FRAMES array is frozen at startup. This design eliminates runtime overhead but means you must edit the source file and save changes before new frames become active.

Summary

• Custom cognitive frames for ADHD are defined as TypeScript objects implementing the Frame interface in src/frames.ts.
• Each frame requires a unique id, descriptive label, perspective-shifting prompt, and strategic tags array.
• The selectFrames() function in src/engine.ts handles random selection with bias toward "code" tags when codeMode is enabled.
• No runtime registration is required; append to the FRAMES array and the next CLI or library execution automatically includes your custom perspective.

Frequently Asked Questions

What properties must a custom Frame object include?

A valid Frame object must include four properties: id (unique string identifier), label (display name), prompt (the system instruction injected into the generation context), and tags (array of category strings). These are defined in the Frame interface located in src/frames.ts at lines 5–22.

How does the engine decide which custom frames to use?

The selectFrames() function in src/engine.ts performs a randomized selection from the FRAMES array. If the codeMode parameter is true, the algorithm weights entries tagged with "code" more heavily during the shuffle. Tags like "wild" force inclusion to ensure cognitive diversity across generation passes.

Do I need to restart the CLI after adding a new frame?

No additional restart or runtime registration is required. Because src/frames.ts exports the FRAMES constant statically, simply saving the file with your new frame object makes it available to the next execution of the CLI or any script importing the library.

Can I create frames specifically for software engineering tasks?

Yes. Tag your custom frame with "code" to ensure it receives priority when codeMode is enabled. You can combine multiple tags—for example, ["code", "wild"]—to indicate the frame applies to technical problems while also guaranteeing it appears regularly in randomized selections for maximum cognitive diversification.

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