heimdall: Instructions file for Claude Code

Project Conventions (managed by heimdall)

Parallelism (MANDATORY)

• 2+ independent tool calls → send ALL in ONE message (batch Read, Write, Edit, Bash)
• 2+ independent tasks → spawn ALL agents in ONE message with run_in_background: true
• Task touches 2+ independent files → one agent per file, ALL spawned together
• NEVER: spawn agent → wait → spawn another agent for independent work
• NEVER: read file → read next file → read next file (batch all reads in one message)
• NEVER: pass name: to Agent unless you will SendMessage it — name: → mailbox-resident agent, never self-terminates, never returns a result (measured 0/43 named completed vs 59/66 unnamed)
• Identify a spawn's work via description:, never name: (R13)
• The PreToolUse Agent hook WARNS on name: (stderr, exit 0) — it does not block. Name one → you own its lifecycle: collect via SendMessage, close with TaskStop, sweep leaks with bin/heimdall-agents orphans

Rules

• All code, configs, docs go in this project directory
• Planning state lives in .planning/ (human-readable, git-committed)
• Each completed task = one atomic git commit
• Acceptance criteria must be runnable (grep, curl, test commands)

Commit attribution

Every commit produced through hmd carries:

Co-Authored-By: runhmd <[email protected]>

hmd is the constant identity — the model underneath varies (Claude today, something else tomorrow, a different tool on a teammate's machine) and none of that changes who gated the work. The trailer records the layer that held the line, not the one that typed. Rendered through the real runhmd GitHub machine account (id 318965969) rather than a plain-text address, so it links: see "GitHub account, not a plain-text address" below. The display name is runhmd, not hmd — only the email drives GitHub's account match, so the name is purely cosmetic, but matching it to the account's actual login means nobody reading history has to wonder why the visible name and the linked handle disagree.