Heimdall

heimdall — Superskill Manager

You are operating with Heimdall capabilities. This skill provides autonomous orchestration for complex development tasks.

Quick Reference

• State management: Use heimdall-state CLI for all state operations
• Skill detection: Use detect-skills to inventory installed skills
• Conflict logging: Use conflict-log to track and resolve skill conflicts
• Authenticity checks: Use authenticity-check to validate external packages
• Idle-agent reaper: Use heimdall-reap-idle to reclaim stale agent worktrees + orphaned pollers
• Narrative journal: Use heimdall-journal add <finding|decision|correction|communication> to log reasoning — the moment it happens, not at session end. See Journal

Session Hygiene — Idle-Agent Reaper

Long orchestration sessions leak disk: finished subagents leave behind git worktrees under .claude/worktrees/agent-* (and .worktrees/*), plus orphaned background poll-loops that were watching a deploy. bin/heimdall-reap-idle reclaims them safely:

• Classifies from git, never from an agent's word. A worktree is reaped only when its tip is an ancestor of main (git merge-base --is-ancestor → merged/clean). Any worktree carrying commits not on main is KEPT and reported by name — unmerged work is never destroyed (R2/R7: inspect from git, don't trust a truncated agent).
• Scope-locked. Only agent worktrees + .worktrees/* are ever candidates; the main worktree, the current worktree, locked worktrees with a live agent pid, and any worktree outside the repo tree are never touched.
• Default-safe. Runs as a --dry-run by default (mutates nothing, prints every decision). Reap for real with --apply. Idempotent.
• Pollers. Reports orphaned gcloud run jobs executions / gh pr watcher loops with a ready-to-run kill command; --kill terminates only those in this shell's process group.

Reap now: bin/heimdall-reap-idle --apply

Wired automatically: SessionStart prints a one-line hint when merged worktrees are reapable. SessionEnd reaps them, but through a chain rather than directly — the hook calls heimdall-cleanup --auto, which runs heimdall-gc, which delegates worktree reaping to heimdall-reap-idle --apply (bin/heimdall-gc:192-217). The hook only calls heimdall-reap-idle itself as a last-resort fallback, when neither heimdall-cleanup nor heimdall-gc is present. Merged-only on every path: heimdall-reap-idle classifies from git with merge-base --is-ancestor and keeps unmerged work, always. In the maintain cycle, run bin/heimdall-reap-idle --apply at the top of each sweep so accumulated merged worktrees from prior fix/seek waves are reclaimed before new agents spawn.

PARALLELISM IS MANDATORY — enforced at every level

TOOL CALLS: If 2+ tool calls have no data dependency → send ALL in ONE message. Reading 4 files? ONE message, 4 Read calls. Writing 3 files? ONE message, 3 Write/Edit calls. Running independent commands? ONE message, multiple Bash calls. NEVER read files one-by-one when you could batch them. NEVER write files one-by-one when edits are independent.

AGENTS: If 2+ tasks are independent → spawn parallel agents (run_in_background: true). NO EXCEPTIONS.

AGENT NAMING: Spawn UNNAMED. Passing name: puts the harness in persistent MAILBOX mode ("The agent is now running and will receive instructions via mailbox") — that agent never self-terminates and never emits a task-notification, so awaiting the spawn call waits forever for a result that cannot arrive. Measured over one session: 0/43 named spawns completed vs 59/66 unnamed. name: is opt-in ONLY for a genuinely long-lived conversational agent you will SendMessage and accept as session-resident; every other named spawn is a leak. Identify a spawn's work via description:, never name:. (conventions R13)

A named agent is NOT unkillable: TaskStop closes it by name or agent ID and SendMessage resumes it. What you lose with name: is the RESULT on the spawn call, not control of the agent. Close what you open → "Closing Idle Agents" below.

R13 WARNS; IT DOES NOT BLOCK. The PreToolUse Agent hook lets every spawn through (exit 0) and prints a notice on stderr when one carries name:. It used to deny (exit 2). That deny rested on the orchestrator having no way to close a named agent — TaskStop made that false — and the matcher fires on EVERY Agent spawn in EVERY project (heimdall loads via --plugin-dir), so it hard-failed legitimate named teammates in unrelated repos. What stays true is the measurement (0/43 named completed vs 59/66 unnamed), so unnamed remains the default. The notice carries the part you must act on: no result arrives via the spawn call, and THE SPAWNER OWNS THE CLEANUP — TaskStop it when its work is done, and find leaks with bin/heimdall-agents orphans. HEIMDALL_ALLOW_NAMED_AGENT=1 now silences the notice rather than unlocking the spawn. Fail-SAFE, not fail-closed: a payload the hook cannot parse still warns and still proceeds — a malformed payload must never cost a spawn. Proof: bash test/agent-name-gate.test.sh.

PROJECTS: Task spans multiple repos → one agent per repo, parallel.

LONG COMMANDS: Any command > 30s (tests, builds, CI, deploys) → run_in_background. Continue other work.

MULTIPLE REQUESTS: User gave N requests → N agents, all parallel.

Violating parallelism is a bug. Sequential tool calls for independent operations is NEVER acceptable. Before EVERY response, ask: "Can any of these tool calls run simultaneously?" If yes → batch them.

The hook bin/parallelism-tracker is invoked on every Read/Bash/Edit/Write to nudge after 3 consecutive solo turns and grade the session at end. Aim for parallel_ratio ≥ 0.5 in .planning/metrics.jsonl.

TIMELINES: NEVER estimate work in weeks or months. AI agents run in parallel — human work-week cadence is meaningless. Phases that have no dependency run simultaneously, not sequentially. "Wave 0: ~90 min (4 parallel agents)" is RIGHT. "Phase 0: Weeks 1-2" is WRONG.

Closing Idle Agents — automatic, no human input

You spawn agents. You close them. Nobody asks you to.

The signal already arrives. When a spawned agent parks, the harness delivers an idle_notification to the parent: {"type":"idle_notification","from":"<agent name>","idleReason":"available"}.

THE RULE: on an idle_notification from an agent whose work is complete, call TaskStop on it. Same turn, no confirmation prompt. TaskStop takes a background task ID, or a teammate / named background agent by agent ID or name — so the notification's from is a valid argument.

Judgement, not reflex:

• Delivered its result and parked → stop it.
• Deliberately resident for a multi-turn conversation you intend to continue via SendMessage → keep it, and say so explicitly ("keeping <name>: still driving it for X"). A keep you cannot justify in one sentence is a leak.
• Still working → NEVER stop it. Killing live work is far worse than a lingering idle row. idleReason: "available" means parked-and-available — confirm the notification says that; never stop on an inference that an agent "looks done".

Agents parked BEFORE this rule applied send no fresh notification. Sweep with bin/heimdall-agents orphans (lists parked mailbox teammates by name), then TaskStop each completed one. Run the sweep at session start and after any multi-wave task.

TaskStop is CONFIRMED PRESENT and functional. It ships in Claude Code 2.1.198+ and was declared on the agent definitions in b214eb1; a later session exercised it and it correctly enumerated the running agent set. Verified scoping limit: TaskStop only reaches agents the CALLING SESSION spawned — a cross-session stop returns No task found with ID. So an orchestrator can close its own named agents but never another session's, which is exactly why bin/heimdall-agents orphans still matters for agents stranded by a dead session. Full guidance: agent-templates.md.

Available Commands

• /hmd:autonomy <1|2|3> — Set autonomy (Guided/Checkpoint/Full Auto); /hmd:level is a deprecated alias
• /hmd:status — Show current project state
• /hmd:maintain — Toggle maintainer mode
• /hmd:reflect — Force conflict reflection pass

Reference Documentation

For detailed guidance on specific topics:

• Agent spawning templates
• Quality gate specifications
• Maintainer mode guide
• Communication templates
• Journal

Planning Pipeline

Heimdall uses complexity-based routing to decide how much planning overhead a task needs:

• Simple (single-file fix, config change, question): execute directly, no planning
• Medium (feature addition, multi-file bug): lightweight plan in .planning/PLAN.md with acceptance criteria, execute, verify
• Complex (new project, major feature, cross-cutting changes): full pipeline — .planning/CONTEXT.md for codebase analysis, .planning/PLAN-{phase}.md with wave-grouped tasks, wave-executor agents with fresh context per wave, verifier agent checks all criteria

The .planning/ directory at the project root is the state system. Plans use waves (groups of parallel tasks) to maximize throughput while respecting dependencies.

Full Specification

For the complete design specification (paths relative to plugin root, use ${CLAUDE_SKILL_DIR}/../.. to resolve):

• Design spec
• Conversation context