How the Frontmatter Stripper Ensures Consistent Always-On Injection Across Runtimes

The frontmatter stripper in ayghri/i-have-adhd guarantees identical rule-set injection across Node.js, POSIX shell, and PowerShell by enforcing strict YAML delimiter detection and relative path resolution in three runtime-specific hook scripts.

The i-have-adhd repository delivers an "always-on" mode for Claude Code by injecting a standardized rule set at every session start. To ensure this behavior remains consistent regardless of whether the agent runs on Node, Bash, or PowerShell, the project implements a frontmatter stripper that preprocesses SKILL.md identically across all three runtimes. This architecture eliminates environment-specific parsing differences that could otherwise corrupt the injected instructions.

Runtime-Specific Frontmatter Stripping Logic

Each hook script in hooks/ performs the same logical operation: detect a complete YAML frontmatter block (opening --- and closing ---) at the start of skills/i-have-adhd/SKILL.md, strip it, and output the clean body. The implementations differ only in syntax, not semantics.

Node.js Regex Implementation (hooks/always-on.mjs)

In hooks/always-on.mjs, the stripper uses a precise regular expression anchored to the file start. The pattern ^---[^\S\r\n]*\r?\n[\s\S]*?\r?\n---[^\S\r\n]*(?:\r?\n|$) removes the entire block and trims trailing newlines.

// Conceptual implementation based on the regex pattern used
const frontmatterPattern = /^---[^\S\r\n]*\r?\n[\s\S]*?\r?\n---[^\S\r\n]*(?:\r?\n|$)/;
const body = skillContent.replace(frontmatterPattern, '').trim();

The regex is anchored to the very beginning of the file (^---), ensuring only a true YAML frontmatter is stripped. It handles both Unix (\n) and Windows (\r\n) line endings explicitly.

POSIX Shell AWK Implementation (hooks/always-on.sh)

The shell version executes an awk script that mirrors the Node approach through state tracking. It detects an opening --- on the first line, then tracks whether a closing --- appears before outputting content.

# Logic as implemented in hooks/always-on.sh

awk 'NR==1 && /^---$/ { in_fm=1; next }
     in_fm && /^---$/ { closed=1; in_fm=0; next }
     in_fm { next }
     closed || !in_fm { print }' "$skill_path"

The two-pass logic (in_fm / closed) guarantees that an unterminated fence is left untouched, matching the Node behavior exactly.

PowerShell Line-Scanning Implementation (hooks/always-on.ps1)

For Windows environments, hooks/always-on.ps1 reads all lines and performs explicit forward scanning:

# Conceptual implementation matching hooks/always-on.ps1 behavior

$lines = Get-Content $skillPath
if ($lines[0] -eq "---") {
    for ($i=1; $i -lt $lines.Length; $i++) {
        if ($lines[$i] -eq "---") {
            $body = $lines[($i+1)..($lines.Length-1)] -join "`n"
            break
        }
    }
} else {
    $body = $lines -join "`n"
}

By explicitly requiring a closing delimiter, PowerShell behaves identically to the other runtimes. If no closing --- is found, the whole file is preserved.

Path Resolution and Injection Guarantees

All three scripts resolve SKILL.md relative to the script’s own location, never trusting environment variables like $PWD. This prevents path-resolution differences between runtimes from causing divergent behavior:

• Node: Uses fileURLToPath and dirname from import.meta.url
• POSIX: Uses dirname "$(realpath "$0")" or equivalent to set script_dir
• PowerShell: Uses $PSScriptRoot to locate scriptDir

Because the stripping logic is the only difference between the runtimes, the injected rule-set (body) is guaranteed to be identical regardless of whether the session is started via Node, sh, or PowerShell.

Graceful Fallback Behavior

The scripts share a unified fallback strategy defined in hooks/hooks.json. If the always-on flag (~/.claude/.i-have-adhd-always) is missing, if SKILL.md is unreadable, or if any step fails, the script exits with status 0. This ensures the frontmatter stripper never blocks session startup, providing consistent reliability across all environments.

Summary

• The frontmatter stripper acts as a runtime-agnostic preprocessor for SKILL.md in the ayghri/i-have-adhd project.
• Three implementations (Node.js regex, POSIX awk, PowerShell line-scan) share identical semantics requiring a closing --- delimiter to strip content.
• All scripts use relative path resolution to locate skills/i-have-adhd/SKILL.md, preventing environment-specific path errors.
• The consistent stripping logic guarantees the injected rule set is byte-for-byte identical across Node, shell, and PowerShell runtimes.
• Graceful fallback (exit code 0 on missing files or errors) ensures the always-on mode never breaks the session startup flow.

Frequently Asked Questions

What is the purpose of stripping frontmatter in the i-have-adhd hooks?

The SKILL.md file contains YAML frontmatter metadata that must be removed before injecting the rules into Claude's system prompt. The frontmatter stripper ensures only the actual instruction content reaches the agent, preventing malformed YAML from corrupting the context window or wasting tokens on metadata.

How does the frontmatter stripper handle incomplete or malformed YAML blocks?

All three runtime implementations require a closing --- delimiter to strip content. If the opening --- on line 1 lacks a matching closer, the scripts preserve the entire file content, ensuring no data loss from malformed frontmatter. This behavior is consistent across the Node.js regex, POSIX awk, and PowerShell implementations.

Why are there three different implementations instead of a single cross-platform script?

Claude Code hooks execute within the agent's native runtime environment. By providing hooks/always-on.mjs for Node, hooks/always-on.sh for POSIX systems, and hooks/always-on.ps1 for Windows, the repository ensures the frontmatter stripper runs without external dependencies in every supported environment. Each script is invoked according to the runtime detected by hooks/hooks.json.

Where does the always-on flag need to be located to activate the frontmatter stripper?

The scripts check for the existence of ~/.claude/.i-have-adhd-always (the always-on flag file). When present, the hooks execute the frontmatter stripper and inject the rules, printing the banner ADHD MODE ACTIVE (always-on)...; when absent, they exit silently with status code 0, allowing the session to start without the rule injection.

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