# How the i-have-adhd Project Ensures Security: Architecture and Implementation

> Discover how the i-have-adhd project secures its architecture and implementation. Learn about least-privilege workflows, isolated secret management, sandboxed plugins, and declarative skill definitions.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: architecture
- Published: 2026-07-30

---

**The i-have-adhd repository implements defense-in-depth security through least-privilege GitHub Actions workflows, isolated secret management via GitHub Secrets, sandboxed plugin verification, and declarative skill definitions that contain no executable code.**

The i-have-adhd project is a lightweight Claude Code skill plugin hosted at `ayghri/i-have-adhd`. According to the source code, the project mitigates common security risks such as credential leakage, arbitrary code execution, and supply-chain attacks through a multi-layered protective architecture that emphasizes minimal permissions and static configuration.

## GitHub Actions Security Model

The project’s continuous integration pipeline adheres to the principle of least privilege, ensuring workflows operate with only the essential permissions required for their specific tasks.

### Minimal Workflow Permissions

In [`.github/workflows/claude.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/claude.yml), the workflow explicitly declares restricted permissions rather than accepting default broad access. The configuration grants only `contents: read`, `pull-requests: read`, `issues: read`, `id-token: write`, and `actions: read` scopes. This constraint reduces the attack surface significantly—if a workflow were compromised, the attacker would gain limited access to repository resources.

### Secure Secret Management

Sensitive OAuth tokens required for Claude Code authentication are never committed to the repository. Instead, the project stores the `CLAUDE_CODE_OAUTH_TOKEN` value as an encrypted GitHub Secret and injects it at runtime using the `${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}` syntax:

```yaml

# .github/workflows/claude.yml

- name: Run Claude Code
  uses: anthropics/claude-code-action@v1
  with:
    claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

```

This approach ensures that credential values remain outside the git history and are only accessible to authorized workflow runs.

## Plugin Integrity Verification

Before any code reaches users, the project validates plugin integrity through isolated testing environments that prevent contaminated or malicious code from propagating.

### Sandboxed Load Testing

The [`.github/workflows/plugin-load-check.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/plugin-load-check.yml) workflow implements runtime verification by installing the plugin in a clean, temporary sandbox. The job creates an isolated `CLAUDE_CONFIG_DIR` within the runner’s temporary directory, installs the plugin from the current checkout, and validates that it reaches an "enabled" state:

```yaml

# .github/workflows/plugin-load-check.yml

- name: Install the plugin from this checkout into a scratch config
  run: |
    export CLAUDE_CONFIG_DIR="$RUNNER_TEMP/claude-scratch"
    mkdir -p "$CLAUDE_CONFIG_DIR"
    claude plugin marketplace add "$GITHUB_WORKSPACE"
    claude plugin install i-have-adhd@i-have-adhd
    claude plugin list | tee plugin-list.txt
    grep -q "✔ enabled" plugin-list.txt || { echo "::error::plugin failed to load"; exit 1; }

```

If the plugin fails to load or exhibits unexpected behavior, the workflow exits with an error code, blocking the release process and preventing malformed plugins from reaching the marketplace.

## Declarative Architecture

The project eliminates code injection vectors by ensuring that skill definitions contain only static metadata rather than executable logic.

### Non-Executable Skill Definitions

The [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) file contains purely declarative metadata describing the skill’s capabilities. Unlike traditional plugins that might execute arbitrary code during initialization, this file defines behavior through structured documentation only. This design choice removes the possibility of accidental code execution or injection within the skill definition itself.

### Immutable Plugin Manifest

The [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json) file describes the plugin’s public interface and capabilities without exposing mutable configuration options or runtime parameters. By maintaining a read-only schema that downstream tools cannot modify at runtime, the project ensures consistent behavior across all installations and prevents runtime manipulation of plugin settings.

### Absence of Hard-Coded Credentials

A review of the repository confirms the absence of `.env` files, configuration scripts containing API keys, or other hard-coded credentials. All required runtime secrets must be supplied through the CI environment, ensuring that sensitive data never appears in source control.

## Summary

The i-have-adhd project security model relies on four key protective measures:

- **Least-privilege CI execution**: Workflows run with minimal GitHub token permissions to limit potential damage from compromise.
- **Secret isolation**: OAuth tokens and sensitive values reside exclusively in GitHub Secrets, referenced only through protected context variables.
- **Runtime sandboxing**: The [`plugin-load-check.yml`](https://github.com/ayghri/i-have-adhd/blob/main/plugin-load-check.yml) workflow validates plugin integrity in an isolated environment before publication.
- **Static skill definitions**: [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) and [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json) contain declarative metadata without executable code, preventing injection attacks.

## Frequently Asked Questions

### How does i-have-adhd handle sensitive credentials?

The project stores all sensitive tokens, including the `CLAUDE_CODE_OAUTH_TOKEN`, as encrypted GitHub Secrets. These values are injected into workflows at runtime using the `${{ secrets.VARIABLE_NAME }}` syntax, ensuring credentials never appear in source code or git history.

### What prevents malicious code execution in the i-have-adhd plugin?

The [`plugin-load-check.yml`](https://github.com/ayghri/i-have-adhd/blob/main/plugin-load-check.yml) CI job installs the plugin in a sandboxed environment with a temporary `CLAUDE_CONFIG_DIR` and verifies it reaches an "enabled" state before allowing publication. Additionally, the [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) file contains only declarative metadata with no executable code, eliminating script injection vectors.

### Why does the project use sandboxed plugin loading?

Sandboxed loading creates an isolated test environment that prevents contaminated dependencies or malicious code from affecting the host system or end users. By verifying the plugin in a clean directory with explicit failure conditions, the project catches loading errors before they reach production.

### Are there hard-coded API keys in the repository?

No. The repository contains no `.env` files, hard-coded API keys, or embedded credentials. All authentication requirements must be satisfied through environment variables or GitHub Secrets supplied during CI execution, following security best practices for open-source projects.