How to Report a Bug in the UditAkhourii/adhd Repository

To report a bug in the adhd repository, file a new GitHub Issue using the template at .github/ISSUE_TEMPLATE/bug_report.md, specifying reproduction steps, environment details (Node ≥ 18, OS, LLM model), and which architectural layer—Engine, CLI, or Index—is affected.

The adhd project is an open-source agent framework that uses a two-phase divergence/focus loop to generate and refine ideas using LLMs. Effective bug reports help maintainers quickly route issues to the correct module—whether the core logic in src/engine.ts, the command-line interface in src/cli.ts, or the public API surface in src/index.ts.

Using the GitHub Issue Template

The repository provides a structured bug report form to ensure consistent information.

Accessing the Template

Navigate to the repository's Issues tab and click "New issue", then select "Bug report". This pre-populates the editor with the template from .github/ISSUE_TEMPLATE/bug_report.md. Alternatively, open the creation page directly:

open "https://github.com/UditAkhouri/adhd/issues/new?template=bug_report.md"

Required Information Sections

Fill out every section in the template to minimize back-and-forth:

• Describe the bug – A one-sentence summary of the symptom.
• To Reproduce – Numbered steps starting with installation (e.g., npm install adhd-agent && npx adhd "example prompt").
• Expected behavior – What you anticipated the system should do.
• Actual behavior – The error message, stack trace, or incorrect output observed.
• Environment – OS version, Node.js version (the README indicates ≥ 18), and the specific LLM model if applicable.
• Screenshots / Logs – Terminal output or UI captures illustrating the failure.

Identifying the Affected Code Layer

The codebase is architecturally split into three layers. Indicating which layer you exercised helps maintainers run the correct unit tests (such as those in tests/llm.test.ts) and target the right file.

Engine (src/engine.ts) – Core divergent-ideation logic. This handles the frame-spawning loop, LLM call isolation, scoring aggregation, and clustering. Report bugs here if the agent produces inconsistent scores or fails to converge.

CLI (src/cli.ts) – The adhd command-line executable. Issues include argument parsing errors, flag validation failures, or terminal UI glitches. For example, a crash when passing --frames -1 originates in this layer.

Index (src/index.ts) – The public library API exposing run and renderText. Report here if importing the package programmatically yields different results than the CLI.

Writing an Effective Reproduction Script

Include the minimal commands needed to trigger the fault. For a CLI-level bug, demonstrate the exact invocation:

# Install the specific version exhibiting the bug

npm install -g adhd-agent@2.3.1

# Trigger the hypothetical negative frames crash

adhd "design a cache invalidation strategy" --frames -1

Paste this block under the To Reproduce section. If the bug involves the library API, provide a minimal Node.js script instead:

import { run } from 'adhd-agent';

// Minimal reproduction for engine layer bug
await run({
  prompt: "optimize a database query",
  framesPerRun: -1  // Invalid value causing RangeError
});

Submitting via the GitHub API (Optional)

For automated tooling or bulk issue creation, use the GitHub REST API. This reproduces the web workflow programmatically:

curl -X POST \
  -H "Authorization: token YOUR_GITHUB_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/UditAkhouri/adhd/issues \
  -d '{
    "title": "CLI crashes with negative --frames value",
    "body": "### Describe the bug\nThe CLI aborts with an uncaught exception.\n\n### To Reproduce\n```bash\nadhd \"test\" --frames -1\n```\n\n### Expected behavior\nShould validate input and return a helpful error.\n\n### Actual behavior\nThrows `RangeError: framesPerRun must be > 0`.\n\n### Environment\n- OS: macOS 13.6\n- Node: 20.12.0\n- adhd-agent: 2.3.1\n",

    "labels": ["bug","cli"]
  }'

Replace YOUR_GITHUB_TOKEN with a personal access token possessing the repo scope. Never commit tokens to the repository.

Summary

• The bug report template at .github/ISSUE_TEMPLATE/bug_report.md enforces a consistent structure for faster triage.
• Specify whether the bug occurs in the Engine (src/engine.ts), CLI (src/cli.ts), or Index (src/index.ts) layer to direct maintainers to the relevant logic.
• Always include environment details: Node.js version (≥ 18 required), operating system, and LLM model configuration.
• Provide minimal reproduction commands or scripts that maintainers can run immediately.
• Optional labels like cli, library, documentation, or performance help categorize the issue backlog.

Frequently Asked Questions

Where is the bug report template located?

The template lives at .github/ISSUE_TEMPLATE/bug_report.md in the repository root. When you click "New issue" and select "Bug report", GitHub automatically loads this file into the editor with pre-populated markdown headings.

What information should I include when reporting a CLI crash?

Include the exact command string (e.g., adhd "prompt" --frames 5), the Node.js version (verify it meets the ≥ 18 requirement shown in the README badge), the operating system, and the complete stack trace or error message printed to stderr. If the crash involves argument parsing, note that logic resides in src/cli.ts.

How do I know if my bug is in the Engine or CLI layer?

If the program launches but produces incorrect reasoning, hangs during the "divergence" phase, or returns malformed scores, the issue likely resides in the Engine (src/engine.ts). If the program fails to start, throws argument-validation errors, or exhibits terminal formatting issues, the CLI layer (src/cli.ts) is the culprit.

Can I report security vulnerabilities through public GitHub Issues?

For sensitive security bugs—such as prompt injection vulnerabilities discovered in the engine logic—avoid public issues. Instead, check the repository's security policy or contact maintainers privately. Public issues are appropriate for functional bugs, crashes, and performance regressions only.

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